@modelstatus/cli 0.1.35 → 0.1.37

package/src/tui/game/dk-core.js

@@ -1,39 +1,113 @@
-/* Donkey Kong — PURE game core. NO React, NO ink, NO Math.random, NO I/O.
+/* Donkey Kong — PURE game engine. NO React, NO ink, NO Math.random, NO Date.now,
+ * NO I/O. The single source of game truth, unit-tested in isolation.
  *
- * This is a small, deterministic state machine: initGame(opts) builds a board
+ * This is a deterministic discrete map. initGame(opts) builds a board
  * procedurally from the terminal's width/height (so it scales + can refuse a
- * too-small terminal), and stepGame(state, { input }) advances exactly one
- * frame. All randomness flows through a seeded mulberry32 RNG carried in the
- * state, so unit tests pass a fixed seed and assert exact barrel paths /
- * collisions. The renderer (dk-render.js) and the Ink wrapper (DkGame.js) never
- * mutate state — they only read it — keeping this file the single source of
- * game truth and trivially unit-testable.
+ * too-small terminal). stepGame(prev, { input, dt }) advances exactly one tick
+ * (1/60s) and returns a NEW state. All randomness flows through a seeded
+ * mulberry32 RNG carried in the state, so unit tests pass a fixed seed and
+ * assert EXACT positions, barrel paths and collisions — and two runtimes (node
+ * and the bun-compiled binary) produce byte-identical state.
  *
- * Coordinate system: integer grid. x = column (0 = left), y = row (0 = TOP).
- * "Up" decreases y. Girders ("platforms") are horizontal-ish rows that drift
- * (classic DK zig-zag); ladders are vertical runs linking adjacent girders. */
+ * === WHY A REWRITE (sub-cell fixed-point) ===
+ * The old core stepped a single integer cell per 100ms frame and jumped a
+ * 4-frame triangle. That coarse 10fps single-cell grid is the "stiffness". This
+ * engine runs true 60Hz with SUB-CELL fixed-point positions so the player
+ * accelerates/slides across girders and the jump is a readable parabolic arc.
+ *
+ * === COORDINATE / FIXED-POINT MODEL ===
+ * Public grid stays INTEGER: x = column (0 = left), y = row (0 = TOP), up = -y.
+ * Girders/ladders/DK/princess and the RENDERER all read integer cells. The
+ * renderer reads jumpman.x/y and barrels[].x/y, which we keep as integer fields
+ * SYNCED each tick from the sub-cell px/py (round-to-nearest). So dk-render.js
+ * is unchanged in contract.
+ *
+ * Internally the player + barrels carry Int32 fixed-point position/velocity in
+ * units of 1/SCALE cell (SCALE = 256, a power of two → exact, no float drift
+ * across machines/runtimes). The render cell is round-to-nearest: (fx+128)>>8.
+ * Integer fixed-point with >>/* is bit-identical under V8 and JSC; that is the
+ * determinism guarantee the tests assert.
+ */
+
+// ---- Fixed-point helpers ---------------------------------------------------
+export const SCALE = 256; // 1 cell = 256 fixed-point units (power of two → exact)
+export const toFx = (n) => (n * SCALE) | 0; // integer cell -> fx
+export const cell = (fx) => (fx + (SCALE >> 1)) >> 8; // fx -> round-to-nearest cell
+export const floorCell = (fx) => fx >> 8; // fx -> floor cell (>> on Int32 = floor for our range)
+const clampFx = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+
+// ---- Tunables (per 1/60s tick unless noted) --------------------------------
+export const TICK_HZ = 60;
+export const FIXED_DT = 1; // the loop ALWAYS steps with dt=1 (true fixed timestep)
+// Legacy alias so old imports of FRAME_MS keep working (now = one 60Hz tick).
+export const FRAME_MS = 1000 / TICK_HZ;
+export const JUMP_LEN = 4; // legacy export (old triangle length); unused by physics
 
-// ---- Tunables --------------------------------------------------------------
-export const FRAME_MS = 100; // 10fps game loop (the wrapper gates this on useTick)
-export const JUMP_LEN = 4; // frames a jump arc lasts
 export const MIN_W = 28; // minimum playfield width
 export const MIN_H = 9; // minimum playfield height
-const GRAVITY = 1; // rows/frame fallen when unsupported
+
+// Player horizontal
+export const RUN_ACCEL = 22; // fx/tick (ramps to top speed in ~6 ticks ≈ 100ms)
+export const RUN_MAX = 130; // fx/tick (~0.5 cell/tick → brisk but readable)
+export const GROUND_FRICTION = 30; // fx/tick decel when no input (the "slide")
+export const AIR_ACCEL = 14; // weaker air-control
+export const AIR_MAX = 130;
+
+// Gravity / jump
+export const GRAVITY = 14; // fx/tick added to vy while airborne (full jump → apex ≈ 3 cells)
+export const JUMP_CUT_GRAVITY = 42; // stronger gravity while RISING after release → short hop (~1.5 cells)
+export const TERMINAL_VY = 220; // fx/tick max fall speed
+export const JUMP_VY = -150; // initial up-velocity → apex ≈ 3 cells, hang ≈ 21 ticks
+export const COYOTE_TICKS = 5; // jump still allowed N ticks after walking off
+export const JUMP_BUFFER_TICKS = 6; // a press N ticks before landing still fires on land
+
+// Ladder
+export const CLIMB_SPEED = 70; // fx/tick (gravity suspended while latched)
+
+// Barrels
+export const BARREL_ROLL = 95; // fx/tick base roll speed
+export const MAX_BARRELS = 24; // hard cap (oldest despawns) — bounded state growth
+
+// Geometry / scoring
 const SLOPE_EVERY = 6; // a 1-row step every ~6 columns on a girder
 const PRINCESS_REACH = 2; // |dx| within which touching the princess wins
 
