@jgengine/core 0.17.0 → 0.18.1

package/dist/runtime/poseInterpolation.js

@@ -0,0 +1,91 @@
+const TWO_PI = Math.PI * 2;
+/** Shortest-arc interpolation between two yaw angles. */
+export function lerpAngle(from, to, t) {
+    let delta = (to - from) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    else if (delta < -Math.PI)
+        delta += TWO_PI;
+    return from + delta * t;
+}
+/**
+ * Previous-step pose buffer for render interpolation under a fixed-step loop. Reuses one 4-slot array per
+ * entity so a step over N entities allocates only for entities seen for the first time.
+ *
+ * @capability pose-interpolation render entity poses between fixed simulation steps without stutter
+ */
+export function createPoseHistory(options) {
+    let snapDistance = options?.snapDistance ?? 8;
+    const previous = new Map();
+    const seen = new Set();
+    return {
+        beginStep(entities) {
+            seen.clear();
+            for (const entity of entities.list()) {
+                seen.add(entity.id);
+                let slot = previous.get(entity.id);
+                if (slot === undefined) {
+                    slot = [0, 0, 0, 0];
+                    previous.set(entity.id, slot);
+                }
+                slot[0] = entity.position[0];
+                slot[1] = entity.position[1];
+                slot[2] = entity.position[2];
+                slot[3] = entity.rotationY;
+            }
+            if (previous.size !== seen.size) {
+                for (const id of previous.keys()) {
+                    if (!seen.has(id))
+                        previous.delete(id);
+                }
+            }
+        },
+        sample(entities, id, alpha, out) {
+            const live = entities.get(id);
+            if (live === null)
+                return false;
+            const prev = previous.get(id);
+            const t = alpha < 0 ? 0 : alpha > 1 ? 1 : alpha;
+            if (prev === undefined || t >= 1) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            const dx = live.position[0] - prev[0];
+            const dy = live.position[1] - prev[1];
+            const dz = live.position[2] - prev[2];
+            if (dx * dx + dy * dy + dz * dz > snapDistance * snapDistance) {
+                out[0] = live.position[0];
+                out[1] = live.position[1];
+                out[2] = live.position[2];
+                out[3] = live.rotationY;
+                return true;
+            }
+            out[0] = prev[0] + dx * t;
+            out[1] = prev[1] + dy * t;
+            out[2] = prev[2] + dz * t;
+            out[3] = lerpAngle(prev[3], live.rotationY, t);
+            return true;
+        },
+        snap(id) {
+            previous.delete(id);
+        },
+        retune(next) {
+            if (next.snapDistance !== undefined)
+                snapDistance = next.snapDistance;
+        },
+        snapshot() {
+            const copy = {};
+            for (const [id, pose] of previous)
+                copy[id] = [pose[0], pose[1], pose[2], pose[3]];
+            return { previous: copy };
+        },
+        restore(state) {
+            previous.clear();
+            for (const [id, pose] of Object.entries(state.previous))
+                previous.set(id, [pose[0], pose[1], pose[2], pose[3]]);
+        },
+    };
+}

package/dist/runtime/prediction.d.ts

@@ -0,0 +1,45 @@
+import type { InputFrame } from "./inputSnapshot.js";
+/** Deterministic state transition used to advance one predicted input frame. */
+export type PredictionStep<S> = (state: S, input: InputFrame, dt: number) => S;
+/** One input, tick, and resulting state retained for authoritative replay. */
+export type PredictionRecord<S> = {
+    tick: number;
+    input: InputFrame;
+    state: S;
+    dt: number;
+};
+/** Serializable prediction state containing the confirmation baseline and pending input history. */
+export type PredictionSnapshot<S> = {
+    confirmedTick: number;
+    confirmed: S;
+    predicted: S;
+    records: PredictionRecord<S>[];
+};
+/** Stateful prediction handle supporting recording, reconciliation, inspection, and restoration. */
+export type PredictionBuffer<S> = {
+    record(input: InputFrame, dt?: number, observedState?: S): S;
+    reconcile(tick: number, authoritative: S): {
+        error: number;
+        replayed: number;
+        snapped: boolean;
+        state: S;
+    };
+    state(): S;
+    snapshot(): PredictionSnapshot<S>;
+    restore(next: PredictionSnapshot<S>): void;
+};
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export declare function createPredictionBuffer<S>(config: {
+    initial: S;
+    step: PredictionStep<S>;
+    maxTicks: number;
+    startTick?: number;
+    dt?: number;
+    /** Error above which a caller should snap its rendered pose to the reconciled result. */
+    snapThreshold?: number;
+}): PredictionBuffer<S>;

