@mudlet/mudlet-web 0.5.0 → 1.0.0

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

@@ -1,9 +1,21 @@
 import { ItemIdSequence } from '../ItemIdSequence';
 import type { TimerNode } from '../../storage/schema';
+import { type Clock } from './workerClock';
 export type { TimerNode };
 type TempFn = () => void;
 type ExecuteFn = (timer: TimerNode) => void;
+/** A permanent timer list indexed the ways the engine walks it. */
+interface PermTree {
+    timers: TimerNode[];
+    byId: Map<string, TimerNode>;
+    children: Map<string, TimerNode[]>;
+    /** Ids switched on along with every ancestor (canBeUnlocked). */
+    enabledIds: Set<string>;
+    /** A timer nested under another *timer* rather than a folder (TTimer.h). */
+    isOffset: (t: TimerNode) => boolean;
+}
 export declare class TimerEngine {
+    private readonly clock;
     private readonly temp;
     /** Permanent timers keyed by stored TimerNode id (uuid). Two timers can
      *  share a name; we keep id as the canonical handle and build a separate
@@ -18,11 +30,30 @@ export declare class TimerEngine {
     private readonly knownPermNames;
     /** Shared with every other engine in the profile — see ItemIdSequence. */
     private idSeq;
+    /** Temp timer bodies on the stack (a body can pump others via waitForEvent).
+     *  Killed timers are reaped when the outermost one returns — TimerUnit's
+     *  mProcessingDepth / doCleanup. */
+    private firingDepth;
     setIdSequence(seq: ItemIdSequence): void;
+    /** Every timeout is armed on `clock`, which keeps time in a worker so a
+     *  hidden tab doesn't throttle the timers (see workerClock). */
+    constructor(clock?: Clock);
     /** 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;
+    /**
+     * After a repeating timer's body returns: if the body ran so long that the
+     * tick armed before it is already due, push that tick a full interval past
+     * now. Desktop's next tick comes at least one interval after a slow body
+     * returns (mudlet-web#293: a 0.2s timer whose body takes 0.5s fires at 0.2
+     * then 0.9, not 0.7), so a late tick must not fire the moment the body
+     * ends. Only the timer's *own* slow body does this — a tick held up by
+     * some other timer's body is re-armed from when it actually fired, which
+     * already is "now". The entry is looked up afresh: a body that killed,
+     * disabled or re-armed its own timer left nothing overdue to move.
+     */
+    private rearmIfOverdue;
     /**
      * Fire every timer that has come due, without waiting for the event loop to
      * deliver its setTimeout.
@@ -35,31 +66,55 @@ export declare class TimerEngine {
      *
      * 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
+     * a repeat is a self-rescheduling setTimeout (see addTemp, startPerm): 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.
+     * Whether a temporary timer with this id is still present — killed or not.
+     * Temp timers aren't in the store: this map is the temporary half of the
+     * one timer tree (exists() asks {@link hasLiveTemp}, which skips a killed
+     * one).
      *
-     * 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}.
+     * Present is not running: a killed timer stays here until the reap, and a
+     * disabled one until it is killed — 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;
+    /**
+     * Mudlet `enableTimer(id)` / `disableTimer(id)` on a temporary timer. Mudlet
+     * names a temp timer by the id tempTimer returned, so its name-based toggles
+     * reach temp timers too. Disabling stops the pending tick; enabling re-arms
+     * it for a full interval, as Mudlet restarts the QTimer. Returns false for
+     * an unknown or killed timer.
+     */
+    setTempEnabled(id: number, enabled: boolean): 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. */
+     *  batch and after each outermost temp timer body, mirroring the deferred
+     *  cleanup Mudlet's TimerUnit does (Host::incomingStreamProcessor and
+     *  TimerUnit::timerFired). */
     reapKilled(): void;
+    /** Temp parent refs some permanent timer hangs off, as of the last loadPerm. */
+    private tempParentRefs;
+    private orphanedParents;
+    private onOrphans;
+    /** Tree keys of freed temp timers that had permanent children, since the
+     *  last call. Their owner removes those subtrees from the store. */
+    takeOrphanedParents(): string[];
+    /** Told when {@link takeOrphanedParents} has something to hand over. */
+    setOrphanListener(fn: (() => void) | null): void;
+    /** Live temp timer ids, ascending, whose name — the id itself — passes `test`. */
+    liveTempIds(test: (name: string) => boolean): number[];
+    /** Whether a temp timer is present and not killed — what exists() counts. */
+    hasLiveTemp(id: number): boolean;
+    /** The executeFn the last loadPerm was given, for a timer started from
+     *  outside it (an offset timer under a temporary parent, see switchOne). */
+    private executeFn;
     /**
      * Cached previous load. `nodes` is the TimerNode keyed by id, `desc` is the
      * shape that determines whether the running setTimeout/setInterval is still
@@ -70,7 +125,104 @@ export declare class TimerEngine {
      */
     private readonly prevDesc;
     private descOf;
