@driftengine/core 3.61.0

package/dist/build/shaderComments.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Keep the engine's shader commentary out of the bundle a consumer ships.
+ *
+ * **Build-time code.** It is not part of the runtime barrel and no game imports it; a
+ * consuming game's bundler configuration does. See AGENTS.md on where non-runtime code
+ * lives.
+ *
+ * The GLSL in `src/render/shaders/` is written inside template literals, which are
+ * *strings*: a minifier renames every identifier around them and does not touch a byte
+ * inside. So every consumer ships each shader exactly as it was authored, comments and
+ * all — and these shaders are heavily commented, because the reasoning behind a term is
+ * the part that is expensive to reconstruct.
+ *
+ * Measured on a production consumer that links 28 programs: 107 KB of a 300 KB chunk is
+ * GLSL, and 62 KB of that is commentary. Stripping it took the chunk from 98 KB to 73 KB
+ * gzipped. So this is a payload win of about a quarter as well as the point of the
+ * exercise, and the two arguments are independent — either one would justify it.
+ *
+ * What it deliberately does not do is obscure the shaders. They still compile from
+ * readable GLSL, because a shader that cannot be read in a driver's error log is a shader
+ * that cannot be debugged in the field. What leaves is the prose.
+ */
+/** A Vite plugin, described structurally so the engine takes no bundler dependency. */
+export interface ShaderCommentPlugin {
+    name: string;
+    apply: 'build';
+    enforce: 'pre';
+    transform(code: string, id: string): {
+        code: string;
+        map: null;
+    } | null;
+}
+export interface ShaderCommentOptions {
+    /**
+     * Which modules hold GLSL.
+     *
+     * Defaults to any module under a `shaders/` directory, which is where the engine keeps
+     * them however it has been vendored — `node_modules/@driftengine/core/src/render/shaders`
+     * for a symlinked consumer, `src/vendor/driftengine/render/shaders` for a copied one.
+     * A consumer with GLSL of its own can widen it.
+     */
+    include?: (id: string) => boolean;
+}
+/**
+ * Strip the comments from every GLSL template literal in a module's source.
+ *
+ * Template literals are found by regex rather than by parsing TypeScript. That is right
+ * for a file which is mostly one GLSL string and wrong in general — a stray backtick
+ * inside an ordinary string would pair with the wrong partner and the "span" would be
+ * code. Two things keep that from mattering: a span is only touched if it contains a GLSL
+ * marker, and `shaderComments.test.ts` runs this over every shader module in the
+ * repository and checks the result. The corpus is the real guard; the checks below are
+ * the cheap one.
+ */
+export declare function stripShaderComments(source: string): string;
+/**
+ * The plugin, for a consumer's bundler configuration.
+ *
+ * `apply: 'build'` so a dev server serves the shaders as written — that is where they are
+ * read and edited, and a stripped shader in devtools would cost exactly the debuggability
+ * this is careful to preserve everywhere else. `enforce: 'pre'` so it sees the module's
+ * own source rather than something another plugin has already rewritten.
+ */
+export declare function shaderCommentStripper(options?: ShaderCommentOptions): ShaderCommentPlugin;

package/dist/cinematic/player.d.ts