package/dist/runtime/prediction.js

@@ -0,0 +1,62 @@
+/**
+ * Keeps local input predictions ahead of the last server confirmation. Reconciliation replaces the
+ * confirmed state and deterministically replays unconfirmed inputs through the supplied step function.
+ * `maxTicks` bounds retained work and memory; dropped inputs are folded into the confirmed baseline.
+ * @capability client-side input prediction with replay reconciliation
+ */
+export function createPredictionBuffer(config) {
+    const maxTicks = Math.max(1, Math.floor(config.maxTicks));
+    const step = config.step;
+    let confirmedTick = config.startTick ?? 0;
+    let confirmed = config.initial;
+    let predicted = config.initial;
+    let records = [];
+    const defaultDt = config.dt ?? 1 / 60;
+    const snapThreshold = Math.max(0, config.snapThreshold ?? 0.1);
+    const replay = (base, pending) => {
+        let next = base;
+        for (const record of pending)
+            next = step(next, record.input, record.dt);
+        return next;
+    };
+    return {
+        record(input, dt = defaultDt, observedState) {
+            const tick = confirmedTick + records.length + 1;
+            const state = observedState === undefined ? step(predicted, input, dt) : observedState;
+            records.push({ tick, input, state, dt });
+            predicted = state;
+            if (records.length > maxTicks) {
+                const oldest = records.shift();
+                confirmedTick = oldest.tick;
+                confirmed = oldest.state;
+            }
+            return predicted;
+        },
+        reconcile(tick, authoritative) {
+            const predictedAtTick = records.find((record) => record.tick === tick)?.state ?? confirmed;
+            const distance = (a, b) => {
+                if (typeof a === "number" && typeof b === "number")
+                    return Math.abs(a - b);
+                if (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v) => typeof v === "number") && b.every((v) => typeof v === "number")) {
+                    return Math.sqrt(a.reduce((sum, value, index) => sum + (Number(value) - Number(b[index])) ** 2, 0));
+                }
+                return JSON.stringify(a) === JSON.stringify(b) ? 0 : 1;
+            };
+            const dx = distance(predictedAtTick, authoritative);
+            const pending = records.filter((record) => record.tick > tick);
+            confirmedTick = tick;
+            confirmed = authoritative;
+            records = pending;
+            predicted = replay(confirmed, records);
+            return { error: dx, replayed: records.length, snapped: dx > snapThreshold, state: predicted };
+        },
+        state: () => predicted,
+        snapshot: () => ({ confirmedTick, confirmed, predicted, records: records.map((record) => ({ ...record })) }),
+        restore(next) {
+            confirmedTick = next.confirmedTick;
+            confirmed = next.confirmed;
+            predicted = next.predicted;
+            records = next.records.map((record) => ({ ...record }));
+        },
+    };
+}

package/dist/runtime/simContext.d.ts

