@woosh/meep-engine 3.0.2 → 3.2.0

package/src/engine/network/CONGESTION_CONTROL.md

@@ -1,87 +1,87 @@
-# Congestion control — deferred design note (review item #6)
-
-**Status: NOT IMPLEMENTED. Deliberately deferred.** This note records the design
-and the decision so it isn't re-litigated. It came out of the comparative review
-against Valve GameNetworkingSockets (GNS), 2026-06.
-
-## The gap
-
-There is no congestion control or send pacing anywhere on the meep-owned send
-path. `NetworkPeer.flush_outbound` packs `[last_acked+1 .. current]` for every
-peer every tick and hands it straight to `Channel.send` / `send_fragmented` with
-no byte budget, no rate ceiling, and no loss→rate feedback. `onPacketLost` only
-drops the stale `seq→frame_end` mapping; it never reduces a send rate. So under a
-constrained link, output *rises* exactly when the path sheds load (the repacked
-unacked frames plus reliable/fragment retransmits stack on top) — classic
-self-inflicted bufferbloat with no AIMD backoff.
-
-GNS, by contrast, paces every packet through `SNP_TokenBucket_Accumulate` at a
-`m_nCurrentSendRateEstimate` that is RFC3390-seeded, shrinks on loss, grows on
-clean acks, and is clamped to `[SendRateMin, SendRateMax]` with a bounded burst.
-
-## Why it's deferred (not "won't do")
-
-The criticality is **conditional on transport choice**:
-
-- **WebRTC / WebSocket / WebTransport** ride DTLS-over-SCTP / TLS-over-TCP. Those
-  layers already do congestion control. On the transports the project actually
-  ships to browsers, this gap is **masked** — adding a second governor on top
-  would fight the underlying one.
-- **NodeUDP / Simulated** are raw datagrams with none of that. These are the
-  *only* transports where #6 bites, and they're scoped as test/LAN today.
-
-So the payoff is low until raw UDP is shipped to real, constrained, or untrusted
-networks. The cost to build correctly is high (see below). That trade puts it
-behind the cheaper items (liveness reaping, in-flight cap, resume ring-floor),
-which are all landed.
-
-## What it would cost to *run* (cheap)
-
-Per connection:
-
-- Token bucket: `tokens`, `rate_estimate`, `last_refill_ms` — ~32 B.
-- Smoothed RTT / RTO (EWMA + variance, RFC6298 shape) — ~24 B.
-- RTT-from-acks needs a send-timestamp per in-flight seq — ~8 B × in-flight.
-- If `PriorityAccumulator` is wired per-peer for fairness when the bucket binds —
-  ~16·`type_count` B (T=50 → ~800 B).
-
-Total ≈ **100 B – 1 KB per peer** (≈ 0.1–1 MB at 1000 peers). ALU is **tens of
-FLOP per peer per tick** (refill + check + deduct; EWMA + AIMD on ack/loss;
-`PriorityAccumulator.sorted_descending` is allocation-free and only runs when the
-bucket binds). Well under 0.1% of a core even at 1000 peers. Cycles and bytes are
-not the obstacle.
-
-## What it would cost to *build* (the real obstacle)
-
-1. **RTT plumbing.** Nothing currently feeds RTT into the live path —
-   `time/TimeSync.js` is built but wired to nothing, and it tracks *min* RTT
-   (SNTP), not the *smoothed* RTT a governor needs. You must add either explicit
-   ping/pong (extra packets) or derive RTT from ack timing with Karn's algorithm
-   (exclude retransmit-ambiguous samples), which means stamping a send time per
-   in-flight seq.
-2. **Latency / buffering interaction.** Pacing deliberately *delays* sends when
-   the bucket is empty. That's the point (avoid self-inflicted loss) but it
-   changes timing and interacts with client prediction / reconciliation.
-3. **Determinism.** The rate decision is wall-clock driven and MUST stay on the
-   transport side, never the deterministic sim path, or it breaks the
-   determinism contract (there is a standing determinism gate). `TimeDilation`
-   already regulates the sim *tick rate* against input-buffer depth — that is
-   orthogonal application-tier flow control, **not** a byte-pacing substitute,
-   and the two must not be conflated.
-
-## Design sketch (if/when built)
-
-- Add a per-connection rate governor on the UDP transport path, gating
-  `NetworkPeer.#send_to_peer` and the retransmit paths. Scope it to
-  `NodeUDPTransport` / `SimulatedTransport`; leave the browser transports alone.
-- Seed the rate from measured RTT (`TimeSync`), reduce on `onPacketLost`, grow on
-  clean acks, clamp `[min, max]` with a bounded burst.
-- When the bucket binds, consult `PriorityAccumulator.sorted_descending` to pick
-  which bytes go out this tick and defer the rest (`BandwidthMeter` can verify
-  the achieved rate). These primitives already exist and are correct — they are
-  intentionally unwired opt-in surface, **not** dead code.
-- Do NOT add a cipher/sliding-window or any of this to `Channel`; congestion
-  control belongs above the seq/ack layer, on the transport-facing send path.
-
-@author Alex Goldring
-@copyright Company Named Limited (c) 2026
+# Congestion control — deferred design note (review item #6)
+
+**Status: NOT IMPLEMENTED. Deliberately deferred.** This note records the design
+and the decision so it isn't re-litigated. It came out of the comparative review
+against Valve GameNetworkingSockets (GNS), 2026-06.
+
+## The gap
+
+There is no congestion control or send pacing anywhere on the meep-owned send
+path. `NetworkPeer.flush_outbound` packs `[last_acked+1 .. current]` for every
+peer every tick and hands it straight to `Channel.send` / `send_fragmented` with
+no byte budget, no rate ceiling, and no loss→rate feedback. `onPacketLost` only
+drops the stale `seq→frame_end` mapping; it never reduces a send rate. So under a
+constrained link, output *rises* exactly when the path sheds load (the repacked
+unacked frames plus reliable/fragment retransmits stack on top) — classic
+self-inflicted bufferbloat with no AIMD backoff.
+
+GNS, by contrast, paces every packet through `SNP_TokenBucket_Accumulate` at a
+`m_nCurrentSendRateEstimate` that is RFC3390-seeded, shrinks on loss, grows on
+clean acks, and is clamped to `[SendRateMin, SendRateMax]` with a bounded burst.
+
+## Why it's deferred (not "won't do")
+
+The criticality is **conditional on transport choice**:
+
+- **WebRTC / WebSocket / WebTransport** ride DTLS-over-SCTP / TLS-over-TCP. Those
+  layers already do congestion control. On the transports the project actually
+  ships to browsers, this gap is **masked** — adding a second governor on top
+  would fight the underlying one.
+- **NodeUDP / Simulated** are raw datagrams with none of that. These are the
+  *only* transports where #6 bites, and they're scoped as test/LAN today.
+
+So the payoff is low until raw UDP is shipped to real, constrained, or untrusted
+networks. The cost to build correctly is high (see below). That trade puts it
+behind the cheaper items (liveness reaping, in-flight cap, resume ring-floor),
+which are all landed.
+
+## What it would cost to *run* (cheap)
+
+Per connection:
+
+- Token bucket: `tokens`, `rate_estimate`, `last_refill_ms` — ~32 B.
+- Smoothed RTT / RTO (EWMA + variance, RFC6298 shape) — ~24 B.
+- RTT-from-acks needs a send-timestamp per in-flight seq — ~8 B × in-flight.
+- If `PriorityAccumulator` is wired per-peer for fairness when the bucket binds —
+  ~16·`type_count` B (T=50 → ~800 B).
+
+Total ≈ **100 B – 1 KB per peer** (≈ 0.1–1 MB at 1000 peers). ALU is **tens of
+FLOP per peer per tick** (refill + check + deduct; EWMA + AIMD on ack/loss;
+`PriorityAccumulator.sorted_descending` is allocation-free and only runs when the
+bucket binds). Well under 0.1% of a core even at 1000 peers. Cycles and bytes are
+not the obstacle.
+
+## What it would cost to *build* (the real obstacle)
+
+1. **RTT plumbing.** Nothing currently feeds RTT into the live path —
+   `time/TimeSync.js` is built but wired to nothing, and it tracks *min* RTT
+   (SNTP), not the *smoothed* RTT a governor needs. You must add either explicit
+   ping/pong (extra packets) or derive RTT from ack timing with Karn's algorithm
+   (exclude retransmit-ambiguous samples), which means stamping a send time per
+   in-flight seq.
+2. **Latency / buffering interaction.** Pacing deliberately *delays* sends when
+   the bucket is empty. That's the point (avoid self-inflicted loss) but it
+   changes timing and interacts with client prediction / reconciliation.
+3. **Determinism.** The rate decision is wall-clock driven and MUST stay on the
+   transport side, never the deterministic sim path, or it breaks the
+   determinism contract (there is a standing determinism gate). `TimeDilation`
+   already regulates the sim *tick rate* against input-buffer depth — that is
+   orthogonal application-tier flow control, **not** a byte-pacing substitute,
+   and the two must not be conflated.
+
+## Design sketch (if/when built)
+
+- Add a per-connection rate governor on the UDP transport path, gating
+  `NetworkPeer.#send_to_peer` and the retransmit paths. Scope it to
+  `NodeUDPTransport` / `SimulatedTransport`; leave the browser transports alone.
+- Seed the rate from measured RTT (`TimeSync`), reduce on `onPacketLost`, grow on
+  clean acks, clamp `[min, max]` with a bounded burst.
+- When the bucket binds, consult `PriorityAccumulator.sorted_descending` to pick
+  which bytes go out this tick and defer the rest (`BandwidthMeter` can verify
+  the achieved rate). These primitives already exist and are correct — they are
+  intentionally unwired opt-in surface, **not** dead code.
+- Do NOT add a cipher/sliding-window or any of this to `Channel`; congestion
+  control belongs above the seq/ack layer, on the transport-facing send path.
+
+@author Alex Goldring
+@copyright Company Named Limited (c) 2026

