@modelstatus/cli 0.1.34 → 0.1.36

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

@@ -0,0 +1,688 @@
+/* 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 deterministic discrete map. initGame(opts) builds a board
+ * procedurally from the terminal's width/height (so it scales + can refuse a
+ * 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.
+ *
+ * === 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
+
+export const MIN_W = 28; // minimum playfield width
+export const MIN_H = 9; // minimum playfield height
+
+// 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
+
+// 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(45, 132 - (level - 1) * 18);
+}
+/** 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 ----------------
+function rng(seed) {
+  let t = (seed + 0x6d2b79f5) | 0;
+  t = Math.imul(t ^ (t >>> 15), t | 1);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  const v = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  return [v, t >>> 0];
+}
+
+// ---- 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 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 };
+}
+
+function buildSlope(baseRow, w, down, amp) {
+  const offs = new Array(w);
+  for (let x = 0; x < w; x++) {
+    const steps = Math.floor(x / SLOPE_EVERY);
+    const off = down ? steps : -steps;
+    offs[x] = baseRow + Math.max(-amp, Math.min(amp, off));
+  }
+  return offs;
+}
+
+/** 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++) {
+    const row = platforms[i].slopeOffsets[x];
+    if (row >= y && row < bestRow) { best = i; bestRow = row; }
+  }
+  return best;
+}
+
+/** True if column x at row y is a girder cell of ANY platform. */
+function isGirderAt(platforms, x, y) {
+  for (const p of platforms) if (p.slopeOffsets[x] === y) return true;
+  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 — swept hit test. */
+function between(v, a, b) {
+  return v >= Math.min(a, b) && v <= Math.max(a, b);
+}
+
+// ---- initGame --------------------------------------------------------------
+/**
+ * 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, 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 };
+
+  const N = Math.max(4, Math.min(5, Math.floor(BOARD_H / 3)));
+  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++) {
+    const baseRow = BOARD_H - 2 - amp - i * gap; // 0 = bottom-most girder
+    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.
+
+  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;
+    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, animPhase: 0 };
+  const princessCol = Math.floor(BOARD_W / 2);
+  const princess = { x: princessCol, y: top.slopeOffsets[princessCol] - 1, animPhase: 0 };
+
+  const player = makePlayer(platforms);
+
+  return {
+    schema: SCHEMA,
+    BOARD_W,
+    BOARD_H,
+    platforms,
+    ladders,
+    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,
+    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}` : "",
+    nextBarrelId: 1,
+  };
+}
+
+/** Fresh player standing on the lowest girder at the start column. */
+function makePlayer(platforms, invuln = 0) {
+  const bottom = platforms[0];
+  const startCol = 2;
+  const standRow = bottom.slopeOffsets[startCol] - 1;
+  return {
+    px: toFx(startCol),
+    py: toFx(standRow),
+    vx: 0,
+    vy: 0,
+    facing: 1,
+    onGround: true,
+    onLadder: false,
+    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 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 = {}, 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 (entities + arrays we mutate).
+  const s = {
+    ...prev,
+    player: { ...prev.player },
+    donkeyKong: { ...prev.donkeyKong },
+    princess: { ...prev.princess },
+    barrels: prev.barrels.map((b) => ({ ...b })),
+    frame: prev.frame + 1,
+  };
+  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;
+}
+
+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 {
+      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);
+
+  // 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.
+  const wantUp = input.up && onLad && row > onLad.yTop;
+  const wantDown = input.down && onLad && row < 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;
+    }
+  }
+
+  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;
+    }
+    // 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 {
+      // 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 {
+        // walked off the edge → coyote window, begin falling
+        p.onGround = false;
+        p.coyote = COYOTE_TICKS;
+      }
+    }
+  }
+  syncCell(p);
+
+  // 5. DK THROW --------------------------------------------------------------
+  const dk = s.donkeyKong;
+  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++,
+      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,
+    });
+    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);
+  }
+
+  // 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) {
+    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) {
+      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;
+        b.onLadder = false;
+      } else {
+        b.py = nextPy;
+      }
+    } else {
+      // 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.onLadder = true;
+        b.px = toFx(lad.col);
+        b.vy = GRAVITY;
+        b.py = b.py + b.vy;
+      } else {
+        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.vy = GRAVITY;
+          b.py = b.py + b.vy;
+        } else {
+          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 {
+            b.px = nextPx; // rolled off the end → fall
+            b.falling = true;
+            b.vy = GRAVITY;
+            b.py = b.py + b.vy;
+          }
+        }
+      }
+    }
+    syncCell(b);
+    if (cell(b.py) < BOARD_H) surviving.push(b); // despawn below the board
+  }
+  s.barrels = surviving;
+}
+
+function finalize(s, seed) {
+  s.rngSeed = seed >>> 0;
+  return s;
+}
+
+// ---- nextLevel / serialize -------------------------------------------------
+/** Build the next level after a win, carrying score + lives + best. */
+export function nextLevel(state, dims) {
+  return initGame({
+    width: dims.width,
+    height: dims.height,
+    level: state.level + 1,
+    score: state.score,
+    lives: state.lives,
+    best: state.best,
+    status: "getready",
+  });
+}
+
+/** 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,
+};