@wenathlan/stealthhead 0.0.0-stage → 2.0.117

package/tests/hud.test.ts

@@ -0,0 +1,204 @@
+// # hud.test — honest unit tests for the hud state logic (vital bands,
+// minimap transforms, hitmarkers, killfeed, damage pings), runnable with
+// the vitest runner:
+//   pnpm test
+// Every case feeds plain structs and checks exact numbers — no dom, no
+// rendering, no mocks, no randomness.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  activehitmarkers,
+  applydamage,
+  DAMAGESTRENGTHFLOOR,
+  directionaldamage,
+  effectivepool,
+  HITWINDOWS,
+  type Hitmarker,
+  healthfraction,
+  hitmarkerfor,
+  hitmarkerwindow,
+  isalive,
+  KILLFEEDCAP,
+  KILLFEEDTTL,
+  type KillfeedEntry,
+  killfeedline,
+  minimapbounds,
+  minimapconfig,
+  poolfraction,
+  prunekillfeed,
+  pushhitmarker,
+  pushkillfeed,
+  sectorof,
+  shieldfraction,
+  tominimap,
+  VITALTHRESHOLDS,
+  type Vitals,
+  vitaltier,
+} from "../hud.ts";
+
+/** full vitals: 100 health behind 50 shield. */
+const FULL: Vitals = { health: 100, maxhealth: 100, shields: 50, maxshields: 50 };
+
+/** a widget transform over a 100x100 world on a 200px map (10px rim). */
+const WIDGET = { bounds: { minx: -50, minz: -50, maxx: 50, maxz: 50 }, sizepx: 200, padding: 10, yaw: 0 };
+
+/** one killfeed row builder. */
+function kill(id: string, at: number): KillfeedEntry {
+  return { id, killer: "ember-1", victim: "tide-2", weapon: "raven", at, headshot: false };
+}
+
+describe("vital bands", () => {
+  it("reads the pool fraction clamped to [0, 1]", () => {
+    assert.equal(poolfraction(FULL), 1);
+    assert.ok(Math.abs(poolfraction({ health: 40, maxhealth: 100, shields: 20, maxshields: 50 }) - 0.4) < 1e-9);
+    assert.equal(poolfraction({ health: 999, maxhealth: 100, shields: 999, maxshields: 50 }), 1);
+    assert.equal(poolfraction({ health: 0, maxhealth: 0, shields: 0, maxshields: 0 }), 0);
+  });
+
+  it("bands the vitals through the four thresholds", () => {
+    assert.equal(vitaltier(FULL), "healthy");
+    assert.equal(vitaltier({ health: 70, maxhealth: 100, shields: 10, maxshields: 50 }), "wounded");
+    assert.equal(vitaltier({ health: 40, maxhealth: 100, shields: 10, maxshields: 50 }), "low");
+    assert.equal(vitaltier({ health: 20, maxhealth: 100, shields: 0, maxshields: 50 }), "critical");
+    assert.equal(VITALTHRESHOLDS.critical, 0.25);
+    assert.equal(VITALTHRESHOLDS.wounded, 0.75);
+  });
+
+  it("applies damage with shields first and counts the overflow", () => {
+    const shielded = applydamage(FULL, 30);
+    assert.equal(shielded.absorbed, 30);
+    assert.deepEqual(shielded.vitals, { health: 100, maxhealth: 100, shields: 20, maxshields: 50 });
+    const spillover = applydamage({ health: 100, maxhealth: 100, shields: 20, maxshields: 50 }, 70);
+    assert.equal(spillover.absorbed, 20);
+    assert.equal(spillover.vitals.health, 50);
+    assert.equal(spillover.overflow, 0);
+    const lethal = applydamage({ health: 100, maxhealth: 100, shields: 0, maxshields: 50 }, 200);
+    assert.equal(lethal.vitals.health, 0);
+    assert.equal(lethal.overflow, 100);
+    assert.equal(applydamage(FULL, -5).overflow, 0);
+  });
+
+  it("answers life and the armor-perk effective pool", () => {
+    assert.equal(healthfraction(FULL), 1);
+    assert.ok(Math.abs(healthfraction({ ...FULL, health: 25 }) - 0.25) < 1e-9);
+    assert.ok(Math.abs(shieldfraction({ ...FULL, shields: 25 }) - 0.5) < 1e-9);
+    assert.equal(shieldfraction({ health: 1, maxhealth: 1, shields: 0, maxshields: 0 }), 0);
+    assert.equal(isalive(FULL), true);
+    assert.equal(isalive({ health: 0, maxhealth: 100, shields: 50, maxshields: 50 }), false);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, 0.5), 70);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, 2), 90);
+    assert.equal(effectivepool({ health: 50, maxhealth: 100, shields: 40, maxshields: 50 }, -1), 50);
+  });
+});
+
+describe("minimap transform", () => {
+  it("computes the padded bounds of a position cloud", () => {
+    assert.deepEqual(
+      minimapbounds(
+        [
+          { x: 0, z: 10 },
+          { x: 30, z: -10 },
+        ],
+        5,
+      ),
+      { minx: -5, minz: -15, maxx: 35, maxz: 15 },
+    );
+    assert.deepEqual(minimapbounds([], 5), { minx: -5, minz: -5, maxx: 5, maxz: 5 });
+  });
+
+  it("maps the world with facing up and z flipped into screen y", () => {
+    assert.deepEqual(tominimap(WIDGET, { x: 0, z: 0 }), { x: 90, y: 90, clamped: false });
+    assert.deepEqual(tominimap(WIDGET, { x: 0, z: 40 }), { x: 90, y: 18, clamped: false });
+    assert.deepEqual(tominimap(WIDGET, { x: 40, z: 0 }), { x: 162, y: 90, clamped: false });
+  });
+
+  it("rotates the world by the receiver yaw", () => {
+    const rotated = minimapconfig(WIDGET.bounds, WIDGET.sizepx, Math.PI / 2, WIDGET.padding);
+    assert.deepEqual(tominimap(rotated, { x: 40, z: 0 }), { x: 90, y: 18, clamped: false });
+    assert.deepEqual(tominimap(rotated, { x: 0, z: -40 }), { x: 162, y: 90, clamped: false });
+  });
+
+  it("clamps outside positions onto the rim with the flag", () => {
+    const rimmed = tominimap(WIDGET, { x: 100, z: 0 });
+    assert.equal(rimmed.x, 190);
+    assert.equal(rimmed.y, 90);
+    assert.equal(rimmed.clamped, true);
+    assert.equal(tominimap(WIDGET, { x: 10, z: 10 }).clamped, false);
+  });
+});
+
+describe("hitmarkers", () => {
+  it("ranks the kinds and exposes their windows", () => {
+    assert.equal(hitmarkerfor(true, true), "kill");
+    assert.equal(hitmarkerfor(false, true), "headshot");
+    assert.equal(hitmarkerfor(false, false), "body");
+    assert.equal(hitmarkerwindow("body"), HITWINDOWS.body);
+    assert.equal(hitmarkerwindow("headshot"), HITWINDOWS.headshot);
+    assert.equal(hitmarkerwindow("kill"), HITWINDOWS.kill);
+  });
+
+  it("keeps only the markers still inside their window", () => {
+    const markers: Hitmarker[] = [
+      { id: "m1", at: 0, kind: "body" },
+      { id: "m2", at: 100, kind: "headshot" },
+      { id: "m3", at: 300, kind: "kill" },
+    ];
+    assert.deepEqual(
+      activehitmarkers(markers, 400).map((marker) => marker.id),
+      ["m2", "m3"],
+    );
+    assert.equal(activehitmarkers(markers, 900).length, 0);
+    assert.equal(pushhitmarker(markers, { id: "m4", at: 500, kind: "body" }).length, 4);
+  });
+});
+
+describe("killfeed", () => {
+  it("dedups by id and caps the feed", () => {
+    const feed = pushkillfeed([], kill("k1", 100));
+    const refreshed = pushkillfeed(feed, { ...kill("k1", 150), victim: "tide-3" });
+    assert.equal(refreshed.length, 1);
+    assert.equal(refreshed[0].at, 150);
+    assert.equal(refreshed[0].victim, "tide-3");
+    let capped: KillfeedEntry[] = [];
+    for (let i = 0; i < 8; i++) capped = pushkillfeed(capped, kill(`k${i}`, i * 100));
+    assert.equal(capped.length, KILLFEEDCAP);
+    assert.equal(capped[0].id, "k2");
+    assert.equal(capped[capped.length - 1].id, "k7");
+  });
+
+  it("expires rows past the ttl", () => {
+    const feed = [kill("k1", 1000), kill("k2", 7000)];
+    assert.deepEqual(
+      prunekillfeed(feed, 8500, KILLFEEDTTL).map((row) => row.id),
+      ["k1", "k2"],
+    );
+    assert.deepEqual(
+      prunekillfeed(feed, 9100, KILLFEEDTTL).map((row) => row.id),
+      ["k2"],
+    );
+  });
+
+  it("renders the plain feed line with the headshot mark", () => {
+    assert.equal(killfeedline(kill("k1", 0)), "ember-1 [raven] tide-2");
+    assert.equal(killfeedline({ ...kill("k1", 0), headshot: true }), "ember-1 [raven] tide-2 ⊕");
+  });
+});
+
+describe("directional damage", () => {
+  it("points front, right, behind and left relative to the yaw", () => {
+    assert.equal(directionaldamage({ x: 0, z: 20 }, { x: 0, z: 0 }, 0).sector, "front");
+    assert.equal(directionaldamage({ x: 20, z: 0 }, { x: 0, z: 0 }, 0).sector, "right");
+    assert.equal(directionaldamage({ x: 0, z: -20 }, { x: 0, z: 0 }, 0).sector, "behind");
+    assert.equal(directionaldamage({ x: -20, z: 0 }, { x: 0, z: 0 }, 0).sector, "left");
+    const faced = directionaldamage({ x: 20, z: 0 }, { x: 0, z: 0 }, Math.PI / 2);
+    assert.equal(faced.sector, "front");
+    assert.ok(Math.abs(faced.angle) < 1e-9);
+  });
+
+  it("fades the ping strength with distance to the floor", () => {
+    assert.ok(Math.abs(directionaldamage({ x: 0, z: 20 }, { x: 0, z: 0 }, 0).strength - 0.5) < 1e-9);
+    assert.equal(directionaldamage({ x: 0, z: 200 }, { x: 0, z: 0 }, 0).strength, DAMAGESTRENGTHFLOOR);
+    assert.equal(sectorof(Math.PI), "behind");
+    assert.equal(sectorof((7 * Math.PI) / 4), "left");
+  });
+});

