@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/network/adapters/PoseCorrection.js

@@ -0,0 +1,211 @@
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { Interpolated } from "../../interpolation/Interpolated.js";
+import { apply_pose_correction } from "../../interpolation/InterpolationSystem.js";
+import { Correction } from "../correction/Correction.js";
+import { rigid_body_of } from "./rigid_body_of.js";
+
+/**
+ * A predicted position within this distance of the host's, in world units, is the same position:
+ * well above the wire's Float32 rounding near the origin, far below anything visible.
+ * @type {number}
+ */
+const POSITION_TOLERANCE = 1e-3;
+
+/**
+ * Float32 keeps 24 significant bits, so a position rounded for the wire is off by up to 2^-24 of
+ * its magnitude; a few of those steps on either side is still the same position.
+ * @type {number}
+ */
+const FLOAT32_RELATIVE_TOLERANCE = 2 ** -20;
+
+/**
+ * Likewise for orientation, as the cosine of half the angle between the two (≈ 0.43°). The wire
+ * rounds a rotation to 10 bits per component, up to ≈ 0.0024 rad each time, and a comparison can
+ * meet three of those roundings: the host's state now, the prediction's own encoding, and — once a
+ * correction has been made — the host's state at the corrected frame, which the correction carried
+ * into every prediction since. Tighter than that, a body that turns after a correction reads its own
+ * rounding as a misprediction and is corrected again for nothing.
+ * @type {number}
+ */
+const ROTATION_TOLERANCE_COS_HALF = Math.cos(0.0075 * 0.5);
+
+/**
+ * Whether two scale factors are the same up to rounding.
+ * @param {number} a
+ * @param {number} b
+ * @returns {boolean}
+ */
+function same_scale(a, b) {
+    return Math.abs(a - b) <= Math.max(Math.abs(a), Math.abs(b)) * FLOAT32_RELATIVE_TOLERANCE;
+}
+
+/**
+ * The factor that takes scale `predicted` to `server`; 1 when they agree, and when there is no
+ * factor to take (a zero predicted scale — degenerate, and left alone).
+ * @param {number} server
+ * @param {number} predicted
+ * @returns {number}
+ */
+function scale_ratio(server, predicted) {
+    if (same_scale(server, predicted) || predicted === 0) {
+        return 1;
+    }
+    return server / predicted;
+}
+
+/**
+ * Corrects a {@link Transform64} the way the simulation would have carried the difference:
+ *
+ *  - position by the offset;
+ *  - orientation by the turn `e` that takes the predicted orientation to the host's in the body's
+ *    own frame (`predicted · e = host`), applied on the same side to every later state — whatever
+ *    world-frame rotation the body made since, it makes from the corrected orientation too
+ *    (`q_now · e`);
+ *  - scale by the ratio.
+ *
+ * Two poses are the same when they are within what the wire cannot tell apart (see the tolerances
+ * above).
+ *
+ * The live pose of a rigid body is moved through its physics system, so a sleeping body wakes and
+ * its broadphase leaves follow; and the step is hidden in what is drawn — the interpolation system
+ * shifts the entity's recent records by the correction and draws the opposite offset, fading.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PoseCorrection extends Correction {
+    /** @type {Float64Array} dx, dy, dz, ex, ey, ez, ew, kx, ky, kz */
+    #difference = new Float64Array(10);
+
+    /** @type {Float64Array} */
+    #quat_scratch = new Float64Array(4);
+
+    /** @type {Transform64} */
+    #pose = new Transform64();
+
+    /**
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     * @returns {boolean}
+     */
+    same(server, predicted) {
+        const dp = Math.hypot(
+            server.translation_x - predicted.translation_x,
+            server.translation_y - predicted.translation_y,
+            server.translation_z - predicted.translation_z,
+        );
+        // the wire rounds positions to Float32, whose step grows with distance from the origin
+        const magnitude = Math.max(Math.abs(server.translation_x), Math.abs(server.translation_y), Math.abs(server.translation_z));
+        if (dp > POSITION_TOLERANCE + magnitude * FLOAT32_RELATIVE_TOLERANCE) {
+            return false;
+        }
+
+        const dot = Math.abs(
+            server.rotation_x * predicted.rotation_x + server.rotation_y * predicted.rotation_y
+            + server.rotation_z * predicted.rotation_z + server.rotation_w * predicted.rotation_w
+        );
+        if (dot < ROTATION_TOLERANCE_COS_HALF) {
+            return false;
+        }
+
+        return same_scale(server.scale_x, predicted.scale_x)
+            && same_scale(server.scale_y, predicted.scale_y)
+            && same_scale(server.scale_z, predicted.scale_z);
+    }
+
+    /**
+     * @param {Transform64} state
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     */
+    carry(state, server, predicted) {
+        const d = this.#compute(server, predicted);
+        apply_pose_correction(state, d[0], d[1], d[2], d[3], d[4], d[5], d[6], this.#quat_scratch);
+        if (d[7] !== 1 || d[8] !== 1 || d[9] !== 1) {
+            state.setScale(state.scale_x * d[7], state.scale_y * d[8], state.scale_z * d[9]);
+            state.updateMatrix();
+        }
+    }
+
+    /**
+     * @param {CorrectionTarget} target
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     * @returns {number} how far the position moved, in world units
+     */
+    apply(target, server, predicted) {
+        const d = this.#compute(server, predicted);
+        const live = target.component;
+        const q = this.#quat_scratch;
+
+        const body = rigid_body_of(target.entity_manager, target.entity);
+
+        if (body !== null) {
+            // through physics, so a sleeping body wakes and its broadphase leaves follow
+            const pose = this.#pose;
+            pose.setTranslation(live.translation_x, live.translation_y, live.translation_z);
+            pose.setRotation(live.rotation_x, live.rotation_y, live.rotation_z, live.rotation_w);
+            apply_pose_correction(pose, d[0], d[1], d[2], d[3], d[4], d[5], d[6], q);
+            body.physics.setPose(body.body,
+                [pose.translation_x, pose.translation_y, pose.translation_z],
+                [pose.rotation_x, pose.rotation_y, pose.rotation_z, pose.rotation_w],
+            );
+            // setPose asks the renderer to snap; this correction is hidden instead
+            const interpolated = target.entity_manager.dataset.getComponent(target.entity, Interpolated);
+            if (interpolated !== undefined) interpolated.snap = false;
+        } else {
+            apply_pose_correction(live, d[0], d[1], d[2], d[3], d[4], d[5], d[6], q);
+        }
+
+        if (d[7] !== 1 || d[8] !== 1 || d[9] !== 1) {
+            live.setScale(live.scale_x * d[7], live.scale_y * d[8], live.scale_z * d[9]);
+            live.updateMatrix();
+        }
+
+        if (target.interpolation !== null) {
+            target.interpolation.correct(target.entity, d[0], d[1], d[2], d[3], d[4], d[5], d[6]);
+        }
+
+        return Math.hypot(d[0], d[1], d[2]);
+    }
+
+    /**
+     * The difference between `server` and `predicted`: offset, turn in the body's frame, scale ratio.
+     * @param {Transform64} server
+     * @param {Transform64} predicted
+     * @returns {Float64Array} dx, dy, dz, ex, ey, ez, ew, kx, ky, kz — this strategy's own; read it
+     */
+    #compute(server, predicted) {
+        const d = this.#difference;
+
+        d[0] = server.translation_x - predicted.translation_x;
+        d[1] = server.translation_y - predicted.translation_y;
+        d[2] = server.translation_z - predicted.translation_z;
+
+        // e = inverse(predicted) * server
+        const px = -predicted.rotation_x, py = -predicted.rotation_y, pz = -predicted.rotation_z, pw = predicted.rotation_w;
+        const sx = server.rotation_x, sy = server.rotation_y, sz = server.rotation_z, sw = server.rotation_w;
+        const ex = pw * sx + px * sw + py * sz - pz * sy;
+        const ey = pw * sy - px * sz + py * sw + pz * sx;
+        const ez = pw * sz + px * sy - py * sx + pz * sw;
+        const ew = pw * sw - px * sx - py * sy - pz * sz;
+        // unit, and the short way round
+        const n = Math.hypot(ex, ey, ez, ew) * (ew < 0 ? -1 : 1);
+        d[3] = ex / n;
+        d[4] = ey / n;
+        d[5] = ez / n;
+        d[6] = ew / n;
+
+        d[7] = scale_ratio(server.scale_x, predicted.scale_x);
+        d[8] = scale_ratio(server.scale_y, predicted.scale_y);
+        d[9] = scale_ratio(server.scale_z, predicted.scale_z);
+
+        return d;
+    }
+}
+
+/**
+ * The shared {@link PoseCorrection}, for {@link Transform64}.
+ * @type {PoseCorrection}
+ */
+export const POSE_CORRECTION = new PoseCorrection();