-    loadPerm(timers: TimerNode[], executeFn: ExecuteFn): void;
+    /**
+     * Offset timers keyed by the id of the timer they hang off. In Mudlet a
+     * timer nested under another *timer* (not a folder) is an offset timer
+     * purely by where it sits (TTimer.h:75-84): it never runs on its own clock
+     * and is skipped by the normal start walk (TTimer.cpp:314, :329). Each time
+     * its parent fires it is started once, due its own interval later
+     * (TTimer.cpp:255-265). Rebuilt on every {@link loadPerm}; only holds
+     * children that are effectively enabled.
+     */
+    private readonly offsetChildren;
+    /**
+     * Permanent timers whose *runtime* active flag is up — TTimer's `mActive`
+     * (Tree.h), kept apart from the user's switch (`enabled`, Mudlet's
+     * `mUserActiveState`). The two disagree in exactly the cases `isActive`
+     * can see: a timer imported enabled under a disabled folder is left
+     * inactive, while an explicit `enableTimer()` on it raises the flag even
+     * though a disabled ancestor keeps it from running. Only non-offset timers
+     * are tracked; Mudlet reports an offset timer by its switch alone.
+     * See {@link applyPermSwitch} for the transitions and {@link loadPerm} for
+     * how the flag is seeded.
+     */
+    private readonly activePerm;
+    /** Each permanent timer's switch and parent as of the last
+     *  {@link loadPerm}, so the next one can tell a switch flipped behind the
+     *  engine's back (the editor) from one that never moved. */
+    private readonly seenPerm;
+    /**
+     * Permanent timers whose code will not compile. Mudlet's `activate()`
+     * refuses them (`Tree::canBeActivated` wants `state()`), so such a timer
+     * neither runs nor reports active, whatever its switch says, and never
+     * fires to arm its offset children. Unlike a trigger's, the gate is the
+     * timer's own: a folder's other timers run on their own clocks, and
+     * `canBeUnlocked` asks only the ancestors' switches.
+     */
+    private broken;
+    loadPerm(timers: TimerNode[], executeFn: ExecuteFn, broken?: ReadonlySet<string>): void;
+    /**
+     * Raise the runtime active flags of a profile's permanent timers as its
+     * load leaves them, without arming anything yet. Desktop builds and
+     * activates the timers from the profile XML before any script compiles,
+     * so a script body that runs at load already sees them active, and an
+     * enableTimer/disableTimer it calls is a transition from that state rather
+     * than from "never seen" — which left every other timer reporting inactive
+     * for good. {@link loadPerm} arms them afterwards.
+     */
+    seedPerm(timers: TimerNode[]): void;
+    /**
+     * Bring the runtime active flags in line with a new node list.
+     *
+     * - A timer seen for the first time is set as Mudlet's loader leaves it:
+     *   XMLimport::readTimer only activates a root that is switched on, and
+     *   TTimer::enableTimer(int) carries that down through folders to each
+     *   child whose whole ancestry is switched on (canBeUnlocked). So it is
+     *   active exactly when effectively enabled. A flag an explicit
+     *   {@link applyPermSwitch} raised before this first sight is kept, as
+     *   long as the timer is still switched on.
+     * - A timer that moved to another parent is re-seeded the same way,
+     *   strictly: TimerUnit::reParentTimer disables it and re-enables it by id,
+     *   which only activates it if it can be unlocked where it now sits.
+     * - A timer whose switch flipped without going through enable/disableTimer
+     *   (the editor's checkbox) gets the same transition those would apply.
+     */
+    private reconcileActive;
+    /**
+     * Mudlet `enableTimer(name)` / `disableTimer(name)` on permanent timers, as
+     * far as the runtime active flag goes (TimerUnit::enableTimer/disableTimer).
+     * `timers` is the node list *after* the switches were written. Applied even
+     * when a switch did not move: enabling an already switched-on timer under a
+     * disabled folder still raises its flag, and disabling an already
+     * switched-off folder still lowers the flags beneath it.
+     */
+    applyPermSwitch(ids: readonly string[], on: boolean, timers: TimerNode[]): void;
+    private switchOne;
+    /**
+     * What Mudlet's `isActive(name, "timer" [, checkAncestors])` reports for a
+     * permanent timer: an offset timer by its switch (shouldBeActive), any
+     * other by its runtime flag (TTimer::isActive). With `checkAncestors`, every
+     * ancestor has to report active by the same rule (shouldAncestorsBeActive).
+     */
+    permReportsActive(node: TimerNode, timers: TimerNode[], checkAncestors?: boolean): boolean;
+    /** Mudlet `isAncestorsActive(id, "timer")`: every ancestor reports active,
+     *  by the rule {@link permReportsActive} uses. */
+    permAncestorsActive(node: TimerNode, timers: TimerNode[], tree?: PermTree): boolean;
+    /** How many non-folder permanent timers report active — the timer half of
+     *  getProfileStats' active count, by the rule {@link permReportsActive} uses. */
+    countPermActive(timers: TimerNode[]): number;
+    private reportsActive;
+    /** Start a permanent offset timer once, as enabling it does — see
+     *  switchOne. Not while it or an ancestor is switched off, or a temporary
+     *  parent is killed (canBeUnlocked asks the parents too), and not one
+     *  without a script: TTimer::enableTimer keeps a command-only offset timer
+     *  to its parent's firing, which would otherwise give it a schedule of its
+     *  own. */
+    private startOffsetOnce;
+    /** (Re)start every enabled offset timer hanging off `parentId`, each due
+     *  its own interval from now. A child still pending from the previous
+     *  parent tick is restarted, as QTimer::start does on a running timer. */
+    private armOffsetChildren;
     private startPerm;
     private killPermHandle;
     /**

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

@@ -0,0 +1,67 @@
+/**
+ * A setTimeout/clearTimeout pair whose clock runs in a dedicated Worker.
+ *
+ * Chrome throttles main-thread timer chains in a hidden tab — to one wake-up a
+ * second at once, and after five minutes hidden to one a *minute* (intensive
+ * throttling). Every Lua timer is such a chain (a repeat re-arms itself from
+ * its own callback, see TimerEngine.addTemp), so a background tab ran a 1s
+ * repeat once a minute while desktop Mudlet keeps exact time (mudlet-web#441).
+ * Dedicated-worker timers are exempt from both, so the worker keeps the time
+ * and posts each due id back; the callback itself still runs on the main
+ * thread, where Lua lives. Message delivery to a hidden page isn't throttled.
+ *
+ * Ordering is the same as plain setTimeout: the worker receives sets in the
+ * order they were made, and its timers fire — and post — in due order.
+ *
+ * The worker is an inline Blob, not a `new URL('./x.worker.ts', import.meta.url)`
+ * chunk: a dozen lines need no bundling, and a Blob works the same in the app
+ * build, the library build and a consumer's bundler. Where there is no Worker
+ * (tests, happy-dom, node) or one can't be started (a CSP without `worker-src
+ * blob:`), the clock falls back to the global setTimeout — looked up at each
+ * call, so vitest's fake timers still drive it.
+ */
+export type ClockHandle = number;
+export interface Clock {
+    setTimeout(fn: () => void, ms: number): ClockHandle;
+    clearTimeout(handle: ClockHandle | null | undefined): void;
+}
+/** The minimal Worker surface the clock uses — what tests fake. */
+export interface ClockWorker {
+    postMessage(msg: ClockWorkerRequest): void;
+    addEventListener(type: 'message', fn: (e: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'error', fn: () => void): void;
+    terminate(): void;
+}
+export type ClockWorkerRequest = {
+    op: 'set';
+    id: number;
+    ms: number;
+} | {
+    op: 'clear';
+    id: number;
+};
+/** Start the inline clock worker, or null where workers aren't available. */
+export declare function createBlobClockWorker(): ClockWorker | null;
+export declare class WorkerClock implements Clock {
+    private readonly createWorker;
+    /** undefined until first use; null once it is known there is none. */
+    private worker;
+    private nextId;
+    private readonly pending;
+    constructor(createWorker?: () => ClockWorker | null);
+    setTimeout(fn: () => void, ms: number): ClockHandle;
+    clearTimeout(handle: ClockHandle | null | undefined): void;
+    /** Whether the clock is running on a worker (false before first use). */
+    get usingWorker(): boolean;
+    private ensureWorker;
+    private onTick;
+    /** The worker failed to start (a CSP blocking blob: workers reports it this
+     *  way): move every timeout it held onto the main thread, keeping its due
+     *  time, and use the main thread from now on. */
+    private fallBack;
+    private armNative;
+}
+/** The clock every Lua timer and the line assembler's idle flushes share. */
+export declare const workerClock: Clock;