@@ -0,0 +1,80 @@
+import type { ShotParams } from '../render/cinematicCamera.ts';
+import type { CinematicLine, CinematicScript } from './script.ts';
+/**
+ * Plays a `CinematicScript`: a clock, the shot it is currently in, and the line
+ * that is currently up.
+ *
+ * It knows about time, camera placements and timed strings, and nothing else.
+ * Which shot suits which moment is the script's business, what a `look` means
+ * is the presentation's, and what any of it is *about* is the game's.
+ *
+ * Everything is derived from accumulated time rather than advanced per frame,
+ * so a script plays identically on a 144 Hz desktop and a phone dropping frames
+ * — a playback that steps an index per frame tells a different story at a
+ * different frame rate, and only one of the two was ever written down.
+ *
+ * The caller drives a `CinematicCamera` from it:
+ *
+ * ```ts
+ * player.update(dt);
+ * if (player.shotChanged) camera.cut(player.shot, player.timeSec);
+ * camera.update(dt, x, y, z, yaw);
+ * ```
+ *
+ * `shotChanged` is true only at a *cut*. A keyframed shot moves while it holds,
+ * and the object handed out by `shot` is a live view that keeps moving — so the
+ * rig damps its way along the authored path instead of snapping to it every
+ * frame. Copy it if you need to keep it past the next `update`.
+ */
+export declare class CinematicPlayer {
+    private readonly script;
+    private time;
+    private shotIndex;
+    private lineIndex;
+    private cut;
+    private current;
+    /**
+     * Scratch for keyframed shots, reused every frame. A cinematic is not a hot
+     * path in the sim sense, but it runs over a live world and a per-frame object
+     * is a per-frame collection somewhere later.
+     */
+    private readonly moving;
+    private readonly movingAnchor;
+    constructor(script: CinematicScript, name?: string);
+    get timeSec(): number;
+    get finished(): boolean;
+    /** The placement the camera should be holding, or null before the first shot. */
+    get shot(): ShotParams | null;
+    /** True on the frame a cut lands — the cue to `cut` the rig. */
+    get shotChanged(): boolean;
+    /** The one line on screen, or null. Never two: the script cannot express it. */
+    get line(): CinematicLine | null;
+    update(frameDt: number): void;
+    /**
+     * Straight to the end, holding nothing.
+     *
+     * Every returning player takes this path, so it has to leave the player inert
+     * rather than merely finished: a skip that leaves a cinematic shot behind
+     * hands somebody a run they cannot see.
+     */
+    skip(): void;
+    /** Back to the top, for a replay from the menu. */
+    reset(): void;
+    private clear;
+    /**
+     * Scanned from the start rather than advanced from the last index: the answer
+     * is then a function of the clock alone, which is what survives a `reset`, a
+     * long frame that crosses two cuts, and a script short enough that the scan
+     * costs less than the branch saving it would.
+     */
+    private selectShot;
+    private selectLine;
+    /**
+     * The placement `localSec` into a keyframed shot.
+     *
+     * Linear between keyframes, and deliberately not eased: the rig already damps
+     * its own motion, and easing each segment would stall the move at every key —
+     * a push-in that pulses instead of pushing.
+     */
+    private sample;
+}

package/dist/cinematic/player.js

