@jgengine/core 0.7.0 → 0.9.0

package/dist/tactics/fallingGrid.js

@@ -0,0 +1,158 @@
+/**
+ * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
+ * `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
+ * with configurable base/step/floor.
+ */
+export function gravityIntervalMs(level, config = {}) {
+    const baseMs = config.baseMs ?? 800;
+    const perLevel = config.perLevel ?? 70;
+    const minMs = config.minMs ?? 50;
+    return Math.max(minMs, baseMs - level * perLevel);
+}
+/**
+ * A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy,
+ * footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand
+ * style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris
+ * logic so any falling-block game can adopt it instead of reimplementing the grid.
+ */
+export function createFallingGrid(config) {
+    const cols = config.cols;
+    const rows = config.rows;
+    const lockDelayMs = config.lockDelayMs ?? 500;
+    if (cols <= 0 || rows <= 0)
+        throw new Error("falling grid needs positive dimensions");
+    let cells = new Array(cols * rows).fill(null);
+    function index(col, row) {
+        return row * cols + col;
+    }
+    function inBounds(col, row) {
+        return col >= 0 && col < cols && row >= 0 && row < rows;
+    }
+    function cellAt(col, row) {
+        if (!inBounds(col, row))
+            return null;
+        return cells[index(col, row)] ?? null;
+    }
+    function occupied(col, row) {
+        return cellAt(col, row) !== null;
+    }
+    function setCell(col, row, value) {
+        if (!inBounds(col, row))
+            return;
+        cells[index(col, row)] = value;
+    }
+    function clearCell(col, row) {
+        if (!inBounds(col, row))
+            return;
+        cells[index(col, row)] = null;
+    }
+    function canPlace(footprint, offset) {
+        for (const [dc, dr] of footprint) {
+            const col = offset[0] + dc;
+            const row = offset[1] + dr;
+            if (col < 0 || col >= cols || row >= rows)
+                return false;
+            if (row >= 0 && occupied(col, row))
+                return false;
+        }
+        return true;
+    }
+    function place(footprint, offset, value) {
+        if (!canPlace(footprint, offset))
+            return false;
+        for (const [dc, dr] of footprint) {
+            const col = offset[0] + dc;
+            const row = offset[1] + dr;
+            if (row >= 0)
+                setCell(col, row, value);
+        }
+        return true;
+    }
+    function fullRows() {
+        const full = [];
+        for (let row = 0; row < rows; row += 1) {
+            let rowFull = true;
+            for (let col = 0; col < cols; col += 1) {
+                if (!occupied(col, row)) {
+                    rowFull = false;
+                    break;
+                }
+            }
+            if (rowFull)
+                full.push(row);
+        }
+        return full;
+    }
+    function clearRows(rowsToClear) {
+        const toClear = new Set(rowsToClear);
+        if (toClear.size === 0)
+            return 0;
+        const kept = [];
+        for (let row = 0; row < rows; row += 1) {
+            if (toClear.has(row))
+                continue;
+            kept.push(cells.slice(index(0, row), index(0, row) + cols));
+        }
+        const cleared = rows - kept.length;
+        const next = [];
+        for (let i = 0; i < cleared; i += 1)
+            next.push(...new Array(cols).fill(null));
+        for (const row of kept)
+            next.push(...row);
+        cells = next;
+        return cleared;
+    }
+    function settle() {
+        let moved = 0;
+        for (let col = 0; col < cols; col += 1) {
+            const values = [];
+            for (let row = 0; row < rows; row += 1) {
+                const value = cellAt(col, row);
+                if (value !== null)
+                    values.push({ row, value });
+            }
+            for (let row = 0; row < rows; row += 1)
+                clearCell(col, row);
+            const count = values.length;
+            for (let i = 0; i < count; i += 1) {
+                const newRow = rows - count + i;
+                const { row: oldRow, value } = values[i];
+                setCell(col, newRow, value);
+                if (oldRow !== newRow)
+                    moved += 1;
+            }
+        }
+        return moved;
+    }
+    function advanceLock(state, grounded, dtMs) {
+        if (!grounded)
+            return null;
+        return { elapsedMs: (state?.elapsedMs ?? 0) + dtMs };
+    }
+    function lockExpired(state) {
+        return state !== null && state.elapsedMs >= lockDelayMs;
+    }
+    function snapshot() {
+        return { cols, rows, cells: cells.slice() };
+    }
+    function reset() {
+        cells = new Array(cols * rows).fill(null);
+    }
+    return {
+        cols,
+        rows,
+        occupied,
+        cellAt,
+        setCell,
+        clearCell,
+        canPlace,
+        place,
+        fullRows,
+        clearRows,
+        settle,
+        advanceLock,
+        lockExpired,
+        snapshot,
+        reset,
+    };
+}