package/src/engine/network/README.md

@@ -1,52 +1,52 @@
-# `engine/network` — netcode package
-
-Action-log replication, client-side prediction + reconciliation, and a
-server-authoritative rollback orchestrator, layered over a pluggable transport.
-
-## Layers (bottom → top)
-
-| Layer | Pieces | Responsibility |
-| --- | --- | --- |
-| Transport | `transport/adapters/*` (`WebRTCDataChannel`, `WebTransport`, `WebSocket`, `NodeUDP`, `Simulated`, `Loopback`) | Move opaque byte buffers. UDP-style unless `reliable`/`ordered` say otherwise. |
-| Channel | `transport/Channel.js` | Seq + ack-bitfield header; surfaces `onPacketAcked` / `onPacketLost` / `onPayload`. No retransmit. |
-| Reliability / fragmentation | `transport/ReliableCommandPipeline.js`, `transport/fragments/*` | At-least-once commands; MTU fragmentation + NACK retransmit. |
-| Sim core | `sim/*` (`ActionLog`, `SimAction`, `SimActionExecutor`, `RewindEngine`, `Snapshotter`, registries) | Record/apply/rewind replicated state mutations. |
-| Replication | `replication/Replicator.js`, `replication/ScopeFilter.js` | Pack/unpack action records per peer, scope-filtered. |
-| Orchestrator | `orchestrator/NetworkPeer.js`, `orchestrator/ServerAuthoritative{Server,Client}.js` | Per-tick send/recv, rollback (server), predict-reconcile (client). |
-| Facade | `NetworkSession.js` | One config + lifecycle surface; wires everything below. |
-
-## Wired automatically by `NetworkSession`
-
-`NetworkPeer` (and through it `Channel`, `Replicator`, `ActionLog`,
-`SimActionExecutor`, the registries, `ReplicationSlotTable`, `Baseline`,
-the fragment layer, and `ReliableCommandPipeline`), the two orchestrators
-(and through them `RewindEngine` and `InputRing`), plus `TimeDilation`,
-`AdaptiveRenderDelay`, `InterpolationLog`, `NetworkSystem`, `NetworkIdentity`,
-and `Snapshotter`. `ChangedEntitySet` / `MutationLedger` are wired on the host
-when a mutation ledger is supplied.
-
-## Opt-in primitives — NOT wired by `NetworkSession`
-
-These are tested, public library surface intended for game code to wire up
-directly; the facade does not use them. They are deliberate exports, not dead
-code — fix bugs in them, don't delete them.
-
-| Primitive | What it's for | To use it |
-| --- | --- | --- |
-| `time/TimeSync.js` | NTP-style clock-offset estimation | Drive it from a ping/pong round-trip; read `offset()` / `best_rtt()`. |
-| `time/JitterBuffer.js` | Frame-tagged reorder/hold buffer | `push(frame, payload)`; `drain_until(current_frame, cb)`. |
-| `sim/SmoothingState.js` | Hide the post-reconcile correction snap | After reconcile, feed the pre/post pose; add the decaying error in your render path. |
-| `state/PriorityAccumulator.js` | Bandwidth-aware action scheduling | Consult `sorted_descending()` when an outgoing packet approaches MTU. |
-| `diagnostics/BandwidthMeter.js` | Throughput accounting | Sample around `transport.getStats()`. |
-| `diagnostics/ReplayLog.js` | Record/replay packet streams | Capture inbound/outbound for offline repro. |
-| `diagnostics/SyncTest.js` | Determinism / desync checking | Compare state hashes across peers. |
-| `adapters/Quaternion`/`Vector3InterpolationAdapter.js` | Interp building blocks | Reference when writing a component interpolation adapter (cf. `TransformInterpolationAdapter`). |
-
-If you wire one of these into the facade, move its row up to the section above.
-
-## Deferred / known gaps
-
-- **Congestion control / send pacing** — there is none on the meep-owned send
-  path. Masked on the browser transports (DTLS/SCTP, TLS/TCP do it underneath);
-  only matters for raw `NodeUDP` / `Simulated` on constrained links. Design and
-  rationale for the deferral are in [`CONGESTION_CONTROL.md`](./CONGESTION_CONTROL.md).
+# `engine/network` — netcode package
+
+Action-log replication, client-side prediction + reconciliation, and a
+server-authoritative rollback orchestrator, layered over a pluggable transport.
+
+## Layers (bottom → top)
+
+| Layer | Pieces | Responsibility |
+| --- | --- | --- |
+| Transport | `transport/adapters/*` (`WebRTCDataChannel`, `WebTransport`, `WebSocket`, `NodeUDP`, `Simulated`, `Loopback`) | Move opaque byte buffers. UDP-style unless `reliable`/`ordered` say otherwise. |
+| Channel | `transport/Channel.js` | Seq + ack-bitfield header; surfaces `onPacketAcked` / `onPacketLost` / `onPayload`. No retransmit. |
+| Reliability / fragmentation | `transport/ReliableCommandPipeline.js`, `transport/fragments/*` | At-least-once commands; MTU fragmentation + NACK retransmit. |
+| Sim core | `sim/*` (`ActionLog`, `SimAction`, `SimActionExecutor`, `RewindEngine`, `Snapshotter`, registries) | Record/apply/rewind replicated state mutations. |
+| Replication | `replication/Replicator.js`, `replication/ScopeFilter.js` | Pack/unpack action records per peer, scope-filtered. |
+| Orchestrator | `orchestrator/NetworkPeer.js`, `orchestrator/ServerAuthoritative{Server,Client}.js` | Per-tick send/recv, rollback (server), predict-reconcile (client). |
+| Facade | `NetworkSession.js` | One config + lifecycle surface; wires everything below. |
+
+## Wired automatically by `NetworkSession`
+
+`NetworkPeer` (and through it `Channel`, `Replicator`, `ActionLog`,
+`SimActionExecutor`, the registries, `ReplicationSlotTable`, `Baseline`,
+the fragment layer, and `ReliableCommandPipeline`), the two orchestrators
+(and through them `RewindEngine` and `InputRing`), plus `TimeDilation`,
+`AdaptiveRenderDelay`, `InterpolationLog`, `NetworkSystem`, `NetworkIdentity`,
+and `Snapshotter`. `ChangedEntitySet` / `MutationLedger` are wired on the host
+when a mutation ledger is supplied.
+
+## Opt-in primitives — NOT wired by `NetworkSession`
+
+These are tested, public library surface intended for game code to wire up
+directly; the facade does not use them. They are deliberate exports, not dead
+code — fix bugs in them, don't delete them.
+
+| Primitive | What it's for | To use it |
+| --- | --- | --- |
+| `time/TimeSync.js` | NTP-style clock-offset estimation | Drive it from a ping/pong round-trip; read `offset()` / `best_rtt()`. |
+| `time/JitterBuffer.js` | Frame-tagged reorder/hold buffer | `push(frame, payload)`; `drain_until(current_frame, cb)`. |
+| `sim/SmoothingState.js` | Hide the post-reconcile correction snap | After reconcile, feed the pre/post pose; add the decaying error in your render path. |
+| `state/PriorityAccumulator.js` | Bandwidth-aware action scheduling | Consult `sorted_descending()` when an outgoing packet approaches MTU. |
+| `diagnostics/BandwidthMeter.js` | Throughput accounting | Sample around `transport.getStats()`. |
+| `diagnostics/ReplayLog.js` | Record/replay packet streams | Capture inbound/outbound for offline repro. |
+| `diagnostics/SyncTest.js` | Determinism / desync checking | Compare state hashes across peers. |
+| `adapters/Quaternion`/`Vector3InterpolationAdapter.js` | Interp building blocks | Reference when writing a component interpolation adapter (cf. `TransformInterpolationAdapter`). |
+
+If you wire one of these into the facade, move its row up to the section above.
+
+## Deferred / known gaps
+
+- **Congestion control / send pacing** — there is none on the meep-owned send
+  path. Masked on the browser transports (DTLS/SCTP, TLS/TCP do it underneath);
+  only matters for raw `NodeUDP` / `Simulated` on constrained links. Design and
+  rationale for the deferral are in [`CONGESTION_CONTROL.md`](./CONGESTION_CONTROL.md).

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

