@mudlet/mudlet-web 0.3.0 → 0.4.0

package/dist-lib/mud/text/serverWrap.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Undoing the game's own line wrapping — Mudlet's `undoServerWrap` /
+ * `undoServerWrapWidth` (`TBuffer.cpp`).
+ *
+ * Many MUDs word-wrap their output server-side at a fixed column. That makes
+ * triggers awkward to write (a phrase can be split across two "lines" that were
+ * never separate) and pins the display to the game's width instead of the
+ * window's. Turning the option on holds back any line that ends where the game's
+ * wrapper would have broken it and glues the continuation on, so triggers and
+ * rendering see one whole logical line.
+ *
+ * The heuristics live here as pure functions over *visible* text so they can be
+ * tested directly, and so the pipeline glue in `ScriptingEngine` stays readable.
+ *
+ * **Visible text, not raw.** Mudlet judges `mMudLine`, which is plain characters
+ * with the styling held alongside in a `TChar` buffer. mudix keeps styling
+ * inline as ANSI escapes, so every predicate here takes text that has been put
+ * through {@link visibleText} first — otherwise a colour-heavy line would be
+ * measured as far longer than the player sees, and its escape punctuation would
+ * drag the letter ratio below the prose threshold.
+ */
+/** How far below the configured column a line may end and still count as
+ *  ending *at* it. The game breaks at the last space that fits, so a wrapped
+ *  segment falls up to a word short. Mudlet's `csmServerWrapSlack`. */
+export declare const SERVER_WRAP_SLACK = 15;
+/** Refuse to keep joining past this visible length — a runaway join would
+ *  otherwise swallow a whole screen. Mudlet's `csmServerWrapMaxJoinedLength`. */
+export declare const SERVER_WRAP_MAX_JOINED_LENGTH = 10000;
+/** How much clear room the continuation's first word must have had on the line
+ *  above before that line counts as one the game ended itself. Mudlet's
+ *  `csmServerWrapFitTolerance` — only *clear* room disproves a wrap, because a
+ *  segment inside the join band already sits up to {@link SERVER_WRAP_SLACK}
+ *  short of the column. */
+export declare const SERVER_WRAP_FIT_TOLERANCE = 8;
+/** Longest run of digits a bare list label may carry (`1.`, `12)`, `999.`).
+ *  Mudlet's `csmMaxListNumberDigits`. Bracketed labels are exempt — `[1366]` is
+ *  a label however long it runs, where a bare `1364.` is as likely a price. */
+export declare const MAX_LIST_NUMBER_DIGITS = 3;
+/** How much of a held game line's opening is kept for comparing a continuation
+ *  against. Mudlet's `csmServerWrapSegmentStartChars` — only the first
+ *  {@link SERVER_WRAP_REPEATED_WORDS} shared words and the spaces after them
+ *  have to fall inside it, and that leaves room for it even where a long name
+ *  is one of them. */
+export declare const SERVER_WRAP_SEGMENT_START_CHARS = 48;
+/** How many opening words a continuation has to share with the held segment
+ *  before it is a message the game re-prefixed rather than a wrap. Mudlet's
+ *  `csmServerWrapRepeatedWords` — one is far too common in prose to prove
+ *  anything. */
+export declare const SERVER_WRAP_REPEATED_WORDS = 2;
+/** How long a held-back line waits for its continuation before being committed
+ *  on its own. Mudlet's `csmServerWrapFlushDelayMs`. */
+export declare const SERVER_WRAP_FLUSH_DELAY_MS = 300;
+/** Bounds on `undoServerWrapWidth`, matching Mudlet's `setConfig` validation
+ *  (and the `qBound` its profile-XML import applies). */
+export declare const SERVER_WRAP_WIDTH_MIN = 20;
+export declare const SERVER_WRAP_WIDTH_MAX = 500;
+/** Mudlet's `Host::mUndoServerWrapWidth` default. */
+export declare const SERVER_WRAP_WIDTH_DEFAULT = 80;
+/** Strip ANSI/OSC escapes so a line can be measured and classified the way the
+ *  player sees it. Uses the shared scanner, so it skips CSI, OSC, DCS-family and
+ *  short escapes alike rather than guessing at a regex. */
+export declare function visibleText(line: string): string;
+/**
+ * Mudlet `TBuffer::endsAtServerWrapColumn`. True when a segment's visible length
+ * lands in the `[width - slack, width]` band — i.e. where the game's own word
+ * wrap would have broken it.
+ */
+export declare function endsAtServerWrapColumn(visibleLength: number, width: number): boolean;
+/**
+ * Mudlet `TBuffer::looksLikeWrappedProse`. Word-wrapped prose breaks *between
+ * words*, so a wrapped segment ends in a word (or a sentence mark that happened
+ * to land on the wrap column) and is mostly letters. ASCII art, dividers and
+ * table borders also run right up to the screen width but end in — and are full
+ * of — symbols; gluing those back together would mangle them.
+ *
+ * `visible` must already be ANSI-stripped.
+ */
+export declare function looksLikeWrappedProse(visible: string): boolean;
+/**
+ * Mudlet `TBuffer::segmentEndsSettledSentence`. Where a game swallows the space
+ * it breaks at, a segment that finishes a sentence right on the wrap column
+ * looks exactly like one the game ended there itself — and games end lines on
+ * sentences all the time: a room description, the exits line below it, the
+ * object line below that. Joining those runs separate lines into one and breaks
+ * triggers anchored to their starts.
+ *
+ * A kept break space is the one piece of evidence that settles it, so only a
+ * sentence with nothing at all after it is refused — the check reads the very
+ * last character rather than the last non-space one. What that costs is a
+ * genuine wrap landing exactly after a sentence staying split, which reads as a
+ * break at a sentence boundary; far cheaper than the joins it prevents.
+ *
+ * This belongs at the *hold* decision only: continuations legitimately end
+ * sentences, so {@link looksLikeWrappedProse} must keep accepting them.
+ *
+ * `visible` must already be ANSI-stripped.
+ */
+export declare function segmentEndsSettledSentence(visible: string): boolean;
+/**
+ * Mudlet `TBuffer::continuationRepeatsSegmentOpening`. Games that wrap a tell,
+ * say or channel message themselves put the whole prefix back on every physical
+ * line of it (`Anne teilt Dir mit: …`). Those lines break mid-sentence at the
+ * wrap column and leave no room for the next word, so every other check reads
+ * them as one wrapped paragraph and the join buries the prefix in the middle of
+ * it. The repeated opening is what gives them away — two words of it, because
+ * prose starts line after line with the same article or pronoun and one proves
+ * nothing.
+ *
+ * `segmentStart` is the held *game line's* opening (see
+ * {@link SERVER_WRAP_SEGMENT_START_CHARS}), not the joined paragraph's: a
+ * continuation is compared against the line it actually follows.
+ *
+ * Both strings must already be ANSI-stripped.
+ */
+export declare function continuationRepeatsSegmentOpening(segmentStart: string, visibleNext: string): boolean;
+/**
+ * Mudlet `TBuffer::startsWithListMarker`. A list entry reads exactly like
+ * wrapped prose — a sentence that can end right at the wrap column — so only its
+ * marker tells a list apart from a paragraph.
+ *
+ * Every form accepted here has to be one the game's own word wrap could not
+ * produce at the start of a continuation. The ambiguous ones are deliberately
+ * left out: a spaced dash opens a continuation whenever the wrap lands on it,
+ * and a parenthesised number is as often an aside as a label, so it is capped at
+ * {@link MAX_LIST_NUMBER_DIGITS} like a bare one. Only `[...]` is exempt from
+ * the cap — nothing writes `[2500]` mid-sentence.
+ *
+ * `visible` must already be ANSI-stripped.
+ */
+export declare function startsWithListMarker(visible: string): boolean;
+/**
+ * Mudlet `TBuffer::pendingLineHadRoomForNextWord`. Word wrap breaks a line for
+ * one reason only: the next word did not fit. So a continuation whose first word
+ * would have gone on the game line above it is not a continuation at all — the
+ * game ended that line itself. Without this, two sentences that each stop short
+ * of the wrap column read exactly like one wrapped paragraph.
+ *
+ * `heldSegmentLength` is the length of the last *game line* joined into the held
+ * text, not of the held text itself: once a paragraph has been joined the held
+ * text is longer than the wrap column, and the line the next word would have
+ * landed on is the one the game last sent.
+ *
+ * Both strings must already be ANSI-stripped.
+ */
+export declare function pendingLineHadRoomForNextWord(visiblePending: string, heldSegmentLength: number, visibleNext: string, width: number): boolean;
+/**
+ * Mudlet's guard before joining: a genuine continuation of wrapped prose starts
+ * with a word — or with the single space some games move the break to instead of
+ * swallowing it. *Deeper* indentation, a segment that isn't prose at all, a list
+ * entry, or a first word that would have fitted on the line above all mean the
+ * held line was complete after all and must be committed on its own first.
+ *
+ * `visibleNext` must already be ANSI-stripped.
+ */
+export declare function shouldCommitPendingBeforeJoin(visibleNext: string, nextIsProse: boolean, fit?: {
+    visiblePending: string;
+    heldSegmentLength: number;
+    segmentStart: string;
+    width: number;
+}): boolean;
+/**
+ * Mudlet `TBuffer::joinPendingServerWrapOntoCurrent`. Concatenates the held line
+ * and its continuation, restoring the space the game's wrapper swallowed when
+ * neither side already carries one.
+ *
+ * Operates on the **raw** lines (escapes and all): mudix's styling is inline, so
+ * a plain concatenation carries each half's colour across untouched — the
+ * `TChar`-buffer splice Mudlet needs has no equivalent here. The space-insertion
+ * test looks at the visible text so a trailing colour reset can't hide the space
+ * that is already there.
+ */
+export declare function joinWrappedLines(pending: string, next: string): string;
+/** Lines shorter than this carry no signal about a wrap column. */
+export declare const WRAP_DETECT_MIN_LENGTH = 40;
+/** Evaluate the collected sample only once every this many recorded lines. */
+export declare const WRAP_DETECT_SAMPLE_INTERVAL = 100;
+/** How many lines must sit at the ceiling before it's believable. */
+export declare const WRAP_DETECT_THRESHOLD = 40;
+/** A plausible wrap column has to fall in this range. */
+export declare const WRAP_DETECT_CEILING_MIN = 60;
+export declare const WRAP_DETECT_CEILING_MAX = 160;
+/**
+ * Given the tally of observed line lengths, report the game's apparent wrap
+ * column, or null when the evidence doesn't support one.
+ *
+ * The ceiling is the longest length seen more than incidentally (≥3 times); it
+ * has to be a plausible screen width, carry enough lines just below it, and have
+ * almost nothing beyond it — a game that regularly emits longer lines is not
+ * wrapping at that column.
+ */
+export declare function detectWrapCeiling(counts: ReadonlyMap<number, number>): number | null;

