@jgengine/core 0.8.0 → 0.9.0

package/dist/scene/sceneRaycast.d.ts

@@ -0,0 +1,80 @@
+import type { EntityPosition } from "./entityStore.js";
+import { type ColliderPurpose, type EntityColliderSet } from "./colliders.js";
+import type { SceneObject } from "./objectStore.js";
+export type SceneRaycastTargetKind = "entity" | "object" | "terrain" | "wall";
+export interface SceneRaycastHit {
+    targetKind: SceneRaycastTargetKind;
+    instanceId: string;
+    catalogId?: string;
+    colliderName: string;
+    purpose: ColliderPurpose;
+    damageEligible: boolean;
+    blocks: boolean;
+    distance: number;
+    point: EntityPosition;
+    normal: EntityPosition;
+}
+export interface SceneRaycastFilter {
+    entities?: boolean;
+    objects?: boolean;
+    terrain?: boolean;
+    walls?: boolean;
+}
+export interface SceneRaycastInput {
+    origin: EntityPosition;
+    direction: EntityPosition;
+    maxDistance: number;
+    excludeInstanceIds?: ReadonlySet<string> | readonly string[];
+    filter?: SceneRaycastFilter;
+    /** When set, only hits satisfying the predicate are kept (applied after geometry). */
+    accept?: (hit: SceneRaycastHit) => boolean;
+}
+export interface SceneEntityQuerySource {
+    list(): readonly {
+        id: string;
+        position: EntityPosition;
+        rotationY: number;
+        name?: string;
+    }[];
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    inRadius?(center: EntityPosition, radius: number): readonly string[];
+    get?(instanceId: string): {
+        id: string;
+        position: EntityPosition;
+        rotationY: number;
+        name?: string;
+    } | null;
+}
+export interface SceneObjectQuerySource {
+    list(): readonly SceneObject[];
+    inBox?(min: EntityPosition, max: EntityPosition): readonly SceneObject[];
+    collidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    halfExtentsOf?(catalogId: string): EntityPosition | null | undefined;
+}
+export interface TerrainRaycastSource {
+    sampleHeight(x: number, z: number): number;
+}
+export interface WallSegment {
+    id: string;
+    /** Segment endpoints on the XZ plane; extruded by halfHeight along Y around yCenter. */
+    a: readonly [number, number];
+    b: readonly [number, number];
+    yCenter?: number;
+    halfHeight?: number;
+    thickness?: number;
+}
+export interface SceneRaycastDeps {
+    entities?: SceneEntityQuerySource;
+    objects?: SceneObjectQuerySource;
+    terrain?: TerrainRaycastSource;
+    walls?: readonly WallSegment[];
+}
+export interface SceneRaycastApi {
+    raycast(input: SceneRaycastInput): SceneRaycastHit | null;
+    raycastAll(input: SceneRaycastInput): SceneRaycastHit[];
+}
+/** First impact: nearest hit that blocks, or nearest hit if none block. */
+export declare function firstImpact(hits: readonly SceneRaycastHit[]): SceneRaycastHit | null;
+/** Hits up to and including the first blocking collider (damage hitboxes before a wall stay). */
+export declare function hitsUntilBlocked(hits: readonly SceneRaycastHit[]): SceneRaycastHit[];
+export declare function createSceneRaycast(deps: SceneRaycastDeps): SceneRaycastApi;

package/dist/scene/sceneRaycast.js

