@bitmagic/cli 0.1.37 → 0.1.39

package/dist/verify/classify.d.ts

@@ -27,6 +27,62 @@ export interface CanvasFrameObservation {
      */
     distinctColors: number;
 }
+/** Which renderer the run asked for and what actually drove the canvas. */
+export interface RendererObservation {
+    /** The `?renderer=` value verify booted the game with. */
+    requested: 'webgpu' | 'webgl';
+    /**
+     * `engine.getRendererType()` — which renderer CLASS the engine constructed (⇒ TSL vs GLSL
+     * material pipeline). Null when the engine or the getter could not be reached (older engine,
+     * probe failed): "not observed", never a failure by itself.
+     */
+    rendererType: string | null;
+    /**
+     * `engine.getActiveBackend()` — what is actually driving the canvas. The load-bearing one:
+     * a WebGPURenderer whose adapter never came up silently runs `'webgl2'`, and only this getter
+     * can tell. Null means "not observed", same contract as `rendererType`.
+     */
+    backend: string | null;
+}
+/**
+ * A snapshot of live engine state at the end of the run, read through `window.gameTemplate`.
+ *
+ * Every field is null when it could not be observed (older engine, probe failure) and classifies
+ * as "not observed", never as a failure — same contract as `RendererObservation`. What this buys
+ * over the console log: the console only says what the engine chose to print; this says what the
+ * running game actually IS.
+ */
+export interface StateSnapshot {
+    /** `gameStateManager.getCurrentState()` — lowercase engine values ('playing', 'menu', …). */
+    gameState: string | null;
+    hasStarted: boolean | null;
+    /** Engine clock seconds since boot. */
+    elapsedTimeSeconds: number | null;
+    /** Rendered frames per second across the final settle polls — page rAF rate, so it proves the
+     *  page's loop is alive rather than measuring render quality. */
+    fps: number | null;
+    player: {
+        x: number;
+        y: number;
+        z: number;
+        isFalling: boolean;
+    } | null;
+    physics: {
+        rigidBodyCount: number;
+        colliderCount: number;
+    } | null;
+    scene: {
+        objects: number;
+        meshes: number;
+        lights: number;
+    } | null;
+    npcCount: number | null;
+}
+/** How the settle ended: early because the game was provably stable, or at the `--timeout` cap. */
+export interface SettleObservation {
+    durationMs: number;
+    reason: 'stable' | 'timeout';
+}
 /** What the start interaction (waiting for and clicking the engine Play button) observed. */
 export interface StartObservations {
     playButtonSeen: boolean;
@@ -41,8 +97,9 @@ export interface VerifyObservations {
     consoleLines: string[];
     pageErrors: string[];
     canvas: CanvasObservation | null;
-    /** Byte length of the PNG screenshot taken after settling. */
-    screenshotBytes: number;
+    /** Byte length of the PNG screenshot taken after settling, or null when the run was asked not
+     *  to capture one (`--fast`) — "not observed", never "blank". */
+    screenshotBytes: number | null;
     /**
      * The page fired `webglcontextlost`. The renderer is dead from that moment: rAF keeps firing,
      * the engine logs its usual lines, the DOM HUD still paints, and nothing else gives it away.
@@ -60,10 +117,26 @@ export interface VerifyObservations {
     /** Only present when the run was asked to perform the start interaction (`bitmagic verify`);
      *  `publish`'s smoke check never sets it and classifies exactly as before. */
     start?: StartObservations;
+    /** Only present when the run was told which renderer it booted (`bitmagic verify` passes its
+     *  `--renderer` choice); `publish`'s smoke check never sets it and classifies exactly as before. */
+    renderer?: RendererObservation;
+    /** End-of-run engine state. Present on `bitmagic verify` runs against a reachable page; null
+     *  when the probe failed outright, absent on the smoke check. */
+    snapshot?: StateSnapshot | null;
+    /** How the settle ended. Only present when the run settled adaptively (`bitmagic verify`). */
+    settle?: SettleObservation;
 }
 export interface VerifyResult {
     ok: boolean;
     failures: string[];
     warnings: string[];
 }
+/**
+ * The engine's line when the player has fallen out of the world and is being put back.
+ *
+ * A game the player cannot stand up in is not verified, however cleanly it renders. This was not
+ * theoretical: a forged level whose terrain never loaded rendered a perfect frame, threw nothing,
+ * and reported PASSED, while the player fell and respawned 14 times in a 45s settle.
+ */
+export declare const RESPAWN_LINE = "Fell below -100";
 export declare function classifyVerifyRun(observations: VerifyObservations): VerifyResult;

package/dist/verify/classify.js

@@ -60,7 +60,7 @@ const MIN_DISTINCT_COLORS = 3;
  * theoretical: a forged level whose terrain never loaded rendered a perfect frame, threw nothing,
  * and reported PASSED, while the player fell and respawned 14 times in a 45s settle.
  */
-const RESPAWN_LINE = 'Fell below -100';
+export const RESPAWN_LINE = 'Fell below -100';
 /**
  * One or two falls can be the spawn beating the chunk colliders — the controller says as much
  * ("waiting for colliders…") and recovers, so those warn. Three is no longer a settle; it is a
@@ -74,6 +74,13 @@ const MAX_TOLERATED_RESPAWNS = 2;
  * only evidence was this line, which nothing was reading.
  */
 const CORS_BLOCK = 'has been blocked by CORS policy';
+/**
+ * A player below this and still falling when the run ends is out of the world, not exploring a
+ * deep cave: the engine's own kill plane respawns at -100, so a sustained fall past -50 means
+ * the respawn keeps landing on nothing. Complements the `RESPAWN_LINE` count — this one fires
+ * even when a game's custom controller never prints that line.
+ */
+const FREEFALL_FAILURE_Y = -50;
 export function classifyVerifyRun(observations) {
     const failures = [];
     const warnings = [];
@@ -102,6 +109,18 @@ export function classifyVerifyRun(observations) {
             warnings.push('The game started but the start menu was still visible when the run ended.');
         }
     }
+    const { renderer } = observations;
+    if (renderer && renderer.requested === 'webgpu') {
+        if (renderer.backend === 'webgl2') {
+            failures.push('WebGPU was requested but the renderer silently fell back to WebGL2 — the WebGPU path '
+                + 'was not verified. Run `bitmagic verify --renderer webgl` to verify the WebGL path '
+                + 'deliberately, or fix WebGPU availability in this environment.');
+        }
+        else if (renderer.backend === null) {
+            warnings.push('Could not observe which backend drove the canvas (older engine or probe failure) — '
+                + 'the WebGPU path may or may not have been exercised.');
+        }
+    }
     const { canvas } = observations;
     if (!canvas) {
         failures.push('No <canvas> was rendered inside #game-container — the game did not start.');
@@ -115,7 +134,7 @@ export function classifyVerifyRun(observations) {
                 `${UNTOUCHED_CANVAS_HEIGHT} HTML default) — nothing claimed it.`);
         }
     }
