@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -1,4 +1,6 @@
-import type { TriggerNode } from '../../storage/schema';
+import type { TriggerNode, TriggerPattern } from '../../storage/schema';
+import { ItemIdSequence } from '../ItemIdSequence';
+import type { RgbColor } from '../text/FormatState';
 export type { TriggerNode };
 type Capture = string | undefined;
 type TempFn = (matches: Capture[], spans?: {
@@ -30,11 +32,47 @@ export type TriggerMatch = {
     captures: Capture[];
     matchedText: string;
     multimatches?: Capture[][];
+    /** Named captures per multimatches row, aligned with it. */
+    multiNamedGroups?: (Record<string, string> | undefined)[];
     namedGroups?: Record<string, string>;
     captureSpans?: CaptureSpan[];
     namedSpans?: Record<string, CaptureSpan>;
     matchStart?: number;
+    groupCount?: number;
+    /** See MatchResult.wholeMatchSkipped. */
+    wholeMatchSkipped?: boolean[];
+    /** See MatchResult.positionsInCurrentColumns. */
+    positionsInCurrentColumns?: boolean;
+    /** No capture groups were set for this fire: the script's `matches` is
+     *  left empty rather than built from `matchedText`/`captures`. True for a
+     *  Lua-function or prompt match and for a fire-length (stay-open) line,
+     *  which desktop runs through a bare `execute()`. */
+    captureless?: boolean;
 };
+/**
+ * A colorizer trigger's stored colour (`mFgColor`/`mBgColor`) as desktop reads
+ * it: QColor::fromString, so a colour name, `#rgb`, `#aarrggbb` and the 9- and
+ * 12-digit forms paint as well as `#rrggbb` does. Null for a string QColor
+ * calls invalid, which leaves that side of the text as it was.
+ */
+export declare function highlightColor(spec: string): RgbColor | null;
+/**
+ * What a trigger's built-in highlight paints, given the `matches` list its
+ * script is handed (whole match first) and the spans the engine reported.
+ *
+ * Mudlet walks the whole flattened capture list — {whole, groups…} per
+ * occurrence — and paints each entry EXCEPT the whole-match ones, but only when
+ * there is more than one entry to choose from: `position %
+ * numberOfCaptureGroups != 1`, 1-based, in TTrigger::processRegexMatch. With one
+ * entry per occurrence the modulus is 1 and nothing is skipped, which is what
+ * makes a match-all substring paint all of its hits. A capture-less match
+ * (empty `matches`) paints nothing. `span` is absent only for a matcher that
+ * reports no position, which the caller falls back to finding by text.
+ */
+export declare function highlightTargets(matches: readonly Capture[], matchStart: number | undefined, captureSpans: readonly CaptureSpan[] | undefined, groupCount: number | undefined, wholeMatchSkipped?: readonly boolean[]): {
+    text: string;
+    span?: CaptureSpan;
+}[];
 /** 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. */
@@ -44,15 +82,69 @@ interface SameLineChain {
 }
 /** 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. */
+    /** The id to file it under, drawn by the caller from the profile's shared
+     *  sequence. The engine draws its own when absent. */
+    id?: number;
+    /** As exists()/killTrigger() and the runaway report know it. Mudlet uses
+     *  the trigger's id when the call carried no name of its own. */
     name?: string;
     onStopped?: () => void;
+    /** See TempEntryBase.onFree. */
+    onFree?: () => void;
+    /** See TempEntryBase.uncompiled. */
+    uncompiled?: boolean;
+    /** A further condition the line has to meet once the pattern matched —
+     *  a colour trigger's colour, which the engine cannot see. A line that
+     *  fails it is a line the trigger did NOT match, so a stay-open window
+     *  (keepFiring) still fires on it. */
+    accept?: () => boolean;
 }
+/**
+ * Why `pattern` will not compile, in the words of desktop's
+ * perlRegexCompileError (TLuaInterpreterMudletObjects.cpp) — `regex pattern
+ * "<p>" failed to compile at offset <n>: <reason>` — or null when it compiles.
+ * The creators (tempRegexTrigger, tempAlias, ...) refuse such a pattern rather
+ * than make an item that can never match. `forTrigger` drops the newlines
+ * first, as TTrigger::setRegexCodeList does before compiling (an alias keeps
+ * them). The offset is reported in UTF-8 bytes, as desktop's 8-bit PCRE2 does;
+ * the build here counts UTF-16 units past the prepended verbs. Null too while
+ * PCRE is still loading: nothing can be judged yet, and the engine reports a
+ * bad pattern once it compiles it.
+ */
+export declare function perlRegexCompileError(pattern: string, forTrigger: boolean): string | null;
+/**
+ * Why a perl pattern will not compile, as PCRE2 words it — or null when it
+ * does, or while PCRE is still loading and nothing can be said. Compiled as
+ * the engines compile triggers and aliases, `(*UTF)(*UCP)` included.
+ */
+export declare function perlPatternError(pattern: string): string | null;
+/** What is wrong with a colour pattern, in TTrigger::setRegexCodeList's two
+ *  cases: it asks for no colour at all, or for one no palette has. */
+export declare function colorPatternProblem(text: string): 'noColors' | 'noMatch' | null;
 export declare class TriggerEngine {
+    /** Every temporary trigger, by the id the script was handed — the
+     *  temporary half of desktop's one mTriggerMap. Insertion order is
+     *  creation order (Map), which is id order too. */
     private readonly temp;
-    /** Key for this engine's own temp map — see PatternEngine.nextInternalId. */
-    private nextInternalId;
+    /** The same entries by their tree key (`temp:<id>`). */
+    private readonly tempByKey;
+    /** Temp trigger ids, shared with every other engine in the profile — see
+     *  ItemIdSequence. A bare engine (unit tests) draws from its own. */
+    private idSeq;
+    setIdSequence(seq: ItemIdSequence): void;
+    /** The store's trigger list and blocked set as the last loadPerm was given
+     *  them, so a complex temp trigger can be compiled into the same tree
+     *  without the store being involved. */
+    private storeItems;
+    private storeBlocked;
+    /** Whether loadPerm has run (PCRE is ready by then): a complex temp trigger
+     *  made before it is compiled by that first load instead. */
+    private permLoaded;
+    /** Tree keys of freed temp triggers that had permanent children: the owner
+     *  of the store removes those subtrees (see takeOrphanedParents). */
+    private orphanedParents;
+    /** Called when a temp trigger with permanent children has been freed. */
+    private onOrphans;
     private inProcessTemp;
     private permCompiled;
     private allById;
@@ -76,21 +168,79 @@ export declare class TriggerEngine {
     private lastRunawayReportAt;
     private cache;
     private lineCounter;
-    private readonly chainOpenUntil;
+    /** What the line being walked has established so far — see PassState. A
+     *  nested pass (a trigger calling feedTriggers) has its own, and the outer
+     *  one's is put back when it returns. */
+    private pass;
     private hasChildren;
+    /**
+     * IDs whose OWN switch is on (and that can be active at all). An
+     * ancestor's state is not folded in: desktop checks each trigger's
+     * `isActive()` once, when its parent's `match()` reaches it, so a parent
+     * disabled by one of its children's scripts still hands the line to the
+     * rest of them (see PassState.active).
+     *
+     * Enabled-ness is checked on each node as the walk reaches it, rather than
+     * by leaving disabled triggers out of the processing list, so a trigger
+     * switched on by another trigger's script gets a look at the same line
+     * (mudlet-web#156). Filtering the list instead meant the enable was only
+     * visible from the NEXT line, because the pass walks a snapshot.
+     */
+    private selfEnabledIds;
+    /** What the last {@link loadPerm} was told cannot be active (code that will
+     *  not compile), so {@link updateEnabled} keeps them out too. */
+    private blocked;
+    /** Triggers with a pattern that failed to compile, as of the last loadPerm. */
+    private invalidPatterns;
     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. */
+    /** Triggers still firing on their own after completing (or after
+     *  setTriggerStayOpen), and how many more lines they do it for. See
+     *  applyFireLength. */
     private keepFiring;
+    /**
+     * The stay-open state a single-line match left its trigger in, to be put
+     * back once that match's script has run. Desktop runs a single-line
+     * trigger's script from inside the pattern test and only then assigns
+     * `mKeepFiring = mStayOpen` (src/TTrigger.cpp:995-999), so a trigger that
+     * calls setTriggerStayOpen on ITSELF has the call overwritten and does not
+     * keep firing; opening another trigger's window is unaffected. Mudlet Web
+     * does the bookkeeping before the script runs, so {@link execPerm} restores
+     * it afterwards (mudlet-web#238).
+     */
+    private readonly stayOpenAfterScript;
+    /** How many times {@link setStayOpen} has been called on each trigger —
+     *  desktop's `mStayOpenSetsByScript`. A script that sets its own trigger's
+     *  window while it runs has the last word over the fire length its match
+     *  would otherwise put back. */
+    private readonly stayOpenSets;
     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. */
+    /** Every offering a filter makes to its children this line — see openChain.
+     *  Empty means "matched, but there is nothing to hand down", which on
+     *  desktop keeps the children out of the line entirely. */
     private filterCaptures;
+    /** The line each filter's offering in {@link filterCaptures} was made for.
+     *  A filter only stands between its children and the line on the line it
+     *  MATCHED: when the chain is merely being held open by the fire length,
+     *  desktop reaches the children from the `mKeepFiring` branch of
+     *  `TTrigger::match` (src/TTrigger.cpp:1083-1093), which passes the
+     *  unfiltered haystack straight down. Without this the children kept
+     *  matching against a capture from an earlier line (mudlet-web#160). */
+    private filterOfferLine;
     private filterActiveOffset;
+    /** Filters whose offerings this line are in the line's current columns
+     *  rather than the ones it arrived with: a colour filter's, and any filter
+     *  under one (TTrigger::filter's positionsInCurrentColumns). */
+    private filterCurrentColumns;
     /** Resolves once PCRE wasm is initialized and patterns can be compiled. */
     static ready(): Promise<void>;
-    /** Number of live session-scoped temp triggers (Mudlet `getProfileStats` temp count). */
+    /** Temp triggers in the tree — killed ones too, until the deferred cleanup
+     *  frees them: desktop's getProfileStats walks the live root list
+     *  unfiltered (Host::assembleReport), so a killed trigger still counts
+     *  until doCleanup() deletes it. */
     get tempCount(): number;
+    /** Patterns the temp triggers carry, for getProfileStats' pattern tally: one
+     *  per simple temp trigger, a complex one's own list. */
+    get tempPatternCount(): number;
     /**
      * Register a temp trigger. `kind` selects the match strategy:
      *   - `'regex'`     — PCRE, same syntax as permanent triggers (Mudlet
@@ -109,22 +259,153 @@ export declare class TriggerEngine {
      *                     `tempExactMatchTrigger`). Callback receives `[line]`.
      *   - `'prompt'`    — fires on every line the server flags as a prompt
      *                     (Mudlet `tempPromptTrigger`); `pattern` is ignored.
-     *                     Callback receives `[line]`.
-     * Invalid regex patterns return a no-op disposer so callers don't need
-     * to special-case compile failures.
+     *                     Callback receives `[]` — match_prompt sets no
+     *                     capture groups.
+     *   - `'none'`      — never fires: the trigger an empty pattern makes once
+     *                     Mudlet has compacted the blank away.
+     * An invalid regex still makes the trigger — numbered, findable, killable —
+     * but one that never fires, as desktop leaves a trigger whose pattern
+     * failed to compile in place. Returns a disposer that removes it at once.
      */
-    addTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt', opts?: TempOptions): () => void;
+    addTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt' | 'none', opts?: TempOptions): () => void;
+    /** {@link addTemp}, handing back the trigger's id rather than a disposer. */
+    createTemp(pattern: string, fn: TempFn, kind?: 'regex' | 'substring' | 'startOfLine' | 'exactMatch' | 'prompt' | 'none', opts?: TempOptions): number;
     /**
      * Mudlet `tempLineTrigger(from, howMany, fn)`. A position-based trigger with
      * no pattern: it fires `fn([lineText])` on `howMany` consecutive lines,
-     * starting `from` lines ahead (`from = 1` → the next line). It self-expires
-     * after the last fire. When created from within a handler, the line on which
-     * it was created is skipped (see `inProcessTemp`/`skipFirst`) so `from`
-     * counts from the next line in every creation context. Returns a disposer
-     * for early cancellation.
+     * after skipping `from` of them (`from = 0` → the first line it sees). It
+     * self-expires after the last fire. Returns a disposer for early
+     * cancellation.
+     */
+    addTempLine(from: number, howMany: number, fn: TempFn, opts?: TempOptions): () => void;
+    /** {@link addTempLine}, handing back the trigger's id. */
+    createTempLine(from: number, howMany: number, fn: TempFn, opts?: TempOptions): number;
+    /**
+     * Mudlet `tempComplexRegexTrigger`: a temporary trigger with everything a
+     * permanent one can have — an AND chain across lines, a filter, a fire
+     * length, a line delta, colour patterns, a highlight. It is compiled and
+     * walked exactly like a permanent trigger, from a node the engine holds
+     * itself rather than one in the store, and fires through the same `exec`
+     * the permanent ones do (its `code` is the caller's dispatch stub).
+     * `node.id` and `parentId` are the engine's to set.
+     */
+    createTempComplex(node: Omit<TriggerNode, 'id' | 'parentId' | 'enabled'>, opts?: TempOptions): number;
+    private tempBase;
+    private insertTemp;
+    /** Rebuild the compiled tree from the store's last list plus the complex
+     *  temp triggers — after one of those came or went. */
+    private recompile;
+    /**
+     * Take a temp trigger out of the tree now. Its permanent children, if it
+     * has any, are left orphaned in the store for its owner to remove (see
+     * {@link takeOrphanedParents}); until then nothing reaches them.
+     */
+    removeTemp(id: number): void;
+    private release;
+    /**
+     * Mudlet `killTrigger` on a temp trigger: it stops firing at once — for the
+     * rest of the line being walked too — and is queued for the deferred
+     * cleanup (TriggerUnit::markCleanup), which frees it with its whole subtree.
+     * False for an unknown id or one already waiting to be freed.
+     */
+    killTemp(id: number): boolean;
+    /** Mudlet `killTrigger(name)` for the temporaries: the newest live temp
+     *  trigger carrying the name (TriggerUnit::killTrigger walks the lookup
+     *  table, newest first, skipping permanent items and corpses). */
+    killTempByName(name: string): boolean;
+    /**
+     * Free every temp trigger killed since the last call — desktop's
+     * TriggerUnit::doCleanup, which runs once no line is being processed.
+     * The engine runs it itself as the outermost pass ends; the owner runs it
+     * at the other points desktop does (after a batch, after a timer).
+     */
+    reapKilled(): void;
+    /** The tree keys of freed temp triggers that had permanent children, since
+     *  the last call. Their owner removes those subtrees from the store, as
+     *  desktop's ~TTrigger deletes its children with it. */
+    takeOrphanedParents(): string[];
+    /** Told when {@link takeOrphanedParents} has something to hand over. */
+    setOrphanListener(fn: (() => void) | null): void;
+    /** Whether a temp trigger with this id is in the tree, killed or not. */
+    hasTemp(id: number): boolean;
+    /** Whether a temp trigger with this id is in the tree and not killed — what
+     *  exists() counts (TriggerUnit::pendingDeletion). */
+    hasLiveTemp(id: number): boolean;
+    /** Whether a live temp trigger is switched on and able to fire — isActive(). */
+    tempIsActive(id: number): boolean;
+    /** A live temp trigger's name, or null. */
+    tempName(id: number): string | null;
+    /** A temp trigger's patterns (its node's), or null for an unknown id. */
+    tempPatterns(id: number): TriggerPattern[] | null;
+    /** Live temp trigger ids, ascending, whose name passes `test`. */
+    liveTempIds(test: (name: string) => boolean): number[];
+    /**
+     * The newest temp trigger carrying `name` — desktop's findTrigger, a
+     * QMultiMap lookup whose newest entry comes first. `includeDead` keeps one
+     * waiting for cleanup in the running, as findTrigger does (perm* parent
+     * resolution); killTrigger and friends skip it.
+     */
+    newestTempByName(name: string, includeDead: boolean): number | null;
+    /** enableTrigger/disableTrigger on a temp trigger by id. False for an
+     *  unknown id or a killed one — re-enabling a corpse would resurrect it. */
+    setTempEnabled(id: number, enabled: boolean): boolean;
+    /** Whether the temp trigger behind a tree key can let a line through: in
+     *  the tree, not killed, switched on, compiled. False for a freed one. */
+    private tempKeyActive;
+    /** `isActive()` of a tree node as the walk reads it: a temp trigger's own
+     *  state, or a permanent trigger's switch (see selfEnabledIds). */
+    private isSelfEnabled;
+    /**
+     * Give the profile's saved triggers their place in the firing order without
+     * compiling them. Desktop builds every permanent trigger from the profile
+     * XML before any script runs, so a temp trigger a script creates at load
+     * time sorts after them. Triggers can't be compiled here until PCRE is
+     * ready — which is after the scripts have run — so the engine calls this
+     * first and the later {@link loadPerm} reuses the seqs reserved here.
      */
-    addTempLine(from: number, howMany: number, fn: TempFn): () => void;
-    loadPerm(items: TriggerNode[]): void;
+    reserveOrder(items: readonly {
+        id: string;
+    }[]): void;
+    /**
+     * Mudlet `TriggerUnit::reorderTriggersAfterPackageImport`, which
+     * `Host::installPackage` runs after every install: every temporary root
+     * trigger is moved to the end of the root list, keeping its order among
+     * the temporaries, so the permanent ones — the profile's own and the
+     * package's — fire ahead of them all. `items` is the permanent tree as the
+     * install left it, so the package's new triggers take their place before
+     * the temporaries are moved behind them.
+     */
+    reorderAfterPackageImport(items: TriggerNode[]): void;
+    /**
+     * `blocked`: triggers whose code (or a Lua-function pattern) will not
+     * compile. Those and every trigger with a pattern PCRE rejects are
+     * inactive, as desktop's `Tree::isActive` wants `state()` — they never
+     * match, so their children are never looked at either.
+     */
+    loadPerm(storeItems: TriggerNode[], blocked?: ReadonlySet<string>): void;
+    /** Whether a line is being walked right now. `updateEnabled` is only worth
+     *  its cost inside one — outside, the store's own coalesced reload lands
+     *  before the next line arrives. */
+    get isProcessing(): boolean;
+    /**
+     * Refresh which triggers count as enabled, without recompiling anything.
+     *
+     * `enableTrigger`/`disableTrigger` write to the store, and the reload that
+     * carries the change into the engine is coalesced onto a microtask — which
+     * lands after the line that called it has finished. Desktop reads the flag
+     * live inside its tree walk, so a trigger enabled by another trigger's
+     * script fires on the SAME line (mudlet-web#156). This is that read: the
+     * caller hands over the current node list the moment it changes the flag,
+     * and the pass in flight sees it when it reaches the node. loadPerm
+     * recomputes the same set from scratch a moment later.
+     */
+    updateEnabled(items: TriggerNode[]): void;
+    /** Triggers whose own switch is on and that can be active at all — see
+     *  {@link selfEnabledIds}. */
+    private buildEnabledIds;
+    /** Whether the permanent trigger `id` has a pattern that failed to compile
+     *  and so cannot be active. */
+    hasInvalidPattern(id: string): boolean;
     /** Fresh compile for an item not present in the cache. Returns a CachedEntry
      * with `compiled: null` when no patterns produced a usable matcher — that
      * negative result is cached so we don't retry on every loadPerm. */
@@ -139,6 +420,9 @@ export declare class TriggerEngine {
      *  triggers delete themselves (and dirty the unified order) when spent. */
     private fireTempEntry;
     private fireTempEntryInner;
+    /** The match half of {@link fireTempEntryInner}: true when the pattern
+     *  matched and the callback has already run. */
+    private fireTempEntryMatch;
     matchPerm(line: string, isPrompt?: boolean): TriggerMatch[];
     /**
      * Match one permanent compiled entry against `line`, appending any matches
@@ -147,9 +431,34 @@ 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;
+    /**
+     * The filter ancestor whose offering `item` matches against on this line:
+     * the innermost one that MATCHED it. A filter merely holding the chain open
+     * with its fire length is passed over — desktop reaches its children from
+     * the `mKeepFiring` branch of `TTrigger::match` (src/TTrigger.cpp:1090-1093),
+     * which hands them the haystack it was itself given, so what they see is the
+     * next filter further out or, failing that, the whole line (mudlet-web#160).
+     */
+    private activeFilterId;
     private matchPermEntryOnce;
+    /**
+     * Mudlet's `mKeepFiring`: a fire length ("Keep firing the script for this
+     * many more lines, after the trigger or chain has matched") keeps a trigger
+     * going once it has matched.
+     *
+     * Desktop arms it from BOTH arms of `TTrigger::match` — the single-line
+     * branch at `src/TTrigger.cpp:995-999`
+     * (`if (!mIsMultiline) { if (ret) { conditionMet = true; mKeepFiring =
+     * mStayOpen; break; } }`) and the multiline completion at
+     * `src/TTrigger.cpp:1016` — and spends it one line at a time at
+     * `src/TTrigger.cpp:1083-1090`, where only a childless trigger re-runs its
+     * own script; one with children is holding the chain open FOR them.
+     *
+     * Mudlet Web used to arm it only in the AND branch, so fire length was inert on
+     * single-line (OR) triggers even though the editor offers the field in both
+     * modes (mudlet-web#61). Sharing the bookkeeping here keeps the two in step.
+     */
+    private applyFireLength;
     /**
      * Mudlet-faithful single pass: walk the one ordered list of permanent and
      * temporary triggers (see the ordering notes on the fields) and, for each
@@ -179,7 +488,10 @@ export declare class TriggerEngine {
      * 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;
+    notePermCreated(node: TriggerNode): void;
+    /** The lineage recorded against a root: a temp trigger's own, or the one
+     *  a permanent root was given as something under it was created. */
+    private lineageOfRoot;
     /** Join the lineage of the trigger whose script is running, a generation on;
      *  or start one when that script predates the line. */
     private nextSameLineChain;
@@ -211,14 +523,38 @@ export declare class TriggerEngine {
     /** 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;
+    /** Paints a trigger's built-in highlight. See {@link setHighlighter}. */
+    private highlighter;
+    /**
+     * How a multiline (AND) trigger's highlight is painted. Desktop paints it
+     * per CONDITION, on the line each pattern matches and at the moment it
+     * matches (the `mIsColorizerTrigger` block every match_* runs before
+     * `updateMultistates`), whether or not the state ever completes — the
+     * completed fire carries no single match to paint, which is why Mudlet Web
+     * painted nothing. ScriptingEngine wires this to the same painter the
+     * single-line path uses; the match handed over is the condition's own.
+     */
+    setHighlighter(fn: ((match: TriggerMatch) => void) | null): void;
     /** How the engine switches off a permanent trigger it stopped. */
     setPermDisabler(fn: ((nodeId: string) => void) | null): void;
+    /**
+     * Where a pattern that failed to compile is reported. ScriptingEngine wires
+     * this to the error log (the Errors tab), tagged with the owning trigger so
+     * the row gets a jump-to-source button; unset (tests, teardown) the report
+     * is dropped. `source` is absent for temporary triggers, which have no node.
+     */
+    setCompileErrorReporter(fn: ((message: string, source?: {
+        id: string;
+        name: 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. */
     private rebuildOrder;
     /** The registration-seq path from the root ancestor down to `item`. */
     private permPath;
+    /** A node's registration seq: a temp trigger's own, or a permanent one's. */
+    private seqOf;
     setLuaEval(fn: ((code: string, line: string) => boolean) | null): void;
     /**
      * Wire the buffer-aware colour check used by `colorTrigger` patterns. The
@@ -231,7 +567,13 @@ export declare class TriggerEngine {
     setColorMatcher(fn: ((fg: number, bg: number, window: {
         start: number;
         length: number;
-    } | null) => boolean) | null): void;
+    } | null) => {
+        text: string;
+        start: number;
+    }[]) | null): void;
+    /** Wire how a stretch of the line in its arrived columns is found where it
+     *  is now — see {@link spanNowRef}. */
+    setSpanMapper(fn: ((span: CaptureSpan) => CaptureSpan) | null): void;
     destroy(): void;
     /**
      * Advance every state an AND trigger has in flight against this line, and
@@ -243,41 +585,95 @@ export declare class TriggerEngine {
      * state let the newer one overwrite the older, so only one ever fired.
      */
     private processAndTrigger;
+    /** What condition `i` of an AND trigger makes of the line being processed:
+     *  tested once per line while {@link processAndTrigger} holds the cache. */
+    private andTest;
+    /**
+     * Desktop's per-line pattern loop for a multiline trigger, run only to
+     * decide what its highlight paints (TTrigger::match, multiline branch):
+     * patterns are tried in order, and the walk stops at the first one that
+     * fails once it is past the furthest condition any state is waiting on.
+     * Every pattern that matches on the way is painted then and there — on its
+     * own line, before any script, whether or not a state needs it or ever
+     * completes. A line spacer counts as a match (match_line_spacer returns
+     * true). `highest` is each state's TMatchState::nextCondition, which for a
+     * state still counting down a spacer is the spacer itself.
+     */
+    private paintAndConditions;
+    private advanceAndTrigger;
     /** 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;
+    /** A line spacer holds a `multimatches` row of its own, as every other
+     *  condition does, so the rows after it keep the index of the pattern they
+     *  belong to. The row is EMPTY — TTrigger::match_line_spacer pushes an
+     *  empty capture list — not one holding an empty string. */
+    private pushSpacerRow;
     /** 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
-     * descendants see it as their effective input.
+     * Record a chain-head match: let this line through to its children (the
+     * fire length keeps it open on later ones — see applyFireLength) and, if
+     * the trigger is also a filter, work out what it offers its children on
+     * this line and stash that as their effective input.
      */
     private openChain;
     /**
-     * Mudlet `setTriggerStayOpen(name, lines)`: keep the named chain head(s)
-     * open for `lines` more lines of input, starting from the line currently
-     * being processed. This is transient runtime state — it mutates only the
-     * `chainOpenUntil` window, never the persisted `fireLength` on the node, so
-     * the trigger's stored definition is untouched and the override expires
-     * naturally as input scrolls past.
+     * Mudlet `setTriggerStayOpen(name, lines)`: keep the named trigger(s) open
+     * for `lines` more lines of input, starting from the line currently being
+     * processed. This is transient runtime state — it mutates only the runtime
+     * windows, never the persisted `fireLength` on the node, so the trigger's
+     * stored definition is untouched and the override expires naturally as
+     * input scrolls past.
      *
-     * `matchPerm` post-increments `lineCounter`, so during a trigger's script
-     * the line just matched is `lineCounter - 1`; the window math then mirrors
-     * `openChain` exactly. Negative counts clamp to 0 (open for the current
-     * line only). `ids` are resolved by name by the caller.
+     * Desktop writes one counter, `mKeepFiring`, and it does two jobs at once
+     * (src/TriggerUnit.cpp:455, spent at src/TTrigger.cpp:1083-1093): the
+     * trigger FIRES on each of those lines whether or not its pattern is in
+     * them, and its children get a look at them. Mudlet Web keeps the same
+     * single counter (`keepFiring`, spent in applyFireLength), so both jobs
+     * share one span. Arming only the chain left a stay-open trigger silent
+     * on the lines it was opened for (upstream Trigger_spec, "large plain-text
+     * trigger sets").
+     *
+     * The count is spent on the lines the trigger is next reached on. When
+     * the call comes from the script of a trigger walked BEFORE the target on
+     * this line, that includes this line: desktop decrements `mKeepFiring` as
+     * soon as the walk reaches the target, so `setTriggerStayOpen(t, 2)` covers
+     * this line and the next — not this line and two more (mudlet-web#262).
+     * When the target has already been walked past (it sorts earlier, or the
+     * call came from outside a pass), the window is the next `lines` lines.
+     *
+     * Negative counts clamp to 0, which closes the window. `ids` are resolved
+     * by name by the caller.
      */
     setStayOpen(ids: string[], lines: number): void;
     /**
-     * Returns the effective line to match against for `item`.
-     * If a filter-trigger ancestor has active filter text, that text is used instead.
-     * Innermost filter wins.
+     * Mudlet `setTriggerStayOpen(name, lines)` for a TEMPORARY trigger, which is
+     * addressed by the string form of its id — startTempTrigger names every temp
+     * after its own id, and setTriggerStayOpen searches the same name table the
+     * permanent ones live in. Returns whether anything answered to the name.
+     *
+     * The counter it sets is `mKeepFiring`: the trigger fires on that many more
+     * lines whether or not its pattern is in them. That is a different thing
+     * from the chain window {@link setStayOpen} writes, which only decides
+     * whether a trigger's CHILDREN get a look at the line.
+     */
+    setTempStayOpen(name: string, lines: number): boolean;
+    /**
+     * The line `item` matches against: the offering of the innermost filter
+     * ancestor that matched THIS line, or the whole line when no filter is
+     * standing in front of it. See activeFilterId.
      */
     private getEffectiveLine;
+    /** Whether `item` is offered a filter's capture in the line's current
+     *  columns this line — see {@link filterCurrentColumns}. */
+    private inCurrentColumns;
+    /** See {@link spanNowRef}. */
+    private spanNow;
     /** The offset within the ORIGINAL line at which `item`'s effective (filtered)
-     *  input begins — 0 unless it sits under a filter ancestor. Mirrors
-     *  getEffectiveLine: the innermost filter ancestor's recorded offset. */
+     *  input begins — 0 unless a filter ancestor is standing in front of it on
+     *  this line. Mirrors getEffectiveLine. */
     private getEffectiveOffset;
     /** Return a copy of `r` with every span (matchStart, captureSpans, namedSpans)
      *  shifted by `offset` — used to re-base a filtered descendant's spans onto
@@ -285,12 +681,18 @@ export declare class TriggerEngine {
      *  Zero-length (unmatched-group) placeholders keep length 0. */
     private shiftResultSpans;
     /**
-     * A trigger is chain-accessible if every patterned ancestor has an open
-     * chain (matched within the last fireLength lines, inclusive of the current
-     * line). Pattern-less ancestors (pure folders) always grant access. This
+     * Whether desktop's recursive walk would hand `item` this line at all: every
+     * ancestor was active when the walk reached it, and every patterned one let
+     * the line through (it matched, or is spending its fire length on it).
+     * Pattern-less ancestors (pure folders) let every line through. This
      * applies regardless of whether the ancestor is a folder or a leaf with its
      * own script — Mudlet treats any patterned trigger with children as a chain
      * head.
+     *
+     * Both facts come from {@link PassState}, as the walk recorded them on its
+     * way past the ancestor, not from the ancestor's state now: a script that
+     * disables its own chain head or folder leaves the remaining children with
+     * the line, as desktop's children loop is already under way.
      */
     private isChainAccessible;
     private computeDepth;