dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/tui/src/canvas.js

@@ -0,0 +1,370 @@
+// @dexterm/tui — cell-buffer canvas with plain, ANSI (24-bit / 256 / none) and HTML emitters.
+// Every glyph drawn is single-column (box drawing, blocks, braille, half-width katakana), so x == column.
+//
+// Two masks make the cyberspace practicality rules mechanical (VISUAL-V2 §3):
+//   `hard[i]`  set by put() for any data glyph (digits, letters, $ % ▲ ▼ …) unless the writer says
+//              `soft: true` (borders, blocks, braille, rain). Effects write through putFx(), which
+//              refuses hard cells and non-blank cells: no effect can overdraw a number by construction.
+//   `zone[i]`  1 = band/gutter (full-brightness rain), 2 = panel interior (dim rain), 0 = never rains.
+//              Screens opt areas in with rainZone(); widgets opt the area under their last row in.
+// `headings` are rects (box titles, logo, section caps) that may take the chromatic colour split.
+import { hexToRgb, hexToAnsi256, mix } from "./color.js";
+export const ATTR_BOLD = 1;
+export const ATTR_DIM = 2;
+export const ATTR_ITALIC = 4;
+export const ATTR_UNDERLINE = 8;
+/** Data glyphs: anything carrying a value or a label the trader reads. Effects never overdraw these. */
+const HARD_RE = /[0-9A-Za-z$%+\-.,:/…₀-₉▲▼✓✗●◐○•›↳⏎⌕◉◌✦#§'"?!()<>=×_|]/;
+export function isHardGlyph(ch) { return HARD_RE.test(ch); }
+/** SGR sequence for one cell style at the given depth. Exported so the flusher shares it. */
+export function sgr(fg, bg, at, depth) {
+    let seq = '\x1b[0';
+    if (at & ATTR_BOLD)
+        seq += ';1';
+    if (at & ATTR_DIM)
+        seq += ';2';
+    if (at & ATTR_ITALIC)
+        seq += ';3';
+    if (at & ATTR_UNDERLINE)
+        seq += ';4';
+    if (depth === 'truecolor') {
+        const [r, g, b] = hexToRgb(fg);
+        const [r2, g2, b2] = hexToRgb(bg);
+        seq += `;38;2;${r};${g};${b};48;2;${r2};${g2};${b2}`;
+    }
+    else if (depth === '256') {
+        seq += `;38;5;${hexToAnsi256(fg)};48;5;${hexToAnsi256(bg)}`;
+    }
+    return seq + 'm';
+}
+export class Canvas {
+    w;
+    h;
+    theme;
+    ch;
+    fg;
+    bg;
+    /** bit0 bold, bit1 dim, bit2 italic, bit3 underline */
+    at;
+    /** 1 = data glyph; effects never touch it. */
+    hard;
+    /** 0 never rains, 1 band/gutter (bright), 2 panel interior (dim). */
+    zone;
+    /** Heading rects eligible for the chromatic colour split. */
+    headings;
+    /**
+     * task-1340: 1 = a cell NO effect may touch at all (the trade ticket in every phase, the caps line, the result
+     * card): putFx / tintFx refuse it, datamosh skips it as source and destination, scanlines skip it, and the
+     * whole-frame shake is disabled while any shield exists. `shields` keeps the rects for tests.
+     */
+    shield;
+    shields;
+    /**
+     * task-1326: image slots recorded by coinImage() when `imageMode` is 'pixels' — cell boxes a pixel
+     * protocol (kitty / iTerm2 / sixel) paints over after the flush. Empty in 'cells' mode (block art is
+     * drawn straight into the cells). Not part of the plain/ANSI emitters.
+     */
+    images;
+    imageMode;
+    constructor(w, h, theme) {
+        this.w = w;
+        this.h = h;
+        this.theme = theme;
+        const n = w * h;
+        this.ch = new Array(n).fill(' ');
+        this.fg = new Array(n).fill(theme.text);
+        this.bg = new Array(n).fill(theme.bg);
+        this.at = new Uint8Array(n);
+        this.hard = new Uint8Array(n);
+        this.zone = new Uint8Array(n);
+        this.headings = [];
+        this.shield = new Uint8Array(n);
+        this.shields = [];
+        this.images = [];
+        this.imageMode = 'cells';
+    }
+    idx(x, y) { return y * this.w + x; }
+    /** Copy every buffer of `src` (same size) into this canvas. */
+    copyFrom(src) {
+        this.ch = src.ch.slice();
+        this.fg = src.fg.slice();
+        this.bg = src.bg.slice();
+        this.at = src.at.slice();
+        this.hard = src.hard.slice();
+        this.zone = src.zone.slice();
+        this.headings = src.headings.slice();
+        this.shield = src.shield.slice();
+        this.shields = src.shields.slice();
+        this.images = src.images.slice();
+        this.imageMode = src.imageMode;
+    }
+    put(x, y, ch, st = {}) {
+        if (x < 0 || y < 0 || x >= this.w || y >= this.h)
+            return;
+        const i = this.idx(x, y);
+        this.ch[i] = ch;
+        if (st.fg)
+            this.fg[i] = st.fg;
+        if (st.bg)
+            this.bg[i] = st.bg;
+        this.at[i] = (st.b ? ATTR_BOLD : 0) | (st.d ? ATTR_DIM : 0) | (st.i ? ATTR_ITALIC : 0) | (st.u ? ATTR_UNDERLINE : 0);
+        this.hard[i] = st.soft ? 0 : (st.hard || HARD_RE.test(ch)) ? 1 : 0;
+    }
+    /** Effects-only writer: refuses hard cells, non-blank cells (unless `overwrite`) and, with needZone, cells outside rain zones. */
+    putFx(x, y, ch, st = {}, needZone = false) {
+        if (x < 0 || y < 0 || x >= this.w || y >= this.h)
+            return false;
+        const i = this.idx(x, y);
+        if (this.hard[i] || this.shield[i])
+            return false;
+        if (needZone && !this.zone[i])
+            return false;
+        if (this.ch[i] !== ' ' && !st.overwrite)
+            return false;
+        this.ch[i] = ch;
+        if (st.fg)
+            this.fg[i] = st.fg;
+        if (st.bg)
+            this.bg[i] = st.bg;
+        this.at[i] = (st.b ? ATTR_BOLD : 0) | (st.d ? ATTR_DIM : 0);
+        return true;
+    }
+    /** Effects-only background tint (task-1340): refuses hard and shielded cells, so a number's contrast never moves. */
+    tintFx(x, y, color, amount) {
+        if (x < 0 || y < 0 || x >= this.w || y >= this.h)
+            return false;
+        const i = this.idx(x, y);
+        if (this.hard[i] || this.shield[i])
+            return false;
+        this.bg[i] = mix(this.bg[i], color, amount);
+        return true;
+    }
+    /** Shield a rect from every effect pass (task-1340: the trade ticket). */
+    shieldRect(x, y, w, h) {
+        this.shields.push({ x, y, w, h });
+        for (let j = 0; j < h; j++)
+            for (let k = 0; k < w; k++) {
+                const xx = x + k, yy = y + j;
+                if (xx < 0 || yy < 0 || xx >= this.w || yy >= this.h)
+                    continue;
+                this.shield[this.idx(xx, yy)] = 1;
+            }
+    }
+    get hasShield() { return this.shields.length > 0; }
+    /** Draw text left-aligned at (x, y), clipped to maxW columns. Returns the x after the text. */
+    text(x, y, str, st = {}, maxW = Infinity) {
+        const s = String(str);
+        const lim = Math.min(s.length, maxW);
+        for (let k = 0; k < lim; k++)
+            this.put(x + k, y, s[k], st);
+        return x + lim;
+    }
+    /** Right-aligned text within [x, x+w). */
+    textR(x, y, w, str, st = {}) {
+        const s = String(str).slice(0, w);
+        return this.text(x + w - s.length, y, s, st);
+    }
+    /** Centered text within [x, x+w). */
+    textC(x, y, w, str, st = {}) {
+        const s = String(str).slice(0, w);
+        return this.text(x + Math.floor((w - s.length) / 2), y, s, st);
+    }
+    fill(x, y, w, h, ch = ' ', st = {}) {
+        for (let j = 0; j < h; j++)
+            for (let k = 0; k < w; k++)
+                this.put(x + k, y + j, ch, st);
+    }
+    /** Paint background only, keep glyphs. */
+    shade(x, y, w, h, bg) {
+        for (let j = 0; j < h; j++) {
+            for (let k = 0; k < w; k++) {
+                const xx = x + k, yy = y + j;
+                if (xx < 0 || yy < 0 || xx >= this.w || yy >= this.h)
+                    continue;
+                this.bg[this.idx(xx, yy)] = bg;
+            }
+        }
+    }
+    /** Mark a rect as rain-eligible. kind 1 = band/gutter (full brightness), 2 = panel interior (dim). Only blank cells rain. */
+    rainZone(x, y, w, h, kind = 1) {
+        for (let j = 0; j < h; j++) {
+            for (let k = 0; k < w; k++) {
+                const xx = x + k, yy = y + j;
+                if (xx < 0 || yy < 0 || xx >= this.w || yy >= this.h)
+                    continue;
+                this.zone[this.idx(xx, yy)] = kind;
+            }
+        }
+    }
+    /** Clear the rain mask over a rect (logos, status boxes, toasts). */
+    noRain(x, y, w, h) {
+        for (let j = 0; j < h; j++) {
+            for (let k = 0; k < w; k++) {
+                const xx = x + k, yy = y + j;
+                if (xx < 0 || yy < 0 || xx >= this.w || yy >= this.h)
+                    continue;
+                this.zone[this.idx(xx, yy)] = 0;
+            }
+        }
+    }
+    /** Record a heading rect so fx can chromatic-aberrate it (ghost glyphs land only in blank neighbours). */
+    heading(x, y, w) { this.headings.push({ x, y, w, h: 1 }); }
+    hline(x, y, w, st = {}, ch = '─') { for (let k = 0; k < w; k++)
+        this.put(x + k, y, ch, st); }
+    vline(x, y, h, st = {}, ch = '│') { for (let k = 0; k < h; k++)
+        this.put(x, y + k, ch, st); }
+    /** Panel box with optional title and right-side caption. Returns the inner rect. */
+    box(x, y, w, h, opts = {}) {
+        const t = this.theme;
+        const bg = opts.bg || t.panel;
+        const bc = opts.focus ? t.borderFocus : (opts.border || t.border);
+        const st = { fg: bc, bg };
+        this.fill(x, y, w, h, ' ', { bg });
+        const r = opts.rounded !== false;
+        this.put(x, y, r ? '╭' : '┌', st);
+        this.put(x + w - 1, y, r ? '╮' : '┐', st);
+        this.put(x, y + h - 1, r ? '╰' : '└', st);
+        this.put(x + w - 1, y + h - 1, r ? '╯' : '┘', st);
+        this.hline(x + 1, y, w - 2, st);
+        this.hline(x + 1, y + h - 1, w - 2, st);
+        this.vline(x, y + 1, h - 2, st);
+        this.vline(x + w - 1, y + 1, h - 2, st);
+        const title = opts.title ? ` ${opts.title} ` : '';
+        const cap = opts.caption ? ` ${opts.caption} ` : '';
+        // Title always wins; caption is dropped when both do not fit.
+        const showCap = cap && (title.length + cap.length + 6 <= w);
+        if (title) {
+            this.text(x + 2, y, title, { fg: opts.focus ? t.borderFocus : (opts.titleFg || t.text), bg, b: true }, w - 4);
+            if (!opts.plain)
+                this.heading(x + 2, y, Math.min(title.length, w - 4));
+        }
+        if (showCap)
+            this.text(x + w - 2 - cap.length, y, cap, { fg: opts.captionFg || t.muted, bg }, w - 4);
+        return { x: x + 1, y: y + 1, w: w - 2, h: h - 2, bg };
+    }
+    // ---------- emitters ----------
+    /** One row as plain text, trailing whitespace trimmed. */
+    rowPlain(y) {
+        let line = '';
+        for (let x = 0; x < this.w; x++)
+            line += this.ch[this.idx(x, y)];
+        return line.replace(/\s+$/, '');
+    }
+    /** Monochrome text render (the snapshot-test surface). */
+    toPlain() {
+        const rows = [];
+        for (let y = 0; y < this.h; y++)
+            rows.push(this.rowPlain(y));
+        return rows.join('\n');
+    }
+    /** One row as ANSI with a trailing reset; styles are re-emitted at the start of the row. */
+    rowAnsi(y, depth = 'truecolor') {
+        let row = '';
+        let pfg = null, pbg = null, pat = -1;
+        for (let x = 0; x < this.w; x++) {
+            const i = this.idx(x, y);
+            const fg = this.fg[i], bg = this.bg[i], at = this.at[i];
+            if (depth === 'none') {
+                // Colors dropped; attributes still carry emphasis. Collapse color-only changes.
+                if (at !== pat) {
+                    row += sgr(fg, bg, at, depth);
+                    pat = at;
+                }
+            }
+            else if (fg !== pfg || bg !== pbg || at !== pat) {
+                row += sgr(fg, bg, at, depth);
+                pfg = fg;
+                pbg = bg;
+                pat = at;
+            }
+            row += this.ch[i];
+        }
+        return row + '\x1b[0m';
+    }
+    /** Full-frame ANSI render. */
+    toAnsi({ home = false, depth = 'truecolor' } = {}) {
+        let out = home ? '\x1b[H' : '';
+        for (let y = 0; y < this.h; y++) {
+            out += this.rowAnsi(y, depth) + (y < this.h - 1 ? '\n' : '');
+        }
+        return out;
+    }
+    /**
+     * Standalone HTML page (screenshots, design review, video frames). Cell-exact: per-cell fg/bg only,
+     * every run pinned to `N ch` so a glyph that falls back to another font cannot shift the grid.
+     */
+    toHtml({ title = 'dexterm', fontPx = 15, chrome = true, fit = null, depth = 'truecolor' } = {}) {
+        const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+        const t = this.theme;
+        // 256-colour proof: map each hex to the xterm cube/grey entry its SGR index would select
+        const pal = (hex) => {
+            if (depth !== '256')
+                return hex;
+            const i = hexToAnsi256(hex);
+            if (i >= 232) {
+                const v = 8 + 10 * (i - 232);
+                return '#' + [v, v, v].map((n) => n.toString(16).padStart(2, '0')).join('');
+            }
+            const k = i - 16, cube = [0, 95, 135, 175, 215, 255];
+            return '#' + [cube[Math.floor(k / 36)], cube[Math.floor(k / 6) % 6], cube[k % 6]].map((n) => n.toString(16).padStart(2, '0')).join('');
+        };
+        let body = '';
+        for (let y = 0; y < this.h; y++) {
+            let run = '', pk = null, line = '';
+            const flush = () => {
+                if (!run || pk === null)
+                    return;
+                const [fg, bg, at] = pk.split('|');
+                const a = Number(at);
+                let style = `color:${fg};background:${bg};width:${run.length}ch;overflow:hidden;`;
+                if (a & ATTR_BOLD)
+                    style += 'font-weight:700;';
+                if (a & ATTR_DIM)
+                    style += 'opacity:.6;';
+                if (a & ATTR_ITALIC)
+                    style += 'font-style:italic;';
+                if (a & ATTR_UNDERLINE)
+                    style += 'text-decoration:underline;';
+                line += `<span style="${style}">${esc(run)}</span>`;
+                run = '';
+            };
+            for (let x = 0; x < this.w; x++) {
+                const i = this.idx(x, y);
+                const k = `${pal(this.fg[i])}|${pal(this.bg[i])}|${this.at[i]}`;
+                if (k !== pk) {
+                    flush();
+                    pk = k;
+                }
+                run += this.ch[i];
+            }
+            flush();
+            body += line + '\n';
+        }
+        const lh = Math.round(fontPx * 1.3);
+        const font = `font-family:'JetBrains Mono','SF Mono',Menlo,Monaco,'Cascadia Code',monospace;font-size:${fontPx}px;line-height:${lh}px;font-variant-ligatures:none;`;
+        if (fit) {
+            return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+  html,body{margin:0;padding:0;background:${t.bg};width:${fit.width}px;height:${fit.height}px;overflow:hidden;}
+  body{display:flex;align-items:center;justify-content:center;}
+  pre{margin:0;${font}background:${t.bg};color:${t.text};white-space:pre;}
+  pre span{display:inline-block;height:${lh}px;vertical-align:top;}
+</style></head><body><pre>${body}</pre></body></html>`;
+        }
+        const chromeHtml = chrome
+            ? `<div class="bar"><span class="dot r"></span><span class="dot y"></span><span class="dot g"></span><span class="ttl">${esc(title)}</span></div>`
+            : '';
+        return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+  html,body{margin:0;padding:0;background:#05070a;}
+  body{padding:28px;display:inline-block;}
+  .win{display:inline-block;border-radius:12px;overflow:hidden;box-shadow:0 30px 80px rgba(0,0,0,.6),0 0 0 1px rgba(255,255,255,.06);background:${t.bg};}
+  .bar{height:34px;background:${t.headBg};display:flex;align-items:center;padding:0 14px;gap:8px;border-bottom:1px solid ${t.border};}
+  .dot{width:12px;height:12px;border-radius:50%;display:inline-block}
+  .dot.r{background:#ff5f57}.dot.y{background:#febc2e}.dot.g{background:#28c840}
+  .ttl{margin-left:auto;margin-right:auto;color:${t.muted};font:500 12px -apple-system,'SF Pro Text',Inter,system-ui,sans-serif;letter-spacing:.2px}
+  pre{margin:0;padding:10px 12px 12px 12px;${font}background:${t.bg};color:${t.text};white-space:pre;}
+  pre span{display:inline-block;height:${lh}px;vertical-align:top;}
+</style></head><body><div class="win">${chromeHtml}<pre>${body}</pre></div></body></html>`;
+    }
+}

package/dist/packages/tui/src/chrome.js

@@ -0,0 +1,85 @@
+import { keyHints, dirGlyph } from "./widgets.js";
+import { fmtPct, clock } from "./fmt.js";
+import { mix } from "./color.js";
+export const SCREENS = [
+    { key: 'screener', label: 'Screener', hot: '1' },
+    { key: 'newpairs', label: 'New pairs', hot: '2' },
+    { key: 'watchlist', label: 'Watchlist', hot: '3' },
+    { key: 'analyst', label: 'Analyst', hot: '4' },
+];
+export function header(c, m) {
+    const t = c.theme;
+    const bg = t.headBg;
+    c.fill(0, 0, c.w, 1, ' ', { bg });
+    // right status cluster (computed first so tabs never collide with it)
+    const solStr = m.sol ? `SOL $${m.sol.price.toFixed(2)} ` : '';
+    const chgStr = m.sol ? dirGlyph(m.sol.chg24) + fmtPct(Math.abs(m.sol.chg24), { sign: false }) : '';
+    const live = m.status ?? (m.paused ? '◌ paused' : m.calm ? '◉ live · calm' : '◉ live');
+    const feed = c.w >= 150 ? ` ${m.feedLabel || 'dexscreener · jup · gecko · rugcheck'}   ` : '';
+    const clk = clock(m.now, m.timeZone);
+    const rightW = feed.length + solStr.length + chgStr.length + (m.sol ? 2 : 0) + live.length + 2 + clk.length + 1;
+    let rx = c.w - rightW;
+    if (feed)
+        rx = c.text(rx, 0, feed, { fg: t.dim, bg });
+    if (m.sol) {
+        rx = c.text(rx, 0, solStr, { fg: t.muted, bg });
+        rx = c.text(rx, 0, chgStr, { fg: m.sol.chg24 >= 0 ? t.up : t.down, bg });
+        rx = c.text(rx, 0, '  ', { bg });
+    }
+    rx = c.text(rx, 0, live, { fg: m.status ? t.warn : m.paused ? t.warn : t.up, bg, b: true });
+    rx = c.text(rx, 0, '  ', { bg });
+    c.text(rx, 0, clk, { fg: t.muted, bg });
+    const limit = c.w - rightW - 1;
+    // logo: "dex" phosphor, "term" white, both bold; registered as a heading so it chromatic-aberrates
+    let x = c.text(1, 0, ' dex', { fg: t.borderFocus, bg, b: true });
+    x = c.text(x, 0, 'term ', { fg: t.text, bg, b: true });
+    c.heading(2, 0, 7);
+    x = c.text(x, 0, '┃ ', { fg: t.border, bg, soft: true });
+    const compact = c.w < 110;
+    for (const s of SCREENS) {
+        const active = s.key === m.screen || ((m.screen === 'token' || m.screen === 'ticket') && s.key === 'screener');
+        const label = compact ? ` ${s.hot} ${s.label.split(' ')[0]} ` : ` ${s.hot} ${s.label} `;
+        if (x + label.length > limit)
+            break;
+        if (active) {
+            x = c.text(x, 0, label, { fg: t.borderFocus, bg: t.tabActiveBg, b: true });
+            c.put(x, 0, '▌', { fg: t.tabActiveBg, bg, soft: true });
+            x += 1;
+        }
+        else {
+            x = c.text(x, 0, label, { fg: t.muted, bg });
+            x += 1;
+        }
+    }
+    // blank middle of the header + the band under it are rain zones
+    c.rainZone(x, 0, Math.max(0, c.w - rightW - x - 1), 1, 1);
+    c.fill(0, 1, c.w, 1, ' ', { bg: t.bg });
+    c.rainZone(0, 1, c.w, 1, 1);
+}
+export function footer(c, hints, themeName, calm = false) {
+    const t = c.theme;
+    const y = c.h - 1;
+    c.fill(0, y, c.w, 1, ' ', { bg: t.headBg });
+    const right = ` ${themeName}${calm ? ' · calm' : ''} · ${c.w}×${c.h} `;
+    const end = keyHints(c, 1, y, c.w - right.length - 2, hints, t.headBg);
+    // Prototype parity: the label is drawn at the last column and clipped (fix queued for D-19).
+    c.textR(c.w - 1, y, right.length, right, { fg: t.dim, bg: t.headBg });
+    c.rainZone(end, y, Math.max(0, c.w - right.length - 1 - end), 1, 1);
+}
+/** Toast (bottom-right, above the footer). */
+export function toast(c, tst) {
+    if (!tst)
+        return;
+    const t = c.theme;
+    const { text, level } = tst;
+    const color = level === 'up' ? t.up : level === 'down' ? t.down : level === 'warn' ? t.warn : level === 'ai' ? t.ai : t.accent;
+    const w = Math.min(c.w - 4, text.length + 4);
+    const x = c.w - w - 1, y = c.h - 4;
+    const bg = mix(t.bg, color, 0.14);
+    c.fill(x, y, w, 3, ' ', { bg });
+    c.noRain(x, y, w, 3);
+    c.hline(x, y, w, { fg: color, bg, soft: true }, '▔');
+    c.hline(x, y + 2, w, { fg: color, bg, soft: true }, '▁');
+    c.text(x + 2, y + 1, text, { fg: t.text, bg, b: true }, w - 4);
+    c.put(x, y + 1, '▌', { fg: color, bg, soft: true });
+}

package/dist/packages/tui/src/color.js

@@ -0,0 +1,133 @@
+// @dexterm/tui — color math and terminal color-depth detection.
+// Colors are hex strings ('#rrggbb') everywhere in the theme and the canvas; the emitters
+// convert them to 24-bit SGR, the nearest xterm-256 index, or drop them (NO_COLOR).
+const hexCache = new Map();
+export function hexToRgb(hex) {
+    let v = hexCache.get(hex);
+    if (v)
+        return v;
+    const h = hex.replace('#', '');
+    v = [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+    hexCache.set(hex, v);
+    return v;
+}
+export function rgbToHex(r, g, b) {
+    return '#' + [r, g, b].map((n) => Math.max(0, Math.min(255, n)).toString(16).padStart(2, '0')).join('');
+}
+const mixCache = new Map();
+/** Linear blend of two hex colors; t = 0 returns a, t = 1 returns b. Memoised on the exact t: the rain mixes thousands of cells per frame. */
+export function mix(a, b, t) {
+    const key = a + b + t;
+    const hit = mixCache.get(key);
+    if (hit !== undefined)
+        return hit;
+    const [r1, g1, b1] = hexToRgb(a);
+    const [r2, g2, b2] = hexToRgb(b);
+    const r = Math.round(r1 + (r2 - r1) * t);
+    const g = Math.round(g1 + (g2 - g1) * t);
+    const bb = Math.round(b1 + (b2 - b1) * t);
+    const out = '#' + [r, g, bb].map((n) => n.toString(16).padStart(2, '0')).join('');
+    if (mixCache.size > 50_000)
+        mixCache.clear();
+    mixCache.set(key, out);
+    return out;
+}
+const lumCache = new Map();
+/** WCAG 2.x relative luminance of a hex colour (0 black .. 1 white). */
+export function luminance(hex) {
+    const hit = lumCache.get(hex);
+    if (hit !== undefined)
+        return hit;
+    const [r, g, b] = hexToRgb(hex).map((c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; });
+    const v = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+    lumCache.set(hex, v);
+    return v;
+}
+/** WCAG contrast ratio between two colours (1 .. 21). The readability gate wants ≥ 4.5 for every numeric cell. */
+export function contrast(fg, bg) {
+    const a = luminance(fg), b = luminance(bg);
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+// xterm-256 palette: 16 system colors (not used as targets, their RGB varies per terminal),
+// a 6×6×6 cube (16..231) and a 24-step gray ramp (232..255).
+const CUBE = [0, 95, 135, 175, 215, 255];
+function nearestCubeIndex(v) {
+    let best = 0;
+    let bestD = Infinity;
+    for (let i = 0; i < CUBE.length; i++) {
+        const d = Math.abs(CUBE[i] - v);
+        if (d < bestD) {
+            bestD = d;
+            best = i;
+        }
+    }
+    return best;
+}
+const ansi256Cache = new Map();
+/** Nearest xterm-256 color index (16..255) for a hex color. */
+export function hexToAnsi256(hex) {
+    const cached = ansi256Cache.get(hex);
+    if (cached !== undefined)
+        return cached;
+    const [r, g, b] = hexToRgb(hex);
+    const ri = nearestCubeIndex(r), gi = nearestCubeIndex(g), bi = nearestCubeIndex(b);
+    const cubeIdx = 16 + 36 * ri + 6 * gi + bi;
+    const cubeD = (CUBE[ri] - r) ** 2 + (CUBE[gi] - g) ** 2 + (CUBE[bi] - b) ** 2;
+    // gray ramp: 232 + i has value 8 + 10*i
+    const avg = Math.round((r + g + b) / 3);
+    const gi2 = Math.max(0, Math.min(23, Math.round((avg - 8) / 10)));
+    const gv = 8 + 10 * gi2;
+    const grayD = (gv - r) ** 2 + (gv - g) ** 2 + (gv - b) ** 2;
+    const idx = grayD < cubeD ? 232 + gi2 : cubeIdx;
+    ansi256Cache.set(hex, idx);
+    return idx;
+}
+/**
+ * Decide the color depth from the environment (SPEC §7.1):
+ * NO_COLOR wins; COLORTERM=truecolor/24bit or a known 24-bit terminal gives truecolor;
+ * a 256color TERM gives 256; anything else falls back to 256 (every modern terminal has it)
+ * unless TERM is dumb.
+ */
+export function detectColorDepth(env = process.env, isTTY = true) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== '')
+        return 'none';
+    const force = env.FORCE_COLOR;
+    if (force !== undefined && force !== '') {
+        if (force === '0')
+            return 'none';
+        if (force === '3')
+            return 'truecolor';
+        if (force === '2' || force === '1')
+            return '256';
+    }
+    if (!isTTY)
+        return 'none';
+    const term = (env.TERM || '').toLowerCase();
+    if (term === 'dumb')
+        return 'none';
+    const ct = (env.COLORTERM || '').toLowerCase();
+    if (ct === 'truecolor' || ct === '24bit')
+        return 'truecolor';
+    const prog = (env.TERM_PROGRAM || '').toLowerCase();
+    if (['iterm.app', 'wezterm', 'ghostty', 'vscode', 'hyper', 'alacritty', 'kitty', 'rio', 'tabby'].includes(prog))
+        return 'truecolor';
+    if (env.WT_SESSION)
+        return 'truecolor';
+    if (term.includes('truecolor') || term.includes('24bit') || term.startsWith('xterm-kitty') || term.startsWith('wezterm') || term.startsWith('alacritty'))
+        return 'truecolor';
+    if (term.includes('256color') || prog === 'apple_terminal')
+        return '256';
+    return '256';
+}
+export function parseColorDepth(s) {
+    if (!s)
+        return undefined;
+    const v = s.toLowerCase();
+    if (v === 'truecolor' || v === '24bit' || v === '24-bit' || v === '16m')
+        return 'truecolor';
+    if (v === '256' || v === 'ansi256')
+        return '256';
+    if (v === 'none' || v === 'no' || v === 'off' || v === 'mono')
+        return 'none';
+    return undefined;
+}

package/dist/packages/tui/src/flush.js

@@ -0,0 +1,62 @@
+export class Flusher {
+    prev = null;
+    prevW = -1;
+    prevH = -1;
+    dirty = true;
+    depth;
+    hideCursor;
+    constructor(opts = {}) {
+        this.depth = opts.depth ?? 'truecolor';
+        this.hideCursor = opts.hideCursor ?? true;
+    }
+    /** Force the next flush to repaint every row. */
+    invalidate() { this.dirty = true; }
+    /** Compute the delta against the previous frame. Does not write anywhere. */
+    diff(c) {
+        const rows = new Array(c.h);
+        for (let y = 0; y < c.h; y++)
+            rows[y] = c.rowAnsi(y, this.depth);
+        const full = this.dirty || this.prev === null || this.prevW !== c.w || this.prevH !== c.h;
+        let out = '';
+        let n = 0;
+        const changed = new Array(c.h).fill(false);
+        if (full) {
+            out += '\x1b[H';
+            if (this.prev !== null && (this.prevW !== c.w || this.prevH !== c.h))
+                out += '\x1b[2J';
+            for (let y = 0; y < c.h; y++) {
+                out += `\x1b[${y + 1};1H` + rows[y];
+                changed[y] = true;
+                n++;
+            }
+        }
+        else {
+            const prev = this.prev;
+            for (let y = 0; y < c.h; y++) {
+                if (rows[y] === prev[y])
+                    continue;
+                out += `\x1b[${y + 1};1H` + rows[y];
+                changed[y] = true;
+                n++;
+            }
+        }
+        if (out && this.hideCursor)
+            out = '\x1b[?25l' + out;
+        this.prev = rows;
+        this.prevW = c.w;
+        this.prevH = c.h;
+        this.dirty = false;
+        return { out, rows: n, full, changed };
+    }
+    /** Diff and write to `write` (e.g. process.stdout.write). Returns the result for callers that count rows. */
+    flush(c, write) {
+        const r = this.diff(c);
+        if (r.out)
+            write(r.out);
+        return r;
+    }
+}
+/** Enter the alternate screen, clear it, hide the cursor. */
+export const ENTER_SCREEN = '\x1b[?1049h\x1b[H\x1b[2J\x1b[?25l';
+/** Reset attributes, show the cursor, leave the alternate screen. */
+export const LEAVE_SCREEN = '\x1b[0m\x1b[?25h\x1b[?1049l';