@jgengine/core 0.24.0 → 0.26.0

package/dist/sim/offScreen.js

@@ -0,0 +1,450 @@
+import { devtools } from "../devtools/devtools.js";
+import { decayMeters, initDecayMeters } from "../survival/decayMeter.js";
+const DEFAULT_SWITCH_BUDGET = 32;
+function distanceBetween(a, b) {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    const dz = a[2] - b[2];
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+function lerp(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}
+/**
+ * Create the world that decides which agents deserve a simulation. Residents are cheap state until
+ * they come near, and cheap again when they leave; the cheap state is the schedule, the needs and
+ * the last place, so a returning resident never pops in at the origin.
+ *
+ * @capability offscreen-world schedules agents near the player as real state and far ones as cheap state
+ */
+export function createOffScreenWorld(options) {
+    const places = options.places;
+    const defs = options.needs.map((definition) => ({ ...definition }));
+    const near = options.near;
+    const residents = [];
+    const residentOf = new Map();
+    let nearRadius = Math.max(0, options.policy.nearRadius);
+    let farRadius = Math.max(nearRadius, options.policy.farRadius ?? nearRadius);
+    let costModel = options.policy.costModel;
+    let nearBudget = options.policy.nearBudget ?? null;
+    let switchBudget = Math.max(1, Math.floor(options.policy.switchBudget ?? DEFAULT_SWITCH_BUDGET));
+    let promotions = 0;
+    let demotions = 0;
+    let farRefreshes = 0;
+    function placeAt(place, id) {
+        const anchor = places[place];
+        if (anchor === undefined)
+            throw new Error(`resident "${id}" follows a routine through unknown place "${place}"`);
+        return anchor;
+    }
+    function goalFor(resident) {
+        if (resident.routine === null)
+            return resident.home;
+        const phase = resident.routine.phaseAt(resident.updatedAt);
+        const target = phase.nextPlace ?? phase.place;
+        return placeAt(target, resident.id);
+    }
+    function positionFor(resident, phase) {
+        if (phase === null || resident.routine === null)
+            return resident.home;
+        const from = placeAt(phase.place, resident.id);
+        if (!phase.travelling || phase.nextPlace === null)
+            return from;
+        return lerp(from, placeAt(phase.nextPlace, resident.id), phase.progress);
+    }
+    /** Advance a far resident's cheap state through every routine boundary up to `now`. */
+    function refreshCheap(resident, now) {
+        if (now <= resident.updatedAt)
+            return;
+        farRefreshes += 1;
+        if (resident.routine === null) {
+            resident.needs = decayMeters(resident.needs, defs, now - resident.updatedAt);
+            resident.updatedAt = now;
+            resident.staleAt = Infinity;
+            return;
+        }
+        while (resident.updatedAt < now) {
+            const boundary = Math.min(now, resident.staleAt);
+            resident.needs = decayMeters(resident.needs, defs, boundary - resident.updatedAt);
+            resident.updatedAt = boundary;
+            if (boundary >= now)
+                break;
+            const phase = resident.routine.phaseAt(boundary);
+            const arriving = !phase.travelling && Math.abs(phase.since - boundary) < 1e-6;
+            resident.stop = phase.stop;
+            resident.travelling = phase.travelling;
+            resident.place = phase.place;
+            resident.activity = phase.activity;
+            resident.position = positionFor(resident, phase);
+            if (arriving) {
+                const stop = resident.routine.stops[phase.stop];
+                if (stop?.refill != null) {
+                    resident.needs = { ...resident.needs };
+                    for (const needId of Object.keys(stop.refill)) {
+                        const def = defs.find((candidate) => candidate.id === needId);
+                        if (def === undefined)
+                            continue;
+                        const min = def.min ?? 0;
+                        resident.needs[needId] = Math.min(def.max, Math.max(min, (resident.needs[needId] ?? min) + stop.refill[needId]));
+                    }
+                }
+            }
+            resident.staleAt = resident.routine.nextChangeAfter(resident.updatedAt);
+        }
+    }
+    /** Keep a near resident's routine phase current and walk it to the next place when the clock moves it. */
+    function refreshNear(resident, now) {
+        if (resident.routine === null || now < resident.staleAt)
+            return;
+        const phase = resident.routine.phaseAt(now);
+        const moved = phase.place !== resident.place || phase.nextPlace !== resident.nextPlace;
+        resident.stop = phase.stop;
+        resident.travelling = phase.travelling;
+        resident.place = phase.place;
+        resident.activity = phase.activity;
+        resident.nextPlace = phase.nextPlace;
+        resident.updatedAt = now;
+        resident.staleAt = resident.routine.nextChangeAfter(now);
+        if (moved)
+            near.setGoal(resident.id, placeAt(phase.nextPlace ?? phase.place, resident.id));
+    }
+    function promote(resident, now) {
+        resolveFar(resident, now);
+        const phase = resident.routine === null ? null : resident.routine.phaseAt(now);
+        if (phase !== null) {
+            resident.stop = phase.stop;
+            resident.travelling = phase.travelling;
+            resident.place = phase.place;
+            resident.activity = phase.activity;
+            resident.nextPlace = phase.nextPlace;
+        }
+        resident.mode = "near";
+        promotions += 1;
+        near.spawn({
+            id: resident.id,
+            position: resident.position,
+            place: resident.place,
+            activity: resident.activity,
+            needs: { ...resident.needs },
+            goal: goalFor(resident),
+            stop: resident.stop,
+            travelling: resident.travelling,
+        });
+    }
+    function demote(resident, now) {
+        const handoff = near.despawn(resident.id);
+        resident.mode = "far";
+        demotions += 1;
+        if (handoff !== null) {
+            resident.position = handoff.position;
+            resident.needs = { ...handoff.needs };
+        }
+        resident.updatedAt = now;
+        resident.staleAt = resident.routine === null ? Infinity : resident.routine.nextChangeAfter(now);
+    }
+    function resolveFar(resident, now) {
+        refreshCheap(resident, now);
+    }
+    function probeLine() {
+        let nearCount = 0;
+        for (const resident of residents)
+            if (resident.mode === "near")
+                nearCount += 1;
+        const decisions = near.decisions?.() ?? 0;
+        return `${nearCount} near ${residents.length - nearCount} far ${promotions} promotions ${demotions} demotions ${farRefreshes} far refreshes ${decisions} decisions`;
+    }
+    const unregister = options.devtoolsName === undefined ? null : devtools.probes.register(options.devtoolsName, () => probeLine());
+    function toResident(spec) {
+        if (spec.routine !== null && spec.routine !== undefined) {
+            for (const stop of spec.routine.stops)
+                placeAt(stop.place, spec.id);
+        }
+        const needs = { ...initDecayMeters(defs) };
+        if (spec.needs !== undefined) {
+            for (const def of defs) {
+                const saved = spec.needs[def.id];
+                if (saved === undefined || !Number.isFinite(saved))
+                    continue;
+                const min = def.min ?? 0;
+                needs[def.id] = Math.min(def.max, Math.max(min, saved));
+            }
+        }
+        const resident = {
+            id: spec.id,
+            home: spec.home,
+            routine: spec.routine ?? null,
+            mode: "far",
+            position: spec.home,
+            place: null,
+            activity: null,
+            nextPlace: null,
+            stop: 0,
+            travelling: false,
+            pinned: spec.pinned === true,
+            updatedAt: 0,
+            staleAt: 0,
+            needs,
+            distance: Infinity,
+        };
+        if (resident.routine !== null) {
+            const phase = resident.routine.phaseAt(0);
+            resident.stop = phase.stop;
+            resident.travelling = phase.travelling;
+            resident.place = phase.place;
+            resident.activity = phase.activity;
+            resident.nextPlace = phase.nextPlace;
+            resident.position = positionFor(resident, phase);
+            resident.staleAt = resident.routine.nextChangeAfter(0);
+        }
+        return resident;
+    }
+    for (const spec of options.residents ?? []) {
+        if (residentOf.has(spec.id))
+            throw new Error(`duplicate off-screen resident "${spec.id}"`);
+        const resident = toResident(spec);
+        residentOf.set(spec.id, residents.length);
+        residents.push(resident);
+    }
+    function indexOf(id) {
+        return residentOf.get(id) ?? -1;
+    }
+    function livePosition(resident) {
+        if (resident.mode === "near") {
+            const live = near.position(resident.id);
+            if (live !== null)
+                return live;
+        }
+        return resident.position;
+    }
+    return {
+        add(spec) {
+            if (residentOf.has(spec.id))
+                return false;
+            const resident = toResident(spec);
+            residentOf.set(spec.id, residents.length);
+            residents.push(resident);
+            return true;
+        },
+        remove(id) {
+            const at = indexOf(id);
+            if (at < 0)
+                return false;
+            if (residents[at].mode === "near")
+                near.despawn(id);
+            const last = residents.pop();
+            residentOf.delete(id);
+            if (at < residents.length) {
+                residents[at] = last;
+                residentOf.set(last.id, at);
+            }
+            return true;
+        },
+        has: (id) => residentOf.has(id),
+        count: () => residents.length,
+        ids: () => residents.map((resident) => resident.id),
+        agent(id) {
+            const at = indexOf(id);
+            if (at < 0)
+                return null;
+            const resident = residents[at];
+            const live = resident.mode === "near" ? near.needs?.(resident.id) ?? null : null;
+            return {
+                id: resident.id,
+                mode: resident.mode,
+                position: livePosition(resident),
+                place: resident.place,
+                activity: resident.activity,
+                stop: resident.stop,
+                travelling: resident.travelling,
+                needs: { ...(live ?? resident.needs) },
+                pinned: resident.pinned,
+                distance: resident.distance,
+            };
+        },
+        pin(id, pinned = true) {
+            const at = indexOf(id);
+            if (at < 0)
+                return false;
+            residents[at].pinned = pinned;
+            return true;
+        },
+        needsAt(id, now) {
+            const at = indexOf(id);
+            if (at < 0)
+                return null;
+            const resident = residents[at];
+            if (resident.mode === "far")
+                resolveFar(resident, now);
+            else {
+                const live = near.needs?.(id) ?? null;
+                if (live !== null)
+                    return { ...live };
+            }
+            return { ...resident.needs };
+        },
+        tick(dt, now, viewer) {
+            let switches = switchBudget;
+            for (const resident of residents) {
+                if (resident.mode === "far" && now >= resident.staleAt)
+                    refreshCheap(resident, now);
+                resident.distance = distanceBetween(livePosition(resident), viewer);
+                const wantsNear = resident.pinned || resident.distance <= (resident.mode === "near" ? farRadius : nearRadius);
+                if (wantsNear === (resident.mode === "near"))
+                    continue;
+                if (switches <= 0)
+                    continue;
+                switches -= 1;
+                if (wantsNear)
+                    promote(resident, now);
+                else
+                    demote(resident, now);
+            }
+            if (nearBudget !== null && costModel !== undefined) {
+                let total = 0;
+                for (const resident of residents)
+                    if (resident.mode === "near")
+                        total += costModel(resident.id, resident.distance);
+                while (total > nearBudget && switches > 0) {
+                    let worst = null;
+                    let worstCost = -Infinity;
+                    for (const resident of residents) {
+                        if (resident.mode !== "near" || resident.pinned)
+                            continue;
+                        const cost = costModel(resident.id, resident.distance);
+                        if (cost > worstCost) {
+                            worst = resident;
+                            worstCost = cost;
+                        }
+                    }
+                    if (worst === null)
+                        break;
+                    demote(worst, now);
+                    total -= worstCost;
+                    switches -= 1;
+                }
+            }
+            near.tick(dt, now);
+            for (const resident of residents) {
+                if (resident.mode !== "near")
+                    continue;
+                const live = near.position(resident.id);
+                if (live !== null)
+                    resident.position = live;
+                refreshNear(resident, now);
+            }
+        },
+        stats() {
+            let nearCount = 0;
+            let farCount = 0;
+            for (const resident of residents) {
+                if (resident.mode === "near")
+                    nearCount += 1;
+                else
+                    farCount += 1;
+            }
+            return {
+                agents: residents.length,
+                near: nearCount,
+                far: farCount,
+                promotions,
+                demotions,
+                farRefreshes,
+                decisions: near.decisions?.() ?? 0,
+            };
+        },
+        retune(patch) {
+            if (patch.nearRadius !== undefined)
+                nearRadius = Math.max(0, patch.nearRadius);
+            if (patch.farRadius !== undefined)
+                farRadius = Math.max(nearRadius, patch.farRadius);
+            farRadius = Math.max(nearRadius, farRadius);
+            if (patch.costModel !== undefined)
+                costModel = patch.costModel;
+            if (patch.nearBudget !== undefined)
+                nearBudget = patch.nearBudget;
+            if (patch.switchBudget !== undefined)
+                switchBudget = Math.max(1, Math.floor(patch.switchBudget));
+        },
+        snapshot() {
+            const copy = residents.map((resident) => {
+                const live = resident.mode === "near" ? near.needs?.(resident.id) ?? null : null;
+                const livePos = resident.mode === "near" ? near.position(resident.id) : null;
+                return {
+                    id: resident.id,
+                    home: [resident.home[0], resident.home[1], resident.home[2]],
+                    mode: resident.mode,
+                    position: livePos === null ? resident.position : livePos,
+                    place: resident.place,
+                    activity: resident.activity,
+                    stop: resident.stop,
+                    travelling: resident.travelling,
+                    pinned: resident.pinned,
+                    updatedAt: resident.updatedAt,
+                    staleAt: resident.staleAt,
+                    needs: { ...(live ?? resident.needs) },
+                };
+            });
+            return {
+                policy: { nearRadius, farRadius, nearBudget, switchBudget },
+                residents: copy,
+            };
+        },
+        restore(next) {
+            const authored = new Map();
+            for (const resident of residents)
+                authored.set(resident.id, { home: resident.home, routine: resident.routine });
+            for (const resident of residents) {
+                if (resident.mode === "near")
+                    near.despawn(resident.id);
+            }
+            residents.length = 0;
+            residentOf.clear();
+            nearRadius = Math.max(0, next.policy.nearRadius);
+            farRadius = Math.max(nearRadius, next.policy.farRadius);
+            nearBudget = next.policy.nearBudget;
+            switchBudget = Math.max(1, Math.floor(next.policy.switchBudget));
+            for (const saved of next.residents) {
+                const source = authored.get(saved.id);
+                const resident = {
+                    id: saved.id,
+                    home: source?.home ?? saved.home,
+                    routine: source?.routine ?? null,
+                    mode: saved.mode,
+                    position: saved.position,
+                    place: saved.place,
+                    activity: saved.activity,
+                    nextPlace: null,
+                    stop: saved.stop,
+                    travelling: saved.travelling,
+                    pinned: saved.pinned,
+                    updatedAt: saved.updatedAt,
+                    staleAt: saved.staleAt,
+                    needs: { ...saved.needs },
+                    distance: Infinity,
+                };
+                if (resident.routine !== null) {
+                    const phase = resident.routine.phaseAt(resident.updatedAt);
+                    resident.nextPlace = phase.nextPlace;
+                    if (resident.mode === "near") {
+                        near.spawn({
+                            id: resident.id,
+                            position: resident.position,
+                            place: resident.place,
+                            activity: resident.activity,
+                            needs: { ...resident.needs },
+                            goal: placeAt(phase.nextPlace ?? phase.place, resident.id),
+                            stop: resident.stop,
+                            travelling: resident.travelling,
+                        });
+                    }
+                }
+                residentOf.set(resident.id, residents.length);
+                residents.push(resident);
+            }
+        },
+        dispose() {
+            unregister?.();
+            near.dispose?.();
+        },
+    };
+}

package/dist/sim/routine.d.ts

@@ -0,0 +1,79 @@
+/** One authored stop in a day: where the agent belongs, and when it wants to get there. */
+export interface RoutineStopSpec {
+    /** Opaque place id the agent occupies; the caller owns what a place means and where it stands. */
+    readonly place: string;
+    /** Authored arrival time in game-seconds into the cycle (0 .. `cycleSeconds`). */
+    readonly arriveAt: number;
+    /** Opaque activity label the stop is for ("work", "meal", "sleep"); never interpreted here. */
+    readonly activity?: string;
+    /** Seconds spent walking here from the previous stop; overrides `RoutineConfig.travelSeconds`. */
+    readonly travelSeconds?: number;
+    /** Need refills applied on arrival — a meal restores hunger while the agent stands there. */
+    readonly refill?: Readonly<Record<string, number>>;
+}
+/** Everything needed to resolve a routine: its authored stops, its cycle, and how far apart places are. */
+export interface RoutineConfig {
+    readonly stops: readonly RoutineStopSpec[];
+    /** Cycle length in game-seconds; default one game day (`SECONDS_PER_GAME_DAY`). */
+    readonly cycleSeconds?: number;
+    /**
+     * Injected travel time between two places, used when a stop does not author `travelSeconds`.
+     * Default `0`, so a routine of places that are all the same spot needs no travel at all.
+     */
+    readonly travelSeconds?: (from: string, to: string) => number;
+}
+/** One stop after travel is accounted for: the authored time and the time the agent really gets there. */
+export interface RoutineStop {
+    readonly index: number;
+    readonly place: string;
+    readonly activity: string | null;
+    /** The authored arrival time, in cycle seconds. */
+    readonly plannedArriveAt: number;
+    /** Real arrival — later than planned when the previous stop's walk ran into this one. */
+    readonly arriveAt: number;
+    /** When the agent must leave to reach the next stop on time; never before `arriveAt`. */
+    readonly departAt: number;
+    readonly refill: Readonly<Record<string, number>> | null;
+}
+/** Where a routine puts its agent at one instant. */
+export interface RoutinePhase {
+    /** Index of the stop held here, or the stop being walked away from. */
+    readonly stop: number;
+    /** Place the agent is at, or the place it is walking from. */
+    readonly place: string;
+    /** Place it is walking to; `null` while holding. */
+    readonly nextPlace: string | null;
+    readonly activity: string | null;
+    readonly travelling: boolean;
+    /** 0 at departure to 1 on arrival; `0` while holding. */
+    readonly progress: number;
+    /** Absolute game-second this phase began. */
+    readonly since: number;
+    /** Absolute game-second the next phase begins. */
+    readonly until: number;
+}
+/**
+ * An authored day resolved against time: arrival times after walking, departures early enough to
+ * make the next stop, and a phase for any instant. Pure — there is no state to tick, so a far agent
+ * and a loaded save read the same day from the same clock.
+ */
+export interface RoutineTimeline {
+    /** Seconds in one cycle. */
+    readonly cycleSeconds: number;
+    /** Stops in order, with real arrival and departure times. */
+    readonly stops: readonly RoutineStop[];
+    /** Where the routine puts the agent at absolute game-second `time`; wraps every cycle. */
+    phaseAt(time: number): RoutinePhase;
+    /** Absolute game-second of the next arrival or departure strictly after `time`. */
+    nextChangeAfter(time: number): number;
+}
+/**
+ * Resolve an authored routine into a timeline driven by the world clock.
+ *
+ * Travel is what makes arrival times real: each stop departs early enough to walk there on time,
+ * and when the previous stop ran long the arrival slips instead of the agent teleporting. A day
+ * whose walks cannot fit its cycle throws rather than silently putting the agent in two places.
+ *
+ * @capability routine-timeline authored daily routines (home, work, meal) resolved against the world clock
+ */
+export declare function resolveRoutine(config: RoutineConfig): RoutineTimeline;

package/dist/sim/routine.js

@@ -0,0 +1,137 @@
+import { SECONDS_PER_GAME_DAY } from "../time/gameClock.js";
+function wrap(value, cycle) {
+    return ((value % cycle) + cycle) % cycle;
+}
+/**
+ * Resolve an authored routine into a timeline driven by the world clock.
+ *
+ * Travel is what makes arrival times real: each stop departs early enough to walk there on time,
+ * and when the previous stop ran long the arrival slips instead of the agent teleporting. A day
+ * whose walks cannot fit its cycle throws rather than silently putting the agent in two places.
+ *
+ * @capability routine-timeline authored daily routines (home, work, meal) resolved against the world clock
+ */
+export function resolveRoutine(config) {
+    if (config.stops.length === 0)
+        throw new Error("routine needs at least one stop");
+    const cycleSeconds = config.cycleSeconds !== undefined && config.cycleSeconds > 0 ? config.cycleSeconds : SECONDS_PER_GAME_DAY;
+    const specs = config.stops;
+    for (let i = 0; i < specs.length; i += 1) {
+        const stop = specs[i];
+        if (!Number.isFinite(stop.arriveAt) || stop.arriveAt < 0 || stop.arriveAt >= cycleSeconds) {
+            throw new Error(`routine stop ${i} ("${stop.place}") needs arriveAt in [0, ${cycleSeconds}), got ${stop.arriveAt}`);
+        }
+        if (i > 0 && stop.arriveAt <= specs[i - 1].arriveAt) {
+            throw new Error(`routine stops must be authored in ascending order; "${stop.place}" is not after "${specs[i - 1].place}"`);
+        }
+    }
+    const travelFrom = (from) => {
+        const index = from % specs.length;
+        const stop = specs[index];
+        if (stop.travelSeconds !== undefined)
+            return Math.max(0, stop.travelSeconds);
+        if (config.travelSeconds === undefined || specs.length < 2)
+            return 0;
+        const previous = specs[(index - 1 + specs.length) % specs.length];
+        return Math.max(0, config.travelSeconds(previous.place, stop.place));
+    };
+    const arrive = [];
+    for (let i = 0; i < specs.length; i += 1) {
+        const planned = specs[i].arriveAt;
+        arrive.push(i === 0 ? planned : Math.max(planned, arrive[i - 1] + travelFrom(i)));
+    }
+    const depart = [];
+    for (let i = 0; i < specs.length; i += 1) {
+        const nextArrive = i + 1 < specs.length ? arrive[i + 1] : arrive[0] + cycleSeconds;
+        const leave = nextArrive - travelFrom(i + 1 < specs.length ? i + 1 : 0);
+        if (leave < arrive[i] - 1e-9) {
+            let needed = 0;
+            for (let index = 0; index < specs.length; index += 1)
+                needed += travelFrom(index);
+            throw new Error(`routine does not fit its ${cycleSeconds} s cycle: it needs ${needed} s of walking and the stops leave too little room`);
+        }
+        depart.push(Math.max(arrive[i], leave));
+    }
+    const stops = specs.map((spec, index) => ({
+        index,
+        place: spec.place,
+        activity: spec.activity ?? null,
+        plannedArriveAt: spec.arriveAt,
+        arriveAt: arrive[index],
+        departAt: depart[index],
+        refill: spec.refill === undefined ? null : { ...spec.refill },
+    }));
+    function phaseAt(time) {
+        const cycle = Math.floor(time / cycleSeconds) * cycleSeconds;
+        const local = wrap(time, cycleSeconds);
+        if (stops.length === 1) {
+            const only = stops[0];
+            return {
+                stop: 0,
+                place: only.place,
+                nextPlace: null,
+                activity: only.activity,
+                travelling: false,
+                progress: 0,
+                since: cycle + only.arriveAt,
+                until: cycle + only.arriveAt + cycleSeconds,
+            };
+        }
+        for (const stop of stops) {
+            if (local >= stop.arriveAt && local < stop.departAt) {
+                return {
+                    stop: stop.index,
+                    place: stop.place,
+                    nextPlace: null,
+                    activity: stop.activity,
+                    travelling: false,
+                    progress: 0,
+                    since: cycle + stop.arriveAt,
+                    until: cycle + stop.departAt,
+                };
+            }
+        }
+        let from = stops.length - 1;
+        for (let i = 0; i < stops.length; i += 1) {
+            if (stops[i].departAt <= local)
+                from = i;
+        }
+        const next = (from + 1) % stops.length;
+        const departLocal = stops[from].departAt;
+        const arriveLocal = stops[next].arriveAt + (next === 0 ? cycleSeconds : 0);
+        const span = arriveLocal - departLocal;
+        const start = departLocal > local ? departLocal - cycleSeconds : departLocal;
+        const raw = span <= 0 ? 1 : (local - start) / span;
+        const progress = Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : 1;
+        return {
+            stop: from,
+            place: stops[from].place,
+            nextPlace: stops[next].place,
+            activity: null,
+            travelling: true,
+            progress,
+            since: cycle + start,
+            until: cycle + start + span,
+        };
+    }
+    return {
+        cycleSeconds,
+        stops,
+        phaseAt,
+        nextChangeAfter(time) {
+            const cycle = Math.floor(time / cycleSeconds) * cycleSeconds;
+            const local = wrap(time, cycleSeconds);
+            let best = Infinity;
+            for (const stop of stops) {
+                for (const boundary of [stop.arriveAt, stop.departAt]) {
+                    let candidate = boundary;
+                    if (candidate <= local)
+                        candidate += cycleSeconds;
+                    if (candidate < best)
+                        best = candidate;
+                }
+            }
+            return cycle + best;
+        },
+    };
+}