@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -1,4 +1,4 @@
-import type { IScriptingRuntime, CaptureSpan, LuaGlobalEntry } from '../IScriptingRuntime';
+import type { IScriptingRuntime, CaptureSpan, LuaGlobalEntry, ScriptHandlerEntry, VariableEdit } from '../IScriptingRuntime';
 import type { ScriptingAPI } from '../ScriptingAPI';
 import type { ProfileVFS } from '../vfs/ProfileVFS';
 import { type MudletVariable } from '../../import/mudletVariables';
@@ -7,13 +7,6 @@ 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 readonly labelCbIds;
     private cmdLineActionCbId;
     private windowCmdLineActionCbIds;
@@ -21,6 +14,7 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private currentMatches;
     private currentCaptureSpans;
     private currentNamedSpans;
+    private nestedDispatchStates;
     private currentFullMatchSpan;
     /**
      * Move the capture positions recorded for the line being processed to
@@ -30,9 +24,18 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * `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.
+     *
+     * For a `replace` of `replaced` characters at `at`
+     * (TLuaInterpreter::adjustCaptureGroupsForReplace) the capture that was
+     * exactly the replaced text keeps its start and takes the replacement's
+     * length, one starting after `at` moves, and the rest — an enclosing group
+     * that shares the start among them — stay as they were.
      */
-    shiftCaptureSpans(at: number, delta: number): void;
-    private _denyCurrentSend;
+    shiftCaptureSpans(at: number, delta: number, replaced?: number): void;
+    /** One entry per sysDataSendRequest dispatch on the stack, innermost
+     *  last: whether a handler denied THAT command. A send a handler makes
+     *  dispatches its own, so a deny is never spent by the wrong command. */
+    private _sendRequestDenies;
     /** 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;
@@ -75,7 +78,9 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private tts;
     private globalEvents;
     private flushPendingSqlSnapshots;
-    private toLuaValue;
+    private stopAnsiPaletteSync;
+    private closeSqlConnections;
+    private yajl;
     private constructor();
     static create(api: ScriptingAPI, vfs?: ProfileVFS | null, proxyUrlGetter?: () => string | undefined): Promise<LuaRuntime>;
     private setup;
@@ -102,6 +107,12 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * 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.
      *
+     * It counts its arguments rather than naming one: a named parameter turns
+     * `tostring()` into `tostring(nil)` and answers "nil", where stock Lua
+     * raises "bad argument #1 to 'tostring' (value expected)" — with no
+     * position, as luaL_argerror gives a C function — and a buggy
+     * `tostring(select(2, ...))` has to fail here as it does on desktop.
+     *
      * Installed after every `global.set` above and before Bridge.lua, so no
      * bundled or user chunk can capture the unsafe version as an upvalue.
      */
