dsh-neotui 0.0.0

package/src/screen.js

@@ -0,0 +1,215 @@
+// screen.js — Cell-grid framebuffer with ANSI diff rendering.
+import { wcwidth } from "./text.js";
+
+export const ATTR = { BOLD: 1, DIM: 2, ITALIC: 4, UNDERLINE: 8, REVERSE: 16, STRIKE: 32 };
+
+let CELL_COUNTER = 0;
+function blank() {
+  CELL_COUNTER++;
+  return { ch: " ", fg: -1, bg: -1, attrs: 0, wide: false, link: "" };
+}
+
+export class Screen {
+  constructor(w, h) {
+    this.w = w; this.h = h;
+    this.prev = null;
+    this.cells = [];
+    this.resize(w, h);
+  }
+
+  resize(w, h) {
+    this.w = w; this.h = h;
+    this.cells = new Array(h);
+    for (let y = 0; y < h; y++) {
+      const row = new Array(w);
+      for (let x = 0; x < w; x++) row[x] = blank();
+      this.cells[y] = row;
+    }
+    this.prev = null;
+  }
+
+  clear(fg = -1, bg = -1) {
+    for (let y = 0; y < this.h; y++)
+      for (let x = 0; x < this.w; x++) {
+        const c = this.cells[y][x];
+        c.ch = " "; c.fg = fg; c.bg = bg; c.attrs = 0; c.wide = false; c.link = "";
+      }
+  }
+
+  /** Set one cell. Wide chars consume two columns; x+1 becomes a continuation. */
+  put(x, y, ch = " ", { fg = -1, bg = -1, attrs = 0, link = "" } = {}) {
+    if (y < 0 || y >= this.h || x < 0 || x >= this.w) return;
+    // A glyph drawn over a wide char's continuation cell clips that wide char
+    // (nvim-style): the overlay wins, and the wide char's left half is cleared
+    // so the terminal never renders a half-glyph that "eats" the border.
+    if (x > 0) {
+      const left = this.cells[y][x - 1];
+      if (left.wide) {
+        left.ch = " ";
+        left.wide = false;
+        left.link = "";
+      }
+    }
+    const cell = this.cells[y][x];
+    const wide = wcwidth(ch.codePointAt(0)) === 2;
+    if (wide && x + 1 >= this.w) ch = " "; // clip wide char at the right edge (terminal wrap corruption)
+    cell.ch = ch; cell.fg = fg; cell.bg = bg; cell.attrs = attrs; cell.link = link;
+    cell.wide = wide && x + 1 < this.w;
+    if (cell.wide) {
+      const cont = this.cells[y][x + 1];
+      // If x+1 was itself a wide char (spanning x+1..x+2), clear its right half.
+      if (cont.wide && x + 2 < this.w) {
+        const next = this.cells[y][x + 2];
+        next.ch = " "; next.wide = false; next.link = "";
+      }
+      cont.ch = ""; cont.fg = fg; cont.bg = bg; cont.attrs = attrs; cont.link = link; cont.wide = false;
+    }
+  }
+
+  /** Write text; wide-aware; clips at right edge. Returns final x. */
+  text(x, y, s, style = {}) {
+    let px = x;
+    for (const ch of s) {
+      const cw = wcwidth(ch.codePointAt(0));
+      if (cw === 0) continue;
+      if (px >= this.w) break;
+      if (cw === 2 && px + 1 >= this.w) break; // wide char needs both columns
+      this.put(px, y, ch, style);
+      px += cw;
+    }
+    return px;
+  }
+
+  fillRect(x0, y0, x1, y1, ch = " ", style = {}) {
+    for (let y = y0; y <= y1; y++)
+      for (let x = x0; x <= x1; x++) this.put(x, y, ch, style);
+  }
+
+  box(x0, y0, x1, y1, style = {}, title = "") {
+    const { fg, bg = -1 } = style;
+    const s = { fg, bg };
+    for (let x = x0; x <= x1; x++) {
+      this.put(x, y0, "─", s);
+      this.put(x, y1, "─", s);
+    }
+    for (let y = y0; y <= y1; y++) {
+      this.put(x0, y, "│", s);
+      this.put(x1, y, "│", s);
+    }
+    this.put(x0, y0, "╭", s); this.put(x1, y0, "╮", s);
+    this.put(x0, y1, "╰", s); this.put(x1, y1, "╯", s);
+    if (title) this.text(x0 + 2, y0, " " + title + " ", s);
+  }
+
+  hline(x0, x1, y, ch = "─", style = {}) {
+    for (let x = x0; x <= x1; x++) this.put(x, y, ch, style);
+  }
+
+  /** Apply reverse-video over a rect (drag-selection highlight). */
+  invertRect(x0, y0, x1, y1) {
+    for (let y = Math.max(0, y0); y <= Math.min(this.h - 1, y1); y++)
+      for (let x = Math.max(0, x0); x <= Math.min(this.w - 1, x1); x++) {
+        const c = this.cells[y][x];
+        if (c.ch !== " " && c.ch !== "") c.attrs |= ATTR.REVERSE;
+      }
+  }
+
+  vline(x, y0, y1, ch = "│", style = {}) {
+    for (let y = y0; y <= y1; y++) this.put(x, y, ch, style);
+  }
+
+  // ---- ANSI diff rendering ----
+
+  sgr(fg, bg, attrs) {
+    const parts = [];
+    if (attrs !== 0) {
+      const bold = attrs & ATTR.BOLD ? ";1" : "";
+      const dim = attrs & ATTR.DIM ? ";2" : "";
+      const ital = attrs & ATTR.ITALIC ? ";3" : "";
+      const ul = attrs & ATTR.UNDERLINE ? ";4" : "";
+      const rev = attrs & ATTR.REVERSE ? ";7" : "";
+      const str = attrs & ATTR.STRIKE ? ";9" : "";
+      parts.push(`\x1b[0${bold}${dim}${ital}${ul}${rev}${str}m`);
+    }
+    if (fg >= 0) parts.push(`\x1b[38;2;${(fg >> 16) & 255};${(fg >> 8) & 255};${fg & 255}m`);
+    if (bg >= 0) parts.push(`\x1b[48;2;${(bg >> 16) & 255};${(bg >> 8) & 255};${bg & 255}m`);
+    return parts.join("");
+  }
+
+  /** Render diff versus previous frame. Returns ANSI string (no final flush). */
+  render() {
+    const prev = this.prev;
+    const out = [];
+    let curFg = -1, curBg = -1, curAttrs = 0, curLink = "";
+    const ensureStyle = (fg, bg, attrs) => {
+      if (fg === curFg && bg === curBg && attrs === curAttrs) return;
+      // Any component returning to default while another stays styled needs a
+      // full reset first, or the terminal keeps the previous background
+      // (the classic scroll-smear bug).
+      const needReset = (bg === -1 && curBg !== -1) || (fg === -1 && curFg !== -1) || (attrs === 0 && curAttrs !== 0);
+      curFg = fg; curBg = bg; curAttrs = attrs;
+      if (fg === -1 && bg === -1 && attrs === 0) {
+        out.push("\x1b[0m");
+        return;
+      }
+      if (needReset) out.push("\x1b[0m");
+      out.push(this.sgr(fg, bg, attrs));
+    };
+    const ensureLink = (link) => {
+      if (link !== curLink) {
+        if (curLink) out.push("\x1b]8;;\x1b\\");
+        if (link) out.push(`\x1b]8;;${link}\x1b\\`);
+        curLink = link;
+      }
+    };
+    for (let y = 0; y < this.h; y++) {
+      const row = this.cells[y];
+      const prow = prev ? prev[y] : null;
+      let x = 0;
+      while (x < this.w) {
+        const c = row[x];
+        const p = prow ? prow[x] : null;
+        let dirty = !p || p.ch !== c.ch || p.fg !== c.fg || p.bg !== c.bg || p.attrs !== c.attrs || p.link !== c.link || p.wide !== c.wide;
+        // Wide-char atomicity: if the wide glyph spans x,x+1 and its right half
+        // was clobbered in the previous frame (e.g. an overlay border overwrote
+        // the continuation cell), redraw the whole glyph so the char reappears.
+        if (!dirty && c.wide && prow && x + 1 < this.w) {
+          const p2 = prow[x + 1];
+          if (p2 && p2.ch !== "") dirty = true;
+        }
+        if (!dirty) { x++; continue; }
+        out.push(`\x1b[${y + 1};${x + 1}H`);
+        ensureStyle(c.fg, c.bg, c.attrs);
+        ensureLink(c.link);
+        out.push(c.ch === "" ? " " : c.ch);
+        if (c.wide) x += 2; else x++;
+      }
+    }
+    if (curLink) out.push("\x1b]8;;\x1b\\");
+    out.push(`\x1b[${this.h};1H`);
+    this.prev = this.cells;
+    this.cells = new Array(this.h);
+    for (let y = 0; y < this.h; y++) {
+      const row = new Array(this.w);
+      for (let x = 0; x < this.w; x++) row[x] = blank();
+      this.cells[y] = row;
+    }
+    return out.join("");
+  }
+
+  /** Plain-text dump (no ANSI) for scripted tests. Reads the last rendered frame. */
+  toPlain() {
+    const cells = this.prev ?? this.cells;
+    const lines = [];
+    for (let y = 0; y < this.h; y++) {
+      let s = "";
+      const row = cells[y] ?? [];
+      for (let x = 0; x < this.w; x++) {
+        const c = row[x];
+        s += c && c.ch !== "" ? c.ch : " ";
+      }
+      lines.push(s.replace(/\s+$/, ""));
+    }
+    return lines.join("\n");
+  }
+}

