pi-mega-compact 0.7.8 → 0.8.0

package/dist/extensions/mega-runtime/state.test.js

@@ -0,0 +1,171 @@
+/**
+ * state.test.ts — S31 MegaRuntime game-state cache round-trip.
+ *
+ * getCachedGameState() lazily reads the game_state row; bumpGameState()
+ * evicts so the next read re-queries. Uses MEGACOMPACT_STATE_DIR + mkdtemp
+ * (G7). A minimal MegaRuntime is constructed directly (no pi runtime).
+ */
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { createRequire } from "node:module";
+import { execSync } from "node:child_process";
+import { closeStore, getGameState, setGameState } from "../../src/store/sqlite.js";
+import { DEFAULT_GAME_STATE } from "../../src/store/sqlite/game-state.js";
+const require = createRequire(import.meta.url);
+// Require the compiled JS (build output) so ESM import of pi-tui etc. resolves.
+const { MegaRuntime } = require("./state.js");
+/** Minimal MegaConfig — enough fields for the constructor; the snapshot path
+ *  isn't exercised here, only getCachedGameState/bumpGameState. */
+function minimalConfig(stateDir) {
+    return {
+        tier: "custom",
+        tierPct: null,
+        thresholdTokens: 100_000,
+        stateDir,
+        fastGatePct: 70,
+        anchorUserMessages: 3,
+        preserveRecent: 4,
+        preserveRecentMin: 2,
+        auto: false,
+        autoInline: false,
+        autoContinueLengthStop: false,
+        autoPctTrigger: null,
+        dedupSim: 0.9,
+        raptorEnabled: false,
+        legacyDurableTrim: false,
+        dbMirror: false,
+        crossRepoEnabled: false,
+        crossRepoCosine: 0.9,
+        memoryAutoReview: false,
+        memoryReviewInterval: 10,
+        recallMaxTokens: 1500,
+        windowDedupe: false,
+        debug: false,
+    };
+}
+/** Fresh isolated state dir per test — the game_state row is global and
+ *  persists across cases in a shared dir, so each case gets its own mkdtemp to
+ *  avoid cross-test contamination. */
+function freshDir() {
+    return mkdtempSync(join(tmpdir(), "mc-state-"));
+}
+describe("MegaRuntime game-state cache (S31)", () => {
+    const dirs = [];
+    after(() => {
+        for (const d of dirs) {
+            try {
+                closeStore(d);
+            }
+            catch { /* */ }
+        }
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        for (const d of dirs)
+            rmSync(d, { recursive: true, force: true });
+    });
+    it("getCachedGameState returns defaults on a fresh install", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const gs = rt.getCachedGameState();
+        assert.deepEqual(gs, { ...DEFAULT_GAME_STATE });
+    });
+    it("getCachedGameState memoizes (same ref across calls)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const a = rt.getCachedGameState();
+        const b = rt.getCachedGameState();
+        assert.equal(a, b, "memoized — same object ref");
+    });
+    it("bumpGameState evicts so the next read reflects a setGameState write", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        const before = rt.getCachedGameState();
+        assert.equal(before.game_mode_on, false);
+        // Write out-of-band (as /mega-game would).
+        setGameState({ game_mode_on: true, theme: "retro", tui_display_mode: "minimal" }, dir);
+        // Without bump, the stale memo is returned.
+        const stale = rt.getCachedGameState();
+        assert.equal(stale.game_mode_on, false, "stale cache before bump");
+        // After bump, the next read re-queries and reflects the write.
+        rt.bumpGameState();
+        const fresh = rt.getCachedGameState();
+        assert.equal(fresh.game_mode_on, true);
+        assert.equal(fresh.theme, "retro");
+        assert.equal(fresh.tui_display_mode, "minimal");
+        // And matches the authoritative getGameState read.
+        assert.deepEqual(fresh, getGameState(dir));
+    });
+    it("bumpGameState is idempotent (safe to call when cache is empty)", () => {
+        const dir = freshDir();
+        dirs.push(dir);
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+        const rt = new MegaRuntime(minimalConfig(dir));
+        rt.bumpGameState(); // no cached state yet — must not throw
+        const gs = rt.getCachedGameState();
+        assert.deepEqual(gs, { ...DEFAULT_GAME_STATE });
+    });
+    it("bindRepo evicts cachedGameState so a repo switch reflects the new repo's game_state", () => {
+        // Two fresh git repos A and B simulate a real repo switch. Each holds its
+        // own per-repo state dir at <root>/.pi/mega-compact (what repoStateDir
+        // returns for a git cwd), and each holds its own game_state row, so a repo
+        // switch (bindRepo) must evict the cached memo or the widget shows A's
+        // theme/mode/toggle after moving to B. Uses MEGACOMPACT_STATE_DIR + mkdtemp
+        // + closeStore (G7); the global state dir stays separate.
+        const globalDir = freshDir();
+        dirs.push(globalDir);
+        const repoA = freshDir();
+        dirs.push(repoA);
+        const repoB = freshDir();
+        dirs.push(repoB);
+        const stateA = join(repoA, ".pi", "mega-compact");
+        const stateB = join(repoB, ".pi", "mega-compact");
+        // Make A and B real git roots so resolveRepoRoot(cwd) returns the root and
+        // repoStateDir produces <root>/.pi/mega-compact (the per-repo store).
+        execSync("git init -q", { cwd: repoA });
+        execSync("git init -q", { cwd: repoB });
+        // Seed A and B with distinct game_state rows in their per-repo dirs.
+        setGameState({ game_mode_on: true, theme: "retro", tui_display_mode: "minimal" }, stateA);
+        setGameState({ game_mode_on: false, theme: "cyan-neon", tui_display_mode: "full" }, stateB);
+        // Construct the runtime against the GLOBAL dir (the non-git fallback so a
+        // real bindRepo switch occurs once we point it at a git root).
+        process.env.MEGACOMPACT_STATE_DIR = globalDir;
+        const rt = new MegaRuntime(minimalConfig(globalDir));
+        // Point the runtime at repo A and prime the cache.
+        rt.bindRepo(repoA);
+        assert.equal(rt.currentStateDir, stateA, "bindRepo(A) switched to A's per-repo dir");
+        const a = rt.getCachedGameState();
+        assert.equal(a.game_mode_on, true, "A: game_mode_on primed");
+        assert.equal(a.theme, "retro", "A: theme primed");
+        assert.equal(a.tui_display_mode, "minimal", "A: tui_display_mode primed");
+        // Switch to repo B: bindRepo must evict cachedGameState so the next read
+        // re-queries B's row instead of returning A's stale memo.
+        rt.bindRepo(repoB);
+        assert.equal(rt.currentStateDir, stateB, "bindRepo(B) switched to B's per-repo dir");
+        const b = rt.getCachedGameState();
+        assert.equal(b.game_mode_on, false, "B: game_mode_on after switch (not A's stale true)");
+        assert.equal(b.theme, "cyan-neon", "B: theme after switch (not A's stale retro)");
+        assert.equal(b.tui_display_mode, "full", "B: tui_display_mode after switch (not A's stale minimal)");
+        assert.deepEqual(b, getGameState(stateB), "B matches authoritative getGameState read");
+        // Cleanup the per-repo DB handles.
+        try {
+            closeStore(globalDir);
+        }
+        catch { /* */ }
+        try {
+            closeStore(stateA);
+        }
+        catch { /* */ }
+        try {
+            closeStore(stateB);
+        }
+        catch { /* */ }
+    });
+});