@@ -1,43 +1,43 @@
-import { quat3_nlerp } from "../../../core/geom/3d/quaternion/quat3_nlerp.js";
-import { BinaryInterpolationAdapter } from "../../interpolation/BinaryInterpolationAdapter.js";
-
-/**
- * Module-level scratch for the blend result. Float64 so the blend keeps full
- * precision right up to the Float32 write. Safe because `interpolate` is
- * synchronous and non-reentrant.
- * @type {Float64Array}
- */
-const scratch = new Float64Array(4);
-
-/**
- * Shortest-path nlerp for a 4 × Float32 quaternion payload (16 bytes).
- * Switch to a slerp variant if you need it for wide per-tick angular
- * steps (animation-blended joints, slow snapshot rate).
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class QuaternionInterpolationAdapter extends BinaryInterpolationAdapter {
-
-    /** @inheritdoc */
-    interpolate(out_buffer, source, first_offset, second_offset, t) {
-        source.position = first_offset;
-        const ax = source.readFloat32();
-        const ay = source.readFloat32();
-        const az = source.readFloat32();
-        const aw = source.readFloat32();
-
-        source.position = second_offset;
-        const bx = source.readFloat32();
-        const by = source.readFloat32();
-        const bz = source.readFloat32();
-        const bw = source.readFloat32();
-
-        quat3_nlerp(scratch, 0, ax, ay, az, aw, bx, by, bz, bw, t);
-
-        out_buffer.writeFloat32(scratch[0]);
-        out_buffer.writeFloat32(scratch[1]);
-        out_buffer.writeFloat32(scratch[2]);
-        out_buffer.writeFloat32(scratch[3]);
-    }
-}
+import { quat3_nlerp } from "../../../core/geom/3d/quaternion/quat3_nlerp.js";
+import { BinaryInterpolationAdapter } from "../../interpolation/BinaryInterpolationAdapter.js";
+
+/**
+ * Module-level scratch for the blend result. Float64 so the blend keeps full
+ * precision right up to the Float32 write. Safe because `interpolate` is
+ * synchronous and non-reentrant.
+ * @type {Float64Array}
+ */
+const scratch = new Float64Array(4);
+
+/**
+ * Shortest-path nlerp for a 4 × Float32 quaternion payload (16 bytes).
+ * Switch to a slerp variant if you need it for wide per-tick angular
+ * steps (animation-blended joints, slow snapshot rate).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class QuaternionInterpolationAdapter extends BinaryInterpolationAdapter {
+
+    /** @inheritdoc */
+    interpolate(out_buffer, source, first_offset, second_offset, t) {
+        source.position = first_offset;
+        const ax = source.readFloat32();
+        const ay = source.readFloat32();
+        const az = source.readFloat32();
+        const aw = source.readFloat32();
+
+        source.position = second_offset;
+        const bx = source.readFloat32();
+        const by = source.readFloat32();
+        const bz = source.readFloat32();
+        const bw = source.readFloat32();
+
+        quat3_nlerp(scratch, 0, ax, ay, az, aw, bx, by, bz, bw, t);
+
+        out_buffer.writeFloat32(scratch[0]);
+        out_buffer.writeFloat32(scratch[1]);
+        out_buffer.writeFloat32(scratch[2]);
+        out_buffer.writeFloat32(scratch[3]);
+    }
+}

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