package/src/term.js

@@ -0,0 +1,270 @@
+// term.js — Raw-mode terminal: alternate screen, SGR mouse (1000/1002/1003/1006),
+// bracketed paste, kitty keyboard (best-effort), key + mouse event decoding.
+import { StringDecoder } from "node:string_decoder";
+
+export function detectKitty(env = process.env) {
+  return Boolean(env.KITTY_WINDOW_ID || env.TERM_PROGRAM === "WezTerm" || /kitty/i.test(env.TERM ?? ""));
+}
+
+const KEY_NAMES = {
+  A: "up", B: "down", C: "right", D: "left", H: "home", F: "end", P: "f1", Q: "f2",
+  R: "f3", S: "f4",
+};
+const TILDE_NAMES = {
+  1: "home", 2: "insert", 3: "delete", 4: "end", 5: "pgup", 6: "pgdn",
+  7: "home", 8: "end", 11: "f1", 12: "f2", 13: "f3", 14: "f4", 15: "f5",
+  17: "f6", 18: "f7", 19: "f8", 20: "f9", 21: "f10", 23: "f11", 24: "f12",
+};
+const KITTY_KEY_NAMES = {
+  13: "enter", 9: "tab", 27: "escape", 127: "backspace",
+  57344: "f1", 57345: "f2", 57346: "f3", 57347: "f4", 57348: "f5", 57349: "f6",
+  57350: "f7", 57351: "f8", 57352: "f9", 57353: "f10", 57354: "f11", 57355: "f12",
+  57356: "insert", 57357: "delete", 57358: "home", 57359: "end", 57360: "pgup", 57361: "pgdn",
+  57362: "up", 57363: "down", 57364: "right", 57365: "left",
+};
+
+export class Term {
+  constructor({ input = process.stdin, output = process.stdout, onEvent, onResize, kitty = false } = {}) {
+    this.input = input; this.output = output;
+    this.onEvent = onEvent ?? (() => {});
+    this.onResize = onResize ?? (() => {});
+    this.kitty = kitty;
+    this.decoder = new StringDecoder("utf8");
+    this.buf = "";
+    this.started = false;
+    this.pasteBuf = null;
+    this.w = (output.columns || 80); this.h = (output.rows || 24);
+  }
+
+  start() {
+    if (this.started) return;
+    this.started = true;
+    if (typeof this.input.setRawMode === "function") this.input.setRawMode(true);
+    this.input.resume();
+    this.input.on("data", (chunk) => this.#feed(this.decoder.write(chunk)));
+    const o = this.output;
+    o.write("\x1b[?1049h"); // alt screen
+    o.write("\x1b[?25l");   // hide cursor
+    o.write("\x1b[?1000h"); // mouse: clicks
+    o.write("\x1b[?1002h"); // mouse: drag
+    o.write("\x1b[?1003h"); // mouse: all motion
+    o.write("\x1b[?1006h"); // SGR extended coordinates
+    o.write("\x1b[?2004h"); // bracketed paste
+    o.write("\x1b[?7l");    // no autowrap (we clip ourselves)
+    if (this.kitty) o.write("\x1b[>1u"); // kitty: disambiguate escape codes
+    this.resizeHandler = () => this.#resize();
+    process.on("SIGWINCH", this.resizeHandler);
+    this.#resize();
+  }
+
+  stop() {
+    if (!this.started) return;
+    this.started = false;
+    const o = this.output;
+    o.write("\x1b[?7h\x1b[?2004l\x1b[?1006l\x1b[?1003l\x1b[?1002l\x1b[?1000l\x1b[?25h\x1b[?1049l");
+    if (this.kitty) o.write("\x1b[<u");
+    process.off("SIGWINCH", this.resizeHandler);
+    this.input.pause();
+    if (typeof this.input.setRawMode === "function") this.input.setRawMode(false);
+  }
+
+  #resize() {
+    const w = this.output.columns || process.stdout.columns || 80;
+    const h = this.output.rows || process.stdout.rows || 24;
+    if (w !== this.w || h !== this.h) {
+      this.w = w; this.h = h;
+      this.onResize(w, h);
+    }
+  }
+
+  #emit(ev) { this.onEvent(ev); }
+
+  #feed(s) {
+    if (!s) return;
+    this.buf += s;
+    this.#parse();
+  }
+
+  #parse() {
+    const buf = this.buf;
+    let i = 0;
+    while (i < buf.length) {
+      const ch = buf[i];
+      if (ch === "\x1b") {
+        // escape sequence
+        const next = buf[i + 1];
+        if (next === "[") {
+          const r = this.#parseCsi(buf, i + 2);
+          if (r === null) { i = buf.length; break; } // incomplete
+          i = r.next;
+        } else if (next === "O") {
+          const fin = buf[i + 2];
+          if (fin === undefined) { i = buf.length; break; }
+          const name = KEY_NAMES[fin];
+          if (name) this.#emit({ type: "key", name, ctrl: false, alt: false, shift: false });
+          i += 3;
+        } else if (next === "]") {
+          // OSC: skip to BEL or ST
+          let j = i + 2;
+          while (j < buf.length) {
+            if (buf[j] === "\x07") { j++; break; }
+            if (buf[j] === "\x1b" && buf[j + 1] === "\\") { j += 2; break; }
+            j++;
+          }
+          if (j > buf.length && buf[buf.length - 1] !== "\x07") { i = buf.length; break; }
+          i = j;
+        } else if (next === "P" || next === "X" || next === "^" || next === "_") {
+          // DCS / SOS / PM / APC: skip to ST (or BEL)
+          let j = i + 2;
+          while (j < buf.length) {
+            if (buf[j] === "\x07") { j++; break; }
+            if (buf[j] === "\x1b" && buf[j + 1] === "\\") { j += 2; break; }
+            j++;
+          }
+          i = j;
+        } else if (next !== undefined) {
+          // ESC + char = alt key
+          const cp = next.codePointAt(0);
+          if (cp === 13) this.#emit({ type: "key", name: "enter", ctrl: false, alt: true, shift: false });
+          else this.#emit({ type: "key", name: "char", key: next.toLowerCase(), text: next, ctrl: false, alt: true, shift: false });
+          i += 2;
+        } else { i = buf.length; break; }
+      } else if (ch === "\r") {
+        this.#emit({ type: "key", name: "enter", ctrl: false, alt: false, shift: false });
+        i++;
+      } else if (ch === "\n") {
+        // LF in raw mode = Ctrl+J (insert newline), distinct from Enter (CR).
+        this.#emit({ type: "key", name: "char", key: "j", text: "j", ctrl: true, alt: false, shift: false });
+        i++;
+      } else if (ch === "\t") {
+        this.#emit({ type: "key", name: "tab", ctrl: false, alt: false, shift: false });
+        i++;
+      } else if (ch === "\x7f") {
+        this.#emit({ type: "key", name: "backspace", ctrl: false, alt: false, shift: false });
+        i++;
+      } else {
+        const cp = ch.codePointAt(0);
+        if (cp < 32) {
+          if (cp === 0) {
+            // NUL: legacy Ctrl+Space encoding (xterm/WezTerm without kitty protocol)
+            this.#emit({ type: "key", name: "char", key: " ", text: " ", ctrl: true, alt: false, shift: false });
+          } else {
+            // ctrl+letter
+            const key = String.fromCharCode(cp + 96);
+            this.#emit({ type: "key", name: "char", key, text: key, ctrl: true, alt: false, shift: false });
+          }
+          i++;
+        } else {
+          // text run: collect until next ESC/control
+          let j = i;
+          while (j < buf.length) {
+            const c = buf.codePointAt(j);
+            if (c === 27 || c < 32) break;
+            j += c > 0xffff ? 2 : 1;
+          }
+          this.#emit({ type: "text", text: buf.slice(i, j) });
+          i = j;
+        }
+      }
+    }
+    this.buf = buf.slice(i);
+  }
+
+  /** Parse CSI starting after "\x1b[". Returns {next} or null when incomplete. */
+  #parseCsi(buf, start) {
+    let i = start;
+    let prefix = "";
+    const first = buf[i];
+    if (first === "<" || first === ">" || first === "?" || first === "=") { prefix = first; i++; }
+    let params = "";
+    while (i < buf.length) {
+      const c = buf[i];
+      const cc = c.charCodeAt(0);
+      if ((cc >= 0x30 && cc <= 0x39) || c === ";" || c === ":" || c === " ") { params += c; i++; continue; }
+      if (cc >= 0x40 && cc <= 0x7e) {
+        this.#dispatchCsi(prefix, params, c);
+        return { next: i + 1 };
+      }
+      if (cc === 0x1b || cc < 32) {
+        // Malformed; drop and resync from here
+        return { next: i };
+      }
+      return null; // incomplete (wait for final byte)
+    }
+    return null;
+  }
+
+  #dispatchCsi(prefix, params, final) {
+    if (prefix === "<") {
+      this.#mouse(params, final);
+      return;
+    }
+    if (prefix === "?") return; // private responses (cursor pos, kitty flags) — ignored
+    if (prefix === ">") return;
+    if (final === "Z") { // Shift+Tab (backtab)
+      this.#emit({ type: "key", name: "backtab", ctrl: false, alt: false, shift: true });
+      return;
+    }
+    if (final === "u") {
+      this.#kittyKey(params);
+      return;
+    }
+    const nums = params.split(";").filter((s) => s !== "").map(Number);
+    if (final === "~") {
+      // xterm modifyOtherKeys: CSI 27;mod;code~ → the code with modifiers
+      if (nums.length >= 3 && nums[0] === 27) {
+        const code = nums[2] ?? 0;
+        const mod = nums[1] ?? 1;
+        const ctrl = !!(mod - 1 & 4), alt = !!(mod - 1 & 2), shift = !!(mod - 1 & 1);
+        let text = "";
+        try { text = String.fromCodePoint(code); } catch { return; }
+        this.#emit({ type: "key", name: "char", key: text.toLowerCase(), text, ctrl, alt, shift });
+        return;
+      }
+      const [n = 0, mod = 1] = nums;
+      const name = TILDE_NAMES[n];
+      if (!name) return;
+      const ctrl = !!(mod - 1 & 4), alt = !!(mod - 1 & 2), shift = !!(mod - 1 & 1);
+      this.#emit({ type: "key", name, ctrl, alt, shift });
+      return;
+    }
+    const name = KEY_NAMES[final];
+    if (!name) return;
+    // modifier is the last param before the final byte (e.g. CSI 1;5A)
+    const mod = nums.length > 1 ? nums[nums.length - 1] : 1;
+    const ctrl = !!(mod - 1 & 4), alt = !!(mod - 1 & 2), shift = !!(mod - 1 & 1);
+    this.#emit({ type: "key", name, ctrl, alt, shift });
+  }
+
+  #kittyKey(params) {
+    const [cp = 0, mod = 1] = params.split(";").filter((s) => s !== "").map(Number);
+    const ctrl = !!(mod & 4), alt = !!(mod & 2), shift = !!(mod & 1);
+    let name = KITTY_KEY_NAMES[cp];
+    if (name === "tab" && shift) name = "backtab";
+    if (name) {
+      this.#emit({ type: "key", name, ctrl, alt, shift });
+      return;
+    }
+    let text;
+    try { text = String.fromCodePoint(cp); } catch { return; }
+    if (ctrl && /^[a-zA-Z]$/.test(text)) text = text.toLowerCase();
+    this.#emit({ type: "key", name: "char", key: text.toLowerCase(), text, ctrl, alt, shift });
+  }
+
+  #mouse(params, final) {
+    const [b = 0, x = 0, y = 0] = params.split(";").filter((s) => s !== "").map(Number);
+    const kind = final === "M" ? "press" : "release";
+    const motion = !!(b & 32);
+    const wheel = !!(b & 64);
+    const button = b & 3; // 0 left, 1 middle, 2 right
+    let ev;
+    if (wheel) {
+      ev = { type: "mouse", kind: button === 0 ? "wheel-up" : "wheel-down", button: button === 0 ? 4 : 5, x: x - 1, y: y - 1, ctrl: !!(b & 16), shift: !!(b & 4), alt: !!(b & 8), motion: false };
+    } else if (motion) {
+      ev = { type: "mouse", kind: button === 3 ? "release" : "drag", button: button === 3 ? 0 : button, x: x - 1, y: y - 1, ctrl: !!(b & 16), shift: !!(b & 4), alt: !!(b & 8), motion: true };
+    } else {
+      ev = { type: "mouse", kind, button, x: x - 1, y: y - 1, ctrl: !!(b & 16), shift: !!(b & 4), alt: !!(b & 8), motion: false };
+    }
+    this.#emit(ev);
+  }
+}