@@ -0,0 +1,184 @@
+import { lerp } from '../math/scalar.js';
+import { validateCinematic } from './script.js';
+/**
+ * Plays a `CinematicScript`: a clock, the shot it is currently in, and the line
+ * that is currently up.
+ *
+ * It knows about time, camera placements and timed strings, and nothing else.
+ * Which shot suits which moment is the script's business, what a `look` means
+ * is the presentation's, and what any of it is *about* is the game's.
+ *
+ * Everything is derived from accumulated time rather than advanced per frame,
+ * so a script plays identically on a 144 Hz desktop and a phone dropping frames
+ * — a playback that steps an index per frame tells a different story at a
+ * different frame rate, and only one of the two was ever written down.
+ *
+ * The caller drives a `CinematicCamera` from it:
+ *
+ * ```ts
+ * player.update(dt);
+ * if (player.shotChanged) camera.cut(player.shot, player.timeSec);
+ * camera.update(dt, x, y, z, yaw);
+ * ```
+ *
+ * `shotChanged` is true only at a *cut*. A keyframed shot moves while it holds,
+ * and the object handed out by `shot` is a live view that keeps moving — so the
+ * rig damps its way along the authored path instead of snapping to it every
+ * frame. Copy it if you need to keep it past the next `update`.
+ */
+export class CinematicPlayer {
+    script;
+    time = 0;
+    shotIndex = -1;
+    lineIndex = -1;
+    cut = false;
+    current = null;
+    /**
+     * Scratch for keyframed shots, reused every frame. A cinematic is not a hot
+     * path in the sim sense, but it runs over a live world and a per-frame object
+     * is a per-frame collection somewhere later.
+     */
+    moving = { kind: 'chase', distance: 6, height: 2, fovDeg: 70 };
+    movingAnchor = [0, 0, 0];
+    constructor(script, name = 'cinematic') {
+        // Even a script that came through `defineCinematic` is checked again: the
+        // ordering and non-overlap rules are what make "the line right now" a
+        // single answer, and this is the object that relies on them.
+        validateCinematic(name, script);
+        this.script = script;
+    }
+    get timeSec() {
+        return this.time;
+    }
+    get finished() {
+        return this.time >= this.script.durationSec;
+    }
+    /** The placement the camera should be holding, or null before the first shot. */
+    get shot() {
+        return this.current;
+    }
+    /** True on the frame a cut lands — the cue to `cut` the rig. */
+    get shotChanged() {
+        return this.cut;
+    }
+    /** The one line on screen, or null. Never two: the script cannot express it. */
+    get line() {
+        return this.lineIndex < 0 ? null : this.script.lines[this.lineIndex];
+    }
+    update(frameDt) {
+        this.cut = false;
+        if (this.finished)
+            return;
+        this.time = Math.min(this.time + Math.max(0, frameDt), this.script.durationSec);
+        this.selectShot();
+        this.selectLine();
+    }
+    /**
+     * Straight to the end, holding nothing.
+     *
+     * Every returning player takes this path, so it has to leave the player inert
+     * rather than merely finished: a skip that leaves a cinematic shot behind
+     * hands somebody a run they cannot see.
+     */
+    skip() {
+        this.time = this.script.durationSec;
+        this.clear();
+    }
+    /** Back to the top, for a replay from the menu. */
+    reset() {
+        this.time = 0;
+        this.clear();
+    }
+    clear() {
+        this.shotIndex = -1;
+        this.lineIndex = -1;
+        this.current = null;
+        this.cut = false;
+    }
+    /**
+     * Scanned from the start rather than advanced from the last index: the answer
+     * is then a function of the clock alone, which is what survives a `reset`, a
+     * long frame that crosses two cuts, and a script short enough that the scan
+     * costs less than the branch saving it would.
+     */
+    selectShot() {
+        const shots = this.script.shots;
+        let index = -1;
+        for (let i = 0; i < shots.length; i++) {
+            if (shots[i].atSec > this.time)
+                break;
+            index = i;
+        }
+        if (index < 0) {
+            this.current = null;
+            return;
+        }
+        if (index !== this.shotIndex) {
+            this.shotIndex = index;
+            this.cut = true;
+        }
+        const camera = shots[index].camera;
+        this.current = 'kind' in camera ? camera : this.sample(camera, this.time - shots[index].atSec);
+    }
+    selectLine() {
+        const lines = this.script.lines;
+        let index = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.atSec > this.time)
+                break;
+            // The window is closed at its end, so a line and its successor cannot
+            // both claim the instant one hands over to the other.
+            if (this.time < line.atSec + line.holdSec) {
+                index = i;
+                break;
+            }
+        }
+        this.lineIndex = index;
+    }
+    /**
+     * The placement `localSec` into a keyframed shot.
+     *
+     * Linear between keyframes, and deliberately not eased: the rig already damps
+     * its own motion, and easing each segment would stall the move at every key —
+     * a push-in that pulses instead of pushing.
+     */
+    sample(frames, localSec) {
+        let index = 0;
+        for (let i = 0; i < frames.length; i++) {
+            if (frames[i].atSec > localSec)
+                break;
+            index = i;
+        }
+        const from = frames[index].camera;
+        const fromSec = frames[index].atSec;
+        const hasNext = index + 1 < frames.length;
+        const to = hasNext ? frames[index + 1].camera : from;
+        const span = hasNext ? frames[index + 1].atSec - fromSec : 0;
+        // Past the last keyframe a shot holds its final placement rather than
+        // running on; the timeline says when it ends.
+        const t = span > 0 ? Math.min(1, (localSec - fromSec) / span) : 1;
+        const moving = this.moving;
+        moving.kind = from.kind;
+        moving.distance = lerp(from.distance, to.distance, t);
+        moving.height = lerp(from.height, to.height, t);
+        moving.fovDeg = lerp(from.fovDeg, to.fovDeg, t);
+        const fromRate = from.orbitRate;
+        const toRate = to.orbitRate;
+        moving.orbitRate =
+            fromRate === undefined || toRate === undefined ? fromRate : lerp(fromRate, toRate, t);
+        const fromAnchor = from.anchor;
+        const toAnchor = to.anchor;
+        if (fromAnchor === undefined || toAnchor === undefined) {
+            moving.anchor = fromAnchor;
+        }
+        else {
+            const anchor = this.movingAnchor;
+            anchor[0] = lerp(fromAnchor[0], toAnchor[0], t);
+            anchor[1] = lerp(fromAnchor[1], toAnchor[1], t);
+            anchor[2] = lerp(fromAnchor[2], toAnchor[2], t);
+            moving.anchor = anchor;
+        }
+        return moving;
+    }
+}

package/dist/cinematic/script.d.ts