@@ -1,84 +1,84 @@
-import { quat3_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat3_decode_from_uint32.js";
-import { quat3_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat3_encode_to_uint32.js";
-import { quat3_nlerp } from "../../../core/geom/3d/quaternion/quat3_nlerp.js";
-import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization/v3_binary_equality_decode.js";
-import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
-import { BinaryInterpolationAdapter } from "../../interpolation/BinaryInterpolationAdapter.js";
-
-/**
- * Module-level scratch. Layout: `[aq.xyzw, bq.xyzw, as.xyz, bs.xyz]`.
- * Safe because `interpolate` is synchronous and non-reentrant.
- * @type {Float32Array}
- */
-const scratch = new Float32Array(16);
-
-/**
- * Module-level scratch for the blended rotation. Kept separate from
- * {@link scratch} and at Float64 so the blend feeds the smallest-three
- * encoder at full precision, exactly as the previous inline math did.
- * @type {Float64Array}
- */
-const rotation_scratch = new Float64Array(4);
-
-/**
- * Linear-blend interpolation for {@link Transform}, matching the wire
- * layout of {@link TransformReplicationAdapter}: 3×Float32 position +
- * uint32 packed quaternion + equality-encoded scale.
- *
- * Position lerps componentwise; rotation nlerps with shortest-path
- * correction; scale decodes/lerps/re-encodes (output is still valid
- * equality-encoded).
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class TransformInterpolationAdapter extends BinaryInterpolationAdapter {
-
-    /** @inheritdoc */
-    interpolate(out_buffer, source, first_offset, second_offset, t) {
-        // ---- Decode sample A ----
-        source.position = first_offset;
-        const ax = source.readFloat32();
-        const ay = source.readFloat32();
-        const az = source.readFloat32();
-        const a_quat_packed = source.readUint32();
-        quat3_decode_from_uint32(scratch, 0, a_quat_packed);  // → scratch[0..3]
-        v3_binary_equality_decode(source, scratch, 8);       // → scratch[8..10]
-
-        // ---- Decode sample B ----
-        source.position = second_offset;
-        const bx = source.readFloat32();
-        const by = source.readFloat32();
-        const bz = source.readFloat32();
-        const b_quat_packed = source.readUint32();
-        quat3_decode_from_uint32(scratch, 4, b_quat_packed);  // → scratch[4..7]
-        v3_binary_equality_decode(source, scratch, 11);      // → scratch[11..13]
-
-        // ---- Position lerp ----
-        const out_x = ax + (bx - ax) * t;
-        const out_y = ay + (by - ay) * t;
-        const out_z = az + (bz - az) * t;
-
-        // ---- Rotation nlerp with shortest-path correction ----
-        quat3_nlerp(
-            rotation_scratch, 0,
-            scratch[0], scratch[1], scratch[2], scratch[3],
-            scratch[4], scratch[5], scratch[6], scratch[7],
-            t,
-        );
-
-        // ---- Scale lerp ----
-        const out_sx = scratch[8]  + (scratch[11] - scratch[8])  * t;
-        const out_sy = scratch[9]  + (scratch[12] - scratch[9])  * t;
-        const out_sz = scratch[10] + (scratch[13] - scratch[10]) * t;
-
-        // ---- Re-encode to TransformReplicationAdapter wire layout ----
-        out_buffer.writeFloat32(out_x);
-        out_buffer.writeFloat32(out_y);
-        out_buffer.writeFloat32(out_z);
-        out_buffer.writeUint32(quat3_encode_to_uint32(
-            rotation_scratch[0], rotation_scratch[1], rotation_scratch[2], rotation_scratch[3],
-        ));
-        v3_binary_equality_encode(out_buffer, out_sx, out_sy, out_sz);
-    }
-}
+import { quat3_decode_from_uint32 } from "../../../core/geom/3d/quaternion/quat3_decode_from_uint32.js";
+import { quat3_encode_to_uint32 } from "../../../core/geom/3d/quaternion/quat3_encode_to_uint32.js";
+import { quat3_nlerp } from "../../../core/geom/3d/quaternion/quat3_nlerp.js";
+import { v3_binary_equality_decode } from "../../../core/geom/vec3/serialization/v3_binary_equality_decode.js";
+import { v3_binary_equality_encode } from "../../../core/geom/vec3/serialization/v3_binary_equality_encode.js";
+import { BinaryInterpolationAdapter } from "../../interpolation/BinaryInterpolationAdapter.js";
+
+/**
+ * Module-level scratch. Layout: `[aq.xyzw, bq.xyzw, as.xyz, bs.xyz]`.
+ * Safe because `interpolate` is synchronous and non-reentrant.
+ * @type {Float32Array}
+ */
+const scratch = new Float32Array(16);
+
+/**
+ * Module-level scratch for the blended rotation. Kept separate from
+ * {@link scratch} and at Float64 so the blend feeds the smallest-three
+ * encoder at full precision, exactly as the previous inline math did.
+ * @type {Float64Array}
+ */
+const rotation_scratch = new Float64Array(4);
+
+/**
+ * Linear-blend interpolation for {@link Transform}, matching the wire
+ * layout of {@link TransformReplicationAdapter}: 3×Float32 position +
+ * uint32 packed quaternion + equality-encoded scale.
+ *
+ * Position lerps componentwise; rotation nlerps with shortest-path
+ * correction; scale decodes/lerps/re-encodes (output is still valid
+ * equality-encoded).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class TransformInterpolationAdapter extends BinaryInterpolationAdapter {
+
+    /** @inheritdoc */
+    interpolate(out_buffer, source, first_offset, second_offset, t) {
+        // ---- Decode sample A ----
+        source.position = first_offset;
+        const ax = source.readFloat32();
+        const ay = source.readFloat32();
+        const az = source.readFloat32();
+        const a_quat_packed = source.readUint32();
+        quat3_decode_from_uint32(scratch, 0, a_quat_packed);  // → scratch[0..3]
+        v3_binary_equality_decode(source, scratch, 8);       // → scratch[8..10]
+
+        // ---- Decode sample B ----
+        source.position = second_offset;
+        const bx = source.readFloat32();
+        const by = source.readFloat32();
+        const bz = source.readFloat32();
+        const b_quat_packed = source.readUint32();
+        quat3_decode_from_uint32(scratch, 4, b_quat_packed);  // → scratch[4..7]
+        v3_binary_equality_decode(source, scratch, 11);      // → scratch[11..13]
+
+        // ---- Position lerp ----
+        const out_x = ax + (bx - ax) * t;
+        const out_y = ay + (by - ay) * t;
+        const out_z = az + (bz - az) * t;
+
+        // ---- Rotation nlerp with shortest-path correction ----
+        quat3_nlerp(
+            rotation_scratch, 0,
+            scratch[0], scratch[1], scratch[2], scratch[3],
+            scratch[4], scratch[5], scratch[6], scratch[7],
+            t,
+        );
+
+        // ---- Scale lerp ----
+        const out_sx = scratch[8]  + (scratch[11] - scratch[8])  * t;
+        const out_sy = scratch[9]  + (scratch[12] - scratch[9])  * t;
+        const out_sz = scratch[10] + (scratch[13] - scratch[10]) * t;
+
+        // ---- Re-encode to TransformReplicationAdapter wire layout ----
+        out_buffer.writeFloat32(out_x);
+        out_buffer.writeFloat32(out_y);
+        out_buffer.writeFloat32(out_z);
+        out_buffer.writeUint32(quat3_encode_to_uint32(
+            rotation_scratch[0], rotation_scratch[1], rotation_scratch[2], rotation_scratch[3],
+        ));
+        v3_binary_equality_encode(out_buffer, out_sx, out_sy, out_sz);
+    }
+}