package/src/text.js

@@ -0,0 +1,110 @@
+// text.js — Unicode width, truncation, braille bitmaps, color helpers.
+// Zero external dependencies.
+
+/** Display width of one code point (approximate wcwidth). */
+export function wcwidth(cp) {
+  if (cp === 0) return 0;
+  // Combining marks and zero-width formatting
+  if (
+    (cp >= 0x0300 && cp <= 0x036f) || (cp >= 0x1ab0 && cp <= 0x1aff) ||
+    (cp >= 0x1dc0 && cp <= 0x1dff) || (cp >= 0x20d0 && cp <= 0x20ff) ||
+    (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0xfe20 && cp <= 0xfe2f) ||
+    (cp >= 0x200b && cp <= 0x200f) || cp === 0x2060 || cp === 0x00ad
+  ) return 0;
+  // Controls (rendered as placeholders by the screen layer)
+  if (cp < 32 || (cp >= 0x7f && cp < 0xa0)) return 0;
+  // Wide (CJK + fullwidth + emoji ranges)
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || cp === 0x2329 || cp === 0x232a ||
+    (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe10 && cp <= 0xfe19) || (cp >= 0xfe30 && cp <= 0xfe6f) ||
+    (cp >= 0xff00 && cp <= 0xff60) || (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) || (cp >= 0x20000 && cp <= 0x3fffd)
+  ) return 2;
+  return 1;
+}
+
+export function strWidth(s) {
+  let w = 0;
+  for (const ch of s) w += wcwidth(ch.codePointAt(0));
+  return w;
+}
+
+/** Truncate to display width; appends '…' when cut. */
+export function truncate(s, w) {
+  if (w <= 0) return "";
+  const ell = "…";
+  if (strWidth(s) <= w) return s;
+  let out = "", used = 0;
+  for (const ch of s) {
+    const cw = wcwidth(ch.codePointAt(0));
+    if (used + cw > w - 1) break;
+    out += ch; used += cw;
+  }
+  return out + ell;
+}
+
+/** Pad with spaces to exact display width (assumes strWidth(s) <= w). */
+export function pad(s, w, align = "left") {
+  const gap = w - strWidth(s);
+  if (gap <= 0) return s;
+  const sp = " ".repeat(gap);
+  return align === "right" ? sp + s : s + sp;
+}
+
+export function hexRgb(hex) {
+  const m = /^#?([0-9a-f]{6})$/i.exec(String(hex).trim());
+  if (!m) return null;
+  const v = parseInt(m[1], 16);
+  return [(v >> 16) & 255, (v >> 8) & 255, v & 255];
+}
+
+/** Blend rgb → 256-color palette index (for degradable terminals). */
+export function rgb256(r, g, b) {
+  if (r === g && g === b) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return Math.round((r - 8) / 10) + 232;
+  }
+  const ri = Math.round((r / 255) * 5), gi = Math.round((g / 255) * 5), bi = Math.round((b / 255) * 5);
+  return 16 + 36 * ri + 6 * gi + bi;
+}
+
+// ---- Braille (2 cols × 4 rows per character cell) ----
+// col: array of up to 4 booleans, index 0 = top dot.
+
+const BRAILLE_BASE = 0x2800;
+
+export function brailleCell(left, right) {
+  let bits = 0;
+  for (let y = 0; y < 4; y++) {
+    if (left[y]) bits |= 1 << y;        // dots 1..4 (left column)
+    if (right[y]) bits |= 1 << (y + 3); // dots 4..8 (right column)
+  }
+  return String.fromCodePoint(BRAILLE_BASE + bits);
+}
+
+/** cols: array of columns (each an array of booleans, 0=top). Returns braille string. */
+export function brailleLine(cols) {
+  let out = "";
+  for (let i = 0; i < cols.length; i += 2) {
+    out += brailleCell(cols[i] ?? [], cols[i + 1] ?? []);
+  }
+  return out;
+}
+
+/** Bars: given values 0..1 and width, produce block-glyph column string. */
+export function bars(values, width, { min = 0, max = 1 } = {}) {
+  const out = [];
+  for (let i = 0; i < width; i++) {
+    const t = values[i] ?? 0;
+    const v = Math.max(0, Math.min(1, (t - min) / (max - min)));
+    let eighths = Math.round(v * 8);
+    if (v > 0 && eighths <= 0) eighths = 1;   // visible sliver for tiny fractions
+    if (eighths <= 0) out.push(" ");
+    else if (eighths < 8) out.push(String.fromCodePoint(0x2581 + eighths - 1));
+    else out.push("█");
+  }
+  return out.join("");
+}