package/tests/matchrules.test.ts

@@ -0,0 +1,219 @@
+// # matchrules.test — honest unit tests for the match rules state machine,
+// runnable with the vitest runner:
+//   pnpm test
+// The fixtures reuse the match seed rows of the root match logic.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { MATCHPLAYERSEED, MATCHSEED, type MatchLobby } from "../match.ts";
+import {
+  addscore,
+  advancelobby,
+  canlobbytransition,
+  canroundtransition,
+  matchruleserror,
+  nextactions,
+  openround,
+  progressof,
+  scoreround,
+  seatplayers,
+  transitionlobby,
+} from "../matchrules.ts";
+
+/** finds one seeded lobby by id (the tests key on the seed rows). */
+function lobby(id: string): MatchLobby {
+  const row = MATCHSEED.find((candidate) => candidate.id === id);
+  assert.ok(row, `seed lobby ${id} missing`);
+  return row;
+}
+
+describe("match rules transitions", () => {
+  it("allows only the table transitions for lobbies", () => {
+    assert.equal(canlobbytransition("open", "live"), true);
+    assert.equal(canlobbytransition("open", "closed"), true);
+    assert.equal(canlobbytransition("live", "open"), false);
+    assert.equal(canlobbytransition("closed", "live"), false);
+    assert.equal(canlobbytransition("closed", "closed"), false);
+  });
+
+  it("allows only pending -> live -> scored for rounds", () => {
+    assert.equal(canroundtransition("pending", "live"), true);
+    assert.equal(canroundtransition("live", "scored"), true);
+    assert.equal(canroundtransition("pending", "scored"), false);
+    assert.equal(canroundtransition("scored", "live"), false);
+  });
+
+  it("moves a lobby and never mutates the input row", () => {
+    const open = lobby("m-2202");
+    const live = transitionlobby(open, "live");
+    assert.equal(live.state, "live");
+    assert.equal(open.state, "open");
+    assert.notEqual(live, open);
+  });
+
+  it("rejects a forbidden lobby transition with a typed error", () => {
+    const closed = lobby("m-2204");
+    assert.throws(
+      () => transitionlobby(closed, "live"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "bad-transition");
+        assert.equal(error.lobbyid, "m-2204");
+        assert.equal(error.from, "closed");
+        assert.equal(error.to, "live");
+        return true;
+      },
+    );
+  });
+
+  it("opens one pending round of a live lobby", () => {
+    const seeded = lobby("m-2202");
+    const live = transitionlobby(seeded, "live");
+    const running = openround(live, "r-4");
+    assert.equal(running.rounds.find((row) => row.id === "r-4")?.state, "live");
+  });
+
+  it("refuses to open a round while another runs or the lobby is not live", () => {
+    const m2201 = lobby("m-2201");
+    assert.throws(() => openround(m2201, "r-3"), matchruleserror);
+    const live = transitionlobby(lobby("m-2202"), "live");
+    const running = openround(live, "r-4");
+    assert.throws(
+      () => openround(running, "r-5"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "bad-transition");
+        return true;
+      },
+    );
+    assert.throws(() => openround(transitionlobby(lobby("m-2202"), "closed"), "r-4"), matchruleserror);
+  });
+
+  it("rejects an unknown round with the unknown-round code", () => {
+    const live = transitionlobby(lobby("m-2202"), "live");
+    assert.throws(
+      () => openround(live, "r-404"),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "unknown-round");
+        return true;
+      },
+    );
+  });
+
+  it("scores the live round and the scored table rows stay scoreable by id", () => {
+    const live = transitionlobby(lobby("m-2202"), "live");
+    const running = openround(live, "r-4");
+    const done = scoreround(running);
+    assert.equal(done.rounds.find((row) => row.id === "r-4")?.state, "scored");
+    const reopened = openround(done, "r-5");
+    const scored = scoreround(reopened, "r-5");
+    assert.equal(scored.rounds.find((row) => row.id === "r-5")?.state, "scored");
+  });
+});
+
+describe("match rules capacity and scoring", () => {
+  it("seats players while the capacity holds and refuses overflow", () => {
+    const seated = lobby("m-2202");
+    const ok = seatplayers(
+      seated,
+      MATCHPLAYERSEED.filter((player) => player.lobbyid === "m-2202"),
+    );
+    assert.equal(ok.length, 2);
+    const overflow = [
+      ...MATCHPLAYERSEED,
+      { id: "p-99", lobbyid: "m-2202", handle: "overflow.seat", squad: "ash", score: 0, ping: 60 },
+    ];
+    assert.throws(
+      () => seatplayers(seated, overflow),
+      (error: unknown) => {
+        assert.ok(error instanceof matchruleserror);
+        assert.equal(error.code, "lobby-full");
+        return true;
+      },
+    );
+  });
+
+  it("adds score, floors penalties at zero and refuses non finite deltas", () => {
+    const seat = MATCHPLAYERSEED[0];
+    assert.equal(addscore(seat, 120).score, seat.score + 120);
+    assert.equal(addscore({ ...seat, score: 40 }, -90).score, 0);
+    assert.throws(() => addscore(seat, Number.NaN), matchruleserror);
+  });
+});
+
+describe("match rules tick simulator", () => {
+  it("opens an open lobby on the first tick", () => {
+    const result = advancelobby(lobby("m-2202"), 0, { roundbudgetseconds: 300, autoadvance: false });
+    assert.equal(result.lobby.state, "live");
+    assert.deepEqual(
+      result.events.map((event) => event.kind),
+      ["lobby-live"],
+    );
+  });
+
+  it("expires a live round past its budget and autoadvances the next one", () => {
+    const seeded = lobby("m-2202");
+    const first = advancelobby(seeded, 0, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(first.lobby.rounds.find((row) => row.id === "r-4")?.state, "live");
+    const second = advancelobby(first.lobby, 301, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-4")?.state, "scored");
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-5")?.state, "live");
+    assert.ok(second.events.some((event) => event.kind === "round-expired" && event.roundid === "r-4"));
+    assert.ok(second.events.some((event) => event.kind === "round-live" && event.roundid === "r-5"));
+  });
+
+  it("closes the lobby when every round is scored", () => {
+    let current = transitionlobby(lobby("m-2202"), "live");
+    current = scoreround(openround(current, "r-4"));
+    current = scoreround(openround(current, "r-5"));
+    const ticked = advancelobby(current, 0, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(ticked.lobby.state, "closed");
+    assert.deepEqual(
+      ticked.events.map((event) => event.kind),
+      ["lobby-closed"],
+    );
+  });
+
+  it("keeps a live round inside its budget untouched", () => {
+    const seeded = lobby("m-2202");
+    const first = advancelobby(seeded, 0, { roundbudgetseconds: 300, autoadvance: true });
+    const second = advancelobby(first.lobby, 120, { roundbudgetseconds: 300, autoadvance: true });
+    assert.equal(second.lobby.state, "live");
+    assert.equal(second.lobby.rounds.find((row) => row.id === "r-4")?.state, "live");
+    assert.equal(second.events.length, 0);
+  });
+
+  it("refuses a bad clock or a bad budget", () => {
+    assert.throws(
+      () => advancelobby(lobby("m-2202"), -1, { roundbudgetseconds: 300, autoadvance: true }),
+      matchruleserror,
+    );
+    assert.throws(
+      () => advancelobby(lobby("m-2202"), 10, { roundbudgetseconds: 0, autoadvance: true }),
+      matchruleserror,
+    );
+  });
+});
+
+describe("match rules board hints", () => {
+  it("hints the board actions in lifecycle order", () => {
+    assert.deepEqual(nextactions(lobby("m-2202")), ["start the match"]);
+    assert.deepEqual(nextactions(lobby("m-2201")), ["score the live round"]);
+    assert.deepEqual(nextactions(lobby("m-2204")), []);
+  });
+
+  it("hints the close action for a live lobby with everything scored", () => {
+    const allscored: MatchLobby = {
+      ...lobby("m-2202"),
+      state: "live",
+      rounds: lobby("m-2202").rounds.map((row) => ({ ...row, state: "scored" })),
+    };
+    assert.deepEqual(nextactions(allscored), ["close the lobby"]);
+  });
+
+  it("measures the scored progress of a lobby", () => {
+    assert.equal(progressof(lobby("m-2201")), 33);
+    assert.equal(progressof(lobby("m-2204")), 100);
+    assert.equal(progressof({ ...lobby("m-2203"), rounds: [] }), 0);
+  });
+});

package/tests/netcode.test.ts

@@ -0,0 +1,251 @@
+// # netcode.test — honest unit tests for the deterministic netcode layer
+// (deltas, interpolation, reconciliation, rewind, jitter), runnable with
+// the vitest runner:
+//   pnpm test
+// Every case feeds plain snapshots and commands and checks exact output —
+// no sockets, no mocks, no timing, no randomness.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  applydelta,
+  bracketpair,
+  CMDSPEED,
+  DEFAULTINTERPDELAY,
+  duepackets,
+  type EntityState,
+  entityattick,
+  interpolateat,
+  jitterof,
+  latestsnapshot,
+  lerpentity,
+  makedelta,
+  makejitterbuffer,
+  needsreconcile,
+  positionerror,
+  pushpacket,
+  pushrewind,
+  RECONCILETHRESHOLD,
+  reconcile,
+  replaycmds,
+  rewindattick,
+  type Snapshot,
+  simulatecmd,
+  wrapangle,
+  yawlerp,
+} from "../netcode.ts";
+
+/** one entity standing at a spot. */
+function entityat(id: string, px: number, tick: number, yaw = 0): EntityState {
+  return { id, tick, px, py: 0, pz: 0, yaw };
+}
+
+/** one snapshot from id/px pairs. */
+function snapshot(tick: number, time: number, rows: Array<[string, number]>): Snapshot {
+  return { tick, time, entities: rows.map(([id, px]) => entityat(id, px, tick)) };
+}
+
+describe("angles", () => {
+  it("wraps angles into [0, 2π)", () => {
+    assert.ok(Math.abs(wrapangle(-0.1) - (Math.PI * 2 - 0.1)) < 1e-9);
+    assert.ok(Math.abs(wrapangle(Math.PI * 5) - Math.PI) < 1e-9);
+    assert.equal(wrapangle(0), 0);
+  });
+
+  it("interpolates yaw by the shortest arc", () => {
+    assert.ok(Math.abs(yawlerp(0, Math.PI / 2, 0.5) - Math.PI / 4) < 1e-9);
+    assert.ok(Math.abs(yawlerp(3, -3, 0.5) - Math.PI) < 1e-9);
+    assert.ok(Math.abs(yawlerp(1, 1, 0.9) - 1) < 1e-9);
+  });
+});
+
+describe("snapshot deltas", () => {
+  it("carries only movers, spawns and despawns", () => {
+    const base = snapshot(1, 10, [
+      ["a", 0],
+      ["b", 5],
+      ["gone", 9],
+    ]);
+    const next = snapshot(2, 20, [
+      ["a", 4],
+      ["b", 5],
+      ["new", 1],
+    ]);
+    const delta = makedelta(base, next);
+    assert.equal(delta.base, 1);
+    assert.deepEqual(delta.changed.map((entity) => entity.id).sort(), ["a", "new"]);
+    assert.deepEqual(delta.removed, ["gone"]);
+  });
+
+  it("rebuilds the full snapshot from base plus delta", () => {
+    const base = snapshot(1, 10, [
+      ["a", 0],
+      ["gone", 9],
+    ]);
+    const next = snapshot(2, 20, [
+      ["a", 4],
+      ["new", 1],
+    ]);
+    const rebuilt = applydelta(base, makedelta(base, next));
+    assert.equal(rebuilt.tick, 2);
+    assert.deepEqual(rebuilt.entities.map((entity) => entity.id).sort(), ["a", "new"]);
+    assert.equal(rebuilt.entities.find((entity) => entity.id === "a")?.px, 4);
+  });
+
+  it("answers the newest snapshot by tick", () => {
+    const stream = [snapshot(1, 0, []), snapshot(3, 20, []), snapshot(2, 10, [])];
+    assert.equal(latestsnapshot(stream)?.tick, 3);
+    assert.equal(latestsnapshot([]), null);
+  });
+});
+
+describe("entity interpolation", () => {
+  it("brackets the render time without extrapolating", () => {
+    const stream = [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])];
+    assert.deepEqual(
+      bracketpair(stream, 50)?.map((snap) => snap.tick),
+      [1, 2],
+    );
+    assert.equal(bracketpair(stream, 150), null);
+    assert.equal(bracketpair(stream, -1), null);
+  });
+
+  it("interpolates positions and yaw at the fraction", () => {
+    const stream = [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])];
+    const state = interpolateat(stream, 50).find((entity) => entity.id === "a");
+    assert.equal(state?.px, 5);
+    const turn = interpolateat(
+      [snapshot(1, 0, [["a", 0]]), snapshot(2, 100, [["a", 10]])].map((snap, i) => ({
+        ...snap,
+        entities: snap.entities.map((entity) => ({ ...entity, yaw: i === 0 ? 0 : Math.PI })),
+      })),
+      50,
+    );
+    assert.ok(Math.abs((turn.find((entity) => entity.id === "a")?.yaw ?? 0) - Math.PI / 2) < 1e-9);
+  });
+
+  it("spawns newer-only entities and drops older-only ones", () => {
+    const stream = [
+      snapshot(1, 0, [
+        ["a", 0],
+        ["dead", 9],
+      ]),
+      snapshot(2, 100, [
+        ["a", 10],
+        ["born", 3],
+      ]),
+    ];
+    const states = interpolateat(stream, 50);
+    assert.deepEqual(states.map((entity) => entity.id).sort(), ["a", "born"]);
+    assert.equal(states.find((entity) => entity.id === "born")?.px, 3);
+  });
+
+  it("lerps one entity directly", () => {
+    const out = lerpentity(entityat("a", 0, 1, 0), { ...entityat("a", 10, 2, Math.PI), py: 4 }, 0.25);
+    assert.equal(out.px, 2.5);
+    assert.equal(out.py, 1);
+    assert.ok(Math.abs(out.yaw - Math.PI / 4) < 1e-9);
+  });
+});
+
+describe("prediction and reconciliation", () => {
+  it("advances the entity with the shared movement math", () => {
+    const walked = simulatecmd(entityat("a", 0, 1), { seq: 1, forward: 1, side: 0, yaw: 0, dt: 0.5 });
+    assert.equal(walked.px, CMDSPEED * 0.5);
+    assert.equal(walked.tick, 2);
+    const sideways = simulatecmd(entityat("a", 0, 1), { seq: 2, forward: 0, side: 1, yaw: 0, dt: 1 });
+    assert.equal(sideways.pz, -CMDSPEED);
+    const turned = simulatecmd(entityat("a", 0, 1), { seq: 3, forward: 1, side: 0, yaw: Math.PI / 2, dt: 1 });
+    assert.ok(Math.abs(turned.pz - CMDSPEED) < 1e-9);
+    assert.equal(turned.yaw, Math.PI / 2);
+  });
+
+  it("replays command lists in order", () => {
+    const cmds = [
+      { seq: 1, forward: 1, side: 0, yaw: 0, dt: 1 },
+      { seq: 2, forward: 1, side: 0, yaw: 0, dt: 1 },
+    ];
+    assert.equal(replaycmds(entityat("a", 0, 1), cmds).px, 2 * CMDSPEED);
+    assert.equal(replaycmds(entityat("a", 0, 1), []).px, 0);
+  });
+
+  it("reconciles only above the drift threshold", () => {
+    const server = entityat("a", 3, 5);
+    const pending = [{ seq: 1, forward: 1, side: 0, yaw: 0, dt: 0.5 }];
+    const drifted = reconcile(entityat("a", 10, 7), server, pending, RECONCILETHRESHOLD);
+    assert.ok(drifted.error > RECONCILETHRESHOLD);
+    assert.equal(drifted.replayed.length, 1);
+    assert.equal(drifted.state.px, 3 + CMDSPEED * 0.5);
+    const close = reconcile(entityat("a", 3, 5), server, pending, RECONCILETHRESHOLD);
+    assert.equal(close.replayed.length, 0);
+    assert.equal(close.state.px, 3);
+    assert.equal(needsreconcile(entityat("a", 3.05, 5), server, RECONCILETHRESHOLD), false);
+    assert.equal(needsreconcile(entityat("a", 3.2, 5), server, RECONCILETHRESHOLD), true);
+    assert.ok(Math.abs(positionerror({ ...entityat("a", 3, 5), pz: 4 }, server) - 4) < 1e-9);
+  });
+});
+
+describe("lag compensation rewind", () => {
+  it("keeps the history ordered and capped to the newest frames", () => {
+    let buffer = { frames: [] as Snapshot[], capacity: 2 };
+    for (const tick of [10, 20, 30]) buffer = pushrewind(buffer, snapshot(tick, tick * 10, [["a", tick]]));
+    assert.deepEqual(
+      buffer.frames.map((frame) => frame.tick),
+      [20, 30],
+    );
+    buffer = pushrewind(buffer, snapshot(20, 200, [["a", 20]]));
+    assert.deepEqual(
+      buffer.frames.map((frame) => frame.tick),
+      [20, 30],
+    );
+  });
+
+  it("rewinds to the newest frame at or before the tick", () => {
+    let buffer = { frames: [] as Snapshot[], capacity: 8 };
+    for (const tick of [10, 20, 30]) buffer = pushrewind(buffer, snapshot(tick, tick * 10, [["a", tick]]));
+    assert.equal(rewindattick(buffer, 25)?.tick, 20);
+    assert.equal(rewindattick(buffer, 30)?.tick, 30);
+    assert.equal(rewindattick(buffer, 5), null);
+    assert.equal(entityattick(buffer, 25, "a")?.px, 20);
+    assert.equal(entityattick(buffer, 25, "ghost"), null);
+  });
+});
+
+describe("jitter buffer", () => {
+  it("measures the arrival jitter of the stream", () => {
+    assert.equal(jitterof([0, 20, 45, 70]), 2.5);
+    assert.equal(jitterof([0, 10]), 0);
+    assert.equal(jitterof([5]), 0);
+    assert.equal(jitterof([]), 0);
+  });
+
+  it("orders, dedupes and caps the playout queue", () => {
+    let buffer = makejitterbuffer(2, DEFAULTINTERPDELAY);
+    buffer = pushpacket(buffer, { tick: 2, arrivedat: 20 });
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 10 });
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 11 });
+    assert.deepEqual(
+      buffer.packets.map((packet) => packet.tick),
+      [1, 2],
+    );
+    buffer = pushpacket(buffer, { tick: 3, arrivedat: 30 });
+    assert.deepEqual(
+      buffer.packets.map((packet) => packet.tick),
+      [2, 3],
+    );
+  });
+
+  it("drains only the packets whose playout delay elapsed", () => {
+    let buffer = makejitterbuffer(8, 50);
+    buffer = pushpacket(buffer, { tick: 1, arrivedat: 0 });
+    buffer = pushpacket(buffer, { tick: 2, arrivedat: 40 });
+    assert.deepEqual(
+      duepackets(buffer, 60).map((packet) => packet.tick),
+      [1],
+    );
+    assert.deepEqual(
+      duepackets(buffer, 100).map((packet) => packet.tick),
+      [1, 2],
+    );
+    assert.deepEqual(duepackets(buffer, 10), []);
+  });
+});