@modelstatus/cli 0.1.34 → 0.1.35

package/src/tui/game/DkGame.js

@@ -0,0 +1,187 @@
+/* Donkey Kong — thin Ink wrapper. h = React.createElement (NO JSX, per ui.js).
+ *
+ * Holds the game state + a synchronously-mutated inputRef (the stale-closure-safe
+ * pattern from useSearch / scan.js refIdxRef), runs the frame loop via useTick
+ * GATED so it NEVER ticks at idle, and composes a fixed-height block:
+ *   row 0: scan-progress HUD (live scan fields → SweepBar)        }
+ *   row 1: game stats (♥ lives · score · level · best · message)  } HUD_ROWS = 2
+ *   rows 2..2+BOARD_H-1: the board (one colored <Text> per row)
+ *   last row: in-game KeyBar
+ * Total rows = BOARD_H + 3 == the terminal `height` (boardSize math), so the
+ * surrounding window chrome never jumps and Ink keeps diffing.
+ *
+ * The component owns its own useInput (gated on `active` + `gameMode`) so it is
+ * independently mountable + testable; when embedded in ScanView the wrapper
+ * simply passes `active` through and relies on ui.setCapturing to stop the
+ * global app keys leaking. The SCAN is never touched — we only READ the hook
+ * fields the design surfaces (scan.filesScanned / scan.candidates.length /
+ * scan.phase). */
+import React from "react";
+import { Box, Text, useInput } from "ink";
+import { h, C, LIGHT, GLYPH, KeyBar, SweepBar, useTick, cell, fmtNum } from "../ui.js";
+import { GAME_GLYPH, GAME_COLORS, colorize } from "./dk-render.js";
+import { initGame, stepGame, nextLevel, FRAME_MS, boardSize, MIN_W, MIN_H } from "./dk-core.js";
+
+const BG_ON = !(process.env.MM_ASCII === "1" || process.env.TERM === "dumb") && process.env.NO_COLOR == null;
+
+const GAME_KEYS = [
+  { k: "←→", label: "move" },
+  { k: "↑↓", label: "climb" },
+  { k: "spc", label: "jump" },
+  { k: "p", label: "pause" },
+  { k: "r", label: "restart" },
+  { k: "q", label: "back to scan" },
+];
+
+const freshInput = () => ({ left: false, right: false, up: false, down: false, jump: false });
+
+/**
+ * DonkeyKong overlay.
+ *  props:
+ *   - width, height: the SAME numbers ScanView gets (drive boardSize)
+ *   - scan: the useStreamingScan return (read-only — filesScanned, candidates, phase)
+ *   - ui: shell helpers ({ showToast, setCapturing, setHandlesBack })
+ *   - onExit: called when the player quits the game (q / esc / backspace)
+ *   - active: input gate (mirrors ScanView's `active`)
+ *   - level: starting level (default 1)
+ */
+export function DonkeyKong({ width = 78, height = 14, scan = {}, ui = {}, onExit = () => {}, active = true, level = 1 }) {
+  const dims = { width, height };
+  const { BOARD_W, BOARD_H } = boardSize(width, height);
+  const playable = BOARD_W >= MIN_W && BOARD_H >= MIN_H;
+
+  const [game, setGame] = React.useState(() => initGame({ ...dims, level }));
+  const [paused, setPaused] = React.useState(false);
+  const pausedRef = React.useRef(false);
+  const inputRef = React.useRef(freshInput());
+  const highRef = React.useRef(0);
+
+  // Track the running session high score (kept in a ref so it survives restarts
+  // within this mount; shown in the HUD).
+  if (game && game.score > highRef.current) highRef.current = game.score;
+
+  const scanLive = scan.phase ? scan.phase !== "done" : true;
+  // The loop NEVER ticks at idle: only while (a) the overlay is up [it's mounted
+  // = up], (b) not paused, (c) the game isn't on a terminal frozen frame, and
+  // (d) the scan is still live (or just finishing). Per the design's idle rule.
+  const playing = game && game.status === "playing";
+  const ticking = playable && active && !paused && playing && (scanLive || game.frame < 1);
+  const tick = useTick(FRAME_MS, ticking);
+
+  // One advance per frame; read + clear the synchronous input ref each tick so a
+  // keypress in the same tick is seen (and isn't applied twice).
+  React.useEffect(() => {
+    if (!ticking) return;
+    setGame((g) => {
+      const ng = stepGame(g, { input: inputRef.current });
+      return ng;
+    });
+    inputRef.current = freshInput();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [tick]);
+
+  // Auto level-up a beat after a win: hold the "you saved her" frame for ~1s,
+  // then rebuild the next level carrying score + lives.
+  React.useEffect(() => {
+    if (game && game.status === "won") {
+      const t = setTimeout(() => setGame((g) => (g.status === "won" ? nextLevel(g, dims) : g)), 1000);
+      return () => clearTimeout(t);
+    }
+    return undefined;
+  }, [game && game.status, game && game.level]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  function exit() {
+    ui.setCapturing?.(false);
+    ui.setHandlesBack?.(false);
+    onExit();
+  }
+
+  // Single input owner for the overlay. q / esc / backspace exit; r restarts;
+  // p toggles ONLY the game loop (the scan keeps running). Movement keys set the
+  // synchronous intent flags consumed next tick. Ctrl-C is NOT swallowed.
+  useInput(
+    (input, key) => {
+      if (!active) return;
+      if (key.ctrl && input === "c") return; // let the global handler exit the app
+      if (input === "q" || key.escape || key.backspace || key.delete) return exit();
+      if (input === "r") { setGame(initGame({ ...dims, level: 1 })); inputRef.current = freshInput(); return; }
+      if (input === "p") { pausedRef.current = !pausedRef.current; setPaused(pausedRef.current); return; }
+      const ir = inputRef.current;
+      if (key.leftArrow || input === "h") ir.left = true;
+      else if (key.rightArrow || input === "l") ir.right = true;
+      else if (key.upArrow || input === "k") ir.up = true;
+      else if (key.downArrow || input === "j") ir.down = true;
+      else if (input === " ") ir.jump = true;
+    },
+    { isActive: active },
+  );
+
+  // --- too-small guard: a single line, no loop, nothing animates -----------
+  if (!playable) {
+    return h(
+      Box,
+      { flexDirection: "column" },
+      h(Text, { color: "#d97706" }, "  terminal too small for the game — resize to ~30x12, q to go back"),
+    );
+  }
+
+  // ---- HUD row 1: live scan progress ----
+  const files = scan.filesScanned || 0;
+  const models = (scan.candidates && scan.candidates.length) || 0;
+  const dirs = scan.dirsSeen || 0;
+  const barW = Math.max(10, Math.min(22, BOARD_W - 28));
+  // SweepBar renders a <Box>, which can't nest inside a <Text> — so the live HUD
+  // row is a flex <Box> with the bar as a sibling of the text spans.
+  const hud1 = scanLive
+    ? h(
+        Box,
+        { flexDirection: "row" },
+        h(Text, { color: C.FG_FAINT }, "  scanning "),
+        h(SweepBar, { tick, width: barW }),
+        h(Text, { color: C.FG_DIM }, `  files ${fmtNum(files)} · models ${fmtNum(models)} · dirs ${fmtNum(dirs)}`),
+      )
+    : h(
+        Text,
+        {},
+        h(Text, { color: "#16a34a" }, `  ${GLYPH.check} scan complete`),
+        h(Text, { color: C.FG_DIM }, ` · ${fmtNum(models)} models · q to view results`),
+      );
+
+  // ---- HUD row 2: game stats + transient message ----
+  const livesStr = "♥".repeat(Math.max(0, game.lives)) || "—";
+  const statusTag =
+    game.status === "over" ? `  ${game.message} · r restart · q back`
+      : game.status === "won" ? `  ${GLYPH.spark} ${game.message}`
+      : game.message ? `  ${game.message}` : "";
+  const hud2 = h(
+    Text,
+    {},
+    h(Text, { color: LIGHT.red }, `  ${livesStr}`),
+    h(Text, { color: C.FG_DIM }, "   score "),
+    h(Text, { color: C.ACCENT, bold: true }, fmtNum(game.score)),
+    h(Text, { color: C.FG_DIM }, `   lvl ${game.level}` + (paused ? "  ⏸ paused" : "")),
+    h(Text, { color: C.FG_FAINT }, `   best ${fmtNum(Math.max(highRef.current, game.score))}`),
+    h(Text, { color: game.status === "over" ? "#dc2626" : C.FG_STRONG }, statusTag),
+  );
+
+  // ---- board: one colored <Text> per row, padded to BOARD_W ----
+  const useColor = BG_ON;
+  const spanRows = colorize(game, { glyph: GAME_GLYPH, colors: GAME_COLORS });
+  const boardNodes = spanRows.map((spans, y) =>
+    h(
+      Text,
+      { key: "b" + y, wrap: "truncate" },
+      ...(useColor
+        ? spans.map((sp, i) => h(Text, { key: i, color: sp.color }, sp.text))
+        : [h(Text, { key: 0, color: C.FG }, spans.map((sp) => sp.text).join("").slice(0, BOARD_W).padEnd(BOARD_W))]),
+    ),
+  );
+  // Defensive height pin: render EXACTLY BOARD_H board rows.
+  while (boardNodes.length < BOARD_H) boardNodes.push(h(Text, { key: "bp" + boardNodes.length, color: C.FG }, cell("", BOARD_W)));
+
+  const keybar = h(KeyBar, { keys: GAME_KEYS, width });
+
+  return h(Box, { flexDirection: "column" }, hud1, hud2, ...boardNodes.slice(0, BOARD_H), keybar);
+}
+
+export default DonkeyKong;

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

@@ -0,0 +1,413 @@
+/* Donkey Kong — PURE game core. NO React, NO ink, NO Math.random, NO I/O.
+ *
+ * This is a small, deterministic state machine: 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.
+ *
+ * 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. */
+
+// ---- 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
+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. */
+export function cooldownForLevel(level) {
+  return Math.max(7, 22 - (level - 1) * 3);
+}
+/** Probability (0..1) a rolling barrel takes a ladder down; rises with level. */
+export function ladderChanceForLevel(level) {
+  return Math.min(0.6, 0.18 + (level - 1) * 0.1);
+}
+
+// ---- 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);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  const v = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  return [v, t >>> 0];
+}
+
+// ---- Board geometry --------------------------------------------------------
+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
+  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++) {
+    const steps = Math.floor(x / SLOPE_EVERY);
+    const off = down ? steps : -steps;
+    offs[x] = baseRow + Math.max(-amp, Math.min(amp, off));
+  }
+  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. */
+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 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). */
+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.
+ */
+export function initGame({ width = 80, height = 14, level = 1, score = 0, lives = 3, seed } = {}) {
+  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 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
+    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
+    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 princessCol = Math.floor(BOARD_W / 2);
+  const princess = { x: princessCol, y: top.slopeOffsets[princessCol] - 1 };
+
+  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,
+  };
+
+  return {
+    BOARD_W,
+    BOARD_H,
+    platforms,
+    ladders,
+    jumpman,
+    donkeyKong,
+    princess,
+    barrels: [],
+    score,
+    lives,
+    level,
+    status: "playing", // playing | won | dead | over
+    rngSeed: (seed == null ? 1234567 + level * 99991 : seed) >>> 0,
+    frame: 0,
+    message: level > 1 ? `level ${level}` : "",
+    nextBarrelId: 1,
+  };
+}
+
+// ---- respawn (after a death, board/barrels keep going) ---------------------
+function respawnJumpman(state) {
+  const bottom = state.platforms[0];
+  const startCol = 2;
+  state.jumpman = {
+    x: startCol,
+    y: bottom.slopeOffsets[startCol] - 1,
+    vy: 0,
+    onGround: true,
+    onLadder: false,
+    facing: 1,
+    jumpFrames: 0,
+    alive: true,
+  };
+}
+
+// ---- 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).
+ */
+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;
+  }
+
+  // Clone (deep-enough: entities + arrays we mutate).
+  const s = {
+    ...prev,
+    jumpman: { ...prev.jumpman },
+    donkeyKong: { ...prev.donkeyKong },
+    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; };
+
+  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
+    } else {
+      // Standing at an endpoint counts as on the girder, not the ladder.
+      jm.onLadder = !!onLad && jm.y > onLad.yTop && jm.y < onLad.yBottom;
+    }
+  }
+
+  // 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;
+  }
+
+  // ---- 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;
+    }
+  } 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;
+    } 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;
+      } else {
+        jm.onGround = false;
+      }
+    }
+  }
+  // Clamp inside the board.
+  jm.y = Math.max(0, Math.min(BOARD_H - 1, jm.y));
+
+  // ---- 3. DK throws barrels ----
+  const dk = s.donkeyKong;
+  if (dk.throwCooldown > 0) {
+    dk.throwCooldown -= 1;
+  } else {
+    const top = platforms[platforms.length - 1];
+    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
+      falling: false,
+      scored: false,
+    });
+    s.nextBarrelId += 1;
+    dk.throwCooldown = cooldownForLevel(s.level);
+  }
+
+  // ---- 4. Barrels roll / fall / descend ladders ----
+  const ladderChance = ladderChanceForLevel(s.level);
+  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;
+    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.falling = false;
+        // continue in the same horizontal direction
+      } else {
+        b.y += GRAVITY;
+      }
+    } else {
+      // Maybe descend a ladder it's standing over.
+      const l = ladderAt(ladders, b.x, b.y + 1);
+      if (l && rnd() < ladderChance) {
+        b.falling = true;
+        b.y += GRAVITY;
+      } 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;
+          b.falling = true;
+          b.y += GRAVITY;
+        } 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;
+          } else {
+            // no girder under us anymore → start falling
+            b.x = nx;
+            b.falling = true;
+            b.y += GRAVITY;
+          }
+        }
+      }
+    }
+    if (b.y < 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) {
+  s.rngSeed = seed >>> 0;
+  return s;
+}
+
+/** Build the next level after a win, carrying score+lives. */
+export function nextLevel(state, dims) {
+  return initGame({
+    width: dims.width,
+    height: dims.height,
+    level: state.level + 1,
+    score: state.score,
+    lives: state.lives,
+  });
+}
+
+// Expose a couple of internals for focused unit tests.
+export const _internals = { girderBelow, isGirderAt, ladderAt, rng };