-/** DK barrel-throw cadence by level: faster (shorter cooldown) as you climb. */
+// State-machine timers (ticks)
+export const GETREADY_TICKS = 90; // ≈1.5s orient beat
+export const DEATH_TICKS = 60; // death-pop / pause before respawn
+export const LEVELCLEAR_TICKS = 120; // banner + bonus count-up
+export const RESPAWN_INVULN = 120; // ≈2s of blink after a respawn
+
+// Bonus timer
+export const BONUS_DRAIN = 10; // points removed each drain
+export const BONUS_TICK = 24; // drain every 24 ticks (~0.4s)
+export function bonusForLevel(level) {
+  return 5000 + level * 1000;
+}
+
+const SCHEMA = 2;
+
+// ---- Level scaling (pure, tested monotonic) --------------------------------
+/** DK barrel-throw cadence in TICKS — faster (shorter) as you climb. */
 export function cooldownForLevel(level) {
-  return Math.max(7, 22 - (level - 1) * 3);
+  return Math.max(45, 132 - (level - 1) * 18);
 }
-/** Probability (0..1) a rolling barrel takes a ladder down; rises with level. */
+/** Barrel roll speed (fx/tick) — faster each level. */
+export function barrelSpeedForLevel(level) {
+  return Math.min(170, BARREL_ROLL + (level - 1) * 12);
+}
+/** Probability a rolling barrel takes a ladder down per eligibility check. */
 export function ladderChanceForLevel(level) {
   return Math.min(0.6, 0.18 + (level - 1) * 0.1);
 }
+/** By construction the jump apex (~3 cells) clears a 1-cell barrel + player at
+ * every level — exposed so a test can assert the invariant numerically. */
+export function jumpClearsBarrel(/* level */) {
+  const apexCells = (JUMP_VY * JUMP_VY) / (2 * GRAVITY) / SCALE; // ≈ 3.14
+  return apexCells > 2; // barrel(1) + player(1) with margin
+}
 
 // ---- Seeded RNG (mulberry32) — pure, threaded through state ----------------