@@ -109,57 +120,46 @@ export declare class LuaRuntime implements IScriptingRuntime {
     private installMudletLuaOverrides;
     private installFastColorEcho;
     private setupAnsiColorTable;
+    private static readonly ANSI16_NAMES;
     /**
-     * True when a script-created (temp) alias/trigger with this id is live and of
-     * the given type. Backs exists(id, "alias"/"trigger") for temp items, which
-     * 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.
+     * TLuaInterpreter::updateAnsi16ColorsInTable: write the sixteen ANSI colours
+     * in force into `color_table` under all three of their names (`ansi_001`,
+     * `ansi_red`, `ansiRed`), each a fresh `{r, g, b}`. Unconditional — the
+     * entries describe the palette, so they replace whatever was there.
      *
-     * 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 — 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;
+     * Raw table writes on the main state rather than a Lua chunk: this runs
+     * whenever the palette moves, which can be in the middle of a script (a
+     * `feedTriggers` carrying `ESC]P`), and it must neither dispatch anything
+     * nor be able to fail half-way.
+     */
+    private updateAnsi16ColorsInTable;
     private setupBustedBridge;
     private setupSqlBridge;
     /**
-     * Fire sysPathChanged for any addFileWatch subscription whose path equals
-     * `changedPath` or is an ancestor directory of it. Mudlet's QFileSystemWatcher
-     * reports the *watched* path (not the inner file) for directory watches, so
-     * we do the same — handlers comparing `path == watchedPath` round-trip.
+     * Fire sysPathChanged for the addFileWatch subscriptions a set of VFS
+     * changes touches, by the rules desktop's QFileSystemWatcher (inotify)
+     * follows:
+     *
+     * - A watched *file* reports any change to it ('modify', 'attrib'), and
+     *   its removal — after which the watch is gone, as the watcher drops a
+     *   path whose inode was deleted or moved away: a file recreated under
+     *   the same name reports nothing, and removeFileWatch answers false.
+     * - A watched *directory* reports its direct children being created,
+     *   removed or renamed, or their attributes changing (lfs.touch) — not a
+     *   write into a child that already exists, and nothing from further
+     *   down the tree. Removing the directory itself reports and drops it.
+     *
+     * The *watched* path is what is reported, not the child, so handlers
+     * comparing `path == watchedPath` round-trip. Each watch reports at most
+     * once per batch.
      */
     private notifyVfsPathChange;
     private setupVFS;
     load(code: string, name: string): void;
-    run(code: string, name: string): void;
+    syntaxError(code: string, chunkName: string): string | null;
+    /** `chunkName`, when given, is what Lua reports the code under — Mudlet's
+     *  "Timer: <name>" / "Key: <name>" — rather than "@name". */
+    run(code: string, name: string, chunkName?: string): void;
     /**
      * Restore saved Lua globals (a parsed Mudlet `<VariablePackage>` tree) into
      * `_G`. Call on profile load, after the bundle is up but before user scripts
@@ -177,14 +177,194 @@ export declare class LuaRuntime implements IScriptingRuntime {
     /** Enumerate `_G` (user globals as a nested tree, built-ins flagged) for the
      *  Variables view. See {@link LuaGlobalEntry}. */
     listGlobals(): LuaGlobalEntry[];
-    runWithMatches(code: string, name: string, matches: (string | undefined)[], multimatches?: (string | undefined)[][], namedGroups?: Record<string, string>, captureSpans?: CaptureSpan[], namedSpans?: Record<string, CaptureSpan>, fullMatchSpan?: CaptureSpan): void;
+    /**
+     * Apply one Variables-view edit to the live `_G`, returning `null` on
+     * success or the reason it was refused.
+     *
+     * Desktop edits variables through `LuaInterface`/`VarUnit` and re-runs the
+     * assignment as Lua (`dlgTriggerEditor::addVar`, :5211, and the
+     * `saveVar`/`deleteVar` paths); the same job here is one small chunk over
+     * the request, so the change is visible to running scripts immediately
+     * rather than only after the next profile save.
+     */
+    editVariable(request: VariableEdit): string | null;
+    withCaptures(matches: (string | undefined)[], captureSpans: CaptureSpan[] | undefined, namedSpans: Record<string, CaptureSpan> | undefined, fullMatchSpan: CaptureSpan | undefined, fn: () => void): void;
+    runWithMatches(code: string, name: string, matches: (string | undefined)[], multimatches?: (string | undefined)[][], namedGroups?: Record<string, string>, captureSpans?: CaptureSpan[], namedSpans?: Record<string, CaptureSpan>, fullMatchSpan?: CaptureSpan, 
+    /** Named captures per multimatches row, aligned with it. */
+    multiNamedGroups?: (Record<string, string> | undefined)[], 
+    /** See IScriptingRuntime.runWithMatches. */
+    chunkName?: string): void;
     private setMatches;
+    /** Nesting of {@link setMatches}' table builds — see the note there. */
+    private captureBuildDepth;
+    /** Mudlet's TLuaInterpreter::buildingCaptureTables: true while
+     *  `matches`/`multimatches` are being built, when only a __gc finaliser can
+     *  be running Lua — and an alias or trigger pass it starts is turned away. */
+    buildingCaptureTables(): boolean;
+    /** Whether {@link setMatches} handed the scripts anything for these
+     *  captures, which is when {@link clearCaptureGlobals} is owed after them. */
+    private static captured;
+    /** Registry key of the empty table `matches` holds between fires, reused
+     *  for as long as nothing has been put in it. See {@link clearCaptureGlobals}.
+     *  A named key rather than a luaL_ref: the table is replaced in place, and
+     *  writing to a numbered slot is only safe while nothing else has freed it. */
+    private static readonly EMPTY_MATCHES_KEY;
+    /**
+     * Put the between-fires globals back once a fire with captures is over,
+     * as TLuaInterpreter::clearCaptureGroups does after every trigger and alias
+     * that had any — even when its script raised. `matches` becomes an empty
+     * table and `multimatches` a new one, so a script that kept a reference to
+     * the tables its fire was handed keeps them to itself, and a later fire
+     * never finds another fire's captures in place.
+     *
+     * The empty `matches` is one table reused while it is still empty and has
+     * no metatable (Mudlet's pushUnusedTable): a table a script has filled or
+     * given a metatable is that script's, and a new one takes its place.
+     */
+    private clearCaptureGlobals;
+    private pushUnusedEmptyMatches;
+    /**
+     * Store the value on top of the stack as the global `name`, raw.
+     *
+     * This is how a dispatch hands the scripts it runs their own `command` and
+     * `line` (`matches` and `multimatches` go through {@link assignGlobal},
+     * as desktop's do), and it runs with the whole dispatch
+     * on the JS stack below it. `lua_setglobal` honours a metatable on the
+     * globals table, so a `__newindex` a package installed there runs from
+     * inside this call on the first write of a name that is absent — and a Lua
+     * error raised by one does not longjmp to the nearest pcall the way it does
+     * on desktop, it unwinds through wasmoon's C closure and takes the whole
+     * lua_State with it. Mudlet writes these raw for the milder version of the
+     * same reason (`set_lua_string`, upstream #10799), and intercepting them
+     * was never something a package could usefully do: the name is absent only
+     * until the first dispatch writes it.
+     */
+    private rawSetGlobal;
+    /**
+     * Store the value on top of the stack as the global `name` by assignment,
+     * popping it — how desktop's setMatches and clearCaptureGroups hand out
+     * `matches` and `multimatches` (lua_setglobal), so a `__newindex` on the
+     * globals table sees each write of a name it does not hold.
+     *
+     * The assignment runs in Bridge.lua's `mudlet.assignGlobal` under
+     * lua_pcall, never as a lua_setglobal from here: see {@link rawSetGlobal}
+     * for what a raising metamethod does to a write made from JS. A handler
+     * that raises is reported, and the value is then stored raw, so the
+     * scripts of the fire still get their captures.
+     */
+    private assignGlobal;
+    private static readonly ASSIGN_GLOBAL_KEY;
+    /**
+     * Park the dispatch state the calling script is holding, and answer the
+     * depth the matching {@link popNestedDispatchState} has to unwind to.
+     *
+     * `expandAlias()` runs a whole alias pass inside whatever script called it,
+     * and that pass claims the per-dispatch globals for the scripts IT runs:
+     * `command` before any pattern is tried, `matches`/`multimatches` on every
+     * fire. Nothing used to put the caller's back, so a script resumed holding
+     * the nested command and an emptied matches table — even `matches[1]`, the
+     * full match, was gone (Mudlet's TLuaInterpreter::pushNestedDispatchState,
+     * upstream #10799).
+     *
+     * The tables are parked by reference rather than rebuilt from the capture
+     * list: a script is free to write into the `matches` it was handed, and it
+     * has to get that same table back. Every read is raw, so a package's
+     * `__index` on the globals table can neither be run by the parking nor
+     * raise from inside it — `multimatches` really is absent from a fresh
+     * profile's globals, which is exactly when an `__index` would answer.
+     *
+     * The JS mirror of the same state (`currentMatches` and the capture spans
+     * `selectCaptureGroup` reads) needs nothing here: every dispatch entry
+     * point already saves and restores it around the script it runs.
+     *
+     * `command` is parked only for an alias script by default; feedTriggers
+     * never parks it (see the binding).
+     */
+    pushNestedDispatchState(parkCommand?: boolean): number;
+    /** Hand the caller at `depth` back the state {@link
+     *  pushNestedDispatchState} parked for it. Anything parked above that depth
+     *  belongs to a dispatch that never reached its own restore; it is stale,
+     *  and handing one back here would give this caller some other script's
+     *  captures and command, so it is discarded. */
+    popNestedDispatchState(depth: number): void;
+    private releaseNestedDispatchState;
+    /**
+     * While an alias pass runs, what `command` ends it holding unless a script
+     * changes it (the last command expanded), and the value the last restore of
+     * an alias script's own command put back. TLuaInterpreter::mPassCommand.
+     */
+    private passCommandRef;
+    private restoredCommandRef;
+    /** Whether the script running now is an alias's: expandAlias() hands
+     *  `command` back to that one only. TLuaInterpreter::mRunningAliasScript. */
+    private runningAliasScript;
+    /** Claimed by the next entry into Lua — see {@link asAliasScript}. */
+    private nextEntryIsAliasScript;
+    /** Run `fn`, whose entry into Lua is an alias's script — the role of
+     *  desktop's `ScriptCallerScope(*this, true)` around TAlias::execute.
+     *  Every other entry runs as a non-alias caller. */
+    asAliasScript<T>(fn: () => T): T;
+    /**
+     * Start an alias pass for `command` (AliasUnit::processDataStream →
+     * TLuaInterpreter::setExpandedCommand): `command` holds it, and whatever an
+     * enclosing pass kept for {@link settleCommandAfterAliasPass} is out of date.
+     */
+    setExpandedCommand(command: string): void;
+    /**
+     * End of an alias pass, at every depth. An alias script had its own
+     * `command` back while it ran, but what is read once the pass is over is the
+     * last command expanded — or whatever a script set it to, which survives.
+     * TLuaInterpreter::settleCommandAfterAliasPass.
+     */
+    settleCommandAfterAliasPass(): void;
     /** Push a 1-indexed Lua table of capture strings (`matches[1]` = whole match),
      *  optionally merging named captures as string keys (`matches.hp`). Same shape
      *  the old `oneIndexed()` + `global.set` produced, via raw stack ops. An
      *  unmatched optional group (`undefined`) is left unset → nil, as before. */
     private pushMatchesTable;
     private exec;
+    /**
+     * The chunk name every piece of Mudlet Web's own Lua is compiled under —
+     * Bridge.lua, the io/lfs/utf8/yajl/luasql/rex/lpeg shims, and the one-line
+     * entry chunks JS runs. Desktop implements all of that in C, so Lua reports
+     * it as `[C]` there; Bridge.lua's error/debug.getinfo/debug.traceback use
+     * this name to show it the same way (see the top of Bridge.lua).
+     */
+    static readonly INTERNAL_CHUNK = "=[C]";
+    /**
+     * The standard library as it stood when an internal chunk loaded, bound as
+     * locals of that chunk, so Mudlet Web's own Lua never looks these up in the
+     * globals table at call time. Desktop's API is C and reaches none of them
+     * through Lua globals, so a script's own global `select` (a "select target"
+     * helper), `type` or `unpack = nil` must leave `send`, `echo`,
+     * `tempTrigger` and the rest working (mudlet-web#374). The tables are bound
+     * too, which still follows a script that changes a function inside one, as
+     * desktop's Lua-side code does. Part of {@link INTERNAL_PROLOGUE}, so it
+     * stays on the chunk's first line.
+     */
+    private static readonly BUILTIN_LOCALS;
+    private static readonly TOSTRING_LOCAL;
+    /**
+     * Put in front of an internal chunk, on its first line so the chunk's line
+     * numbers don't move: `error` there is one of {@link C_ERROR_LUA}'s, so an
+     * error raised from that code is positioned the way the C it stands in for
+     * positions it.
+     *   - `mudlet`: Mudlet's own API raises with lua_error — no position at
+     *     all (`tempTimer: bad argument #1 ...`).
+     *   - `lual`: the C libraries (io, lfs, luautf8, lrexlib, lua-yajl,
+     *     LuaSQL, LPeg) raise with luaL_error / luaL_argerror — the position
+     *     of the script line that called them, none when C called them.
+     * A chunk-local rather than a replaced global `error`, because a script's
+     * `return error(msg)` tail-calls it: the stock C function keeps the
+     * caller's frame for its position, a Lua replacement would not.
+     */
+    private static readonly INTERNAL_PROLOGUE;
+    /** Run one of Mudlet Web's own bootstrap chunks on the main state, under
+     *  {@link INTERNAL_CHUNK}. */
+    private runInternalChunk;
+    /** {@link exec} for Mudlet Web's own Lua: compiled under
+     *  {@link INTERNAL_CHUNK}, so what it defines reads as C to a script. */
+    private execInternal;
     private static readonly LUA_GCCOUNT;
     private static readonly MEMORY_WARN_MB;
     private static readonly MEMORY_SAMPLE_EVERY;
@@ -206,6 +386,44 @@ export declare class LuaRuntime implements IScriptingRuntime {
      */
     private markFatal;
     private execInner;
+    private readonly runningThreads;
+    /** Make the globals table `from` runs with the main state's, and so the one
+     *  every thread made from now on starts with. */
+    private adoptGlobalsOf;
+    /** Hand `to` the main state's globals table. */
+    private giveGlobalsTo;
+    /** Before anything reads or writes the globals table from JS, or makes a
+     *  thread: whatever the running script switched to is the one. */
+    private syncGlobalsFromRunning;
+    /** Run `resume` with `t` as the running thread, then leave its globals
+     *  table in place — in the main state and in the thread it returns to. */
+    private resumeAsRunning;
+    /** Desktop runs every entry point on the main state, so a script must not
+     *  see the thread at `threadIndex` as a coroutine — Bridge.lua's
+     *  coroutine.running/yield consult this registry table. Absent until
+     *  Bridge.lua has run. */
+    private markEntryThread;
+    private static readonly ENTRY_THREADS_KEY;
+    /** Give the new entry thread at `threadIndex` the debug hook a script set
+     *  on the main state, if any. Desktop runs every entry on that one state,
+     *  so its hook carries over from callback to callback; Lua 5.1 keeps hooks
+     *  per thread, so each thread made here has to be handed it (Bridge.lua's
+     *  debug.sethook keeps the record). */
+    private inheritDebugHook;
+    /**
+     * Before wasmoon reads a failed thread's error, make it a string.
+     *
+     * `assertOk` renders a non-string error with its own `luaL_tolstring`,
+     * which calls `__tostring` unprotected: an error object whose `__tostring`
+     * raises is then a Lua panic, and the panic is C `exit()` — the module is
+     * gone for the session (mudlet-web#330). Desktop reports such an error and
+     * carries on, so the object is described here first, under a pcall, by
+     * Bridge.lua's `__mudlet_describe_error`. Strings, numbers and userdata
+     * (wasmoon's wrapped JS errors, whose message `assertOk` keeps) are left
+     * alone.
+     */
+    private stringifyThreadError;
+    private static readonly DESCRIBE_ERROR_KEY;
     private execOnThread;
     private runChunk;
     private runChunkOnThread;
@@ -216,10 +434,10 @@ export declare class LuaRuntime implements IScriptingRuntime {
     /**
      * A thread resume returned LUA_YIELD. If it is invokeFileDialog's yield
      * (sentinel first), read the request off the thread stack, anchor the
-     * thread, and open the picker — returns true. Any other yield reaching
-     * the handler boundary is a script bug (stock Lua 5.1 errors with
-     * "attempt to yield from outside a coroutine" there): report and abandon
-     * the thread — returns false.
+     * thread, and open the picker — returns true. No other yield should get
+     * here: Bridge.lua's coroutine.yield refuses to leave an entry thread, as
+     * desktop's main state does. Should one anyway, report and abandon the
+     * thread — returns false.
      *
      * First park: the thread still sits at `threadIndex` on the global stack
      * (the caller's finally pops it), so take a registry ref now. Re-park
@@ -229,13 +447,27 @@ export declare class LuaRuntime implements IScriptingRuntime {
     /** Continue a parked handler with the picked VFS path ('' = cancelled). */
     private resumeDialogThread;
     private dispatchCb;
+    /** Set by {@link runCallback}: whether the callback's first result was
+     *  `true` — the way an expiring temp trigger asks for another life. */
+    private cbReturnedTrue;
+    /** Whether the callback {@link dispatchCb} last ran returned true. */
+    private lastCbReturnedTrue;
     private dispatchCbWithArg;
+    /**
+     * Call the Lua function registered under `cbId` (Bridge.lua's
+     * `mudlet.cb` registry table) as the base function of a fresh entry
+     * thread. Desktop calls such a callback straight from C with lua_pcall, so
+     * nothing sits under it: its traceback ends at the callback, which shows as
+     * `in function <chunk:line>` — called from C, it has no name. Running it
+     * through a Lua dispatcher chunk instead left two frames of ours under it.
+     */
+    private runCallback;
     private unregisterCb;
     /**
      * Mudlet `T2DMap::initiateSpeedWalk` / `Host::startSpeedWalk` — the map's
      * double-click-to-walk gesture. Pathfinds `from` → `to` (unless the mapper
      * opted into `mudlet.custom_speedwalk`) and calls the mapper package's
-     * `doSpeedWalk`; see `__mudix_start_speedwalk` in Bridge.lua. Errors inside
+     * `doSpeedWalk`; see `__mudlet_start_speedwalk` in Bridge.lua. Errors inside
      * the mapper are reported, never thrown at the UI caller.
      */
     startSpeedWalk(from: number, to: number): void;
@@ -253,25 +485,55 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * distinct from nil's "not my pattern, use yours".
      */
     private installNativeUtf8Find;
-    private dispatchingEvent;
-    private readonly pendingEvents;
+    /**
+     * The Unicode tables behind luautf8's normalize_nfc / isnfc /
+     * grapheme_indices, read off the JS engine (String.prototype.normalize,
+     * Intl.Segmenter) rather than vendored. Both take and give the text armored
+     * (see byteArmor.ts) — valid UTF-8 may still hold a NUL, which the wasmoon
+     * string bridge would cut at. utf8.lua validates before calling, so the
+     * bytes always decode.
+     */
+    private installUtf8Natives;
     emitEvent(event: string, args: unknown[]): void;
     private dispatchEventNow;
     setGmcpValue(path: string, value: unknown): void;
     setMsdpValue(path: string, value: unknown): void;
+    /**
+     * Push a JSON-decoded protocol payload as yajl.to_value would decode it.
+     * False, with nothing pushed, when it nests deeper than lua_yajl accepts —
+     * Mudlet's json_to_value raises on such a payload and the table is left as
+     * it was, so the caller skips the update too.
+     */
+    private pushDecodedJson;
+    /** Records one channel-102 report in the Lua `channel102` global. Both
+     *  halves are bytes, so there is nothing to marshal — Mudlet's
+     *  setChannel102Table does the same rawset. */
+    setChannel102Value(variable: number, value: number): void;
+    /** Records one ATCP message in the Lua `atcp` global — Mudlet's
+     *  setAtcpTable rawset. The event is raised separately by the engine. */
+    setAtcpValue(name: string, value: string): void;
     setMsspValue(name: string, value: string): void;
     /**
      * Bridges one use of a server-defined MXP element into the Lua `mxp` global
      * as `mxp.<element>` — a fresh table each time, with every attribute key
      * lowercased and a `text` field, exactly as Mudlet's signalMXPEvent builds
-     * it. Values keep their case.
+     * it. Values keep their case. `body` carries what a tag that wraps text
+     * reports about it: the text itself, and the Lua its click would run.
      */
-    setMxpElement(name: string, attrs: Record<string, string>): void;
+    setMxpElement(name: string, attrs: Record<string, string>, body?: {
+        text: string;
+        actions: string[];
+    }): void;
     /**
-     * Mudlet-style async unzip. Reads the zip from the profile VFS, decodes
-     * it on a worker (fflate falls back to a chunked main-thread decode where
-     * workers aren't available), writes every entry under destDir, then
-     * raises sysUnzipDone / sysUnzipError. Always fire-and-forget.
+     * Mudlet-style async unzip, after TLuaInterpreter::unzipAsync: the extract
+     * directory is created (mkpath) before the call returns, whether or not the
+     * zip turns out to be usable, and everything after that — reading the zip,
+     * decoding it, writing every entry under destDir — runs on the timer queue
+     * and ends in sysUnzipDone or sysUnzipError. A missing or broken zip is
+     * therefore reported after unzipAsync() has returned, never inside it.
+     *
+     * Returns null once started, or the message desktop's warnArgumentValue
+     * gives when the directory could not be made (and nothing is queued).
      */
     private runUnzipAsync;
     /** Run `fn` off the current call stack, on the queue a blocked script still
@@ -285,7 +547,21 @@ export declare class LuaRuntime implements IScriptingRuntime {
     setCurrentLine(line: string, _isPrompt: boolean): void;
     setCommand(command: string): void;
     dispatchSendRequest(text: string): boolean;
-    killScriptHandlers(scriptId: string): void;
+    syncScriptHandlers(entries: ScriptHandlerEntry[]): void;
+    /**
+     * A package's `config.lua`, read the way Mudlet reads one: by RUNNING it in
+     * an environment with nothing in it. Returns the string and number globals
+     * the chunk set, or the reason it never finished — a manifest that raises
+     * partway leaves nothing behind, which is the contract packages are written
+     * against and the reason a pattern match is not good enough here.
+     */
+    readPackageConfig(source: string): {
+        ok: true;
+        info: Record<string, string>;
+    } | {
+        ok: false;
+        reason: string;
+    };
     /**
      * Mudlet REGEX_LUA_CODE: the pattern body runs as a Lua function on every
      * incoming line. Side effects (raiseEvent, etc.) always run; the trigger
@@ -295,7 +571,7 @@ export declare class LuaRuntime implements IScriptingRuntime {
     /**
      * Invoke a `registerMapInfo` contributor. The Lua dispatcher pcalls the
      * stashed callback and writes its multi-return into scalar globals
-     * (`__mudix_mapinfo_text` / _bold / _italic / _r / _g / _b). Returning
+     * (`__mudlet_mapinfo_text` / _bold / _italic / _r / _g / _b). Returning
      * `null` covers three cases: runtime is being torn down, callback id is
      * stale, or the callback returned a nil/empty text — the panel treats
      * all three the same (skip the entry).
@@ -321,16 +597,15 @@ export declare class LuaRuntime implements IScriptingRuntime {
      * pushTable does (see issue #2) is gone:
      *   - integer-valued numbers → lua_pushinteger, others → lua_pushnumber
      *   - arrays keyed by Object.keys + lua_rawseti, so dense 0-based arrays
-     *     (map getters) stay 0-indexed and the sparse 1-based arrays toLuaValue
-     *     builds stay 1-indexed — identical to wasmoon's arrIndexs handling
+     *     (map getters) stay 0-indexed and sparse 1-based arrays stay
+     *     1-indexed — identical to wasmoon's arrIndexs handling
      *   - plain objects → string keys via lua_setfield
      * Anything that isn't a primitive / plain array / plain object (wasmoon
-     * LuaTable proxies such as the yajl.null sentinel, functions, Maps, class
-     * instances) is delegated to wasmoon's own pushValue, which is O(1) for
-     * these leaves and preserves their reference identity. Such values only
-     * appear as leaves of GMCP/MSDP payloads (toLuaValue rebuilds every
-     * container as a fresh plain array/object) and always push on the main
-     * thread; on a coroutine stack we can't safely delegate, so degrade to nil.
+     * LuaTable proxies, functions, Maps, class instances) is delegated to
+     * wasmoon's own pushValue, which is O(1) for these leaves and preserves
+     * their reference identity. That is only safe on the main thread; on a
+     * coroutine stack we can't delegate, so degrade to nil. (GMCP/MSDP
+     * payloads don't come through here — see pushDecodedJson.)
      */
     private pushJsValue;
     /**

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

@@ -0,0 +1,71 @@
+/**
+ * Mudlet's argument-type contracts for the C API, as data.
+ *
+ * Desktop Mudlet validates the arguments of its C functions up front
+ * (`getVerifiedString/Int/Bool/Double`, `checkStringArg`, the `WINDOW_NAME` and
+ * `CMDLINE_NAME` macros in `TLuaInterpreter*.cpp`) and RAISES
+ * `"<fn>: bad argument #N type (<name> as <type> expected, got <type>!)"` on a
+ * mismatch. Mudlet Web's bindings mostly coerced or answered false/nil instead,
+ * so a script bug that fails loudly on desktop went unnoticed here and a
+ * `pcall` guard never fired (issue #277).
+ *
+ * Rather than hand-edit a check into every binding, each contract below is
+ * compiled once — by {@link buildArgContractLua} — into a small Lua wrapper that
+ * is installed over the global right after Bridge.lua, before the bundled
+ * mudlet-lua tree runs (so Geyser & co. capture the checked versions, as they
+ * do on desktop). The wrapper only VALIDATES: arguments are forwarded to the
+ * original binding untouched, so its existing coercion and its soft
+ * `(nil, msg)` answers for missing windows/rooms stay as they were.
+ *
+ * Validation follows Lua 5.1's `lua_is*`, exactly like desktop:
+ *   - `s` (lua_isstring)  — a string OR a number passes;
+ *   - `n` / `i` (lua_isnumber) — a number OR a numeric string passes; `i`
+ *     adds getVerifiedInt's 32-bit range check;
+ *   - `b` (lua_isboolean) — strictly true/false.
+ * Where desktop picks an optional leading window name by ARGUMENT COUNT
+ * (`if (lua_gettop(L) > K)`), `win: K` does the same; desktop functions that
+ * dispatch on the TYPE of an argument are written out as `custom` checkers.
+ *
+ * Messages are desktop's, character for character, including the C++ function
+ * name where it differs from the Lua one (`clearWindow` reports as
+ * `clearUserWindow`). The error is raised at the caller's line (level 2 from
+ * the wrapper), as Bridge.lua's own checks are.
+ *
+ * Only functions where desktop really raises belong here; see the PR for #277
+ * for what was left out and why.
+ */
+type Kind = 's' | 'n' | 'i' | 'b' | 'w' | 'c' | 'si' | 'sf' | 'x';
+interface Arg {
+    k: Kind;
+    name?: string;
+    /** Desktop passes isOptional=true: the message reads "is optional". */
+    opt?: boolean;
+    /** Checked only when the argument is present (desktop gates on lua_gettop). */
+    present?: boolean;
+    /** Checked only when present and not nil (desktop gates on lua_isnoneornil). */
+    nonnil?: boolean;
+    /** A hand-written desktop message: `%d` is the position, `%s` the type name. */
+    msg?: string;
+}
+interface Contract {
+    args?: Arg[];
+    /** When more than this many arguments are passed, #1 is a window name. */
+    win?: number;
+    /** How that leading name is checked; WINDOW_NAME semantics when omitted. */
+    winArg?: Arg;
+    /** The C++ function name desktop's messages carry, when it differs. */
+    cname?: string;
+    /**
+     * A Lua function `(n, ...) -> errMsg|nil` for desktop functions whose
+     * argument layout depends on the type of an argument. It may use the
+     * helpers defined in PRELUDE (M, MW, MF, MO, isS, isN).
+     */
+    custom?: string;
+}
+export declare const ARG_CONTRACTS: Record<string, Contract>;
+/**
+ * One Lua chunk that wraps every global named in {@link ARG_CONTRACTS} that
+ * exists when it runs. A missing global is skipped, not created.
+ */
+export declare function buildArgContractLua(): string;
+export {};

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

@@ -7,4 +7,4 @@ import type { BindingContext } from './context';
  * Every one of these is a thin forward into ScriptingAPI, which in turn routes
  * through the engine callbacks so mutations land in the appStore tree.
  */
-export declare function installAutomationBindings({ lua, api }: BindingContext): void;
+export declare function installAutomationBindings({ lua, api, releaseCb }: BindingContext): void;

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

@@ -0,0 +1,13 @@
+import type { BindingContext } from './context';
+/**
+ * Mudlet's addon command API: the commands a package places on the client's own
+ * surfaces, and the handful of things it can change about one afterwards.
+ *
+ * The argument CONTRACT is in Bridge.lua rather than here, because every
+ * refusal names the Lua type of what it was handed ("surfaces has to be a list
+ * of surface names and this one holds a boolean") and a value's Lua type is
+ * precisely what does not survive the trip across wasmoon. What is left for
+ * this side is everything that needs state or real parsing: the ids, the key
+ * sequence, who already holds a key, and what the pulse will accept.
+ */
+export declare function installCommandBindings({ lua, api, registerRawGlobal }: BindingContext): void;