package/dist-lib/mud/timers/TimerEngine.d.ts

@@ -1,3 +1,4 @@
+import { ItemIdSequence } from '../ItemIdSequence';
 import type { TimerNode } from '../../storage/schema';
 export type { TimerNode };
 type TempFn = () => void;
@@ -8,15 +9,23 @@ export declare class TimerEngine {
      *  share a name; we keep id as the canonical handle and build a separate
      *  name → id index for Mudlet's name-based lookups. */
     private readonly perm;
-    /** Name → first matching id, used by remainingTime / kill-by-name. */
+    /** Name → first matching id, used by remainingTime / kill-by-name. Only
+     *  holds *armed* timers, since that is what loadPerm builds handles for. */
     private readonly permNameToId;
-    private nextId;
-    /** Number of live session-scoped temp timers (Mudlet `getProfileStats` temp count). */
+    /** Every stored permanent timer name, armed or not. remainingTime needs it
+     *  to tell "exists but inactive" (-1) from "no such timer" (-2): a disabled
+     *  timer has no handle, so its absence from `perm` proves nothing. */
+    private readonly knownPermNames;
+    /** Shared with every other engine in the profile — see ItemIdSequence. */
+    private idSeq;
+    setIdSequence(seq: ItemIdSequence): void;
+    /** Number of live session-scoped temp timers (Mudlet `getProfileStats` temp
+     *  count). Killed-but-unreaped timers are not live and don't count. */
     get tempCount(): number;
     addTemp(seconds: number, fn: TempFn, repeat?: boolean): number;
     /**
-     * Fire every one-shot timer that has come due, without waiting for the
-     * event loop to deliver its setTimeout.
+     * Fire every timer that has come due, without waiting for the event loop to
+     * deliver its setTimeout.
      *
      * This exists for `waitForEvent`, the busted-only helper Mudlet implements
      * by spinning a nested QEventLoop. A browser can't re-enter its event loop,
@@ -24,15 +33,33 @@ export declare class TimerEngine {
      * deadlock; pumping the due timers by hand is the equivalent of Qt draining
      * its timer queue inside that nested loop.
      *
-     * Repeating timers are deliberately skipped: their setInterval is still
-     * armed, and firing them here would double-fire each tick. A repeat timer
-     * therefore misses ticks across a synchronous wait — the same thing that
-     * happens whenever the main thread is busy.
+     * Repeating timers are pumped too — Mudlet's own specs wait on a repeat
+     * tick, so skipping them made every such wait time out. That works because
+     * a repeat is a self-rescheduling setTimeout (see addTemp): the pending
+     * tick is cancelled and re-armed rather than left to land a second time.
      *
      * Returns the number of timers fired.
      */
     pumpDue(now?: number): number;
+    /**
+     * Whether a temporary timer with this id is still present.
+     *
+     * Backs `exists(id, "timer")`. Temp timers aren't in the store and — unlike
+     * temp triggers and aliases — aren't tracked in LuaRuntime's tempIds either,
+     * so this map is the only thing that knows.
+     *
+     * There is no enable/disable for a temporary timer, so this used to answer
+     * `isActive` too. A killed one splits the two apart: it is still present
+     * here until the reap, but no longer running — see {@link tempIsActive}.
+     */
+    hasTemp(id: number): boolean;
+    /** Whether a temporary timer is present *and* still running — `isActive(id,
+     *  "timer")`. False for one killed since the last reap. */
+    tempIsActive(id: number): boolean;
     killTimer(id: number): boolean;
+    /** Free every timer killed since the last call. Runs once per processed line
+     *  batch, mirroring the deferred cleanup Mudlet's TTimerUnit does. */
+    reapKilled(): void;
     /**
      * Cached previous load. `nodes` is the TimerNode keyed by id, `desc` is the
      * shape that determines whether the running setTimeout/setInterval is still
@@ -50,10 +77,14 @@ export declare class TimerEngine {
      * Mudlet `remainingTime(idOrName)` — seconds until the next fire. For
      * non-repeating timers, returns the time left before the one and only
      * fire. For repeating timers, returns the time until the next tick.
-     * Returns -1 if no live timer matches (Mudlet's miss sentinel).
+     * Mirrors Mudlet's two miss sentinels, which the Lua wrapper turns into
+     * different messages: **-1** the timer exists but isn't running (a perm
+     * timer starts inactive), **-2** nothing of that id or name exists at all.
      *   - Numeric arg: looks up tempTimer ids only.
-     *   - String arg: looks up permanent timer names; falls back to the stored
-     *     TimerNode id when the string is a uuid that no name matched.
+     *   - String arg: permanent timer names (or a raw uuid), then temp ids —
+     *     a temporary timer's "name" is the number tempTimer handed back, so
+     *     remainingTime(tostring(id)) has to resolve the same timer as
+     *     remainingTime(id).
      */
     remainingTime(idOrName: number | string): number;
     private stopPerm;

package/dist-lib/mud/triggers/TriggerEngine.d.ts

@@ -35,9 +35,24 @@ export type TriggerMatch = {
     namedSpans?: Record<string, CaptureSpan>;
     matchStart?: number;
 };
+/** The lineage a trigger created mid-pass belongs to, and how many generations
+ *  deep it sits in it. Absent on a trigger that was not created while a line was
+ *  being processed. See TriggerEngine.addedWhileProcessing. */
+interface SameLineChain {
+    chainId: number;
+    generation: number;
+}
+/** What a caller can tell the engine about a temp trigger beyond its pattern. */
+export interface TempOptions {
+    /** As the runaway report names it. Mudlet uses the trigger's id when the
+     *  call carried no name of its own. */
+    name?: string;
+    onStopped?: () => void;
+}
 export declare class TriggerEngine {
     private readonly temp;
-    private nextId;
+    /** Key for this engine's own temp map — see PatternEngine.nextInternalId. */
+    private nextInternalId;
     private inProcessTemp;
     private permCompiled;
     private allById;
@@ -45,12 +60,32 @@ export declare class TriggerEngine {
     private permReg;
     private unified;
     private orderDirty;
+    private processingDepth;
+    private addedWhileProcessing;
+    /** Lineage of each permanent ROOT trigger enrolled for the current line. */
+    private permSameLine;
+    /** Lineage id → name of the trigger whose script started it, for the report. */
+    private sameLineChainStarters;
+    private lastSameLineChainId;
+    private currentSameLineChainId;
+    private currentSameLineGeneration;
+    /** The name of the trigger whose script is running, for the abort report. */
+    private currentExecutingTriggerName;
+    /** When the runaway report was last posted, so a runaway whose creator
+     *  outlives its line cannot bury the game text. */
+    private lastRunawayReportAt;
     private cache;
     private lineCounter;
     private readonly chainOpenUntil;
     private hasChildren;
     private andStates;
+    /** Triggers still firing on their own after completing, and the match they
+     *  re-report while they do. See the fire-length branch in matchPermEntryOnce. */
+    private keepFiring;
     private filterActiveText;
+    /** Every offering a filter makes to its children this line: one per
+     *  capture group, or the whole match when it has none. See openChain. */
+    private filterCaptures;
     private filterActiveOffset;
     /** Resolves once PCRE wasm is initialized and patterns can be compiled. */
     static ready(): Promise<void>;
@@ -78,7 +113,7 @@ export declare class TriggerEngine {
      * Invalid regex patterns return a no-op disposer so callers don't need
      * to special-case compile failures.
      */
-    addTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt'): () => void;
+    addTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt', opts?: TempOptions): () => void;
     /**
      * Mudlet `tempLineTrigger(from, howMany, fn)`. A position-based trigger with
      * no pattern: it fires `fn([lineText])` on `howMany` consecutive lines,
@@ -95,9 +130,15 @@ export declare class TriggerEngine {
      * negative result is cached so we don't retry on every loadPerm. */
     private compileItem;
     processTemp(line: string, isPrompt?: boolean): void;
+    /** Leave a processing pass, and once the outermost one is over, forget the
+     *  lineages it tracked: a trigger that outlives the line it was created on
+     *  is no longer part of one, so what IT creates later starts counting
+     *  afresh. */
+    private endPass;
     /** Match + fire a single temp trigger against `line`. Self-expiring `line`
      *  triggers delete themselves (and dirty the unified order) when spent. */
     private fireTempEntry;
+    private fireTempEntryInner;
     matchPerm(line: string, isPrompt?: boolean): TriggerMatch[];
     /**
      * Match one permanent compiled entry against `line`, appending any matches
@@ -106,6 +147,9 @@ export declare class TriggerEngine {
      * shared across all entries processed for that line.
      */
     private matchPermEntry;
+    /** The nearest filter ancestor of `item`, or null when it has none. */
+    private innermostFilterId;
+    private matchPermEntryOnce;
     /**
      * Mudlet-faithful single pass: walk the one ordered list of permanent and
      * temporary triggers (see the ordering notes on the fields) and, for each
@@ -122,6 +166,53 @@ export declare class TriggerEngine {
      * re-entrancy a handler can cause via `feedTriggers`.
      */
     process(line: string, isPrompt: boolean, exec: (match: TriggerMatch) => void): void;
+    /**
+     * Enrol a trigger armed while a line was being processed, so the pass can
+     * offer it that line, and put it in a lineage: the one belonging to the
+     * trigger whose script armed it, a generation on, or a new one when the
+     * script predates the line.
+     */
+    private registerSameLineCreation;
+    /**
+     * The same, for a permanent trigger a script created mid-pass. Only ROOT
+     * triggers carry a lineage: one sitting in a folder creates on the folder's
+     * behalf, and reading the child's own (always empty) lineage instead would
+     * start a fresh one every round — which never deepens and so never trips.
+     */
+    notePermCreated(node: TriggerNode, root: TriggerNode): void;
+    /** Join the lineage of the trigger whose script is running, a generation on;
+     *  or start one when that script predates the line. */
+    private nextSameLineChain;
+    /** The lineage of something enrolled for this line, whichever kind it is. */
+    private sameLineOf;
+    /** The root ancestor's id — the node a lineage is recorded against. */
+    private rootIdOf;
+    /** Run a permanent trigger's script inside its lineage, so what it creates
+     *  is enrolled behind it rather than starting a lineage of its own. */
+    private execPerm;
+    /**
+     * Run `fn` as the script of the trigger named `name`, so anything it arms
+     * joins that trigger's lineage rather than starting one of its own.
+     */
+    runAsTrigger<T>(name: string, sameLine: SameLineChain | undefined, fn: () => T): T;
+    /**
+     * End a lineage that keeps arming triggers which match the line being
+     * processed. Stopping the pass alone would not do: what it created is still
+     * live, so the next line would start with a budget's worth of them and each
+     * would spawn a budget's worth again. Only this lineage is disowned — a
+     * capture trigger an unrelated script armed on the same line belongs to a
+     * lineage of its own and is left alone.
+     */
+    private stopSameLineCreationLoop;
+    /** Tell the player, at most once every REPORT interval — a runaway whose
+     *  creator outlives the line trips on every matching line, and an unthrottled
+     *  report would bury the game text it is trying to explain. */
+    private reportRunaway;
+    /** Where the runaway report is printed. ScriptingEngine wires this to the
+     *  main console; unset (tests, teardown) the report is dropped. */
+    setRunawayReporter(fn: ((text: string) => void) | null): void;
+    /** How the engine switches off a permanent trigger it stopped. */
+    setPermDisabler(fn: ((nodeId: string) => void) | null): void;
     /** Rebuild the merged, path-sorted processing list from the current
      *  permanent entries and temporary triggers. Called lazily from process()
      *  when either source changed. */
@@ -137,9 +228,27 @@ export declare class TriggerEngine {
      * `ScriptingAPI.currentLineMatchesColor`. Passing `null` disables every
      * colour trigger (e.g. during runtime teardown).
      */
-    setColorMatcher(fn: ((fg: number, bg: number) => boolean) | null): void;
+    setColorMatcher(fn: ((fg: number, bg: number, window: {
+        start: number;
+        length: number;
+    } | null) => boolean) | null): void;
     destroy(): void;
+    /**
+     * Advance every state an AND trigger has in flight against this line, and
+     * report the ones that completed on it.
+     *
+     * States are a LIST, not one: a trigger whose first condition matches twice
+     * before its second ever does has two matches part-way through, and both
+     * complete when that second condition finally arrives. Keeping a single
+     * state let the newer one overwrite the older, so only one ever fired.
+     */
     private processAndTrigger;
+    /** Carry one in-flight state as far through the remaining conditions as this
+     *  line takes it. Several can be satisfied by the same line. */
+    private advanceAndState;
+    /** The match a completed AND state reports: every line's captures, in order,
+     *  as `multimatches`. */
+    private andMatch;
     /**
      * Record a chain-head match: open the chain for `fireLength` more lines and,
      * if the trigger is also a filter, stash the captured/matched text so

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

@@ -1,4 +1,14 @@
+import type { TriggerPattern } from '../storage/schema';
 import type { InstallOutcome } from './ScriptingAPI';
+/**
+ * The item families the tree-walking APIs accept, lowercased — Mudlet's
+ * "'alias', 'button', 'script', 'keybind', 'timer' or 'trigger'", plus the
+ * 'key' spelling the engine already treats as 'keybind'. Lives here rather than
+ * on the engine so the no-op host below answers the same list: a runtime with no
+ * engine wired has no items, but it still knows what an item type IS, and
+ * reporting a valid type as invalid would send a caller looking for a typo.
+ */
+export declare const KNOWN_ITEM_TYPES: ReadonlySet<string>;
 /**
  * Everything {@link ScriptingAPI} needs from {@link ScriptingEngine}.
  *
@@ -15,6 +25,22 @@ import type { InstallOutcome } from './ScriptingAPI';
  *
  * Members are grouped the way the engine groups them, not alphabetically.
  */
+/** What tempComplexRegexTrigger asks for: a session-scoped trigger carrying
+ *  everything a permanent one can. See ScriptingEngine.createTempComplexTrigger. */
+export interface TempComplexTriggerSpec {
+    name: string;
+    patterns: TriggerPattern[];
+    code: string;
+    multiline: boolean;
+    isFilter: boolean;
+    multipleMatches: boolean;
+    fireLength: number;
+    delta: number;
+    highlight?: {
+        fg?: string;
+        bg?: string;
+    };
+}
 export interface EngineHost {
     /** Run a chunk of Lua on behalf of a clicked hyperlink. Errors are reported
      *  through the API's error channel rather than thrown. */
@@ -34,9 +60,12 @@ export interface EngineHost {
     requestReconnect(): boolean;
     /** Run a synthetic batch of lines through the same pipeline as network
      *  output, so `feedTriggers` shares ordering semantics with real data. */
+    /** `fromServer` distinguishes a batch that came off the socket from one a
+     *  script synthesised (feedTriggers). Absent means the socket. */
     processFlushBatch(groups: {
         text: string;
         type: string;
+        fromServer?: boolean;
     }[]): void;
     /** Apply any coalesced trigger/alias reloads immediately instead of on the
      *  scheduled microtask. The Mudlet `perm…`, `enableTrigger` and
@@ -54,6 +83,8 @@ export interface EngineHost {
     installModuleFromPath(path: string): InstallOutcome;
     uninstallModuleByName(name: string): boolean;
     syncModuleToFile(name: string): Promise<void>;
+    /** Write every module flagged to sync back out to its own file. */
+    saveSyncedModules(): void;
     reloadModuleFromFile(name: string): boolean;
     setModuleSync(name: string, sync: boolean): void;
     getModuleSync(name: string): boolean;
@@ -75,12 +106,22 @@ export interface EngineHost {
     /** Read raw bytes from the profile VFS, or null if missing/unreadable.
      *  Backs synchronous binary consumers such as setMovie's GIF decoder. */
     readFileBytes(path: string): Uint8Array | null;
+    /** Write raw bytes into the VFS, creating parent directories. False with no
+     *  VFS or when the write throws. Paths are absolute, so this also reaches
+     *  outside the profile — the shared window layout lives beside the profiles
+     *  folder, not inside one. */
+    writeFileBytes(path: string, bytes: Uint8Array): boolean;
+    /** Absolute VFS path of the directory that holds every profile folder —
+     *  Mudlet's configuration directory, where files shared between profiles
+     *  (the window layout) live. Null with no VFS. */
+    configDirectory(): string | null;
     toggleScriptByName(name: string, enabled: boolean): boolean;
     toggleTriggerByName(name: string, enabled: boolean): boolean;
     toggleTimerByName(name: string, enabled: boolean): boolean;
     toggleAliasByName(name: string, enabled: boolean): boolean;
     toggleKeyByName(name: string, enabled: boolean): boolean;
-    toggleToolBarByName(name: string, show: boolean): boolean;
+    /** 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. */
@@ -104,12 +145,19 @@ export interface EngineHost {
         node: string;
         isActive: boolean;
     }> | null;
-    findItemsByName(name: string, type: string, exact: boolean, caseSensitive: boolean): number[];
+    findItemsByName(name: string, type: string, exact: boolean, caseSensitive: boolean): number[] | null;
+    /** Whether `type` names an item family at all. */
+    isKnownItemType(type: string): boolean;
+    /** Next id from the profile's single item-id sequence. Temporary items draw
+     *  from it too, so a temp and a permanent item can never collide. */
+    allocateItemId(): number;
     isAncestorsActiveById(id: number, type: string): boolean | null;
     getProfileStats(): Record<string, unknown>;
     createPermScript(name: string, parent: string, code: string): number;
     createPermRegexTrigger(name: string, parent: string, regexes: string[], code: string): number;
     createPermSubstringTrigger(name: string, parent: string, patterns: string[], code: string): number;
+    createTempComplexTrigger(spec: TempComplexTriggerSpec): number;
+    removeTemporaryTriggerById(id: number): boolean;
     createPermBeginOfLineStringTrigger(name: string, parent: string, patterns: string[], code: string): number;
     createPermExactMatchTrigger(name: string, parent: string, patterns: string[], code: string): number;
     createPermPromptTrigger(name: string, parent: string, code: string): number;
@@ -120,14 +168,19 @@ export interface EngineHost {
     createPermKey(name: string, parent: string, modifier: number, key: string | number, code: string): number;
     createTempButton(toolbar: string, name: string, code: 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;
+    /** Which of Mudlet's button refusals applies to `name`. */
+    buttonKindByName(name: string): 'missing' | 'plain' | 'pushdown';
     setButtonStyleSheetByName(name: string, css: string): boolean;
     setScriptByName(name: string, code: string, pos: number): number;
     getScriptByName(name: string, pos: number): {
         code: string;
-        count: number;
+        id: number;
     } | null;
+    /** Remove the script with this numeric id; true when one was removed. */
+    removeScriptById(id: number): boolean;
     /** 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. */

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

@@ -49,7 +49,15 @@ export interface IScriptingRuntime {
     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;
     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
+     *  property of how a runtime ships its own library, not of running scripts:
+     *  the Lua runtime serves `/lua/...` this way. */
+    readBuiltinBytes?(path: string): Uint8Array | null;
     setCurrentLine(line: string, isPrompt: boolean): void;
+    /** The line {@link setCurrentLine} last recorded. The engine reads it back
+     *  to restore the outer line after a nested feedTriggers. */
+    getCurrentLine(): string;
     /**
      * Mirror the last command-bar input into the Lua `command` global, matching
      * Mudlet's AliasUnit::processDataStream. Read by scripts/keys such as the
@@ -66,6 +74,12 @@ export interface IScriptingRuntime {
      * denyCurrentSend().
      */
     dispatchSendRequest(text: string): boolean;
+    /**
+     * Start a speedwalk between two rooms (Mudlet Host::startSpeedWalk): find
+     * the path and hand it to the mapper package's `doSpeedWalk`. Driven by the
+     * map's double-click-to-walk gesture via WindowManager.startSpeedWalk.
+     */
+    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
@@ -78,6 +92,9 @@ export interface IScriptingRuntime {
      * (unlike permanent items) don't live in the persisted store.
      */
     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;
     /** 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)`. */
@@ -85,6 +102,11 @@ export interface IScriptingRuntime {
     /** 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;
     /** 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. */