@vgai/live 0.5.2 → 0.5.4

package/src/game-client/errors.ts

@@ -0,0 +1,96 @@
+import type { SessionFailureData } from './failure-block.js';
+
+/**
+ * Machine-readable error codes this client throws. `INPUT_GATED` is the same
+ * frozen token `@vgai/sdk`'s input operations declare, so a caller classifies
+ * a gated actuation identically whichever door it came through. `WAIT_FOR_*`
+ * and `EVENTS_EXPECT_FAILED` are this client's own extension of the same
+ * "errors carry machine-readable `code` fields" rule: nothing in the codebase
+ * may identify a failure by parsing message prose, so an assertion failure
+ * gets a code too.
+ */
+export const SESSION_ERROR_CODES = {
+  INPUT_GATED: 'INPUT_GATED',
+  WAIT_FOR_INVALID_BUDGET: 'WAIT_FOR_INVALID_BUDGET',
+  WAIT_FOR_TIMEOUT: 'WAIT_FOR_TIMEOUT',
+  EVENTS_EXPECT_FAILED: 'EVENTS_EXPECT_FAILED',
+} as const;
+
+export type SessionErrorCode = (typeof SESSION_ERROR_CODES)[keyof typeof SESSION_ERROR_CODES];
+
+/**
+ * Base error for this client. `code` is always machine-readable; `data` (if
+ * any) is structured, never prose-only. Bridge-surfaced errors (unknown
+ * provider/command/action names) are re-thrown as this class carrying the
+ * bridge's own `code`/`data` verbatim — see `client.ts`'s `invokeBridge`.
+ */
+export class SessionError extends Error {
+  readonly code: string;
+  readonly data: unknown;
+
+  constructor(code: string, message: string, data?: unknown) {
+    super(message);
+    this.name = 'SessionError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/** A `delivered:false` virtual-input actuation fails loudly and immediately
+ *  (Task 3.2 item: "game.input hold-tap-set"). */
+export function inputGatedError(action: string, reason: string | undefined): SessionError {
+  return new SessionError(
+    SESSION_ERROR_CODES.INPUT_GATED,
+    `INPUT_GATED: action "${action}" was not delivered — ${reason ?? 'input gated'}`,
+    { action, reason },
+  );
+}
+
+/** The exact `code` the engine's debug registry throws for an unknown
+ *  command name (`packages/engine/src/runtime/debug-registry.ts`) — not one
+ *  of this client's OWN `SESSION_ERROR_CODES` above (it originates on the
+ *  page side and crosses the bridge verbatim via `client.ts`'s `unwrap`),
+ *  named here so `appendWarmSessionHint` below doesn't compare against a
+ *  bare string literal. */
+const DEBUG_COMMAND_NOT_REGISTERED_CODE = 'DEBUG_COMMAND_NOT_REGISTERED';
+
+/** Cheapest honest fix for a blind-validation finding: a run against a WARM
+ *  game server (one already up before this client attached) gives a
+ *  `DEBUG_COMMAND_NOT_REGISTERED` failure an extra way to be true besides
+ *  "this command was never registered" — the agent may have added the command
+ *  to the game's OWN code AFTER the warm server already booted, so the running
+ *  server simply predates it. Without a live page handle this client can't
+ *  tell the two apart either, so the honest move is naming the possibility,
+ *  not guessing. Appended ONLY for that exact (code, warm) combination — never
+ *  on a fresh boot, and never for any other error code, so an ordinary "you
+ *  never wrote this command" failure stays exactly as terse as before. Pure so
+ *  the message logic is testable without a real bridge round trip. */
+export const WARM_SESSION_STALE_COMMAND_NOTE =
+  'note: this run reused a warm game server — if you added this command since the server ' +
+  'booted, restart the server and re-run';
+
+export function appendWarmSessionHint(
+  message: string,
+  code: string | undefined,
+  warm: boolean,
+): string {
+  if (!warm || code !== DEBUG_COMMAND_NOT_REGISTERED_CODE) return message;
+  return `${message}\n${WARM_SESSION_STALE_COMMAND_NOTE}`;
+}
+
+/**
+ * A `game.waitFor` / `game.input.hold` / `game.events.expect` failure. Always
+ * carries the full eight-member failure block (Task 3.3) both as the
+ * rendered assertion `message` and as structured `data` for a JSON reporter.
+ */
+export class SessionFailure extends Error {
+  readonly code: string;
+  readonly data: SessionFailureData;
+
+  constructor(code: string, block: { message: string; data: SessionFailureData }) {
+    super(block.message);
+    this.name = 'SessionFailure';
+    this.code = code;
+    this.data = block.data;
+  }
+}

package/src/game-client/events-matcher.ts

@@ -0,0 +1,106 @@
+/**
+ * Pure `game.events.expect` matcher — no Playwright. Default mode is an
+ * ordered SUBSEQUENCE match (extra actual events are tolerated, including
+ * interleaved ones); `{ exact: true }` requires the actual (fenced) event
+ * window to equal `expected` position-for-position with nothing extra.
+ */
+
+import type { TickStampedEvent } from './types.js';
+
+export interface EventsMatchOptions {
+  exact?: boolean;
+  /** All matched expected events must land within this many ticks of the
+   *  fence (the snapshot `actual` was already filtered to). Optional —
+   *  unset means no timing constraint beyond ordering. */
+  withinTicks?: number;
+}
+
+export interface EventsMatchResult {
+  matched: boolean;
+  /** Index into `expected` of the first expectation the match couldn't
+   *  satisfy; `null` when `matched` is true. */
+  firstUnmatchedIndex: number | null;
+}
+
+/**
+ * M9: `fenceTick` is the REAL fence (the tick `game.events.expect` fenced
+ * `actual` from — `GameClient.fenceTick`, i.e. the test's own start), not
+ * `actual[0].tick`. Using the first EVENT's tick as the fence under-counts
+ * `withinTicks`: if the fence is tick 10 and the first matching event
+ * happens at tick 50 (40 ticks after the fence), `actual[0].tick` would make
+ * that look like "0 ticks since the fence" instead of 40.
+ *
+ * It is REQUIRED, and comes BEFORE `opts`. It used to be a trailing optional
+ * with an `actual[0]?.tick ?? 0` back-compat default — i.e. the very
+ * under-counting bug above, silently reinstated for anyone who forgot the
+ * argument. The one production caller always had a real fence, so the
+ * default only ever existed to be wrong. Also (M9): `{ exact: true }` honors
+ * `withinTicks` too — previously only the default subsequence mode checked
+ * it at all.
+ */
+export function matchEventsSubsequence(
+  expected: string[],
+  actual: TickStampedEvent[],
+  fenceTick: number,
+  opts: EventsMatchOptions = {},
+): EventsMatchResult {
+  if (opts.exact) {
+    return matchExact(expected, actual, opts.withinTicks, fenceTick);
+  }
+  return matchSubsequence(expected, actual, opts.withinTicks, fenceTick);
+}
+
+function matchSubsequence(
+  expected: string[],
+  actual: TickStampedEvent[],
+  withinTicks: number | undefined,
+  fenceTick: number,
+): EventsMatchResult {
+  let expectedIdx = 0;
+  for (const e of actual) {
+    const wantName = expected[expectedIdx];
+    if (wantName === undefined) break;
+    if (e.event !== wantName) continue;
+    if (withinTicks !== undefined && e.tick - fenceTick > withinTicks) continue;
+    expectedIdx += 1;
+  }
+  if (expectedIdx >= expected.length) {
+    return { matched: true, firstUnmatchedIndex: null };
+  }
+  return { matched: false, firstUnmatchedIndex: expectedIdx };
+}
+
+function matchExact(
+  expected: string[],
+  actual: TickStampedEvent[],
+  withinTicks: number | undefined,
+  fenceTick: number,
+): EventsMatchResult {
+  const len = Math.max(expected.length, actual.length);
+  for (let i = 0; i < len; i++) {
+    const want = expected[i];
+    const gotEvent = actual[i];
+    if (want !== gotEvent?.event) {
+      return { matched: false, firstUnmatchedIndex: Math.min(i, Math.max(expected.length - 1, 0)) };
+    }
+    if (
+      withinTicks !== undefined &&
+      gotEvent !== undefined &&
+      gotEvent.tick - fenceTick > withinTicks
+    ) {
+      return { matched: false, firstUnmatchedIndex: Math.min(i, Math.max(expected.length - 1, 0)) };
+    }
+  }
+  return { matched: true, firstUnmatchedIndex: null };
+}
+
+/** Renders the "predicate" line `events.expect` uses in its failure block —
+ *  there is no user predicate function for this assertion, so the failure
+ *  block's generic `predicateSource` slot gets a description instead. */
+export function describeEventsExpectation(
+  expected: string[],
+  opts: EventsMatchOptions = {},
+): string {
+  const optsText = opts.exact ? ', { exact: true }' : '';
+  return `events.expect(${JSON.stringify(expected)}${optsText})`;
+}

package/src/game-client/failure-block.ts

@@ -0,0 +1,199 @@
+/**
+ * Pure failure-block assembly (Task 3.3) — no Playwright. Every
+ * driver-originated failure (`game.waitFor` timeout, `game.events.expect`
+ * mismatch) renders through this one assembler so the frozen eight-member
+ * contract is met identically everywhere: elapsed (sim/wall/ratio+hint),
+ * tick, predicate/expectation source, tier-annotated + byte-capped last
+ * state, last 8 events, screenshot path, console errors, page errors. (M13
+ * review fix adds one MORE line, hidden-tab recovery notices, kept
+ * deliberately separate from the console/page-errors member rather than
+ * folded into it — see `recoveryNotices` below.)
+ */
+
+import { capJson } from './state-cap.js';
+import type { ProviderInfo, TickStampedEvent } from './types.js';
+
+export interface FailureBlockContext {
+  /** First line — e.g. "game.waitFor timed out: budget 10 sim-seconds". */
+  headline: string;
+  simElapsedSeconds: number;
+  wallElapsedMs: number;
+  tick: number;
+  /** `pred.toString()` for waitFor; a rendered description for events.expect. */
+  predicateSource: string;
+  providers: ProviderInfo[];
+  /** Provider names the predicate actually read (waitFor only) — drives the
+   *  "⚠ proof consumed assisted state" header flag. Omitted (or empty) for
+   *  assertions with no predicate function, e.g. events.expect. */
+  touchedProviders?: string[];
+  lastState: Record<string, unknown>;
+  lastEvents: TickStampedEvent[];
+  screenshotPath: string | null;
+  consoleErrors: string[];
+  pageErrors: string[];
+  /** M13: hidden-tab recovery's own structured log lines (hidden-recovery.ts's
+   *  `hiddenRecoveryLogLine`), kept SEPARATE from `consoleErrors` — a
+   *  recovery notice ("bringToFront() fired") is not itself an error, and
+   *  conflating it with real console/page errors muddies the one section a
+   *  reader scans to tell "the game crashed" from "the tab was backgrounded
+   *  and got recovered". Optional/defaults to empty — most failures have
+   *  none. */
+  recoveryNotices?: string[];
+  /**
+   * Issue #175 — the REAL loop liveness at the moment of failure (the
+   * timed-out/failed snapshot's `time.loopLiveness`). When this is
+   * `'hidden-paused'`, `ratioLine` below replaces its generic "if ~0x, the
+   * loop is stalled" hint with an explicit "the tab is hidden" diagnosis —
+   * `HiddenRecoveryDriver` already tried ONE `bringToFront()` recovery
+   * before this failure was ever thrown (see `client.ts`/`hidden-recovery.ts`);
+   * a 0.00x ratio surviving past that recovery attempt is exactly the
+   * ambiguous reading this field resolves: a backgrounded tab the recovery
+   * couldn't reach (headless/no-op `bringToFront`), not proof the game
+   * itself crashed. Optional/`undefined` when the bridge build predates
+   * `loopLiveness` — falls back to the old generic hint, same as before.
+   */
+  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null | undefined;
+}
+
+export interface SessionFailureData {
+  headline: string;
+  elapsed: { simSeconds: number; wallMs: number; ratio: number; line: string };
+  tick: number;
+  predicateSource: string;
+  lastState: { text: string; truncated: boolean };
+  lastEvents: TickStampedEvent[];
+  screenshotPath: string | null;
+  consoleErrors: string[];
+  pageErrors: string[];
+  /** Non-empty when the predicate consumed an `assisted`-tier provider. */
+  assistedTierConsumed: string[];
+  /** M13: see `FailureBlockContext.recoveryNotices`. Always present (an
+   *  empty array, not omitted) so a JSON reporter never has to distinguish
+   *  "no notices" from "field absent". */
+  recoveryNotices: string[];
+  /** Issue #175 — see `FailureBlockContext.loopLiveness`'s doc comment.
+   *  Machine-readable twin of `elapsed.line`'s hidden-tab hint, for a JSON
+   *  reporter that doesn't want to parse prose to tell a frozen tab from a
+   *  stalled game. `undefined`/`null` exactly mirrors the context field. */
+  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null | undefined;
+}
+
+export interface AssembledFailureBlock {
+  message: string;
+  data: SessionFailureData;
+}
+
+/** Annotates each top-level state key with its provider tier, e.g.
+ *  `"inventory[observable]"`. Providers with no matching registration
+ *  (shouldn't normally happen — `stateAll()` and `providers()` are read from
+ *  the same registry) are marked `[unknown]` rather than dropped. */
+export function annotateStateTiers(
+  state: Record<string, unknown>,
+  providers: ProviderInfo[],
+): Record<string, unknown> {
+  const tierByName = new Map(providers.map((p) => [p.name, p.tier]));
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(state)) {
+    const tier = tierByName.get(key) ?? 'unknown';
+    out[`${key}[${tier}]`] = value;
+  }
+  return out;
+}
+
+function ratioLine(
+  simElapsedSeconds: number,
+  wallElapsedMs: number,
+  loopLiveness?: 'running' | 'hidden-paused' | 'stopped' | null,
+): { ratio: number; line: string } {
+  const wallElapsedS = wallElapsedMs / 1000;
+  const ratio = wallElapsedS > 0 ? simElapsedSeconds / wallElapsedS : 0;
+  // Issue #175: a hidden tab hard-stops the engine loop (T2.1's deliberate
+  // idle throttle) — the same ~0x reading a genuinely stalled/crashed game
+  // produces. Without this branch an agent sees "loop is stalled" and has no
+  // way to tell a frozen tab from a dead game; say so explicitly instead.
+  const hint =
+    loopLiveness === 'hidden-paused'
+      ? 'the EDITOR/BROWSER TAB IS HIDDEN — the engine loop deliberately ' +
+        'stops ticking while backgrounded (not a crash); bring the tab to ' +
+        'the foreground and retry'
+      : 'if ~0x, the loop is stalled; if <1x under CI, the budget may just ' +
+        'be too small for SwiftShader';
+  const line =
+    `sim-time elapsed: ${simElapsedSeconds.toFixed(2)}s over ${wallElapsedS.toFixed(1)}s wall ` +
+    `(sim speed ${ratio.toFixed(2)}x — ${hint})`;
+  return { ratio, line };
+}
+
+export function assembleFailureBlock(ctx: FailureBlockContext): AssembledFailureBlock {
+  const tierByName = new Map(ctx.providers.map((p) => [p.name, p.tier]));
+  const touched = ctx.touchedProviders ?? [];
+  const assistedTierConsumed = touched.filter((name) => tierByName.get(name) === 'assisted');
+
+  const annotatedState = annotateStateTiers(ctx.lastState, ctx.providers);
+  const capped = capJson(annotatedState);
+  const last8Events = ctx.lastEvents.slice(-8);
+  const { ratio, line: elapsedLine } = ratioLine(
+    ctx.simElapsedSeconds,
+    ctx.wallElapsedMs,
+    ctx.loopLiveness,
+  );
+
+  const eventsLine =
+    last8Events.length > 0
+      ? last8Events
+          .map(
+            (e) =>
+              `[t=${e.tick}] ${e.event}${e.detail !== undefined ? ` ${JSON.stringify(e.detail)}` : ''}`,
+          )
+          .join(' ')
+      : '(none)';
+
+  const consoleAndPageErrorsText =
+    ctx.consoleErrors.length + ctx.pageErrors.length > 0
+      ? [...ctx.consoleErrors, ...ctx.pageErrors].join('; ')
+      : '(none)';
+
+  const recoveryNotices = ctx.recoveryNotices ?? [];
+  const recoveryNoticesText = recoveryNotices.length > 0 ? recoveryNotices.join('; ') : '(none)';
+
+  const lines = [
+    ctx.headline,
+    elapsedLine,
+    `tick at failure: ${ctx.tick}`,
+    `predicate: ${ctx.predicateSource}`,
+    `last state (tier-annotated): ${capped.text}${capped.truncated ? ' [truncated]' : ''}`,
+    `last 8 events: ${eventsLine}`,
+    `screenshot: ${ctx.screenshotPath ?? '(none)'}`,
+    `console/page errors during test: ${consoleAndPageErrorsText}`,
+    // M13: its own line, deliberately separate from the console/page errors
+    // line above — a hidden-tab recovery notice is not itself an error.
+    `hidden-tab recovery notices: ${recoveryNoticesText}`,
+  ];
+
+  const header =
+    assistedTierConsumed.length > 0
+      ? `⚠ proof consumed assisted (X-ray) state: ${assistedTierConsumed.join(', ')}\n`
+      : '';
+
+  const data: SessionFailureData = {
+    headline: ctx.headline,
+    elapsed: {
+      simSeconds: ctx.simElapsedSeconds,
+      wallMs: ctx.wallElapsedMs,
+      ratio,
+      line: elapsedLine,
+    },
+    tick: ctx.tick,
+    predicateSource: ctx.predicateSource,
+    lastState: capped,
+    lastEvents: last8Events,
+    screenshotPath: ctx.screenshotPath,
+    consoleErrors: ctx.consoleErrors,
+    pageErrors: ctx.pageErrors,
+    assistedTierConsumed,
+    recoveryNotices,
+    loopLiveness: ctx.loopLiveness,
+  };
+
+  return { message: header + lines.join('\n'), data };
+}

package/src/game-client/fast-forward.ts

@@ -0,0 +1,175 @@
+/**
+ * Pure `game.fastForward` batching/accounting math — no Playwright (same
+ * "pure module, Playwright-free" split `wait-for.ts` established, so this
+ * unit-tests headlessly). `client.ts`'s `GameClient.fastForward` is the
+ * thin Playwright-bound wrapper around `runFastForward` below, exactly the
+ * way `GameClient.waitFor` wraps `runWaitFor`.
+ *
+ * The shape: `game.fastForward({simSeconds}|{simTicks})` synchronously
+ * drives the live `Game`'s `runTicks` (through the debug bridge, door (a))
+ * instead of relying on real wall-clock time to pass. Doctrine:
+ * fastForward is for SETUP/STAGING traversal —
+ * reaching a known late-game state fast — not a replacement for real-input
+ * proofs, which still run in real ticks; a scripted/scheduled input sequence
+ * driven THROUGH a fastForward burst is still an honest proof of "what the sim
+ * consumed" (the post-gate recording framing) — fastForward changes
+ * how fast ticks are produced, never what a tick consumes.
+ *
+ * Two honesty decisions this module encodes, both because burst ticks are NOT
+ * ordinary wall-clock-paced simulation and must never be reported as if they
+ * were (the "never fabricate" rule threaded through `perf-sampling.ts`/
+ * `failure-block.ts`):
+ *
+ *  1. **Batching, not one giant `runTicks` call.** A single call driving (say)
+ *     an hour of sim time would (a) block the page's JS thread for the ENTIRE
+ *     burst with zero observable progress, and (b) starve anything watching
+ *     this run's stdout for liveness for however long the burst takes — a
+ *     false "wedged" verdict on a run that was making fine (just silent)
+ *     progress. Batching into `DEFAULT_FAST_FORWARD_BATCH_TICKS`-sized chunks
+ *     with one heartbeat per chunk (`client.ts` prints it) keeps output flowing
+ *     without giving up the speedup — each batch is still driven synchronously
+ *     in-page; only the ROUND TRIP is chunked.
+ *  2. **Burst ticks never feed the ordinary tps stats.** `perf-sampling.ts`'s
+ *     `TpsAccumulator` measures REAL wall-clock throughput between ordinary
+ *     `snapshot()` polls — its whole purpose is "is the game's frame loop
+ *     keeping up in real time." A burst of, say, 1800 ticks completed in
+ *     ~50ms would produce a `~36000 ticks/s` sample that means nothing about
+ *     the game's real per-frame cost, and would silently corrupt the p50/p95
+ *     a genuine stall would otherwise surface in. `client.ts`'s `fastForward`
+ *     therefore drives every batch through a RAW bridge call (bypassing
+ *     `GameClient.snapshot()`'s automatic `TpsAccumulator.record`) and resets
+ *     the accumulator's baseline once the burst completes, so the very next
+ *     ordinary poll starts a fresh "first observation" instead of diffing
+ *     across the burst discontinuity. The whole-TEST `simSpeedRatio` (fixture
+ *     teardown, `perf-sampling.ts`) is NOT protected this way, deliberately:
+ *     it is an honest end-to-end ratio (fence snapshot -> final snapshot),
+ *     not a sampled rate, and showing "this test ran at 400x" when it
+ *     genuinely did IS the correct, undistorted signal. `waitFor` budgets are
+ *     themselves unaffected by any of this — they are still sim-time
+ *     budgets; a `fastForward` immediately before one just leaves less real
+ *     ground for it to cover (sim-time got CHEAPER, not redefined).
+ */
+
+export type FastForwardBudget = { simSeconds: number } | { simTicks: number };
+
+export type FastForwardRenderMode = 'last' | 'all' | 'none';
+
+export interface FastForwardOptions {
+  /** Render mode for the FINAL tick of the WHOLE fast-forward (default
+   *  `'last'`, matching `Game.runTicks`'s own default) — every intermediate
+   *  batch always forces `'none'` regardless of this value; see the module
+   *  doc's batching rationale (point 1). */
+  render?: FastForwardRenderMode;
+  /** Overrides `DEFAULT_FAST_FORWARD_BATCH_TICKS` — test-only seam; real
+   *  callers should leave this unset. */
+  batchTicks?: number;
+}
+
+/** One fixed timestep, matching every real host's loop construction
+ *  (`createGameLoop`'s own `fixedTimestep ?? 1/60` default: "fixedDt = the
+ *  host loop's fixed timestep (1/60)"). Used ONLY as a fallback when a
+ *  `simSeconds` budget needs converting to a tick count before the game has
+ *  ticked even once (nothing observed yet to measure the real fixedDt from) —
+ *  see `ticksForBudget`. */
+export const DEFAULT_FIXED_DT = 1 / 60;
+
+/** 5 sim-seconds' worth of ticks at the default 60Hz rate — small enough that
+ *  even a complex game's batch finishes well inside a second of real time
+ *  (keeping heartbeats frequent), large enough that round-trip overhead stays
+ *  negligible next to the speedup (module doc, point 1). */
+export const DEFAULT_FAST_FORWARD_BATCH_TICKS = 300;
+
+export interface FastForwardTime {
+  tick: number;
+  simSeconds: number;
+}
+
+/** The driver's I/O seam — real usage (`client.ts`) wires this to raw
+ *  (non-tps-recording) bridge calls; tests supply a scripted fake so this
+ *  module's batching/accounting logic is provable with no browser at all. */
+export interface FastForwardClock {
+  /** Synchronously runs `n` fixed ticks with the given render mode for THIS
+   *  batch (the driver, not the clock, decides which batch is final and
+   *  therefore gets the caller's requested render mode). */
+  runTicksBatch(n: number, render: FastForwardRenderMode): Promise<void>;
+  /** Reads the current `{tick, simSeconds}` WITHOUT recording a tps sample —
+   *  called once up front (to derive `fixedDt` for a `simSeconds` budget) and
+   *  once at the very end (the returned result). */
+  readTime(): Promise<FastForwardTime>;
+  /** One call per completed batch — real usage prints a heartbeat line
+   *  (reaching the CLI wedge watchdog's stdout-liveness check); tests just
+   *  record the calls. */
+  heartbeat(info: { ticksDone: number; ticksTotal: number }): void;
+}
+
+/** Converts a `simSeconds` budget into an exact tick count using the game's
+ *  OWN observed `simSeconds`/`tick` ratio — not a hardcoded constant, since a
+ *  project may run a non-default fixed timestep (see `simulate-cinematic`'s
+ *  `vgai-simulate-fixed-dt` precedent); measuring beats assuming. Falls back
+ *  to `DEFAULT_FIXED_DT` only when `observed.tick` is still `0` (nothing to
+ *  measure from yet — a fresh page that hasn't ticked once). A `simTicks`
+ *  budget passes straight through, unaffected by any of this. */
+export function ticksForBudget(budget: FastForwardBudget, observed: FastForwardTime): number {
+  if ('simTicks' in budget) {
+    if (!Number.isInteger(budget.simTicks) || budget.simTicks < 0) {
+      throw new RangeError(
+        `game.fastForward: simTicks must be a non-negative integer, got ${budget.simTicks}`,
+      );
+    }
+    return budget.simTicks;
+  }
+  if (!Number.isFinite(budget.simSeconds) || budget.simSeconds < 0) {
+    throw new RangeError(`game.fastForward: simSeconds must be >= 0, got ${budget.simSeconds}`);
+  }
+  const fixedDt = observed.tick > 0 ? observed.simSeconds / observed.tick : DEFAULT_FIXED_DT;
+  return Math.ceil(budget.simSeconds / fixedDt);
+}
+
+/** Pure batch-size planner: splits `totalTicks` into chunks of at most
+ *  `batchTicks`, the LAST of which may be smaller (never any other position —
+ *  the driver marks exactly the last chunk "final" and applies the caller's
+ *  requested render mode only to it). Empty for `totalTicks <= 0`. */
+export function planFastForwardBatches(totalTicks: number, batchTicks: number): number[] {
+  if (totalTicks <= 0) return [];
+  const batches: number[] = [];
+  let remaining = totalTicks;
+  while (remaining > 0) {
+    const chunk = Math.min(batchTicks, remaining);
+    batches.push(chunk);
+    remaining -= chunk;
+  }
+  return batches;
+}
+
+/**
+ * Drives a `fastForward` call against `clock`: converts `budget` to an exact
+ * tick count (`ticksForBudget`), batches it (`planFastForwardBatches`), runs
+ * each batch through `runTicksBatch` (forcing `render: 'none'` on every batch
+ * but the last, which gets `opts.render ?? 'last'`), heartbeats once per
+ * batch, and returns the final observed `{tick, simSeconds}`. See the module
+ * doc for why batching and the render-mode split exist.
+ */
+export async function runFastForward(
+  budget: FastForwardBudget,
+  opts: FastForwardOptions,
+  clock: FastForwardClock,
+): Promise<FastForwardTime> {
+  const observed = await clock.readTime();
+  const totalTicks = ticksForBudget(budget, observed);
+  const batches = planFastForwardBatches(
+    totalTicks,
+    opts.batchTicks ?? DEFAULT_FAST_FORWARD_BATCH_TICKS,
+  );
+  const finalRender = opts.render ?? 'last';
+
+  let ticksDone = 0;
+  for (let i = 0; i < batches.length; i++) {
+    const size = batches[i] as number;
+    const isFinalBatch = i === batches.length - 1;
+    await clock.runTicksBatch(size, isFinalBatch ? finalRender : 'none');
+    ticksDone += size;
+    clock.heartbeat({ ticksDone, ticksTotal: totalTicks });
+  }
+
+  return clock.readTime();
+}