package/dist/tactics/tacticalGrid.d.ts

@@ -1,9 +1,16 @@
 export type Tile = readonly [number, number];
+/** Maps abstract `[col, row]` tiles onto world-space `[x, z]`, mirroring `navGrid`'s bounds+cellSize convention. */
+export interface TacticalGridWorldConfig {
+    /** World-space `[x, z]` of the min corner of tile `[0, 0]`. */
+    origin: readonly [number, number];
+    tileSize: number;
+}
 export interface TacticalGridConfig {
     width: number;
     height: number;
     blocked?: readonly Tile[];
     diagonal?: boolean;
+    world?: TacticalGridWorldConfig;
 }
 export interface ReachableOptions {
     passThrough?: readonly string[];
@@ -53,5 +60,9 @@ export interface TacticalGrid {
     push(id: string, direction: Tile, options?: PushOptions): PushResult;
     capture(): TacticalGridSnapshot;
     restore(snapshot: TacticalGridSnapshot): void;
+    /** World `[x, z]` to the containing tile, or `null` when outside the grid. Requires `config.world`. */
+    worldToTile(x: number, z: number): Tile | null;
+    /** A tile's world-space center. Requires `config.world`. */
+    tileToWorld(tile: Tile): readonly [number, number];
 }
 export declare function createTacticalGrid(config: TacticalGridConfig): TacticalGrid;

package/dist/tactics/tacticalGrid.js

@@ -12,9 +12,24 @@ export function createTacticalGrid(config) {
     const blocked = new Set((config.blocked ?? []).map(key));
     const occupants = new Map();
     const tiles = new Map();
+    const world = config.world;
     function inBounds(tile) {
         return tile[0] >= 0 && tile[0] < width && tile[1] >= 0 && tile[1] < height;
     }
+    function requireWorld() {
+        if (world === undefined)
+            throw new Error("tacticalGrid: worldToTile/tileToWorld require config.world.");
+        return world;
+    }
+    function worldToTile(x, z) {
+        const { origin, tileSize } = requireWorld();
+        const tile = [Math.floor((x - origin[0]) / tileSize), Math.floor((z - origin[1]) / tileSize)];
+        return inBounds(tile) ? tile : null;
+    }
+    function tileToWorld(tile) {
+        const { origin, tileSize } = requireWorld();
+        return [origin[0] + (tile[0] + 0.5) * tileSize, origin[1] + (tile[1] + 0.5) * tileSize];
+    }
     function isBlocked(tile) {
         return blocked.has(key(tile));
     }
@@ -223,6 +238,8 @@ export function createTacticalGrid(config) {
         reachable,
         path,
         push,
+        worldToTile,
+        tileToWorld,
         capture: () => {
             const occ = {};
             for (const [k, unitId] of occupants)

package/dist/time/beatClock.d.ts

@@ -22,6 +22,24 @@ export interface BeatClock {
     bpm(): number;
 }
 export declare function createBeatClock(config: BeatClockConfig, onBeat?: (beatIndex: number) => void): BeatClock;
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12). */
+export declare function nearestBeatDelta(nowSec: number, beatDurationSec: number): number;
+export interface BeatAccuracyTier {
+    id: string;
+    /** Maximum absolute delta (game-seconds) from the beat that still earns this tier. */
+    windowSec: number;
+}
+export interface BeatJudgement {
+    /** The matched tier id, or `"miss"` beyond every tier. */
+    tier: string;
+    /** Signed delta to the nearest beat — negative = early, positive = late. */
+    deltaSec: number;
+}
+export declare const DEFAULT_BEAT_TIERS: readonly BeatAccuracyTier[];
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first. */
+export declare function classifyBeatAccuracy(nowSec: number, beatDurationSec: number, tiers?: readonly BeatAccuracyTier[]): BeatJudgement;
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12). */
+export declare function inBarWindow(snapshot: BeatSnapshot, fromBeat: number, toBeat: number): boolean;
 /** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
 export declare function nextBeatTime(nowSec: number, beatDurationSec: number, epsilon?: number): number;
 export interface BufferedAction<T> {

package/dist/time/beatClock.js

@@ -35,6 +35,30 @@ export function createBeatClock(config, onBeat) {
         bpm: () => config.bpm,
     };
 }
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12). */
+export function nearestBeatDelta(nowSec, beatDurationSec) {
+    const beatIndex = Math.round(nowSec / beatDurationSec);
+    return nowSec - beatIndex * beatDurationSec;
+}
+export const DEFAULT_BEAT_TIERS = [
+    { id: "perfect", windowSec: 0.06 },
+    { id: "good", windowSec: 0.14 },
+];
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first. */
+export function classifyBeatAccuracy(nowSec, beatDurationSec, tiers = DEFAULT_BEAT_TIERS) {
+    const deltaSec = nearestBeatDelta(nowSec, beatDurationSec);
+    const magnitude = Math.abs(deltaSec);
+    for (const tier of tiers) {
+        if (magnitude <= tier.windowSec)
+            return { tier: tier.id, deltaSec };
+    }
+    return { tier: "miss", deltaSec };
+}
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12). */
+export function inBarWindow(snapshot, fromBeat, toBeat) {
+    const barBeat = snapshot.beatInBar + snapshot.phase;
+    return barBeat >= fromBeat && barBeat < toBeat;
+}
 const QUANTIZE_EPSILON = 1e-6;
 /** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
 export function nextBeatTime(nowSec, beatDurationSec, epsilon = QUANTIZE_EPSILON) {

package/dist/time/idleProgress.d.ts

@@ -0,0 +1,29 @@
+export interface IdleWindowConfig {
+    maxSeconds?: number;
+    efficiency?: number;
+}
+export interface IdleWindow {
+    elapsedSeconds: number;
+    effectiveSeconds: number;
+    capped: boolean;
+}
+export declare function idleWindow(lastSeenMs: number, nowMs: number, config?: IdleWindowConfig): IdleWindow;
+export interface LinearCatchUpInput {
+    current: number;
+    ratePerSecond: number;
+    min?: number;
+    max?: number;
+}
+export declare function linearCatchUp(seconds: number, input: LinearCatchUpInput): number;
+export interface ExponentialCatchUpInput {
+    current: number;
+    factorPerSecond: number;
+    min?: number;
+    max?: number;
+}
+export declare function exponentialCatchUp(seconds: number, input: ExponentialCatchUpInput): number;
+export interface SteppedCatchUpResult {
+    steps: number;
+    remainderSeconds: number;
+}
+export declare function steppedCatchUp(seconds: number, stepSeconds: number, step: (index: number) => void, maxSteps?: number): SteppedCatchUpResult;

package/dist/time/idleProgress.js

@@ -0,0 +1,31 @@
+export function idleWindow(lastSeenMs, nowMs, config = {}) {
+    const elapsedSeconds = Math.max(0, (nowMs - lastSeenMs) / 1000);
+    const capped = config.maxSeconds !== undefined && elapsedSeconds > config.maxSeconds;
+    const boundedSeconds = Math.min(elapsedSeconds, config.maxSeconds ?? Number.POSITIVE_INFINITY);
+    const efficiency = Math.max(0, config.efficiency ?? 1);
+    return {
+        elapsedSeconds,
+        effectiveSeconds: boundedSeconds * efficiency,
+        capped,
+    };
+}
+export function linearCatchUp(seconds, input) {
+    const clampedSeconds = Math.max(0, seconds);
+    const value = input.current + input.ratePerSecond * clampedSeconds;
+    return Math.min(input.max ?? Number.POSITIVE_INFINITY, Math.max(input.min ?? Number.NEGATIVE_INFINITY, value));
+}
+export function exponentialCatchUp(seconds, input) {
+    const clampedSeconds = Math.max(0, seconds);
+    const factor = Math.max(0, input.factorPerSecond);
+    const value = input.current * factor ** clampedSeconds;
+    return Math.min(input.max ?? Number.POSITIVE_INFINITY, Math.max(input.min ?? Number.NEGATIVE_INFINITY, value));
+}
+export function steppedCatchUp(seconds, stepSeconds, step, maxSteps) {
+    if (stepSeconds <= 0 || seconds <= 0) {
+        return { steps: 0, remainderSeconds: Math.max(0, seconds) };
+    }
+    const steps = Math.min(Math.floor(seconds / stepSeconds), maxSteps ?? Number.POSITIVE_INFINITY);
+    for (let index = 0; index < steps; index++)
+        step(index);
+    return { steps, remainderSeconds: seconds - steps * stepSeconds };
+}

package/dist/time/serverTick.d.ts

@@ -9,8 +9,14 @@ export interface ServerTickPlan<TSystemId extends string = string> {
     due: TSystemId[];
     anchors: TickAnchors;
 }
+export type PlanServerTickOptions = {
+    /** Cap catch-up runs per system per heartbeat to avoid spiral-of-death. Default 3. */
+    maxCatchUp?: number;
+};
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
+ * When wall time stalls past multiple intervals, the system id is repeated (bounded by
+ * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
-export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number): ServerTickPlan<TSystemId>;
+export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number, options?: PlanServerTickOptions): ServerTickPlan<TSystemId>;

