@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/scene/sequenceDirector.d.ts

@@ -0,0 +1,110 @@
+/** One scheduled beat of a cutscene: a typed cue that fires when the playhead reaches `atMs`. */
+export interface SequenceCue<Payload = unknown> {
+    /** Playhead time (ms from the start of the timeline) at which this cue fires. Must be `>= 0`. */
+    atMs: number;
+    /**
+     * Free-string tag naming what this cue is — `"camera"`, `"dialogue"`, `"fade"`, anything.
+     * The director never interprets it; the game switches on `kind` to act on the {@link SequenceCue.payload}.
+     */
+    kind: string;
+    /** Arbitrary serializable data the game reads when the cue fires. Opaque to the director. */
+    payload?: Payload;
+    /** Optional stable id, surfaced on emission and useful for logging/debugging. */
+    id?: string;
+}
+/** A cue plus the resolved firing context passed to {@link SequenceDirector.onCue} listeners. */
+export interface EmittedCue<Payload = unknown> {
+    /** The cue that fired. */
+    cue: SequenceCue<Payload>;
+    /** Its index in the ordered cue list. */
+    index: number;
+    /** Playhead (ms) at the moment it was emitted — `>= cue.atMs`, possibly well past on a large jump. */
+    atPlayheadMs: number;
+}
+/** A read-only view of the director's playback state, returned by {@link SequenceDirector.state}. */
+export interface SequenceState {
+    /** Current playhead position in ms from the start of the timeline. */
+    playheadMs: number;
+    /** Total timeline length — the largest cue `atMs` (0 when empty). */
+    durationMs: number;
+    /** Whether the clock is currently advancing the playhead. */
+    playing: boolean;
+    /** True once the playhead has reached the end (every cue has fired). */
+    done: boolean;
+    /** Fraction of the timeline elapsed, in `[0, 1]`; `1` when `durationMs` is 0. */
+    progress: number;
+    /** How many cues have fired so far (a prefix of the ordered list). */
+    firedCount: number;
+    /** Total number of cues. */
+    total: number;
+}
+/** Serializable snapshot — enough to resume a cutscene exactly where a save left it. */
+export interface SequenceSnapshot {
+    /** Playhead position in ms. */
+    playheadMs: number;
+    /** Index of the next cue to fire; cues before it are considered already fired. */
+    nextIndex: number;
+    /** Whether playback was running when captured. */
+    playing: boolean;
+}
+/** Options for {@link createSequenceDirector}. */
+export interface SequenceDirectorOptions<Payload = unknown> {
+    /** The timeline: cues in any order (sorted by `atMs` internally, stably). */
+    cues: readonly SequenceCue<Payload>[];
+    /** Injected clock (ms) that drives playback. Default `Date.now`; inject a fake for deterministic tests. */
+    now?: () => number;
+    /** Start playing immediately (default `false` — call {@link SequenceDirector.play}). */
+    autoplay?: boolean;
+}
+/** A cue listener, called once per cue as it fires. Returns nothing. */
+export type CueListener<Payload = unknown> = (emitted: EmittedCue<Payload>) => void;
+/**
+ * A data-driven cutscene: an ordered timeline of typed cues that fire on a single
+ * injected clock. See {@link createSequenceDirector}.
+ */
+export interface SequenceDirector<Payload = unknown> {
+    /** The cues, sorted by `atMs`. */
+    readonly cues: readonly SequenceCue<Payload>[];
+    /** Start (or resume) playback from the current playhead. No-op if already playing or done. */
+    play(): void;
+    /** Freeze the playhead, capturing elapsed clock time up to now. No-op if not playing. */
+    pause(): void;
+    /**
+     * Jump the playhead to `ms` (clamped to `[0, durationMs]`). Moving forward fires every
+     * un-fired cue up to `ms` in order (once each, even across a large jump); moving backward
+     * re-arms cues now in the future without emitting them.
+     */
+    seek(ms: number): void;
+    /** Fast-forward to the end: emit every remaining cue in order, then stop and mark done. */
+    skip(): void;
+    /** Halt and rewind: pause, reset the playhead to 0, and re-arm every cue. */
+    stop(): void;
+    /**
+     * Advance the playhead by the elapsed injected-clock time since the last tick/resume and
+     * emit any cues now due. A host calls this once per frame while playing; a no-op when paused.
+     */
+    tick(): void;
+    /** Current playback state (playhead, duration, playing/done, progress). */
+    state(): SequenceState;
+    /** Register a cue listener; returns an unsubscribe fn. */
+    onCue(listener: CueListener<Payload>): () => void;
+    /** Observe state changes (play/pause/seek/skip/stop/tick/restore); returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): SequenceSnapshot;
+    /** Restore from a {@link SequenceSnapshot}; does not re-emit already-fired cues. */
+    restore(snapshot: SequenceSnapshot): void;
+}
+/**
+ * A serializable cutscene / sequence director: an ordered timeline of typed cues
+ * (`{ atMs, kind, payload }`) advanced by one injected clock, firing each cue once
+ * and in order as its time passes — even across a large seek — with play/pause/
+ * seek/skip/stop controls. The director only *schedules and emits* cues; it never
+ * interprets what a `kind` means, so the same primitive drives camera moves,
+ * dialogue lines, fades, or any game event. `snapshot`/`restore` round-trip the
+ * playhead and which cues have fired. Deterministic (no wall clock beyond the
+ * injected `now`) and allocation-free on the tick path.
+ *
+ * @capability sequence-director data-driven cutscene timeline — fire typed camera/dialogue/event cues on one injected clock with play/pause/seek/skip and snapshot/restore
+ */
+export declare function createSequenceDirector<Payload = unknown>(options: SequenceDirectorOptions<Payload>): SequenceDirector<Payload>;

