@modelstatus/cli 0.1.34 → 0.1.35

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

@@ -0,0 +1,114 @@
+/* Donkey Kong — PURE renderer. No state, no React, no ink. Maps a game state
+ * (from dk-core.js) into an array of EXACTLY BOARD_H strings, each hard-padded /
+ * sliced to BOARD_W (the `cell` discipline), plus a colorize() that turns one
+ * row into {char,color} spans so the Ink wrapper can emit colored <Text>.
+ *
+ * Glyphs come from a GAME_GLYPH map with a full ASCII mirror, selected by the
+ * SAME flags ui.js uses (MM_ASCII=1 / TERM=dumb), so the board degrades to clean
+ * monochrome ASCII on dumb terminals exactly like the rest of the TUI. */
+
+const ASCII = process.env.MM_ASCII === "1" || process.env.TERM === "dumb";
+
+const G_UNICODE = {
+  jumpman: "☻",
+  dk: "@",
+  princess: "♥",
+  barrel: "O",
+  girder: "═",
+  ladder: "‖",
+  empty: " ",
+};
+const G_ASCII = {
+  jumpman: "P",
+  dk: "K",
+  princess: "V",
+  barrel: "o",
+  girder: "=",
+  ladder: "H",
+  empty: " ",
+};
+export const GAME_GLYPH = ASCII ? G_ASCII : G_UNICODE;
+
+// Entity color keys (resolved against the C palette by the wrapper; kept here as
+// literal hex so the renderer stays dependency-free + the colorize output is
+// directly usable by tests without importing the design system).
+export const GAME_COLORS = {
+  jumpman: "#22d3ee", // C.ACCENT
+  barrel: "#ea580c", // retiring-orange
+  girder: "#243042", // C.BORDER
+  ladder: "#8b98a5", // C.FG_DIM
+  dk: "#dc2626", // retired-red
+  princess: "#a78bfa", // violet
+  empty: "#5b6673", // C.FG_FAINT
+};
+
+/** Build a BOARD_H × BOARD_W matrix of cell descriptors {ch, kind}. Drawing
+ * order (low → high priority): girders, ladders, princess, DK, barrels, jumpman
+ * — so the player + hazards are never hidden by scenery. */
+function buildGrid(state, glyph) {
+  const { BOARD_W, BOARD_H, platforms, ladders, jumpman, donkeyKong, princess, barrels } = state;
+  const grid = [];
+  for (let y = 0; y < BOARD_H; y++) {
+    const row = new Array(BOARD_W);
+    for (let x = 0; x < BOARD_W; x++) row[x] = { ch: glyph.empty, kind: "empty" };
+    grid.push(row);
+  }
+  const put = (x, y, ch, kind) => {
+    if (y < 0 || y >= BOARD_H || x < 0 || x >= BOARD_W) return;
+    grid[y][x] = { ch, kind };
+  };
+
+  // girders (per-column slope row)
+  for (const p of platforms) {
+    for (let x = 0; x < BOARD_W; x++) put(x, p.slopeOffsets[x], glyph.girder, "girder");
+  }
+  // ladders
+  for (const l of ladders) {
+    for (let y = l.yTop; y <= l.yBottom; y++) put(l.col, y, glyph.ladder, "ladder");
+  }
+  // goal + actors
+  put(princess.x, princess.y, glyph.princess, "princess");
+  put(donkeyKong.x, donkeyKong.y, glyph.dk, "dk");
+  for (const b of barrels) put(b.x, b.y, glyph.barrel, "barrel");
+  put(jumpman.x, jumpman.y, glyph.jumpman, "jumpman");
+  return grid;
+}
+
+/**
+ * renderGame(state, opts) -> string[] of exactly BOARD_H rows, each BOARD_W wide.
+ * Plain monochrome text — the wrapper uses colorize() when it wants color.
+ */
+export function renderGame(state, { glyph = GAME_GLYPH } = {}) {
+  if (!state || state.tooSmall) return [];
+  const grid = buildGrid(state, glyph);
+  return grid.map((row) => {
+    let s = "";
+    for (const cell of row) s += cell.ch;
+    return s.slice(0, state.BOARD_W).padEnd(state.BOARD_W);
+  });
+}
+
+/**
+ * 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
+ * so the wrapper emits a handful of <Text> per row instead of one-per-cell.
+ * `bgOn` is accepted for parity with ui.js (no background wash is used today —
+ * the board reads cleanest as foreground glyphs on the app background).
+ */
+export function colorize(state, { glyph = GAME_GLYPH, colors = GAME_COLORS } = {}) {
+  if (!state || state.tooSmall) return [];
+  const grid = buildGrid(state, glyph);
+  return grid.map((row) => {
+    const spans = [];
+    for (const cell of row) {
+      const color = colors[cell.kind] || colors.empty;
+      const last = spans[spans.length - 1];
+      if (last && last.color === color) last.text += cell.ch;
+      else spans.push({ text: cell.ch, color });
+    }
+    // Pad to width (defensive — buildGrid already fills the full row).
+    const used = spans.reduce((n, sp) => n + sp.text.length, 0);
+    if (used < state.BOARD_W) spans.push({ text: " ".repeat(state.BOARD_W - used), color: colors.empty });
+    return spans;
+  });
+}

