@woosh/meep-engine 3.30.0 → 3.31.0

package/src/engine/interpolation/InterpolationSystem.js

@@ -2,33 +2,95 @@ import { BinaryBuffer } from "../../core/binary/BinaryBuffer.js";
 import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
 import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { SmoothingState } from "../network/sim/SmoothingState.js";
 import { InterpolationLog } from "./InterpolationLog.js";
 import { Interpolated, INTERPOLATION_KEY_UNSET, INTERPOLATION_SOURCE_LOCAL } from "./Interpolated.js";
 
 /**
- * Render-time consumer of the interpolation log. Runs in {@link update} (the
- * variable-rate, render-loop-driven cycle): for every {@link Interpolated}
- * entity it blends each interpoland between the last two completed fixed ticks
- * by the current fixed-step alpha and writes the result into the live target
- * component (e.g. {@link Transform}). Because it writes the live component, all
- * Transform-linked machinery (culling, particles, trails, attachments) renders
- * the smoothed pose.
+ * Ticks of local history the log is kept large enough for, whatever the entity count.
+ * @type {number}
+ */
+const LOCAL_HISTORY_TICKS = 8;
+
+/**
+ * Move `t` by `(dx, dy, dz)` and turn it by the unit quaternion `(ex, ey, ez, ew)` in its own
+ * frame — on the right, `q' = q * e`.
+ *
+ * That is the correction that carries over a difference in orientation observed at an earlier
+ * moment: if `q_now = W * q_then` for whatever world-frame rotation `W` happened since (physics
+ * integrates angular velocity that way), then replacing `q_then` by `q_then * e` gives
+ * `q_now * e`. Position differences carry over by addition.
+ *
+ * @param {Transform64} t
+ * @param {Float64Array} q_scratch 4 elements
+ */
+export function apply_pose_correction(t, dx, dy, dz, ex, ey, ez, ew, q_scratch) {
+    const qx = t.rotation_x, qy = t.rotation_y, qz = t.rotation_z, qw = t.rotation_w;
+
+    // q * e
+    q_scratch[0] = qw * ex + qx * ew + qy * ez - qz * ey;
+    q_scratch[1] = qw * ey - qx * ez + qy * ew + qz * ex;
+    q_scratch[2] = qw * ez + qx * ey - qy * ex + qz * ew;
+    q_scratch[3] = qw * ew - qx * ex - qy * ey - qz * ez;
+
+    const n = Math.hypot(q_scratch[0], q_scratch[1], q_scratch[2], q_scratch[3]);
+
+    t.setTranslation(t.translation_x + dx, t.translation_y + dy, t.translation_z + dz);
+    t.setRotation(q_scratch[0] / n, q_scratch[1] / n, q_scratch[2] / n, q_scratch[3] / n);
+    t.updateMatrix();
+}
+
+/**
+ * What one render write displaced, for one interpoland of one entity: the live component's value
+ * before the first blend since the last restore — the truth.
  *
- * Producers (physics, network) record authoritative per-tick snapshots into
- * {@link log}; this system only consumes. Cost is O(entities × interpolands),
- * and producers record only for things that moved, so the log stays sparse.
+ * Held losslessly: a copy of the component through its own `copy`, where it has one. Only a
+ * component without one falls back to the interpoland's serialization, which is only as exact as
+ * that serialization.
+ */
+class Displacement {
+    /** @type {Interpoland|null} */
+    interpoland = null;
+    /** @type {object|null} a copy of the component, when it can copy itself */
+    truth = null;
+    /** @type {Uint8Array} the serialized truth otherwise */
+    truth_bytes = new Uint8Array(0);
+    truth_length = 0;
+}
+
+/**
+ * Render-time interpolation, end to end. For every {@link Interpolated} entity it:
  *
- * For a LOCAL entity (the default), tick + alpha come from the simulation hub:
- * `entityManager.fixedStepTick` is the latest completed fixed step and
- * `entityManager.getFixedStepAlpha()` is the sub-step fraction, blending
- * `(fixedStepTick - 1, fixedStepTick)` from this system's own log.
+ *  - **records** the entity's state for every completed fixed step, under that step's tick, when
+ *    the entity is on the local timeline (the default). Nothing else has to: physics, a character
+ *    controller, a network prediction and plain game code in a `fixedUpdate` all get interpolated
+ *    the same way. The record is taken after the step, when the next step opens or the next render
+ *    update comes, whichever is first — so it is after every system, and an entity created during a
+ *    step is recorded on the tick it was born in.
+ *  - **blends** it every render frame, in {@link update}: local entities between the last two
+ *    completed steps at the fixed-step alpha; entities on a registered timeline (a network
+ *    playout, a remote editor's presence stream) on that timeline's window. The blend is written
+ *    into the live target component (e.g. {@link Transform64}) and announced, so everything that
+ *    follows the transform — mesh placement, attachments, particles — renders the smoothed pose.
+ *    The system declares write access to {@link Transform64}, so derived execution order puts the
+ *    blend before systems that read transforms, such as the camera.
+ *  - **restores** the truth before anything simulates from it. A blend is a render-only value and
+ *    must not become simulation state, so when a fixed step opens — and whenever {@link restore}
+ *    is called — every value a blend displaced is put back. Whatever else was written to the live
+ *    component after the blend is discarded with it, unless the writer set
+ *    {@link Interpolated#snap}: a write made between steps, at render rate, is a write to a drawn
+ *    pose, not to the simulation. Code that has to change the simulation between steps calls
+ *    {@link restore} first; after it the live components hold the truth, and what is written there
+ *    stays (the network session does this before every action it applies).
  *
- * An entity may instead carry a non-default {@link Interpolated#sourceId} naming
- * a timeline registered via {@link registerSource} (the log + window provider
- * live on the system, not the component) — e.g. a networked entity blended on
- * the network's render-delayed playout. The same render pass then drives both
- * local and remote entities, so a mixed scene is coherent; each source is
- * sampled once per frame.
+ * An interpolated entity is therefore simulated at the fixed step: moved in a `fixedUpdate`, by
+ * physics, by an action, by the network. Something that genuinely repositions it between steps —
+ * a teleport — sets {@link Interpolated#snap} (`PhysicsSystem.setPose` does): the next consume
+ * shows the live value as it is, the entity's recent records are rewritten to it so the blend
+ * resumes from there instead of sliding across the jump, and no restore puts the old value back.
+ *
+ * Cost is O(entities × interpolands) per render frame and per fixed step.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -38,8 +100,101 @@ export class InterpolationSystem extends System {
     dependencies = [Interpolated];
     components_used = [
         ResourceAccessSpecification.from(Interpolated, ResourceAccessKind.Read | ResourceAccessKind.Write),
+        // the blend writes the pose; declaring it is what orders the blend ahead of pose readers
+        ResourceAccessSpecification.from(Transform64, ResourceAccessKind.Read | ResourceAccessKind.Write),
     ];
 
+    /**
+     * Linked entities → their {@link Interpolated} component. Iterated each update.
+     * @private
+     * @type {Map<number, Interpolated>}
+     */
+    __entities = new Map();
+
+    /**
+     * Non-local timeline registry, keyed by `sourceId`. Each entry is the
+     * timeline's `{ log, sample() }` — its log to read and a per-frame window
+     * provider. Owners (e.g. the network layer) register here; the
+     * {@link Interpolated} component only carries the integer id.
+     * @private
+     * @type {Map<number, { log: InterpolationLog, sample: () => { tick_a: number, tick_b: number, t: number } }>}
+     */
+    __sources = new Map();
+
+    /**
+     * Per-update cache of `sourceId → window`, so a source's playout is
+     * sampled once per frame, not once per entity. Cleared each update.
+     * @private
+     * @type {Map<number, { tick_a: number, tick_b: number, t: number }>}
+     */
+    __source_windows = new Map();
+
+    /**
+     * What the render writes displaced, per entity, per interpoland index. An entry exists only
+     * while the entity's live components hold a blend.
+     * @type {Map<number, Array<Displacement|null>>}
+     */
+    #displaced = new Map();
+
+    /** @type {Displacement[]} */
+    #displacement_pool = [];
+
+    /** @type {Array<Array<Displacement|null>>} */
+    #slots_pool = [];
+
+    /**
+     * Spare truth copies, by component class.
+     * @type {Map<Function, object[]>}
+     */
+    #truth_pool = new Map();
+
+    /**
+     * The newest fixed-step tick recorded into {@link log}; -1 before the first.
+     * @type {number}
+     */
+    #recorded_tick = -1;
+
+    /**
+     * The fixed-step tick {@link settle} last ran for; -1 before the first.
+     * @type {number}
+     */
+    #settled_step = -1;
+
+    /**
+     * Per local-timeline entity, the first tick recorded since it was linked. Records under its key
+     * from before then belong to whoever held the key last — an entity id is reused once freed — and
+     * are not blended from.
+     * @type {Map<number, number>}
+     */
+    #valid_from = new Map();
+
+    /**
+     * Next id handed out by {@link allocateSourceId}. Starts far above the small integers callers
+     * pick for themselves, so an allocated id and a hand-picked one do not meet.
+     * @type {number}
+     */
+    #next_source_id = 0x40000000;
+
+    /**
+     * Render-only offsets hiding corrections applied through {@link correct}, per entity; they
+     * decay over wall time. The orientation offset is in the entity's own frame: drawn as
+     * `q * offset`.
+     * @type {SmoothingState}
+     */
+    #smoothing = new SmoothingState();
+
+    /**
+     * Entities {@link #smoothing} holds an offset for.
+     * @type {Set<number>}
+     */
+    #smoothed = new Set();
+
+    /** @type {Transform64} */
+    #correct_scratch = new Transform64();
+
+    /** @type {Float64Array} */
+    #quat_scratch = new Float64Array(4);
+
     /**
      * @param {{ buffer_capacity_bytes?: number, records_capacity?: number }} [options]
      */
