@moku-labs/game 0.9.0 → 0.11.0

package/dist/{types-B0v5VVa3.d.mts → types-ZQLYXo5X.d.mts}

@@ -71,211 +71,243 @@ type Require = <Plugin extends {
   };
 }>(plugin: Plugin) => ApiOf<Plugin>;
 declare namespace types_d_exports$7 {
-  export { Api$7 as Api, ClockCtx, ClockSource, Config$7 as Config, Elapsed, FakeClock, State$7 as State };
+  export { Api$7 as Api, Config$7 as Config, FrameCallback, Phase, State$7 as State, Time, TimeCtx };
 }
 /**
- * Source of time and timers. The system source is the default; a game passes its own when time
- * must come from somewhere else, for example a server.
+ * Frame phases, in call order.
  *
  * @example
  * ```ts
- * // Server time: the device clock only measures the distance from the last sync. The plugin keeps
- * // at most one timer alive, so the source remembers one.
- * const serverClock = (serverNow: number): ClockSource => {
- *   const syncedAt = performance.now();
- *   let timer: ReturnType<typeof setTimeout> | undefined;
- *
- *   return {
- *     now: () => serverNow + (performance.now() - syncedAt),
- *     setTimer: (callback, delayMs) => (timer = setTimeout(callback, delayMs)),
- *     clearTimer: () => clearTimeout(timer)
- *   };
- * };
- *
- * createApp({ pluginConfigs: { clock: { source: serverClock(1_790_000_000_000) } } });
+ * const phase: Phase = "animate";
  * ```
  */
-type ClockSource = {
-  /**
-   * Reads the current moment.
-   *
-   * @returns Epoch milliseconds. A fraction is cut by the plugin; going back is tolerated.
-   */
-  now(): number;
-  /**
-   * Schedules one callback. The plugin keeps at most one timer alive.
-   *
-   * @param callback - Function to run when the delay has passed.
-   * @param delayMs - Delay in milliseconds, never negative.
-   * @returns A handle of any shape; the plugin only hands it back to `clearTimer`.
-   */
-  setTimer(callback: () => void, delayMs: number): unknown;
-  /**
-   * Cancels a pending timer. A handle this source did not produce must be ignored.
-   *
-   * @param handle - Handle returned by `setTimer`.
-   */
-  clearTimer(handle: unknown): void;
-};
+type Phase = "input" | "animate" | "layout" | "sync" | "signals" | "render";
 /**
- * Fake source for tests, from `@moku-labs/game/testing`. It needs no real timer.
+ * The Time resource, in scaled milliseconds. `idle` tells whether the loop currently runs at the
+ * lowered idle cap.
  *
  * @example
  * ```ts
- * // An energy point refills after 60 s. The test does not wait: it moves the clock.
- * const clock = fakeClock(1000);
- * const app = createApp({ pluginConfigs: { clock: { source: clock } } });
- *
- * app.clock.scheduleAt(61_000);
- * clock.advance(60_000); // the listeners of onElapsed get { now: 61000 }
+ * const time: Time = { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false };
  * ```
  */