package/src/engine/network/adapters/TransformReplicationAdapter.d.ts

@@ -31,6 +31,7 @@ export class TransformReplicationAdapter extends BinaryClassSerializationAdapter
      */
     deserialize(buffer: BinaryBuffer, value: Transform64): void;
 }
+export type EntityComponentDataset = import("../../ecs/EntityComponentDataset.js").EntityComponentDataset;
 import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
 import { Transform64 } from "../../ecs/transform/Transform64.js";
 //# sourceMappingURL=TransformReplicationAdapter.d.ts.map

package/src/engine/network/adapters/TransformReplicationAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransformReplicationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/TransformReplicationAdapter.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;IAEI,0BAAoB;IAGpB;;;OAGG;IACH,uCAFW,WAAW,QAgBrB;IAED;;;OAGG;IACH,yCAFW,WAAW,QAsBrB;CACJ;gDAjF+C,6DAA6D;4BACjF,oCAAoC"}
+{"version":3,"file":"TransformReplicationAdapter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/TransformReplicationAdapter.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;IAEI,0BAAoB;IAGpB;;;OAGG;IACH,uCAFW,WAAW,QAgBrB;IAED;;;OAGG;IACH,yCAFW,WAAW,QAsBrB;CAaJ;qCA7FY,OAAO,qCAAqC,EAAE,sBAAsB;gDALjC,6DAA6D;4BACjF,oCAAoC"}