@@ -47,20 +202,12 @@ export class InterpolationSystem extends System {
         super();
 
         /**
-         * Shared per-tick snapshot store. Producers record into it; this system
-         * blends from it.
+         * The local timeline's per-tick snapshot store: recorded by this system for every completed
+         * fixed step, blended from every render frame.
          * @type {InterpolationLog}
          */
         this.log = new InterpolationLog({ buffer_capacity_bytes, records_capacity });
 
-        /**
-         * Linked entities → their {@link Interpolated} component. Iterated each
-         * update.
-         * @private
-         * @type {Map<number, Interpolated>}
-         */
-        this.__entities = new Map();
-
         /**
          * Reusable decode buffer for blended snapshots.
          * @private
@@ -70,22 +217,12 @@ export class InterpolationSystem extends System {
         this.__scratch.fromArrayBuffer(new ArrayBuffer(256));
 
         /**
-         * Non-local timeline registry, keyed by `sourceId`. Each entry is the
-         * timeline's `{ log, sample() }` — its log to read and a per-frame window
-         * provider. Owners (e.g. the network layer) register here; the
-         * {@link Interpolated} component only carries the integer id.
+         * Reusable buffer for serializing a component that cannot copy itself.
          * @private
-         * @type {Map<number, { log: InterpolationLog, sample: () => { tick_a: number, tick_b: number, t: number } }>}
-         */
-        this.__sources = new Map();
-
-        /**
-         * Per-update cache of `sourceId → window`, so a source's playout is
-         * sampled once per frame, not once per entity. Cleared each update.
-         * @private
-         * @type {Map<number, { tick_a: number, tick_b: number, t: number }>}
+         * @type {BinaryBuffer}
          */
-        this.__source_windows = new Map();
+        this.__probe = new BinaryBuffer();
+        this.__probe.setCapacity(256);
     }
 
     /**
@@ -101,9 +238,30 @@ export class InterpolationSystem extends System {
      * @param {() => { tick_a: number, tick_b: number, t: number }} sample
      */
     registerSource(sourceId, log, sample) {
+        if (sourceId === INTERPOLATION_SOURCE_LOCAL) {
+            throw new Error(`InterpolationSystem.registerSource: source id ${INTERPOLATION_SOURCE_LOCAL} is the local timeline and cannot be registered`);
+        }
+
+        const existing = this.__sources.get(sourceId);
+
+        if (existing !== undefined && existing.log !== log) {
+            throw new Error(`InterpolationSystem.registerSource: source id ${sourceId} is already registered to another timeline; unregister it first, or take a fresh id from allocateSourceId()`);
+        }
+
         this.__sources.set(sourceId, { log, sample });
     }
 
