@modelstatus/cli 0.1.35 → 0.1.37

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

@@ -88,6 +88,52 @@ export function renderGame(state, { glyph = GAME_GLYPH } = {}) {
   });
 }
 
+/** "#rrggbb" | "#rgb" -> packed 24-bit int (-1 if unparseable). Kept local so
+ * the renderer stays dependency-free; identical packing to term.js packHex. */
+function packHex(hex) {
+  if (typeof hex !== "string") return -1;
+  let h = hex[0] === "#" ? hex.slice(1) : hex;
+  if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  if (h.length !== 6) return -1;
+  const n = parseInt(h, 16);
+  return Number.isNaN(n) ? -1 : n & 0xffffff;
+}
+
+// Packed-RGB color table by entity kind, derived once from GAME_COLORS so the
+// hot path (fillCells, every frame) never re-parses hex strings.
+const PACKED_COLORS = Object.fromEntries(
+  Object.entries(GAME_COLORS).map(([k, v]) => [k, packHex(v)]),
+);
+
+/**
+ * fillCells(state, opts) -> { ch:Uint16Array, fg:Int32Array, width, height }.
+ * The cell-buffer path the direct-ANSI Backbuffer.blit() consumes: a flat
+ * BOARD_W × BOARD_H grid of char codes + packed-RGB foregrounds, drawn in the
+ * same priority order as colorize/renderGame (girders → ladders → goal → actors
+ * → jumpman). `empty` cells get fg = -1 (NO_FG sentinel) so the diff renderer
+ * leaves them at the default color and emits no SGR for blank space.
+ *
+ * opts.color=false zeroes all foregrounds to -1 (NO_COLOR/MM_ASCII path).
+ */
+export function fillCells(state, { glyph = GAME_GLYPH, color = true } = {}) {
+  if (!state || state.tooSmall) return { ch: new Uint16Array(0), fg: new Int32Array(0), width: 0, height: 0 };
+  const grid = buildGrid(state, glyph);
+  const w = state.BOARD_W, h = state.BOARD_H;
+  const ch = new Uint16Array(w * h);
+  const fg = new Int32Array(w * h);
+  for (let y = 0; y < h; y++) {
+    const row = grid[y];
+    const base = y * w;
+    for (let x = 0; x < w; x++) {
+      const c = row[x];
+      ch[base + x] = c.ch.charCodeAt(0) & 0xffff;
+      // empty space carries no color (default fg) so blanks emit zero SGR.
+      fg[base + x] = !color || c.kind === "empty" ? -1 : (PACKED_COLORS[c.kind] ?? -1);
+    }
+  }
+  return { ch, fg, width: w, height: h };
+}
+
 /**
  * colorize(state, opts) -> array (length BOARD_H) of span arrays, where each
  * span is { text, color }. Adjacent same-color cells are merged into one span

package/src/tui/game/input.js

@@ -0,0 +1,169 @@
+/* Raw-stdin key reader + held-key model for the game loop. NO Ink.
+ *
+ * Terminals deliver key REPEATS (OS autorepeat) on a held key, NOT a key-up:
+ * after an initial ~250-500ms delay, the same byte(s) arrive every ~30-50ms.
+ * There is no release event in a raw TTY stream. So "held" is modelled as:
+ * a direction is held until HOLD_MS after its LAST received byte. HOLD_MS (90)
+ * is sized > the worst repeat gap (~50ms) so the hold never drops mid-press, but
+ * a real release expires it within 90ms. Movement applies on the FIRST byte
+ * immediately (we do NOT wait out the ~300ms OS repeat-delay) → input latency is
+ * one 60Hz step (~16.7ms), well under the 40ms bar.
+ *
+ * Trigger semantics:
+ *   - movement (left/right/up/down): LEVEL-triggered — sample() reports them as
+ *     "down" for the whole held window, so key-held walking/climbing is smooth.
+ *   - actions (jump/restart/pause/quit): EDGE-triggered — one-shot per physical
+ *     byte, drained on read so a single press fires exactly once.
+ *
+ * The parser is pure (parseKeys: Buffer -> token[]) and the held model is pure
+ * (InputState, driven by an injected clock), so both are unit-tested with no
+ * TTY and no real time. attachStdin() wires a live stdin to an InputState. */
+
+export const HOLD_MS = 90; // direction stays "held" this long after its last byte
+
+// Movement is level-triggered (held); these are the directions.
+const DIRECTIONS = ["left", "right", "up", "down"];
+// Actions are edge-triggered (one-shot per byte).
+const ACTIONS = ["jump", "restart", "pause", "quit"];
+
+// Byte/sequence -> logical token. Arrows are 3-byte CSI; the rest are single
+// chars. wasd + hjkl mirror the arrows; space=jump; r/p/q actions; q/esc/^C quit.
+const ESC = 0x1b, BR = 0x5b; // \x1b '['
+const CSI_FINAL = { 0x41: "up", 0x42: "down", 0x43: "right", 0x44: "left" }; // A B C D
+const CHAR_TOKEN = {
+  " ": "jump",
+  w: "up", a: "left", s: "down", d: "right",
+  h: "left", j: "down", k: "up", l: "right",
+  r: "restart", p: "pause", q: "quit",
+};
+
+/**
+ * Decode a raw input Buffer (or string) into a flat list of logical tokens.
+ * Handles arrow CSI sequences (ESC [ A/B/C/D), bracketed single chars, and a
+ * lone ESC (treated as "quit"). Unknown bytes are dropped. Pure + synchronous.
+ */
+export function parseKeys(buf) {
+  const b = typeof buf === "string" ? Buffer.from(buf, "utf8") : buf;
+  const out = [];
+  let i = 0;
+  while (i < b.length) {
+    const c = b[i];
+    if (c === ESC) {
+      // CSI arrow: ESC [ <final>
+      if (b[i + 1] === BR && i + 2 < b.length) {
+        const tok = CSI_FINAL[b[i + 2]];
+        if (tok) { out.push(tok); i += 3; continue; }
+        // Unknown CSI (e.g. ESC [ 1 ; 2 A modified) — skip the ESC[ and let the
+        // final byte fall through; cheap + safe for our small key set.
+        i += 2; continue;
+      }
+      // Lone ESC (not part of a recognized sequence) = quit / back.
+      out.push("quit");
+      i += 1;
+      continue;
+    }
+    if (c === 0x03) { out.push("quit"); i += 1; continue; } // Ctrl-C
+    if (c === 0x7f || c === 0x08) { out.push("quit"); i += 1; continue; } // backspace/del
+    const tok = CHAR_TOKEN[String.fromCharCode(c)];
+    if (tok) out.push(tok);
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Held-key + edge-action state machine. Injectable `now` so tests drive a fake
+ * clock; defaults to a monotonic ms clock in production.
+ *
+ *   feed(buf): parse bytes, refresh direction hold-stamps, queue edge actions.
+ *   sample(): return the per-step intent the loop applies:
+ *       { left, right, up, down, jump } booleans, where directions are LEVEL
+ *       (held within HOLD_MS of last byte) and jump is EDGE (true once after a
+ *       space byte, then consumed). Action queue (restart/pause/quit) is drained
+ *       separately via takeActions() so the loop can react out-of-band.
+ */
+export class InputState {
+  constructor({ now = monotonicNow, holdMs = HOLD_MS } = {}) {
+    this.now = now;
+    this.holdMs = holdMs;
+    // last-byte timestamp per direction (-Infinity = never pressed; a real press
+    // at clock-time 0 must still register, so 0 is NOT the "never" sentinel).
+    this.lastAt = { left: -Infinity, right: -Infinity, up: -Infinity, down: -Infinity };
+    this._jump = false;     // edge: pending jump for the next sample()
+    this._actions = [];     // edge: restart/pause/quit queue
+  }
+
+  /** Ingest a raw buffer of bytes (one stdin 'data' event, or several). */
+  feed(buf) {
+    const t = this.now();
+    for (const tok of parseKeys(buf)) this.push(tok, t);
+  }
+
+  /** Apply one already-decoded token at time `t` (exposed for testing). */
+  push(tok, t = this.now()) {
+    if (DIRECTIONS.includes(tok)) {
+      this.lastAt[tok] = t; // refresh the hold; movement is level-triggered
+    } else if (tok === "jump") {
+      this._jump = true;    // edge — fires once on the next sample()
+    } else if (ACTIONS.includes(tok)) {
+      this._actions.push(tok);
+    }
+  }
+
+  /** True if direction `dir` is currently held (within HOLD_MS of last byte). */
+  isHeld(dir, t = this.now()) {
+    return t - this.lastAt[dir] < this.holdMs;
+  }
+
+  /**
+   * The per-step movement intent. Directions are level-triggered (held);
+   * jump is edge-triggered (consumed). Opposite directions don't cancel here —
+   * the core clamps movement — but a simultaneous left+right is reported as-is
+   * (matches a player mashing both; harmless to the core).
+   */
+  sample(t = this.now()) {
+    const intent = {
+      left: this.isHeld("left", t),
+      right: this.isHeld("right", t),
+      up: this.isHeld("up", t),
+      down: this.isHeld("down", t),
+      jump: this._jump,
+    };
+    this._jump = false; // edge consumed
+    return intent;
+  }
+
+  /** Drain queued one-shot actions (restart/pause/quit). */
+  takeActions() {
+    const a = this._actions;
+    this._actions = [];
+    return a;
+  }
+
+  /** Reset all held + queued state (e.g. on restart / pause-resume). */
+  reset() {
+    this.lastAt = { left: -Infinity, right: -Infinity, up: -Infinity, down: -Infinity };
+    this._jump = false;
+    this._actions = [];
+  }
+}
+
+function monotonicNow() {
+  // Monotonic, ms — immune to wall-clock jumps.
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+
+/**
+ * Wire a live raw stdin to an InputState. Returns a detach() that removes the
+ * listener (the loop calls it on teardown). Term.start() already put stdin in
+ * raw mode; we only add the data pump here so input.js stays free of TTY setup.
+ */
+export function attachStdin(inputState, inp = process.stdin) {
+  const onData = (chunk) => inputState.feed(chunk);
+  inp.on("data", onData);
+  return function detach() {
+    try { inp.removeListener("data", onData); } catch {}
+  };
+}
+
+export const _internals = { DIRECTIONS, ACTIONS, CHAR_TOKEN, CSI_FINAL, monotonicNow };

package/src/tui/game/loop.js

@@ -0,0 +1,337 @@
+/* Donkey Kong — Ink-free, direct-ANSI, 60Hz fixed-timestep GAME LOOP.
+ *
+ * This is the third leg of the rebuild: term.js (double-buffered diff renderer)
+ * + input.js (raw-stdin held-key model) + dk-core.js (pure 60Hz sub-cell engine)
+ * are stitched together here into a runnable loop. NO Ink, NO React.
+ *
+ * Reached two ways (see src/index.js + src/tui/views/scan.js):
+ *   - `mm play`           → cmdPlay, scanStore = null (static play header)
+ *   - the Scan-tab P key  → Ink is UNMOUNTED first, then runGame is awaited with
+ *                           a live scanStore (the background scan subprocess
+ *                           keeps running across the unmount), then Ink remounts.
+ *
+ * Fixed timestep (the no-lag core): the loop fires on a ~16.7ms cadence; a real-
+ * time accumulator steps the PURE core EXACTLY at 60Hz (dt=1 per step) with a
+ * MAX_STEPS spiral-of-death clamp, so the physics is deterministic and never
+ * fast-forwards after a stall. Render + input run every loop tick. A near-static
+ * frame writes ~0 bytes (Backbuffer.diff()), so idle never repaints.
+ *
+ * High score: the ENGINE stays IO-free (it only tracks state.best). Persistence
+ * is the loop's job — load dkHighScore from config.json at start, write it back
+ * on game-over / clean exit if beaten. One config file, one write path.
+ */
+import { Backbuffer, Term, packHex, COLOR_ON } from "./term.js";
+import { InputState, attachStdin } from "./input.js";
+import {
+  initGame, stepGame, boardSize, FRAME_MS, MIN_W, MIN_H,
+} from "./dk-core.js";
+import { fillCells, GAME_GLYPH, GAME_COLORS } from "./dk-render.js";
+import { loadConfig, setConfigValue } from "../../config.js";
+
+const STEP_MS = FRAME_MS;        // 1000/60 — the core's fixed tick (≈16.67ms)
+const MAX_STEPS = 5;             // spiral-of-death clamp (drop backlog after a stall)
+export const HUD_ROWS = 2;       // scan strip + stats line (above the board)
+export const KEY_ROW = 1;        // in-game keybar (below the board)
+
+const ASCII = process.env.MM_ASCII === "1" || process.env.TERM === "dumb";
+
+// --- HUD glyphs / colors (self-contained — no Ink) --------------------------
+const G = ASCII
+  ? { heart: "v", spark: "*", check: "OK", pause: "||" }
+  : { heart: "♥", spark: "✦", check: "✓", pause: "⏸" };
+
+// Mirror the ui.js palette so the HUD matches the rest of the TUI.
+const COL = {
+  faint: packHex("#5b6673"),
+  dim: packHex("#8b98a5"),
+  fg: packHex("#cbd5e1"),
+  strong: packHex("#f9fafb"),
+  accent: packHex("#22d3ee"),
+  red: packHex("#ff5f56"),
+  green: packHex("#16a34a"),
+  amber: packHex("#d97706"),
+  violet: packHex("#a78bfa"),
+};
+
+const fmtNum = (n) => (n == null ? "0" : Number(n).toLocaleString("en-US"));
+
+/**
+ * Run the game to completion. Returns when the player quits (q / esc / ^C-via-
+ * teardown) — the caller (cmdPlay or the Scan-tab handler) then restores/remounts.
+ *
+ * @param {object} o
+ * @param {number} o.width            terminal columns
+ * @param {number} o.height           terminal rows
+ * @param {number} [o.level]          starting level (default 1)
+ * @param {object|null} [o.scanStore] the startScanProcess handle (reads .stats); null = `mm play`
+ * @param {Function} [o.onExit]       optional callback fired right before resolve
+ * @param {object} [o._inject]        test seams: { out, inp, proc, now, schedule, autoExitAfterMs }
+ * @returns {Promise<{score:number, level:number, best:number, status:string}>}
+ */
+export function runGame({ width, height, level = 1, scanStore = null, onExit, _inject = {} } = {}) {
+  return new Promise((resolve) => {
+    const proc = _inject.proc || process;
+    const out = _inject.out || proc.stdout || process.stdout;
+    const inp = _inject.inp || proc.stdin || process.stdin;
+    const now = _inject.now || (() => Number(process.hrtime.bigint() / 1000000n));
+    // schedule(fn, ms) -> handle; cancel(handle). Defaults to setTimeout so the
+    // loop self-paces; tests inject a virtual clock.
+    const schedule = _inject.schedule || ((fn, ms) => setTimeout(fn, ms));
+    const cancel = _inject.cancel || ((h) => clearTimeout(h));
+
+    let best = 0;
+    try { best = Number(loadConfig().dkHighScore) || 0; } catch { best = 0; }
+
+    const dims = { width, height };
+    const term = new Term({ out, inp, proc, color: COLOR_ON });
+    const input = new InputState({ now });
+
+    // Allocate the buffer for the WHOLE frame: HUD rows + board + key row, BOARD_W
+    // wide (boardSize caps width; the chrome rows are clipped to BOARD_W too).
+    const { BOARD_W, BOARD_H } = boardSize(width, height);
+    const tooSmall = BOARD_W < MIN_W || BOARD_H < MIN_H;
+
+    let game = initGame({ ...dims, level, best });
+
+    // --- too-small terminal: a single static line, NEVER enter the loop. ----
+    if (tooSmall || (game && game.tooSmall)) {
+      // Don't enter alt screen / raw mode — just print a hint on the normal
+      // buffer and resolve so the caller can show its own chrome.
+      try { out.write(`  terminal too small for the game — resize to ~${MIN_W + 2}x${MIN_H + 3}, then run again.\n`); } catch {}
+      onExit && onExit();
+      resolve({ score: 0, level, best, status: "toosmall" });
+      return;
+    }
+
+    let bb = new Backbuffer(BOARD_W, HUD_ROWS + BOARD_H + KEY_ROW, { color: COLOR_ON });
+    let curW = BOARD_W, curH = BOARD_H;
+
+    term.start();
+    const detach = attachStdin(input, inp);
+
+    let running = true;
+    let timer = null;
+    let prevT = now();
+    let acc = 0;
+    let paused = false;
+    let highSaved = false;
+
+    // SIGWINCH: recompute board, realloc the buffer, force ONE full repaint.
+    term.onResize(() => {
+      const sz = term.size();
+      const nb = boardSize(sz.width, sz.height);
+      if (nb.BOARD_W === curW && nb.BOARD_H === curH) return; // no real change
+      if (nb.BOARD_W < MIN_W || nb.BOARD_H < MIN_H) return;   // ignore too-small grow-back
+      curW = nb.BOARD_W; curH = nb.BOARD_H;
+      // Rebuild the game at the new size, preserving score/lives/level/best.
+      game = initGame({ width: sz.width, height: sz.height, level: game.level, score: game.score, lives: game.lives, best: game.best });
+      bb = new Backbuffer(curW, HUD_ROWS + curH + KEY_ROW, { color: COLOR_ON });
+      acc = 0; // drop accumulated time so we don't burst-step after a resize
+    });
+
+    function persistHigh() {
+      if (highSaved) return;
+      highSaved = true;
+      const score = (game && Math.max(game.best || 0, game.score || 0)) || 0;
+      if (score > best) {
+        try { setConfigValue("dkHighScore", score); best = score; } catch { /* best effort */ }
+      }
+    }
+
+    function finish(status) {
+      if (!running) return;
+      running = false;
+      if (timer != null) { try { cancel(timer); } catch {} timer = null; }
+      persistHigh();
+      try { detach(); } catch {}
+      try { term.restore(); } catch {}
+      onExit && onExit();
+      resolve({ score: game ? game.score : 0, level: game ? game.level : level, best, status: status || "quit" });
+    }
+
+    // The actual frame body. Returns true to keep looping, false if it finished.
+    function runTick() {
+      if (!running) return false;
+      const t = now();
+      let dt = t - prevT;
+      prevT = t;
+      if (dt < 0) dt = 0;
+      if (dt > 250) dt = 250; // clamp a huge wall-clock jump (suspend/resume)
+
+      // --- input: edge actions (quit/pause/restart) + movement intent --------
+      for (const action of input.takeActions()) {
+        if (action === "quit") { finish("quit"); return false; }
+        if (action === "pause") { paused = !paused; input.reset(); }
+        if (action === "restart") {
+          // 'over' is a hard no-op in the core, so RESTART re-inits a fresh game
+          // carrying best. Also lets the player bail a run mid-play.
+          game = initGame({ ...sizeDims(), level: 1, best: game.best });
+          input.reset();
+          acc = 0;
+        }
+      }
+
+      // --- fixed-timestep core advance --------------------------------------
+      if (!paused) {
+        acc += dt;
+        let steps = 0;
+        while (acc >= STEP_MS && steps < MAX_STEPS) {
+          // Sample once per core step so a same-step keypress is seen and input
+          // latency is one tick. jump is edge (consumed); movement is level.
+          const intent = input.sample(t);
+          // On the title/over frames the press doubles as start/restart.
+          intent.start = intent.jump;
+          game = stepGame(game, { input: intent, dt: 1 });
+          acc -= STEP_MS;
+          steps++;
+          if (game.status === "over" && !highSaved) persistHigh();
+        }
+        if (steps >= MAX_STEPS) acc = 0; // drop the backlog after a stall
+      }
+
+      // --- render ------------------------------------------------------------
+      render();
+
+      // schedule the next tick for the remaining slice of a frame
+      const elapsed = now() - t;
+      const wait = Math.max(0, STEP_MS - elapsed);
+      timer = schedule(guardedTick, wait);
+      return true;
+    }
+
+    function sizeDims() {
+      const sz = term.size();
+      return { width: sz.width, height: sz.height };
+    }
+
+    function render() {
+      bb.clearBack();
+      drawScanStrip(bb, scanStore, curW);
+      drawStats(bb, game, best, paused, curW);
+      // board → blit the fillCells grid under the HUD rows.
+      const cells = fillCells(game, { glyph: GAME_GLYPH, colors: GAME_COLORS, color: COLOR_ON });
+      bb.blit(cells, 0, HUD_ROWS, cells.width, cells.height);
+      // Respawn blink: hide the player glyph on alternate frames during invuln.
+      maybeBlinkPlayer(bb, game, curW);
+      drawBanner(bb, game, curW, curH);
+      drawKeybar(bb, curW, HUD_ROWS + curH);
+      const s = bb.render();
+      if (s) term.write(s);
+    }
+
+    // Single guarded entry: every scheduled call goes through here, so a throw
+    // ANYWHERE in the frame still restores the terminal (the #1 safety risk) and
+    // kills nothing leaks. restore() is idempotent so the exit handler is safe too.
+    function guardedTick() {
+      try {
+        runTick();
+      } catch (err) {
+        if (!running) return;
+        running = false;
+        if (timer != null) { try { cancel(timer); } catch {} timer = null; }
+        try { detach(); } catch {}
+        try { term.restore(); } catch {}
+        try { (proc.stderr || process.stderr).write("game loop error: " + (err && err.stack || err) + "\n"); } catch {}
+        onExit && onExit();
+        resolve({ score: game ? game.score : 0, level: game ? game.level : level, best, status: "error" });
+      }
+    }
+
+    timer = schedule(guardedTick, 0);
+
+    // Auto-exit hook for tests (drives a finite run without a real `q`).
+    if (_inject.autoExitAfterMs != null) {
+      schedule(() => finish("auto"), _inject.autoExitAfterMs);
+    }
+  });
+}
+
+// --- HUD composition --------------------------------------------------------
+
+/** Row 0: live scan progress (or a static "play" header when scanStore=null). */
+function drawScanStrip(bb, scanStore, w) {
+  if (!scanStore) {
+    bb.setText(0, 0, clip("  Donkey Kong — press q to quit", w), COL.faint);
+    return;
+  }
+  const st = scanStore.stats || scanStore; // tolerate a bare stats object
+  const phase = st.phase || "scanning";
+  if (phase === "done") {
+    const n = st.candidateCount || 0;
+    let x = bb.setText(0, 0, "  " + G.check + " scan complete", COL.green);
+    bb.setText(x, 0, clip(` · ${fmtNum(n)} model${n === 1 ? "" : "s"} · q to view results`, w - x), COL.dim);
+  } else if (phase === "error") {
+    bb.setText(0, 0, clip("  scan unavailable (" + (st.error || "error") + ") — game still plays", w), COL.amber);
+  } else {
+    const files = st.filesScanned || 0;
+    const models = st.candidateCount || 0;
+    const dirs = st.dirsSeen || 0;
+    bb.setText(0, 0, clip(`  scanning · files ${fmtNum(files)} · models ${fmtNum(models)} · dirs ${fmtNum(dirs)}`, w), COL.dim);
+  }
+}
+
+/** Row 1: lives / score / level / best / transient message. */
+function drawStats(bb, game, best, paused, w) {
+  if (!game) return;
+  const lives = Math.max(0, game.lives || 0);
+  const heart = lives > 0 ? G.heart.repeat(lives) : "—";
+  let x = bb.setText(0, 1, "  ", COL.fg);
+  x = bb.setText(x, 1, heart, COL.red);
+  x = bb.setText(x, 1, "   score ", COL.dim);
+  x = bb.setText(x, 1, fmtNum(game.score), COL.accent);
+  x = bb.setText(x, 1, `   lvl ${game.level}`, COL.dim);
+  if (paused) x = bb.setText(x, 1, "  " + G.pause + " paused", COL.amber);
+  x = bb.setText(x, 1, `   best ${fmtNum(Math.max(best || 0, game.best || 0, game.score || 0))}`, COL.faint);
+  // Bonus timer (when playing).
+  if (game.status === "playing" || game.status === "getready") {
+    x = bb.setText(x, 1, `   bonus ${fmtNum(game.bonus || 0)}`, COL.violet);
+  }
+}
+
+/** Hide the player glyph on alternate frames during the respawn-invuln blink. */
+function maybeBlinkPlayer(bb, game, w) {
+  const p = game && game.player;
+  if (!p || !(p.invuln > 0)) return;
+  if ((p.invuln >> 2) & 1) return; // visible this phase
+  // blank the player's cell (it was drawn last by fillCells, so it's on top)
+  bb.setCell(p.x, HUD_ROWS + p.y, 32 /* space */, -1);
+}
+
+/** Centered banner overlay for transient statuses (GET READY / GAME OVER / win).
+ * Drawn into the board region so the board stays BOARD_H tall (it overwrites a
+ * board row rather than adding one). */
+function drawBanner(bb, game, w, boardH) {
+  if (!game) return;
+  let text = null, color = COL.strong;
+  if (game.status === "getready") { text = game.message || "GET READY"; color = COL.accent; }
+  else if (game.status === "levelclear") { text = game.message || "YOU SAVED HER!"; color = COL.violet; }
+  else if (game.status === "over") { text = game.message || "GAME OVER"; color = COL.red; }
+  else if (game.status === "title") { text = G.spark + " DONKEY KONG " + G.spark; color = COL.accent; }
+  if (!text) return;
+  const row = HUD_ROWS + Math.floor(boardH / 2);
+  const x = Math.max(0, Math.floor((w - text.length) / 2));
+  bb.setText(x, row, clip(text, w - x), color);
+  // sub-line for terminal states
+  if (game.status === "over") {
+    const sub = "r restart · q back";
+    const sx = Math.max(0, Math.floor((w - sub.length) / 2));
+    bb.setText(sx, Math.min(HUD_ROWS + boardH - 1, row + 1), clip(sub, w - sx), COL.dim);
+  } else if (game.status === "title") {
+    const sub = "press SPACE to start · q quit";
+    const sx = Math.max(0, Math.floor((w - sub.length) / 2));
+    bb.setText(sx, Math.min(HUD_ROWS + boardH - 1, row + 1), clip(sub, w - sx), COL.dim);
+  }
+}
+
+/** Bottom row: in-game keybar. */
+function drawKeybar(bb, w, y) {
+  const bar = ASCII
+    ? "  <- -> move  ^v climb  spc jump  p pause  r restart  q back"
+    : "  ←→ move  ↑↓ climb  spc jump  p pause  r restart  q back";
+  bb.setText(0, y, clip(bar, w), COL.faint);
+}
+
+function clip(s, w) {
+  if (w <= 0) return "";
+  return s.length > w ? s.slice(0, w) : s;
+}