-    if (observations.screenshotBytes < MIN_SCREENSHOT_BYTES) {
+    if (observations.screenshotBytes !== null && observations.screenshotBytes < MIN_SCREENSHOT_BYTES) {
         failures.push(`The screenshot is implausibly small (${observations.screenshotBytes} bytes) — the frame ` +
             'looks blank.');
     }
@@ -164,6 +183,33 @@ export function classifyVerifyRun(observations) {
             warnings.push(`Expected "${marker}" in the console and did not see it.`);
         }
     }
+    // Live-state checks. All skipped when the snapshot is null/absent — "not observed" is never a
+    // failure, and everything above already covers the page that could not be probed at all.
+    const snapshot = observations.snapshot;
+    if (snapshot) {
+        const { player } = snapshot;
+        if (player !== null && player.isFalling && player.y < FREEFALL_FAILURE_Y) {
+            failures.push(`The player was still falling when the run ended (at y=${Math.round(player.y)}) — the `
+                + 'level renders but cannot be stood on. Its terrain most likely never loaded.');
+        }
+        if (snapshot.fps === 0) {
+            // Software WebGPU is the measured way to get here without a broken game: SwiftShader
+            // brings the adapter up and then freezes at game start, so the backend probe looks fine.
+            const hint = observations.renderer?.requested === 'webgpu'
+                ? ' On a machine without a usable GPU (CI), the WebGPU path can freeze under software '
+                    + 'rendering — run with --renderer webgl there.'
+                : '';
+            failures.push('The page\'s render loop stalled — no frames were produced across the final stretch of '
+                + `the run, however healthy the console looks.${hint}`);
+        }
+        if (observations.start?.gameStartDetected === true
+            && snapshot.gameState !== null
+            && snapshot.gameState !== 'playing'
+            && snapshot.gameState !== 'end') {
+            warnings.push(`The game started but ended the run in state "${snapshot.gameState}" instead of playing `
+                + '— it bounced back out of gameplay.');
+        }
+    }
     return { ok: failures.length === 0, failures, warnings };
 }
 //# sourceMappingURL=classify.js.map