-// Returns [value in [0,1), nextSeed] so the core never holds hidden mutable
-// state; stepGame folds the new seed back into the returned state.
 function rng(seed) {
   let t = (seed + 0x6d2b79f5) | 0;
   t = Math.imul(t ^ (t >>> 15), t | 1);
@@ -42,20 +116,15 @@ function rng(seed) {
   return [v, t >>> 0];
 }
 
-// ---- Board geometry --------------------------------------------------------
+// ---- Board geometry (KEPT from the old core — integer grid, good) ----------
 export function boardSize(width, height) {
-  const HUD_ROWS = 2; // scan-progress line + score/lives line (rendered by wrapper)
-  const KEY_ROW = 1; // in-game keybar (rendered by wrapper)
-  const BOARD_W = Math.max(MIN_W, Math.min(width - 2, 64)); // 1-col rail gutter each side
-  const BOARD_H = height - HUD_ROWS - KEY_ROW; // identical total rows to the list view
+  const HUD_ROWS = 2; // scan-progress line + score/lives line (rendered by loop)
+  const KEY_ROW = 1; // in-game keybar (rendered by loop)
+  const BOARD_W = Math.max(MIN_W, Math.min(width - 2, 64));
+  const BOARD_H = height - HUD_ROWS - KEY_ROW;
   return { BOARD_W, BOARD_H };
 }
 
-/** Build the per-column y of one girder: a base row that steps 1 cell every
- * SLOPE_EVERY columns, alternating drift direction per level (classic zig-zag),
- * bounded to a `±amp` envelope around baseRow so adjacent girders never overlap
- * and none drifts off the board. Returned as an Int array of length BOARD_W so
- * collision/standing math reads the exact row a girder occupies at any column. */
 function buildSlope(baseRow, w, down, amp) {
   const offs = new Array(w);
   for (let x = 0; x < w; x++) {
@@ -66,8 +135,7 @@ function buildSlope(baseRow, w, down, amp) {
   return offs;
 }
 
-/** The girder index whose standing row is at-or-just-below y at column x, i.e.
- * the platform a body at (x,y) would land on when falling. Returns -1 if none. */
+/** Girder index whose standing row is at-or-just-below row y at column x. */
 function girderBelow(platforms, x, y) {
   let best = -1, bestRow = Infinity;
   for (let i = 0; i < platforms.length; i++) {
@@ -83,92 +151,90 @@ function isGirderAt(platforms, x, y) {
   return false;
 }
 
+/** The platform index whose girder row is exactly `y` at column `x`, or -1. */
+function girderIndexAt(platforms, x, y) {
+  for (let i = 0; i < platforms.length; i++) if (platforms[i].slopeOffsets[x] === y) return i;
+  return -1;
+}
+
 /** The ladder occupying column x within [yTop..yBottom] at row y, or null. */
 function ladderAt(ladders, x, y) {
   for (const l of ladders) if (l.col === x && y >= l.yTop && y <= l.yBottom) return l;
   return null;
 }
 
-/** Inclusive "is `v` between `a` and `b`" regardless of order — for swept hit
- * tests (the moving body crossed cell v this frame). */
+/** Inclusive "is v between a and b" regardless of order — swept hit test. */
 function between(v, a, b) {
   return v >= Math.min(a, b) && v <= Math.max(a, b);
 }
 
 // ---- initGame --------------------------------------------------------------
 /**
- * Build a fresh level. Carries score/lives across level-ups. Returns
- * { tooSmall:true } (and nothing else) when the terminal can't host a playable
- * board, so the wrapper can refuse to enter game mode without ever ticking.
+ * Build a fresh game. Carries score/lives/best across level-ups. Returns
+ * { tooSmall:true } when the terminal can't host a playable board so the loop
+ * can refuse to enter without ever ticking.
+ *
+ * status starts at 'getready' (a brief orient beat) — the loop can set 'title'
+ * for the cold-start title card; both are valid entry states.
  */
-export function initGame({ width = 80, height = 14, level = 1, score = 0, lives = 3, seed } = {}) {
+export function initGame({
+  width = 80, height = 14, level = 1, score = 0, lives = 3, best = 0, seed,
+  status = "getready",
+} = {}) {
   const { BOARD_W, BOARD_H } = boardSize(width, height);
   if (BOARD_W < MIN_W || BOARD_H < MIN_H) return { tooSmall: true, BOARD_W, BOARD_H };
 
-  // Lay out N girders evenly across the height. Highest girder (index 0) sits
-  // near the top (DK + princess); lowest (last) near the bottom (Jumpman start).
   const N = Math.max(4, Math.min(5, Math.floor(BOARD_H / 3)));
-  const gap = Math.floor((BOARD_H - 2) / N); // rows between girder bands
-  // Slope amplitude must stay strictly inside the gap so neighboring girders
-  // never overlap (which would break standing/collision math) and the lowest
-  // girder's lowest column stays on-board. ±1 is plenty of zig-zag at our sizes.
+  const gap = Math.floor((BOARD_H - 2) / N);
   const amp = Math.max(0, Math.min(2, Math.floor((gap - 1) / 2)));
   const platforms = [];
   for (let i = 0; i < N; i++) {
-    // Reserve `amp` rows of headroom at the bottom so the down-sloped lowest
-    // girder can't exceed BOARD_H - 1.
     const baseRow = BOARD_H - 2 - amp - i * gap; // 0 = bottom-most girder
-    const down = i % 2 === 0; // alternate slope direction per level band
+    const down = i % 2 === 0;
     platforms.push({ row: baseRow, slopeOffsets: buildSlope(baseRow, BOARD_W, down, amp) });
   }
   // platforms[0] is the LOWEST (largest row); platforms[N-1] the HIGHEST.
 
-  // Ladders: 1 per gap, at a staggered column, linking the STANDING ROW of the
-  // lower girder (girderRow - 1) to the standing row of the upper girder, so a
-  // climber moves directly between the two walkable rows. yTop < yBottom.
   const ladders = [];
   for (let i = 0; i < N - 1; i++) {
     const lower = platforms[i];
     const upper = platforms[i + 1];
     const col = Math.max(2, Math.min(BOARD_W - 3, Math.floor(((i + 1) / N) * BOARD_W) + (i % 2 ? -3 : 3)));
-    const yBottom = lower.slopeOffsets[col] - 1; // stand on the lower girder
-    const yTop = upper.slopeOffsets[col] - 1; // stand on the upper girder
+    const yBottom = lower.slopeOffsets[col] - 1;
+    const yTop = upper.slopeOffsets[col] - 1;
     ladders.push({ col, yTop: Math.min(yTop, yBottom), yBottom: Math.max(yTop, yBottom) });
   }
 
   const top = platforms[N - 1];
   const dkCol = 2;
-  const donkeyKong = { x: dkCol, y: top.slopeOffsets[dkCol] - 1, throwCooldown: 2 };
-  // Princess one row above DK's girder, near top-center (the goal zone).
+  const donkeyKong = { x: dkCol, y: top.slopeOffsets[dkCol] - 1, throwCooldown: 2, animPhase: 0 };
   const princessCol = Math.floor(BOARD_W / 2);
-  const princess = { x: princessCol, y: top.slopeOffsets[princessCol] - 1 };
+  const princess = { x: princessCol, y: top.slopeOffsets[princessCol] - 1, animPhase: 0 };
 
-  const bottom = platforms[0];
-  const startCol = 2;
-  const jumpman = {
-    x: startCol,
-    y: bottom.slopeOffsets[startCol] - 1, // stand ON the lowest girder
-    vy: 0,
-    onGround: true,
-    onLadder: false,
-    facing: 1,
-    jumpFrames: 0,
-    alive: true,
-  };
+  const player = makePlayer(platforms);
 
   return {
+    schema: SCHEMA,
     BOARD_W,
     BOARD_H,
     platforms,
     ladders,
-    jumpman,
+    player,
+    // `jumpman` is a same-object alias of `player` so dk-render.js (which reads
+    // state.jumpman.x/y) stays unchanged in contract. Re-pointed after each clone.
+    jumpman: player,
     donkeyKong,
     princess,
     barrels: [],
+    // --- meta / state machine ---
+    status, // title | getready | playing | dying | levelclear | over
+    statusTimer: status === "getready" ? GETREADY_TICKS : 0,
     score,
     lives,
     level,
-    status: "playing", // playing | won | dead | over
+    bonus: bonusForLevel(level),
+    bonusDrainTick: 0,
+    best: Math.max(best, score) >>> 0,
     rngSeed: (seed == null ? 1234567 + level * 99991 : seed) >>> 0,
     frame: 0,
     message: level > 1 ? `level ${level}` : "",
@@ -176,221 +242,418 @@ export function initGame({ width = 80, height = 14, level = 1, score = 0, lives
   };
 }
 
-// ---- respawn (after a death, board/barrels keep going) ---------------------
-function respawnJumpman(state) {
-  const bottom = state.platforms[0];
+/** Fresh player standing on the lowest girder at the start column. */
+function makePlayer(platforms, invuln = 0) {
+  const bottom = platforms[0];
   const startCol = 2;
-  state.jumpman = {
-    x: startCol,
-    y: bottom.slopeOffsets[startCol] - 1,
+  const standRow = bottom.slopeOffsets[startCol] - 1;
+  return {
+    px: toFx(startCol),
+    py: toFx(standRow),
+    vx: 0,
     vy: 0,
+    facing: 1,
     onGround: true,
     onLadder: false,
-    facing: 1,
-    jumpFrames: 0,
+    jumpHeld: false,
+    coyote: 0,
+    jumpBuffer: 0,
+    invuln,
     alive: true,
+    // integer mirror read by the renderer (synced each tick)
+    x: startCol,
+    y: standRow,
   };
 }
 
+/** Sync the integer cell mirror the renderer reads from sub-cell fx. */
+function syncCell(body) {
+  body.x = cell(body.px);
+  body.y = cell(body.py);
+}
+
 // ---- stepGame --------------------------------------------------------------
 /**
- * Advance one frame. PURE: returns a NEW state (shallow-cloned then mutated on
- * the clone) so React setState(g => stepGame(g, …)) is safe. `input` is a flat
- * intent object the wrapper fills from keypresses and clears each frame:
- *   { left, right, up, down, jump } (booleans).
+ * Advance one tick. PURE: returns a NEW state. `input` is a flat intent object:
+ *   { left, right, up, down, jump, start, restart } (booleans).
+ *   `jump` is EDGE-triggered (true only on the press tick); held is derived.
+ * dt is a tick multiplier (default 1); the loop ALWAYS passes dt=1.
  */
-export function stepGame(prev, { input = {} } = {}) {
-  // Frozen states ignore gameplay input (the wrapper handles r/q out-of-band).
-  if (prev.status === "over" || prev.status === "won" || prev.tooSmall) {
-    return prev;
-  }
+export function stepGame(prev, { input = {}, dt = FIXED_DT } = {}) {
+  if (prev.tooSmall) return prev;
+  // 'over' is frozen — a hard no-op (preserves the loop-freeze contract).
+  if (prev.status === "over") return prev;
 
-  // Clone (deep-enough: entities + arrays we mutate).
+  // Clone (entities + arrays we mutate).
   const s = {
     ...prev,
-    jumpman: { ...prev.jumpman },
+    player: { ...prev.player },
     donkeyKong: { ...prev.donkeyKong },
+    princess: { ...prev.princess },
     barrels: prev.barrels.map((b) => ({ ...b })),
     frame: prev.frame + 1,
   };
-  const { platforms, ladders, BOARD_W, BOARD_H } = s;
-  let seed = s.rngSeed;
-  const rnd = () => { const [v, n] = rng(seed); seed = n; return v; };
+  s.jumpman = s.player; // keep the renderer's alias pointing at the live player
+
+  switch (s.status) {
+    case "title": return stepTitle(s, input);
+    case "getready": return stepGetReady(s, input);
+    case "playing": return stepPlaying(s, input, dt);
+    case "dying": return stepDying(s, dt);
+    case "levelclear": return stepLevelClear(s, dt);
+    default: return s;
+  }
+}
+
+// ---- transient-status steps ------------------------------------------------
+function stepTitle(s, input) {
+  s.donkeyKong.animPhase = (s.frame >> 4) & 1; // slow idle chest-beat on the title only
+  if (input.start) {
+    s.status = "getready";
+    s.statusTimer = GETREADY_TICKS;
+    s.player = makePlayer(s.platforms);
+    s.jumpman = s.player;
+    s.message = "GET READY";
+  }
+  return s;
+}
+
+function stepGetReady(s, _input) {
+  s.message = "GET READY";
+  s.statusTimer -= 1;
+  if (s.statusTimer <= 0) {
+    s.status = "playing";
+    s.statusTimer = 0;
+    s.message = s.level > 1 ? `level ${s.level}` : "";
+  }
+  return s;
+}
 
-  const jm = s.jumpman;
-  const prevX = jm.x;
-  const prevY = jm.y;
-
-  // ---- 1. Jumpman intent: horizontal move + ladder + jump ----
-  if (input.left) { jm.x = Math.max(0, jm.x - 1); jm.facing = -1; }
-  if (input.right) { jm.x = Math.min(BOARD_W - 1, jm.x + 1); jm.facing = 1; }
-
-  // Ladder logic. A ladder spans the walkable run [yTop..yBottom] where BOTH
-  // ends are standing rows (yTop = upper girder's standing row, yBottom = lower
-  // girder's). When the player's column + row sit on the run, up/down moves one
-  // row along it (gravity suspended). At yTop, up steps onto the upper girder
-  // (off the ladder); at yBottom, down is a no-op (already on the lower girder).
-  const onLad = ladderAt(ladders, jm.x, jm.y);
-  if (jm.jumpFrames === 0) {
-    if (input.up && onLad && jm.y > onLad.yTop) {
-      jm.y -= 1; jm.onGround = false;
-      jm.onLadder = jm.y > onLad.yTop; // off the ladder once on the upper girder's row
-    } else if (input.down && onLad && jm.y < onLad.yBottom) {
-      jm.y += 1; jm.onGround = false;
-      jm.onLadder = jm.y < onLad.yBottom; // off the ladder once on the lower girder's row
+function stepDying(s, _dt) {
+  // Death-pop: a small hop then fall, purely visual; barrels keep rolling.
+  const p = s.player;
+  p.vy = Math.min(p.vy + GRAVITY, TERMINAL_VY);
+  p.py = clampFx(p.py + p.vy, 0, toFx(s.BOARD_H - 1));
+  syncCell(p);
+  advanceBarrels(s, makeRnd(s)); // juice: hazards stay live during the death beat
+  s.statusTimer -= 1;
+  if (s.statusTimer <= 0) {
+    if (s.lives > 0) {
+      // respawn with invulnerability (blink window)
+      s.player = makePlayer(s.platforms, RESPAWN_INVULN);
+      s.jumpman = s.player;
+      s.status = "getready";
+      s.statusTimer = Math.floor(GETREADY_TICKS / 2);
+      s.message = "GET READY";
     } else {
-      // Standing at an endpoint counts as on the girder, not the ladder.
-      jm.onLadder = !!onLad && jm.y > onLad.yTop && jm.y < onLad.yBottom;
+      s.status = "over";
+      s.statusTimer = 0;
+      s.best = Math.max(s.best, s.score) >>> 0;
+      s.message = `GAME OVER — score ${s.score}`;
     }
   }
+  return finalize(s, s.rngSeed);
+}
+
+function stepLevelClear(s, _dt) {
+  // Count the remaining bonus up into the score over the banner (juice).
+  if (s.bonus > 0) {
+    const award = Math.min(s.bonus, 100);
+    s.bonus -= award;
+    s.score += award;
+    s.best = Math.max(s.best, s.score) >>> 0;
+  }
+  s.statusTimer -= 1;
+  if (s.statusTimer <= 0) {
+    return nextLevel(s, { width: s.BOARD_W + 2, height: s.BOARD_H + 3 });
+  }
+  return s;
+}
+
+// ---- the playing pipeline --------------------------------------------------
+function makeRnd(s) {
+  let seed = s.rngSeed;
+  const rnd = () => { const [v, n] = rng(seed); seed = n; return v; };
+  rnd.flush = () => { s.rngSeed = seed >>> 0; };
+  return rnd;
+}
+
+function stepPlaying(s, input, dt) {
+  const { platforms, ladders, BOARD_W, BOARD_H } = s;
+  const rnd = makeRnd(s);
+  const p = s.player;
+  const maxPx = toFx(BOARD_W - 1);
+  const maxPy = toFx(BOARD_H - 1);
 
-  // Jump: only from the ground (not mid-air, not on a ladder).
-  if (input.jump && jm.onGround && jm.jumpFrames === 0 && !jm.onLadder) {
-    jm.jumpFrames = JUMP_LEN;
-    jm.onGround = false;
+  // 1. LADDER LATCH ----------------------------------------------------------
+  // Latch when the player's cell sits on a ladder run and up/down is pressed.
+  const col = cell(p.px);
+  const row = cell(p.py);
+  const onLad = ladderAt(ladders, col, row);
+  // Latch when the player's cell sits on a ladder run and is pressing up/down
+  // (and isn't trying to jump). Up only latches if there's run above; down only
+  // if there's run below — so standing at an endpoint and pressing "off" doesn't
+  // glue you to the ladder.
+  // Gate on the FIXED-POINT position, not the rounded cell: once the player rounds
+  // into the top cell (cell(py)===yTop) but py hasn't yet reached the exact snap
+  // point toFx(yTop), `cell(py) > yTop` is false — the climb would stall a fraction
+  // below the girder AND the unlatch can't fire while up is held → a deadlock at
+  // the top of every ladder. Comparing px/py in fx lets the climb finish onto the
+  // girder (the step-off below snaps + unlatches). Same fix for descending.
+  const wantUp = input.up && onLad && p.py > toFx(onLad.yTop);
+  const wantDown = input.down && onLad && p.py < toFx(onLad.yBottom);
+  if ((wantUp || wantDown) && !input.jump) {
+    p.onLadder = true;
+    p.vx = 0; p.vy = 0;
+    p.px = toFx(onLad.col); // snap to the ladder column while latched
+    if (wantUp) p.py = Math.max(toFx(onLad.yTop), p.py - CLIMB_SPEED);
+    else p.py = Math.min(toFx(onLad.yBottom), p.py + CLIMB_SPEED);
+    // Reached an endpoint EXACTLY → step off onto that girder (off the ladder).
+    if (p.py <= toFx(onLad.yTop)) { p.onLadder = false; p.onGround = true; p.py = toFx(onLad.yTop); }
+    else if (p.py >= toFx(onLad.yBottom)) { p.onLadder = false; p.onGround = true; p.py = toFx(onLad.yBottom); }
+  } else if (p.onLadder) {
+    // Left the column, pressed jump, or no climb input → unlatch.
+    const stillOn = onLad && cell(p.px) === onLad.col;
+    if (!stillOn || input.jump || !(input.up || input.down)) {
+      p.onLadder = false;
+      // settle onto a girder if one is at/below this cell; else gravity takes over.
+      if (isGirderAt(platforms, cell(p.px), cell(p.py) + 1) || isGirderAt(platforms, cell(p.px), cell(p.py))) p.onGround = true;
+    }
   }
 
-  // ---- 2. Jump arc + gravity ----
-  if (jm.jumpFrames > 0) {
-    // Symmetric parabola: rise on the first half, fall on the second.
-    const half = Math.ceil(JUMP_LEN / 2);
-    if (jm.jumpFrames > half) jm.y -= 1; // going up
-    else jm.y += 1; // coming down
-    jm.jumpFrames -= 1;
-    if (jm.jumpFrames === 0) {
-      // settle onto the girder at the landing column
-      const gi = girderBelow(platforms, jm.x, jm.y);
-      if (gi >= 0) jm.y = platforms[gi].slopeOffsets[jm.x] - 1;
+  if (!p.onLadder) {
+    // 2. HORIZONTAL --------------------------------------------------------
+    const accel = p.onGround ? RUN_ACCEL : AIR_ACCEL;
+    const max = p.onGround ? RUN_MAX : AIR_MAX;
+    if (input.left && !input.right) { p.vx = Math.max(-max, p.vx - accel * dt); p.facing = -1; }
+    else if (input.right && !input.left) { p.vx = Math.min(max, p.vx + accel * dt); p.facing = 1; }
+    else if (p.onGround) {
+      // friction (the slide) — decel toward 0
+      if (p.vx > 0) p.vx = Math.max(0, p.vx - GROUND_FRICTION * dt);
+      else if (p.vx < 0) p.vx = Math.min(0, p.vx + GROUND_FRICTION * dt);
+    }
+    p.px = clampFx(p.px + p.vx * dt, 0, maxPx);
+    if (p.px === 0 || p.px === maxPx) p.vx = 0; // wall contact
+
+    // 3. JUMP --------------------------------------------------------------
+    if (p.coyote > 0) p.coyote -= 1;
+    if (p.jumpBuffer > 0) p.jumpBuffer -= 1;
+    if (input.jump) p.jumpBuffer = JUMP_BUFFER_TICKS; // buffer the press
+    const canJump = (p.onGround || p.coyote > 0);
+    if (p.jumpBuffer > 0 && canJump) {
+      p.vy = JUMP_VY;
+      p.onGround = false;
+      p.coyote = 0;
+      p.jumpBuffer = 0;
+      p.jumpHeld = true;
     }
-  } else if (!jm.onLadder) {
-    // Gravity: stand on a girder if the cell directly below is one; else fall to
-    // the nearest girder beneath us.
-    const onSomeGirder = isGirderAt(platforms, jm.x, jm.y + 1);
-    if (onSomeGirder) {
-      jm.onGround = true;
-      jm.vy = 0;
+    // Variable height: holding through the rise = full jump (~3 cells); letting
+    // go while still rising applies a stronger cut-gravity → a short hop.
+    if (!input.jump && p.vy < 0) p.jumpHeld = false;
+    if (p.vy >= 0) p.jumpHeld = false;
+
+    // 4. GRAVITY + SWEPT LANDING ------------------------------------------
+    if (!p.onGround) {
+      const rising = p.vy < 0;
+      const g = rising && !p.jumpHeld ? JUMP_CUT_GRAVITY : GRAVITY;
+      p.vy = Math.min(p.vy + g * dt, TERMINAL_VY);
+      const prevPy = p.py;
+      let nextPy = p.py + p.vy * dt;
+      const c = cell(p.px);
+      if (p.vy < 0) {
+        // Rising: bonk a girder directly overhead (can't pass up THROUGH one).
+        const headRow = cell(prevPy) - 1;
+        if (headRow >= 0 && isGirderAt(platforms, c, headRow)) {
+          // stop the rise just below the girder (stand row of THIS body unchanged)
+          p.py = toFx(cell(prevPy));
+          p.vy = 0;
+          p.jumpHeld = false;
+        } else {
+          p.py = clampFx(nextPy, 0, maxPy);
+        }
+      } else if (p.vy > 0) {
+        // Falling: land on the HIGHEST girder top crossed top-down this tick
+        // (prevPy at/above the stand row, nextPy at/below it → a real landing).
+        const y0 = Math.max(0, floorCell(prevPy));
+        const y1 = Math.min(BOARD_H - 1, floorCell(nextPy) + 1);
+        let landRow = -1;
+        for (let gy = y0; gy <= y1; gy++) {
+          if (!isGirderAt(platforms, c, gy)) continue;
+          const stand = gy - 1; // stand ON TOP of the girder
+          if (prevPy <= toFx(stand) && nextPy >= toFx(stand)) { landRow = stand; break; }
+        }
+        if (landRow >= 0) {
+          p.py = toFx(landRow);
+          p.vy = 0;
+          p.onGround = true;
+          p.jumpHeld = false;
+        } else {
+          p.py = clampFx(nextPy, 0, maxPy);
+        }
+      } else {
+        p.py = clampFx(nextPy, 0, maxPy);
+      }
     } else {
-      const gi = girderBelow(platforms, jm.x, jm.y + 1);
-      const standRow = gi >= 0 ? platforms[gi].slopeOffsets[jm.x] : -1;
-      if (standRow >= 0 && standRow - 1 > jm.y) {
-        jm.y = Math.min(jm.y + GRAVITY, standRow - 1);
-        jm.onGround = jm.y === standRow - 1;
+      // Grounded: follow the slope at the current column, detect walk-off.
+      const c = cell(p.px);
+      const gi = girderIndexAt(platforms, c, cell(p.py) + 1);
+      if (gi >= 0) {
+        p.py = toFx(platforms[gi].slopeOffsets[c] - 1); // re-snap to slope
+        p.vy = 0;
       } else {
-        jm.onGround = false;
+        // walked off the edge → coyote window, begin falling
+        p.onGround = false;
+        p.coyote = COYOTE_TICKS;
       }
     }
   }
-  // Clamp inside the board.
-  jm.y = Math.max(0, Math.min(BOARD_H - 1, jm.y));
+  syncCell(p);
 
-  // ---- 3. DK throws barrels ----
+  // 5. DK THROW --------------------------------------------------------------
   const dk = s.donkeyKong;
-  if (dk.throwCooldown > 0) {
-    dk.throwCooldown -= 1;
-  } else {
+  dk.throwCooldown -= 1;
+  if (dk.throwCooldown <= 0) {
     const top = platforms[platforms.length - 1];
+    const jitter = rnd() < 0.5 ? 0 : 1; // seeded ±1 col so barrels don't stack
+    const spawnCol = Math.min(BOARD_W - 1, dk.x + 1 + jitter);
     s.barrels.push({
-      id: s.nextBarrelId,
-      x: dk.x + 1,
-      y: top.slopeOffsets[dk.x + 1] - 1,
-      vx: 1, // roll to the right off the top girder
+      id: s.nextBarrelId++,
+      px: toFx(spawnCol),
+      py: toFx(top.slopeOffsets[spawnCol] - 1),
+      vx: barrelSpeedForLevel(s.level), // roll right
+      vy: 0,
       falling: false,
+      onLadder: false,
       scored: false,
+      spin: 0,
+      x: spawnCol,
+      y: top.slopeOffsets[spawnCol] - 1,
     });
-    s.nextBarrelId += 1;
+    if (s.barrels.length > MAX_BARRELS) s.barrels.shift(); // cap (oldest despawns)
     dk.throwCooldown = cooldownForLevel(s.level);
+    dk.animPhase ^= 1; // chest-beat juice (only on a throw)
+  }
+
+  // 6/7. BARRELS -------------------------------------------------------------
+  advanceBarrels(s, rnd);
+
+  // 8. COLLISIONS + SCORING --------------------------------------------------
+  const pCol = cell(p.px), pRow = cell(p.py);
+  for (const b of s.barrels) {
+    const bCol = cell(b.px), bRow = cell(b.py);
+    const endOn = bCol === pCol && bRow === pRow;
+    // Swept overlap using pre-move floor cells (no tunneling).
+    const bPrevCol = b._pCol ?? bCol, bPrevRow = b._pRow ?? bRow;
+    const sameRowSweep = (bRow === pRow || bPrevRow === pRow) && between(pCol, bPrevCol, bCol);
+    const sameColSweep = (bCol === pCol || bPrevCol === pCol) && between(pRow, bPrevRow, bRow);
+    const playerSweep = bRow === pRow && between(bCol, p._prevCol ?? pCol, pCol);
+    const hit = endOn || sameRowSweep || sameColSweep || playerSweep;
+    if (hit && p.invuln === 0 && p.alive) {
+      s.lives -= 1;
+      s.status = "dying";
+      s.statusTimer = DEATH_TICKS;
+      s.message = "ouch! barrel hit";
+      p.vy = -90; // death-pop kick
+      rnd.flush();
+      return finalize(s, s.rngSeed);
+    }
+    // Jump-over credit: airborne, barrel below + shares column, once per barrel.
+    const airborne = !p.onGround || p.vy !== 0;
+    if (!b.scored && airborne && (bCol === pCol || bPrevCol === pCol) && bRow > pRow) {
+      b.scored = true;
+      s.score += 10;
+      s.best = Math.max(s.best, s.score) >>> 0;
+      s.message = "+10 jumped!";
+    }
+  }
+
+  // 9. BONUS DRAIN -----------------------------------------------------------
+  s.bonusDrainTick += 1;
+  if (s.bonusDrainTick >= BONUS_TICK) {
+    s.bonusDrainTick = 0;
+    s.bonus = Math.max(0, s.bonus - BONUS_DRAIN);
+  }
+
+  // 10. WIN ------------------------------------------------------------------
+  const dxP = Math.abs(pCol - s.princess.x);
+  const dyP = Math.abs(pRow - s.princess.y);
+  if (dxP <= PRINCESS_REACH && dyP <= 1) {
+    s.status = "levelclear";
+    s.statusTimer = LEVELCLEAR_TICKS;
+    s.score += 100;
+    s.best = Math.max(s.best, s.score) >>> 0;
+    s.message = "YOU SAVED HER! +100";
+    rnd.flush();
+    return finalize(s, s.rngSeed);
   }
 
-  // ---- 4. Barrels roll / fall / descend ladders ----
+  // 11. invuln decay + record prev cells for next tick's sweep
+  if (p.invuln > 0) p.invuln -= 1;
+  p._prevCol = pCol;
+  rnd.flush();
+  return finalize(s, s.rngSeed);
+}
+
+/** Advance every barrel one tick (roll / fall / descend ladders) in fx. */
+function advanceBarrels(s, rnd) {
+  const { platforms, ladders, BOARD_W, BOARD_H } = s;
   const ladderChance = ladderChanceForLevel(s.level);
+  const maxPx = toFx(BOARD_W - 1);
   const surviving = [];
   for (const b of s.barrels) {
-    // Pre-move position, so collision (below) can catch a barrel that rolled
-    // THROUGH the player's cell in one frame, not just where it ended up.
-    b.px = b.x; b.py = b.y;
+    b._pCol = cell(b.px); b._pRow = cell(b.py); // pre-move cells for the sweep
+    b.spin = (b.spin + 1) & 0xffff;
+    const c = cell(b.px);
     if (b.falling) {
-      // Free-fall until it lands on the next girder below, then resume rolling.
-      const gi = girderBelow(platforms, b.x, b.y + 1);
-      const landRow = gi >= 0 ? platforms[gi].slopeOffsets[b.x] - 1 : Infinity;
-      if (b.y + GRAVITY >= landRow && landRow !== Infinity) {
-        b.y = landRow;
+      b.vy = Math.min((b.vy || 0) + GRAVITY, TERMINAL_VY);
+      const nextPy = b.py + b.vy;
+      const gi = girderIndexAt(platforms, c, floorCell(nextPy) + 1) >= 0
+        ? girderIndexAt(platforms, c, floorCell(nextPy) + 1)
+        : girderBelow(platforms, c, cell(b.py) + 1);
+      const landRow = gi >= 0 ? platforms[gi].slopeOffsets[c] - 1 : -1;
+      if (landRow >= 0 && nextPy >= toFx(landRow) && toFx(landRow) >= b.py - 1) {
+        b.py = toFx(landRow);
+        b.vy = 0;
         b.falling = false;
-        // continue in the same horizontal direction
+        b.onLadder = false;
       } else {
-        b.y += GRAVITY;
+        b.py = nextPy;
       }
     } else {
-      // Maybe descend a ladder it's standing over.
-      const l = ladderAt(ladders, b.x, b.y + 1);
-      if (l && rnd() < ladderChance) {
+      // On a girder: maybe descend a ladder it's over.
+      const lad = ladderAt(ladders, c, cell(b.py) + 1);
+      if (lad && rnd() < ladderChance) {
         b.falling = true;
-        b.y += GRAVITY;
+        b.onLadder = true;
+        b.px = toFx(lad.col);
+        b.vy = GRAVITY;
+        b.py = b.py + b.vy;
       } else {
-        const nx = b.x + b.vx;
-        if (nx < 0 || nx >= BOARD_W) {
-          // hit the wall: fall to the girder below and reverse
-          b.vx = -b.vx;
+        const nextPx = b.px + b.vx;
+        const nc = cell(nextPx);
+        if (nextPx < 0 || nextPx > maxPx) {
+          b.vx = -b.vx; // bounce off the wall and fall to the girder below
           b.falling = true;
-          b.y += GRAVITY;
+          b.vy = GRAVITY;
+          b.py = b.py + b.vy;
         } else {
-          // Follow the girder's slope: snap onto the girder row at the new col
-          // if there is one; otherwise it rolled off the low end → fall.
-          const giHere = (() => { for (let i = 0; i < platforms.length; i++) if (platforms[i].slopeOffsets[b.x] === b.y + 1) return i; return -1; })();
-          if (giHere >= 0) {
-            const nextRow = platforms[giHere].slopeOffsets[nx];
-            b.x = nx;
-            b.y = nextRow - 1;
+          const giHere = girderIndexAt(platforms, c, cell(b.py) + 1);
+          if (giHere >= 0 && nc >= 0 && nc < BOARD_W && platforms[giHere].slopeOffsets[nc] !== undefined) {
+            b.px = nextPx;
+            b.py = toFx(platforms[giHere].slopeOffsets[nc] - 1); // follow slope
           } else {
-            // no girder under us anymore → start falling
-            b.x = nx;
+            b.px = nextPx; // rolled off the end → fall
             b.falling = true;
-            b.y += GRAVITY;
+            b.vy = GRAVITY;
+            b.py = b.py + b.vy;
           }
         }
       }
     }
-    if (b.y < BOARD_H) surviving.push(b); // despawn below the board
+    syncCell(b);
+    if (cell(b.py) < BOARD_H) surviving.push(b); // despawn below the board
   }
   s.barrels = surviving;
-
-  // ---- 5. Collisions + jump-over scoring (swept to avoid tunneling) ----
-  for (const b of s.barrels) {
-    // Hit if the barrel ends on the player's cell, OR it rolled/fell THROUGH the
-    // player this frame (swept on both axes using the captured pre-move pos), OR
-    // the player walked into where the barrel ended up (player's x sweep).
-    const endOn = b.x === jm.x && b.y === jm.y;
-    const barrelSwept =
-      (b.py === jm.y && b.y === jm.y && between(jm.x, b.px, b.x)) || // rolled across the row
-      (b.px === jm.x && b.x === jm.x && between(jm.y, b.py, b.y)); // fell down the column
-    const playerSwept = b.y === jm.y && between(b.x, prevX, jm.x);
-    if ((endOn || barrelSwept || playerSwept) && jm.alive) {
-      s.lives -= 1;
-      s.message = "ouch! barrel hit";
-      if (s.lives <= 0) { s.status = "over"; s.message = `GAME OVER — score ${s.score}`; return finalize(s, seed); }
-      respawnJumpman(s);
-      return finalize(s, seed); // brief pause; next frame resumes
-    }
-    // Jump-over credit: while airborne (mid-jump), a barrel that is below the
-    // player and shares his column has been cleared — +10, once per barrel.
-    // Checked against the barrel's pre- OR post-move column so a fast barrel
-    // that rolled under during the same frame still earns the credit.
-    if (!b.scored && jm.jumpFrames > 0 && (b.x === jm.x || b.px === jm.x) && b.y > jm.y) {
-      b.scored = true;
-      s.score += 10;
-      s.message = "+10 jumped!";
-    }
-  }
-
-  // ---- 6. Win: reach the princess ----
-  const dxP = Math.abs(jm.x - s.princess.x);
-  const dyP = Math.abs(jm.y - s.princess.y);
-  if (dxP <= PRINCESS_REACH && dyP <= 1) {
-    s.score += 100;
-    s.status = "won";
-    s.message = "you saved her! +100";
-  }
-
-  return finalize(s, seed);
 }
 
 function finalize(s, seed) {
@@ -398,7 +661,8 @@ function finalize(s, seed) {
   return s;
 }
 
-/** Build the next level after a win, carrying score+lives. */
+// ---- nextLevel / serialize -------------------------------------------------
+/** Build the next level after a win, carrying score + lives + best. */
 export function nextLevel(state, dims) {
   return initGame({
     width: dims.width,
@@ -406,8 +670,25 @@ export function nextLevel(state, dims) {
     level: state.level + 1,
     score: state.score,
     lives: state.lives,
+    best: state.best,
+    status: "getready",
   });
 }
 
-// Expose a couple of internals for focused unit tests.
-export const _internals = { girderBelow, isGirderAt, ladderAt, rng };
+/** serialize/deserialize: the state is plain JSON already (Int32 fx + arrays).
+ * serialize drops the `jumpman` alias (it duplicates `player`); deserialize and
+ * stepGame re-point it, so round-tripping is byte-stable and compact. */
+export function serialize(state) {
+  const { jumpman, ...rest } = state; // jumpman === player; don't double-encode
+  return JSON.parse(JSON.stringify(rest));
+}
+export function deserialize(obj) {
+  obj.jumpman = obj.player; // re-establish the renderer alias
+  return obj;
+}
+
+// Expose internals for focused unit tests.
+export const _internals = {
+  girderBelow, isGirderAt, girderIndexAt, ladderAt, rng, between,
+  makePlayer, advanceBarrels, syncCell,
+};