pi-mega-compact 0.7.9 → 0.8.0

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

@@ -13,6 +13,7 @@
 // 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
@@ -39,15 +40,44 @@ const PULSE = ["◐", "◓", "◑", "◒"];
 // 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).
-const PANEL_BG = "\x1b[48;5;236m"; // dark slate panel background
-const PANEL_RST = "\x1b[0m" + PANEL_BG; // reset fg but retain panel bg
+/** 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) {
+function wrapLine(text, maxWidth, panelBg) {
     if (maxWidth <= 0)
         return [text];
+    const panelRst = "\x1b[0m" + panelBg;
     const result = [];
     let current = "";
     let currentW = 0;
@@ -55,7 +85,7 @@ function wrapLine(text, maxWidth) {
     const segments = text.split("│");
     for (let i = 0; i < segments.length; i++) {
         const seg = (i > 0 ? "│" : "") + segments[i];
-        const segW = visibleWidth(PANEL_BG + seg.replace(/\x1b\[0m/g, PANEL_RST));
+        const segW = visibleWidth(panelBg + seg.replace(/\x1b\[0m/g, panelRst));
         if (currentW + segW <= maxWidth || currentW === 0) {
             current += seg;
             currentW += segW;
@@ -70,12 +100,13 @@ function wrapLine(text, maxWidth) {
         result.push(current);
     return result;
 }
-function panelLine(content, width) {
+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 = PANEL_BG + content.replace(/\x1b\[0m/g, PANEL_RST);
+    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
@@ -83,12 +114,12 @@ function panelLine(content, width) {
     return truncateToWidth(withBg, width, "", true) + "\x1b[0m";
 }
 /** A full-width hairline bar (top/bottom border of the panel). */