package/dist/scene/sequenceDirector.js

@@ -0,0 +1,146 @@
+/**
+ * A serializable cutscene / sequence director: an ordered timeline of typed cues
+ * (`{ atMs, kind, payload }`) advanced by one injected clock, firing each cue once
+ * and in order as its time passes — even across a large seek — with play/pause/
+ * seek/skip/stop controls. The director only *schedules and emits* cues; it never
+ * interprets what a `kind` means, so the same primitive drives camera moves,
+ * dialogue lines, fades, or any game event. `snapshot`/`restore` round-trip the
+ * playhead and which cues have fired. Deterministic (no wall clock beyond the
+ * injected `now`) and allocation-free on the tick path.
+ *
+ * @capability sequence-director data-driven cutscene timeline — fire typed camera/dialogue/event cues on one injected clock with play/pause/seek/skip and snapshot/restore
+ */
+export function createSequenceDirector(options) {
+    const cues = [...options.cues].sort((a, b) => a.atMs - b.atMs);
+    for (const cue of cues) {
+        if (!(cue.atMs >= 0) || !Number.isFinite(cue.atMs)) {
+            throw new Error(`sequence cue "${cue.kind}" needs a finite atMs >= 0, got ${cue.atMs}`);
+        }
+    }
+    const durationMs = cues.length > 0 ? cues[cues.length - 1].atMs : 0;
+    const now = options.now ?? Date.now;
+    const cueListeners = new Set();
+    const stateListeners = new Set();
+    let playheadMs = 0;
+    let nextIndex = 0;
+    let playing = false;
+    let lastNow = now();
+    function notify() {
+        for (const listener of stateListeners)
+            listener();
+    }
+    /** Emit every un-fired cue with `atMs <= playheadMs`, in order. Allocation-free. */
+    function fireDue() {
+        let fired = false;
+        while (nextIndex < cues.length && cues[nextIndex].atMs <= playheadMs) {
+            const cue = cues[nextIndex];
+            const index = nextIndex;
+            nextIndex += 1;
+            fired = true;
+            for (const listener of cueListeners)
+                listener({ cue, index, atPlayheadMs: playheadMs });
+        }
+        return fired;
+    }
+    /** Fold elapsed injected-clock time into the playhead and fire due cues. */
+    function advanceToNow() {
+        const t = now();
+        const delta = t - lastNow;
+        lastNow = t;
+        if (delta <= 0)
+            return false;
+        playheadMs = Math.min(durationMs, playheadMs + delta);
+        const fired = fireDue();
+        const stopped = playheadMs >= durationMs && playing;
+        if (playheadMs >= durationMs)
+            playing = false;
+        return fired || stopped;
+    }
+    function isDone() {
+        return nextIndex >= cues.length && playheadMs >= durationMs;
+    }
+    return {
+        cues,
+        play() {
+            if (playing || isDone())
+                return;
+            playing = true;
+            lastNow = now();
+            notify();
+        },
+        pause() {
+            if (!playing)
+                return;
+            advanceToNow();
+            playing = false;
+            notify();
+        },
+        seek(ms) {
+            const target = Math.max(0, Math.min(durationMs, ms));
+            if (target < playheadMs) {
+                // Backward scrub: re-arm cues now in the future, emit nothing.
+                playheadMs = target;
+                let i = 0;
+                while (i < cues.length && cues[i].atMs <= target)
+                    i += 1;
+                nextIndex = i;
+            }
+            else {
+                playheadMs = target;
+                fireDue();
+            }
+            lastNow = now();
+            if (playheadMs >= durationMs && nextIndex >= cues.length)
+                playing = false;
+            notify();
+        },
+        skip() {
+            playheadMs = durationMs;
+            fireDue();
+            playing = false;
+            notify();
+        },
+        stop() {
+            playheadMs = 0;
+            nextIndex = 0;
+            playing = false;
+            lastNow = now();
+            notify();
+        },
+        tick() {
+            if (!playing)
+                return;
+            if (advanceToNow())
+                notify();
+        },
+        state() {
+            return {
+                playheadMs,
+                durationMs,
+                playing,
+                done: isDone(),
+                progress: durationMs > 0 ? Math.max(0, Math.min(1, playheadMs / durationMs)) : 1,
+                firedCount: nextIndex,
+                total: cues.length,
+            };
+        },
+        onCue(listener) {
+            cueListeners.add(listener);
+            return () => cueListeners.delete(listener);
+        },
+        subscribe(listener) {
+            stateListeners.add(listener);
+            return () => stateListeners.delete(listener);
+        },
+        snapshot() {
+            return { playheadMs, nextIndex, playing };
+        },
+        restore(snapshot) {
+            playheadMs = Math.max(0, Math.min(durationMs, snapshot.playheadMs));
+            nextIndex = Math.max(0, Math.min(cues.length, snapshot.nextIndex));
+            playing = snapshot.playing;
+            lastNow = now();
+            notify();
+        },
+    };
+}

