@mudlet/mudlet-web 0.5.0 → 1.0.1

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

@@ -1,4 +1,4 @@
-import type { TriggerPattern } from '../storage/schema';
+import type { KeyNode, TriggerPattern } from '../storage/schema';
 import type { InstallOutcome } from './ScriptingAPI';
 /**
  * The item families the tree-walking APIs accept, lowercased — Mudlet's
@@ -40,6 +40,12 @@ export interface TempComplexTriggerSpec {
         fg?: string;
         bg?: string;
     };
+    /** Its code string did not compile. Mudlet still makes the trigger, but it
+     *  is inactive however it is switched — it never matches or highlights. */
+    uncompiled?: boolean;
+    /** Called once when the trigger is killed or expires, so the callback it
+     *  dispatches to can be let go of. */
+    onFree?: () => void;
 }
 export interface EngineHost {
     /** Run a chunk of Lua on behalf of a clicked hyperlink. Errors are reported
@@ -75,11 +81,21 @@ export interface EngineHost {
     flushPendingApplies(): void;
     /** Raise a Mudlet event with the given arguments. */
     raiseEvent(event: string, args: unknown[]): void;
+    /** Raise sysExitEvent now, while the profile is still connected. It is
+     *  raised at most once per engine, so the teardown that follows does not
+     *  repeat it. */
+    raiseExitEvent(): void;
     installPackageFromVfsPath(path: string): InstallOutcome;
     uninstallPackageByName(name: string): boolean;
+    /** Which package or module owns the code a Lua frame is running ('' for
+     *  the profile's own), from the frame's chunk source. */
+    packageOfCaller(source: string, isMain: boolean, calledFromMain: boolean): string;
+    /** Lua `uninstallPackage()`: the refusal, or null once it is uninstalled. */
+    uninstallPackageFromScript(name: string): string | null;
     getPackageNames(): string[];
     getPackageInfo(name: string): Record<string, string>;
-    setPackageInfo(name: string, key: string, value: string): boolean;
+    /** The refusal, or null once the field is set. */
+    setPackageInfo(name: string, key: string, value: string): string | null;
     installModuleFromPath(path: string): InstallOutcome;
     uninstallModuleByName(name: string): boolean;
     syncModuleToFile(name: string): Promise<void>;
@@ -87,21 +103,27 @@ export interface EngineHost {
     saveSyncedModules(): void;
     /** Write the profile out as a Mudlet-format XML save, answering with the
      *  full path written. The XML half of `saveProfile([location [, saveName]])`. */
+    /** A refusal names the file it could not write, when it got that far. */
     saveProfileXml(location?: string, saveName?: string): {
         ok: true;
         path: string;
     } | {
         ok: false;
         err: string;
+        path?: string;
     };
-    reloadModuleFromFile(name: string): boolean;
+    /** Put package installs off until the turn that started a profile save has
+     *  ended; see ScriptingEngine.markProfileSaveInFlight. */
+    markProfileSaveInFlight(): void;
+    reloadModuleFromFile(name: string): InstallOutcome;
     setModuleSync(name: string, sync: boolean): void;
     getModuleSync(name: string): boolean;
     setModulePriority(name: string, priority: number): boolean;
     getModulePriority(name: string): number;
     getModuleNames(): string[];
     getModulePath(name: string): string | null;
-    setModuleInfo(name: string, key: string, value: string): boolean;
+    /** The refusal, or null once the field is set. */
+    setModuleInfo(name: string, key: string, value: string): string | null;
     /** Module manifest fields as a flat record, with any Lua-set overrides
      *  applied. Null when no module by that name is installed. */
     getModuleInfoRecord(name: string): Record<string, unknown> | null;
@@ -132,20 +154,16 @@ export interface EngineHost {
     /** Null when the toolbar moved, otherwise why it did not. */
     toggleToolBarByName(name: string, show: boolean): string | null;
     setTriggerStayOpenByName(name: string, lines: number): boolean;
-    /** The saved keybinding carrying this numeric id, or null — getKeyCode
-     *  resolves a permanent key by the id permKey returned, not only by name. */
-    keyNodeByNumericId(numericId: number): {
-        key: string;
-        modifiers: string[];
-    } | null;
+    /** The saved keybinding or key group carrying this numeric id or name, or
+     *  null — getKeyCode resolves a permanent key by the id permKey returned as
+     *  well as by name, and reaches the groups and switched-off keys the key
+     *  engine does not hold. */
+    savedKeyNode(idOrName: number | string): KeyNode | null;
     /** Mudlet's Host::setForceMXPProcessorOn — run the in-band MXP parser with
      *  no option-91 handshake. */
     setForceMxpProcessorOn(on: boolean): void;
     /** Mudlet `exists(nameOrId, type)` — count of matching items. */
     existsByName(nameOrId: string | number, type: string): number;
-    /** enable/disable a script-created temp trigger or alias by its numeric id.
-     *  False when no live temp item has that id. */
-    setTempItemEnabled(id: number, enabled: boolean): boolean;
     /** Mudlet `isActive(nameOrId, type)` — count of matching *active* items. */
     isActiveByName(nameOrId: string | number, type: string, checkAncestors: boolean): number;
     ancestorsById(id: number, type: string): Array<{
@@ -175,13 +193,13 @@ export interface EngineHost {
     /** `modifier` arrives as a Qt::KeyboardModifier int; the engine translates
      *  it back into `["ctrl", …]` strings to store on the KeyNode. */
     createPermKey(name: string, parent: string, modifier: number, key: string | number, code: string): number;
-    createTempButton(toolbar: string, name: string, code: string, orientation: number): number;
+    createTempButton(toolbar: string, name: string, orientation: number): number;
     createTempButtonToolbar(name: string, orientation: number, location: number): number;
     /** True when the state actually changed; false when it already was that. */
-    setButtonStateByName(name: string, state: boolean): boolean;
-    getButtonStateByName(name: string): boolean | null;
+    setButtonStateByName(name: string | number, state: boolean): boolean;
+    getButtonStateByName(name: string | number): boolean | null;
     /** Which of Mudlet's button refusals applies to `name`. */
-    buttonKindByName(name: string): 'missing' | 'plain' | 'pushdown';
+    buttonKindByName(name: string | number): 'missing' | 'plain' | 'pushdown';
     setButtonStyleSheetByName(name: string, css: string): boolean;
     setScriptByName(name: string, code: string, pos: number): number;
     getScriptByName(name: string, pos: number): {
@@ -190,15 +208,21 @@ export interface EngineHost {
     } | null;
     /** Remove the script with this numeric id; true when one was removed. */
     removeScriptById(id: number): boolean;
+    /** Why the body of the script with this numeric id failed the last time it
+     *  ran, or null when it ran cleanly. */
+    scriptLoadErrorById(id: number): string | null;
     /** Mudlet's killTimer/killAlias/killTrigger/killKey by permanent-item name. */
     killByName(kind: 'timer' | 'alias' | 'trigger' | 'key', name: string): boolean;
-    /** Mudlet `resetProfile()` — reload the profile with a fresh Lua VM. */
-    resetProfile(): void;
-    /** Render a map area to a PNG inside the profile VFS. */
-    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number): {
+    /** Mudlet `resetProfile()` — reload the profile with a fresh Lua VM. True
+     *  when the reset was armed, false when it was refused. */
+    resetProfile(): boolean;
+    /** Render a map area to a PNG inside the profile VFS — one z level, or
+     *  every level to a file each for `true`. */
+    exportAreaImageToVfs(areaId: number, filePath: string, zLevel?: number | true): {
         path: string;
     } | {
         error: string;
+        target?: boolean;
     };
 }
 /**

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

@@ -26,10 +26,51 @@ export interface LuaGlobalEntry {
     builtin?: boolean;
     keyKind?: string;
 }
+/** One step of a path into `_G`: the key, and whether Lua holds it as a string
+ *  or a number (`myTable.name` vs `myTable[3]`). */
+export interface VariablePathSegment {
+    key: string;
+    kind: 'string' | 'number';
+}
+/**
+ * One edit the Variables view asks the runtime to make.
+ *
+ * `set` assigns `value`, read according to `valueType` — retyping to `table`
+ * keeps an existing table's contents rather than emptying it. `move` renames
+ * the last segment in place (which is also how the key type is changed), and
+ * refuses to overwrite a key that already exists. `delete` assigns nil.
+ */
+export type VariableEdit = {
+    op: 'set';
+    path: VariablePathSegment[];
+    valueType: 'string' | 'number' | 'boolean' | 'table';
+    value: string;
+} | {
+    op: 'move';
+    path: VariablePathSegment[];
+    to: VariablePathSegment;
+} | {
+    op: 'delete';
+    path: VariablePathSegment[];
+};
+/** A script's event-handler-list registration (Host::mEventHandlerMap entry):
+ *  the name its handler function is looked up by, whether it may run right now
+ *  (isActive() && ancestorsActive()), and the events it lists. No events means
+ *  the script is not registered at all. */
+export interface ScriptHandlerEntry {
+    id: string;
+    name: string;
+    active: boolean;
+    events: string[];
+}
 export interface IScriptingRuntime {
     load(code: string, name: string): void;
-    /** Execute a code chunk once, without match context. Used for timers and keybindings. */
-    run(code: string, name: string): void;
+    /** Execute a code chunk once, without match context. Used for timers and
+     *  keybindings. `chunkName` as for {@link runWithMatches}. */
+    run(code: string, name: string, chunkName?: string): void;
+    /** The error compiling `code` gives, without running it, or null when it
+     *  compiles. `chunkName` is used as Lua's chunk name verbatim. */
+    syntaxError?(code: string, chunkName: string): string | null;
     /** Dispatch an event to user-registered handlers. Handlers run synchronously. */
     emitEvent(event: string, args: unknown[]): void;
     /**
@@ -47,7 +88,29 @@ export interface IScriptingRuntime {
      * `name` is the flat variable name; the value is a scalar string.
      */
     setMsspValue(name: string, value: string): void;
-    runWithMatches(code: string, name: string, matches: (string | undefined)[], multimatches?: (string | undefined)[][], namedGroups?: Record<string, string>, captureSpans?: CaptureSpan[], namedSpans?: Record<string, CaptureSpan>, fullMatchSpan?: CaptureSpan): void;
+    /**
+     * Write one zMUD channel-102 report into the runtime's `channel102` table.
+     * Both halves are the raw bytes the subnegotiation carried.
+     */
+    setChannel102Value(variable: number, value: number): void;
+    /**
+     * Write one ATCP message into the runtime's `atcp` table: `name` is the
+     * dotless message name (`CharVitals`), `value` its string.
+     */
+    setAtcpValue(name: string, value: string): 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)[], 
+    /** The chunk name Lua reports the code under — Mudlet's
+     *  "Trigger: <name>" / "Alias: <name>". Without one, `name` is used
+     *  as a file name ("@name"). Last, so the positional callers ahead of
+     *  it are undisturbed. */
+    chunkName?: string): void;
+    /** Run `fn` with a fire's captures in place for selectCaptureGroup and the
+     *  like, leaving the script-facing `matches` table alone — what a trigger
+     *  whose command is sent, or which has no script, hands on (desktop's
+     *  setCaptureGroups without the call that builds `matches`). */
+    withCaptures?(matches: (string | undefined)[], captureSpans: CaptureSpan[] | undefined, namedSpans: Record<string, CaptureSpan> | undefined, fullMatchSpan: CaptureSpan | undefined, fn: () => void): void;
     destroy(): void;
     /** Bytes behind a path in the runtime's read-only bundled namespace, or null
      *  when it has none / the path is not one of them. Optional because it is a
@@ -64,11 +127,33 @@ export interface IScriptingRuntime {
      * stock "Repeat Last Command" key (`send(command)`).
      */
     setCommand(command: string): void;
+    /** Start an alias pass for `command`: {@link setCommand}, and drop what an
+     *  enclosing pass kept for {@link settleCommandAfterAliasPass}. */
+    setExpandedCommand?(command: string): void;
+    /** End of an alias pass, at every depth: `command` holds the last command
+     *  expanded unless a script set it (TLuaInterpreter::settleCommandAfterAliasPass). */
+    settleCommandAfterAliasPass?(): void;
+    /** Run `fn`, whose entry into the runtime is an alias's script — the only
+     *  caller expandAlias() hands its own `command` back to. */
+    asAliasScript?<T>(fn: () => T): T;
     /**
      * Evaluate a Lua-function trigger pattern. Side effects (raiseEvent, etc.)
      * always run; the trigger "matches" only when the body returns truthy.
      */
     evalTriggerPattern(code: string): boolean;
+    /** Run a package's `config.lua` in an empty environment and report what it
+     *  set, or why it never finished — the way Mudlet reads a manifest.
+     *
+     *  Optional: a runtime that cannot run one leaves the installer to read the
+     *  manifest by pattern, which is enough for a well-formed config.lua and
+     *  cannot tell a manifest that would raise from one that would not. */
+    readPackageConfig?(source: string): {
+        ok: true;
+        info: Record<string, string>;
+    } | {
+        ok: false;
+        reason: string;
+    };
     /**
      * Raise sysDataSendRequest and report whether a handler called
      * denyCurrentSend().
@@ -81,32 +166,20 @@ export interface IScriptingRuntime {
      */
     startSpeedWalk(from: number, to: number): void;
     /**
-     * Kill every event handler registered by `wrapScript` for the given
-     * script id. Called when a script is removed or disabled so its handlers
-     * stop firing without waiting for a full runtime reload.
-     */
-    killScriptHandlers(scriptId: string): void;
-    /**
-     * 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
-     * (unlike permanent items) don't live in the persisted store.
+     * Bring scripts' event-handler-list registrations up to date: register,
+     * re-register after a list change (to the end, as setEventHandlerList
+     * does), rename, flip the active flag, or drop one (empty `events`).
      */
-    tempItemExists(id: number, type: string): boolean;
-    /** A live temp item of `type` carrying this script-supplied name (Mudlet's
-     *  tempComplexRegexTrigger is the one temp API that takes one), or null. */
-    tempItemIdByName(name: string, type: string): number | null;
+    syncScriptHandlers(entries: ScriptHandlerEntry[]): void;
     /** Publish one use of a server-defined MXP element as `mxp.<element>`. */
-    setMxpElement(name: string, attrs: Record<string, string>): void;
-    /** Whether a live temp item is enabled — backs `isActive(id, type)`. */
-    tempItemEnabled(id: number): boolean;
-    /** enable/disable a live temp item by id — backs enableTrigger/disableTrigger
-     *  (and the alias pair) when handed the numeric id rather than a name. */
-    setTempItemEnabled(id: number, enabled: boolean): boolean;
-    /** Free every temp item killed since the last call, or only those of `type`.
-     *  A killed item stops firing immediately but stays findable until here,
-     *  which is Mudlet's deferred per-unit cleanup: aliases are reaped when
-     *  nested alias processing unwinds, triggers when the line batch finishes. */
-    reapKilledTempItems(type?: 'alias' | 'trigger'): void;
+    setMxpElement(name: string, attrs: Record<string, string>, body?: {
+        text: string;
+        actions: string[];
+    }): void;
+    /** Whether the capture globals are being built, when a pass a __gc
+     *  finaliser starts is refused (TLuaInterpreter::buildingCaptureTables).
+     *  Optional: a runtime with no finalisers never builds under one. */
+    buildingCaptureTables?(): boolean;
     /** Rebuild saved Lua globals (a Mudlet `<VariablePackage>` tree) into `_G`. */
     restoreVariables(vars: MudletVariable[]): void;
     /** Snapshot the save-listed globals out of `_G` into a variable tree. */
@@ -114,4 +187,7 @@ export interface IScriptingRuntime {
     /** Enumerate `_G` for the Variables view: user globals as a full nested tree,
      *  built-ins flagged (and not recursed). */
     listGlobals(): LuaGlobalEntry[];
+    /** Apply one Variables-view edit to `_G`. Returns null on success, or the
+     *  reason it was refused. */
+    editVariable(request: VariableEdit): string | null;
 }

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

@@ -14,7 +14,7 @@
  * This class owns the same bookkeeping — the frame records, the accumulated
  * borders, the parent/child hierarchy and the tab groups — and drives the UI
  * through {@link MxpFrameHost} so the geometry is testable without a DOM.
- * mudix maps a frame's console onto a mini-console (an overlay panel with
+ * Mudlet Web maps a frame's console onto a mini-console (an overlay panel with
  * script-controlled geometry); the tab strip is window chrome rendered by
  * ScriptWindow, and child frames nest by portalling into the parent panel's
  * viewport, so their coordinates are parent-relative.
@@ -51,7 +51,13 @@ export interface MxpFrameHost {
     placeFrameConsole(name: string, x: number, y: number, width: number, height: number, parent?: string): void;
     /** Open an `EXTERNAL` frame as a free-floating window with its own titlebar. */
     openExternalFrame(name: string, title: string, width: number, height: number): void;
+    /** Close a frame's console — only while it is still the frame's own: a
+     *  script that deleted it and made a window of its own under the name
+     *  keeps that window. */
     destroyFrameConsole(name: string): void;
+    /** Whether a script's own window holds `name`, which a frame must not
+     *  take over: closing the frame would leave the window unreachable. */
+    nameTakenByScript(name: string): boolean;
     showFrameConsole(name: string): void;
     raiseFrameConsole(name: string): void;
     setFrameScrolling(name: string, enabled: boolean): void;
@@ -101,6 +107,9 @@ export declare class MxpFrameManager {
      *  omitting it keeps whichever page is showing, so a tab arriving or closing
      *  never yanks the reader off the one they were watching. */
     private publishTabs;
+    /** Whether `name` is a page of a tab strip that is showing another page —
+     *  a tab host's own console included, once a docked frame is in front. */
+    isBehindTab(name: string): boolean;
     /** Bring `name` to the front of whichever tab strip holds it, if any. */
     private selectTabFor;
     /**