package/src/engine/network/adapters/TransformReplicationAdapter.js

@@ -4,6 +4,11 @@ import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization
 import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
 import { BinaryClassSerializationAdapter } from "../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
 import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { t64_announce_change } from "../../ecs/transform/t64_announce_change.js";
+
+/**
+ * @typedef {import("../../ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ */
 
 /**
  * Decode scratch for {@link TransformReplicationAdapter#deserialize}. Decoders
@@ -83,4 +88,16 @@ export class TransformReplicationAdapter extends BinaryClassSerializationAdapter
         // rotation and scale both moved, so the matrix owes an update before anyone reads it
         value.updateMatrix();
     }
+
+    /**
+     * A {@link Transform64} carries no signals: a write to one is invisible — mesh placement,
+     * attachments and everything else that follows a transform wake on {@link t64_announce_change}
+     * and nothing else — until it is announced.
+     *
+     * @param {EntityComponentDataset} dataset
+     * @param {number} entity
+     */
+    announce(dataset, entity) {
+        t64_announce_change(dataset, entity);
+    }
 }

package/src/engine/network/adapters/VelocityCorrection.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Corrects a rigid body's velocities by the difference: the host's linear and angular velocity at
+ * frame S, less the prediction's, added to the present and to every prediction since. The live
+ * velocities are set through the physics system, so a sleeping body wakes.
+ *
+ * For a component shaped like the physics package's `RigidBody` — `linearVelocity` and
+ * `angularVelocity`, indexable `[x, y, z]` — and found by its physics system's marker, so the
+ * network does not import physics.
+ *
+ * It corrects velocities only. A position the corrected velocity would have produced since S is
+ * not carried with it: the pose's own correction takes that up, a frame at a time, as the host's
+ * states arrive.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VelocityCorrection extends Correction {
+    carry(state: any, server: any, predicted: any): void;
+    /**
+     * @returns {number} the size of the linear velocity's correction, in world units per second
+     */
+    apply(target: any, server: any, predicted: any): number;
+    #private;
+}
+/**
+ * The shared {@link VelocityCorrection}, for a replicated rigid body.
+ * @type {VelocityCorrection}
+ */
+export const VELOCITY_CORRECTION: VelocityCorrection;
+import { Correction } from "../correction/Correction.js";
+//# sourceMappingURL=VelocityCorrection.d.ts.map

package/src/engine/network/adapters/VelocityCorrection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VelocityCorrection.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/VelocityCorrection.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH;IAOI,qDAKC;IAED;;OAEG;IACH,iDAFa,MAAM,CA6BlB;;CACJ;AAED;;;GAGG;AACH,kCAFU,kBAAkB,CAEgC;2BAtEjC,6BAA6B"}

package/src/engine/network/adapters/VelocityCorrection.js