@@ -0,0 +1,63 @@
+import type { ShotParams } from '../render/cinematicCamera.ts';
+/**
+ * A cinematic, as data: when the camera cuts, and what is on screen when.
+ *
+ * A sequence is a *file*, not a function. That is the whole point of the split
+ * — a new season, a new trailer or a different cut of the same footage must be
+ * a data change, and the moment one of them needs a branch in TypeScript the
+ * boundary has moved to the wrong place.
+ *
+ * Which means data is where the mistakes will be, and this module is where they
+ * are caught. Everything a timeline can get wrong — two lines up at once, an
+ * entry written above the one it plays after, a keyframe past the end of the
+ * shot it belongs to — is rejected the moment the script is loaded, by name and
+ * by index. The alternative is a cinematic that silently drops its fourth line,
+ * which nobody notices until a player asks what it said.
+ *
+ * Nothing here knows what is being narrated. A shot is a placement, a line is a
+ * string with a window and a `look` the presentation layer resolves.
+ */
+/** One camera placement inside a shot. Times are from the shot's own start. */
+export interface CameraKeyframe {
+    readonly atSec: number;
+    readonly camera: ShotParams;
+}
+/**
+ * A cut, at `atSec`.
+ *
+ * A shot is either a fixed placement or a list of keyframes moved through while
+ * it holds. Keyframes are a *move*, never a second cut: they may not change the
+ * kind of shot, because that is a cut and belongs on the timeline where an
+ * editor can see it.
+ */
+export interface CinematicShot {
+    readonly atSec: number;
+    readonly camera: ShotParams | readonly CameraKeyframe[];
+}
+export interface CinematicLine {
+    readonly atSec: number;
+    readonly holdSec: number;
+    readonly text: string;
+    /** A presentation key — 'story', 'rule'. The player never resolves it. */
+    readonly look: string;
+}
+export interface CinematicScript {
+    readonly durationSec: number;
+    /** In play order. May be empty: a sequence of lines over live gameplay. */
+    readonly shots: readonly CinematicShot[];
+    /** In play order, non-overlapping. */
+    readonly lines: readonly CinematicLine[];
+}
+/**
+ * Validate a script and hand it back, so a data module fails on import:
+ *
+ * ```ts
+ * export const SEASON_ONE = defineCinematic('season1', { ... });
+ * ```
+ *
+ * Loud at load is the only useful moment. A malformed timeline cannot be
+ * repaired at runtime and must not be played half-right.
+ */
+export declare function defineCinematic(name: string, script: CinematicScript): CinematicScript;
+/** Throws on the first thing wrong, naming the entry and both times. */
+export declare function validateCinematic(name: string, script: CinematicScript): void;

package/dist/cinematic/script.js