-type FakeClock = ClockSource & {
-  /**
-   * Moves the clock forward and fires every timer that falls due on the way, in due order.
-   *
-   * @param ms - Milliseconds to move forward. A negative amount moves nothing.
-   * @example
-   * ```ts
-   * clock.advance(5000); // now() is 5000 later, a timer due in 3000 has fired
-   * ```
-   */
-  advance(ms: number): void;
-  /**
-   * Jumps to a moment without firing any timer. Moving back is allowed: that is a player who
-   * sets the device clock by hand.
-   *
-   * @param moment - Moment in epoch milliseconds.
-   * @example
-   * ```ts
-   * clock.set(400); // the device clock went back; app.clock.now() does not decrease
-   * ```
-   */
-  set(moment: number): void;
+type Time = {
+  delta: number;
+  elapsed: number;
+  scale: number;
+  frame: number;
+  idle: boolean;
 };
 /**
- * Input delivered to `onElapsed` listeners when a due moment arrives or the game resumes.
+ * Callback run once per frame in its phase.
  *
  * @example
  * ```ts
- * const input: Elapsed = { now: 1_790_000_060_000 };
+ * const advanceTweens: FrameCallback = time => tweens.advance(time.delta);
  * ```
  */
-type Elapsed = {
-  now: number;
-};
+type FrameCallback = (time: Readonly<Time>) => void;
 /**
- * clock plugin config.
+ * time plugin config.
  *
  * @example
  * ```ts
- * createApp({ pluginConfigs: { clock: { source: fakeClock(1000) } } });
+ * createApp({ pluginConfigs: { time: { maxFps: 30 } } });
  * ```
  */
 type Config$7 = {
   /**
-   * Time source. `undefined` means the system source: `Date.now` and `setTimeout`.
+   * Frame rate cap. The default is 60. 120 is for WebViews that really deliver 120 Hz frames:
+   * Android today; WKWebView on iOS and macOS is capped at 60 by WebKit (bug 294338).
    */
-  source: ClockSource | undefined;
+  maxFps: 30 | 60 | 120;
+  /**
+   * Upper bound of one frame's delta in milliseconds.
+   */
+  maxDeltaMs: number;
+  /**
+   * Frame rate cap of an idle screen, when nothing woke the clock for `idleAfterMs`. The default
+   * is 30; 0 turns the idle cap off and every frame runs at `maxFps`.
+   */
+  idleFps: 0 | 30;
+  /**
+   * Unscaled milliseconds without a `wake()` after which the loop drops to `idleFps`.
+   */
+  idleAfterMs: number;
 };
 /**
- * clock plugin state.
+ * time plugin state.
  */
 type State$7 = {
-  source: ClockSource;
-  last: number;
-  dueAt: number | undefined;
-  handle: unknown;
-  listeners: Array<(input: Elapsed) => void>;
+  callbacks: Record<Phase, FrameCallback[]>;
+  /**
+   * Scratch array of a frame: the six callback lists as they were when the frame started.
+   */
+  captured: (readonly FrameCallback[])[];
+  time: Time;
+  paused: boolean;
+  running: boolean;
+  /**
+   * True while a frame runs; guards `step` re-entry.
+   */
+  stepping: boolean;
+  rafId: number | undefined;
+  lastTimestamp: number | undefined;
+  /**
+   * Elapsed time of the frame source in unscaled milliseconds, the clock of the idle timer: it
+   * keeps running while `scale` is 0.
+   */
+  unscaledElapsedMs: number;
+  /**
+   * Unscaled elapsed time of the last wake.
+   */
+  lastWakeMs: number;
+  /**
+   * True while the loop runs at `idleFps`.
+   */
+  idle: boolean;
 };
 /**
- * clock plugin API, `app.clock`. Trusted time for rules that depend on real time: energy refill,
- * generators, daily rewards. The clock holds ONE pending moment; the rules decide the next one.
+ * time plugin API, `app.time`. The one clock of the screen: frame callbacks per phase, the `Time`
+ * resource, the time scale, and `step` for tests and tools.
  *
  * @example
  * ```ts
- * // The whole cycle: ask the rules for the nearest moment, wait for it, apply, ask again.
- * app.clock.onElapsed(({ now }) => {
- *   applyRefills(now);
- *   app.clock.scheduleAt(nextRefillAt(now)); // undefined when nothing is pending
- * });
- * app.clock.scheduleAt(nextRefillAt(app.clock.now()));
+ * // Frame work is a callback in a phase. A test has no frame source: it drives the frames itself.
+ * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
+ *
+ * app.time.step(16);
+ * // the callback gets { delta: 16, elapsed: 16, scale: 1, frame: 1, idle: false }
+ * off();
  * ```
  */
 type Api$7 = {
   /**
-   * Reads trusted time. It never decreases, whatever the device clock does, so a player who sets
-   * the clock back gains nothing.
+   * Registers a frame callback. Callbacks of one phase run in registration order; a callback
+   * registered during a frame runs from the next frame on.
    *
-   * @returns The current moment in epoch milliseconds, an integer.
+   * @param phase - Phase the callback belongs to.
+   * @param callback - Function called once per frame with the current `Time`.
+   * @returns Unsubscribe function; calling it twice is a no-op.
    * @example
    * ```ts
-   * // Stamp a generator when it is used, and compare later.
-   * player.generator.usedAt = app.clock.now(); // 1790000000000
-   * const ready = app.clock.now() - player.generator.usedAt >= 60_000;
+   * // The coin counter rolls up while the reward popup is open.
+   * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
+   *
+   * off(); // the popup is closed
    * ```
    */
-  now(): number;
+  onFrame(phase: Phase, callback: FrameCallback): () => void;
   /**
-   * Replaces the single pending due moment. A moment in the past is not delivered synchronously:
-   * it fires on the next macrotask of the source.
+   * Returns a snapshot of the current `Time`, so a caller cannot write into the frame state.
    *
-   * @param moment - Moment in epoch milliseconds, or `undefined` to cancel.
+   * @returns A copy of the current `Time`.
    * @example
    * ```ts
-   * // A generator refills in 60 s. Only one moment is pending: the nearest one.
-   * app.clock.scheduleAt(app.clock.now() + 60_000);
-   * app.clock.scheduleAt(undefined); // nothing is due any more: cancel
+   * // Stamp the start of a combo window in game time, which stands still during a pause.
+   * const startedAt = app.time.snapshot().elapsed; // 1600
+   * app.time.snapshot(); // { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false }
    * ```
    */
-  scheduleAt(moment: number | undefined): void;
+  snapshot(): Readonly<Time>;
   /**
-   * Registers a listener for the `elapsed` input: a due moment arrived, or `poke` was called.
-   * The clock does not reschedule by itself.
+   * Sets the time scale. Every frame delta is multiplied by it; 0 freezes the game time
+   * while the frames keep running. A negative scale is clamped to 0.
    *
-   * @param listener - Called with `{ now }`, the trusted moment of the delivery.
-   * @returns The unsubscribe function.
+   * @param scale - New time scale, 0 or greater.
    * @example
    * ```ts
-   * const off = app.clock.onElapsed(({ now }) => {
-   *   applyRefills(now); // now: 1790000060000
-   * });
+   * // Slow motion while the last match of the level resolves.
+   * app.time.setScale(0.5); // a frame of 20 ms now has delta 10
+   * app.time.setScale(1);
+   * ```
+   */
+  setScale(scale: number): void;
+  /**
+   * Pauses the clock: no phase runs and `elapsed` stops advancing. Called by `lifecycle`.
    *
-   * off(); // the screen that showed the timer is closed
+   * @example
+   * ```ts
+   * // The lifecycle plugin owns the pause policy: the first pause reason stops the clock.
+   * // A game pauses through app.lifecycle.push(reason), never here.
+   * const time = ctx.require(timePlugin);
+   * if (reasons.length === 1) time.pause(); // app.time.isPaused() is true, no phase runs
    * ```
    */
-  onElapsed(listener: (input: Elapsed) => void): () => void;
+  pause(): void;
   /**
-   * Delivers `elapsed` right now, without touching the pending due moment. The engine calls it
-   * when the game resumes; a game calls it after it changed something the rules depend on.
+   * Resumes the clock and drops the stale timestamp, so the first frame after the pause has
+   * a normal delta instead of the whole pause. Called by `lifecycle`.
    *
    * @example
    * ```ts
-   * // The game synced with its server and the time source jumped forward: let the rules catch up.
-   * // On resume from background the engine pokes by itself, a game never does that.
-   * app.clock.poke(); // onElapsed listeners get { now } at once; the pending moment stays
+   * // The lifecycle plugin resumes when the last pause reason is gone.
+   * const time = ctx.require(timePlugin);
+   * if (reasons.length === 0) time.resume(); // the next frame has a normal delta, not the whole pause
    * ```
    */
-  poke(): void;
+  resume(): void;
   /**
-   * Reads the pending due moment, for inspection and tests.
+   * Tells whether the clock is paused.
    *
-   * @returns The pending moment, or `undefined` when nothing is scheduled.
+   * @returns True while paused.
    * @example
    * ```ts
-   * app.clock.scheduleAt(1500);
-   * app.clock.dueAt(); // 1500
-   * await app.stop();
-   * app.clock.dueAt(); // undefined
+   * // A test checks that a pause reason really stopped the frames.
+   * app.lifecycle.push("background");
+   * app.time.isPaused(); // true
    * ```
    */
-  dueAt(): number | undefined;
+  isPaused(): boolean;
+  /**
+   * Tells whether a real frame source drives the loop. False in plain Bun, where a test
+   * drives the frames with `step`.
+   *
+   * @returns True while the loop runs.
+   * @example
+   * ```ts
+   * // Without a frame source no frame ever comes: finish the fly-in at once instead of waiting.
+   * if (!app.time.isRunning()) coin.moveTo(target); // false in plain Bun, true in a browser
+   * ```
+   */
+  isRunning(): boolean;
+  /**
+   * Resets the idle timer: the next frame runs at `maxFps` again, even after a long idle. Cheap,
+   * idempotent and safe inside a frame callback. Every plugin that gives the player something to
+   * look at calls it: a pointer sample, a starting animation, a flow edge, a finished load, a
+   * scene switch, a locale change, a reconcile.
+   *
+   * @example
+   * ```ts
+   * // The flow runner walked an edge, so the screen has work again and the cap goes back up.
+   * const time = ctx.require(timePlugin);
+   *
+   * time.wake(); // app.time.snapshot().idle is false from here on
+   * ```
+   */
+  wake(): void;
+  /**
+   * Runs exactly one frame with the given unscaled delta, ignoring the fps cap, the pause
+   * flag and `maxDeltaMs`. The time scale still applies. For tests and tools.
+   *
+   * @param deltaMs - Unscaled delta of the frame in milliseconds.
+   * @throws {Error} When called from inside a frame callback.
+   * @example
+   * ```ts
+   * // A test plays two frames without a browser.
+   * app.time.step(16);
+   * app.time.step(4);
+   * app.time.snapshot(); // { delta: 4, elapsed: 20, scale: 1, frame: 2, idle: false }
+   * ```
+   */
+  step(deltaMs: number): void;
 };
 /**
- * Domain context of the clock plugin.
+ * Domain context of the time plugin.
  */
-type ClockCtx = PluginCtx<Config$7, State$7> & {
+type TimeCtx = PluginCtx<Config$7, State$7> & {
   readonly global: object;
+  readonly log: Log.LogApi;
 };
 declare namespace types_d_exports$6 {
   export { Api$6 as Api, Config$6 as Config, Events$5 as Events, LifecycleCtx, PauseReason, State$6 as State };
@@ -1056,244 +1088,212 @@ type ModelCtx = PluginCtx<Config$5, State$5, Events$4> & {
   readonly global: object;
   readonly log: Log.LogApi;
 };
-declare namespace types_d_exports$4 {
-  export { Api$4 as Api, Config$4 as Config, FrameCallback, Phase, State$4 as State, Time, TimeCtx };
-}
+declare namespace types_d_exports$4 {
+  export { Api$4 as Api, ClockCtx, ClockSource, Config$4 as Config, Elapsed, FakeClock, State$4 as State };
+}
+/**
+ * Source of time and timers. The system source is the default; a game passes its own when time
+ * must come from somewhere else, for example a server.
+ *
+ * @example
+ * ```ts
+ * // Server time: the device clock only measures the distance from the last sync. The plugin keeps
+ * // at most one timer alive, so the source remembers one.
+ * const serverClock = (serverNow: number): ClockSource => {
+ *   const syncedAt = performance.now();
+ *   let timer: ReturnType<typeof setTimeout> | undefined;
+ *
+ *   return {
+ *     now: () => serverNow + (performance.now() - syncedAt),
+ *     setTimer: (callback, delayMs) => (timer = setTimeout(callback, delayMs)),
+ *     clearTimer: () => clearTimeout(timer)
+ *   };
+ * };
+ *
+ * createApp({ pluginConfigs: { clock: { source: serverClock(1_790_000_000_000) } } });
+ * ```
+ */
+type ClockSource = {
+  /**
+   * Reads the current moment.
+   *
+   * @returns Epoch milliseconds. A fraction is cut by the plugin; going back is tolerated.
+   */
+  now(): number;
+  /**
+   * Schedules one callback. The plugin keeps at most one timer alive.
+   *
+   * @param callback - Function to run when the delay has passed.
+   * @param delayMs - Delay in milliseconds, never negative.
+   * @returns A handle of any shape; the plugin only hands it back to `clearTimer`.
+   */
+  setTimer(callback: () => void, delayMs: number): unknown;
+  /**
+   * Cancels a pending timer. A handle this source did not produce must be ignored.
+   *
+   * @param handle - Handle returned by `setTimer`.
+   */
+  clearTimer(handle: unknown): void;
+};
 /**
- * Frame phases, in call order.
+ * Fake source for tests, from `@moku-labs/game/testing`. It needs no real timer.
  *
  * @example
  * ```ts
- * const phase: Phase = "animate";
- * ```
- */
-type Phase = "input" | "animate" | "layout" | "sync" | "signals" | "render";
-/**
- * The Time resource, in scaled milliseconds. `idle` tells whether the loop currently runs at the
- * lowered idle cap.
+ * // An energy point refills after 60 s. The test does not wait: it moves the clock.
+ * const clock = fakeClock(1000);
+ * const app = createApp({ pluginConfigs: { clock: { source: clock } } });
  *
- * @example
- * ```ts
- * const time: Time = { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false };
+ * app.clock.scheduleAt(61_000);
+ * clock.advance(60_000); // the listeners of onElapsed get { now: 61000 }
  * ```
  */
-type Time = {
-  delta: number;
-  elapsed: number;
-  scale: number;
-  frame: number;
-  idle: boolean;
+type FakeClock = ClockSource & {
+  /**
+   * Moves the clock forward and fires every timer that falls due on the way, in due order.
+   *
+   * @param ms - Milliseconds to move forward. A negative amount moves nothing.
+   * @example
+   * ```ts
+   * clock.advance(5000); // now() is 5000 later, a timer due in 3000 has fired
+   * ```
+   */
+  advance(ms: number): void;
+  /**
+   * Jumps to a moment without firing any timer. Moving back is allowed: that is a player who
+   * sets the device clock by hand.
+   *
+   * @param moment - Moment in epoch milliseconds.
+   * @example
+   * ```ts
+   * clock.set(400); // the device clock went back; app.clock.now() does not decrease
+   * ```
+   */
+  set(moment: number): void;
 };
 /**
- * Callback run once per frame in its phase.
+ * Input delivered to `onElapsed` listeners when a due moment arrives or the game resumes.
  *
  * @example
  * ```ts
- * const advanceTweens: FrameCallback = time => tweens.advance(time.delta);
+ * const input: Elapsed = { now: 1_790_000_060_000 };
  * ```
  */
-type FrameCallback = (time: Readonly<Time>) => void;
+type Elapsed = {
+  now: number;
+};
 /**
- * time plugin config.
+ * clock plugin config.
  *
  * @example
  * ```ts
- * createApp({ pluginConfigs: { time: { maxFps: 30 } } });
+ * createApp({ pluginConfigs: { clock: { source: fakeClock(1000) } } });
  * ```
  */
 type Config$4 = {
   /**
-   * Frame rate cap. The default is 60. 120 is for WebViews that really deliver 120 Hz frames:
-   * Android today; WKWebView on iOS and macOS is capped at 60 by WebKit (bug 294338).
-   */
-  maxFps: 30 | 60 | 120;
-  /**
-   * Upper bound of one frame's delta in milliseconds.
-   */
-  maxDeltaMs: number;
-  /**
-   * Frame rate cap of an idle screen, when nothing woke the clock for `idleAfterMs`. The default
-   * is 30; 0 turns the idle cap off and every frame runs at `maxFps`.
-   */
-  idleFps: 0 | 30;
-  /**
-   * Unscaled milliseconds without a `wake()` after which the loop drops to `idleFps`.
+   * Time source. `undefined` means the system source: `Date.now` and `setTimeout`.
    */
-  idleAfterMs: number;
+  source: ClockSource | undefined;
 };
 /**
- * time plugin state.
+ * clock plugin state.
  */
 type State$4 = {
-  callbacks: Record<Phase, FrameCallback[]>;
-  /**
-   * Scratch array of a frame: the six callback lists as they were when the frame started.
-   */
-  captured: (readonly FrameCallback[])[];
-  time: Time;
-  paused: boolean;
-  running: boolean;
-  /**
-   * True while a frame runs; guards `step` re-entry.
-   */
-  stepping: boolean;
-  rafId: number | undefined;
-  lastTimestamp: number | undefined;
-  /**
-   * Elapsed time of the frame source in unscaled milliseconds, the clock of the idle timer: it
-   * keeps running while `scale` is 0.
-   */
-  unscaledElapsedMs: number;
-  /**
-   * Unscaled elapsed time of the last wake.
-   */
-  lastWakeMs: number;
-  /**
-   * True while the loop runs at `idleFps`.
-   */
-  idle: boolean;
+  source: ClockSource;
+  last: number;
+  dueAt: number | undefined;
+  handle: unknown;
+  listeners: Array<(input: Elapsed) => void>;
 };
 /**
- * time plugin API, `app.time`. The one clock of the screen: frame callbacks per phase, the `Time`
- * resource, the time scale, and `step` for tests and tools.
+ * clock plugin API, `app.clock`. Trusted time for rules that depend on real time: energy refill,
+ * generators, daily rewards. The clock holds ONE pending moment; the rules decide the next one.
  *
  * @example
  * ```ts
- * // Frame work is a callback in a phase. A test has no frame source: it drives the frames itself.
- * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
- *
- * app.time.step(16);
- * // the callback gets { delta: 16, elapsed: 16, scale: 1, frame: 1, idle: false }
- * off();
+ * // The whole cycle: ask the rules for the nearest moment, wait for it, apply, ask again.
+ * app.clock.onElapsed(({ now }) => {
+ *   applyRefills(now);
+ *   app.clock.scheduleAt(nextRefillAt(now)); // undefined when nothing is pending
+ * });
+ * app.clock.scheduleAt(nextRefillAt(app.clock.now()));
  * ```
  */
 type Api$4 = {
   /**
-   * Registers a frame callback. Callbacks of one phase run in registration order; a callback
-   * registered during a frame runs from the next frame on.
-   *
-   * @param phase - Phase the callback belongs to.
-   * @param callback - Function called once per frame with the current `Time`.
-   * @returns Unsubscribe function; calling it twice is a no-op.
-   * @example
-   * ```ts
-   * // The coin counter rolls up while the reward popup is open.
-   * const off = app.time.onFrame("animate", time => counter.advance(time.delta));
-   *
-   * off(); // the popup is closed
-   * ```
-   */
-  onFrame(phase: Phase, callback: FrameCallback): () => void;
-  /**
-   * Returns a snapshot of the current `Time`, so a caller cannot write into the frame state.
-   *
-   * @returns A copy of the current `Time`.
-   * @example
-   * ```ts
-   * // Stamp the start of a combo window in game time, which stands still during a pause.
-   * const startedAt = app.time.snapshot().elapsed; // 1600
-   * app.time.snapshot(); // { delta: 16, elapsed: 1600, scale: 1, frame: 100, idle: false }
-   * ```
-   */
-  snapshot(): Readonly<Time>;
-  /**
-   * Sets the time scale. Every frame delta is multiplied by it; 0 freezes the game time
-   * while the frames keep running. A negative scale is clamped to 0.
-   *
-   * @param scale - New time scale, 0 or greater.
-   * @example
-   * ```ts
-   * // Slow motion while the last match of the level resolves.
-   * app.time.setScale(0.5); // a frame of 20 ms now has delta 10
-   * app.time.setScale(1);
-   * ```
-   */
-  setScale(scale: number): void;
-  /**
-   * Pauses the clock: no phase runs and `elapsed` stops advancing. Called by `lifecycle`.
+   * Reads trusted time. It never decreases, whatever the device clock does, so a player who sets
+   * the clock back gains nothing.
    *
+   * @returns The current moment in epoch milliseconds, an integer.
    * @example
    * ```ts
-   * // The lifecycle plugin owns the pause policy: the first pause reason stops the clock.
-   * // A game pauses through app.lifecycle.push(reason), never here.
-   * const time = ctx.require(timePlugin);
-   * if (reasons.length === 1) time.pause(); // app.time.isPaused() is true, no phase runs
+   * // Stamp a generator when it is used, and compare later.
+   * player.generator.usedAt = app.clock.now(); // 1790000000000
+   * const ready = app.clock.now() - player.generator.usedAt >= 60_000;
    * ```
    */
-  pause(): void;
+  now(): number;
   /**
-   * Resumes the clock and drops the stale timestamp, so the first frame after the pause has
-   * a normal delta instead of the whole pause. Called by `lifecycle`.
+   * Replaces the single pending due moment. A moment in the past is not delivered synchronously:
+   * it fires on the next macrotask of the source.
    *
+   * @param moment - Moment in epoch milliseconds, or `undefined` to cancel.
    * @example
    * ```ts
-   * // The lifecycle plugin resumes when the last pause reason is gone.
-   * const time = ctx.require(timePlugin);
-   * if (reasons.length === 0) time.resume(); // the next frame has a normal delta, not the whole pause
+   * // A generator refills in 60 s. Only one moment is pending: the nearest one.
+   * app.clock.scheduleAt(app.clock.now() + 60_000);
+   * app.clock.scheduleAt(undefined); // nothing is due any more: cancel
    * ```
    */
-  resume(): void;
+  scheduleAt(moment: number | undefined): void;
   /**
-   * Tells whether the clock is paused.
+   * Registers a listener for the `elapsed` input: a due moment arrived, or `poke` was called.
+   * The clock does not reschedule by itself.
    *
-   * @returns True while paused.
+   * @param listener - Called with `{ now }`, the trusted moment of the delivery.
+   * @returns The unsubscribe function.
    * @example
    * ```ts
-   * // A test checks that a pause reason really stopped the frames.
-   * app.lifecycle.push("background");
-   * app.time.isPaused(); // true
-   * ```
-   */
-  isPaused(): boolean;
-  /**
-   * Tells whether a real frame source drives the loop. False in plain Bun, where a test
-   * drives the frames with `step`.
+   * const off = app.clock.onElapsed(({ now }) => {
+   *   applyRefills(now); // now: 1790000060000
+   * });
    *
-   * @returns True while the loop runs.
-   * @example
-   * ```ts
-   * // Without a frame source no frame ever comes: finish the fly-in at once instead of waiting.
-   * if (!app.time.isRunning()) coin.moveTo(target); // false in plain Bun, true in a browser
+   * off(); // the screen that showed the timer is closed
    * ```
    */
-  isRunning(): boolean;
+  onElapsed(listener: (input: Elapsed) => void): () => void;
   /**
-   * Resets the idle timer: the next frame runs at `maxFps` again, even after a long idle. Cheap,
-   * idempotent and safe inside a frame callback. Every plugin that gives the player something to
-   * look at calls it: a pointer sample, a starting animation, a flow edge, a finished load, a
-   * scene switch, a locale change, a reconcile.
+   * Delivers `elapsed` right now, without touching the pending due moment. The engine calls it
+   * when the game resumes; a game calls it after it changed something the rules depend on.
    *
    * @example
    * ```ts
-   * // The flow runner walked an edge, so the screen has work again and the cap goes back up.
-   * const time = ctx.require(timePlugin);
-   *
-   * time.wake(); // app.time.snapshot().idle is false from here on
+   * // The game synced with its server and the time source jumped forward: let the rules catch up.
+   * // On resume from background the engine pokes by itself, a game never does that.
+   * app.clock.poke(); // onElapsed listeners get { now } at once; the pending moment stays
    * ```
    */
-  wake(): void;
+  poke(): void;
   /**
-   * Runs exactly one frame with the given unscaled delta, ignoring the fps cap, the pause
-   * flag and `maxDeltaMs`. The time scale still applies. For tests and tools.
+   * Reads the pending due moment, for inspection and tests.
    *
-   * @param deltaMs - Unscaled delta of the frame in milliseconds.
-   * @throws {Error} When called from inside a frame callback.
+   * @returns The pending moment, or `undefined` when nothing is scheduled.
    * @example
    * ```ts
-   * // A test plays two frames without a browser.
-   * app.time.step(16);
-   * app.time.step(4);
-   * app.time.snapshot(); // { delta: 4, elapsed: 20, scale: 1, frame: 2, idle: false }
+   * app.clock.scheduleAt(1500);
+   * app.clock.dueAt(); // 1500
+   * await app.stop();
+   * app.clock.dueAt(); // undefined
    * ```
    */
-  step(deltaMs: number): void;
+  dueAt(): number | undefined;
 };
 /**
- * Domain context of the time plugin.
+ * Domain context of the clock plugin.
  */
-type TimeCtx = PluginCtx<Config$4, State$4> & {
+type ClockCtx = PluginCtx<Config$4, State$4> & {
   readonly global: object;
-  readonly log: Log.LogApi;
 };
 //#endregion
 //#region src/plugins/flow/gate/types.d.ts
@@ -2828,9 +2828,9 @@ type Api$3 = RunnerApi & {
  * shared by the runner, gate, inbox and fx.
  */
 type Deps$3 = {
-  time: Api$4;
+  time: Api$7;
   model: Api$5;
-  clock: Api$7;
+  clock: Api$4;
 };
 /**
  * What the kernel context offers before the deps are attached. `emit` is the kernel's: `index.ts`
@@ -4840,7 +4840,7 @@ type Api$2 = {
  * Resolved dependency APIs.
  */
 type Deps$2 = {
-  time: Api$4;
+  time: Api$7;
   model: Api$5;
   flow: Api$3;
 };
@@ -6409,10 +6409,10 @@ type Under = {
  * Resolved dependency APIs. `clock` is the time source of the frame counters.
  */
 type Deps$1 = {
-  time: Api$4;
+  time: Api$7;
   lifecycle: Api$6;
   world: Api$2;
-  clock: Api$7;
+  clock: Api$4;
 };
 /**
  * What the kernel context offers before the deps are attached.
@@ -7153,7 +7153,7 @@ type Api = {
 type Deps = {
   flow: Api$3;
   renderer: Api$1;
-  time: Api$4;
+  time: Api$7;
 };
 /**
  * What the kernel context offers before the deps are attached.
@@ -7181,4 +7181,4 @@ type FlowRest = {
   checkpoint: boolean;
 };
 //#endregion
-export { Ease as $, PlayerStateProvider as $t, Config$2 as A, FlowState as At, ComponentValue as B, Api$4 as Bt, Captured as C, to as Ct, Point as D, Bookmark as Dt, FilterSlot as E, AnyFlow as Et, AnyComponentType as F, TypeTag as Ft, Narrowed as G, Api$5 as Gt, EntitySnapshot as H, State$4 as Ht, AnyComponentValue as I, Descriptor as It, ResourceType as J, Json as Jt, Owner as K, Config$5 as Kt, ComponentHandle as L, GuideOptions as Lt, State$2 as M, NodeTable as Mt, types_d_exports$2 as N, RouteStep as Nt, ViewportSize as O, DefineNode as Ot, AnyComponent as P, SceneIdOf as Pt, DescriptionNode as Q, Patch as Qt, ComponentSchema as R, Hint as Rt, types_d_exports$1 as S, slot as St, DebugSwitches as T, FeatureDescription as Tt, FrameDiff as U, Time as Ut, Entity as V, Config$4 as Vt, Mut as W, types_d_exports$4 as Wt, TagType as X, State$5 as Xt, SystemDefinition as Y, Root as Yt, ChangeHook as Z, types_d_exports$5 as Zt, PixiModule as _, State$7 as _n, State$3 as _t, DefineBundles as a, RngApi as an, ProjectionMotion as at, State$1 as b, Events$6 as bn, defineFlow as bt, LoadReason as c, Config$6 as cn, TrackSegment as ct, Tier as d, State$6 as dn, BundlesOf as dt, ProviderCall as en, LayerSort as et, Usage as f, types_d_exports$6 as fn, Config$3 as ft, PixiFilter as g, FakeClock as gn, Position as gt, Config$1 as h, Config$7 as hn, GameTypes as ht, Config as i, StoreApi as in, NumericFields as it, Explained as j, JournalEntry as jt, Api$2 as k, FlowGraph as kt, Manifest as l, Events$5 as ln, ViewHandle as lt, Api$1 as m, ClockSource as mn, FeaturePlugin as mt, BundleMap as n, SaveUnreadableError as nn, Motion as nt, Events as o, RngState as on, ProjectionSpec as ot, types_d_exports as p, Api$7 as pn, EmitterIdOf as pt, QueryTerm as q, Events$4 as qt, BundleSpec as r, Snapshot as rn, MotionHandle as rt, LoadBundles as s, Api$6 as sn, TrackOptions as st, Api as t, SaveDoc as tn, LayerSpec as tt, State as u, PauseReason as un, Api$3 as ut, PixiSprite as v, types_d_exports$7 as vn, TextStylesOf as vt, RenderStats as w, type as wt, Under as x, Require as xn, exit as xt, PixiTexture as y, Config$8 as yn, types_d_exports$3 as yt, ComponentType as z, Answer as zt };
+export { DescriptionNode as $, types_d_exports$5 as $t, Api$2 as A, FlowGraph as At, ComponentType as B, Answer as Bt, types_d_exports$1 as C, slot as Ct, FilterSlot as D, AnyFlow as Dt, DebugSwitches as E, FeatureDescription as Et, AnyComponent as F, SceneIdOf as Ft, Mut as G, State$4 as Gt, Entity as H, ClockSource as Ht, AnyComponentType as I, TypeTag as It, QueryTerm as J, Config$5 as Jt, Narrowed as K, types_d_exports$4 as Kt, AnyComponentValue as L, Descriptor as Lt, Explained as M, JournalEntry as Mt, State$2 as N, NodeTable as Nt, Point as O, Bookmark as Ot, types_d_exports$2 as P, RouteStep as Pt, ChangeHook as Q, State$5 as Qt, ComponentHandle as R, GuideOptions as Rt, Under as S, Require as Sn, exit as St, RenderStats as T, type as Tt, EntitySnapshot as U, Config$4 as Ut, ComponentValue as V, Api$4 as Vt, FrameDiff as W, FakeClock as Wt, SystemDefinition as X, Json as Xt, ResourceType as Y, Events$4 as Yt, TagType as Z, Root as Zt, PixiFilter as _, State$7 as _n, Position as _t, Config as a, Snapshot as an, NumericFields as at, PixiTexture as b, Config$8 as bn, types_d_exports$3 as bt, LoadBundles as c, RngState as cn, TrackOptions as ct, State as d, Events$5 as dn, Api$3 as dt, Patch as en, Ease as et, Tier as f, PauseReason as fn, BundlesOf as ft, Config$1 as g, Config$7 as gn, GameTypes as gt, Api$1 as h, Api$7 as hn, FeaturePlugin as ht, BundleSpec as i, SaveUnreadableError as in, MotionHandle as it, Config$2 as j, FlowState as jt, ViewportSize as k, DefineNode as kt, LoadReason as l, Api$6 as ln, TrackSegment as lt, types_d_exports as m, types_d_exports$6 as mn, EmitterIdOf as mt, AssetsIo as n, ProviderCall as nn, LayerSpec as nt, DefineBundles as o, StoreApi as on, ProjectionMotion as ot, Usage as p, State$6 as pn, Config$3 as pt, Owner as q, Api$5 as qt, BundleMap as r, SaveDoc as rn, Motion as rt, Events as s, RngApi as sn, ProjectionSpec as st, Api as t, PlayerStateProvider as tn, LayerSort as tt, Manifest as u, Config$6 as un, ViewHandle as ut, PixiModule as v, Time as vn, State$3 as vt, Captured as w, to as wt, State$1 as x, Events$6 as xn, defineFlow as xt, PixiSprite as y, types_d_exports$7 as yn, TextStylesOf as yt, ComponentSchema as z, Hint as zt };