@@ -0,0 +1,71 @@
+import { Correction } from "../correction/Correction.js";
+import { physics_system_of } from "./rigid_body_of.js";
+
+/**
+ * Corrects a rigid body's velocities by the difference: the host's linear and angular velocity at
+ * frame S, less the prediction's, added to the present and to every prediction since. The live
+ * velocities are set through the physics system, so a sleeping body wakes.
+ *
+ * For a component shaped like the physics package's `RigidBody` — `linearVelocity` and
+ * `angularVelocity`, indexable `[x, y, z]` — and found by its physics system's marker, so the
+ * network does not import physics.
+ *
+ * It corrects velocities only. A position the corrected velocity would have produced since S is
+ * not carried with it: the pose's own correction takes that up, a frame at a time, as the host's
+ * states arrive.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VelocityCorrection extends Correction {
+    /** @type {number[]} */
+    #v = [0, 0, 0];
+
+    /** @type {number[]} */
+    #w = [0, 0, 0];
+
+    carry(state, server, predicted) {
+        for (let i = 0; i < 3; i++) {
+            state.linearVelocity[i] += server.linearVelocity[i] - predicted.linearVelocity[i];
+            state.angularVelocity[i] += server.angularVelocity[i] - predicted.angularVelocity[i];
+        }
+    }
+
+    /**
+     * @returns {number} the size of the linear velocity's correction, in world units per second
+     */
+    apply(target, server, predicted) {
+        const live = target.component;
+        const v = this.#v;
+        const w = this.#w;
+
+        for (let i = 0; i < 3; i++) {
+            v[i] = live.linearVelocity[i] + server.linearVelocity[i] - predicted.linearVelocity[i];
+            w[i] = live.angularVelocity[i] + server.angularVelocity[i] - predicted.angularVelocity[i];
+        }
+
+        const physics = physics_system_of(target.entity_manager);
+
+        if (physics !== null) {
+            physics.setLinearVelocity(live, v);
+            physics.setAngularVelocity(live, w);
+        } else {
+            for (let i = 0; i < 3; i++) {
+                live.linearVelocity[i] = v[i];
+                live.angularVelocity[i] = w[i];
+            }
+        }
+
+        return Math.hypot(
+            server.linearVelocity[0] - predicted.linearVelocity[0],
+            server.linearVelocity[1] - predicted.linearVelocity[1],
+            server.linearVelocity[2] - predicted.linearVelocity[2],
+        );
+    }
+}
+
+/**
+ * The shared {@link VelocityCorrection}, for a replicated rigid body.
+ * @type {VelocityCorrection}
+ */
+export const VELOCITY_CORRECTION = new VelocityCorrection();

package/src/engine/network/adapters/replicate_transform64.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Replicate {@link Transform64} on `session`, drawn between network ticks by the engine's pose
+ * interpolation at full precision — {@link POSE_INTERPOLAND}, the interpoland local interpolation
+ * uses — and corrected on a client that predicts it by {@link POSE_CORRECTION}. Nothing more than
+ * `session.replicate_interpolated(Transform64, POSE_INTERPOLAND, POSE_CORRECTION)`.
+ *
+ * Like any replicated component, Transform64 needs its wire format registered in the session's
+ * `binary_registry` before the session starts — {@link TransformReplicationAdapter}.
+ *
+ * @param {import("../NetworkSession.js").NetworkSession} session
+ */
+export function replicate_transform64(session: import("../NetworkSession.js").NetworkSession): void;
+//# sourceMappingURL=replicate_transform64.d.ts.map

package/src/engine/network/adapters/replicate_transform64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replicate_transform64.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/replicate_transform64.js"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,+CAFW,OAAO,sBAAsB,EAAE,cAAc,QAIvD"}

package/src/engine/network/adapters/replicate_transform64.js

@@ -0,0 +1,18 @@
+import { Transform64 } from "../../ecs/transform/Transform64.js";
+import { POSE_INTERPOLAND } from "../../interpolation/pose_interpoland.js";
+import { POSE_CORRECTION } from "./PoseCorrection.js";
+
+/**
+ * Replicate {@link Transform64} on `session`, drawn between network ticks by the engine's pose
+ * interpolation at full precision — {@link POSE_INTERPOLAND}, the interpoland local interpolation
+ * uses — and corrected on a client that predicts it by {@link POSE_CORRECTION}. Nothing more than
+ * `session.replicate_interpolated(Transform64, POSE_INTERPOLAND, POSE_CORRECTION)`.
+ *
+ * Like any replicated component, Transform64 needs its wire format registered in the session's
+ * `binary_registry` before the session starts — {@link TransformReplicationAdapter}.
+ *
+ * @param {import("../NetworkSession.js").NetworkSession} session
+ */
+export function replicate_transform64(session) {
+    session.replicate_interpolated(Transform64, POSE_INTERPOLAND, POSE_CORRECTION);
+}