+    /**
+     * A source id no one else holds, for an owner that does not need a meaningful one of its own.
+     * @returns {number}
+     */
+    allocateSourceId() {
+        while (this.__sources.has(this.#next_source_id)) {
+            this.#next_source_id++;
+        }
+        return this.#next_source_id++;
+    }
+
     /**
      * Forget a source (its peer left). Entities still marked with it are left where they are
      * until their marker goes; the system does not blend from a source it does not have.
@@ -121,6 +279,13 @@ export class InterpolationSystem extends System {
         this.entityManager = entityManager;
     }
 
+    /**
+     * @param {EntityManager} entityManager
+     */
+    async shutdown(entityManager) {
+        this.restore();
+    }
+
     /**
      * @param {Interpolated} interpolated
      * @param {number} entity
@@ -131,6 +296,11 @@ export class InterpolationSystem extends System {
             // layer) may have set a network_id already, in which case we keep it.
             interpolated.key = entity;
         }
+
+        // Whatever the log already holds under this key was recorded for whoever held it before —
+        // entity ids are reused once freed. The first record that is this entity's is the next one.
+        this.#valid_from.set(entity, this.#recorded_tick + 1);
+
         this.__entities.set(entity, interpolated);
     }
 
@@ -139,7 +309,432 @@ export class InterpolationSystem extends System {
      * @param {number} entity
      */
     unlink(interpolated, entity) {
+        // leave the entity holding its truth, not a render blend it will never be restored from
+        this.#restore_entity(entity, interpolated);
         this.__entities.delete(entity);
+        this.#valid_from.delete(entity);
+        if (this.#smoothed.delete(entity)) {
+            this.#smoothing.untrack(entity);
+        }
+    }
+
+    /**
+     * Put back the truth wherever a render blend is in the live components (keeping, instead, the
+     * live value of an entity that declared it with {@link Interpolated#snap}). Idempotent, and cheap
+     * when nothing is blended. Safe to call at any time.
+     */
+    restore() {
+        const displaced = this.#displaced;
+
+        if (displaced.size === 0) {
+            return;
+        }
+
+        for (const [entity, slots] of displaced) {
+            this.#restore_slots(entity, slots, this.__entities.get(entity));
+        }
+
+        displaced.clear();
+    }
+
+    /**
+     * Ready the interpolated entities for the fixed step that is opening: blends restored, the step
+     * just completed recorded, teleports raised since then settled into its record. Idempotent per
+     * step — the first call does the work, later ones in the same step return.
+     *
+     * The engine runs it when the step opens ({@link openFixedStep}). A system that applies state as
+     * a step opens and must find the simulation's truth there — the network, before it applies what
+     * arrived — calls it first, so which of the two opens first does not matter. Only valid while a
+     * fixed step is opening: `entityManager.fixedStepTick` names the step about to run.
+     */
+    settle() {
+        const step = this.entityManager.fixedStepTick;
+
+        if (step === this.#settled_step) {
+            return;
+        }
+
+        this.#settled_step = step;
+
+        this.restore();
+
+        const completed = step - 1;
+
+        if (completed > this.#recorded_tick) {
+            // the live components hold its truth — snapped entities' included
+            this.#record(completed);
+        } else if (completed >= 0) {
+            // already recorded (by a render update since); a teleport raised after that is not in it
+            for (const [entity, interpolated] of this.__entities) {
+                if (interpolated.snap && interpolated.sourceId === INTERPOLATION_SOURCE_LOCAL) {
+                    this.#rewrite_with_live(entity, interpolated, completed);
+                }
+            }
+        }
+
+        // the step is about to integrate from the live pose, and the record now says the same
+        for (const interpolated of this.__entities.values()) {
+            interpolated.snap = false;
+        }
+    }
+
+    openFixedStep() {
+        this.settle();
+    }
+
+    /**
+     * @param {number} entity
+     * @param {Interpolated} [interpolated]
+     */
+    #restore_entity(entity, interpolated) {
+        const slots = this.#displaced.get(entity);
+
+        if (slots === undefined) {
+            return;
+        }
+
+        this.#restore_slots(entity, slots, interpolated);
+        this.#displaced.delete(entity);
+    }
+
+    /**
+     * Put back what the blend displaced — unless the entity declared its live value the truth
+     * ({@link Interpolated#snap}) — and release the slots.
+     *
+     * @param {number} entity
+     * @param {Array<Displacement|null>} slots
+     * @param {Interpolated|undefined} interpolated
+     */
+    #restore_slots(entity, slots, interpolated) {
+        const em = this.entityManager;
+        const dataset = (em !== null && em !== undefined) ? em.dataset : null;
+        const keep_live = interpolated !== undefined && interpolated.snap;
+
+        // newest displacement first, so two interpolands over one component unwind to the oldest truth
+        for (let i = slots.length - 1; i >= 0; i--) {
+            const slot = slots[i];
+
+            if (slot === null) {
+                continue;
+            }
+
+            if (!keep_live && dataset !== null && dataset !== undefined) {
+                const interpoland = slot.interpoland;
+                const target = dataset.getComponent(entity, interpoland.component_class);
+
+                if (target !== undefined && target !== null) {
+                    this.#write_truth(slot, target);
+                    interpoland.announce(dataset, entity);
+                }
+            }
+
+            this.#release(slot);
+        }
+
+        slots.length = 0;
+        this.#slots_pool.push(slots);
+    }
+
+    /**
+     * @param {Displacement} slot
+     * @param {object} target
+     */
+    #write_truth(slot, target) {
+        if (slot.truth !== null) {
+            target.copy(slot.truth);
+            return;
+        }
+
+        const probe = this.__probe;
+        probe.position = 0;
+        probe.writeBytes(slot.truth_bytes, 0, slot.truth_length);
+        probe.position = 0;
+        slot.interpoland.serialization_adapter.deserialize(probe, target);
+    }
+
+    /**
+     * @param {Displacement} slot
+     */
+    #release(slot) {
+        if (slot.truth !== null) {
+            const klass = slot.interpoland.component_class;
+            let pool = this.#truth_pool.get(klass);
+            if (pool === undefined) {
+                pool = [];
+                this.#truth_pool.set(klass, pool);
+            }
+            pool.push(slot.truth);
+            slot.truth = null;
+        }
+        slot.interpoland = null;
+        slot.truth_length = 0;
+        this.#displacement_pool.push(slot);
+    }
+
+    /**
+     * Remember the truth a blend is about to be written over — once per restore: after the first
+     * blend the live value is a blend, and the truth is the one already held.
+     *
+     * @param {number} entity
+     * @param {number} index interpoland index
+     * @param {Interpoland} interpoland
+     * @param {object} target
+     */
+    #displace(entity, index, interpoland, target) {
+        let slots = this.#displaced.get(entity);
+
+        if (slots === undefined) {
+            slots = this.#slots_pool.length > 0 ? this.#slots_pool.pop() : [];
+            this.#displaced.set(entity, slots);
+        }
+
+        while (slots.length <= index) {
+            slots.push(null);
+        }
+
+        if (slots[index] !== null) {
+            return;
+        }
+
+        const slot = this.#displacement_pool.length > 0 ? this.#displacement_pool.pop() : new Displacement();
+        slot.interpoland = interpoland;
+
+        if (typeof target.copy === 'function') {
+            const klass = interpoland.component_class;
+            const pool = this.#truth_pool.get(klass);
+            const truth = (pool !== undefined && pool.length > 0) ? pool.pop() : new klass();
+            truth.copy(target);
+            slot.truth = truth;
+        } else {
+            const probe = this.__probe;
+            probe.position = 0;
+            interpoland.serialization_adapter.serialize(probe, target);
+            const length = probe.position;
+            if (slot.truth_bytes.length < length) {
+                slot.truth_bytes = new Uint8Array(Math.max(length, 64));
+            }
+            slot.truth_bytes.set(probe.raw_bytes.subarray(0, length), 0);
+            slot.truth_length = length;
+        }
+
+        slots[index] = slot;
+    }
+
+    /**
+     * Record every local-timeline entity's state under `tick`, the newest completed fixed step. Only
+     * called where the live components hold the truth: in {@link settle} right after the restore,
+     * or in {@link update} before anything is blended.
+     * @param {number} tick
+     */
+    #record(tick) {
+        const em = this.entityManager;
+        const dataset = (em !== null && em !== undefined) ? em.dataset : null;
+
+        if (dataset === null || dataset === undefined || tick <= this.#recorded_tick) {
+            return;
+        }
+
+        const log = this.log;
+
+        let open = false;
+
+        for (const [entity, interpolated] of this.__entities) {
+            if (interpolated.sourceId !== INTERPOLATION_SOURCE_LOCAL) {
+                continue;
+            }
+
+            const key = interpolated.key;
+
+            if (key === INTERPOLATION_KEY_UNSET) {
+                continue;
+            }
+
+            const interpolands = interpolated.interpolands;
+            const n = interpolands.length;
+
+            for (let i = 0; i < n; i++) {
+                const interpoland = interpolands[i];
+                const target = dataset.getComponent(entity, interpoland.component_class);
+
+                if (target === undefined || target === null) {
+                    continue;
+                }
+
+                if (!open) {
+                    log.begin_tick(tick);
+                    open = true;
+                }
+
+                const buffer = log.begin_record(key, interpoland.type_id);
+                interpoland.serialization_adapter.serialize(buffer, target);
+                log.end_record();
+            }
+        }
+
+        if (open) {
+            log.end_tick();
+
+            // A blend reads the last two ticks; keep a few more so a correction can rewrite recent
+            // history. Grows with the number of interpolated entities instead of squashing ticks.
+            log.ensure_ticks(LOCAL_HISTORY_TICKS);
+        }
+
+        this.#recorded_tick = tick;
+    }
+
+    /**
+     * Overwrite `entity`'s records at `tick` with its live state, for every interpoland it has a
+     * record for.
+     * @param {number} entity
+     * @param {Interpolated} interpolated
+     * @param {number} tick
+     */
+    #rewrite_with_live(entity, interpolated, tick) {
+        if (tick < 0) {
+            return;
+        }
+
+        const dataset = this.entityManager.dataset;
+        const interpolands = interpolated.interpolands;
+
+        for (let i = 0; i < interpolands.length; i++) {
+            const interpoland = interpolands[i];
+            const target = dataset.getComponent(entity, interpoland.component_class);
+
+            if (target === undefined || target === null) {
+                continue;
+            }
+
+            this.log.rewrite(tick, interpolated.key, interpoland.type_id, (buffer) => {
+                interpoland.serialization_adapter.serialize(buffer, target);
+            });
+        }
+    }
+
+    /**
+     * Hide a correction of a local-timeline entity's pose: the simulation has just moved it by
+     * `(dx, dy, dz)` and turned it by the unit quaternion `(ex, ey, ez, ew)` in its own frame
+     * (`q' = q * e`), and the picture should not jump.
+     *
+     * The entity's most recent records are moved by the same correction, so the blend reads a
+     * history consistent with the corrected simulation; and the drawn pose carries the opposite
+     * offset, which then decays over a fraction of a second. The drawn pose is continuous at the
+     * moment of the correction and converges on the corrected one.
+     *
+     * Call with the correction already applied to the live pose. Only {@link Transform64}
+     * interpolands on the local timeline are corrected; anything else is left as is.
+     *
+     * @param {number} entity
+     * @param {number} dx
+     * @param {number} dy
+     * @param {number} dz
+     * @param {number} [ex]
+     * @param {number} [ey]
+     * @param {number} [ez]
+     * @param {number} [ew]
+     * @returns {boolean} whether there was anything to correct
+     */
+    correct(entity, dx, dy, dz, ex = 0, ey = 0, ez = 0, ew = 1) {
+        const interpolated = this.__entities.get(entity);
+
+        if (interpolated === undefined || interpolated.sourceId !== INTERPOLATION_SOURCE_LOCAL) {
+            return false;
+        }
+
+        const interpolands = interpolated.interpolands;
+        let corrected = false;
+
+        for (let i = 0; i < interpolands.length; i++) {
+            const interpoland = interpolands[i];
+            if (interpoland.component_class !== Transform64) continue;
+
+            // the two newest records are the ones a blend reads from here on
+            const valid_from = this.#valid_from.get(entity) ?? 0;
+            for (let tick = this.#recorded_tick - 1; tick <= this.#recorded_tick; tick++) {
+                if (tick < 0 || tick < valid_from) continue;
+                this.#shift_record(interpolated.key, interpoland, tick, dx, dy, dz, ex, ey, ez, ew);
+            }
+            corrected = true;
+        }
+
+        if (!corrected) {
+            return false;
+        }
+
+        this.#smoothing.absorb_position_correction(entity, dx, dy, dz);
+        this.#smoothing.absorb_body_orientation_correction(entity, ex, ey, ez, ew);
+        this.#smoothed.add(entity);
+
+        return true;
+    }
+
+    /**
+     * @param {number} key
+     * @param {Interpoland} interpoland
+     * @param {number} tick
+     */
+    #shift_record(key, interpoland, tick, dx, dy, dz, ex, ey, ez, ew) {
+        const log = this.log;
+        const scratch = this.__scratch;
+
+        scratch.position = 0;
+        if (!log.interpolate(scratch, key, interpoland.type_id, tick, tick, 0, interpoland.interpolation_adapter)) {
+            return;
+        }
+
+        const t = this.#correct_scratch;
+        scratch.position = 0;
+        interpoland.serialization_adapter.deserialize(scratch, t);
+
+        apply_pose_correction(t, dx, dy, dz, ex, ey, ez, ew, this.#quat_scratch);
+
+        log.rewrite(tick, key, interpoland.type_id, (buffer) => {
+            interpoland.serialization_adapter.serialize(buffer, t);
+        });
+    }
+
+    /**
+     * Draw `target` (a freshly blended pose) with its entity's correction offset.
+     * @param {number} entity
+     * @param {Transform64} target
+     */
+    #apply_render_offset(entity, target) {
+        const smoothing = this.#smoothing;
+        const state = smoothing.state_for(entity);
+        if (state === undefined) return;
+
+        const p = state.position_error;
+        const q = this.#quat_scratch;
+        q[0] = target.rotation_x;
+        q[1] = target.rotation_y;
+        q[2] = target.rotation_z;
+        q[3] = target.rotation_w;
+        smoothing.render_body_orientation(entity, q, q);
+        const n = Math.hypot(q[0], q[1], q[2], q[3]);
+
+        target.setTranslation(target.translation_x + p[0], target.translation_y + p[1], target.translation_z + p[2]);
+        target.setRotation(q[0] / n, q[1] / n, q[2] / n, q[3] / n);
+        target.updateMatrix();
+    }
+
+    /**
+     * Fade every correction offset by the frame's wall time; forget the settled ones.
+     * @param {number} dt seconds
+     */
+    #decay_offsets(dt) {
+        const smoothed = this.#smoothed;
+        if (smoothed.size === 0) return;
+
+        const smoothing = this.#smoothing;
+        const step = dt > 0 ? dt : 0;
+
+        for (const entity of smoothed) {
+            smoothing.decay(entity, step);
+            if (smoothing.is_settled(entity)) {
+                smoothing.untrack(entity);
+                smoothed.delete(entity);
+            }
+        }
     }
 
     update(dt) {
@@ -154,6 +749,9 @@ export class InterpolationSystem extends System {
             return;
         }
 
+        // Nothing has been blended since the last step, so the live components hold its truth.
+        this.#record(em.fixedStepTick);
+
         const scratch = this.__scratch;
 
         // Default (local) timeline: blend the last two completed fixed steps at
@@ -167,31 +765,50 @@ export class InterpolationSystem extends System {
         const source_windows = this.__source_windows;
         source_windows.clear();
 
+        this.#decay_offsets(dt);
+
         for (const [entity, interpolated] of entities) {
             const key = interpolated.key;
             if (key === INTERPOLATION_KEY_UNSET) {
                 continue;
             }
 
+            const source_id = interpolated.sourceId;
+
             if (interpolated.snap) {
-                // Teleport / wake: the live components already hold the
-                // authoritative pose (set by setPose, or the body's own pose on
-                // wake), which isn't in the log as the latest two ticks yet.
-                // Leave them untouched this frame so we don't slide across the
-                // jump; resume interpolating next frame.
+                // The live components hold a pose the entity was deliberately moved to. Show it as
+                // it is, never restore a blend over it, and — on the local timeline — make the two
+                // records the next blends read say the same, so blending resumes from here instead
+                // of sliding across the jump.
+                this.#restore_entity(entity, interpolated);
                 interpolated.snap = false;
+
+                if (source_id === INTERPOLATION_SOURCE_LOCAL) {
+                    this.#rewrite_with_live(entity, interpolated, local_tick_b);
+                    this.#rewrite_with_live(entity, interpolated, local_tick_a);
+                }
                 continue;
             }
 
             // Pick the timeline by id: the default local fixed-step clock, or a
             // registered non-local source (e.g. the network playout).
             let log, tick_a, tick_b, t;
-            const source_id = interpolated.sourceId;
             if (source_id === INTERPOLATION_SOURCE_LOCAL) {
                 log = local_log;
                 tick_a = local_tick_a;
                 tick_b = local_tick_b;
                 t = local_t;
+
+                // nothing recorded before this entity was linked is its own
+                const valid_from = this.#valid_from.get(entity);
+                if (valid_from !== undefined) {
+                    if (tick_b < valid_from) {
+                        continue;
+                    }
+                    if (tick_a < valid_from) {
+                        tick_a = tick_b;
+                    }
+                }
             } else {
                 const src = this.__sources.get(source_id);
                 if (src === undefined) {
@@ -210,6 +827,7 @@ export class InterpolationSystem extends System {
 
             const interpolands = interpolated.interpolands;
             const n = interpolands.length;
+
             for (let i = 0; i < n; i++) {
                 const interpoland = interpolands[i];
 
@@ -228,9 +846,15 @@ export class InterpolationSystem extends System {
                     continue;
                 }
 
+                this.#displace(entity, i, interpoland, target);
+
                 scratch.position = 0;
                 interpoland.serialization_adapter.deserialize(scratch, target);
 
+                if (interpoland.component_class === Transform64 && this.#smoothed.has(entity)) {
+                    this.#apply_render_offset(entity, target);
+                }
+
                 // the write is invisible to everything downstream until it is announced
                 interpoland.announce(dataset, entity);
             }