package/dist/extensions/mega-runtime/widget.js

@@ -0,0 +1,270 @@
+/**
+ * widget.ts — above-editor widget rendering helpers (free functions, consts,
+ * and interfaces) extracted from the original mega-runtime.ts monolith.
+ *
+ * These are pure rendering primitives with zero runtime-state dependencies;
+ * the `MegaRuntime` class (state.ts) imports them to paint the panel.
+ */
+// pi-tui's OWN width measurers — the same functions pi-tui uses to enforce its
+// render-width check ("visibleWidth(line) > width" → crash). Measuring with
+// these guarantees we never disagree on a grapheme's width (e.g. RGI emoji
+// like ⚡ which pi-tui counts as 2 but a naive regex counts as 1), and
+// truncateToWidth both pads AND hard-clips to exactly `width` cells, so no
+// off-by-one can trip the strict `> width` guard. (Fix for the
+// `Rendered line N exceeds terminal width (W > W-1)` crash.)
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getTheme, DEFAULT_THEME } from "../../src/config/themes.js";
+// ── ANSI palette ───────────────────────────────────────────────────────────
+// The pi TUI's Text component preserves ANSI escape codes (see wrapTextWithAnsi),
+// so raw escapes render as colors. No chalk dependency needed — these are just
+// strings. Exported because mega-pipeline.ts and mega-commands.ts import `C`
+// from the mega-runtime barrel.
+export const C = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    amber: "\x1b[38;5;214m", // tier / ready
+    green: "\x1b[38;5;120m", // saved
+    cyan: "\x1b[38;5;51m", // used / live activity
+    teal: "\x1b[38;5;37m", // processing (compress/dedup)
+    magenta: "\x1b[38;5;201m", // dedup rate
+    blue: "\x1b[38;5;75m", // repo totals
+    gray: "\x1b[38;5;245m", // labels
+    red: "\x1b[38;5;203m", // pressure / overflow
+};
+const PULSE = ["◐", "◓", "◑", "◒"];
+// ── Full-width widget panel helpers ────────────────────────────────────────
+// pi's above-editor widget renderer (a Container of Text lines) does NOT pass
+// a terminal width to setWidget(), so lines render left-aligned by default. To
+// make the widget read as a full-width status panel we pad each line to the
+// real terminal width with a background fill. NOTE: C.reset is a FULL SGR
+// reset, so we re-apply the panel bg after every reset to keep the background
+// continuous under colored text (and under pi's own trailing reset).
+/** Default panel background (dark slate). Used when no theme is threaded or
+ *  the theme is transparent (no bg fill). Parametrized per-render via the
+ *  `panelTheme` arg so game-mode themes can restyle the panel background.
+ *  A transparent theme yields `""` so panelLine/panelBar still call
+ *  truncateToWidth (the width guard holds — empty prefix adds zero cells). */
+const DEFAULT_PANEL_BG = "\x1b[48;5;236m"; // dark slate panel background
+/** Resolve the panel-background SGR prefix for a theme id. Transparent themes
+ *  (bg=null) and unknown themes yield `""` (no bg fill) — the width guard in
+ *  panelLine/panelBar still applies via truncateToWidth. */
+function panelBgFor(theme) {
+    if (!theme || theme === DEFAULT_THEME)
+        return "";
+    const t = getTheme(theme);
+    const bg = t?.ansi.bg;
+    return bg ? `\x1b[${bg}m` : "";
+}
+/** Resolve a theme ANSI accent/mega/fg SGR prefix (`\x1b[<params>m`) for the
+ *  given role. Falls back to `""` (no SGR) for transparent/unknown themes so
+ *  game-mode text still renders in the default fg without color noise. */
+function themeAnsi(theme, role) {
+    const t = theme ? getTheme(theme) : undefined;
+    const params = t?.ansi[role];
+    return params ? `\x1b[${params}m` : "";
+}
+/** Emit a full SGR reset, OR `""` if `sgr` is empty (transparent theme). Keeps
+ *  the panel bg continuous by NOT clobbering it with a bare reset when the
+ *  accent/mega prefix was a no-op. */
+function sgrReset(sgr) {
+    return sgr ? "\x1b[0m" : "";
+}
+// (Visible-width measurement is delegated to pi-tui's `visibleWidth` — imported
+// above — so our width math can never diverge from pi-tui's render-width check.)
+/** Wrap a string (with ANSI codes) to fit within `maxWidth` visible chars.
+ *  Splits at │ separators or whitespace when possible. */
+function wrapLine(text, maxWidth, panelBg) {
+    if (maxWidth <= 0)
+        return [text];
+    const panelRst = "\x1b[0m" + panelBg;
+    const result = [];
+    let current = "";
+    let currentW = 0;
+    // Split at │ boundaries first
+    const segments = text.split("│");
+    for (let i = 0; i < segments.length; i++) {
+        const seg = (i > 0 ? "│" : "") + segments[i];
+        const segW = visibleWidth(panelBg + seg.replace(/\x1b\[0m/g, panelRst));
+        if (currentW + segW <= maxWidth || currentW === 0) {
+            current += seg;
+            currentW += segW;
+        }
+        else {
+            result.push(current);
+            current = seg;
+            currentW = segW;
+        }
+    }
+    if (current)
+        result.push(current);
+    return result;
+}
+function panelLine(content, width, panelBg = DEFAULT_PANEL_BG) {
+    if (width <= 0)
+        return "";
+    const panelRst = "\x1b[0m" + panelBg;
+    // Apply the panel background; swap every inner full-reset for a reset that
+    // re-applies the bg so the fill stays continuous under colored text.
+    const withBg = panelBg + content.replace(/\x1b\[0m/g, panelRst);
+    // truncateToWidth(line, width, "", true) returns EXACTLY `width` visible cells
+    // (by pi-tui's measure), ANSI-preserved, space-padded. It hard-clips overflow
+    // — so even a segment wider than `width` (or a width-rule mismatch) can never
+    // produce a line that trips pi-tui's strict `visibleWidth(line) > width` check.
+    return truncateToWidth(withBg, width, "", true) + "\x1b[0m";
+}
+/** A full-width hairline bar (top/bottom border of the panel). */
+function panelBar(width, ch = "─", panelBg = DEFAULT_PANEL_BG) {
+    // `─` (U+2500) is narrow (1 cell) in both our measure and pi-tui's, so a
+    // `ch.repeat(width)` bar is exactly `width` cells and already passes the
+    // `> width` guard. truncateToWidth is belt-and-suspenders in case `ch` is
+    // ever swapped for a wide/fullwidth character.
+    return truncateToWidth(panelBg + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
+}
+/** Token-count formatter: M at/above 1e6, k at/above 1e3, raw below.
+ *  5,472,700 → "5.5mil", 24,100 → "24.1k", 142 → "142". */
+function fmtTokens(x) {
+    return x >= 1_000_000
+        ? `${(x / 1_000_000).toFixed(1)}mil`
+        : x >= 1000
+            ? `${(x / 1000).toFixed(1)}k`
+            : `${Math.round(x)}`;
+}
+/** Retro gradient bar — `w` cells shaded by fill position (green→amber→red).
+ *  Used for CONTEXT fill where low=green (room) and high=red (near the limit). */
+function ramp(pct, w = 12) {
+    const cells = ["▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"];
+    const scaled = Math.max(0, Math.min(w, pct * w));
+    const full = Math.floor(scaled);
+    const frac = scaled - full;
+    const fracCell = frac > 0 ? cells[Math.round(frac * (cells.length - 1))] : "";
+    let out = "";
+    for (let i = 0; i < full; i++)
+        out += (i / w < 0.6 ? C.green : i / w < 0.85 ? C.amber : C.red) + "█";
+    if (fracCell)
+        out +=
+            (full / w < 0.6 ? C.green : full / w < 0.85 ? C.amber : C.red) + fracCell;
+    out +=
+        C.dim + "░".repeat(Math.max(0, w - full - (fracCell ? 1 : 0))) + C.reset;
+    return out;
+}
+/** Human "time since" string from a millisecond delta (or null → "never"). */
+function sinceCompactStr(ms) {
+    if (ms == null)
+        return "never";
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    return `${Math.floor(h / 24)}d ago`;
+}
+// ── buildWidgetLines ───────────────────────────────────────────────────────
+// Kept as a free function (not a MegaRuntime method) so state.ts stays
+// focused on state management. It reads the WidgetData snapshot + the live
+// activeAgents counter (passed in) and returns the panel lines.
+/** Build the full-width panel lines from the latest snapshot. Cheap: reads
+ *  only the WidgetData + a couple of live counters; no DB/IO. */
+export function buildWidgetLines(wd, width, activeAgents) {
+    // Resolve the panel background from the threaded theme (transparent → "",
+    // unknown → default dark slate). Computed once per render; threaded into
+    // every panelLine/panelBar/wrapLine so the bg stays continuous and the width
+    // guard (truncateToWidth) still holds for transparent themes.
+    const panelBg = wd?.theme ? panelBgFor(wd.theme) : DEFAULT_PANEL_BG;
+    if (!wd) {
+        return [
+            panelBar(width, "─", panelBg),
+            panelLine(" mega-compact: warming up…", width, panelBg),
+            panelBar(width, "─", panelBg),
+        ];
+    }
+    // S31: minimal TUI mode — a single content line `LVL n | cache NN%` flanked
+    // by panel bars. Built through the same panelLine/panelBar helpers so the
+    // width guard + theme bg apply identically to the full panel. Level is shown
+    // only when game mode is on (otherwise just the cache %).
+    if (wd.tuiMode === "minimal") {
+        const lvl = wd.gameMode ? wd.level ?? 1 : undefined;
+        const cachePct = wd.cachePct ?? 0;
+        const cacheStr = `${Math.round(cachePct * 10) / 10}%`;
+        const accent = themeAnsi(wd.theme, "accent");
+        const mega = themeAnsi(wd.theme, "mega");
+        const megaFlare = wd.gameMode && wd.megaCacheFlare && cachePct >= 100
+            ? ` ${mega}MEGA CACHE${sgrReset(mega)}`
+            : "";
+        const body = lvl != null
+            ? `${accent}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${lvl}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(accent)} ${C.dim}|${C.reset} cache ${cacheStr}${megaFlare}`
+            : `cache ${cacheStr}${megaFlare}`;
+        return [
+            panelBar(width, "─", panelBg),
+            panelLine(` ${body}`, width, panelBg),
+            panelBar(width, "─", panelBg),
+        ];
+    }
+    const pulse = wd.pulsing
+        ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} `
+        : "";
+    const sep = ` ${C.dim}│${C.reset} `;
+    // S31: game-mode header prefix — `LVL n` (accent) prepended to content[0],
+    // and a MEGA CACHE flare (mega ansi) + oopsie gag appended when armed. Both
+    // hidden when game mode is off (keeps the legacy panel byte-for-byte).
+    const lvlPrefix = wd.gameMode
+        ? `${themeAnsi(wd.theme, "accent")}${wd.gameMode && wd.levelUpFlare ? "\x1b[5m" : ""}LVL ${wd.level ?? 1}${wd.gameMode && wd.levelUpFlare ? "\x1b[0m" : ""}${sgrReset(themeAnsi(wd.theme, "accent"))} `
+        : "";
+    const megaFlareSuffix = wd.gameMode && wd.megaCacheFlare && (wd.cachePct ?? 0) >= 100
+        ? `${sep}${themeAnsi(wd.theme, "mega")}MEGA CACHE! (oops, you cached so hard the dedup caught fire)${sgrReset(themeAnsi(wd.theme, "mega"))}`
+        : "";
+    // Build one long content line — let terminal wrap it naturally
+    const content = [
+        `${lvlPrefix}${C.amber}⚡ ${wd.tierLabel}${C.reset} v${C.bold}${wd.version}${C.reset} ${ramp(wd.ctxPct, 20)} ${C.bold}${wd.pctStr}${C.reset} ${wd.tokStr}/${wd.maxStr}${megaFlareSuffix}`,
+        wd.triggerLabel,
+        `${C.cyan}${wd.modelStr}${C.reset}`,
+        `${wd.chk} chk${wd.agentStr}${wd.turnStr}`,
+        `${C.magenta}dup ${wd.dedupStr}${C.reset}`,
+        `${C.gray}sess${C.reset} ${fmtTokens(wd.sessIn)}→${fmtTokens(wd.sessKept)} kept ${C.green}(${wd.sTxt}% freed)${C.reset}`,
+        `${C.gray}all-time${C.reset} ${fmtTokens(wd.repoIn)}→${fmtTokens(wd.repoKept)} kept ${C.blue}(${wd.rTxt}% freed)${C.reset}`,
+        `${wd.repoChk} chk/${wd.repoSess} sess`,
+        `${C.gray}mem${C.reset} ${wd.embedderName} · ${wd.chk} chunks · ${C.blue}comp ${wd.compStr}${C.reset}`,
+        `${C.gray}drift${C.reset} ${wd.driftStatus === "ok" ? C.green : C.amber}${wd.driftStatus}${C.reset}`,
+        `${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
+    ].join(sep);
+    // Wrap to terminal width and pad each line
+    const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent
+    const lines = [
+        panelBar(width, "─", panelBg),
+        ...wrapped.map((l) => panelLine(l, width, panelBg)),
+    ];
+    // L4 — agents block (S27, count + status; per-agent tokens gated on P0)
+    if (wd.agentsActive) {
+        lines.push(panelLine(`   ${C.cyan}🤖 ${activeAgents} active${wd.turnStr}${C.reset}`, width, panelBg));
+    }
+    // L5 — live ticker / activity (♻ deduped … why, or tier trace, or pulsing)
+    if (wd.tierTrace && wd.fresh) {
+        lines.push(panelLine(`   ${pulse}${wd.tierTrace}`, width, panelBg));
+    }
+    else if (wd.ticker.length > 0) {
+        const step = Math.floor(Date.now() / 250);
+        const idx = wd.ticker.length - 1 - (step % wd.ticker.length);
+        const head = wd.ticker[idx].text;
+        const why = wd.lastWhy ? ` ${C.gray}· ${wd.lastWhy}${C.reset}` : "";
+        const more = wd.ticker.length > 1
+            ? ` ${C.dim}(+${wd.ticker.length - 1} more)${C.reset}`
+            : "";
+        lines.push(panelLine(`   ${wd.fresh ? C.teal : C.dim}${head}${why}${more}${C.reset}`, width, panelBg));
+    }
+    else if (wd.pulsing) {
+        lines.push(panelLine(`   ${pulse}${C.teal}compacting…${C.reset}`, width, panelBg));
+    }
+    // S35: achievement-unlock toast (one-line, accent) -- fires for one render cycle.
+    if (wd.gameMode && wd.achievementFlare && wd.achievementFlareTitles?.length) {
+        const accentSgr = themeAnsi(wd.theme, "accent");
+        const titlesStr = wd.achievementFlareTitles.join(", ");
+        lines.push(panelLine(`   ${accentSgr}🏆 Achievement unlocked: ${titlesStr}${sgrReset(accentSgr)}`, width, panelBg));
+    }
+    // bottom border
+    lines.push(panelBar(width, "─", panelBg));
+    return lines;
+}

package/dist/extensions/mega-runtime/widget.test.js

@@ -0,0 +1,160 @@
+/**
+ * widget.test.ts — S31 buildWidgetLines render snapshot matrix.
+ *
+ * buildWidgetLines is a free function (no pi runtime needed), so we drive it
+ * directly with a fake WidgetData across the full matrix:
+ *   6 themes × {full,minimal} × {gameMode on/off} × {cachePct<100, >=100}
+ * and assert the S31 invariants:
+ *  (a) transparent theme → no '\x1b[48;' bg fill on any line
+ *  (b) non-transparent themes → at least one line carries '\x1b[48;'
+ *  (c) minimal mode → exactly one content line (between the two panel bars)
+ *  (d) gameMode off → no 'LVL' + no 'MEGA CACHE'
+ *  (e) megaCacheFlare + gameMode on + cachePct>=100 → 'MEGA CACHE' text present
+ *  (f) every line visibleWidth <= the terminal width passed in
+ *
+ * Uses MEGACOMPACT_STATE_DIR + mkdtemp (G7). No pi runtime.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtempSync, rmSync } from "node:fs";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { buildWidgetLines } from "./widget.js";
+import { THEME_IDS, DEFAULT_THEME, getTheme } from "../../src/config/themes.js";
+/** A minimal but complete WidgetData (all required fields populated). The S31
+ *  game-mode fields are overridden per-case. */
+function baseWd(overrides = {}) {
+    return {
+        version: "0.0.0-test",
+        tierLabel: "low",
+        triggerLabel: "idle",
+        pctStr: "42%",
+        tokStr: "10k",
+        maxStr: "200k",
+        ctxPct: 0.42,
+        chk: 3,
+        agentStr: "",
+        turnStr: "",
+        dedupStr: "12%",
+        sessIn: 1000,
+        sessKept: 800,
+        sTxt: "20",
+        repoIn: 5000,
+        repoKept: 4000,
+        rTxt: "20",
+        repoChk: 9,
+        repoSess: 2,
+        modelStr: "test-model",
+        sinceCompact: null,
+        embedderName: "Trigram",
+        compStr: "1.2x",
+        driftStatus: "ok",
+        agentsActive: false,
+        fresh: false,
+        ticker: [],
+        lastWhy: undefined,
+        tierTrace: undefined,
+        pulsing: false,
+        ...overrides,
+    };
+}
+const WIDTH = 120;
+function contentLines(lines) {
+    // Strip the top + bottom panel bars; what's left is the content body.
+    return lines.slice(1, lines.length - 1);
+}
+describe("buildWidgetLines (S31)", () => {
+    let dir;
+    before(() => {
+        dir = mkdtempSync(join(tmpdir(), "mc-widget-"));
+        process.env.MEGACOMPACT_STATE_DIR = dir;
+    });
+    after(() => {
+        delete process.env.MEGACOMPACT_STATE_DIR;
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it("null wd → warm-up panel (3 lines, all width-safe)", () => {
+        const lines = buildWidgetLines(null, WIDTH, 0);
+        assert.equal(lines.length, 3);
+        for (const l of lines)
+            assert.ok(visibleWidth(l) <= WIDTH, "width safe");
+    });
+    for (const theme of THEME_IDS) {
+        for (const tuiMode of ["full", "minimal"]) {
+            for (const gameMode of [false, true]) {
+                for (const cachePct of [42, 150]) {
+                    const flare = cachePct >= 100;
+                    const label = `theme=${theme} tui=${tuiMode} game=${gameMode} cache=${cachePct}`;
+                    it(label, () => {
+                        const wd = baseWd({
+                            theme,
+                            tuiMode,
+                            gameMode,
+                            level: 1,
+                            cachePct,
+                            megaCacheFlare: flare,
+                        });
+                        const lines = buildWidgetLines(wd, WIDTH, 0);
+                        const body = contentLines(lines);
+                        const joined = lines.join("\n");
+                        // (f) every line width <= terminal (truncateToWidth respected)
+                        for (const l of lines) {
+                            assert.ok(visibleWidth(l) <= WIDTH, `width safe: ${visibleWidth(l)} > ${WIDTH}`);
+                        }
+                        // (a) transparent theme → no '\x1b[48;' bg fill anywhere
+                        if (theme === DEFAULT_THEME) {
+                            assert.ok(!joined.includes("\x1b[48;"), `transparent has no 48; bg fill: ${label}`);
+                        }
+                        else {
+                            // (b) non-transparent themes → their bg SGR appears on some line.
+                            // (Themes may use 3-bit bg like \x1b[40m, not just 48;5; form.)
+                            const bgParams = getTheme(theme).ansi.bg;
+                            const bgEsc = `\x1b[${bgParams}m`;
+                            assert.ok(joined.includes(bgEsc), `themed has bg fill ${bgEsc}: ${label}`);
+                        }
+                        // (c) minimal mode → exactly one content line
+                        if (tuiMode === "minimal") {
+                            assert.equal(body.length, 1, `minimal one line: ${label}`);
+                        }
+                        // (d) gameMode off → no LVL + no MEGA CACHE
+                        if (!gameMode) {
+                            assert.ok(!joined.includes("LVL"), `no LVL when off: ${label}`);
+                            assert.ok(!joined.includes("MEGA CACHE"), `no MEGA CACHE when off: ${label}`);
+                        }
+                        else {
+                            // gameMode on → LVL shown (in full mode header, or minimal line)
+                            assert.ok(joined.includes("LVL"), `LVL shown when on: ${label}`);
+                        }
+                        // (e) MEGA CACHE flare text appears only when flare + gameMode on
+                        const expectMega = flare && gameMode;
+                        const hasMega = joined.includes("MEGA CACHE");
+                        assert.equal(hasMega, expectMega, `MEGA CACHE flare: ${label} (got ${hasMega}, want ${expectMega})`);
+                    });
+                }
+            }
+        }
+    }
+});
+describe("buildWidgetLines achievement flare (S35)", () => {
+    const achBase = (overrides = {}) => baseWd({
+        theme: DEFAULT_THEME, tuiMode: "full", gameMode: true, level: 1, cachePct: 42, ...overrides,
+    });
+    it("achievementFlare + titles -> renders the unlock toast line", () => {
+        const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+        assert.ok(lines.some((l) => l.includes("Achievement unlocked: First Compact")), "toast line present");
+    });
+    it("achievementFlare off -> no toast line", () => {
+        const lines = buildWidgetLines(achBase({ achievementFlare: false, achievementFlareTitles: ["First Compact"] }), WIDTH, 0);
+        assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when flare off");
+    });
+    it("gameMode off -> no toast even if flare set", () => {
+        const lines = buildWidgetLines(achBase({ gameMode: false, achievementFlare: true, achievementFlareTitles: ["X"] }), WIDTH, 0);
+        assert.ok(!lines.some((l) => l.includes("Achievement unlocked")), "no toast when game off");
+    });
+    it("achievement toast is width-safe", () => {
+        const lines = buildWidgetLines(achBase({ achievementFlare: true, achievementFlareTitles: ["First Compact", "Turn Veteran"] }), 60, 0);
+        for (const l of lines)
+            assert.ok(visibleWidth(l) <= 60, "width safe");
+    });
+});