package/src/engine/network/adapters/rigid_body_of.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The engine's physics system, when it has one; otherwise null. Found by its marker
+ * (`isPhysicsSystem`), so the network does not import the physics package.
+ *
+ * @param {EntityManager} entity_manager
+ * @returns {object|null}
+ */
+export function physics_system_of(entity_manager: EntityManager): object | null;
+/**
+ * The rigid body on `entity` and the physics system that owns it, when the engine has physics and
+ * the entity is a body; otherwise null. Found by marker (`isPhysicsSystem`, `isRigidBody`), so the
+ * network does not import the physics package.
+ *
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @returns {{physics: object, body: object}|null}
+ */
+export function rigid_body_of(entity_manager: EntityManager, entity: number): {
+    physics: object;
+    body: object;
+} | null;
+//# sourceMappingURL=rigid_body_of.d.ts.map

package/src/engine/network/adapters/rigid_body_of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rigid_body_of.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/adapters/rigid_body_of.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,kEAFa,MAAM,GAAC,IAAI,CAKvB;AAED;;;;;;;;GAQG;AACH,qEAHW,MAAM,GACJ;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAahD"}

package/src/engine/network/adapters/rigid_body_of.js

@@ -0,0 +1,33 @@
+/**
+ * The engine's physics system, when it has one; otherwise null. Found by its marker
+ * (`isPhysicsSystem`), so the network does not import the physics package.
+ *
+ * @param {EntityManager} entity_manager
+ * @returns {object|null}
+ */
+export function physics_system_of(entity_manager) {
+    const physics = entity_manager.systems.find(system => system.isPhysicsSystem === true);
+    return physics === undefined ? null : physics;
+}
+
+/**
+ * The rigid body on `entity` and the physics system that owns it, when the engine has physics and
+ * the entity is a body; otherwise null. Found by marker (`isPhysicsSystem`, `isRigidBody`), so the
+ * network does not import the physics package.
+ *
+ * @param {EntityManager} entity_manager
+ * @param {number} entity
+ * @returns {{physics: object, body: object}|null}
+ */
+export function rigid_body_of(entity_manager, entity) {
+    const physics = physics_system_of(entity_manager);
+    if (physics === null) return null;
+
+    const RigidBodyClass = physics.dependencies.find(k => k.prototype !== undefined && k.prototype.isRigidBody === true);
+    if (RigidBodyClass === undefined) return null;
+
+    const body = entity_manager.dataset.getComponent(entity, RigidBodyClass);
+    if (body === undefined) return null;
+
+    return { physics, body };
+}