@@ -0,0 +1,141 @@
+const SHOT_KINDS = ['chase', 'lowWide', 'orbit', 'flyby', 'overhead', 'lookAt'];
+/**
+ * Validate a script and hand it back, so a data module fails on import:
+ *
+ * ```ts
+ * export const SEASON_ONE = defineCinematic('season1', { ... });
+ * ```
+ *
+ * Loud at load is the only useful moment. A malformed timeline cannot be
+ * repaired at runtime and must not be played half-right.
+ */
+export function defineCinematic(name, script) {
+    validateCinematic(name, script);
+    return script;
+}
+/** Throws on the first thing wrong, naming the entry and both times. */
+export function validateCinematic(name, script) {
+    const fail = (message) => {
+        throw new Error(`cinematic "${name}": ${message}`);
+    };
+    const duration = script.durationSec;
+    if (!Number.isFinite(duration) || duration <= 0) {
+        fail(`runs for ${duration}s, which is not a length`);
+    }
+    validateShots(script, duration, fail);
+    validateLines(script, duration, fail);
+}
+function validateShots(script, duration, fail) {
+    const shots = script.shots;
+    for (let i = 0; i < shots.length; i++) {
+        const shot = shots[i];
+        if (!Number.isFinite(shot.atSec) || shot.atSec < 0) {
+            fail(`shot ${i} cuts at ${shot.atSec}s`);
+        }
+        if (i === 0 && shot.atSec !== 0) {
+            fail(`shot 0 cuts at ${shot.atSec}s — the camera has nowhere to be before it`);
+        }
+        if (i > 0 && shot.atSec <= shots[i - 1].atSec) {
+            fail(`shot ${i} cuts at ${shot.atSec}s, at or before shot ${i - 1} at ` +
+                `${shots[i - 1].atSec}s — shots must be written in the order they play`);
+        }
+        if (shot.atSec >= duration) {
+            fail(`shot ${i} cuts at ${shot.atSec}s, after the script ends at ${duration}s`);
+        }
+        // How long this shot holds — what a keyframe inside it has to fit within.
+        const span = (i + 1 < shots.length ? shots[i + 1].atSec : duration) - shot.atSec;
+        validateCamera(shot.camera, span, i, fail);
+    }
+}
+function validateCamera(camera, spanSec, index, fail) {
+    if ('kind' in camera) {
+        validateShotParams(camera, `shot ${index}`, fail);
+        return;
+    }
+    if (camera.length === 0)
+        fail(`shot ${index} is keyframed but has no keyframes`);
+    const first = camera[0];
+    if (first.atSec !== 0) {
+        fail(`shot ${index} keyframe 0 is at ${first.atSec}s — a move must start where the cut lands`);
+    }
+    for (let i = 0; i < camera.length; i++) {
+        const frame = camera[i];
+        const where = `shot ${index} keyframe ${i}`;
+        if (!Number.isFinite(frame.atSec) || frame.atSec < 0)
+            fail(`${where} is at ${frame.atSec}s`);
+        if (i > 0 && frame.atSec <= camera[i - 1].atSec) {
+            fail(`${where} is at ${frame.atSec}s, at or before keyframe ${i - 1} at ` +
+                `${camera[i - 1].atSec}s — keyframes must be written in the order they play`);
+        }
+        if (frame.atSec > spanSec) {
+            fail(`${where} is at ${frame.atSec}s but the shot holds ${spanSec}s — it would never play`);
+        }
+        if (frame.camera.kind !== first.camera.kind) {
+            fail(`${where} changes the shot from ${first.camera.kind} to ${frame.camera.kind} — ` +
+                'a change of kind is a cut, and cuts belong on the timeline');
+        }
+        /*
+         * An optional parameter has to be on every keyframe of a shot or none of
+         * them. Interpolating toward a missing anchor would send the shot to the
+         * world origin, which reads as the camera being thrown rather than as a
+         * mistake in the data.
+         */
+        if ((frame.camera.anchor === undefined) !== (first.camera.anchor === undefined)) {
+            fail(`${where} adds or drops an anchor mid-move`);
+        }
+        if ((frame.camera.orbitRate === undefined) !== (first.camera.orbitRate === undefined)) {
+            fail(`${where} adds or drops an orbit rate mid-move`);
+        }
+        validateShotParams(frame.camera, where, fail);
+    }
+}
+function validateShotParams(shot, where, fail) {
+    if (!SHOT_KINDS.includes(shot.kind))
+        fail(`${where} is a "${shot.kind}" shot, which is not a shot`);
+    for (const [label, value] of [
+        ['distance', shot.distance],
+        ['height', shot.height],
+        ['fovDeg', shot.fovDeg],
+    ]) {
+        if (!Number.isFinite(value))
+            fail(`${where} has ${label} ${value}`);
+    }
+    if (shot.orbitRate !== undefined && !Number.isFinite(shot.orbitRate)) {
+        fail(`${where} has orbitRate ${shot.orbitRate}`);
+    }
+    const anchor = shot.anchor;
+    if (anchor !== undefined && (anchor.length !== 3 || !anchor.every(Number.isFinite))) {
+        fail(`${where} has an anchor that is not three finite numbers`);
+    }
+}
+function validateLines(script, duration, fail) {
+    const lines = script.lines;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.text.length === 0)
+            fail(`line ${i} has nothing to say`);
+        if (line.look.length === 0)
+            fail(`line ${i} ("${line.text}") has no look`);
+        if (!Number.isFinite(line.atSec) || line.atSec < 0) {
+            fail(`line ${i} ("${line.text}") opens at ${line.atSec}s`);
+        }
+        if (!Number.isFinite(line.holdSec) || line.holdSec <= 0) {
+            fail(`line ${i} ("${line.text}") holds for ${line.holdSec}s`);
+        }
+        if (i > 0) {
+            const previous = lines[i - 1];
+            if (line.atSec <= previous.atSec) {
+                fail(`line ${i} ("${line.text}") opens at ${line.atSec}s, at or before line ${i - 1} at ` +
+                    `${previous.atSec}s — lines must be written in the order they play`);
+            }
+            if (line.atSec < previous.atSec + previous.holdSec) {
+                fail(`line ${i} ("${line.text}") opens at ${line.atSec}s while line ${i - 1} is still up ` +
+                    `until ${previous.atSec + previous.holdSec}s — two lines at once is unreadable`);
+            }
+        }
+        if (line.atSec + line.holdSec > duration) {
+            fail(`line ${i} ("${line.text}") is still up at ${line.atSec + line.holdSec}s, ` +
+                `after the script ends at ${duration}s`);
+        }
+    }
+}

