@jgengine/core 0.8.0 → 0.10.0

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);
         },

package/dist/sensor/replayLoop.d.ts

@@ -0,0 +1,39 @@
+import type { RecordingBuffer } from "./recordingBuffer.js";
+export interface ReplayLoopOptions<T> {
+    /** Blend between the two frames straddling the seek time; omit to hold the earlier frame. */
+    interpolate?: (before: T, after: T, alpha: number) => T;
+    /** Returns `null` for this long at the start of every loop pass — a spawn-grace gap so a looping ghost blinks out instead of teleporting. Default `0`. */
+    spawnGraceSeconds?: number;
+}
+/**
+ * Replays a finished `RecordingBuffer` on a loop — modulo-time seek, frame interpolation, and
+ * spawn grace, the pieces every ghost-lap/echo feature hand-rolled (#286.4). `sample(t)` is a pure
+ * function of absolute time; `null` means "the ghost isn't on track right now".
+ */
+export interface ReplayLoop<T> {
+    duration(): number;
+    sample(t: number): T | null;
+}
+export declare function createReplayLoop<T>(buffer: RecordingBuffer<T>, options?: ReplayLoopOptions<T>): ReplayLoop<T>;
+export interface ReplayEntityDeps {
+    has(id: string): boolean;
+    spawn(id: string): void;
+    setPose(id: string, pose: {
+        position: readonly [number, number, number];
+        rotationY?: number;
+        dt?: number;
+    }): unknown;
+    despawn(id: string): unknown;
+}
+export interface RecordedPoseLike {
+    position: readonly [number, number, number];
+    rotationY?: number;
+}
+/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw. */
+export declare function interpolateRecordedPose<T extends RecordedPoseLike>(before: T, after: T, alpha: number): T;
+/**
+ * Reconcile a replayed pose against an entity store: spawns the ghost on the first non-null sample,
+ * poses it while samples flow, despawns it through grace gaps or after the recording empties.
+ * `deps` matches `ctx.scene.entity` structurally — pass `{ has: (id) => ctx.scene.entity.get(id) !== null, spawn, setPose, despawn }`.
+ */
+export declare function syncReplayEntity(deps: ReplayEntityDeps, id: string, pose: RecordedPoseLike | null, dt?: number): void;

package/dist/sensor/replayLoop.js

@@ -0,0 +1,64 @@
+export function createReplayLoop(buffer, options = {}) {
+    const grace = Math.max(0, options.spawnGraceSeconds ?? 0);
+    const interpolate = options.interpolate;
+    return {
+        duration: () => buffer.duration(),
+        sample(t) {
+            const frames = buffer.frames();
+            if (frames.length === 0)
+                return null;
+            const first = frames[0];
+            const duration = buffer.duration();
+            if (duration <= 0)
+                return first.data;
+            const local = ((t % duration) + duration) % duration;
+            if (local < grace)
+                return null;
+            const seekT = first.t + local;
+            const pair = buffer.seekPair(seekT);
+            if (pair.before === null)
+                return pair.after?.data ?? null;
+            if (pair.after === null || interpolate === undefined)
+                return pair.before.data;
+            const span = pair.after.t - pair.before.t;
+            const alpha = span <= 1e-9 ? 0 : (seekT - pair.before.t) / span;
+            return interpolate(pair.before.data, pair.after.data, alpha);
+        },
+    };
+}
+/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw. */
+export function interpolateRecordedPose(before, after, alpha) {
+    let yawDelta = (after.rotationY ?? 0) - (before.rotationY ?? 0);
+    while (yawDelta > Math.PI)
+        yawDelta -= Math.PI * 2;
+    while (yawDelta < -Math.PI)
+        yawDelta += Math.PI * 2;
+    return {
+        ...before,
+        position: [
+            before.position[0] + (after.position[0] - before.position[0]) * alpha,
+            before.position[1] + (after.position[1] - before.position[1]) * alpha,
+            before.position[2] + (after.position[2] - before.position[2]) * alpha,
+        ],
+        ...(before.rotationY === undefined ? {} : { rotationY: (before.rotationY ?? 0) + yawDelta * alpha }),
+    };
+}
+/**
+ * Reconcile a replayed pose against an entity store: spawns the ghost on the first non-null sample,
+ * poses it while samples flow, despawns it through grace gaps or after the recording empties.
+ * `deps` matches `ctx.scene.entity` structurally — pass `{ has: (id) => ctx.scene.entity.get(id) !== null, spawn, setPose, despawn }`.
+ */
+export function syncReplayEntity(deps, id, pose, dt) {
+    if (pose === null) {
+        if (deps.has(id))
+            deps.despawn(id);
+        return;
+    }
+    if (!deps.has(id))
+        deps.spawn(id);
+    deps.setPose(id, {
+        position: pose.position,
+        ...(pose.rotationY === undefined ? {} : { rotationY: pose.rotationY }),
+        ...(dt === undefined ? {} : { dt }),
+    });
+}