package/dist/session/roles.js

@@ -1,14 +1,15 @@
 import { shuffleWithRng } from "../cards/cardPile.js";
+import { resolveRng } from "../random/resolveRng.js";
 /**
  * Assign hidden or team roles across players by ratio — social-deduction and team-shuffle setups.
  *
  * @capability role-assign assign hidden or team roles to players by ratio
   * @internal
   */
-export function assignRoles(userIds, roles, rng = Math.random) {
+export function assignRoles(userIds, roles, rng) {
     if (roles.length === 0)
         throw new Error("assignRoles needs at least one role");
-    const shuffled = shuffleWithRng(userIds, rng);
+    const shuffled = shuffleWithRng(userIds, resolveRng(rng, "assignRoles"));
     const assignment = {};
     let index = 0;
     const countRoles = roles.filter((role) => role.count !== undefined);

package/dist/settings/settingsModel.d.ts

@@ -68,6 +68,7 @@ export declare const SETTING_IDS: {
     readonly graphicsShadows: "graphics.shadows";
     readonly graphicsUiScale: "graphics.uiScale";
     readonly touchStyle: "controls.touchStyle";
+    readonly touchJoystick: "controls.touchJoystick";
 };
 export type GraphicsQuality = "low" | "medium" | "high";
 export declare const GRAPHICS_QUALITY_OPTIONS: readonly SettingOption[];

package/dist/settings/settingsModel.js

@@ -12,6 +12,7 @@ export const SETTING_IDS = {
     graphicsShadows: "graphics.shadows",
     graphicsUiScale: "graphics.uiScale",
     touchStyle: "controls.touchStyle",
+    touchJoystick: "controls.touchJoystick",
 };
 export const GRAPHICS_QUALITY_OPTIONS = [
     { value: "low", label: "Low" },

package/dist/stats/rollCheck.js

@@ -1,12 +1,14 @@
+import { resolveRng } from "../random/resolveRng.js";
 /**
  * Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
  *
  * @capability dice-check resolve a pass/fail roll against a target number with modifiers and crits
  */
-export function rollCheck(input, rng = Math.random) {
+export function rollCheck(input, rng) {
+    const random = resolveRng(rng, "rollCheck");
     const sides = input.diceSides ?? 20;
     const advantage = input.advantage ?? "normal";
-    const rollDie = () => Math.floor(rng() * sides) + 1;
+    const rollDie = () => Math.floor(random() * sides) + 1;
     const rolls = advantage === "normal" ? [rollDie()] : [rollDie(), rollDie()];
     const roll = advantage === "advantage"
         ? Math.max(...rolls)

package/dist/time/dayNightCycle.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Turnkey day-night cycle: one serializable brain that advances a normalized day
+ * fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. A game wires this one model and drives an existing sky/daylight seam from
+ * `sample()` instead of hand-rolling a clock plus a color lerp.
+ *
+ * The model is genre-agnostic: `phase` labels and colors are free-form values the
+ * game styles. The model never branches on what a phase string "means" — it only
+ * interpolates between the keyframes you give it.
+ */
+/** One day-night keyframe: at a normalized day position, the phase label and target colors the game styles. */
+export interface DayNightKeyframe {
+    /** Normalized day position in [0,1) where this keyframe sits; the cycle wraps past 1 back to 0. */
+    at: number;
+    /** Free-form phase label (e.g. `"dawn"`, `"day"`, `"dusk"`, `"night"`, or anything). The model never interprets it. */
+    phase: string;
+    /** Primary tint/grade color at this keyframe as `"#rrggbb"`. */
+    color: string;
+    /** Optional secondary color (e.g. sky zenith or key-light color). Falls back to `color` when sampled. */
+    lightColor?: string;
+    /** Optional light level in [0,1] a presenter maps to intensity. Falls back to `1` when sampled. */
+    intensity?: number;
+}
+/** The interpolated day-night look at a moment: day fraction, active phase, and blended colors. */
+export interface DayNightSample {
+    /** Current normalized day fraction in [0,1). */
+    dayFraction: number;
+    /** Phase label of the keyframe segment currently active (the free string the game styles). */
+    phase: string;
+    /** Blended primary tint/grade color as `"#rrggbb"`. */
+    color: string;
+    /** Blended secondary color as `"#rrggbb"` (equals `color` when no keyframe set `lightColor`). */
+    lightColor: string;
+    /** Blended light level in [0,1]. */
+    intensity: number;
+}
+/** Serializable day-night position — accumulated clock offset, pause state, and speed — for save/load. */
+export interface DayNightSnapshot {
+    /** Accumulated game-time in ms since the cycle's zero, before wrapping into a day. */
+    elapsedMs: number;
+    /** Whether the clock is paused. */
+    paused: boolean;
+    /** Clock rate multiplier in effect. */
+    speed: number;
+}
+/** Options for {@link createDayNightCycle}. */
+export interface DayNightCycleOptions {
+    /** At least one keyframe; sorted and wrapped into [0,1) internally. Colors and phases are free-form. */
+    keyframes: readonly DayNightKeyframe[];
+    /** Real milliseconds for one full day at speed 1. Default `120000` (two minutes). */
+    dayLengthMs?: number;
+    /** Normalized day fraction to start at, in [0,1). Default `0`. */
+    start?: number;
+    /** Clock rate multiplier (`2` runs twice as fast). Default `1`. */
+    speed?: number;
+    /** Start with the clock paused. Default `false`. */
+    startPaused?: boolean;
+    /** Injected clock in ms so advancement stays deterministic under test. Default `Date.now`. */
+    now?: () => number;
+}
+/** A running, observable, serializable day-night cycle. A presenter renders `sample()`. */
+export interface DayNightCycle {
+    /** The configured keyframes, sorted by `at` and wrapped into [0,1). */
+    readonly keyframes: readonly DayNightKeyframe[];
+    /** Real milliseconds for one full day at speed 1. */
+    readonly dayLengthMs: number;
+    /** Current normalized day fraction in [0,1), advanced from the injected clock. */
+    dayFraction(): number;
+    /** The free-form phase label active at the current day fraction. */
+    phase(): string;
+    /** The interpolated look at the current day fraction. */
+    sample(): DayNightSample;
+    /** The interpolated look at an explicit day fraction, without touching the clock. */
+    sampleAt(fraction: number): DayNightSample;
+    /**
+     * Calendar adapter (`{ dayFraction }`) so the cycle drops straight into any
+     * `{ calendar(): { dayFraction: number } }` sky/daylight seam that already
+     * consumes a day fraction — no glue in the game.
+     */
+    calendar(): {
+        dayFraction: number;
+    };
+    /** Jump the clock to a normalized day fraction (wrapped into [0,1)). */
+    setDayFraction(fraction: number): void;
+    /** Whether the clock is paused. */
+    isPaused(): boolean;
+    /** Pause advancement. */
+    pause(): void;
+    /** Resume advancement. */
+    play(): void;
+    /** Toggle pause/resume. */
+    toggle(): void;
+    /** Current clock rate multiplier. */
+    speed(): number;
+    /** Set the clock rate multiplier; `0` or negative pauses. */
+    setSpeed(multiplier: number): void;
+    /** Observe control changes (pause/play/speed/setDayFraction/restore). Returns an unsubscribe fn. Continuous advance is read via `sample()`, not events. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable position for a save. */
+    snapshot(): DayNightSnapshot;
+    /** Restore position from a {@link DayNightSnapshot}. */
+    restore(snapshot: DayNightSnapshot): void;
+}
+/**
+ * Creates a turnkey day-night cycle: a serializable model that advances a normalized
+ * day fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. Wire this one model, then drive an existing sky/daylight seam from `sample()`
+ * (or drop it straight into a `{ calendar(): { dayFraction } }` seam via `calendar()`)
+ * to get a moving day-night cycle with color grading — no hand-rolled clock or lerp.
+ * `phase` labels and colors are free-form; the model never interprets their meaning.
+ *
+ * @capability day-night-cycle one wired model gives a moving day-night cycle — running clock plus keyframed phase labels and tint/light colors a game drives an existing sky/daylight seam from
+ */
+export declare function createDayNightCycle(options: DayNightCycleOptions): DayNightCycle;

package/dist/time/dayNightCycle.js

@@ -0,0 +1,208 @@
+/**
+ * Turnkey day-night cycle: one serializable brain that advances a normalized day
+ * fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. A game wires this one model and drives an existing sky/daylight seam from
+ * `sample()` instead of hand-rolling a clock plus a color lerp.
+ *
+ * The model is genre-agnostic: `phase` labels and colors are free-form values the
+ * game styles. The model never branches on what a phase string "means" — it only
+ * interpolates between the keyframes you give it.
+ */
+/** Clamp a number into [0,1]. */
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/** Wrap a number into [0,1), so `-0.1` → `0.9` and `1.2` → `0.2`. */
+function wrap01(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return ((value % 1) + 1) % 1;
+}
+/** Linear interpolation between `a` and `b` by `t`. */
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+/** Parse `"#rrggbb"` (or `"rrggbb"`) into an `[r,g,b]` byte triple. */
+function hexToRgb(hex) {
+    const clean = hex.startsWith("#") ? hex.slice(1) : hex;
+    const value = Number.parseInt(clean, 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+}
+/** Clamp and round a channel into a 0-255 byte. */
+function clampByte(value) {
+    return Math.max(0, Math.min(255, Math.round(value)));
+}
+/** Encode an `[r,g,b]` triple back into `"#rrggbb"`. */
+function rgbToHex(rgb) {
+    return `#${rgb.map((channel) => clampByte(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+/** Interpolate two `"#rrggbb"` colors in RGB space by `t`. */
+function lerpHex(a, b, t) {
+    const [ar, ag, ab] = hexToRgb(a);
+    const [br, bg, bb] = hexToRgb(b);
+    return rgbToHex([lerp(ar, br, t), lerp(ag, bg, t), lerp(ab, bb, t)]);
+}
+/** Sanitize a positive finite number, falling back to `fallback`. */
+function positiveOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+/** Sort keyframes by wrapped `at` and fill in color/intensity fallbacks; never mutates the input. */
+function normalizeKeyframes(keyframes) {
+    if (keyframes.length === 0) {
+        throw new Error("createDayNightCycle requires at least one keyframe");
+    }
+    return keyframes
+        .map((keyframe) => ({
+        at: wrap01(keyframe.at),
+        phase: keyframe.phase,
+        color: keyframe.color,
+        lightColor: keyframe.lightColor ?? keyframe.color,
+        intensity: keyframe.intensity ?? 1,
+    }))
+        .sort((a, b) => a.at - b.at);
+}
+/** Blend the normalized keyframe ring at a wrapped day fraction. */
+function sampleKeyframes(sorted, fraction) {
+    const dayFraction = wrap01(fraction);
+    if (sorted.length === 1) {
+        const only = sorted[0];
+        return { dayFraction, phase: only.phase, color: only.color, lightColor: only.lightColor, intensity: only.intensity };
+    }
+    // Find the last keyframe at or before the fraction; the following one (wrapping past
+    // 1.0 back to the first) is the segment we interpolate across.
+    let fromIndex = sorted.length - 1;
+    for (let index = 0; index < sorted.length; index += 1) {
+        if (sorted[index].at <= dayFraction)
+            fromIndex = index;
+        else
+            break;
+    }
+    const from = sorted[fromIndex];
+    const to = sorted[(fromIndex + 1) % sorted.length];
+    const span = (to.at - from.at + 1) % 1;
+    const localRaw = (dayFraction - from.at + 1) % 1;
+    const localT = span <= 0 ? 0 : clamp01(localRaw / span);
+    return {
+        dayFraction,
+        phase: from.phase,
+        color: lerpHex(from.color, to.color, localT),
+        lightColor: lerpHex(from.lightColor, to.lightColor, localT),
+        intensity: lerp(from.intensity, to.intensity, localT),
+    };
+}
+/**
+ * Creates a turnkey day-night cycle: a serializable model that advances a normalized
+ * day fraction on an injected clock and blends per-keyframe phase labels and tint/light
+ * colors. Wire this one model, then drive an existing sky/daylight seam from `sample()`
+ * (or drop it straight into a `{ calendar(): { dayFraction } }` seam via `calendar()`)
+ * to get a moving day-night cycle with color grading — no hand-rolled clock or lerp.
+ * `phase` labels and colors are free-form; the model never interprets their meaning.
+ *
+ * @capability day-night-cycle one wired model gives a moving day-night cycle — running clock plus keyframed phase labels and tint/light colors a game drives an existing sky/daylight seam from
+ */
+export function createDayNightCycle(options) {
+    const sorted = normalizeKeyframes(options.keyframes);
+    const keyframes = sorted.map((keyframe) => ({ ...keyframe }));
+    const dayLengthMs = positiveOr(options.dayLengthMs, 120_000);
+    const now = options.now ?? Date.now;
+    const listeners = new Set();
+    let elapsedMs = wrap01(options.start ?? 0) * dayLengthMs;
+    let paused = options.startPaused ?? false;
+    let speed = positiveOr(options.speed, 1);
+    let anchor = now();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Accrue elapsed game-time from the injected clock since the last sync, then re-anchor. */
+    function sync() {
+        const t = now();
+        if (!paused)
+            elapsedMs += Math.max(0, t - anchor) * speed;
+        anchor = t;
+    }
+    function dayFraction() {
+        sync();
+        return wrap01(elapsedMs / dayLengthMs);
+    }
+    return {
+        keyframes,
+        dayLengthMs,
+        dayFraction,
+        phase() {
+            return sampleKeyframes(sorted, dayFraction()).phase;
+        },
+        sample() {
+            return sampleKeyframes(sorted, dayFraction());
+        },
+        sampleAt(fraction) {
+            return sampleKeyframes(sorted, fraction);
+        },
+        calendar() {
+            return { dayFraction: dayFraction() };
+        },
+        setDayFraction(fraction) {
+            sync();
+            elapsedMs = wrap01(fraction) * dayLengthMs;
+            notify();
+        },
+        isPaused() {
+            return paused;
+        },
+        pause() {
+            if (paused)
+                return;
+            sync();
+            paused = true;
+            notify();
+        },
+        play() {
+            if (!paused)
+                return;
+            sync();
+            paused = false;
+            notify();
+        },
+        toggle() {
+            if (paused)
+                this.play();
+            else
+                this.pause();
+        },
+        speed() {
+            return speed;
+        },
+        setSpeed(multiplier) {
+            sync();
+            if (!Number.isFinite(multiplier) || multiplier <= 0) {
+                if (!paused) {
+                    paused = true;
+                    notify();
+                }
+                return;
+            }
+            const changed = paused || multiplier !== speed;
+            speed = multiplier;
+            paused = false;
+            if (changed)
+                notify();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        snapshot() {
+            sync();
+            return { elapsedMs, paused, speed };
+        },
+        restore(snapshot) {
+            elapsedMs = Number.isFinite(snapshot.elapsedMs) ? snapshot.elapsedMs : 0;
+            paused = snapshot.paused;
+            speed = positiveOr(snapshot.speed, 1);
+            anchor = now();
+            notify();
+        },
+    };
+}