@modelstatus/cli 0.1.35 → 0.1.36

package/src/tui/game/term.js

@@ -0,0 +1,330 @@
+/* Direct-ANSI terminal control + double-buffered cell renderer for the game.
+ * NO Ink, NO React. This is the renderer half of the DECISION: a diff-based
+ * cell buffer that emits ONLY changed cells (cursor-move on run-break + sticky
+ * SGR fg) so a near-static frame writes ~0 bytes and the screen is NEVER cleared
+ * during play — that is what removes the old Ink clearTerminal flicker.
+ *
+ * The pieces here are deliberately split so they're unit-testable WITHOUT a TTY:
+ *   - Backbuffer: pure cell store + diff() string builder (front/back typed
+ *     arrays). diff-minimality is asserted directly in tests.
+ *   - Term: the IO shell (alt-screen, raw mode, hide cursor, SIGWINCH) with a
+ *     SINGLE idempotent restore() wired to every exit path — the #1 safety risk.
+ *
+ * Color: GAME_COLORS are hex strings ("#rrggbb"); we pack to a 24-bit int once
+ * and emit truecolor SGR (\x1b[38;2;r;g;bm), sticky so a run of one color emits
+ * one SGR. When color is off (NO_COLOR / MM_ASCII / TERM=dumb) we skip ALL SGR
+ * and just place glyphs — matching the rest of the TUI's degrade discipline. */
+
+// ---- env flags (read once, mirror ui.js / dk-render.js) --------------------
+const ASCII = process.env.MM_ASCII === "1" || process.env.TERM === "dumb";
+export const COLOR_ON = !ASCII && process.env.NO_COLOR == null;
+
+// ---- ANSI primitives -------------------------------------------------------
+export const ESC = "\x1b";
+const CSI = ESC + "[";
+export const ALT_ENTER = CSI + "?1049h"; // enter alternate screen buffer
+export const ALT_LEAVE = CSI + "?1049l"; // leave it (restores prior screen)
+export const CURSOR_HIDE = CSI + "?25l";
+export const CURSOR_SHOW = CSI + "?25h";
+export const SGR_RESET = CSI + "0m";
+const CLEAR_SCREEN = CSI + "2J" + CSI + "H";
+
+/** 1-based cursor positioning (terminals are 1-indexed). */
+export function cursorTo(x, y) {
+  return CSI + (y + 1) + ";" + (x + 1) + "H";
+}
+/** Truecolor foreground SGR for a packed 24-bit RGB int. */
+export function fgSeq(rgb) {
+  return CSI + "38;2;" + ((rgb >> 16) & 255) + ";" + ((rgb >> 8) & 255) + ";" + (rgb & 255) + "m";
+}
+
+/** "#rrggbb" | "#rgb" | "rrggbb" -> packed 24-bit int. Unparseable -> -1
+ * (sentinel = "no color", so the diff path skips SGR for that cell). */
+export 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;
+}
+
+const SPACE = 32; // char code for a blank cell
+const NO_FG = -1; // packed-fg sentinel for "default / no SGR"
+const DIRTY = -2; // front-buffer sentinel forcing every cell to differ once
+
+/**
+ * Double-buffered cell grid. Cells are two flat typed arrays:
+ *   ch  : Uint16Array of char codes (BMP glyphs — DK's glyph set is all BMP)
+ *   fg  : Int32Array of packed 24-bit RGB (or NO_FG = -1 = default)
+ * `front` is what's on screen; you write the next frame into `back` (via set /
+ * clear / setCell or fillFromCells), then diff() returns the minimal escape
+ * string and (when applied) swaps the buffers.
+ *
+ * Pure + TTY-free: construct, write cells, call diff() — assert the string.
+ */
+export class Backbuffer {
+  constructor(width, height, { color = COLOR_ON } = {}) {
+    this.color = color;
+    this.resize(width, height);
+  }
+
+  resize(width, height) {
+    this.width = Math.max(0, width | 0);
+    this.height = Math.max(0, height | 0);
+    this.n = this.width * this.height;
+    this.frontCh = new Uint16Array(this.n);
+    this.frontFg = new Int32Array(this.n);
+    this.backCh = new Uint16Array(this.n);
+    this.backFg = new Int32Array(this.n);
+    this.frontCh.fill(SPACE);
+    this.backCh.fill(SPACE);
+    this.frontFg.fill(NO_FG);
+    this.backFg.fill(NO_FG);
+    // Force the very next diff() to be a full paint (front all-dirty).
+    this.markAllDirty();
+  }
+
+  /** Poison the front buffer so EVERY cell differs from back -> full repaint on
+   * the next diff(). Used at game start and after SIGWINCH (size changed). */
+  markAllDirty() {
+    this.frontCh.fill(0xffff);
+    this.frontFg.fill(DIRTY);
+  }
+
+  /** Reset the BACK buffer to blank before composing a frame. */
+  clearBack(fg = NO_FG) {
+    this.backCh.fill(SPACE);
+    this.backFg.fill(fg);
+  }
+
+  /** Write one cell into the back buffer. Out-of-bounds is a safe no-op so the
+   * caller never has to bounds-check (e.g. a HUD string longer than the row). */
+  setCell(x, y, chCode, fg = NO_FG) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    const i = y * this.width + x;
+    this.backCh[i] = chCode & 0xffff;
+    this.backFg[i] = this.color ? fg : NO_FG;
+  }
+
+  /** Write a string starting at (x,y), one column per code unit, clipped to the
+   * row. fg applies to the whole run. Returns the x after the last glyph. */
+  setText(x, y, text, fg = NO_FG) {
+    for (let k = 0; k < text.length; k++) {
+      this.setCell(x + k, y, text.charCodeAt(k), fg);
+    }
+    return x + text.length;
+  }
+
+  /**
+   * Fill a rectangle of the back buffer from a flat cell descriptor produced by
+   * dk-render.fillCells: arrays `ch` (char codes) and `fg` (packed RGB) of
+   * length w*h, placed with the top-left at (ox, oy). Lets the renderer hand the
+   * board straight into the buffer with no per-cell call overhead.
+   */
+  blit(cells, ox, oy, w, h) {
+    const { ch, fg } = cells;
+    for (let cy = 0; cy < h; cy++) {
+      const dy = oy + cy;
+      if (dy < 0 || dy >= this.height) continue;
+      const srcRow = cy * w;
+      const dstRow = dy * this.width;
+      for (let cx = 0; cx < w; cx++) {
+        const dx = ox + cx;
+        if (dx < 0 || dx >= this.width) continue;
+        const di = dstRow + dx;
+        this.backCh[di] = ch[srcRow + cx] & 0xffff;
+        this.backFg[di] = this.color ? fg[srcRow + cx] : NO_FG;
+      }
+    }
+  }
+
+  /**
+   * Build the MINIMAL escape string that turns the on-screen (front) buffer into
+   * the composed (back) buffer:
+   *   - skip cells that are unchanged (no bytes)
+   *   - emit a cursor-move ONLY when the cursor isn't already where it needs to
+   *     be (i.e. only at the start of a changed run / after a skipped cell)
+   *   - emit an fg SGR ONLY when the color changes (sticky across the frame)
+   *   - reset SGR once at the very end (and only if any color was emitted)
+   * Does NOT mutate buffers; call swap() after writing the result to apply.
+   */
+  diff() {
+    let out = "";
+    let cx = -1, cy = -1;          // tracked cursor position (-1 = unknown)
+    let curFg = -1;                 // currently-active SGR fg (-1 = none set)
+    let emittedColor = false;
+    const { width, n, backCh, backFg, frontCh, frontFg, color } = this;
+    for (let i = 0; i < n; i++) {
+      if (backCh[i] === frontCh[i] && backFg[i] === frontFg[i]) {
+        continue; // unchanged — emit nothing; the next change will reposition
+      }
+      const y = (i / width) | 0;
+      const x = i - y * width;
+      if (x !== cx || y !== cy) {
+        out += cursorTo(x, y);
+        cx = x; cy = y;
+      }
+      if (color) {
+        const fg = backFg[i];
+        if (fg !== curFg) {
+          if (fg === NO_FG) {
+            out += SGR_RESET;
+            curFg = NO_FG;
+            emittedColor = false; // reset clears the sticky color
+          } else {
+            out += fgSeq(fg);
+            curFg = fg;
+            emittedColor = true;
+          }
+        }
+      }
+      out += String.fromCharCode(backCh[i]);
+      cx += 1; // we advanced one column by printing the glyph
+    }
+    if (emittedColor) out += SGR_RESET;
+    return out;
+  }
+
+  /** Apply: copy back -> front so the next frame diffs against what's now shown.
+   * (Call after writing diff() output to the terminal.) */
+  swap() {
+    this.frontCh.set(this.backCh);
+    this.frontFg.set(this.backFg);
+  }
+
+  /** Convenience for headless tests: returns the diff string AND applies it. */
+  render() {
+    const s = this.diff();
+    this.swap();
+    return s;
+  }
+}
+
+/**
+ * Term: the IO shell that owns alt-screen, raw mode, the hidden cursor, resize,
+ * and — most importantly — a SINGLE idempotent restore() registered on every
+ * exit path so a crash mid-game can NEVER leave the user in raw mode + alt
+ * screen + hidden cursor (the "broken terminal").
+ *
+ * Injectable streams/hooks (`out`, `inp`, `proc`) make it fully testable: tests
+ * pass fakes and assert the exact teardown sequence without touching a TTY.
+ */
+export class Term {
+  constructor({
+    out = process.stdout,
+    inp = process.stdin,
+    proc = process,
+    color = COLOR_ON,
+  } = {}) {
+    this.out = out;
+    this.inp = inp;
+    this.proc = proc;
+    this.color = color;
+    this.started = false;
+    this.restored = false;
+    this._wasRaw = false;
+    this._signalHandlers = null;
+    this._onResize = null;
+  }
+
+  write(s) {
+    if (s) this.out.write(s);
+  }
+
+  /** Enter the game's terminal mode: alt screen, hide cursor, raw stdin, and
+   * wire bulletproof teardown. Idempotent. */
+  start() {
+    if (this.started) return;
+    this.started = true;
+    this.restored = false;
+
+    // Enter alt screen + hide cursor ONCE (never per frame — that's the anti-
+    // flicker invariant). Clear the alt buffer so a stale prior frame can't show
+    // through before the first diff paints.
+    this.write(ALT_ENTER + CURSOR_HIDE + CLEAR_SCREEN);
+
+    // Raw mode so we get bytes immediately (no line buffering / no echo). Save
+    // the prior state so restore() returns the terminal exactly as it was.
+    const inp = this.inp;
+    if (inp && typeof inp.setRawMode === "function" && inp.isTTY) {
+      this._wasRaw = !!inp.isRaw;
+      inp.setRawMode(true);
+    }
+    if (inp && typeof inp.resume === "function") inp.resume();
+
+    // Bulletproof teardown: a single restore() on EVERY way out.
+    const restore = () => this.restore();
+    const handlers = {
+      exit: restore,
+      SIGINT: () => { this.restore(); this.proc.exit(130); },
+      SIGTERM: () => { this.restore(); this.proc.exit(143); },
+      SIGHUP: () => { this.restore(); this.proc.exit(129); },
+      uncaughtException: (err) => {
+        this.restore();
+        // Surface the error on the now-restored terminal, then exit non-zero.
+        try { (this.proc.stderr || process.stderr).write(String(err && err.stack || err) + "\n"); } catch {}
+        this.proc.exit(1);
+      },
+    };
+    this._signalHandlers = handlers;
+    for (const [evt, fn] of Object.entries(handlers)) this.proc.on(evt, fn);
+  }
+
+  /** Register a resize callback. On SIGWINCH we recompute nothing here (the loop
+   * owns board math) — we just notify; the loop reallocs + forces a full repaint
+   * via Backbuffer.markAllDirty(). Debounced is the loop's concern; we pass the
+   * raw signal. */
+  onResize(cb) {
+    this._onResize = cb;
+    const handler = () => { if (this._onResize) this._onResize(this.size()); };
+    this._resizeHandler = handler;
+    this.proc.on("SIGWINCH", handler);
+  }
+
+  size() {
+    return {
+      width: (this.out && this.out.columns) || 80,
+      height: (this.out && this.out.rows) || 24,
+    };
+  }
+
+  /**
+   * IDEMPOTENT restore: leave alt screen, show cursor, reset SGR, drop raw mode
+   * back to its prior state, and unhook every signal handler. Safe to call
+   * twice (double-restore is a no-op) — which it WILL be (try/finally in the loop
+   * plus the exit handler both call it).
+   */
+  restore() {
+    if (this.restored) return;
+    this.restored = true;
+
+    // Order matters: reset SGR + show cursor + leave alt LAST so the chrome
+    // lands back on the normal buffer with a visible cooked cursor.
+    try { this.write(SGR_RESET + CURSOR_SHOW + ALT_LEAVE); } catch {}
+
+    const inp = this.inp;
+    try {
+      if (inp && typeof inp.setRawMode === "function" && inp.isTTY) {
+        inp.setRawMode(this._wasRaw);
+      }
+    } catch {}
+    // Don't pause stdin here — the caller (TUI remount) may want to keep reading.
+
+    // Unhook our signal/exit handlers so a subsequent normal exit doesn't double-
+    // fire and so the process can exit cleanly when nothing else is listening.
+    if (this._signalHandlers) {
+      for (const [evt, fn] of Object.entries(this._signalHandlers)) {
+        try { this.proc.removeListener(evt, fn); } catch {}
+      }
+      this._signalHandlers = null;
+    }
+    if (this._resizeHandler) {
+      try { this.proc.removeListener("SIGWINCH", this._resizeHandler); } catch {}
+      this._resizeHandler = null;
+    }
+    this.started = false;
+  }
+}
+
+export const _internals = { SPACE, NO_FG, DIRTY, CLEAR_SCREEN };