package/dist/verify/classify.js.map

@@ -1 +1 @@
-{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/verify/classify.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/verify/classify.ts"],"names":[],"mappings":"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"}

package/dist/verify/iterate.d.ts

@@ -0,0 +1,47 @@
+import { type RendererChoice } from '../browser-gl.js';
+import type { Output } from '../output.js';
+import { type VerifyObservations } from './classify.js';
+/**
+ * Runs verify iterations one at a time. A change that lands mid-iteration queues exactly one
+ * follow-up — not one per change, because the follow-up will see all of them anyway.
+ *
+ * Extracted pure (no timers, no I/O beyond the injected runner) so the rerun-on-change-during-run
+ * behaviour is testable the way `ReloadCoordinator`'s is.
+ */
+export declare class VerifyIterationScheduler {
+    private readonly run;
+    /** Where a detached follow-up's failure goes — `request` only rethrows for its own caller. */
+    private readonly onError;
+    private running;
+    private queued;
+    constructor(run: (reason: string) => Promise<void>, 
+    /** Where a detached follow-up's failure goes — `request` only rethrows for its own caller. */
+    onError?: (error: unknown) => void);
+    /**
+     * Resolves when THIS request's iteration completes (or immediately, if it was queued behind a
+     * running one). A queued follow-up runs detached — awaiting it here would make the first
+     * caller's promise hostage to work it never asked for.
+     */
+    request(reason: string): Promise<void>;
+}
+export interface VerifyWatchOptions {
+    root: string;
+    /** Path to the project's `tsc` binary (for `tsc --watch`). */
+    tsc: string;
+    artifactDir: string;
+    consolePath: string;
+    screenshotPath: string;
+    /** The vite dev server's port — already up; the loop only builds URLs from it. */
+    port: number;
+    renderer: RendererChoice;
+    settleMs: number;
+    /** Skip the screenshot pipeline (default in watch mode). */
+    fast: boolean;
+    output: Output;
+    describeRunState: (observations: VerifyObservations) => string;
+}
+/**
+ * Run the watch loop until SIGINT/SIGTERM. The caller owns vite; everything spawned here —
+ * `tsc --watch`, the file watcher, the browser session — is cleaned up before returning.
+ */
+export declare function runVerifyWatch(options: VerifyWatchOptions): Promise<void>;

package/dist/verify/iterate.js

@@ -0,0 +1,162 @@
+/**
+ * `bitmagic verify --watch`: the warm inner loop.
+ *
+ * One-shot verify pays Chrome launch + full tsc build + vite spawn on every run — most of a
+ * minute before the game is even observed. The watch loop pays each of those once: `tsc --watch`
+ * keeps the build incremental, vite stays up (the command owns it, like one-shot), and one
+ * launched Chrome runs every iteration in a fresh browser context. What triggers an iteration is
+ * `editor/watch.ts`'s coordinator — the same debounce + compile gate `bitmagic dev` uses, so an
+ * agent's five-file edit burst becomes one re-verify, and a red build reports its type errors
+ * instead of wasting a browser run on the previous emit.
+ */
+import * as path from 'path';
+import { browserRendererArgs, shouldRetrySoftwareGl } from '../browser-gl.js';
+import { ReloadCoordinator, pipeTscWatch, watchProject } from '../editor/watch.js';
+import { computeFingerprint } from '../publish/fingerprint.js';
+import { VerifyBrowserSession, DEFAULT_START_INTERACTION } from './browser.js';
+import { classifyVerifyRun } from './classify.js';
+import { decideVerifyOutcome, writeVerifyRecord } from './result.js';
+/**
+ * Runs verify iterations one at a time. A change that lands mid-iteration queues exactly one
+ * follow-up — not one per change, because the follow-up will see all of them anyway.
+ *
+ * Extracted pure (no timers, no I/O beyond the injected runner) so the rerun-on-change-during-run
+ * behaviour is testable the way `ReloadCoordinator`'s is.
+ */
+export class VerifyIterationScheduler {
+    run;
+    onError;
+    running = false;
+    queued = null;
+    constructor(run, 
+    /** Where a detached follow-up's failure goes — `request` only rethrows for its own caller. */
+    onError = () => { }) {
+        this.run = run;
+        this.onError = onError;
+    }
+    /**
+     * Resolves when THIS request's iteration completes (or immediately, if it was queued behind a
+     * running one). A queued follow-up runs detached — awaiting it here would make the first
+     * caller's promise hostage to work it never asked for.
+     */
+    async request(reason) {
+        if (this.running) {
+            this.queued = reason;
+            return;
+        }
+        this.running = true;
+        try {
+            await this.run(reason);
+        }
+        finally {
+            this.running = false;
+            const queued = this.queued;
+            this.queued = null;
+            if (queued !== null) {
+                void this.request(queued).catch((error) => this.onError(error));
+            }
+        }
+    }
+}
+/**
+ * Run the watch loop until SIGINT/SIGTERM. The caller owns vite; everything spawned here —
+ * `tsc --watch`, the file watcher, the browser session — is cleaned up before returning.
+ */
+export async function runVerifyWatch(options) {
+    const { output } = options;
+    let session = await VerifyBrowserSession.launch(browserRendererArgs(process.env, options.renderer));
+    // Sticky across iterations: once one run loses its context and the software re-run works,
+    // every following iteration goes straight to software instead of failing GPU-first each time.
+    let onSoftwareGl = false;
+    const reportIterationError = (error) => {
+        // An iteration that throws (page never loaded, browser died) must not kill the loop — the
+        // next edit deserves its verify. Say what happened and keep watching.
+        const message = error instanceof Error ? error.message : String(error);
+        output.info(`✗ verify iteration failed: ${message}`);
+    };
+    const scheduler = new VerifyIterationScheduler(async (reason) => {
+        const startedAt = Date.now();
+        // Before the check, not after: this names the state the browser is about to load. A file
+        // that changes mid-run makes the record stale, and the coordinator immediately queues the
+        // iteration that will re-verify it.
+        const fingerprint = computeFingerprint(options.root);
+        const checkOptions = {
+            url: `http://localhost:${options.port}/?renderer=${options.renderer}`,
+            screenshotPath: options.screenshotPath,
+            consolePath: options.consolePath,
+            settleMs: options.settleMs,
+            startInteraction: DEFAULT_START_INTERACTION,
+            requestedRenderer: options.renderer,
+            captureScreenshot: !options.fast,
+        };
+        let observations = await session.check(checkOptions);
+        let result = classifyVerifyRun(observations);
+        let retriedWithSoftwareGl = false;
+        if (!result.ok && !onSoftwareGl && shouldRetrySoftwareGl(observations, process.env)) {
+            output.info('The WebGL context was lost — switching this watch to software rendering…');
+            await session.close();
+            session = await VerifyBrowserSession.launch(browserRendererArgs({ ...process.env, BITMAGIC_BROWSER_SOFTWARE_GL: 'true' }, options.renderer));
+            onSoftwareGl = true;
+            retriedWithSoftwareGl = true;
+            observations = await session.check({
+                ...checkOptions,
+                consolePath: path.join(options.artifactDir, 'console.retry.log'),
+            });
+            result = classifyVerifyRun(observations);
+        }
+        const outcome = decideVerifyOutcome(result, fingerprint, new Date().toISOString(), {
+            renderer: observations.renderer,
+            settle: observations.settle,
+            snapshot: observations.snapshot,
+            ...(retriedWithSoftwareGl ? { retriedWithSoftwareGl } : {}),
+        });
+        // Recorded but never thrown: a failing iteration is information for the next edit, not the
+        // end of the loop. Publish still gates on this record exactly as it does after one-shot.
+        writeVerifyRecord(options.artifactDir, outcome.record);
+        const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+        if (result.ok) {
+            output.info(`✓ verified in ${seconds}s (${reason}) — ${options.describeRunState(observations)}`);
+        }
+        else {
+            for (const failure of result.failures)
+                output.info(`✗ ${failure}`);
+            output.info(`✗ ${result.failures.length} failure${result.failures.length === 1 ? '' : 's'} in `
+                + `${seconds}s (${reason})`);
+        }
+    }, reportIterationError);
+    let firstBuildSeen = false;
+    const coordinator = new ReloadCoordinator({
+        onReload: (reason) => {
+            void scheduler.request(reason).catch(reportIterationError);
+        },
+        onBuild: (status, message) => {
+            if (status === 'failed' && message !== undefined) {
+                output.info(`✗ ${message}`);
+                return;
+            }
+            if (status === 'ok' && !firstBuildSeen) {
+                // The first clean compile is the loop's starting gun; after that, only file changes
+                // (gated on their own compiles) trigger iterations.
+                firstBuildSeen = true;
+                coordinator.noteFileChange('initial build');
+            }
+        },
+    });
+    const tscWatch = pipeTscWatch(options.tsc, options.root, coordinator);
+    const watcher = watchProject(options.root, coordinator, (message) => output.info(message));
+    output.info('Watching for changes — Ctrl-C to stop.');
+    try {
+        await new Promise((resolve) => {
+            const stop = () => resolve();
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+        });
+    }
+    finally {
+        coordinator.stop();
+        watcher.close();
+        tscWatch.kill('SIGTERM');
+        await session.close();
+    }
+}
+//# sourceMappingURL=iterate.js.map

package/dist/verify/iterate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterate.js","sourceRoot":"","sources":["../../src/verify/iterate.ts"],"names":[],"mappings":"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"}

package/dist/verify/result.d.ts

@@ -1,4 +1,4 @@
-import type { VerifyResult } from './classify.js';
+import type { RendererObservation, SettleObservation, StateSnapshot, VerifyResult } from './classify.js';
 export declare const VERIFY_RESULT_FILENAME = "result.json";
 /**
  * What `bitmagic verify` observed, written so `bitmagic publish` can gate on it.
@@ -13,6 +13,19 @@ export interface VerifyRunRecord {
     fingerprint: string;
     /** ISO 8601. Reported to the creator; never used to decide staleness. */
     at: string;
+    /**
+     * Which renderer was requested and what actually drove the canvas. Optional — `isRecord` must
+     * not require it, so records written by older CLI versions keep parsing (publish gates on this
+     * file across versions).
+     */
+    renderer?: RendererObservation;
+    /** The run failed on a lost WebGL context and was automatically re-run once on software GL;
+     *  the recorded verdict is the retry's. Optional for the same cross-version reason. */
+    retriedWithSoftwareGl?: boolean;
+    /** How the settle ended: early on provable stability, or at the `--timeout` cap. */
+    settle?: SettleObservation;
+    /** Live engine state at the end of the run — what the agent reads instead of pixels. */
+    snapshot?: StateSnapshot | null;
 }
 export declare function writeVerifyRecord(artifactDir: string, record: VerifyRunRecord): void;
 /**
@@ -33,7 +46,7 @@ export declare function readVerifyRecord(artifactDir: string): VerifyRunRecord |
  * different messages and different remedies. Inside `run()` that ordering is only observable by
  * spawning vite and a browser, which is why it went unguarded.
  */