package/src/engine/network/correction/Correction.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @typedef {import("../../ecs/EntityManager.js").EntityManager} EntityManager
+ * @typedef {import("../../interpolation/InterpolationSystem.js").InterpolationSystem} InterpolationSystem
+ * @typedef {import("../../ecs/storage/binary/BinaryClassSerializationAdapter.js").BinaryClassSerializationAdapter} BinaryClassSerializationAdapter
+ */
+/**
+ * Where a correction lands: the live component of an entity, and what follows it. The session fills
+ * one in for every component it corrects and hands it to {@link Correction#apply}; read it there, do
+ * not keep it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class CorrectionTarget {
+    /**
+     * The engine the entity lives in — for a correction that has to go through the system that owns
+     * the component (a rigid body's pose goes through its physics system).
+     * @type {EntityManager|null}
+     */
+    entity_manager: EntityManager | null;
+    /** @type {number} */
+    entity: number;
+    /**
+     * The live component being corrected.
+     * @type {object|null}
+     */
+    component: object | null;
+    /**
+     * The engine's interpolation system, for a correction that hides its step in what is drawn
+     * ({@link InterpolationSystem#correct}); null when there is none.
+     * @type {InterpolationSystem|null}
+     */
+    interpolation: InterpolationSystem | null;
+    /**
+     * The component's replication adapter.
+     * @type {BinaryClassSerializationAdapter|null}
+     */
+    adapter: import("../../ecs/storage/binary/BinaryClassSerializationAdapter.js").BinaryClassSerializationAdapter<any> | null;
+    /**
+     * Make the live component `state`, as the wire carries it: through the component's replication
+     * adapter.
+     * @param {object} state a decoded state of the component
+     */
+    write(state: object): void;
+    #private;
+}
+/**
+ * How a client corrects one replicated component of an entity it predicts, when it reconciles by
+ * comparison ({@link NetworkSessionReconcile.Correct}).
+ *
+ * The host's state of the entity at frame S arrives some frames after the client predicted S. The
+ * session compares the two — their wire images first, and only where those differ, through
+ * {@link same} — and when they disagree, hands the strategy both: the host's state and the
+ * prediction, at S, decoded through the component's replication adapter, so both at the wire's
+ * precision. The strategy carries the difference into the present: into the live component
+ * ({@link apply}), and into each prediction the client has made since S ({@link carry}), so the next
+ * comparison is against a history consistent with the correction.
+ *
+ * This base class carries nothing: it has no notion of what a difference between two states of an
+ * arbitrary component means. The host's value at S replaces the live component, and the predictions
+ * since S are left as they were. What the client predicted after S is lost with it — so for a
+ * component the client predicts from its own input, every prediction since comes up short of the
+ * host, and each comparison corrects it again: it does not settle. It is for components a client
+ * does not predict, and values with no difference to carry. A component whose differences mean
+ * something — a pose, a velocity, a count the client adds to — has a strategy that carries them.
+ *
+ * Strategies are stateless as far as the session is concerned, and shared: one instance serves every
+ * entity and every session.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Correction {
+    /**
+     * Whether `server` and `predicted`, the host's state and the prediction for the same frame,
+     * describe the same state. Asked only when their wire images differ: a strategy that tolerates
+     * a difference — the rounding an encoding cannot tell apart — says so here.
+     *
+     * @param {object} server
+     * @param {object} predicted
+     * @returns {boolean}
+     */
+    same(server: object, predicted: object): boolean;
+    /**
+     * Carry the difference between `server` and `predicted` into `state`, in place: a prediction of
+     * the same entity for a frame after theirs.
+     *
+     * @param {object} state
+     * @param {object} server
+     * @param {object} predicted
+     */
+    carry(state: object, server: object, predicted: object): void;
+    /**
+     * Carry the difference between `server` and `predicted` into the entity's live component, and
+     * into whatever the component's value runs through — the system that owns it, what is drawn.
+     * The session announces the write afterwards.
+     *
+     * @param {CorrectionTarget} target
+     * @param {object} server
+     * @param {object} predicted
+     * @returns {number} the size of the correction, in the strategy's own terms, for
+     *   {@link NetworkSession#onCorrection}; 0 when it has none
+     */
+    apply(target: CorrectionTarget, server: object, predicted: object): number;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isCorrection: boolean;
+}
+/**
+ * The host's value replaces the live component; see {@link Correction}. For a component a client
+ * does not predict, or whose value has no difference to carry — a name, a state machine's state.
+ * @type {Correction}
+ */
+export const HOST_VALUE_CORRECTION: Correction;
+export type EntityManager = import("../../ecs/EntityManager.js").EntityManager;
+export type InterpolationSystem = import("../../interpolation/InterpolationSystem.js").InterpolationSystem;
+export type BinaryClassSerializationAdapter = import("../../ecs/storage/binary/BinaryClassSerializationAdapter.js").BinaryClassSerializationAdapter<any>;
+//# sourceMappingURL=Correction.d.ts.map

package/src/engine/network/correction/Correction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Correction.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/correction/Correction.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,gBAFU,aAAa,GAAC,IAAI,CAEN;IAEtB,qBAAqB;IACrB,QADW,MAAM,CACL;IAEZ;;;OAGG;IACH,WAFU,MAAM,GAAC,IAAI,CAEJ;IAEjB;;;;OAIG;IACH,eAFU,mBAAmB,GAAC,IAAI,CAEb;IAErB;;;OAGG;IACH,SAFU,6GAAgC,IAAI,CAE/B;IAKf;;;;OAIG;IACH,aAFW,MAAM,QAQhB;;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACI;;;;;;;;OAQG;IACH,aAJW,MAAM,aACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,aAJW,MAAM,UACN,MAAM,aACN,MAAM,QAGhB;IAED;;;;;;;;;;OAUG;IACH,cANW,gBAAgB,UAChB,MAAM,aACN,MAAM,GACJ,MAAM,CAMlB;IAGL;;;OAGG;IACH,uBAFU,OAAO,CAEgB;CANhC;AAQD;;;;GAIG;AACH,oCAFU,UAAU,CAEiD;4BA3IxD,OAAO,4BAA4B,EAAE,aAAa;kCAClD,OAAO,4CAA4C,EAAE,mBAAmB"}