@@ -0,0 +1,45 @@
+import type { EntityStore } from "../scene/entityStore.js";
+import { type PoseHistory, type RenderPose } from "./poseInterpolation.js";
+import { type SimAdvanceResult, type SimLoop, type SimulationConfig } from "./simLoop.js";
+/** Where a registered stage runs inside one simulation step. */
+export type SimStagePhase = "beforeMovement" | "afterMovement" | "afterTick";
+/** Extra work a game or engine seam (a physics backend, a netcode buffer) runs inside every simulation step. */
+export interface SimStage {
+    id: string;
+    phase: SimStagePhase;
+    run(dt: number, tick: number): void;
+}
+/** Serializable `ctx.sim` state: loop position plus the interpolation pose history. */
+export interface SimContextState {
+    loop: ReturnType<SimLoop["snapshot"]>;
+    poses: ReturnType<PoseHistory["snapshot"]>;
+}
+/**
+ * `ctx.sim`: the simulation stepper shared by every driver plus the render-side interpolation it enables.
+ * Drivers call {@link advance} with real elapsed seconds and do their per-step work inside the callback;
+ * renderers call {@link renderPose} each frame.
+ */
+export interface SimContext {
+    readonly loop: SimLoop;
+    /** Advance the loop; `body` runs once per simulation step with that step's dt. Pose history is captured before each step. */
+    advance(realDt: number, body: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    /** Interpolation fraction for the current frame, 1 on a variable loop. */
+    alpha(): number;
+    /** Interpolated pose for rendering; live pose on a variable loop. `false` when the entity does not exist. */
+    renderPose(id: string, out: RenderPose): boolean;
+    /** Forget an entity's interpolation history so it renders at its live pose next frame. */
+    snapPose(id: string): void;
+    /** Register a stage; returns an unregister handle. Stages run in registration order within a phase. */
+    addStage(stage: SimStage): () => void;
+    /** Run every stage registered for `phase`; drivers call this from inside {@link advance}'s body. */
+    runStages(phase: SimStagePhase, dt: number): void;
+    retune(config: SimulationConfig): void;
+    snapshot(): SimContextState;
+    restore(state: SimContextState): void;
+}
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export declare function createSimContext(options: {
+    config?: SimulationConfig;
+    entities: EntityStore;
+}): SimContext;

package/dist/runtime/simContext.js

@@ -0,0 +1,65 @@
+import { createPoseHistory } from "./poseInterpolation.js";
+import { createSimLoop } from "./simLoop.js";
+/** Build `ctx.sim` for a context; `createGameContext` calls this from `definition.simulation`. */
+export function createSimContext(options) {
+    const { entities } = options;
+    const loop = createSimLoop(options.config);
+    const poses = createPoseHistory({ snapDistance: loop.config().snapDistance });
+    const stages = new Map();
+    let advancing = false;
+    return {
+        loop,
+        advance(realDt, body) {
+            if (advancing)
+                throw new Error("ctx.sim.advance is not reentrant");
+            advancing = true;
+            try {
+                return loop.advance(realDt, (dt, tick) => {
+                    if (loop.isFixed())
+                        poses.beginStep(entities);
+                    body(dt, tick);
+                });
+            }
+            finally {
+                advancing = false;
+            }
+        },
+        tick: () => loop.tick(),
+        alpha: () => loop.alpha(),
+        renderPose(id, out) {
+            return poses.sample(entities, id, loop.isFixed() ? loop.alpha() : 1, out);
+        },
+        snapPose: (id) => poses.snap(id),
+        addStage(stage) {
+            const list = stages.get(stage.phase) ?? [];
+            list.push(stage);
+            stages.set(stage.phase, list);
+            return () => {
+                const current = stages.get(stage.phase);
+                if (current === undefined)
+                    return;
+                const index = current.indexOf(stage);
+                if (index >= 0)
+                    current.splice(index, 1);
+            };
+        },
+        runStages(phase, dt) {
+            const list = stages.get(phase);
+            if (list === undefined)
+                return;
+            const tick = loop.tick();
+            for (const stage of list)
+                stage.run(dt, tick);
+        },
+        retune(config) {
+            loop.retune(config);
+            if (config.snapDistance !== undefined)
+                poses.retune({ snapDistance: config.snapDistance });
+        },
+        snapshot: () => ({ loop: loop.snapshot(), poses: poses.snapshot() }),
+        restore(state) {
+            loop.restore(state.loop);
+            poses.restore(state.poses);
+        },
+    };
+}

package/dist/runtime/simLoop.d.ts

@@ -0,0 +1,52 @@
+/** How the simulation is stepped: a fixed rate with a catch-up cap, or once per frame with the frame's dt. */
+export interface SimulationConfig {
+    /**
+     * Fixed simulation rate in steps per second, or `"variable"` to run one step per frame with the frame's
+     * clamped dt. Default `"variable"` (the historical behavior). A fixed rate makes every step's dt identical,
+     * which is what determinism, replay, rollback, and a stable physics solver need; renderers read
+     * `ctx.sim.renderPose` to interpolate between steps.
+     */
+    hz?: number | "variable";
+    /** Fixed steps run per advance before the loop drops the remaining time instead of spiralling. Default 5. */
+    maxCatchUpSteps?: number;
+    /** Entities that move farther than this in one step snap instead of interpolating (teleports, respawns). Default 8 world units. */
+    snapDistance?: number;
+}
+/** Serializable loop position: the tick count and the real seconds accumulated toward the next fixed step. */
+export interface SimLoopState {
+    tick: number;
+    accumulator: number;
+}
+/** What one {@link SimLoop.advance} did. */
+export interface SimAdvanceResult {
+    /** Steps run this advance. */
+    steps: number;
+    /** Fraction of a step accumulated but not yet simulated, 0..1; always 1 on a variable loop. */
+    alpha: number;
+    /** Tick count after this advance. */
+    tick: number;
+    /** Steps discarded because the catch-up cap was hit. */
+    dropped: number;
+}
+/** The stepper handle: advance with real time, read the tick and interpolation alpha, retune the rate, snapshot and restore. */
+export interface SimLoop {
+    /** Feed real elapsed seconds; runs `step(dt, tick)` zero or more times and returns what happened. */
+    advance(realDt: number, step: (dt: number, tick: number) => void): SimAdvanceResult;
+    tick(): number;
+    alpha(): number;
+    /** Seconds per fixed step, `null` on a variable loop. */
+    stepSeconds(): number | null;
+    isFixed(): boolean;
+    retune(config: SimulationConfig): void;
+    config(): Readonly<Required<SimulationConfig>>;
+    snapshot(): SimLoopState;
+    restore(state: SimLoopState): void;
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export declare function createSimLoop(initial?: SimulationConfig): SimLoop;

package/dist/runtime/simLoop.js

@@ -0,0 +1,72 @@
+const DEFAULT_MAX_CATCH_UP = 5;
+const DEFAULT_SNAP_DISTANCE = 8;
+function resolveConfig(config) {
+    const hz = config?.hz;
+    return {
+        hz: typeof hz === "number" && Number.isFinite(hz) && hz > 0 ? hz : "variable",
+        maxCatchUpSteps: Math.max(1, Math.floor(config?.maxCatchUpSteps ?? DEFAULT_MAX_CATCH_UP)),
+        snapDistance: config?.snapDistance ?? DEFAULT_SNAP_DISTANCE,
+    };
+}
+/**
+ * The simulation stepper every driver (shell frame, headless runner, authoritative host) advances through, so
+ * the sim sees the same dt sequence regardless of who drives it. Fixed mode accumulates real time and steps in
+ * equal slices with a catch-up cap; variable mode steps once per advance.
+ *
+ * @capability sim-loop fixed-step or variable simulation stepping with tick count, catch-up cap, and interpolation alpha
+ */
+export function createSimLoop(initial) {
+    let config = resolveConfig(initial);
+    let tick = 0;
+    let accumulator = 0;
+    let alpha = 1;
+    function stepSeconds() {
+        return config.hz === "variable" ? null : 1 / config.hz;
+    }
+    return {
+        advance(realDt, step) {
+            if (!(realDt > 0))
+                return { steps: 0, alpha, tick, dropped: 0 };
+            const stepDt = stepSeconds();
+            if (stepDt === null) {
+                tick += 1;
+                alpha = 1;
+                step(realDt, tick);
+                return { steps: 1, alpha, tick, dropped: 0 };
+            }
+            accumulator += realDt;
+            let steps = 0;
+            while (accumulator >= stepDt && steps < config.maxCatchUpSteps) {
+                tick += 1;
+                step(stepDt, tick);
+                accumulator -= stepDt;
+                steps += 1;
+            }
+            let dropped = 0;
+            if (accumulator >= stepDt) {
+                dropped = Math.floor(accumulator / stepDt);
+                accumulator -= dropped * stepDt;
+            }
+            alpha = accumulator / stepDt;
+            return { steps, alpha, tick, dropped };
+        },
+        tick: () => tick,
+        alpha: () => alpha,
+        stepSeconds,
+        isFixed: () => config.hz !== "variable",
+        retune(next) {
+            config = resolveConfig({ ...config, ...next });
+            if (config.hz === "variable") {
+                accumulator = 0;
+                alpha = 1;
+            }
+        },
+        config: () => config,
+        snapshot: () => ({ tick, accumulator }),
+        restore(state) {
+            tick = state.tick;
+            accumulator = state.accumulator;
+            alpha = config.hz === "variable" ? 1 : accumulator * config.hz;
+        },
+    };
+}

package/dist/runtime/simSnapshot.d.ts

@@ -0,0 +1,32 @@
+import type { GameContext } from "./gameContext.js";
+/** One piece of simulation state that can be captured and restored by id. */
+export interface SimSnapshotContributor<T = unknown> {
+    id: string;
+    capture(): T;
+    restore(data: T): void;
+}
+/** Captured contributor data keyed by contributor id. */
+export type SimSnapshot = Record<string, unknown>;
+/** Registry of {@link SimSnapshotContributor}s that captures and restores them together. */
+export interface SimSnapshotRegistry {
+    register<T>(contributor: SimSnapshotContributor<T>): () => void;
+    capture(): SimSnapshot;
+    /** Alias of {@link capture}, matching the engine's snapshot/restore naming. */
+    snapshot(): SimSnapshot;
+    /** Restore every contributor present in `snapshot`; contributors missing from it are left untouched. */
+    restore(snapshot: SimSnapshot): void;
+    ids(): string[];
+}
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export declare function createSimSnapshotRegistry(): SimSnapshotRegistry;
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export declare function createContextSimSnapshot(ctx: GameContext): SimSnapshotRegistry;

package/dist/runtime/simSnapshot.js

@@ -0,0 +1,60 @@
+import { rngStateOf, restoreRng } from "../random/rng.js";
+/**
+ * A registry of everything that must round-trip for a simulation to resume bit-for-bit: world state, the
+ * clock, the rng cursor, the loop accumulator, and whatever a physics backend or game adds. Pair with
+ * {@link createInputRecorder} for replay.
+ *
+ * @capability sim-snapshot capture and restore whole-simulation state for replay, rollback, and regression tests
+ */
+export function createSimSnapshotRegistry() {
+    const contributors = new Map();
+    function capture() {
+        const out = {};
+        for (const [id, contributor] of contributors)
+            out[id] = contributor.capture();
+        return out;
+    }
+    return {
+        register(contributor) {
+            if (contributors.has(contributor.id)) {
+                throw new Error(`sim snapshot contributor "${contributor.id}" is already registered`);
+            }
+            contributors.set(contributor.id, contributor);
+            return () => {
+                contributors.delete(contributor.id);
+            };
+        },
+        capture,
+        snapshot: capture,
+        restore(snapshot) {
+            for (const [id, contributor] of contributors) {
+                if (id in snapshot)
+                    contributor.restore(snapshot[id]);
+            }
+        },
+        ids: () => Array.from(contributors.keys()),
+    };
+}
+/**
+ * The engine's own contributors for a context: replicated world state, the sim clock, the loop and pose
+ * history, and the rng cursor when `ctx.rng` is a seeded stream. Games register theirs on the same registry.
+ */
+export function createContextSimSnapshot(ctx) {
+    const registry = createSimSnapshotRegistry();
+    // ctx.snapshot() hands back live rows; clone both ways so a captured snapshot stays frozen while the sim keeps running.
+    registry.register({
+        id: "world",
+        capture: () => structuredClone(ctx.snapshot()),
+        restore: (data) => ctx.hydrate(structuredClone(data)),
+    });
+    registry.register({ id: "clock", capture: () => ctx.time.snapshot(), restore: (data) => ctx.time.hydrate(data) });
+    registry.register({ id: "sim", capture: () => ctx.sim.snapshot(), restore: (data) => ctx.sim.restore(data) });
+    if (rngStateOf(ctx.rng) !== null) {
+        registry.register({
+            id: "rng",
+            capture: () => rngStateOf(ctx.rng) ?? 0,
+            restore: (cursor) => restoreRng(ctx.rng, cursor),
+        });
+    }
+    return registry;
+}

package/dist/runtime/snapshot.d.ts

@@ -36,6 +36,8 @@ export type RuntimeInventorySlot = {
     slot?: number;
 };
 export type RuntimePlayerRow = {
+    territoryOwnedCount?: number;
+    ownedTerritoryChunkKeys?: string[];
     userId: string;
     inventories: Record<string, RuntimeInventorySlot[]>;
     economy: Record<string, number>;
@@ -46,6 +48,12 @@ export type RuntimePlayerRow = {
     session?: Record<string, unknown>;
 };
 export type RuntimeChunkRow = {
+    /** Cell key to owner id, persisted with its spatial chunk. */
+    territory?: Record<string, string>;
+    territoryReceipts?: Record<string, {
+        claimedAt: number;
+        costPaid: number;
+    }>;
     chunkKey: string;
     objects: RuntimeObjectRow[];
     entities: RuntimeEntityRow[];

package/dist/runtime/snapshotBuffer.d.ts

@@ -0,0 +1,33 @@
+/** A sampled pair of snapshots and interpolation factor. */
+export type SnapshotBufferSample<T> = {
+    before: T;
+    after: T;
+    alpha: number;
+};
+/** Serializable snapshot-buffer state. */
+export type SnapshotBufferState<T> = {
+    delayMs: number;
+    capacity: number;
+    entries: Array<{
+        atMs: number;
+        value: T;
+    }>;
+};
+/** Handle for a timestamped delayed snapshot buffer. */
+export type SnapshotBuffer<T> = {
+    push(atMs: number, value: T): void;
+    sampleAt(nowMs: number): SnapshotBufferSample<T> | null;
+    snapshot(): SnapshotBufferState<T>;
+    restore(next: SnapshotBufferState<T>): void;
+    retune(config: {
+        delayMs?: number;
+        capacity?: number;
+    }): void;
+};
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export declare function createSnapshotBuffer<T>(config: {
+    delayMs: number;
+    capacity: number;
+}): SnapshotBuffer<T>;

package/dist/runtime/snapshotBuffer.js

@@ -0,0 +1,58 @@
+/** Stores timestamped snapshots and samples a delayed, interpolatable pair.
+ * @capability runtime snapshot interpolation
+ */
+export function createSnapshotBuffer(config) {
+    let delayMs = Math.max(0, config.delayMs);
+    let capacity = Math.max(1, Math.floor(config.capacity));
+    let entries = [];
+    const trim = () => {
+        if (entries.length > capacity)
+            entries = entries.slice(-capacity);
+    };
+    return {
+        push(atMs, value) {
+            const entry = { atMs, value };
+            const index = entries.findIndex((item) => item.atMs > atMs);
+            if (index < 0)
+                entries.push(entry);
+            else
+                entries.splice(index, 0, entry);
+            trim();
+        },
+        sampleAt(nowMs) {
+            if (entries.length === 0)
+                return null;
+            const target = nowMs - delayMs;
+            if (target <= entries[0].atMs)
+                return { before: entries[0].value, after: entries[0].value, alpha: 0 };
+            const last = entries[entries.length - 1];
+            if (target >= last.atMs)
+                return { before: last.value, after: last.value, alpha: 1 };
+            for (let i = 1; i < entries.length; i += 1) {
+                const after = entries[i];
+                if (target <= after.atMs) {
+                    const before = entries[i - 1];
+                    const span = after.atMs - before.atMs;
+                    return { before: before.value, after: after.value, alpha: span === 0 ? 1 : (target - before.atMs) / span };
+                }
+            }
+            return null;
+        },
+        snapshot() {
+            return { delayMs, capacity, entries: entries.map((entry) => ({ ...entry })) };
+        },
+        restore(next) {
+            delayMs = Math.max(0, next.delayMs);
+            capacity = Math.max(1, Math.floor(next.capacity));
+            entries = next.entries.map((entry) => ({ ...entry })).sort((a, b) => a.atMs - b.atMs);
+            trim();
+        },
+        retune(config) {
+            if (config.delayMs !== undefined)
+                delayMs = Math.max(0, config.delayMs);
+            if (config.capacity !== undefined)
+                capacity = Math.max(1, Math.floor(config.capacity));
+            trim();
+        },
+    };
+}