package/src/theme.js

@@ -0,0 +1,90 @@
+// theme.js — Named terminal palettes. All UI code reads through the live
+// proxy T; switching themes takes effect on the next frame render.
+export const THEMES = {
+  dark: {
+    name: "dark",
+    BG: 0x12151a, BG2: 0x161a20, PANEL: 0x1c2128, STATUSBG: 0x1f242b, CARD: 0x181d24,
+    USERBG: 0x22262e, THINKBG: 0x181b20, TOOLBG: 0x1e1e2e, TOOLOK: 0x1e2e1e, TOOLERR: 0x2e1e1e,
+    BORDER: 0x2a323c, BORDER2: 0x3a424c,
+    TXT: 0xd4d8dd, DIM: 0x8b939e, FAINT: 0x5c6670, BOLD: 0xffffff,
+    ACCENT: 0x67b7ff, ACCENT2: 0x4d9fff, HEADING: 0x7cc7ff,
+    LINK: 0x67b7ff, CODE: 0x9ce5ed, CODEBG: 0x1c2128,
+    OK: 0x7dde86, WARN: 0xf5c96b, ERR: 0xff7a7a,
+    PURPLE: 0x9f86ff, RED: 0xff8a8a, GREEN: 0x8adf95, PINK: 0xffb3b3, GREENG: 0xb3e6b8,
+    KEYWORD: 0xc792ea, STRING: 0x98c379, NUMBER: 0xd19a66,
+    TABLEHEAD: 0xf2f4f6, TABLESEP: 0x3a424c, QUOTE: 0x8b949e, QUOTEFG: 0xc7ccd1,
+    SELBG: 0x3a4a5c, SELFG: 0xffffff, CURSORBG: 0x3a4a5c, CURSORFG: 0xffffff,
+    MENUBG: 0x1c2128, MENUSEL: 0x3a4a5c, SCROLLTHUMB: 0x67b7ff, SCROLLTRACK: 0x2a323c,
+  },
+  light: {
+    name: "light",
+    BG: 0xf6f6f6, BG2: 0xf0f0f0, PANEL: 0xffffff, STATUSBG: 0xe8e8e8, CARD: 0xffffff,
+    USERBG: 0xececec, THINKBG: 0xf2f2f2, TOOLBG: 0xe9edf7, TOOLOK: 0xe9f4e9, TOOLERR: 0xf7e9e9,
+    BORDER: 0xd4d4d4, BORDER2: 0xc0c0c0,
+    TXT: 0x2a2a2a, DIM: 0x666666, FAINT: 0x999999, BOLD: 0x000000,
+    ACCENT: 0x0a5fd7, ACCENT2: 0x0a5fd7, HEADING: 0x0a5fd7,
+    LINK: 0x0a5fd7, CODE: 0x9a2b6e, CODEBG: 0xf0f0f0,
+    OK: 0x1f8a3d, WARN: 0xa86a00, ERR: 0xd02222,
+    PURPLE: 0x6a3fd0, RED: 0xd02222, GREEN: 0x1f8a3d, PINK: 0xc05060, GREENG: 0x2a8a4a,
+    KEYWORD: 0x7c2fc0, STRING: 0x1f6f3d, NUMBER: 0xa05a00,
+    TABLEHEAD: 0x111111, TABLESEP: 0xc0c0c0, QUOTE: 0x777777, QUOTEFG: 0x444444,
+    SELBG: 0xcfe4ff, SELFG: 0x000000, CURSORBG: 0xcfe4ff, CURSORFG: 0x000000,
+    MENUBG: 0xffffff, MENUSEL: 0xcfe4ff, SCROLLTHUMB: 0x0a5fd7, SCROLLTRACK: 0xd4d4d4,
+  },
+  gruvbox: {
+    name: "gruvbox",
+    BG: 0x282828, BG2: 0x242424, PANEL: 0x32302f, STATUSBG: 0x32302f, CARD: 0x32302f,
+    USERBG: 0x3c3836, THINKBG: 0x2e2b28, TOOLBG: 0x2f3a3c, TOOLOK: 0x333c33, TOOLERR: 0x3c3232,
+    BORDER: 0x504945, BORDER2: 0x665c54,
+    TXT: 0xebdbb2, DIM: 0xa89984, FAINT: 0x7c6f64, BOLD: 0xfbf1c7,
+    ACCENT: 0x83a598, ACCENT2: 0x8ec07c, HEADING: 0x8ec07c,
+    LINK: 0x83a598, CODE: 0x8ec07c, CODEBG: 0x3c3836,
+    OK: 0xb8bb26, WARN: 0xfabd2f, ERR: 0xfb4934,
+    PURPLE: 0xd3869b, RED: 0xfb4934, GREEN: 0xb8bb26, PINK: 0xd3869b, GREENG: 0xb8bb26,
+    KEYWORD: 0xd3869b, STRING: 0xb8bb26, NUMBER: 0xd65d0e,
+    TABLEHEAD: 0xfbf1c7, TABLESEP: 0x665c54, QUOTE: 0xa89984, QUOTEFG: 0xebdbb2,
+    SELBG: 0x504945, SELFG: 0xfbf1c7, CURSORBG: 0x665c54, CURSORFG: 0xfbf1c7,
+    MENUBG: 0x32302f, MENUSEL: 0x504945, SCROLLTHUMB: 0x83a598, SCROLLTRACK: 0x504945,
+  },
+};
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function themeFile() {
+  const base = process.env.DSH_HOME ?? (process.env.XDG_CONFIG_HOME ?? join(process.env.HOME ?? ".", ".config"));
+  return join(base, "tui-theme.txt");
+}
+
+let current = "dark";
+const ORDER = ["dark", "light", "gruvbox"];
+
+try {
+  const saved = readFileSync(themeFile(), "utf8").trim();
+  if (THEMES[saved]) current = saved;
+} catch { /* first run */ }
+
+/** Live theme accessor: T.ACCENT etc. reads the active palette. */
+export const T = new Proxy({}, {
+  get(_t, key) { return THEMES[current][key]; },
+});
+
+function persist() {
+  try {
+    mkdirSync(dirname(themeFile()), { recursive: true });
+    writeFileSync(themeFile(), current + "\n");
+  } catch {}
+}
+
+export function setTheme(name) {
+  if (THEMES[name]) { current = name; persist(); return true; }
+  return false;
+}
+
+export function cycleTheme() {
+  current = ORDER[(ORDER.indexOf(current) + 1) % ORDER.length];
+  persist();
+  return current;
+}
+
+export function themeName() { return current; }