-export declare function decideVerifyOutcome(result: VerifyResult, fingerprint: string, at: string): {
+export declare function decideVerifyOutcome(result: VerifyResult, fingerprint: string, at: string, extras?: Pick<VerifyRunRecord, 'renderer' | 'retriedWithSoftwareGl' | 'settle' | 'snapshot'>): {
     record: VerifyRunRecord;
     shouldThrow: boolean;
 };
@@ -56,5 +69,5 @@ export declare function recordAndGateVerify(artifactDir: string, outcome: {
     shouldThrow: boolean;
 }, paths: {
     consolePath: string;
-    screenshotPath: string;
+    screenshotPath?: string;
 }, reporter: VerifyReporter): void;

package/dist/verify/result.js

@@ -44,9 +44,16 @@ export function readVerifyRecord(artifactDir) {
  * different messages and different remedies. Inside `run()` that ordering is only observable by
  * spawning vite and a browser, which is why it went unguarded.
  */
-export function decideVerifyOutcome(result, fingerprint, at) {
+export function decideVerifyOutcome(result, fingerprint, at, extras) {
     return {
-        record: { ok: result.ok, failures: result.failures, warnings: result.warnings, fingerprint, at },
+        record: {
+            ok: result.ok,
+            failures: result.failures,
+            warnings: result.warnings,
+            fingerprint,
+            at,
+            ...extras,
+        },
         shouldThrow: !result.ok,
     };
 }
@@ -66,7 +73,10 @@ export function recordAndGateVerify(artifactDir, outcome, paths, reporter) {
     if (outcome.shouldThrow) {
         for (const failure of outcome.record.failures)
             reporter.error(`✗ ${failure}`);
-        reporter.error(`\nArtifacts: ${paths.consolePath}, ${paths.screenshotPath}`);
+        // screenshotPath is absent on a `--fast` run, which captures none — listing it would point
+        // the reader at a file that does not exist (or worse, a stale one from an earlier run).
+        const artifacts = [paths.consolePath, paths.screenshotPath].filter((p) => p !== undefined);
+        reporter.error(`\nArtifacts: ${artifacts.join(', ')}`);
         throw new CliError('Verification failed.');
     }
     reporter.info(`Verification passed. Artifacts in ${artifactDir}`);

package/dist/verify/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/verify/result.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/verify/result.ts"],"names":[],"mappings":"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"}

package/dist/verify/settle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The decision "has the game settled enough to observe", extracted pure so it is testable
+ * without a browser.
+ *
+ * Verify used to wait a fixed 15 seconds regardless of what the game was doing. The samples the
+ * browser loop feeds this function come from the live engine (`window.gameTemplate`), so a
+ * healthy game that reaches gameplay and holds steady is observed after ~4-5 seconds, while the
+ * fixed `--timeout` stays as the hard cap for games that never stabilise. An engine too old to
+ * answer the probes never settles early — it gets exactly the old fixed-wait behaviour.
+ */
+/** One poll of the live page, taken every `SETTLE_POLL_MS` during the settle. */
+export interface SettleSample {
+    /** ms since the settle began. */
+    atMs: number;
+    /** `window.__bitmagicFrameCount` — rAF ticks since page load, injected by verify's init
+     *  script. Null when the page could not be evaluated. */
+    frameCount: number | null;
+    /** `engine.gameStateManager.getCurrentState()` — lowercase engine values ('menu', 'loading',
+     *  'ready', 'playing', 'paused', 'end'). Null when unobservable (older engine, no manager). */
+    gameState: string | null;
+    /** `engine.gameStateManager.hasStarted()`. Null when unobservable. */
+    hasStarted: boolean | null;
+    /** Player world-Y. Null when there is no player to ask (menu, loading, engine too old). */
+    playerY: number | null;
+    /** Console error lines + player-fell-out-of-world lines seen so far. Monotonic; a rise
+     *  between samples means the game is still misbehaving. */
+    errorEventCount: number;
+}
+export interface SettleConfig {
+    /** Never settle before this — engines finish async spawns (NPCs, deferred GLBs) well after
+     *  gameplay starts, and a too-early observation would miss them. */
+    minSettleMs: number;
+    /** Frames the page must have rendered — proves a live render loop, not just a live DOM. */
+    minFrames: number;
+    /** How long the error counters must have been flat. */
+    quietMs: number;
+}
+export declare const DEFAULT_SETTLE_CONFIG: SettleConfig;
+export declare const SETTLE_POLL_MS = 500;
+/**
+ * The player is in sustained freefall at the end of `samples`.
+ *
+ * Judged over the trailing samples that HAVE a player position; unobservable positions mean
+ * "cannot tell", never "falling". Exported because the final state snapshot reports the same
+ * judgement as `player.isFalling`.
+ */
+export declare function isFreefalling(samples: SettleSample[]): boolean;
+/**
+ * True when the run has seen enough to stop settling early.
+ *
+ * Every condition must hold on the latest sample:
+ * - the minimum settle floor has passed;
+ * - gameplay is actually running — state 'playing' or 'end' (a run-to-completion minigame), or
+ *   `hasStarted` when the state manager is not observable. Both unobservable → never settle
+ *   early; the fixed timeout is the correct behaviour for an engine that cannot be asked;
+ * - the page has rendered enough frames to prove a live render loop;
+ * - the error counters have been flat for the quiet window;
+ * - the player is not falling out of the world.
+ */
+export declare function settleVerdict(samples: SettleSample[], config: SettleConfig): 'settled' | 'keep-waiting';