package/dist/time/serverTick.js

@@ -1,18 +1,41 @@
+const DEFAULT_MAX_CATCH_UP = 3;
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
+ * When wall time stalls past multiple intervals, the system id is repeated (bounded by
+ * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
-export function planServerTick(systems, anchors, now) {
+export function planServerTick(systems, anchors, now, options) {
+    const maxCatchUp = options?.maxCatchUp ?? DEFAULT_MAX_CATCH_UP;
     const due = [];
     const nextAnchors = {};
     for (const system of systems) {
         const lastRunAt = anchors[system.id];
-        if (lastRunAt !== undefined && now - lastRunAt < system.intervalMs) {
+        if (lastRunAt === undefined) {
+            due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        if (system.intervalMs <= 0) {
+            due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        const elapsed = now - lastRunAt;
+        if (elapsed < system.intervalMs) {
             nextAnchors[system.id] = lastRunAt;
             continue;
         }
-        due.push(system.id);
-        nextAnchors[system.id] = now;
+        const missed = Math.floor(elapsed / system.intervalMs);
+        if (missed > maxCatchUp) {
+            for (let i = 0; i < maxCatchUp; i += 1)
+                due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        for (let i = 0; i < missed; i += 1)
+            due.push(system.id);
+        nextAnchors[system.id] = lastRunAt + missed * system.intervalMs;
     }
     return { due, anchors: nextAnchors };
 }

package/dist/time/simClock.d.ts

@@ -9,6 +9,10 @@ export interface TimeConfig {
     start?: number;
     /** Boot with the clock paused. Default false. */
     startPaused?: boolean;
+    /** In-world days per year, driving `calendar().year`/`dayOfYear`/`yearFraction`. Default 365. */
+    daysPerYear?: number;
+    /** Named season segments spanning the year in equal shares; when set, `calendar().season` names the current one. */
+    seasons?: readonly string[];
 }
 export interface CalendarTime {
     /** Total game-seconds since the world started. */
@@ -20,14 +24,24 @@ export interface CalendarTime {
     second: number;
     /** Progress through the current day, 0..1. */
     dayFraction: number;
+    /** 0-based year index, using `daysPerYear` (default 365). */
+    year: number;
+    /** 0-based day index within the current year. */
+    dayOfYear: number;
+    /** Progress through the current year, 0..1. */
+    yearFraction: number;
+    /** Current season name, present only when `TimeConfig.seasons` is configured. */
+    season?: string;
 }
 export interface ClockSnapshot {
     now: number;
     paused: boolean;
-    /** Effective multiplier applied to real time — 0 while paused. */
+    /** Speed-control multiplier — 0 while paused. The full game-time rate is `speed × timescale × scale`. */
     speed: number;
     /** The non-zero multiplier `play()` resumes to. */
     playSpeed: number;
+    /** Global slow-motion/fast-forward multiplier; 1 unless `setTimescale` was called. */
+    timescale: number;
     scale: number;
     speeds: readonly number[];
     calendar: CalendarTime;
@@ -47,6 +61,16 @@ export interface SimClock {
     setSpeed(multiplier: number): void;
     /** Step to the next configured speed (wraps); always unpauses. */
     cycleSpeed(): void;
+    /** Current global timescale multiplier; 1 by default. */
+    timescale(): number;
+    /**
+     * Global slow-motion/fast-forward multiplier composed with the speed control —
+     * `advance` returns `realDt × scale × speed × timescale`. `0` freezes game time
+     * without flipping pause state (`0.08` = bullet time, `2` = fast-forward); negative
+     * or non-finite values clamp to 0. Timescale is host-authoritative: in multiplayer
+     * it belongs to the host simulation, never to an individual client.
+     */
+    setTimescale(multiplier: number): void;
     /** Run `callback` once, `seconds` of game-time from now. Returns a cancel handle. */
     after(seconds: number, callback: () => void): () => void;
     /** Run `callback` every `seconds` of game-time. Returns a cancel handle. */

package/dist/time/simClock.js

@@ -7,9 +7,12 @@ export function createSimClock(options = {}) {
     const configuredSpeeds = config.speeds === undefined ? [1, 2, 3, 4] : config.speeds.filter((value) => value > 0);
     const speeds = configuredSpeeds.length > 0 ? configuredSpeeds : [1];
     const dayLength = config.dayLength !== undefined && config.dayLength > 0 ? config.dayLength : SECONDS_PER_GAME_DAY;
+    const daysPerYear = config.daysPerYear !== undefined && config.daysPerYear > 0 ? config.daysPerYear : 365;
+    const seasons = config.seasons;
     let now = config.start !== undefined && config.start > 0 ? config.start : 0;
     let paused = config.startPaused ?? false;
     let playSpeed = speeds[0];
+    let timescale = 1;
     let nextTimerId = 0;
     const timers = new Map();
     let displayMinute = minuteIndex(now, dayLength);
@@ -17,14 +20,26 @@ export function createSimClock(options = {}) {
         const day = Math.floor(now / dayLength);
         const dayFraction = (now - day * dayLength) / dayLength;
         const secondOfDay = dayFraction * 24 * 3600;
-        return {
+        const year = Math.floor(day / daysPerYear);
+        const dayOfYear = day - year * daysPerYear;
+        const yearFraction = (dayOfYear + dayFraction) / daysPerYear;
+        const result = {
             totalSeconds: now,
             day,
             hour: Math.floor(secondOfDay / 3600) % 24,
             minute: Math.floor(secondOfDay / 60) % 60,
             second: Math.floor(secondOfDay) % 60,
             dayFraction,
+            year,
+            dayOfYear,
+            yearFraction,
         };
+        if (seasons !== undefined && seasons.length > 0) {
+            const segmentLength = daysPerYear / seasons.length;
+            const index = Math.min(seasons.length - 1, Math.floor(dayOfYear / segmentLength));
+            result.season = seasons[index];
+        }
+        return result;
     }
     function fireDueTimers() {
         let fires = 0;
@@ -52,9 +67,9 @@ export function createSimClock(options = {}) {
         }
     }
     function advance(realDt) {
-        if (paused || realDt <= 0)
+        if (paused || realDt <= 0 || timescale === 0)
             return 0;
-        const gameDt = realDt * scale * playSpeed;
+        const gameDt = realDt * scale * playSpeed * timescale;
         now += gameDt;
         fireDueTimers();
         const minute = minuteIndex(now, dayLength);
@@ -91,6 +106,13 @@ export function createSimClock(options = {}) {
         const index = speeds.indexOf(playSpeed);
         setSpeed(speeds[(index + 1) % speeds.length]);
     }
+    function setTimescale(multiplier) {
+        const next = Number.isFinite(multiplier) && multiplier > 0 ? multiplier : 0;
+        if (next === timescale)
+            return;
+        timescale = next;
+        onChange();
+    }
     function register(due, interval, callback) {
         const id = nextTimerId;
         nextTimerId += 1;
@@ -108,6 +130,7 @@ export function createSimClock(options = {}) {
             paused,
             speed: paused ? 0 : playSpeed,
             playSpeed,
+            timescale,
             scale,
             speeds,
             calendar: calendar(),
@@ -119,6 +142,8 @@ export function createSimClock(options = {}) {
         toggle: () => (paused ? play() : pause()),
         setSpeed,
         cycleSpeed,
+        timescale: () => timescale,
+        setTimescale,
         after: (seconds, callback) => register(now + Math.max(0, seconds), null, callback),
         every: (seconds, callback) => {
             const interval = Math.max(Number.EPSILON, seconds);

package/dist/time/stateSchedule.d.ts

@@ -0,0 +1,57 @@
+export interface SchedulePhase<T> {
+    state: T;
+    durationSeconds: number;
+}
+export interface StateScheduleConfig<T> {
+    phases: readonly SchedulePhase<T>[];
+    /** Repeat the phase list forever (default); `false` clamps to the last phase after one pass. */
+    loop?: boolean;
+    /** Shifts the whole timeline so `t = 0` lands `offsetSeconds` into the cycle — staggers identical schedules. */
+    offsetSeconds?: number;
+}
+export interface ScheduleSample<T> {
+    state: T;
+    /** Index into `phases`. */
+    index: number;
+    elapsedSeconds: number;
+    /** Seconds until this phase ends; `Infinity` on the clamped final phase of a non-looping schedule. */
+    remainingSeconds: number;
+    /** Elapsed fraction of the phase in `[0, 1]`; `1` on the clamped final phase. */
+    fraction: number;
+}
+export interface ScheduleWindow {
+    start: number;
+    end: number;
+}
+/**
+ * A deterministic timeline of states — position-in-schedule is a pure function of absolute time,
+ * so a forecast preview and the live state can never disagree. One primitive behind zoned weather
+ * shifts, hazard cycles, and timetabled machinery: `stateAt`/`sampleAt` for the live state,
+ * `nextTransitionAt` for countdowns, `windowsOf`/`nextWindow` for "when is it safe" forecasts.
+ */
+export interface StateSchedule<T> {
+    /** Sum of all phase durations — one full cycle. */
+    readonly cycleSeconds: number;
+    stateAt(t: number): T;
+    sampleAt(t: number): ScheduleSample<T>;
+    /** Absolute time of the next phase boundary after `t`; `Infinity` once a non-looping schedule ends. */
+    nextTransitionAt(t: number): number;
+    /** All windows within `[fromT, fromT + horizonSeconds]` where the state matches. */
+    windowsOf(match: (state: T) => boolean, fromT: number, horizonSeconds: number): ScheduleWindow[];
+    /** The first matching window at or after `fromT` (looking ahead `horizonSeconds`, default one full cycle). */
+    nextWindow(match: (state: T) => boolean, fromT: number, horizonSeconds?: number): ScheduleWindow | null;
+}
+export declare function createStateSchedule<T>(config: StateScheduleConfig<T>): StateSchedule<T>;
+export interface ClearWindowScan {
+    fromSeconds: number;
+    horizonSeconds: number;
+    /** Sampling resolution; smaller catches shorter gaps. */
+    stepSeconds: number;
+    /** Reject windows shorter than this; default `0`. */
+    minDurationSeconds?: number;
+}
+/**
+ * Forward-scan any predicate-of-time — a timetable mover's "is the crossing clear at `t`" — for the
+ * next open window. Sampling-based: pick `stepSeconds` at or below half the shortest gap that matters.
+ */
+export declare function nextClearWindow(isClear: (t: number) => boolean, scan: ClearWindowScan): ScheduleWindow | null;