@jgengine/core 0.14.0 → 0.15.0

package/dist/scene/objectStore.d.ts

@@ -1,3 +1,4 @@
+import type { ModelAnimationConfig } from "../game/playableGame.js";
 import type { EntityPosition } from "./entityStore.js";
 export interface ObjectVisual {
     scale?: number | readonly [number, number, number];
@@ -11,12 +12,21 @@ export interface SceneObject {
     rotationY: number;
     parentSpace?: string;
     visual?: ObjectVisual;
+    /**
+     * Per-placement rig animation override applied on top of catalog resolution — the same shape as
+     * `ModelConfig.animation` (role→clip states, `"auto"`/`"none"`, speeds, fade, one-shot bindings).
+     * Authored in the editor as `marker.meta.animation` (#1274) and threaded here by
+     * `resolveAuthoredObjects` → `placeAuthoredObjects`; `undefined` keeps the catalog-resolved default.
+     */
+    animation?: ModelAnimationConfig | "auto" | "none";
 }
 export interface PlaceOptions {
     instanceId?: string;
     parentSpace?: string;
     rotation?: number;
     visual?: ObjectVisual;
+    /** Per-placement rig animation override stored on the placed {@link SceneObject}; same shape as `ModelConfig.animation`. Omit to keep the catalog-resolved default. */
+    animation?: ModelAnimationConfig | "auto" | "none";
     /** When `instanceId` is already placed: `"throw"` (default), `"replace"` (fresh placement over it — remount-safe world setup, #284.10), or `"keep"` (leave it untouched and return the id). */
     onExisting?: "throw" | "replace" | "keep";
 }

package/dist/scene/objectStore.js

@@ -1,5 +1,12 @@
 import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
 const CELL_SIZE = 1;
+/**
+ * When an `inBox` query spans more than this many 1 m cells, walk the object list instead of the
+ * cell grid. Tall/wide colliders (city buildings) can inflate movement broadphase to hundreds of
+ * metres on each axis — at 1 m cells that is O(10⁶) empty `Map.get`s per frame and freezes `pose`.
+ * Linear scan over a few hundred objects is cheaper the moment the cell volume exceeds the scene.
+ */
+const IN_BOX_CELL_VOLUME_LIMIT = 4096;
 function cellIndexOf(value) {
     return Math.floor(value / CELL_SIZE);
 }
@@ -9,6 +16,10 @@ function cellKey(cx, cy, cz) {
 function cellKeyOf(position) {
     return cellKey(cellIndexOf(position[0]), cellIndexOf(position[1]), cellIndexOf(position[2]));
 }
+function objectInAabb(object, min, max) {
+    const [x, y, z] = object.position;
+    return x >= min[0] && x <= max[0] && y >= min[1] && y <= max[1] && z >= min[2] && z <= max[2];
+}
 export function createObjectStore() {
     const store = createObservableKeyedStore();
     const cellIndex = new Map();
@@ -60,6 +71,7 @@ export function createObjectStore() {
                 rotationY: options.rotation ?? 0,
                 ...(options.parentSpace !== undefined ? { parentSpace: options.parentSpace } : {}),
                 ...(options.visual !== undefined ? { visual: options.visual } : {}),
+                ...(options.animation !== undefined ? { animation: options.animation } : {}),
             });
             indexAdd(instanceId, position);
             return instanceId;
@@ -99,6 +111,7 @@ export function createObjectStore() {
                 position: current.position,
                 rotationY: current.rotationY,
                 ...(current.parentSpace !== undefined ? { parentSpace: current.parentSpace } : {}),
+                ...(current.animation !== undefined ? { animation: current.animation } : {}),
                 ...(visual !== undefined ? { visual } : {}),
             });
             return true;
@@ -145,13 +158,27 @@ export function createObjectStore() {
             return results;
         },
         inBox(min, max) {
-            const hits = [];
             const minCx = cellIndexOf(min[0]);
             const maxCx = cellIndexOf(max[0]);
             const minCy = cellIndexOf(min[1]);
             const maxCy = cellIndexOf(max[1]);
             const minCz = cellIndexOf(min[2]);
             const maxCz = cellIndexOf(max[2]);
+            const cellsX = Math.max(0, maxCx - minCx + 1);
+            const cellsY = Math.max(0, maxCy - minCy + 1);
+            const cellsZ = Math.max(0, maxCz - minCz + 1);
+            const cellVolume = cellsX * cellsY * cellsZ;
+            // Huge queries (city-scale movement broadphase inflated by tall building colliders): scanning
+            // every empty 1 m cell is far more expensive than testing the few hundred placed objects.
+            if (cellVolume > IN_BOX_CELL_VOLUME_LIMIT) {
+                const hits = [];
+                for (const object of store.arraySnapshot()) {
+                    if (objectInAabb(object, min, max))
+                        hits.push(object);
+                }
+                return hits;
+            }
+            const hits = [];
             for (let cx = minCx; cx <= maxCx; cx += 1) {
                 for (let cy = minCy; cy <= maxCy; cy += 1) {
                     for (let cz = minCz; cz <= maxCz; cz += 1) {
@@ -162,12 +189,8 @@ export function createObjectStore() {
                             const object = store.get(instanceId);
                             if (object === undefined)
                                 continue;
-                            const [x, y, z] = object.position;
-                            if (x >= min[0] && x <= max[0] &&
-                                y >= min[1] && y <= max[1] &&
-                                z >= min[2] && z <= max[2]) {
+                            if (objectInAabb(object, min, max))
                                 hits.push(object);
-                            }
                         }
                     }
                 }

package/dist/scene/sceneKinds.d.ts

@@ -265,6 +265,24 @@ export interface SceneKindResolveContext {
  * inspector, `+ Add` menu, and `AuthoredScene` renderer lookup all read this registry.
  */
 export declare function registerSceneKind<TResolved>(definition: SceneKindDefinition<TResolved>): void;
+/**
+ * Declare a game's own **click-to-place** marker kind in one call — the light path for logical
+ * markers a game reads off the document by `kind` (a stash, checkpoint, spawn point, bounty…), with
+ * none of a full studio's schema/resolver boilerplate. Registering it makes the kind a click-to-place
+ * tool in the editor's `+ Add` menu (grouped under `category`) and gives its markers an inspector for
+ * any `fields` you pass. Call at module load from a module the editor loads (a game's `editorLayers`
+ * import graph). Rendering is unaffected — the game still reads `kind` off `editorLayers.markers`.
+ */
+export declare function definePlaceableMarkerKind(options: {
+    kind: string;
+    label: string;
+    /** `+ Add` menu section header this kind groups under. Defaults to `"Custom"`. */
+    category?: string;
+    /** Accent hex for the menu entry + inspector header. */
+    accent?: string;
+    /** Optional inspector fields written into each marker's `meta` (e.g. a payout value). */
+    fields?: readonly ParamField[];
+}): string;
 /** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
 export declare function getSceneKind(kind: string): SceneKindDefinition | undefined;
 /** True when a kind has a registered studio definition (schema/inspector/renderer). @internal */

package/dist/scene/sceneKinds.js

@@ -198,6 +198,25 @@ const registry = new Map();
 export function registerSceneKind(definition) {
     registry.set(definition.kind, definition);
 }
+/**
+ * Declare a game's own **click-to-place** marker kind in one call — the light path for logical
+ * markers a game reads off the document by `kind` (a stash, checkpoint, spawn point, bounty…), with
+ * none of a full studio's schema/resolver boilerplate. Registering it makes the kind a click-to-place
+ * tool in the editor's `+ Add` menu (grouped under `category`) and gives its markers an inspector for
+ * any `fields` you pass. Call at module load from a module the editor loads (a game's `editorLayers`
+ * import graph). Rendering is unaffected — the game still reads `kind` off `editorLayers.markers`.
+ */
+export function definePlaceableMarkerKind(options) {
+    registerSceneKind({
+        kind: options.kind,
+        target: "marker",
+        label: options.label,
+        addCategory: options.category ?? "Custom",
+        ...(options.accent === undefined ? {} : { accent: options.accent }),
+        schema: { fields: options.fields ?? [] },
+    });
+    return options.kind;
+}
 /** The registered definition for a kind, or undefined if the kind is a plain (non-studio) kind. @internal */
 export function getSceneKind(kind) {
     return registry.get(kind);

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;