package/dist/core/bootGate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The one bit of state the fixed loop and the engine badge have to share.
+ *
+ * **The problem it solves.** The badge holds the screen for a few seconds after the game's first
+ * frame reaches it — deliberately, because the badge is a hold and not merely a cover. Without a
+ * gate the game is *running* for that whole time behind an opaque black plate: an intro animation
+ * plays to nobody, a music cue starts and is three seconds in by the time anyone hears it, and a
+ * countdown is already counting. Every one of those is content the player paid for and did not
+ * get.
+ *
+ * So the loop freezes on the frame it just drew, and resumes when the plate is gone.
+ *
+ * **Why a module-level holder rather than a parameter.** `createRenderer` mounts the badge and
+ * `startLoop` runs the loop, and a consumer calls them separately with nothing passed between —
+ * threading a handle through would make this a thing every game has to wire, which is the whole
+ * failure the default-on badge exists to avoid. There is exactly one screen, so there is exactly
+ * one badge, and a singleton is the honest shape for it rather than a convenience.
+ *
+ * **`ui/` writes it and `core/` reads it**, which is why the state lives here rather than in
+ * `ui/splash.ts`: the fixed loop must not import a module that touches the DOM. This file names
+ * neither of them and knows only that something may be holding frames back.
+ */
+/**
+ * Register what decides whether frames are held, and hand back the way to stop deciding.
+ *
+ * The last registration wins, and releasing only clears the gate if it is still yours — two
+ * badges cannot exist at once, but a badge that was released after a second one mounted must
+ * not open a gate it no longer owns.
+ */
+export declare function holdFrames(frozen: () => boolean): () => void;
+/**
+ * Whether this frame should be skipped entirely.
+ *
+ * A null check and at most one call, per frame, for the handful of frames a badge is up and none
+ * at all afterwards — the badge clears the holder when it leaves. Nothing here allocates.
+ */
+export declare function framesHeld(): boolean;

package/dist/core/bootGate.js

@@ -0,0 +1,47 @@
+/**
+ * The one bit of state the fixed loop and the engine badge have to share.
+ *
+ * **The problem it solves.** The badge holds the screen for a few seconds after the game's first
+ * frame reaches it — deliberately, because the badge is a hold and not merely a cover. Without a
+ * gate the game is *running* for that whole time behind an opaque black plate: an intro animation
+ * plays to nobody, a music cue starts and is three seconds in by the time anyone hears it, and a
+ * countdown is already counting. Every one of those is content the player paid for and did not
+ * get.
+ *
+ * So the loop freezes on the frame it just drew, and resumes when the plate is gone.
+ *
+ * **Why a module-level holder rather than a parameter.** `createRenderer` mounts the badge and
+ * `startLoop` runs the loop, and a consumer calls them separately with nothing passed between —
+ * threading a handle through would make this a thing every game has to wire, which is the whole
+ * failure the default-on badge exists to avoid. There is exactly one screen, so there is exactly
+ * one badge, and a singleton is the honest shape for it rather than a convenience.
+ *
+ * **`ui/` writes it and `core/` reads it**, which is why the state lives here rather than in
+ * `ui/splash.ts`: the fixed loop must not import a module that touches the DOM. This file names
+ * neither of them and knows only that something may be holding frames back.
+ */
+/** What is holding frames, if anything. Set by the badge, read by the loop. */
+let holder = null;
+/**
+ * Register what decides whether frames are held, and hand back the way to stop deciding.
+ *
+ * The last registration wins, and releasing only clears the gate if it is still yours — two
+ * badges cannot exist at once, but a badge that was released after a second one mounted must
+ * not open a gate it no longer owns.
+ */
+export function holdFrames(frozen) {
+    holder = frozen;
+    return () => {
+        if (holder === frozen)
+            holder = null;
+    };
+}
+/**
+ * Whether this frame should be skipped entirely.
+ *
+ * A null check and at most one call, per frame, for the handful of frames a badge is up and none
+ * at all afterwards — the badge clears the holder when it leaves. Nothing here allocates.
+ */
+export function framesHeld() {
+    return holder !== null && holder();
+}