package/src/tui/views/add.js

@@ -2,7 +2,7 @@ import React from "react";
 import { Box, Text, useInput } from "ink";
 import { h, C, GLYPH, useAsync, clampCursor } from "../ui.js";
 
-const ENV_ORDER = ["prod", "staging", "dev", "other"];
+const ENV_ORDER = ["prod", "staging", "dev", "unknown"];
 
 export const meta = {
   keys: [

package/src/tui/views/integrations.js

@@ -0,0 +1,224 @@
+import React from "react";
+import { Box, Text, useInput } from "ink";
+import {
+  h, C, GLYPH, ListRow, EmptyCard, envTag as envTagSeg,
+  cell, cellE, SPINNER, useTick, useAsync, clampCursor,
+} from "../ui.js";
+import { getSource } from "../../sources/index.js";
+import {
+  INTEGRATION_IDS, INTEGRATION_META, readIntegrations,
+  setEnabled, setEnvTag, getEnvTag,
+} from "../../integrations.js";
+
+const ENV_TAGS = ["prod", "staging", "dev", "unknown"];
+
+// kind → accent pill color (mirrors the channel KIND_COLOR taste in alerts.js).
+const KIND_COLOR = {
+  "aws-lambda": "#ff9900", // AWS orange
+  vercel: C.FG_STRONG,
+  "supabase-edge": "#3ecf8e", // Supabase green
+  "github-actions": "#a78bfa",
+};
+
+/** A compact provider pill text (kept ≤ the 14-col column). */
+const PILL = {
+  "aws-lambda": "aws",
+  vercel: "vercel",
+  "supabase-edge": "supabase",
+  "github-actions": "github",
+};
+
+/**
+ * Integrations view: a single fixed list of the 4 LIVE integration sources, with
+ * a per-source enabled toggle (the authoritative local switch that drives what
+ * `mm scan` runs by default) + a declared env label. Authorization is NOT stored
+ * here — it's the user's already-authenticated local CLI (aws/gh/vercel/supabase);
+ * `t` runs a one-off read-only identity probe and toasts the result.
+ *
+ * needsAuth:false in app.js — the toggle is local-first and scanning is free; the
+ * web row (best-effort PATCH) is only for cross-device visibility + plan display.
+ * No idle timers / setState-on-tick (the spinner ticks ONLY while a probe runs).
+ */
+export function IntegrationsView({ client, me, ui, active, width = 78, height = 14 }) {
+  const ROWS = Math.max(3, height - 3); // hint line + a little overhead
+  const [cursor, setCursor] = React.useState(0);
+  // Local toggle state, re-read from integrations.json. `gen` bumps to force a
+  // re-read after a write (the file is the source of truth, not React state).
+  const [gen, setGen] = React.useState(0);
+  const local = React.useMemo(() => readIntegrations(), [gen]);
+  // Probing state: which id is mid-probe (drives the spinner) + last results.
+  const [probing, setProbing] = React.useState(null);
+  const [probed, setProbed] = React.useState({}); // id -> { connected, account?, reason? }
+  const tick = useTick(80, probing != null);
+
+  // Availability is the cheap PATH check (no spawn) per source.
+  const avail = useAsync(
+    async () => {
+      const out = {};
+      for (const id of INTEGRATION_IDS) {
+        const src = getSource(id);
+        out[id] = src ? await src.available({}) : false;
+      }
+      return out;
+    },
+    [gen],
+  );
+  const availMap = avail.data || {};
+
+  const rows = INTEGRATION_IDS.map((id) => ({
+    id,
+    meta: INTEGRATION_META[id],
+    enabled: !!local[id]?.enabled,
+    env: getEnvTag(id) || "unknown",
+    hasCmd: !!availMap[id],
+    probe: probed[id] || null,
+  }));
+  const cur = rows[clampCursor(cursor, rows.length)] || null;
+  const enabledCount = rows.filter((r) => r.enabled).length;
+
+  React.useEffect(
+    () => ui?.reportStatus?.({ context: `${enabledCount}/${rows.length} on` }),
+    [enabledCount, rows.length, ui],
+  );
+
+  function refresh() {
+    setProbed({});
+    setGen((g) => g + 1);
+    avail.reload();
+  }
+
+  function toggle(r) {
+    const next = !r.enabled;
+    setEnabled(r.id, next); // local write is authoritative + instant
+    setGen((g) => g + 1);
+    ui.showToast(`${r.id} ${next ? "enabled" : "disabled"}`);
+    // Best-effort cloud mirror (cross-device + plan-gating). The local toggle
+    // already applied; a 402/anything else just toasts and leaves it local.
+    if (me) {
+      client
+        .setIntegration({ action: next ? "enable" : "disable", kind: r.id, env: r.env })
+        .catch((e) => {
+          if (e.status === 402) ui.showToast("Live integrations sync is a Pro feature (toggle still applies locally)", "yellow");
+        });
+    }
+  }
+
+  function setEnv(r) {
+    ui.askPrompt(`Env for ${r.id} (${ENV_TAGS.join("/")})`, {
+      initial: r.env,
+      onSubmit: (val) => {
+        const tag = (val || "").trim().toLowerCase();
+        if (!ENV_TAGS.includes(tag)) return ui.showToast("env must be prod/staging/dev/unknown", "red");
+        try {
+          setEnvTag(r.id, tag); // "unknown" clears the override (guessEnvFrom resumes)
+          setGen((g) => g + 1);
+          ui.showToast(tag === "unknown" ? `${r.id} env override cleared` : `${r.id} env → ${tag}`);
+          if (me) client.setIntegration({ action: r.enabled ? "enable" : "disable", kind: r.id, env: tag }).catch(() => {});
+        } catch (e) {
+          ui.showToast(e.message, "red");
+        }
+      },
+    });
+  }
+
+  async function testAuth(r) {
+    if (!r.hasCmd) return ui.showToast(`${r.meta.requiresCmd} not installed`, "red");
+    const src = getSource(r.id);
+    if (!src || typeof src.authState !== "function") return ui.showToast("no auth probe for this source", "yellow");
+    setProbing(r.id);
+    try {
+      const st = await src.authState({ region: local[r.id]?.ref });
+      setProbed((p) => ({ ...p, [r.id]: st }));
+      if (st.connected) ui.showToast(`${r.id} authorized${st.account ? ` · ${st.account}` : ""}`, "#16a34a");
+      else ui.showToast(`${r.id}: ${st.reason || "not authorized"}`, "red");
+    } catch (e) {
+      setProbed((p) => ({ ...p, [r.id]: { connected: false, reason: e.message } }));
+      ui.showToast(e.message, "red");
+    } finally {
+      setProbing(null);
+    }
+  }
+
+  useInput(
+    (input, key) => {
+      if (!active) return;
+      if (key.downArrow || input === "j") return setCursor((c) => clampCursor(c + 1, rows.length));
+      if (key.upArrow || input === "k") return setCursor((c) => clampCursor(c - 1, rows.length));
+      if (input === "g") return refresh();
+      if (!cur) return;
+      if (input === " " || key.return) return toggle(cur);
+      if (input === "e") return setEnv(cur);
+      if (input === "t") return testAuth(cur);
+    },
+    { isActive: active },
+  );
+
+  // Column budget: rail(1) + toggle(2) + label + gap(1) + kind(10) + status(rest) + env(8).
+  const ENV_W = 8;
+  const KIND_W = 10;
+  const LABEL_W = 30;
+  const restW = Math.max(8, width - 1 - 2 - LABEL_W - 1 - KIND_W - ENV_W);
+
+  // Status string per row: not-installed › off/available › on › on·authorized / auth failed.
+  function statusFor(r) {
+    if (!r.hasCmd) return { text: `${r.meta.requiresCmd} not installed`, color: C.FG_FAINT };
+    if (r.probe && !r.probe.connected) return { text: "auth failed", color: "#dc2626" };
+    if (r.probe && r.probe.connected) {
+      const who = r.probe.account ? ` · ${r.probe.account}` : "";
+      return { text: `authorized${who}`, color: "#16a34a" };
+    }
+    if (r.enabled) return { text: "on", color: C.ACCENT };
+    return { text: "available · off", color: C.FG_DIM };
+  }
+
+  const curIdx = clampCursor(cursor, rows.length);
+  let body;
+  if (avail.loading) {
+    body = h(Text, {}, h(Text, { color: C.ACCENT }, ` ${SPINNER[tick % SPINNER.length]} `), h(Text, { color: C.FG_DIM }, "checking installed CLIs…"));
+  } else if (!rows.length) {
+    body = h(EmptyCard, {
+      icon: GLYPH.spark,
+      title: "Connect your live deployments",
+      lines: ["Scan AWS Lambda, Vercel, Supabase Edge and GitHub Actions for the models you actually ship.", "Toggle one on with space — it then scans by default. Authorization is your own CLI; we never store a token."],
+      width,
+    });
+  } else {
+    body = h(
+      Box,
+      { flexDirection: "column" },
+      ...rows.slice(0, ROWS).map((r, i) => {
+        const isCur = i === curIdx;
+        const st = statusFor(r);
+        const spin = probing === r.id ? `${SPINNER[tick % SPINNER.length]} ` : "";
+        const et = envTagSeg(r.env);
+        const cells = [
+          { text: `${r.enabled ? GLYPH.check : GLYPH.dot} `, color: r.enabled ? C.ACCENT : C.FG_FAINT },
+          { text: cellE(r.meta.label, LABEL_W), color: isCur ? C.FG_STRONG : r.enabled ? C.FG : C.FG_FAINT, bold: isCur },
+          { text: " ", color: C.FG },
+          { text: cell(PILL[r.id] || "", KIND_W), color: KIND_COLOR[r.id] || C.FG_DIM, bold: true },
+          { text: cellE(spin + st.text, restW), color: st.color },
+          { text: cell(et.text, ENV_W), color: et.color },
+        ];
+        return h(ListRow, { key: r.id, active: isCur, cells, width });
+      }),
+    );
+  }
+
+  const hint = "  Toggle which live deployments scan by default · space on/off · t authorize · e env. Secrets stay on your machine.";
+  return h(
+    Box,
+    { flexDirection: "column" },
+    h(Text, { color: C.FG_FAINT }, cellE(hint, width)),
+    body,
+  );
+}
+
+export const meta = {
+  keys: [
+    { k: "↑↓", label: "nav" },
+    { k: "space", label: "toggle" },
+    { k: "e", label: "env" },
+    { k: "t", label: "test" },
+    { k: "g", label: "refresh" },
+  ],
+};

package/src/tui/views/inventory.js

@@ -11,12 +11,13 @@ import {
 } from "../ui.js";
 import { readSnippet, findSourceFile } from "../snippet.js";
 
-const ENV_ORDER = ["prod", "staging", "dev", "other"];
+const ENV_ORDER = ["prod", "staging", "dev", "unknown"];
 
 export const meta = {
   keys: [
     { k: "↑↓", label: "nav" },
     { k: "e", label: "env" },
+    { k: "t", label: "tag untagged" },
     { k: "c", label: "critical" },
     { k: "d", label: "delete" },
     { k: "C", label: "clear all" },
@@ -26,6 +27,10 @@ export const meta = {
   ],
 };
 
+// A row whose env is genuinely unknown — disk had no signal and nobody tagged it.
+// Legacy null/empty + the old "other" bucket count as untagged too.
+const isUntagged = (u) => !u.environment || u.environment === "unknown" || u.environment === "other";
+
 export function InventoryView({ client, ui, dir = ".", active, width = 78, height = 14 }) {
   const q = useAsync(async () => {
     const [u, p] = await Promise.all([client.listUsages(), client.listProjects()]);
@@ -82,6 +87,27 @@ export function InventoryView({ client, ui, dir = ".", active, width = 78, heigh
       if (input === "g") return q.reload();
       if (input === "r") return ui.switchTo("scan");
       if (input === "n") return ui.switchTo("add");
+      if (input === "t") {
+        const untagged = usages.filter(isUntagged);
+        if (!untagged.length) return ui.showToast("nothing untagged");
+        return ui.askPrompt(`Tag ${untagged.length} untagged → type prod / staging / dev`, {
+          onSubmit: async (v) => {
+            const env = String(v || "").trim().toLowerCase();
+            if (!["prod", "staging", "dev"].includes(env)) return ui.showToast("tag cancelled");
+            let n = 0;
+            for (const u of untagged) {
+              try {
+                await client.patchUsage(u.id, { environment: env });
+                n += 1;
+              } catch {
+                /* skip the row that failed; report the rest */
+              }
+            }
+            ui.showToast(`${GLYPH.check} tagged ${n} → ${env}`);
+            q.reload();
+          },
+        });
+      }
       if (input === "C" && usages.length) {
         return ui.askPrompt(`Type "clear" to delete ALL ${usages.length} usages`, {
           onSubmit: (v) => {
@@ -98,7 +124,10 @@ export function InventoryView({ client, ui, dir = ".", active, width = 78, heigh
         });
       }
       if (!cur) return;
-      if (input === "e") return patch(cur, { environment: ENV_ORDER[(ENV_ORDER.indexOf(cur.environment) + 1) % 4] }, "env updated");
+      if (input === "e") {
+        const i = ENV_ORDER.indexOf(cur.environment);
+        return patch(cur, { environment: ENV_ORDER[(i + 1) % ENV_ORDER.length] }, "env updated");
+      }
       if (input === "c") return patch(cur, { is_critical: !cur.is_critical }, "critical toggled");
       if (input === "d")
         return client

package/src/tui/views/scan.js

@@ -3,7 +3,17 @@
  * retirement display, and lets you select + upload to your inventory. Server
  * model_ids are resolved only at upload time so uploads stay correct.
  * Scrollable (j/k/↑↓), filterable (/), with a full-width detail panel; ↵ drills
- * into the highlighted model's usage locations and ↵ opens one in your editor. */
+ * 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. */
 import React from "react";
 import fs from "node:fs";
 import path from "node:path";
@@ -20,6 +30,8 @@ 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 = {
   keys: [
@@ -30,6 +42,7 @@ export const meta = {
     { k: "/", label: "search" },
     { k: "g", label: "rescan" },
     { k: "u", label: "upload all" },
+    { k: "P", label: "play" }, // only meaningful mid-scan; shown when running
   ],
 };
 
@@ -51,6 +64,32 @@ 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);
+  const { BOARD_W, BOARD_H } = boardSize(width, height);
+  const canPlay = BOARD_W >= MIN_W && BOARD_H >= MIN_H;
+  function openGame() {
+    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.
+    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.
+  }
+
   // Upload-target projects (cheap; independent of the scan).
   const projQ = useAsync(() => client.listProjects().then((r) => r.data || []).catch(() => []), []);
   const projects = projQ.data || [];
@@ -122,13 +161,29 @@ 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, or an active filter) rather than stepping to the previous tab.
+  // 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.
   const setHandlesBack = ui?.setHandlesBack;
   React.useEffect(() => {
-    setHandlesBack?.(focus === "refs" || !!search.query);
+    setHandlesBack?.(gameMode || focus === "refs" || !!search.query);
     return () => setHandlesBack?.(false);
-  }, [setHandlesBack, focus, search.query]);
+  }, [setHandlesBack, gameMode, focus, search.query]);
 
   function openRef(r) {
     if (!r) return;
@@ -189,6 +244,17 @@ 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; }
@@ -227,7 +293,12 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
       if (input === "a") return setItems((its) => its.map((it) => ({ ...it, selected: true })));
       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") return ui.askPrompt("New project", { onSubmit: createProject });
+      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();
+        return ui.askPrompt("New project", { onSubmit: createProject });
+      }
       if (input === "g") return scan.reload();
       if (input === "u") return upload();
       if (input === "l") {
@@ -238,8 +309,30 @@ 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(StateLine, { kind: "scanning", spin: SPINNER[tick % SPINNER.length], text: `scanning ${dir}…` });
+  if (running && !items.length)
+    return h(
+      Box,
+      { flexDirection: "column" },
+      h(StateLine, { kind: "scanning", spin: SPINNER[tick % SPINNER.length], text: `scanning ${dir}…` }),
+      canPlay ? h(Text, { color: C.FG_FAINT }, `  ${GLYPH.spark} press P to play Donkey Kong while you wait`) : null,
+    );
   if (!items.length)
     return h(EmptyCard, { icon: GLYPH.spark, title: `No models found in ${path.basename(dir)} — yet`, lines: ["We looked through code, config, and prompt files for model ids.", "Press g to rescan, 1 Here to try another project, or 5 Add to enter one by hand."], width });
 
@@ -264,10 +357,13 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
     return h(ListRow, { key: it.key + realIdx, active: isCur, selected: it.selected, cells, width });
   });
 
+  // While the walk is still running (and the terminal fits a board), nudge the
+  // "Play Donkey Kong while you wait" affordance on the showing line.
+  const playHint = running && canPlay ? " · P play" : "";
   const showingLine = h(
     Text,
     { color: C.FG_FAINT },
-    `  ${fmtNum(filtered.length)} ref${filtered.length === 1 ? "" : "s"}${filtered.length > pageSize ? ` · ${nav.start + 1}-${Math.min(nav.end, filtered.length)}` : ""}${search.query ? ` · filter "${search.query}"` : ""}${scan.fromCache ? " · cached" : ""} · ${selCount === items.length ? `all ${selCount}` : `${selCount}/${items.length}`} selected · u uploads them all`,
+    `  ${fmtNum(filtered.length)} ref${filtered.length === 1 ? "" : "s"}${filtered.length > pageSize ? ` · ${nav.start + 1}-${Math.min(nav.end, filtered.length)}` : ""}${search.query ? ` · filter "${search.query}"` : ""}${scan.fromCache ? " · cached" : ""} · ${selCount === items.length ? `all ${selCount}` : `${selCount}/${items.length}`} selected · u uploads them all${playHint}`,
   );
   const footer = busy
     ? h(Text, { color: C.ACCENT }, ` ${SPINNER[tick % SPINNER.length]} uploading…`)