@@ -0,0 +1,284 @@
+import { colliderBounds, colliderWorldCenter, defaultEntityColliders, defaultObjectColliders, resolveColliders, } from "./colliders.js";
+import { intersectAabb, normalizeDirection } from "./objectQuery.js";
+function excluded(exclude, id) {
+    if (exclude === undefined)
+        return false;
+    if (typeof exclude.has === "function") {
+        return exclude.has(id);
+    }
+    for (const value of exclude) {
+        if (value === id)
+            return true;
+    }
+    return false;
+}
+function enabled(filter, key) {
+    if (filter === undefined)
+        return true;
+    return filter[key] !== false;
+}
+function rayHitsSphere(origin, direction, center, radius, maxDistance) {
+    const ox = origin[0] - center[0];
+    const oy = origin[1] - center[1];
+    const oz = origin[2] - center[2];
+    const b = ox * direction[0] + oy * direction[1] + oz * direction[2];
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    const disc = b * b - c;
+    if (disc < 0)
+        return null;
+    const sqrt = Math.sqrt(disc);
+    let t = -b - sqrt;
+    if (t < 0)
+        t = -b + sqrt;
+    if (t < 0 || t > maxDistance)
+        return null;
+    const px = origin[0] + direction[0] * t - center[0];
+    const py = origin[1] + direction[1] * t - center[1];
+    const pz = origin[2] + direction[2] * t - center[2];
+    const len = Math.hypot(px, py, pz) || 1;
+    return { distance: t, normal: [px / len, py / len, pz / len] };
+}
+function rayHitsCollider(origin, direction, maxDistance, collider, position, rotationY) {
+    if (collider.shape.kind === "sphere") {
+        const center = colliderWorldCenter(collider, position, rotationY);
+        const hit = rayHitsSphere(origin, direction, center, collider.shape.radius, maxDistance);
+        if (hit === null)
+            return null;
+        return {
+            distance: hit.distance,
+            normal: hit.normal,
+            point: [
+                origin[0] + direction[0] * hit.distance,
+                origin[1] + direction[1] * hit.distance,
+                origin[2] + direction[2] * hit.distance,
+            ],
+        };
+    }
+    const bounds = colliderBounds(collider, position, rotationY);
+    const hit = intersectAabb(origin, direction, bounds.min, bounds.max, maxDistance);
+    if (hit === null)
+        return null;
+    return {
+        distance: hit.distance,
+        normal: hit.normal,
+        point: [
+            origin[0] + direction[0] * hit.distance,
+            origin[1] + direction[1] * hit.distance,
+            origin[2] + direction[2] * hit.distance,
+        ],
+    };
+}
+function pushColliderHits(hits, targetKind, instanceId, catalogId, colliders, position, rotationY, origin, direction, maxDistance) {
+    for (const collider of colliders) {
+        const hit = rayHitsCollider(origin, direction, maxDistance, collider, position, rotationY);
+        if (hit === null)
+            continue;
+        hits.push({
+            targetKind,
+            instanceId,
+            ...(catalogId !== undefined ? { catalogId } : {}),
+            colliderName: collider.name,
+            purpose: collider.purpose,
+            damageEligible: collider.damageEligible,
+            blocks: collider.blocks,
+            distance: hit.distance,
+            point: hit.point,
+            normal: hit.normal,
+        });
+    }
+}
+function wallAabb(wall) {
+    const thickness = wall.thickness ?? 0.25;
+    const halfHeight = wall.halfHeight ?? 1.5;
+    const yCenter = wall.yCenter ?? halfHeight;
+    const ax = wall.a[0];
+    const az = wall.a[1];
+    const bx = wall.b[0];
+    const bz = wall.b[1];
+    const dx = bx - ax;
+    const dz = bz - az;
+    const len = Math.hypot(dx, dz) || 1;
+    const nx = (-dz / len) * thickness;
+    const nz = (dx / len) * thickness;
+    const xs = [ax + nx, ax - nx, bx + nx, bx - nx];
+    const zs = [az + nz, az - nz, bz + nz, bz - nz];
+    const minX = Math.min(...xs);
+    const maxX = Math.max(...xs);
+    const minZ = Math.min(...zs);
+    const maxZ = Math.max(...zs);
+    return {
+        min: [minX, yCenter - halfHeight, minZ],
+        max: [maxX, yCenter + halfHeight, maxZ],
+        center: [(ax + bx) / 2, yCenter, (az + bz) / 2],
+    };
+}
+function rayHitsTerrain(origin, direction, maxDistance, terrain) {
+    const steps = Math.max(8, Math.ceil(maxDistance * 2));
+    const step = maxDistance / steps;
+    let prevAbove = null;
+    let prevT = 0;
+    for (let i = 0; i <= steps; i += 1) {
+        const t = Math.min(maxDistance, i * step);
+        const x = origin[0] + direction[0] * t;
+        const y = origin[1] + direction[1] * t;
+        const z = origin[2] + direction[2] * t;
+        const ground = terrain.sampleHeight(x, z);
+        const above = y >= ground;
+        if (prevAbove === true && !above) {
+            let lo = prevT;
+            let hi = t;
+            for (let refine = 0; refine < 8; refine += 1) {
+                const mid = (lo + hi) / 2;
+                const my = origin[1] + direction[1] * mid;
+                const mg = terrain.sampleHeight(origin[0] + direction[0] * mid, origin[2] + direction[2] * mid);
+                if (my >= mg)
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            const distance = hi;
+            const px = origin[0] + direction[0] * distance;
+            const py = origin[1] + direction[1] * distance;
+            const pz = origin[2] + direction[2] * distance;
+            return {
+                targetKind: "terrain",
+                instanceId: "terrain",
+                colliderName: "ground",
+                purpose: "physical",
+                damageEligible: false,
+                blocks: true,
+                distance,
+                point: [px, py, pz],
+                normal: [0, 1, 0],
+            };
+        }
+        prevAbove = above;
+        prevT = t;
+    }
+    return null;
+}
+function candidateEntityIds(entities, origin, maxDistance) {
+    if (entities.inRadius !== undefined && entities.get !== undefined) {
+        const ids = entities.inRadius(origin, maxDistance + 2);
+        const out = [];
+        for (const id of ids) {
+            const entity = entities.get(id);
+            if (entity !== null && entity !== undefined)
+                out.push(entity);
+        }
+        return out;
+    }
+    return entities.list();
+}
+function candidateObjects(objects, origin, direction, maxDistance) {
+    if (objects.inBox !== undefined) {
+        const end = [
+            origin[0] + direction[0] * maxDistance,
+            origin[1] + direction[1] * maxDistance,
+            origin[2] + direction[2] * maxDistance,
+        ];
+        const pad = 2;
+        const min = [
+            Math.min(origin[0], end[0]) - pad,
+            Math.min(origin[1], end[1]) - pad,
+            Math.min(origin[2], end[2]) - pad,
+        ];
+        const max = [
+            Math.max(origin[0], end[0]) + pad,
+            Math.max(origin[1], end[1]) + pad,
+            Math.max(origin[2], end[2]) + pad,
+        ];
+        return objects.inBox(min, max);
+    }
+    return objects.list();
+}
+function gatherHits(deps, input) {
+    const direction = normalizeDirection(input.direction);
+    if (direction[0] === 0 && direction[1] === 0 && direction[2] === 0)
+        return [];
+    const hits = [];
+    const { origin, maxDistance } = input;
+    if (enabled(input.filter, "entities") && deps.entities !== undefined) {
+        for (const entity of candidateEntityIds(deps.entities, origin, maxDistance)) {
+            if (excluded(input.excludeInstanceIds, entity.id))
+                continue;
+            const set = deps.entities.collidersOf?.(entity.id) ?? defaultEntityColliders();
+            const colliders = resolveColliders(set);
+            pushColliderHits(hits, "entity", entity.id, entity.name, colliders.length > 0 ? colliders : resolveColliders(defaultEntityColliders()), entity.position, entity.rotationY, origin, direction, maxDistance);
+        }
+    }
+    if (enabled(input.filter, "objects") && deps.objects !== undefined) {
+        for (const object of candidateObjects(deps.objects, origin, direction, maxDistance)) {
+            if (excluded(input.excludeInstanceIds, object.instanceId))
+                continue;
+            const half = deps.objects.halfExtentsOf?.(object.catalogId) ?? undefined;
+            const set = deps.objects.collidersOf?.(object.instanceId) ??
+                defaultObjectColliders(half === null || half === undefined ? undefined : half);
+            const colliders = resolveColliders(set);
+            pushColliderHits(hits, "object", object.instanceId, object.catalogId, colliders, object.position, object.rotationY, origin, direction, maxDistance);
+        }
+    }
+    if (enabled(input.filter, "walls") && deps.walls !== undefined) {
+        for (const wall of deps.walls) {
+            if (excluded(input.excludeInstanceIds, wall.id))
+                continue;
+            const box = wallAabb(wall);
+            const hit = intersectAabb(origin, direction, box.min, box.max, maxDistance);
+            if (hit === null)
+                continue;
+            hits.push({
+                targetKind: "wall",
+                instanceId: wall.id,
+                colliderName: "wall",
+                purpose: "physical",
+                damageEligible: false,
+                blocks: true,
+                distance: hit.distance,
+                point: [
+                    origin[0] + direction[0] * hit.distance,
+                    origin[1] + direction[1] * hit.distance,
+                    origin[2] + direction[2] * hit.distance,
+                ],
+                normal: hit.normal,
+            });
+        }
+    }
+    if (enabled(input.filter, "terrain") && deps.terrain !== undefined) {
+        const terrainHit = rayHitsTerrain(origin, direction, maxDistance, deps.terrain);
+        if (terrainHit !== null)
+            hits.push(terrainHit);
+    }
+    hits.sort((a, b) => a.distance - b.distance || a.instanceId.localeCompare(b.instanceId) || a.colliderName.localeCompare(b.colliderName));
+    if (input.accept !== undefined)
+        return hits.filter(input.accept);
+    return hits;
+}
+/** First impact: nearest hit that blocks, or nearest hit if none block. */
+export function firstImpact(hits) {
+    for (const hit of hits) {
+        if (hit.blocks)
+            return hit;
+    }
+    return hits[0] ?? null;
+}
+/** Hits up to and including the first blocking collider (damage hitboxes before a wall stay). */
+export function hitsUntilBlocked(hits) {
+    const out = [];
+    for (const hit of hits) {
+        out.push(hit);
+        if (hit.blocks)
+            break;
+    }
+    return out;
+}
+export function createSceneRaycast(deps) {
+    return {
+        raycast(input) {
+            const hits = gatherHits(deps, input);
+            return firstImpact(hits);
+        },
+        raycastAll(input) {
+            return gatherHits(deps, input);
+        },
+    };
+}

package/dist/scene/spatial.d.ts

@@ -19,21 +19,24 @@ export interface MoveTowardOptions {
     dt: number;
 }
 export interface SpatialGridOptions {
-    /** Cell edge over the x/z plane; tune to ≈ the typical query radius so a query touches a handful of cells. */
     cellSize: number;
 }
 export interface SpatialApiOptions {
     resolvePosition: (instanceId: string) => EntityPosition | undefined;
-    candidates: () => string[];
+    candidates: () => readonly string[];
+    /**
+     * When omitted, `hasLineOfSight` always returns true for known entities (open-field bypass).
+     * Wire a wall/collision test here for combat LoS; `true` means the segment is blocked.
+     */
     occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
     /**
-     * Opt-in broadphase acceleration for `inRadius`/`queryArc` over large candidate sets. When set,
-     * a uniform x/z cell index is built lazily from `candidates()` + `resolvePosition()` on first use
-     * and reused across calls until `invalidate()` is called — so many queries against one tick's
-     * frozen positions pay for one rebuild, not one linear scan each. Results are exactly the linear
-     * scan's results (same filtering; see `SpatialApi.invalidate` for the staleness contract).
+     * Broadphase for `inRadius`/`queryArc`. Defaults to `{ cellSize: 8 }`. Pass `false` to force a
+     * linear scan. When enabled, the index rebuilds lazily on first use after `invalidate()` or when
+     * `getVersion()` advances — call `invalidate()` after moves unless a version source is wired.
      */
-    grid?: SpatialGridOptions;
+    grid?: SpatialGridOptions | false;
+    /** When this number changes between queries, the grid rebuilds without an explicit `invalidate()`. */
+    getVersion?: () => number;
 }
 export interface SpatialApi {
     distance(aInstanceId: string, bInstanceId: string): number | null;
@@ -41,14 +44,6 @@ export interface SpatialApi {
     hasLineOfSight(fromInstanceId: string, toInstanceId: string): boolean;
     queryArc(options: QueryArcOptions): string[];
     moveToward(instanceId: string, target: EntityPosition | string, options: MoveTowardOptions): EntityPosition | null;
-    /**
-     * Marks the `grid` broadphase index stale so the next `inRadius`/`queryArc` call rebuilds it from
-     * `candidates()` and `resolvePosition()`. Call this after moving, spawning, or despawning a
-     * candidate; a candidate absent from the index at query time is never skipped (it falls back to
-     * an exact check), but a candidate that *moved* since the last rebuild can be missed until you
-     * invalidate — so treat "invalidate after any position change" as the contract, not an
-     * optimization. A no-op when no `grid` config was supplied. Safe to call every tick.
-     */
     invalidate(): void;
 }
 export declare function distanceBetween(a: EntityPosition, b: EntityPosition): number;

package/dist/scene/spatial.js

@@ -17,58 +17,117 @@ function forwardXZ(aim) {
 function cellCoord(value, cellSize) {
     return Math.floor(value / cellSize);
 }
-function gridCellKey(cx, cz) {
-    return `${cx}:${cz}`;
+const CELL_KEY_OFFSET = 0x8000;
+function packCell(cx, cz) {
+    return ((cx + CELL_KEY_OFFSET) << 16) | ((cz + CELL_KEY_OFFSET) & 0xffff);
 }
+const DEFAULT_CELL_SIZE = 8;
 export function createSpatialApi(options) {
-    const { resolvePosition, candidates, occluder, grid } = options;
-    const cellSize = grid?.cellSize;
+    const { resolvePosition, candidates, occluder, getVersion } = options;
+    const gridConfig = options.grid === false ? undefined : (options.grid ?? { cellSize: DEFAULT_CELL_SIZE });
+    const cellSize = gridConfig?.cellSize;
     let gridIndex = null;
     let gridDirty = true;
+    let lastVersion;
     function resolveTarget(target) {
         return typeof target === "string" ? resolvePosition(target) : target;
     }
+    function takeBucket(index) {
+        if (index.poolCursor < index.bucketPool.length) {
+            const bucket = index.bucketPool[index.poolCursor];
+            index.poolCursor += 1;
+            bucket.length = 0;
+            return bucket;
+        }
+        const bucket = [];
+        index.bucketPool.push(bucket);
+        index.poolCursor += 1;
+        return bucket;
+    }
     function ensureGrid() {
         if (cellSize === undefined)
             return null;
+        const version = getVersion?.();
+        if (version !== undefined && version !== lastVersion) {
+            gridDirty = true;
+            lastVersion = version;
+        }
         if (!gridDirty && gridIndex !== null)
             return gridIndex;
-        const cells = new Map();
-        const indexed = new Set();
+        const previous = gridIndex;
+        const cells = previous?.cells ?? new Map();
+        cells.clear();
+        const indexed = previous?.indexed ?? new Set();
+        indexed.clear();
+        const index = {
+            cells,
+            indexed,
+            bucketPool: previous?.bucketPool ?? [],
+            poolCursor: 0,
+        };
         for (const instanceId of candidates()) {
             const position = resolvePosition(instanceId);
             if (position === undefined)
                 continue;
             indexed.add(instanceId);
-            const key = gridCellKey(cellCoord(position[0], cellSize), cellCoord(position[2], cellSize));
+            const key = packCell(cellCoord(position[0], cellSize), cellCoord(position[2], cellSize));
             let bucket = cells.get(key);
             if (bucket === undefined) {
-                bucket = [];
+                bucket = takeBucket(index);
                 cells.set(key, bucket);
             }
             bucket.push(instanceId);
         }
-        gridIndex = { cells, indexed };
+        gridIndex = index;
         gridDirty = false;
-        return gridIndex;
+        return index;
     }
-    function inRangeSet(index, centerX, centerZ, radius) {
+    function collectNear(index, centerX, centerZ, radius, out) {
         const size = cellSize;
         const cxMin = cellCoord(centerX - radius, size);
         const cxMax = cellCoord(centerX + radius, size);
         const czMin = cellCoord(centerZ - radius, size);
         const czMax = cellCoord(centerZ + radius, size);
-        const near = new Set();
+        out.length = 0;
+        const seen = collectNearSeen;
+        seen.clear();
         for (let cz = czMin; cz <= czMax; cz += 1) {
             for (let cx = cxMin; cx <= cxMax; cx += 1) {
-                const bucket = index.cells.get(gridCellKey(cx, cz));
+                const bucket = index.cells.get(packCell(cx, cz));
                 if (bucket === undefined)
                     continue;
-                for (const id of bucket)
-                    near.add(id);
+                for (const id of bucket) {
+                    if (seen.has(id))
+                        continue;
+                    seen.add(id);
+                    out.push(id);
+                }
             }
         }
-        return near;
+    }
+    const collectNearSeen = new Set();
+    const nearScratch = [];
+    const resultScratch = [];
+    function appendUnindexed(index, out) {
+        for (const instanceId of candidates()) {
+            if (index.indexed.has(instanceId))
+                continue;
+            out.push(instanceId);
+        }
+    }
+    function filterInRadius(ids, centerId, centerPosition, radius, filter) {
+        resultScratch.length = 0;
+        for (const instanceId of ids) {
+            if (instanceId === centerId)
+                continue;
+            if (filter !== undefined && !filter(instanceId))
+                continue;
+            const position = resolvePosition(instanceId);
+            if (position !== undefined && distanceBetween(centerPosition, position) <= radius) {
+                resultScratch.push(instanceId);
+            }
+        }
+        return resultScratch.slice();
     }
     return {
         distance(aInstanceId, bInstanceId) {
@@ -84,17 +143,12 @@ export function createSpatialApi(options) {
             if (centerPosition === undefined)
                 return [];
             const index = ensureGrid();
-            const near = index === null ? null : inRangeSet(index, centerPosition[0], centerPosition[2], radius);
-            return candidates().filter((instanceId) => {
-                if (instanceId === centerId)
-                    return false;
-                if (filter !== undefined && !filter(instanceId))
-                    return false;
-                if (near !== null && index.indexed.has(instanceId) && !near.has(instanceId))
-                    return false;
-                const position = resolvePosition(instanceId);
-                return position !== undefined && distanceBetween(centerPosition, position) <= radius;
-            });
+            if (index === null) {
+                return filterInRadius(candidates(), centerId, centerPosition, radius, filter);
+            }
+            collectNear(index, centerPosition[0], centerPosition[2], radius, nearScratch);
+            appendUnindexed(index, nearScratch);
+            return filterInRadius(nearScratch, centerId, centerPosition, radius, filter);
         },
         hasLineOfSight(fromInstanceId, toInstanceId) {
             const from = resolvePosition(fromInstanceId);
@@ -114,25 +168,32 @@ export function createSpatialApi(options) {
                 return [];
             const minDot = Math.cos((halfAngleDeg * Math.PI) / 180);
             const index = ensureGrid();
-            const near = index === null ? null : inRangeSet(index, origin[0], origin[2], radius);
-            return candidates().filter((instanceId) => {
+            const ids = index === null
+                ? candidates()
+                : (collectNear(index, origin[0], origin[2], radius, nearScratch),
+                    appendUnindexed(index, nearScratch),
+                    nearScratch);
+            resultScratch.length = 0;
+            for (const instanceId of ids) {
                 if (instanceId === from)
-                    return false;
-                if (near !== null && index.indexed.has(instanceId) && !near.has(instanceId))
-                    return false;
+                    continue;
                 const position = resolvePosition(instanceId);
                 if (position === undefined)
-                    return false;
+                    continue;
                 const dx = position[0] - origin[0];
                 const dz = position[2] - origin[2];
                 const planarDistance = Math.sqrt(dx * dx + dz * dz);
                 if (planarDistance > radius)
-                    return false;
-                if (planarDistance === 0)
-                    return true;
+                    continue;
+                if (planarDistance === 0) {
+                    resultScratch.push(instanceId);
+                    continue;
+                }
                 const dot = (forward[0] * dx + forward[1] * dz) / planarDistance;
-                return dot >= minDot;
-            });
+                if (dot >= minDot)
+                    resultScratch.push(instanceId);
+            }
+            return resultScratch.slice();
         },
         invalidate() {
             gridDirty = true;

package/dist/sensor/recordingBuffer.d.ts

@@ -9,10 +9,16 @@ export interface RecordingBufferOptions {
     /** Hard cap on frame count, oldest evicted first. Default unlimited. */
     maxFrames?: number;
 }
+export interface RecordingPair<T> {
+    before: RecordingFrame<T> | null;
+    after: RecordingFrame<T> | null;
+}
 export interface RecordingBuffer<T> {
     append(t: number, data: T): void;
     /** Nearest frame at or before `t`, or null if the buffer is empty or `t` precedes every frame. */
     seek(t: number): RecordingFrame<T> | null;
+    /** The frames bracketing `t` for interpolated playback: `before` is `seek(t)`, `after` is the next recorded frame (null past the end). */
+    seekPair(t: number): RecordingPair<T>;
     /** Frames with `fromT <= t <= toT`, in recorded order. */
     range(fromT: number, toT: number): RecordingFrame<T>[];
     clear(): void;

package/dist/sensor/recordingBuffer.js

@@ -45,6 +45,13 @@ export function createRecordingBuffer(options = {}) {
             const index = floorIndex(t);
             return index === -1 ? null : frames[index];
         },
+        seekPair(t) {
+            const index = floorIndex(t);
+            return {
+                before: index === -1 ? null : frames[index],
+                after: frames[index + 1] ?? null,
+            };
+        },
         range(fromT, toT) {
             return frames.filter((frame) => frame.t >= fromT && frame.t <= toT);
         },