package/src/tui/views/scan.js

@@ -5,17 +5,21 @@
  * Scrollable (j/k/↑↓), filterable (/), with a full-width detail panel; ↵ drills
  * into the highlighted model's usage locations and ↵ opens one in your editor.
  *
- * BACKGROUND RUNNER: the walk runs on the shared cooperative engine via
- * useStreamingScan (scan-stream.js) → scanFilesystemStreaming, which yields the
- * event loop on a time+count budget (filesystem.js) so the Ink renderer + input
- * loop stay responsive. Because the scan lives entirely in that async loop and
- * is independent of which keys this view consumes, a "Play Donkey Kong while you
- * wait" overlay (DkGame) can mount, capture input, and run its own useTick frame
- * loop CONCURRENTLY — candidates keep streaming into scan.candidates in the
- * background, and the game reads (never mutates) the live scan fields for its
- * HUD. Mid-scan only: P opens the game; q/esc/⌫/↵ closes it. */
+ * BACKGROUND RUNNER: the live view's walk runs on the shared cooperative engine
+ * via useStreamingScan (scan-stream.js) → scanFilesystemStreaming.
+ *
+ * PLAY-WHILE-YOU-WAIT: P launches Donkey Kong via a clean Ink↔game handoff (NOT
+ * an Ink overlay anymore). We (1) start a TRUE background scan SUBPROCESS
+ * (scan-process.js) that survives Ink being unmounted because it's a separate OS
+ * process, (2) UNMOUNT the whole Ink tree (releasing raw mode + stdin), (3) run
+ * the direct-ANSI 60Hz game loop (loop.js — its own raw mode + alt screen +
+ * diff renderer, zero flicker), then (4) on game exit REMOUNT the TUI at the
+ * Scan tab. When the subprocess scan finishes during play we persist its
+ * candidates to the on-disk scan cache, so the remounted Scan view loads the
+ * fresh results on its fast path. Mid-scan only: P opens the game. */
 import React from "react";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { Box, Text, useInput } from "ink";
 import {
@@ -30,7 +34,6 @@ import { readSnippet } from "../snippet.js";
 import { buildUsages, assignProjects } from "../../upload.js";
 import { track } from "../../telemetry.js";
 import { openUrl, openLocation } from "../../openUrl.js";
-import { DonkeyKong } from "../game/DkGame.js";
 import { boardSize, MIN_W, MIN_H } from "../game/dk-core.js";
 
 export const meta = {
@@ -48,7 +51,7 @@ export const meta = {
 
 const PANEL_H = 6;
 
-export function ScanView({ client, dir, ui, active, width = 78, height = 14, fresh = false }) {
+export function ScanView({ client, dir, ui, active, width = 78, height = 14, fresh = false, launchGameImpl = null }) {
   // Reuse the SHARED cached scan engine (same module-level cache as the Here
   // tab) instead of re-walking the repo on every visit. Switching to Scan after
   // Here is now instant; `g` forces a fresh walk for both.
@@ -64,30 +67,83 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
   const tick = useTick(80, running || busy);
   const search = useSearch();
 
-  // "Play Donkey Kong while you wait" overlay. gameRef is the synchronous mirror
-  // (same stale-closure-safe pattern as refIdxRef / useSearch) so a key in the
-  // same tick that opens the game is routed correctly. The board fits only if
-  // the terminal is large enough (boardSize ≥ MIN_W×MIN_H), so the affordance is
-  // hidden on tiny terminals and the open is a no-op there.
-  const [gameMode, setGameMode] = React.useState(false);
-  const gameRef = React.useRef(false);
+  // "Play Donkey Kong while you wait." The board fits only if the terminal is
+  // large enough (boardSize ≥ MIN_W×MIN_H), so the affordance is hidden on tiny
+  // terminals and the open is a no-op there. launchingRef guards against a
+  // double-launch (the handoff is async).
   const { BOARD_W, BOARD_H } = boardSize(width, height);
   const canPlay = BOARD_W >= MIN_W && BOARD_H >= MIN_H;
-  function openGame() {
+  const launchingRef = React.useRef(false);
+
+  async function launchGame() {
+    if (launchingRef.current) return;
     if (!canPlay) return ui?.showToast?.("terminal too small for the game — resize a bit", "#d97706");
-    gameRef.current = true;
-    setGameMode(true);
-    ui?.setCapturing?.(true); // stop app-shell number/Tab/q keys leaking while playing
-    // setHandlesBack(true) is asserted by the effect (keyed on gameMode); the
-    // game's own useInput swallows backspace to close itself.
+    launchingRef.current = true;
     track("game_opened", { game: "donkey_kong", scan_phase: scan.phase });
-  }
-  function closeGame() {
-    gameRef.current = false;
-    setGameMode(false);
-    ui?.setCapturing?.(false);
-    // setHandlesBack is re-asserted by the effect below (keyed on gameMode/focus/
-    // search.query) once gameMode flips back to false.
+    // Test seam: a caller may inject the launcher so the Ink↔game handoff (which
+    // grabs the real terminal + spawns a subprocess) can be asserted without
+    // either. Production passes nothing → the real handoff below runs.
+    if (launchGameImpl) {
+      try { await launchGameImpl({ dir, width, height }); }
+      finally { launchingRef.current = false; }
+      return;
+    }
+    try {
+      const [{ runGame }, { startScanProcess }, { appController }, { writeDiskScan, loadRegistry }] = await Promise.all([
+        import("../game/loop.js"),
+        import("../../sources/scan-process.js"),
+        import("../app.js"),
+        import("../scan-stream.js"),
+      ]);
+
+      // (1) Start a TRUE background scan SUBPROCESS over the same dir. It survives
+      // the Ink unmount (separate OS process). Pre-fetch + cache the registry so
+      // the worker skips the network; on done, persist candidates to the disk
+      // cache so the remounted Scan view loads the fresh results.
+      let cacheFile = null;
+      try {
+        const snapshot = await loadRegistry().catch(() => null);
+        if (snapshot) {
+          cacheFile = path.join(os.tmpdir(), `mm-reg-game-${process.pid}.json`);
+          fs.writeFileSync(cacheFile, JSON.stringify(snapshot));
+        }
+      } catch { /* worker fetches itself */ }
+
+      let handle = null;
+      try {
+        handle = startScanProcess(
+          { root: dir, registryCachePath: cacheFile || undefined },
+          { onDone: (r) => { try { if (r?.candidates?.length) writeDiskScan(dir, r.candidates); } catch { /* best effort */ } } },
+        );
+      } catch { handle = null; }
+
+      // (2) Unmount the Ink tree (releases raw mode + stdin). Wait a tick so the
+      // teardown fully settles before the game grabs raw mode + alt screen.
+      appController.unmount();
+      await new Promise((r) => setImmediate(r));
+
+      // (3) Run the game. Its loop owns raw mode / alt screen / the diff renderer
+      // and restores the terminal (cooked, main buffer, cursor shown) on exit.
+      try {
+        await runGame({
+          width: process.stdout.columns || width,
+          height: process.stdout.rows || height,
+          level: 1,
+          scanStore: handle,
+        });
+      } finally {
+        try { handle && handle.abort(); } catch { /* ignore */ }
+        try { if (cacheFile) fs.unlinkSync(cacheFile); } catch { /* ignore */ }
+      }
+
+      // (4) Remount the TUI at the Scan tab. fresh:false → the view loads the
+      // (now-updated) disk scan cache on its fast path.
+      appController.remount({ initialView: "scan", fresh: false });
+    } catch (e) {
+      ui?.showToast?.(`couldn't start the game: ${e?.message || e}`, "#dc2626");
+    } finally {
+      launchingRef.current = false;
+    }
   }
 
   // Upload-target projects (cheap; independent of the scan).
@@ -161,29 +217,13 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
     ui?.reportStatus?.({ counts, context: ctx });
   }, [items, selCount, project, ui]);
 
-  // While playing, surface scan completion once (toast) so the player knows the
-  // results are ready to review (Enter/q/esc back out). The DkGame HUD also flips
-  // to a "scan complete · N models · q to view results" line — this is the
-  // shell-level nudge for players watching the toast row, not the board.
-  const completeToastedRef = React.useRef(false);
-  React.useEffect(() => {
-    if (gameMode && scan.phase === "done" && !completeToastedRef.current) {
-      completeToastedRef.current = true;
-      const n = scan.candidateCount ?? scan.candidates?.length ?? 0;
-      ui?.showToast?.(`${GLYPH.check} scan complete — ${fmtNum(n)} model${n === 1 ? "" : "s"}, press Enter to review`);
-    }
-    if (running) completeToastedRef.current = false; // arm again for a g-rescan
-  }, [gameMode, scan.phase, running]); // eslint-disable-line react-hooks/exhaustive-deps
-
   // Tell the shell when backspace should back out *within* this view (drilled
-  // into refs, an active filter, or the game overlay is up) rather than stepping
-  // to the previous tab. Includes gameMode so closing the game restores the
-  // correct list/refs/filter back-handling without a stale value.
+  // into refs or an active filter) rather than stepping to the previous tab.
   const setHandlesBack = ui?.setHandlesBack;
   React.useEffect(() => {
-    setHandlesBack?.(gameMode || focus === "refs" || !!search.query);
+    setHandlesBack?.(focus === "refs" || !!search.query);
     return () => setHandlesBack?.(false);
-  }, [setHandlesBack, gameMode, focus, search.query]);
+  }, [setHandlesBack, focus, search.query]);
 
   function openRef(r) {
     if (!r) return;
@@ -244,17 +284,6 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
   useInput(
     (input, key) => {
       if (!active || busy) return;
-      // GAME MODE: while the Donkey Kong overlay is up, DkGame owns its own
-      // useInput (gated on active && gameMode) and handles movement / jump /
-      // pause / quit (q · esc · ⌫). Branch FIRST (synchronous gameRef so a
-      // same-tick keypress routes correctly). We only add ↵ here: once the scan
-      // has finished, Enter "review results" exits the game (DkGame doesn't bind
-      // ↵, so it falls through to us). Everything else is swallowed — the scan
-      // keeps streaming in the background regardless.
-      if (gameRef.current) {
-        if (key.return && !running) return closeGame();
-        return;
-      }
       if (search.isSearchingNow()) {
         if (key.escape) { search.clear(); ui?.setCapturing?.(false); return; }
         if (key.return) { search.confirm(); ui?.setCapturing?.(false); return; }
@@ -294,9 +323,10 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
       if (input === "x") return setItems((its) => its.map((it) => ({ ...it, selected: false })));
       if (input === "p") return setProjectIdx((i) => (i + 1) % projOptions.length);
       if (input === "P") {
-        // Mid-scan, P launches "Play Donkey Kong while you wait"; otherwise it
-        // keeps its original meaning (create a new upload-target project).
-        if (running) return openGame();
+        // Mid-scan, P launches "Play Donkey Kong while you wait" (a clean Ink↔
+        // game handoff); otherwise it keeps its original meaning (create a new
+        // upload-target project).
+        if (running) { launchGame(); return; }
         return ui.askPrompt("New project", { onSubmit: createProject });
       }
       if (input === "g") return scan.reload();
@@ -309,22 +339,6 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
     { isActive: active },
   );
 
-  // GAME OVERLAY — takes precedence over every scan-state render (including the
-  // "scanning…" placeholder), since you most want a distraction while the walk
-  // is still running and the list is empty. DkGame renders a FIXED-height block
-  // (BOARD_H + 3 == height) so the surrounding window chrome never jumps, reads
-  // the live scan fields for its HUD, and never touches the scan itself.
-  if (gameMode)
-    return h(DonkeyKong, {
-      width,
-      height,
-      scan, // read-only: filesScanned / candidates / dirsSeen / phase
-      ui,
-      onExit: closeGame,
-      active: active && gameMode,
-      level: 1,
-    });
-
   if (scan.phase === "error") return h(StateLine, { kind: "error", text: scan.error });
   if (running && !items.length)
     return h(