-function panelBar(width, ch = "─") {
+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(PANEL_BG + ch.repeat(Math.max(0, width)), width, "", false) + "\x1b[0m";
+    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". */
@@ -139,20 +170,56 @@ function sinceCompactStr(ms) {
 /** 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, "─"),
-            panelLine(" mega-compact: warming up…", width),
-            panelBar(width, "─"),
+            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 = [
-        `${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}`,
+        `${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}`,
@@ -165,18 +232,18 @@ export function buildWidgetLines(wd, width, activeAgents) {
         `${C.gray}compact${C.reset} ${sinceCompactStr(wd.sinceCompact)}`,
     ].join(sep);
     // Wrap to terminal width and pad each line
-    const wrapped = wrapLine(content, width - 2); // 2-char indent
+    const wrapped = wrapLine(content, width - 2, panelBg); // 2-char indent
     const lines = [
-        panelBar(width, "─"),
-        ...wrapped.map((l) => panelLine(l, width)),
+        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));
+        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));
+        lines.push(panelLine(`   ${pulse}${wd.tierTrace}`, width, panelBg));
     }
     else if (wd.ticker.length > 0) {
         const step = Math.floor(Date.now() / 250);
@@ -186,12 +253,18 @@ export function buildWidgetLines(wd, width, activeAgents) {
         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));
+        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));
+        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, "─"));
+    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");
+    });
+});

package/dist/src/config/themes.js

@@ -0,0 +1,84 @@
+/**
+ * themes.ts — SINGLE SOURCE OF TRUTH for game-mode visual-effect themes (S30).
+ *
+ * Each theme defines BOTH an HTML/CSS palette (dashboard) AND an ANSI accent
+ * mapping (TUI widget), since the TUI is ANSI and the dashboard is HTML.
+ *
+ * Theme scope (QA1 correction): themes restyle the mega-compact statusbar
+ * widget + the whole dashboard HTML page. We do NOT theme pi's chrome.
+ *
+ * `transparent` (default) semantics: no background fill, colored accents only —
+ * so game-mode stays visible against any terminal background.
+ *
+ * PREVENT-PI-004: pure config, no network. Pi-agnostic: no pi runtime types.
+ */
+export const DEFAULT_THEME = "transparent";
+export const THEMES = [
+    {
+        id: "transparent",
+        label: "Transparent (accents only)",
+        css: { bg: null, fg: "#c9d1d9", accent: "#3fb950", mega: "#f0883e" },
+        ansi: { bg: null, fg: "39", accent: "32", mega: "33" },
+    },
+    {
+        id: "retro",
+        label: "Retro 8-bit green",
+        css: { bg: "#003300", fg: "#33ff33", accent: "#00ff41", mega: "#39ff14" },
+        ansi: { bg: "40", fg: "92", accent: "92", mega: "1;92" },
+    },
+    {
+        id: "orange-bold",
+        label: "Orange bold",
+        css: { bg: "#1a0f00", fg: "#ff8c00", accent: "#ff6b00", mega: "#ff4500" },
+        ansi: { bg: "48;5;52", fg: "38;5;208", accent: "38;5;208", mega: "1;38;5;202" },
+    },
+    {
+        id: "cyan-neon",
+        label: "Cyan neon",
+        css: { bg: "#001a1a", fg: "#00ffff", accent: "#22d3ee", mega: "#7df9ff" },
+        ansi: { bg: "48;5;23", fg: "38;5;51", accent: "38;5;51", mega: "1;38;5;51" },
+    },
+    {
+        id: "amber-mono",
+        label: "Amber phosphor",
+        css: { bg: "#1a1200", fg: "#ffb000", accent: "#ff8c00", mega: "#ff5500" },
+        ansi: { bg: "48;5;58", fg: "38;5;214", accent: "38;5;214", mega: "1;38;5;208" },
+    },
+    {
+        id: "grayscale",
+        label: "Grayscale minimal",
+        css: { bg: "#161616", fg: "#b0b0b0", accent: "#8b949e", mega: "#e6edf3" },
+        ansi: { bg: "48;5;235", fg: "38;5;249", accent: "38;5;249", mega: "1;38;5;255" },
+    },
+];
+/** All valid theme ids, in definition order (used for `theme next` cycling). */
+export const THEME_IDS = THEMES.map((t) => t.id);
+/** Look up a theme by id; returns `undefined` for an unknown id (caller
+ *  validates + falls back to DEFAULT_THEME). */
+export function getTheme(id) {
+    return THEMES.find((t) => t.id === id);
+}
+/** True if `id` is a known theme id. */
+export function isValidTheme(id) {
+    return THEME_IDS.includes(id);
+}
+/** Cycle to the next theme id (wraps at the end). Falls back to DEFAULT_THEME
+ *  if `current` is unknown (defensive — the stored id should always be valid). */
+export function nextTheme(current) {
+    const i = THEME_IDS.indexOf(current);
+    if (i < 0)
+        return DEFAULT_THEME;
+    return THEME_IDS[(i + 1) % THEME_IDS.length];
+}
+/** CSS variable declarations for a theme's CSS palette. `bg` is `null` for the
+ *  transparent theme → `--bg: transparent` (no page fill, accents only). Pure,
+ *  no pi types. */
+export function themeCssVars(theme) {
+    const bg = theme.css.bg ?? "transparent";
+    return `--bg: ${bg}; --fg: ${theme.css.fg}; --accent: ${theme.css.accent}; --mega: ${theme.css.mega};`;
+}
+/** A `:root[data-theme="<id>"]` override block carrying the theme's CSS vars,
+ *  for client-side instant theme switching. Pure, no pi types. */
+export function themeDataBlock(theme) {
+    return `:root[data-theme="${theme.id}"]{ ${themeCssVars(theme)} }`;
+}

package/dist/src/config/themes.test.js

@@ -0,0 +1,94 @@
+/**
+ * themes.test.ts — S30 theme palette source-of-truth tests.
+ * Pi-agnostic: no pi runtime imports.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { THEMES, THEME_IDS, DEFAULT_THEME, getTheme, isValidTheme, nextTheme, themeCssVars, themeDataBlock, } from "./themes.js";
+describe("themes (S30)", () => {
+    it("defines exactly 6 themes", () => {
+        assert.equal(THEMES.length, 6);
+        assert.equal(THEME_IDS.length, 6);
+    });
+    it("has unique ids", () => {
+        assert.equal(new Set(THEME_IDS).size, 6);
+    });
+    it("default theme is transparent", () => {
+        assert.equal(DEFAULT_THEME, "transparent");
+        assert.ok(isValidTheme(DEFAULT_THEME));
+    });
+    it("includes retro, orange-bold, cyan-neon, amber-mono, grayscale", () => {
+        for (const id of ["retro", "orange-bold", "cyan-neon", "amber-mono", "grayscale"]) {
+            assert.ok(isValidTheme(id), `missing ${id}`);
+        }
+    });
+    it("transparent theme has null bg (CSS + ANSI)", () => {
+        const t = getTheme("transparent");
+        assert.ok(t);
+        assert.equal(t.css.bg, null);
+        assert.equal(t.ansi.bg, null);
+    });
+    it("every non-transparent theme has a non-null bg", () => {
+        for (const t of THEMES) {
+            if (t.id === "transparent")
+                continue;
+            assert.ok(t.css.bg, `${t.id} css.bg`);
+            assert.ok(t.ansi.bg, `${t.id} ansi.bg`);
+        }
+    });
+    it("every theme has css + ansi {fg,accent,mega} strings", () => {
+        for (const t of THEMES) {
+            assert.ok(typeof t.css.fg === "string" && t.css.fg.startsWith("#"));
+            assert.ok(typeof t.css.accent === "string");
+            assert.ok(typeof t.css.mega === "string");
+            assert.ok(typeof t.ansi.fg === "string");
+            assert.ok(typeof t.ansi.accent === "string");
+            assert.ok(typeof t.ansi.mega === "string");
+        }
+    });
+    it("getTheme returns undefined for unknown id", () => {
+        assert.equal(getTheme("nope"), undefined);
+    });
+    it("isValidTheme is false for unknown", () => {
+        assert.equal(isValidTheme("nope"), false);
+    });
+    it("nextTheme cycles through all themes and wraps", () => {
+        const seen = [];
+        let cur = DEFAULT_THEME;
+        for (let i = 0; i < THEME_IDS.length; i++) {
+            cur = nextTheme(cur);
+            seen.push(cur);
+        }
+        // after N steps we've visited every theme once
+        assert.equal(new Set(seen).size, THEME_IDS.length);
+        // wraps: one more step from the last returns to the first
+        const first = nextTheme(THEME_IDS[THEME_IDS.length - 1]);
+        assert.equal(first, THEME_IDS[0]);
+    });
+    it("nextTheme falls back to DEFAULT_THEME for unknown current", () => {
+        assert.equal(nextTheme("garbage"), DEFAULT_THEME);
+    });
+});
+describe("themeCssVars / themeDataBlock (S32)", () => {
+    it("themeCssVars emits --bg/--fg/--accent/--mega for a normal theme", () => {
+        const t = getTheme("retro");
+        const vars = themeCssVars(t);
+        assert.match(vars, /--bg: #003300;/);
+        assert.match(vars, /--fg: #33ff33;/);
+        assert.match(vars, /--accent: #00ff41;/);
+        assert.match(vars, /--mega: #39ff14;/);
+    });
+    it("themeCssVars maps null bg to 'transparent'", () => {
+        const t = getTheme("transparent");
+        const vars = themeCssVars(t);
+        assert.match(vars, /--bg: transparent;/);
+        assert.match(vars, /--fg: #c9d1d9;/);
+    });
+    it("themeDataBlock wraps vars in a :root[data-theme=\"<id\"] selector", () => {
+        const t = getTheme("cyan-neon");
+        const block = themeDataBlock(t);
+        assert.equal(block.startsWith(':root[data-theme="cyan-neon"]{ '), true);
+        assert.equal(block.endsWith(" }"), true);
+        assert.ok(block.includes("--accent: #22d3ee;"));
+    });
+});

package/dist/src/game/scoring.js

@@ -0,0 +1,105 @@
+/** Canonical allow-list of game metrics (mirrors the schema CHECK constraint). */
+export const METRICS = [
+    "cache",
+    "dedupe",
+    "turns",
+    "repos",
+    "mega_cache",
+];
+/**
+ * Player level as a function of completed turns.
+ * Sequence: n=0→1, 1→2, 2→2, 3→3, 4→3, 7→4, 15→5, ...
+ * i.e. floor(log2(n+1)) + 1 (one level per doubling of turns). Defensive: any
+ * non-finite / negative input collapses to level 1 (never throws, never NaN).
+ */
+export function turnLevel(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return 1;
+    return Math.floor(Math.log2(n + 1)) + 1;
+}
+/**
+ * MEGA CACHE trigger test: the cache hit-rate (real ratio, may exceed 100%)
+ * has crossed the 100% threshold. Used to award the mega_cache trophy + arm
+ * the widget flare (the oopsie gag).
+ */
+export function isMegaCache(pct) {
+    return Number.isFinite(pct) && pct >= 100;
+}
+/**
+ * Cache-hit percentage (0..100+). Returns 0 when there are no lookups so the
+ * ratio can never be NaN / Infinity (QA3). Safe against non-finite inputs.
+ */
+export function cacheScore(hits, lookups) {
+    if (!Number.isFinite(hits) || !Number.isFinite(lookups))
+        return 0;
+    return lookups > 0 ? (hits / lookups) * 100 : 0;
+}
+/**
+ * The 9 achievements (8 visible + 1 hidden easter egg = Opie's Wild Ride).
+ * Seeded idempotently into the `game_achievements` table on first open
+ * (schema.ts). Pure, pi-agnostic — no I/O.
+ */
+export const ACHIEVEMENT_DEFS = [
+    { id: "first_compact", title: "First Compact", description: "Compact a conversation once.", hidden: false, icon: "\u{1F476}" },
+    { id: "compact_streak", title: "Compact Streak", description: "Compact 5 times in one session.", hidden: false, icon: "\u{1F525}" },
+    { id: "turn_veteran", title: "Turn Veteran", description: "Reach 25 turns in a repo.", hidden: false, icon: "\u{1F3C3}" },
+    { id: "level_five", title: "Level 5", description: "Reach player level 5.", hidden: false, icon: "\u{2B50}" },
+    { id: "dedupe_master", title: "Dedupe Master", description: "Collapse 100 chunks total.", hidden: false, icon: "\u{1F5DC}\u{FE0F}" },
+    { id: "repo_explorer", title: "Repo Explorer", description: "Use game mode across 3 repos.", hidden: false, icon: "\u{1F30D}" },
+    { id: "night_owl", title: "Night Owl", description: "Record a score after midnight (00:00–05:00 local).", hidden: false, icon: "\u{1F989}" },
+    { id: "flawless", title: "Flawless", description: "Hit exactly 100% cache with no overshoot.", hidden: false, icon: "\u{1F4AF}" },
+    { id: "opie_wild_ride", title: "Opie's Wild Ride", description: "Push the cache past 100%.", hidden: true, icon: "\u{1F3C6}" },
+];
+/**
+ * Max `compactCount` carried in a dedupe row's `meta` (S33 records
+ * `{ compactCount }` on each session_compact). Returns 0 when absent.
+ */
+export function maxCompactCount(rows) {
+    return rows.reduce((m, r) => {
+        const meta = r.meta;
+        const cm = meta && typeof meta === "object" && "compactCount" in meta
+            ? Number(meta.compactCount) || 0
+            : 0;
+        return Math.max(m, cm);
+    }, 0);
+}
+/**
+ * Pure evaluation of the 9 achievements against the leaderboard aggregates.
+ * `alreadyUnlocked` is the set of ids already persisted (so `newlyUnlocked`
+ * excludes them). No I/O, no pi types. Mirrors the S35.9 condition table.
+ */
+export function evaluateAchievements(ctx, alreadyUnlocked) {
+    const sumBy = (rows) => rows.reduce((s, r) => s + (Number(r.value) || 0), 0);
+    const maxBy = (rows) => rows.reduce((m, r) => Math.max(m, Number(r.value) || 0), 0);
+    const dedupeSum = sumBy(ctx.dedupe);
+    const maxTurns = maxBy(ctx.turns);
+    const maxCache = maxBy(ctx.cache);
+    const maxCompact = maxCompactCount(ctx.dedupe);
+    // Night owl: any row (across all metrics) recorded between 00:00–05:00 local.
+    const allTs = [
+        ...ctx.dedupe,
+        ...ctx.turns,
+        ...ctx.cache,
+        ...ctx.megaCache,
+    ];
+    const nightOwl = allTs.some((r) => {
+        const h = new Date(Number(r.ts) || 0).getHours();
+        return h >= 0 && h < 5;
+    });
+    // Flawless: cache hit 100%+, but NO mega_cache overshoot (>100).
+    const megaOvershoot = ctx.megaCache.some((r) => Number(r.value) > 100);
+    const conditions = {
+        first_compact: ctx.dedupe.length >= 1,
+        compact_streak: maxCompact >= 5,
+        turn_veteran: maxTurns >= 25,
+        level_five: turnLevel(maxTurns) >= 5,
+        dedupe_master: dedupeSum >= 100,
+        repo_explorer: ctx.reposCount >= 3,
+        night_owl: nightOwl,
+        flawless: maxCache >= 100 && !megaOvershoot,
+        opie_wild_ride: ctx.megaCache.length >= 1,
+    };
+    const unlocked = Object.keys(conditions).filter((id) => conditions[id]);
+    const newlyUnlocked = unlocked.filter((id) => !alreadyUnlocked.includes(id));
+    return { unlocked, newlyUnlocked };
+}