novac 2.0.1 → 2.2.0

package/novac/kits/libterm/kitdef.js

@@ -0,0 +1,1927 @@
+'use strict';
+
+/**
+ * ╔═══════════════════════════════════════════════════════════════════════════╗
+ * ║                          kitdef.js  v1.0                                 ║
+ * ║                                                                           ║
+ * ║  A complete terminal application kit in a single CJS module.             ║
+ * ║                                                                           ║
+ * ║  Subsystems                                                               ║
+ * ║  ─────────────────────────────────────────────────────────────────────── ║
+ * ║  tview   TVPixel, TView, InputManager  — pixel-grid rendering engine     ║
+ * ║  tshell  TShell   — spawn / pipe / interact with child processes         ║
+ * ║  tenv    TEnv     — typed env-var config with validation & defaults      ║
+ * ║  tlog    TLog     — levelled logger that streams into a TView            ║
+ * ║  ttheme  TTheme   — named colour/style token system with dark/light      ║
+ * ║  twidget TWidget  — higher-level widgets (menu, list, dialog, input…)    ║
+ * ║  trouter TRouter  — keyboard-driven "screen router" (push/pop/replace)   ║
+ * ║                                                                           ║
+ * ║  Top-level export                                                         ║
+ * ║  ─────────────────────────────────────────────────────────────────────── ║
+ * ║  Terminal — one object that boots everything and wires it together        ║
+ * ║                                                                           ║
+ * ║  Usage                                                                    ║
+ * ║    const { kitdef } = require('./kitdef');                                ║
+ * ║    const { Terminal, TView, TShell, TEnv, TLog,                          ║
+ * ║            TTheme, TWidget, TRouter } = kitdef;                           ║
+ * ╚═══════════════════════════════════════════════════════════════════════════╝
+ */
+
+const { EventEmitter }          = require('events');
+const { spawn, spawnSync }      = require('child_process');
+const fs                        = require('fs');
+const path                      = require('path');
+const os                        = require('os');
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §1  ANSI / colour primitives
+// ═════════════════════════════════════════════════════════════════════════════
+
+const ESC = '\x1b';
+
+const ansi = {
+  reset:         `${ESC}[0m`,
+  clear:         `${ESC}[2J`,
+  clearLine:     `${ESC}[2K`,
+  altScreenOn:   `${ESC}[?1049h`,
+  altScreenOff:  `${ESC}[?1049l`,
+  hideCursor:    `${ESC}[?25l`,
+  showCursor:    `${ESC}[?25h`,
+  cursorHome:    `${ESC}[H`,
+  saveCursor:    `${ESC}[s`,
+  restoreCursor: `${ESC}[u`,
+  mouseOn:       `${ESC}[?1000h${ESC}[?1002h${ESC}[?1006h`,
+  mouseOff:      `${ESC}[?1006l${ESC}[?1002l${ESC}[?1000l`,
+  moveTo:        (r, c)  => `${ESC}[${r};${c}H`,
+  fg256:         n       => `${ESC}[38;5;${n}m`,
+  bg256:         n       => `${ESC}[48;5;${n}m`,
+  fg:            c       => _colorSeq(c, false),
+  bg:            c       => _colorSeq(c, true),
+  bold:          `${ESC}[1m`,
+  dim:           `${ESC}[2m`,
+  italic:        `${ESC}[3m`,
+  underline:     `${ESC}[4m`,
+  blink:         `${ESC}[5m`,
+  reverse:       `${ESC}[7m`,
+  strikethrough: `${ESC}[9m`,
+};
+
+const NAMED_COLORS = {
+  black:0, red:1, green:2, yellow:3, blue:4, magenta:5,
+  cyan:6, white:7, gray:8, grey:8,
+  brightred:9, brightgreen:10, brightyellow:11, brightblue:12,
+  brightmagenta:13, brightcyan:14, brightwhite:15,
+};
+
+function _colorSeq(color, isBg) {
+  if (color == null) return '';
+  const p = isBg ? '48' : '38';
+  if (typeof color === 'string') {
+    const l = color.toLowerCase();
+    if (l === 'default' || l === 'reset') return isBg ? `${ESC}[49m` : `${ESC}[39m`;
+    if (l in NAMED_COLORS) return `${ESC}[${p};5;${NAMED_COLORS[l]}m`;
+    if (/^#[0-9a-f]{6}$/i.test(l)) {
+      const r = parseInt(l.slice(1,3),16), g = parseInt(l.slice(3,5),16), b = parseInt(l.slice(5,7),16);
+      return `${ESC}[${p};2;${r};${g};${b}m`;
+    }
+  }
+  if (Array.isArray(color)) {
+    if (color.length === 3) return `${ESC}[${p};2;${color[0]};${color[1]};${color[2]}m`;
+    if (color.length === 1) return `${ESC}[${p};5;${color[0]}m`;
+  }
+  if (typeof color === 'number') return `${ESC}[${p};5;${color}m`;
+  return '';
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §2  KEY_MAP  (escape sequence → named key)
+// ═════════════════════════════════════════════════════════════════════════════
+
+const KEY_MAP = {
+  '\x1b[A':{name:'up'},    '\x1b[B':{name:'down'},
+  '\x1b[C':{name:'right'}, '\x1b[D':{name:'left'},
+  '\x1b[1;2A':{name:'up',shift:true},   '\x1b[1;2B':{name:'down',shift:true},
+  '\x1b[1;2C':{name:'right',shift:true},'\x1b[1;2D':{name:'left',shift:true},
+  '\x1b[1;5A':{name:'up',ctrl:true},    '\x1b[1;5B':{name:'down',ctrl:true},
+  '\x1b[1;5C':{name:'right',ctrl:true}, '\x1b[1;5D':{name:'left',ctrl:true},
+  '\x1b[1;3A':{name:'up',alt:true},     '\x1b[1;3B':{name:'down',alt:true},
+  '\x1b[1;3C':{name:'right',alt:true},  '\x1b[1;3D':{name:'left',alt:true},
+  '\x1bOP':{name:'f1'},'\x1bOQ':{name:'f2'},'\x1bOR':{name:'f3'},'\x1bOS':{name:'f4'},
+  '\x1b[15~':{name:'f5'},'\x1b[17~':{name:'f6'},'\x1b[18~':{name:'f7'},
+  '\x1b[19~':{name:'f8'},'\x1b[20~':{name:'f9'},'\x1b[21~':{name:'f10'},
+  '\x1b[23~':{name:'f11'},'\x1b[24~':{name:'f12'},
+  '\x1b[H':{name:'home'},'\x1b[F':{name:'end'},
+  '\x1b[5~':{name:'pageup'},'\x1b[6~':{name:'pagedown'},
+  '\x1b[2~':{name:'insert'},'\x1b[3~':{name:'delete'},
+  '\x1b[Z':{name:'tab',shift:true},
+  '\r':{name:'enter'},'\n':{name:'enter'},'\t':{name:'tab'},
+  '\x7f':{name:'backspace'},'\x08':{name:'backspace'},'\x1b':{name:'escape'},
+  '\x01':{name:'a',ctrl:true},'\x02':{name:'b',ctrl:true},'\x03':{name:'c',ctrl:true},
+  '\x04':{name:'d',ctrl:true},'\x05':{name:'e',ctrl:true},'\x06':{name:'f',ctrl:true},
+  '\x07':{name:'g',ctrl:true},'\x0b':{name:'k',ctrl:true},'\x0c':{name:'l',ctrl:true},
+  '\x0e':{name:'n',ctrl:true},'\x0f':{name:'o',ctrl:true},'\x10':{name:'p',ctrl:true},
+  '\x11':{name:'q',ctrl:true},'\x12':{name:'r',ctrl:true},'\x13':{name:'s',ctrl:true},
+  '\x14':{name:'t',ctrl:true},'\x15':{name:'u',ctrl:true},'\x16':{name:'v',ctrl:true},
+  '\x17':{name:'w',ctrl:true},'\x18':{name:'x',ctrl:true},'\x19':{name:'y',ctrl:true},
+  '\x1a':{name:'z',ctrl:true},
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §3  BORDER_STYLES
+// ═════════════════════════════════════════════════════════════════════════════
+
+const BORDER_STYLES = {
+  single:  {tl:'┌',tr:'┐',bl:'└',br:'┘',h:'─',v:'│'},
+  double:  {tl:'╔',tr:'╗',bl:'╚',br:'╝',h:'═',v:'║'},
+  rounded: {tl:'╭',tr:'╮',bl:'╰',br:'╯',h:'─',v:'│'},
+  heavy:   {tl:'┏',tr:'┓',bl:'┗',br:'┛',h:'━',v:'┃'},
+  ascii:   {tl:'+',tr:'+',bl:'+',br:'+',h:'-',v:'|'},
+  none:    {tl:' ',tr:' ',bl:' ',br:' ',h:' ',v:' '},
+};
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §4  tview  —  TVPixel · TView · InputManager
+// ═════════════════════════════════════════════════════════════════════════════
+
+// ── TVPixel ───────────────────────────────────────────────────────────────────
+
+class TVPixel {
+  /**
+   * A single rendered cell.
+   * @param {object} o
+   * @param {string}  [o.char=' ']       display character
+   * @param {boolean} [o.isStatic=false] writes ignored when true
+   * @param {*}       [o.color]          [fg,bg] pair or single fg
+   * @param {string}  [o.style]          bold|dim|italic|underline|blink|reverse|strike
+   */
+  constructor({ char=' ', isStatic=false, color=[null,null], style=null } = {}) {
+    this.char     = String(char).slice(0,1) || ' ';
+    this.isStatic = Boolean(isStatic);
+    if (Array.isArray(color) && color.length === 2) { this.fg=color[0]; this.bg=color[1]; }
+    else { this.fg=color; this.bg=null; }
+    this.style = style;
+  }
+  render() {
+    let o = '';
+    if (this.fg != null) o += ansi.fg(this.fg);
+    if (this.bg != null) o += ansi.bg(this.bg);
+    if (this.style) o += ({bold:ansi.bold,dim:ansi.dim,italic:ansi.italic,
+      underline:ansi.underline,blink:ansi.blink,reverse:ansi.reverse,
+      strike:ansi.strikethrough,strikethrough:ansi.strikethrough})[this.style]||'';
+    return o + this.char + ansi.reset;
+  }
+  clone() { return new TVPixel({char:this.char,isStatic:this.isStatic,color:[this.fg,this.bg],style:this.style}); }
+  set(char) { if (!this.isStatic) this.char = String(char).slice(0,1)||' '; return this; }
+}
+
+// ── InputManager ─────────────────────────────────────────────────────────────
+
+class InputManager extends EventEmitter {
+  constructor() {
+    super();
+    this._views      = [];
+    this._focused    = null;
+    this._mouseOn    = false;
+    this._running    = false;
+    this._buf        = '';
+    this._flushTimer = null;
+    this._lastClick  = {btn:null,row:0,col:0,t:0};
+    this._drag       = {active:false,btn:null,startRow:0,startCol:0,view:null};
+  }
+
+  start(opts = {}) {
+    if (this._running) return this;
+    this._running = true;
+    const stdin = process.stdin;
+    stdin.setEncoding('utf8');
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', this._onData.bind(this));
+    process.stdout.on('resize', this._onTermResize.bind(this));
+    if (opts.mouse !== false) this.enableMouse();
+    return this;
+  }
+
+  stop() {
+    if (!this._running) return this;
+    this._running = false;
+    process.stdin.removeAllListeners('data');
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+    process.stdin.pause();
+    process.stdout.removeAllListeners('resize');
+    if (this._mouseOn) this.disableMouse();
+    return this;
+  }
+
+  enableMouse()  { process.stdout.write(ansi.mouseOn);  this._mouseOn=true;  return this; }
+  disableMouse() { process.stdout.write(ansi.mouseOff); this._mouseOn=false; return this; }
+
+  register(view) {
+    if (!this._views.includes(view)) {
+      this._views.push(view);
+      if (!this._focused) this._focused = view;
+    }
+    return this;
+  }
+
+  unregister(view) {
+    this._views = this._views.filter(v => v !== view);
+    if (this._focused === view) this._focused = this._views[this._views.length-1] ?? null;
+    return this;
+  }
+
+  focus(view) {
+    if (this._focused && this._focused !== view) {
+      this._focused._hasFocus = false;
+      this._focused.emit('blur');
+      this._focused.markDirty?.();
+    }
+    this._focused = view;
+    view._hasFocus = true;
+    view.emit('focus');
+    view.markDirty?.();
+    return this;
+  }
+
+  _onData(raw) {
+    this._buf += raw;
+    clearTimeout(this._flushTimer);
+    if (!this._buf.startsWith(ESC) || this._buf.length > 1) { this._flush(); }
+    else { this._flushTimer = setTimeout(() => this._flush(), 20); }
+  }
+
+  _flush() {
+    while (this._buf.length > 0) {
+      const n = this._parseOne(this._buf);
+      if (n === 0) break;
+      this._buf = this._buf.slice(n);
+    }
+  }
+
+  _parseOne(buf) {
+    // SGR mouse
+    const sgr = buf.match(/^\x1b\[<(\d+);(\d+);(\d+)([Mm])/);
+    if (sgr) { this._dispatchMouse({btn:+sgr[1],col:+sgr[2]-1,row:+sgr[3]-1,release:sgr[4]==='m'}); return sgr[0].length; }
+    // X10 mouse
+    if (buf.startsWith(`${ESC}[M`) && buf.length >= 6) {
+      this._dispatchMouse({btn:buf.charCodeAt(3)-32,col:buf.charCodeAt(4)-33,row:buf.charCodeAt(5)-33,release:(buf.charCodeAt(3)-32&3)===3});
+      return 6;
+    }
+    // Escape sequences / keys
+    if (buf.startsWith(ESC)) {
+      for (let len = Math.min(buf.length,8); len >= 1; len--) {
+        const seq = buf.slice(0,len);
+        if (KEY_MAP[seq]) { this._dispatchKey({sequence:seq,...KEY_MAP[seq]}); return len; }
+      }
+      if (buf.length === 1) { this._dispatchKey({sequence:ESC,name:'escape'}); return 1; }
+      if (buf.length >= 2) return 2;
+      return 0;
+    }
+    const ch = buf[0], def = KEY_MAP[ch];
+    this._dispatchKey(def ? {sequence:ch,...def} : {sequence:ch,name:ch,char:ch});
+    return 1;
+  }
+
+  _dispatchKey(key) {
+    if (key.name === 'c' && key.ctrl) {
+      this.emit('sigint', key);
+      if (this.listenerCount('sigint') <= 1) {
+        if (this._mouseOn) this.disableMouse();
+        process.stdout.write(ansi.showCursor + '\n');
+        process.exit(0);
+      }
+      return;
+    }
+    this.emit('key', key);
+    const f = this._focused;
+    if (!f) return;
+    f.emit('key', key);
+    f.emit(`key:${key.name}`, key);
+    if (key.ctrl)  f.emit(`key:ctrl+${key.name}`, key);
+    if (key.shift) f.emit(`key:shift+${key.name}`, key);
+    if (key.alt)   f.emit(`key:alt+${key.name}`, key);
+    if (['up','down','left','right'].includes(key.name)) {
+      f.emit('arrow', key); f.emit(`arrow:${key.name}`, key);
+    }
+  }
+
+  _dispatchMouse(ev) {
+    const {btn,col,row,release} = ev;
+    const button=btn&3, shift=!!(btn&4), alt=!!(btn&8), ctrl=!!(btn&16);
+    const motion=!!(btn&32), scroll=btn>=64;
+    const base = {col,row,button,shift,alt,ctrl};
+    this.emit('mouse',{...base,type:'raw',btn});
+
+    if (scroll) {
+      const dir = (btn&1)?'down':'up', target = this._hitTest(row,col);
+      const sEv = {...base,type:'scroll',direction:dir};
+      this.emit('scroll',sEv);
+      if (target) { const l=this._toLocal(target,row,col); target.emit('scroll',{...sEv,...l}); target.emit(`scroll:${dir}`,{...sEv,...l}); }
+      return;
+    }
+    if (motion && !release) {
+      const d = this._drag;
+      if (d.active) {
+        const dEv={...base,type:'drag',startRow:d.startRow,startCol:d.startCol,deltaRow:row-d.startRow,deltaCol:col-d.startCol};
+        this.emit('drag',dEv);
+        if (d.view) { const l=this._toLocal(d.view,row,col); d.view.emit('drag',{...dEv,...l}); }
+      } else {
+        const target=this._hitTest(row,col), mEv={...base,type:'mousemove'};
+        this.emit('mousemove',mEv);
+        if (target) { const l=this._toLocal(target,row,col); target.emit('mousemove',{...mEv,...l}); }
+      }
+      return;
+    }
+    if (release) {
+      const d=this._drag;
+      if (d.active) {
+        const dEv={...base,type:'dragend',startRow:d.startRow,startCol:d.startCol,deltaRow:row-d.startRow,deltaCol:col-d.startCol};
+        this.emit('dragend',dEv);
+        if (d.view) { const l=this._toLocal(d.view,row,col); d.view.emit('dragend',{...dEv,...l}); }
+        this._drag.active=false; this._drag.view=null;
+      }
+      const target=this._hitTest(row,col), rEv={...base,type:'mouseup'};
+      this.emit('mouseup',rEv);
+      if (target) { const l=this._toLocal(target,row,col); target.emit('mouseup',{...rEv,...l}); }
+      return;
+    }
+    const target=this._hitTest(row,col);
+    if (target && target !== this._focused) this.focus(target);
+    const now=Date.now(), lc=this._lastClick;
+    const isDbl=(lc.btn===button&&lc.row===row&&lc.col===col&&now-lc.t<400);
+    this._lastClick={btn:button,row,col,t:now};
+    this._drag={active:true,btn:button,startRow:row,startCol:col,view:target};
+    const local=target?this._toLocal(target,row,col):{localRow:row,localCol:col};
+    const type=isDbl?'dblclick':'click';
+    const cEv={...base,type,view:target,...local};
+    this.emit('click',cEv); this.emit(type,cEv);
+    if (target) {
+      target.emit('click',cEv);
+      ['click:left','click:middle','click:right'][button] && target.emit(['click:left','click:middle','click:right'][button],cEv);
+      if (isDbl) target.emit('dblclick',cEv);
+      if (button===2) target.emit('contextmenu',cEv);
+      const pixelObj=target.getPixel?.(local.localRow,local.localCol);
+      if (pixelObj) target.emit('click:pixel',{...cEv,pixel:pixelObj});
+    }
+  }
+
+  _onTermResize() {
+    const cols=process.stdout.columns||80, rows=process.stdout.rows||24;
+    const ev={cols,rows,type:'resize'};
+    this.emit('resize',ev);
+    for (const v of this._views) v.emit('termresize',ev);
+  }
+
+  _hitTest(termRow,termCol) {
+    for (let i=this._views.length-1;i>=0;i--) {
+      const v=this._views[i]; if (v._hidden) continue;
+      const r0=v.offsetRow-1,r1=r0+v.rows-1,c0=v.offsetCol-1,c1=c0+v.cols-1;
+      if (termRow>=r0&&termRow<=r1&&termCol>=c0&&termCol<=c1) return v;
+    }
+    return null;
+  }
+
+  _toLocal(view,row,col) { return {localRow:row-(view.offsetRow-1),localCol:col-(view.offsetCol-1)}; }
+}
+
+const inputManager = new InputManager();
+
+// ── TView ─────────────────────────────────────────────────────────────────────
+
+class TView extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {number}  [opts.rows]
+   * @param {number}  [opts.cols]
+   * @param {number}  [opts.offsetRow=1]
+   * @param {number}  [opts.offsetCol=1]
+   * @param {number}  [opts.fps=30]
+   * @param {string}  [opts.title]
+   * @param {*}       [opts.defaultFg]
+   * @param {*}       [opts.defaultBg]
+   * @param {boolean} [opts.border=false]
+   * @param {string}  [opts.borderStyle='single']
+   * @param {boolean} [opts.scrollable=false]
+   * @param {boolean} [opts.autoResize=false]
+   * @param {boolean} [opts.autoRegister=true]
+   */
+  constructor(opts = {}) {
+    super();
+    const ts = process.stdout;
+    this.rows        = opts.rows        ?? (ts.rows    || 24);
+    this.cols        = opts.cols        ?? (ts.columns || 80);
+    this.offsetRow   = opts.offsetRow   ?? 1;
+    this.offsetCol   = opts.offsetCol   ?? 1;
+    this.fps         = opts.fps         ?? 30;
+    this.title       = opts.title       ?? '';
+    this.defaultBg   = opts.defaultBg   ?? null;
+    this.defaultFg   = opts.defaultFg   ?? null;
+    this.border      = opts.border      ?? false;
+    this.borderStyle = opts.borderStyle ?? 'single';
+    this.scrollable  = opts.scrollable  ?? false;
+    this.autoResize  = opts.autoResize  ?? false;
+    this._scrollOffset = 0;
+    this._altScreen    = false;
+    this._dirty        = true;
+    this._timer        = null;
+    this._hidden       = false;
+    this._hasFocus     = false;
+    this._promptActive = false;
+    this._overlay      = null;
+    this._animations   = [];
+    this._dataBindings = [];
+    this.grid = this._makeGrid(this.rows, this.cols);
+    if (this.autoResize) this.on('termresize',({rows,cols}) => this.resize(rows,cols));
+    if (this.fps > 0) this._startRenderLoop();
+    if (opts.autoRegister !== false) inputManager.register(this);
+  }
+
+  // ── Handler shortcuts ──────────────────────────────────────────────────────
+  onKey(keys, fn) {
+    const pairs = [].concat(keys).map(k => { const ev=`key:${k}`; this.on(ev,fn); return [ev,fn]; });
+    return () => pairs.forEach(([ev,h]) => this.removeListener(ev,h));
+  }
+  onArrow(dir, fn) {
+    const ev = dir==='*'?'arrow':`arrow:${dir}`; this.on(ev,fn); return ()=>this.removeListener(ev,fn);
+  }
+  onClick(fn)      { this.on('click',fn);       return ()=>this.removeListener('click',fn); }
+  onDblClick(fn)   { this.on('dblclick',fn);    return ()=>this.removeListener('dblclick',fn); }
+  onRightClick(fn) { this.on('contextmenu',fn); return ()=>this.removeListener('contextmenu',fn); }
+  onMouseUp(fn)    { this.on('mouseup',fn);     return ()=>this.removeListener('mouseup',fn); }
+  onMouseMove(fn)  { this.on('mousemove',fn);   return ()=>this.removeListener('mousemove',fn); }
+  onDrag(fn)       { this.on('drag',fn);        return ()=>this.removeListener('drag',fn); }
+  onDragEnd(fn)    { this.on('dragend',fn);     return ()=>this.removeListener('dragend',fn); }
+  onScroll(dir, fn) {
+    const ev=dir==='*'?'scroll':`scroll:${dir}`; this.on(ev,fn); return ()=>this.removeListener(ev,fn);
+  }
+  onResize(fn) { this.on('termresize',fn); return ()=>this.removeListener('termresize',fn); }
+  onFocus(fn)  { this.on('focus',fn);      return ()=>this.removeListener('focus',fn); }
+  onBlur(fn)   { this.on('blur',fn);       return ()=>this.removeListener('blur',fn); }
+
+  focus() { inputManager.focus(this); return this; }
+  get focused() { return this._hasFocus; }
+
+  // ── Data binding ───────────────────────────────────────────────────────────
+  bindData(source, event, handler) {
+    const wrapped = data => { handler(data,this); this.markDirty(); };
+    source.on(event, wrapped);
+    this._dataBindings.push({source,event,handler:wrapped});
+    return () => { source.removeListener(event,wrapped); this._dataBindings=this._dataBindings.filter(b=>b.handler!==wrapped); };
+  }
+
+  pipeStream(stream, pixelOpts = {}) {
+    let buf = '';
+    const stop = this.bindData(stream,'data',chunk => {
+      buf += String(chunk);
+      const lines = buf.split('\n'); buf = lines.pop();
+      for (const line of lines) {
+        const row = this.grid.length;
+        this.grid.push(Array.from({length:this.cols},()=>new TVPixel({char:' ',color:[this.defaultFg,this.defaultBg]})));
+        const display = line.replace(/\x1b\[[^m]*m/g,'').slice(0,this.cols);
+        for (let c=0;c<display.length;c++) this.grid[row][c]=new TVPixel({char:display[c],...pixelOpts});
+        if (this.scrollable) this.scrollToBottom();
+      }
+    });
+    stream.once('end',stop); stream.once('close',stop);
+    return stop;
+  }
+
+  // ── Grid ───────────────────────────────────────────────────────────────────
+  _makeGrid(rows,cols) {
+    return Array.from({length:rows},()=>Array.from({length:cols},()=>new TVPixel({char:' ',color:[this.defaultFg,this.defaultBg]})));
+  }
+  _startRenderLoop() {
+    this._timer = setInterval(()=>{ if(this._dirty&&!this._hidden) this.render(); }, Math.round(1000/this.fps));
+    this._timer.unref?.();
+  }
+  _stopRenderLoop() { if(this._timer){clearInterval(this._timer);this._timer=null;} }
+
+  // ── Rendering ──────────────────────────────────────────────────────────────
+  render() {
+    if (this._hidden) return this;
+    const out=[ansi.saveCursor,ansi.hideCursor];
+    const iRS=this.border?1:0, iCS=this.border?1:0;
+    const iR=this.border?this.rows-2:this.rows, iC=this.border?this.cols-2:this.cols;
+    if (this.border) {
+      const bs=BORDER_STYLES[this.borderStyle]||BORDER_STYLES.single;
+      const fc=this._hasFocus?ansi.fg('brightcyan'):ansi.fg('gray');
+      const pad=this.cols-2-this.title.length;
+      const top=bs.tl+(this.title?bs.h.repeat(Math.max(0,Math.floor(pad/2)))+this.title+bs.h.repeat(Math.max(0,Math.ceil(pad/2))):bs.h.repeat(this.cols-2))+bs.tr;
+      out.push(ansi.moveTo(this.offsetRow,this.offsetCol)+fc+top+ansi.reset);
+      for (let r=1;r<this.rows-1;r++) {
+        out.push(ansi.moveTo(this.offsetRow+r,this.offsetCol)+fc+bs.v+ansi.reset);
+        out.push(ansi.moveTo(this.offsetRow+r,this.offsetCol+this.cols-1)+fc+bs.v+ansi.reset);
+      }
+      out.push(ansi.moveTo(this.offsetRow+this.rows-1,this.offsetCol)+fc+bs.bl+bs.h.repeat(this.cols-2)+bs.br+ansi.reset);
+    }
+    for (let r=0;r<iR;r++) {
+      const gr=r+this._scrollOffset; if(gr>=this.grid.length) break;
+      out.push(ansi.moveTo(this.offsetRow+iRS+r,this.offsetCol+iCS));
+      for (let c=0;c<iC;c++) { const p=this.grid[gr]?.[c]; out.push(p?p.render():ansi.reset+' '); }
+    }
+    if (this._overlay) {
+      const ov=this._overlay;
+      for (let r=0;r<ov.rows;r++) {
+        out.push(ansi.moveTo(this.offsetRow+ov.row+r,this.offsetCol+ov.col));
+        for (let c=0;c<ov.cols;c++) { const p=ov.pixels[r]?.[c]; out.push(p?p.render():ansi.reset+' '); }
+      }
+    }
+    out.push(ansi.reset,ansi.restoreCursor,ansi.showCursor);
+    process.stdout.write(out.join(''));
+    this._dirty=false; this.emit('render');
+    return this;
+  }
+  markDirty() { this._dirty=true; return this; }
+
+  // ── Pixel/text ─────────────────────────────────────────────────────────────
+  setPixel(row,col,pixel) {
+    if(row<0||row>=this.grid.length)return this;
+    if(col<0||col>=(this.grid[row]?.length||0))return this;
+    if(this.grid[row][col].isStatic)return this;
+    this.grid[row][col]=pixel instanceof TVPixel?pixel:new TVPixel(pixel);
+    this._dirty=true; return this;
+  }
+  getPixel(row,col) { return this.grid[row]?.[col]??null; }
+  writeText(row,col,text,opts={}) {
+    return new Promise(res => {
+    for(let i=0;i<text.length;i++) this.setPixel(row,col+i,new TVPixel({char:text[i],...opts}));
+    return this;
+    })
+  }
+  writeCentered(row,text,opts={}) { return this.writeText(row,Math.max(0,Math.floor((this.cols-text.length)/2)),text,opts); }
+  writeRight(row,text,opts={})    { return this.writeText(row,Math.max(0,this.cols-text.length),text,opts); }
+  fill(row,col,rows,cols,opts={}) {
+    for(let r=row;r<row+rows;r++) for(let c=col;c<col+cols;c++) this.setPixel(r,c,new TVPixel(opts));
+    return this;
+  }
+  clear()     { this.grid=this._makeGrid(this.rows,this.cols); this._dirty=true; return this; }
+  clearRow(r) {
+    if(r>=0&&r<this.grid.length){ this.grid[r]=Array.from({length:this.cols},()=>new TVPixel({char:' ',color:[this.defaultFg,this.defaultBg]})); this._dirty=true; }
+    return this;
+  }
+
+  // ── Drawing ────────────────────────────────────────────────────────────────
+  drawBox(row,col,rows,cols,opts={},style='single') {
+    const bs=BORDER_STYLES[style]||BORDER_STYLES.single;
+    this.setPixel(row,col,new TVPixel({char:bs.tl,...opts}));
+    this.setPixel(row,col+cols-1,new TVPixel({char:bs.tr,...opts}));
+    this.setPixel(row+rows-1,col,new TVPixel({char:bs.bl,...opts}));
+    this.setPixel(row+rows-1,col+cols-1,new TVPixel({char:bs.br,...opts}));
+    for(let c=col+1;c<col+cols-1;c++){this.setPixel(row,c,new TVPixel({char:bs.h,...opts}));this.setPixel(row+rows-1,c,new TVPixel({char:bs.h,...opts}));}
+    for(let r=row+1;r<row+rows-1;r++){this.setPixel(r,col,new TVPixel({char:bs.v,...opts}));this.setPixel(r,col+cols-1,new TVPixel({char:bs.v,...opts}));}
+    return this;
+  }
+  drawHLine(row,col,len,opts={},style='single'){const h=(BORDER_STYLES[style]||BORDER_STYLES.single).h;for(let c=col;c<col+len;c++)this.setPixel(row,c,new TVPixel({char:h,...opts}));return this;}
+  drawVLine(row,col,len,opts={},style='single'){const v=(BORDER_STYLES[style]||BORDER_STYLES.single).v;for(let r=row;r<row+len;r++)this.setPixel(r,col,new TVPixel({char:v,...opts}));return this;}
+
+  // ── Overlay ────────────────────────────────────────────────────────────────
+  setOverlay(row,col,pixels){this._overlay={row,col,rows:pixels.length,cols:pixels[0]?.length??0,pixels};this._dirty=true;return this;}
+  clearOverlay(){this._overlay=null;this._dirty=true;return this;}
+
+  // ── Scroll ─────────────────────────────────────────────────────────────────
+  scrollDown(n=1){this._scrollOffset=Math.min(this._scrollOffset+n,Math.max(0,this.grid.length-this.rows));this._dirty=true;return this;}
+  scrollUp(n=1)  {this._scrollOffset=Math.max(0,this._scrollOffset-n);this._dirty=true;return this;}
+  scrollTo(r)    {this._scrollOffset=Math.max(0,Math.min(r,this.grid.length-this.rows));this._dirty=true;return this;}
+  scrollToBottom(){return this.scrollTo(Math.max(0,this.grid.length-this.rows));}
+  pushRow(pixels){this.grid.push(pixels);if(this.scrollable)this.scrollToBottom();this._dirty=true;return this;}
+
+  // ── Alt screen ─────────────────────────────────────────────────────────────
+  renderInAltScreen(){if(!this._altScreen){process.stdout.write(ansi.altScreenOn+ansi.clear+ansi.cursorHome);this._altScreen=true;}return this.render();}
+  leaveAltScreen(){if(this._altScreen){process.stdout.write(ansi.altScreenOff);this._altScreen=false;}return this;}
+
+  hide()   {this._hidden=true;return this;}
+  show()   {this._hidden=false;this._dirty=true;return this;}
+  toggle() {return this._hidden?this.show():this.hide();}
+
+  resize(rows,cols) {
+    const g=this._makeGrid(rows,cols);
+    for(let r=0;r<Math.min(rows,this.grid.length);r++) for(let c=0;c<Math.min(cols,(this.grid[r]||[]).length);c++) g[r][c]=this.grid[r][c];
+    this.rows=rows;this.cols=cols;this.grid=g;this._dirty=true;this.emit('resize',{rows,cols});return this;
+  }
+
+  // ── Prompt ─────────────────────────────────────────────────────────────────
+  prompt(promptStr = '> ') {
+    return new Promise(resolve => {
+      this._promptActive=true;
+      const pRow=this.rows-1; let inputStr='', inputCol=promptStr.length;
+      this.clearRow(pRow);
+      this.writeText(pRow,0,promptStr,{color:['cyan',null]});
+      this.render();
+      process.stdout.write(ansi.moveTo(this.offsetRow+pRow,this.offsetCol+inputCol)+ansi.showCursor);
+      this.focus();
+      const onKey = key => {
+        if (key.name==='enter') {
+          this.removeListener('key',onKey); this._promptActive=false; this.clearRow(pRow); this.markDirty(); resolve(inputStr);
+        } else if (key.name==='backspace') {
+          if(inputStr.length>0){inputStr=inputStr.slice(0,-1);inputCol--;this.setPixel(pRow,inputCol,new TVPixel({char:' '}));this.render();process.stdout.write(ansi.moveTo(this.offsetRow+pRow,this.offsetCol+inputCol));}
+        } else if (key.name==='escape') {
+          this.removeListener('key',onKey);this._promptActive=false;this.clearRow(pRow);this.markDirty();resolve(null);
+        } else if (key.char&&key.char>=' '&&!key.ctrl&&inputCol<this.cols) {
+          this.setPixel(pRow,inputCol,new TVPixel({char:key.char,color:['white',null]}));inputStr+=key.char;inputCol++;this.render();process.stdout.write(ansi.moveTo(this.offsetRow+pRow,this.offsetCol+inputCol));
+        }
+      };
+      this.on('key',onKey);
+    });
+  }
+
+  // ── Cut/split ──────────────────────────────────────────────────────────────
+  cut(n) {
+    if(n<1)throw new RangeError('cut: n>=1'); this._stopRenderLoop();
+    const sh=Math.floor(this.rows/n);
+    return Array.from({length:n},(_,i)=>{
+      const rows=(i===n-1)?this.rows-sh*(n-1):sh;
+      return new TView({rows,cols:this.cols,offsetRow:this.offsetRow+i*sh,offsetCol:this.offsetCol,fps:this.fps,defaultBg:this.defaultBg,defaultFg:this.defaultFg});
+    });
+  }
+  cutHorizontal(n) {
+    if(n<1)throw new RangeError('cutHorizontal: n>=1'); this._stopRenderLoop();
+    const sw=Math.floor(this.cols/n);
+    return Array.from({length:n},(_,i)=>{
+      const cols=(i===n-1)?this.cols-sw*(n-1):sw;
+      return new TView({rows:this.rows,cols,offsetRow:this.offsetRow,offsetCol:this.offsetCol+i*sw,fps:this.fps,defaultBg:this.defaultBg,defaultFg:this.defaultFg});
+    });
+  }
+  cutGrid(gr,gc) { return this.cut(gr).map(rv=>rv.cutHorizontal(gc)); }
+  cutWeighted(weights) {
+    const total=weights.reduce((a,b)=>a+b,0), isPct=total<=1.01&&total>=0.99;
+    let cursor=0; this._stopRenderLoop();
+    return weights.map((w,i)=>{
+      const rows=(i===weights.length-1)?this.rows-cursor:Math.floor(isPct?w*this.rows:w);
+      const v=new TView({rows,cols:this.cols,offsetRow:this.offsetRow+cursor,offsetCol:this.offsetCol,fps:this.fps,defaultBg:this.defaultBg,defaultFg:this.defaultFg});
+      cursor+=rows; return v;
+    });
+  }
+
+  // ── Animation ──────────────────────────────────────────────────────────────
+  animatePixel(row,col,frames,interval=100,opts={}) {
+    let i=0; const t=setInterval(()=>this.setPixel(row,col,new TVPixel({char:frames[i++%frames.length],...opts})),interval);
+    const stop=()=>clearInterval(t); this._animations.push(stop); return stop;
+  }
+  marquee(row,text,interval=80,opts={}) {
+    const padded=text+'  '; let offset=0;
+    const t=setInterval(()=>{this.writeText(row,0,(padded.slice(offset%padded.length)+padded).slice(0,this.cols).padEnd(this.cols),opts);offset++;},interval);
+    const stop=()=>clearInterval(t); this._animations.push(stop); return stop;
+  }
+  spinner(row,col,style='dots',interval=80,opts={}) {
+    const S={dots:['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'],line:['-','\\','|','/'],arc:['◜','◠','◝','◞','◡','◟'],bounce:['⠁','⠂','⠄','⠂'],pulse:['·','●','◉','●'],arrows:['←','↖','↑','↗','→','↘','↓','↙'],clock:['🕐','🕑','🕒','🕓','🕔','🕕'],bar:['▏','▎','▍','▌','▋','▊','▉','█','▉','▊','▋','▌','▍','▎']};
+    return this.animatePixel(row,col,S[style]||S.dots,interval,opts);
+  }
+  flash(row,col,rows,cols,color='yellow',times=6,interval=150) {
+    let count=0,on=true;
+    const orig=this.grid.slice(row,row+rows).map(r=>r.slice(col,col+cols).map(p=>p.clone()));
+    const t=setInterval(()=>{
+      if(on)this.fill(row,col,rows,cols,{color:[null,color]});
+      else{for(let r=0;r<rows;r++)for(let c=0;c<cols;c++)this.grid[row+r][col+c]=orig[r][c].clone();this._dirty=true;}
+      on=!on;count++;if(count>=times*2)clearInterval(t);
+    },interval);
+    return ()=>clearInterval(t);
+  }
+
+  // ── Widgets ────────────────────────────────────────────────────────────────
+  progressBar(row,col,width,pct,opts={}) {
+    const{filledColor='green',emptyColor='gray',filledChar='█',emptyChar='░',showLabel=false}=opts;
+    const filled=Math.round(Math.min(1,Math.max(0,pct))*width);
+    for(let c=0;c<width;c++){const f=c<filled;this.setPixel(row,col+c,new TVPixel({char:f?filledChar:emptyChar,color:[f?filledColor:emptyColor,null]}));}
+    if(showLabel){const lbl=`${Math.round(pct*100)}%`;this.writeText(row,col+Math.floor((width-lbl.length)/2),lbl,{color:['white',null]});}
+    this._dirty=true; return this;
+  }
+  statusBar(left,right='',opts={color:['black','white']}) {
+    const spacer=' '.repeat(Math.max(0,this.cols-left.length-right.length));
+    this.writeText(this.rows-1,0,(left+spacer+right).slice(0,this.cols),opts); return this;
+  }
+  table(row,col,data,opts={}) {
+    const{headerColor=['black','cyan'],cellColor=['white',null],colWidths}=opts;
+    if(!data.length)return this;
+    const widths=colWidths??data[0].map((_,ci)=>Math.max(...data.map(r=>(r[ci]??'').length))+2);
+    let r=row;
+    for(let ri=0;ri<data.length;ri++){let c=col;const isH=ri===0;for(let ci=0;ci<data[ri].length;ci++){const cell=(' '+(data[ri][ci]??'')+' ').padEnd(widths[ci]).slice(0,widths[ci]);this.writeText(r,c,cell,isH?{color:headerColor}:{color:cellColor});c+=widths[ci];}r++;}
+    return this;
+  }
+
+  // ── Snapshot/copy ──────────────────────────────────────────────────────────
+  snapshot()       { return this.grid.map(r=>r.map(p=>p.clone())); }
+  restoreSnapshot(snap) {
+    for(let r=0;r<snap.length&&r<this.grid.length;r++) for(let c=0;c<snap[r].length&&c<this.grid[r].length;c++) if(!this.grid[r][c].isStatic)this.grid[r][c]=snap[r][c].clone();
+    this._dirty=true; return this;
+  }
+  copyRegion(row,col,rows,cols) { return Array.from({length:rows},(_,r)=>Array.from({length:cols},(_,c)=>this.grid[row+r]?.[col+c]?.clone()??new TVPixel())); }
+  pasteRegion(row,col,pixels)   { for(let r=0;r<pixels.length;r++)for(let c=0;c<pixels[r].length;c++)this.setPixel(row+r,col+c,pixels[r][c]);return this; }
+
+  // ── Destroy ────────────────────────────────────────────────────────────────
+  destroy() {
+    this._stopRenderLoop();
+    this._animations.forEach(s=>s()); this._animations=[];
+    this._dataBindings.forEach(({source,event,handler})=>source.removeListener(event,handler)); this._dataBindings=[];
+    inputManager.unregister(this);
+    if(this._altScreen)this.leaveAltScreen();
+    this.emit('destroy'); this.removeAllListeners();
+  }
+
+  toString()     { return this.grid.map(r=>r.map(p=>p.char).join('')).join('\n'); }
+  toAnsiString() { return this.grid.map(r=>r.map(p=>p.render()).join('')+ansi.reset).join('\n'); }
+}
+
+function createFullscreen(opts={}) {
+  return new TView({rows:process.stdout.rows||24,cols:process.stdout.columns||80,...opts});
+}
+function px(char,fg=null,bg=null,isStatic=false) { return new TVPixel({char,color:[fg,bg],isStatic}); }
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §5  tshell  —  child-process runner / interactive shell
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TShell  — spawn programs, pipe their output into TViews, send input,
+ *            collect results, and run shell pipelines.
+ *
+ * @example
+ *   const sh = new TShell({ view: myView });
+ *   const { stdout } = await sh.run('ls', ['-la']);
+ *   sh.spawn('tail', ['-f', '/var/log/syslog']);  // live stream
+ *   sh.write('hello\n');                            // send stdin
+ */
+class TShell extends EventEmitter {
+  /**
+   * @param {object} [opts]
+   * @param {TView}  [opts.view]       — pipe stdout into this view
+   * @param {object} [opts.env]        — extra env vars (merged over process.env)
+   * @param {string} [opts.cwd]        — working directory
+   * @param {*}      [opts.pixelOpts]  — color/style for piped text
+   * @param {string} [opts.shell]      — shell binary for .shell() (default: /bin/sh)
+   */
+  constructor(opts = {}) {
+    super();
+    this._view      = opts.view      ?? null;
+    this._env       = opts.env       ? { ...process.env, ...opts.env } : process.env;
+    this._cwd       = opts.cwd       ?? process.cwd();
+    this._pixelOpts = opts.pixelOpts ?? { color: ['brightgreen', null] };
+    this._shell     = opts.shell     ?? (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh');
+    this._proc      = null;   // currently spawned process
+    this._history   = [];     // command history
+  }
+
+  /** Change the view that output is piped into. */
+  setView(view) { this._view = view; return this; }
+
+  /**
+   * Run a command and collect its output (like exec but streaming).
+   * Resolves when the process exits.
+   * @param {string}   cmd
+   * @param {string[]} [args=[]]
+   * @param {object}   [spawnOpts]
+   * @returns {Promise<{code, stdout, stderr}>}
+   */
+  run(cmd, args = [], spawnOpts = {}) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(cmd, args, {
+        env: this._env, cwd: this._cwd,
+        ...spawnOpts,
+      });
+      let stdout = '', stderr = '';
+      proc.stdout?.on('data', d => {
+        const s = String(d); stdout += s;
+        this._toView(s); this.emit('data', s);
+      });
+      proc.stderr?.on('data', d => {
+        const s = String(d); stderr += s;
+        this._toView(s, { color: ['brightyellow', null] }); this.emit('stderr', s);
+      });
+      proc.on('error', reject);
+      proc.on('close', code => {
+        this._history.push({ cmd, args, code, ts: Date.now() });
+        this.emit('exit', { cmd, args, code });
+        resolve({ code, stdout, stderr });
+      });
+      this._proc = proc;
+    });
+  }
+
+  /**
+   * Spawn a long-running process (don't await its exit).
+   * Stdout is continuously piped to the bound view.
+   * @returns {ChildProcess}
+   */
+  spawn(cmd, args = [], spawnOpts = {}) {
+    const proc = spawn(cmd, args, { env: this._env, cwd: this._cwd, ...spawnOpts });
+    proc.stdout?.on('data', d => { const s=String(d); this._toView(s); this.emit('data',s); });
+    proc.stderr?.on('data', d => { const s=String(d); this._toView(s,{color:['brightyellow',null]}); this.emit('stderr',s); });
+    proc.on('close', code => { this._history.push({cmd,args,code,ts:Date.now()}); this.emit('exit',{cmd,args,code}); });
+    proc.on('error', err  => this.emit('error', err));
+    this._proc = proc;
+    return proc;
+  }
+
+  /**
+   * Execute a shell command string (passed to /bin/sh -c).
+   * @param {string} cmdStr  — e.g. 'ls -la | head -5'
+   * @returns {Promise<{code, stdout, stderr}>}
+   */
+  shell(cmdStr) {
+    return this.run(this._shell, ['-c', cmdStr]);
+  }
+
+  /**
+   * Run a command synchronously (blocks the event loop).
+   * @returns {{ code, stdout, stderr }}
+   */
+  runSync(cmd, args = [], opts = {}) {
+    const result = spawnSync(cmd, args, {
+      env: this._env, cwd: this._cwd, encoding: 'utf8', ...opts,
+    });
+    this._history.push({ cmd, args, code: result.status, ts: Date.now() });
+    return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+  }
+
+  /** Send text to the running process's stdin. */
+  write(data) {
+    if (this._proc?.stdin) { this._proc.stdin.write(data); }
+    return this;
+  }
+
+  /** Send SIGTERM (or another signal) to the running process. */
+  kill(signal = 'SIGTERM') {
+    this._proc?.kill(signal); return this;
+  }
+
+  /** Change working directory (affects subsequent runs). */
+  cd(dir) {
+    const resolved = path.resolve(this._cwd, dir);
+    if (fs.existsSync(resolved)) { this._cwd = resolved; this.emit('cwd', resolved); }
+    else throw new Error(`TShell.cd: directory not found: ${resolved}`);
+    return this;
+  }
+
+  /** Set/get an environment variable for subsequent runs. */
+  setEnv(key, value) { this._env = { ...this._env, [key]: String(value) }; return this; }
+  getEnv(key)        { return this._env[key]; }
+
+  /** Returns a copy of the command history array. */
+  getHistory() { return [...this._history]; }
+
+  /**
+   * Run a series of commands in sequence, stopping on first non-zero exit.
+   * @param {Array<{cmd, args}>} pipeline
+   * @returns {Promise<Array<result>>}
+   */
+  async sequence(pipeline) {
+    const results = [];
+    for (const { cmd, args = [] } of pipeline) {
+      const r = await this.run(cmd, args);
+      results.push(r);
+      if (r.code !== 0) break;
+    }
+    return results;
+  }
+
+  /**
+   * Run commands in parallel, resolve when all complete.
+   * @param {Array<{cmd, args}>} commands
+   */
+  parallel(commands) {
+    return Promise.all(commands.map(({ cmd, args = [] }) => this.run(cmd, args)));
+  }
+
+  _toView(str, overrideOpts) {
+    if (!this._view) return;
+    const opts = overrideOpts ?? this._pixelOpts;
+    // Append each line to the view grid
+    const lines = str.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].replace(/\x1b\[[^m]*m/g, '');
+      if (!line && i === lines.length - 1) continue;
+      const row = this._view.grid.length;
+      this._view.grid.push(Array.from({length:this._view.cols},()=>new TVPixel({char:' '})));
+      const display = line.slice(0, this._view.cols);
+      for (let c = 0; c < display.length; c++)
+        this._view.grid[row][c] = new TVPixel({ char: display[c], ...opts });
+      if (this._view.scrollable) this._view.scrollToBottom();
+    }
+    this._view.markDirty();
+  }
+
+  get cwd()  { return this._cwd; }
+  get pid()  { return this._proc?.pid ?? null; }
+  get alive(){ return !!(this._proc && !this._proc.exitCode && !this._proc.killed); }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §6  tenv  —  typed, validated environment config
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TEnv  — typed env-var system with defaults, validation, transforms,
+ *          .env file loading, and change-watching.
+ *
+ * @example
+ *   const env = new TEnv();
+ *   env.define('PORT',       { type: 'int',    default: 3000 });
+ *   env.define('DEBUG',      { type: 'bool',   default: false });
+ *   env.define('LOG_LEVEL',  { type: 'enum',   values: ['debug','info','warn','error'], default: 'info' });
+ *   env.define('API_KEY',    { type: 'string', required: true });
+ *   env.load();
+ *
+ *   const port = env.get('PORT');   // → 3000 (number)
+ *   env.set('DEBUG', true);         // programmatic override
+ *   env.watch('./config.env', 500); // reload on file change
+ */
+class TEnv extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this._source   = opts.source ?? process.env;  // raw string map
+    this._schema   = new Map();                   // name → schema entry
+    this._values   = new Map();                   // name → parsed value
+    this._watchers = [];
+    this._strict   = opts.strict ?? false;        // throw on undefined vars
+  }
+
+  /**
+   * Define a variable.
+   * @param {string} name
+   * @param {object} schema
+   * @param {string}   schema.type       — 'string'|'int'|'float'|'bool'|'json'|'list'|'enum'|'path'|'url'
+   * @param {*}        [schema.default]  — value when var is absent
+   * @param {boolean}  [schema.required] — throw if absent and no default
+   * @param {string[]} [schema.values]   — allowed values (for enum)
+   * @param {function} [schema.validate] — custom (val)=>true|string(error)
+   * @param {function} [schema.transform]— (raw)=>transformed
+   * @param {string}   [schema.desc]     — human description
+   */
+  define(name, schema = {}) {
+    this._schema.set(name, { type: 'string', ...schema });
+    return this;
+  }
+
+  /**
+   * Load and parse all defined variables from the source.
+   * @param {string} [dotenvPath]  — optional .env file to read first
+   */
+  load(dotenvPath) {
+    if (dotenvPath) this._parseDotenv(dotenvPath);
+    for (const [name, schema] of this._schema) {
+      this._resolve(name, schema);
+    }
+    this.emit('load', Object.fromEntries(this._values));
+    return this;
+  }
+
+  /** Get a parsed value. Throws if not loaded and strict mode is on. */
+  get(name) {
+    if (!this._values.has(name)) {
+      const schema = this._schema.get(name);
+      if (schema) this._resolve(name, schema);
+      else if (this._strict) throw new Error(`TEnv: unknown variable "${name}"`);
+      else return this._source[name];
+    }
+    return this._values.get(name);
+  }
+
+  /** Programmatically override a value (bypasses env but not validate). */
+  set(name, value) {
+    const schema = this._schema.get(name) ?? { type: typeof value === 'number' ? 'float' : 'string' };
+    const parsed = this._parse(String(value), schema);
+    this._values.set(name, parsed);
+    this.emit('change', { name, value: parsed });
+    return this;
+  }
+
+  /** Return all resolved values as a plain object. */
+  all() { return Object.fromEntries(this._values); }
+
+  /** Return a flat diagnostic table (useful for TView.table()). */
+  describe() {
+    const rows = [['Variable', 'Type', 'Value', 'Default', 'Required', 'Description']];
+    for (const [name, schema] of this._schema) {
+      rows.push([
+        name,
+        schema.type ?? 'string',
+        String(this._values.has(name) ? this._values.get(name) : '—'),
+        String(schema.default ?? '—'),
+        schema.required ? 'yes' : 'no',
+        schema.desc ?? '',
+      ]);
+    }
+    return rows;
+  }
+
+  /**
+   * Watch a .env file for changes and reload automatically.
+   * @param {string} filePath
+   * @param {number} [interval=1000]  — poll interval ms (fs.watchFile)
+   */
+  watch(filePath, interval = 1000) {
+    fs.watchFile(filePath, { interval }, () => {
+      this._parseDotenv(filePath);
+      for (const [name, schema] of this._schema) this._resolve(name, schema);
+      this.emit('reload', Object.fromEntries(this._values));
+    });
+    this._watchers.push(filePath);
+    return this;
+  }
+
+  unwatch() { this._watchers.forEach(f => fs.unwatchFile(f)); this._watchers = []; return this; }
+
+  // ── internal ──────────────────────────────────────────────────────────────
+
+  _resolve(name, schema) {
+    const raw = this._source[name];
+    if (raw == null || raw === '') {
+      if (schema.required && schema.default == null)
+        throw new Error(`TEnv: required variable "${name}" is not set`);
+      this._values.set(name, schema.default ?? null);
+      return;
+    }
+    let value = schema.transform ? schema.transform(raw) : this._parse(raw, schema);
+    if (schema.validate) {
+      const verdict = schema.validate(value);
+      if (verdict !== true && verdict != null)
+        throw new Error(`TEnv: "${name}" failed validation: ${verdict}`);
+    }
+    this._values.set(name, value);
+  }
+
+  _parse(raw, schema) {
+    switch (schema.type) {
+      case 'int':    return parseInt(raw, 10);
+      case 'float':  return parseFloat(raw);
+      case 'bool':   return /^(true|1|yes|on)$/i.test(raw);
+      case 'json':   return JSON.parse(raw);
+      case 'list':   return raw.split(schema.separator ?? ',').map(s => s.trim());
+      case 'path':   return path.resolve(raw);
+      case 'url':    return new URL(raw).toString();
+      case 'enum': {
+        const vals = schema.values ?? [];
+        if (!vals.includes(raw))
+          throw new Error(`TEnv: "${raw}" not in allowed values [${vals.join(', ')}]`);
+        return raw;
+      }
+      default: return raw;
+    }
+  }
+
+  _parseDotenv(filePath) {
+    if (!fs.existsSync(filePath)) return;
+    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq < 0) continue;
+      const key = trimmed.slice(0, eq).trim();
+      let val = trimmed.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) ||
+          (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+      this._source[key] = val;
+    }
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §7  tlog  —  levelled logger with TView integration
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TLog  — structured levelled logger.
+ * Can write to a TView, to a file, or both.
+ *
+ * @example
+ *   const log = new TLog({ view: myView, level: 'debug' });
+ *   log.info('Server started', { port: 3000 });
+ *   log.error('Connection failed', err);
+ *   log.time('init');  // start timer
+ *   log.timeEnd('init');  // log elapsed
+ */
+class TLog extends EventEmitter {
+  static LEVELS = { trace:0, debug:1, info:2, warn:3, error:4, fatal:5, silent:99 };
+  static COLORS = { trace:'gray', debug:'brightcyan', info:'brightgreen', warn:'brightyellow', error:'brightred', fatal:'magenta' };
+  static ICONS  = { trace:'·', debug:'◌', info:'ℹ', warn:'⚠', error:'✖', fatal:'☠' };
+
+  /**
+   * @param {object}  [opts]
+   * @param {TView}   [opts.view]       — render logs here
+   * @param {string}  [opts.level]      — minimum level (default 'info')
+   * @param {string}  [opts.file]       — path to append log file
+   * @param {boolean} [opts.timestamp]  — include ISO timestamp (default true)
+   * @param {boolean} [opts.json]       — write JSON to file instead of pretty
+   * @param {number}  [opts.maxLines]   — max lines kept in view grid (default 500)
+   * @param {string}  [opts.prefix]     — static prefix for all messages
+   */
+  constructor(opts = {}) {
+    super();
+    this._view      = opts.view      ?? null;
+    this._level     = TLog.LEVELS[opts.level ?? 'info'] ?? TLog.LEVELS.info;
+    this._file      = opts.file      ?? null;
+    this._timestamp = opts.timestamp ?? true;
+    this._json      = opts.json      ?? false;
+    this._maxLines  = opts.maxLines  ?? 500;
+    this._prefix    = opts.prefix    ?? '';
+    this._timers    = new Map();
+    this._fileStream = this._file ? fs.createWriteStream(this._file, { flags: 'a' }) : null;
+    this._lineCount = 0;
+  }
+
+  trace(msg, meta) { return this._log('trace', msg, meta); }
+  debug(msg, meta) { return this._log('debug', msg, meta); }
+  info (msg, meta) { return this._log('info',  msg, meta); }
+  warn (msg, meta) { return this._log('warn',  msg, meta); }
+  error(msg, meta) { return this._log('error', msg, meta); }
+  fatal(msg, meta) { return this._log('fatal', msg, meta); }
+
+  /** Set log level dynamically. */
+  setLevel(level) { this._level = TLog.LEVELS[level] ?? this._level; return this; }
+
+  /** Bind to a TView. */
+  setView(view) { this._view = view; return this; }
+
+  /** Start a named timer. */
+  time(label) { this._timers.set(label, process.hrtime.bigint()); return this; }
+
+  /** Stop a named timer and log the elapsed time. */
+  timeEnd(label) {
+    const start = this._timers.get(label);
+    if (!start) { this.warn(`timeEnd: no timer "${label}"`); return this; }
+    const ms = Number(process.hrtime.bigint() - start) / 1e6;
+    this._timers.delete(label);
+    return this.info(`${label}: ${ms.toFixed(2)}ms`);
+  }
+
+  /** Log a group header (indents subsequent lines visually). */
+  group(label) { return this._log('info', `▼ ${label}`); }
+  groupEnd()   { return this._log('info', '▲'); }
+
+  /** Dump an object as formatted JSON to the log. */
+  dir(obj, label = '') {
+    const str = JSON.stringify(obj, null, 2);
+    for (const line of (`${label ? label + ': ' : ''}${str}`).split('\n'))
+      this._log('debug', line);
+    return this;
+  }
+
+  /** Clear the log view. */
+  clearView() {
+    if (this._view) { this._view.clear(); this._lineCount = 0; }
+    return this;
+  }
+
+  _log(level, msg, meta) {
+    if (TLog.LEVELS[level] < this._level) return this;
+    const ts   = this._timestamp ? new Date().toISOString().slice(11,23) : '';
+    const icon = TLog.ICONS[level]  || ' ';
+    const color= TLog.COLORS[level] || 'white';
+    const metaStr = meta != null
+      ? (typeof meta === 'string' ? ' ' + meta : ' ' + JSON.stringify(meta))
+      : '';
+    const prefix = this._prefix ? `[${this._prefix}] ` : '';
+    const line   = `${ts ? ts + ' ' : ''}${icon} ${prefix}${msg}${metaStr}`;
+
+    // View output
+    if (this._view) {
+      if (this._lineCount >= this._maxLines) {
+        this._view.grid.shift(); this._lineCount--;
+      }
+      const row = this._view.grid.length;
+      this._view.grid.push(Array.from({length:this._view.cols},()=>new TVPixel({char:' '})));
+      const display = line.slice(0, this._view.cols);
+      for (let c = 0; c < display.length; c++)
+        this._view.grid[row][c] = new TVPixel({ char: display[c], color: [color, null] });
+      if (this._view.scrollable) this._view.scrollToBottom();
+      this._view.markDirty();
+      this._lineCount++;
+    }
+
+    // File output
+    if (this._fileStream) {
+      const fileLine = this._json
+        ? JSON.stringify({ ts: new Date().toISOString(), level, msg, meta }) + '\n'
+        : line + '\n';
+      this._fileStream.write(fileLine);
+    }
+
+    const entry = { ts: new Date().toISOString(), level, msg, meta };
+    this.emit('log', entry);
+    this.emit(level, entry);
+    return this;
+  }
+
+  close() { this._fileStream?.end(); return this; }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §8  ttheme  —  named colour/style token system
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TTheme  — token-based colour system.  Define named tokens, bundle them into
+ *            themes, switch themes at runtime.  All TView/TVPixel colour calls
+ *            accept raw values, so you just pass theme.get('primary') anywhere.
+ *
+ * @example
+ *   const theme = new TTheme();
+ *   theme.define('dark', { primary:'brightcyan', bg:'#0d1117', fg:'white', error:'brightred', muted:'gray' });
+ *   theme.define('light',{ primary:'blue', bg:'white', fg:'black', error:'red', muted:'gray' });
+ *   theme.use('dark');
+ *
+ *   view.writeText(0, 0, 'Hello', { color: [theme.get('primary'), theme.get('bg')] });
+ *   theme.on('change', name => view.markDirty());
+ */
+class TTheme extends EventEmitter {
+  /** Built-in themes */
+  static DARK = {
+    primary:'brightcyan', secondary:'brightmagenta', accent:'brightyellow',
+    success:'brightgreen', warning:'brightyellow',   error:'brightred',   info:'brightblue',
+    fg:'brightwhite',      fgMuted:'gray',           bg:'#0d1117',        bgAlt:'#161b22',
+    bgHighlight:'#21262d', border:'#30363d',         selection:'#1f6feb',
+  };
+  static LIGHT = {
+    primary:'blue',        secondary:'magenta',      accent:'yellow',
+    success:'green',       warning:'yellow',          error:'red',         info:'blue',
+    fg:'black',            fgMuted:'gray',            bg:'white',          bgAlt:'#f6f8fa',
+    bgHighlight:'#e1e4e8', border:'#d0d7de',          selection:'#0969da',
+  };
+  static MONOKAI = {
+    primary:'#a6e22e',     secondary:'#fd971f',       accent:'#e6db74',
+    success:'#a6e22e',     warning:'#fd971f',         error:'#f92672',     info:'#66d9ef',
+    fg:'#f8f8f2',          fgMuted:'#75715e',         bg:'#272822',        bgAlt:'#3e3d32',
+    bgHighlight:'#49483e', border:'#75715e',          selection:'#49483e',
+  };
+
+  constructor(initial = 'dark') {
+    super();
+    this._themes  = new Map();
+    this._current = null;
+    this._name    = null;
+    // Register built-ins
+    this.define('dark',    TTheme.DARK);
+    this.define('light',   TTheme.LIGHT);
+    this.define('monokai', TTheme.MONOKAI);
+    this.use(initial);
+  }
+
+  /** Register a named theme (merges with dark base for missing tokens). */
+  define(name, tokens) {
+    this._themes.set(name, { ...TTheme.DARK, ...tokens });
+    return this;
+  }
+
+  /** Switch to a named theme. */
+  use(name) {
+    if (!this._themes.has(name)) throw new Error(`TTheme: unknown theme "${name}"`);
+    this._name    = name;
+    this._current = this._themes.get(name);
+    this.emit('change', name, this._current);
+    return this;
+  }
+
+  /** Get a token value from the active theme. */
+  get(token, fallback = null) {
+    return this._current?.[token] ?? fallback;
+  }
+
+  /** Get fg/bg pair as a color array suitable for TVPixel. */
+  pair(fg, bg) { return [this.get(fg), this.get(bg)]; }
+
+  /** All token names of the active theme. */
+  tokens() { return this._current ? Object.keys(this._current) : []; }
+
+  /** All registered theme names. */
+  names()  { return [...this._themes.keys()]; }
+
+  /** Active theme name. */
+  get name()   { return this._name; }
+
+  /** Active theme raw object. */
+  get theme()  { return { ...this._current }; }
+
+  /**
+   * Build a TVPixel pixelOpts object from semantic token names.
+   * @param {string} fgToken   — e.g. 'primary'
+   * @param {string} bgToken   — e.g. 'bg'
+   * @param {string} [style]
+   */
+  style(fgToken, bgToken = null, style = null) {
+    return { color: [this.get(fgToken), bgToken ? this.get(bgToken) : null], style };
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §9  twidget  —  higher-level interactive widgets
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TWidget  — collection of interactive terminal widgets rendered into TViews.
+ *
+ * Widgets:
+ *   TWidget.Menu         — keyboard/mouse navigable menu
+ *   TWidget.List         — scrollable multi-select list
+ *   TWidget.Dialog       — modal confirmation/info dialog
+ *   TWidget.TextInput    — single-line text input component
+ *   TWidget.NumberInput  — number spinner
+ *   TWidget.Checkbox     — toggleable check item
+ *   TWidget.Tabs         — tab bar + content switching
+ *   TWidget.Gauge        — animated gauge/meter
+ *   TWidget.Notification — timed toast notification
+ */
+class TWidget {
+
+  // ── Menu ───────────────────────────────────────────────────────────────────
+  /**
+   * Render a navigable menu into a TView.
+   * Returns a Promise that resolves to the selected item (or null on Escape).
+   *
+   * @param {TView}    view
+   * @param {string[]} items
+   * @param {object}   [opts]
+   * @param {number}   [opts.initialIndex=0]
+   * @param {*}        [opts.selectedColor='brightcyan']
+   * @param {*}        [opts.normalColor='white']
+   * @param {string}   [opts.prefix='  ']   — prefix for non-selected items
+   * @param {string}   [opts.selPrefix='▶ ']— prefix for selected item
+   */
+  static menu(view, items, opts = {}) {
+    return new Promise(resolve => {
+      const {
+        initialIndex = 0,
+        selectedColor = 'brightcyan',
+        normalColor   = 'white',
+        prefix        = '  ',
+        selPrefix     = '▶ ',
+      } = opts;
+      let idx = Math.max(0, Math.min(initialIndex, items.length - 1));
+
+      const draw = () => {
+        for (let i = 0; i < items.length && i < view.rows; i++) {
+          const sel = i === idx;
+          const pre = sel ? selPrefix : prefix;
+          const text = (pre + items[i]).padEnd(view.cols).slice(0, view.cols);
+          view.writeText(i, 0, text, {
+            color: [sel ? selectedColor : normalColor, null],
+            style: sel ? 'bold' : null,
+          });
+        }
+        view.markDirty();
+      };
+
+      draw();
+      view.focus();
+
+      const offUp    = view.onArrow('up',   () => { idx = (idx - 1 + items.length) % items.length; draw(); });
+      const offDown  = view.onArrow('down', () => { idx = (idx + 1) % items.length;                draw(); });
+      const offEnter = view.onKey('enter',  () => done(items[idx]));
+      const offEsc   = view.onKey('escape', () => done(null));
+      const offClick = view.onClick(({ localRow }) => {
+        if (localRow >= 0 && localRow < items.length) { idx = localRow; draw(); done(items[idx]); }
+      });
+
+      function done(value) {
+        offUp(); offDown(); offEnter(); offEsc(); offClick();
+        resolve(value);
+      }
+    });
+  }
+
+  // ── List ───────────────────────────────────────────────────────────────────
+  /**
+   * Multi-select scrollable list.
+   * Returns a Promise that resolves to an array of selected item strings.
+   *
+   * @param {TView}    view
+   * @param {string[]} items
+   * @param {object}   [opts]
+   * @param {boolean}  [opts.multiSelect=true]
+   * @param {number[]} [opts.preSelected=[]]
+   */
+  static list(view, items, opts = {}) {
+    return new Promise(resolve => {
+      const { multiSelect = true, preSelected = [], selectedColor = 'brightcyan', normalColor = 'white' } = opts;
+      let cursor = 0, scroll = 0;
+      const selected = new Set(preSelected);
+      const visRows  = view.rows;
+
+      const draw = () => {
+        for (let i = 0; i < visRows; i++) {
+          const idx = i + scroll;
+          if (idx >= items.length) { view.clearRow(i); continue; }
+          const isCursor   = idx === cursor;
+          const isSelected = selected.has(idx);
+          const mark  = isSelected ? '[✓] ' : '[ ] ';
+          const color = isCursor ? selectedColor : (isSelected ? 'brightgreen' : normalColor);
+          view.writeText(i, 0, (mark + items[idx]).padEnd(view.cols).slice(0, view.cols), { color:[color,null], style: isCursor?'bold':null });
+        }
+        view.markDirty();
+      };
+
+      draw();
+      view.focus();
+
+      const offUp   = view.onArrow('up',   () => { if(cursor>0){cursor--;if(cursor<scroll)scroll--;} draw(); });
+      const offDown = view.onArrow('down', () => { if(cursor<items.length-1){cursor++;if(cursor>=scroll+visRows)scroll++;} draw(); });
+      const offSpace= view.onKey('space',  () => { multiSelect?(selected.has(cursor)?selected.delete(cursor):selected.add(cursor)):(selected.clear(),selected.add(cursor)); draw(); });
+      const offEnter= view.onKey('enter',  () => done([...selected].map(i=>items[i])));
+      const offEsc  = view.onKey('escape', () => done([]));
+
+      function done(values) { offUp();offDown();offSpace();offEnter();offEsc(); resolve(values); }
+    });
+  }
+
+  // ── Dialog ─────────────────────────────────────────────────────────────────
+  /**
+   * Modal dialog over a view.
+   * @param {TView}    view        — the view to draw the dialog on
+   * @param {string}   title
+   * @param {string}   message
+   * @param {string[]} [buttons]   — default: ['OK', 'Cancel']
+   * @returns {Promise<string>}    — the label of the clicked/selected button
+   */
+  static dialog(view, title, message, buttons = ['OK', 'Cancel']) {
+    return new Promise(resolve => {
+      const snap  = view.snapshot();
+      const dw    = Math.min(view.cols - 4, Math.max(title.length + 4, message.length + 4, 30));
+      const dh    = 6;
+      const dr    = Math.floor((view.rows - dh) / 2);
+      const dc    = Math.floor((view.cols - dw) / 2);
+      let btnIdx  = 0;
+
+      const draw = () => {
+        view.drawBox(dr, dc, dh, dw, { color: ['brightcyan', null] }, 'double');
+        view.writeText(dr,     dc + Math.floor((dw - title.length)   / 2), title,   { color: ['brightwhite', null], style: 'bold' });
+        view.writeText(dr + 2, dc + Math.floor((dw - message.length) / 2), message, { color: ['white', null] });
+        let btnCol = dc + Math.floor((dw - buttons.reduce((a,b)=>a+b.length+4,0)) / 2);
+        buttons.forEach((btn, i) => {
+          const sel  = i === btnIdx;
+          const text = ` [ ${btn} ] `;
+          view.writeText(dr + 4, btnCol, text, { color: [sel ? 'black' : 'white', sel ? 'brightcyan' : null] });
+          btnCol += text.length;
+        });
+        view.markDirty();
+      };
+
+      draw();
+      view.focus();
+
+      const offLeft  = view.onArrow('left',  () => { btnIdx=(btnIdx-1+buttons.length)%buttons.length; draw(); });
+      const offRight = view.onArrow('right', () => { btnIdx=(btnIdx+1)%buttons.length; draw(); });
+      const offEnter = view.onKey('enter',   () => done(buttons[btnIdx]));
+      const offEsc   = view.onKey('escape',  () => done(buttons[buttons.length-1]));
+
+      function done(label) {
+        offLeft();offRight();offEnter();offEsc();
+        view.restoreSnapshot(snap);
+        resolve(label);
+      }
+    });
+  }
+
+  // ── TextInput ──────────────────────────────────────────────────────────────
+  /**
+   * Inline text-input rendered at (row, col) in a view.
+   * Returns a Promise<string|null>.
+   *
+   * @param {TView}  view
+   * @param {number} row
+   * @param {number} col
+   * @param {number} width
+   * @param {object} [opts]
+   * @param {string} [opts.placeholder]
+   * @param {string} [opts.initial]
+   * @param {string} [opts.mask]  — char to show instead of actual input (e.g. '*' for passwords)
+   */
+  static textInput(view, row, col, width, opts = {}) {
+    return new Promise(resolve => {
+      const { placeholder = '', initial = '', mask = null } = opts;
+      let value  = initial;
+      let cursor = value.length;
+
+      const draw = () => {
+        const display = mask ? mask.repeat(value.length) : value;
+        const visible = display.slice(Math.max(0, cursor - width + 1));
+        const text    = (visible || placeholder).padEnd(width).slice(0, width);
+        const color   = value.length ? 'white' : 'gray';
+        view.writeText(row, col, text, { color: [color, '#1a1a2e'] });
+        view.markDirty();
+        process.stdout.write(ansi.moveTo(view.offsetRow + row, view.offsetCol + col + Math.min(cursor, width - 1)));
+      };
+
+      draw(); view.focus();
+
+      const onKey = key => {
+        if (key.name === 'enter')     { cleanup(); resolve(value); }
+        else if (key.name === 'escape'){ cleanup(); resolve(null); }
+        else if (key.name === 'backspace' && cursor > 0)  { value=value.slice(0,cursor-1)+value.slice(cursor); cursor--; draw(); }
+        else if (key.name === 'delete' && cursor < value.length) { value=value.slice(0,cursor)+value.slice(cursor+1); draw(); }
+        else if (key.name === 'left'  && cursor > 0)             { cursor--; draw(); }
+        else if (key.name === 'right' && cursor < value.length)  { cursor++; draw(); }
+        else if (key.name === 'home') { cursor = 0; draw(); }
+        else if (key.name === 'end')  { cursor = value.length; draw(); }
+        else if (key.char && key.char >= ' ' && !key.ctrl) { value=value.slice(0,cursor)+key.char+value.slice(cursor); cursor++; draw(); }
+      };
+      view.on('key', onKey);
+      function cleanup() { view.removeListener('key', onKey); }
+    });
+  }
+
+  // ── Checkbox ───────────────────────────────────────────────────────────────
+  /**
+   * Toggle-able checkbox at (row, col).
+   * @param {TView}   view
+   * @param {number}  row
+   * @param {number}  col
+   * @param {string}  label
+   * @param {boolean} [initial=false]
+   * @returns {{ get: ()=>boolean, set: (v)=>void, off: ()=>void }}
+   */
+  static checkbox(view, row, col, label, initial = false) {
+    let value = initial;
+    const draw = () => {
+      const box = value ? '[✓]' : '[ ]';
+      view.writeText(row, col, `${box} ${label}`, { color: [value ? 'brightgreen' : 'white', null] });
+      view.markDirty();
+    };
+    draw();
+    const offClick = view.onClick(({ localRow, localCol }) => {
+      if (localRow === row && localCol >= col && localCol < col + 3 + label.length + 1) {
+        value = !value; draw();
+      }
+    });
+    view.focus();
+    return { get: () => value, set: v => { value = Boolean(v); draw(); }, off: offClick };
+  }
+
+  // ── Tabs ───────────────────────────────────────────────────────────────────
+  /**
+   * Tab bar rendered at (row) in a view.
+   * Returns a controller { active, setActive, onSwitch }.
+   *
+   * @param {TView}    view
+   * @param {number}   row        — row to draw the tab bar on
+   * @param {string[]} tabNames
+   */
+  static tabs(view, row, tabNames) {
+    let active = 0;
+    const handlers = [];
+
+    const draw = () => {
+      let col = 0;
+      tabNames.forEach((name, i) => {
+        const isActive = i === active;
+        const text = ` ${name} `;
+        view.writeText(row, col, text, {
+          color: [isActive ? 'black' : 'gray', isActive ? 'brightcyan' : null],
+          style: isActive ? 'bold' : null,
+        });
+        col += text.length + 1;
+      });
+      view.markDirty();
+    };
+    draw();
+
+    const offClick = view.onClick(({ localRow, localCol }) => {
+      if (localRow !== row) return;
+      let col = 0;
+      tabNames.forEach((name, i) => {
+        const w = name.length + 2;
+        if (localCol >= col && localCol < col + w) { active = i; draw(); handlers.forEach(h=>h(i,name)); }
+        col += w + 1;
+      });
+    });
+
+    return {
+      get active()      { return active; },
+      setActive(i)      { active=i; draw(); },
+      onSwitch(fn)      { handlers.push(fn); return ()=>{ const idx=handlers.indexOf(fn); if(idx>-1)handlers.splice(idx,1); }; },
+      destroy()         { offClick(); },
+    };
+  }
+
+  // ── Notification ───────────────────────────────────────────────────────────
+  /**
+   * Show a timed toast notification over a view.
+   *
+   * @param {TView}  view
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {number} [opts.duration=2500]   — ms before auto-dismiss
+   * @param {string} [opts.type]            — 'info'|'success'|'warn'|'error'
+   * @param {string} [opts.position]        — 'top'|'bottom' (default 'top')
+   */
+  static notify(view, message, opts = {}) {
+    const { duration=2500, type='info', position='top' } = opts;
+    const colors = { info:'brightcyan', success:'brightgreen', warn:'brightyellow', error:'brightred' };
+    const icons  = { info:'ℹ', success:'✔', warn:'⚠', error:'✖' };
+    const color  = colors[type] || 'brightcyan';
+    const icon   = icons[type]  || 'ℹ';
+    const snap   = view.snapshot();
+    const text   = ` ${icon} ${message} `;
+    const row    = position === 'bottom' ? view.rows - 2 : 1;
+    const col    = Math.max(0, Math.floor((view.cols - text.length) / 2));
+    view.writeText(row, col, text.slice(0,view.cols), { color: ['black', color] });
+    view.markDirty();
+    const timer = setTimeout(() => { view.restoreSnapshot(snap); view.markDirty(); }, duration);
+    return () => { clearTimeout(timer); view.restoreSnapshot(snap); view.markDirty(); };
+  }
+
+  // ── Gauge ──────────────────────────────────────────────────────────────────
+  /**
+   * Animated radial-style (ASCII) gauge rendered into a region.
+   * @param {TView}  view
+   * @param {number} row
+   * @param {number} col
+   * @param {number} [size=5]   — radius in chars (width = size*4+1)
+   */
+  static gauge(view, row, col, size = 5) {
+    let _value = 0;
+    const ARC = ['▁','▂','▃','▄','▅','▆','▇','█'];
+
+    const draw = () => {
+      const w = size * 4 + 1;
+      const filled = Math.round(_value * w);
+      const bar = ARC[7].repeat(filled).padEnd(w, '░').slice(0, w);
+      view.writeText(row,   col, bar, { color: [_value>0.7?'brightred':_value>0.4?'brightyellow':'brightgreen', null] });
+      const pct = `${Math.round(_value*100)}%`.padStart(4);
+      view.writeText(row+1, col + Math.floor((w-pct.length)/2), pct, { color: ['white', null] });
+      view.markDirty();
+    };
+    draw();
+    return {
+      set value(v) { _value = Math.max(0, Math.min(1, v)); draw(); },
+      get value()  { return _value; },
+    };
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §10  trouter  —  keyboard-driven screen router
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * TRouter  — push/pop/replace stack-based screen router.
+ *
+ * Each "screen" is a named factory function: (view, router, params) => cleanup.
+ * The cleanup function is called when the screen is popped or replaced.
+ *
+ * @example
+ *   const router = new TRouter(screen, inputManager);
+ *
+ *   router.register('home', (view, router) => {
+ *     view.writeCentered(2, 'Press ENTER to go to settings');
+ *     view.onKey('enter', () => router.push('settings'));
+ *     return () => view.clear();  // cleanup
+ *   });
+ *
+ *   router.register('settings', (view, router) => {
+ *     view.writeCentered(2, 'Settings — press Backspace to go back');
+ *     view.onKey('backspace', () => router.pop());
+ *     return () => view.clear();
+ *   });
+ *
+ *   router.push('home');
+ */
+class TRouter extends EventEmitter {
+  /**
+   * @param {TView}        rootView      — the single view screens render into
+   * @param {InputManager} [im]          — defaults to the module singleton
+   */
+  constructor(rootView, im = inputManager) {
+    super();
+    this._view    = rootView;
+    this._im      = im;
+    this._screens = new Map();    // name → factory(view, router, params) => cleanup
+    this._stack   = [];           // [{ name, params, cleanup }]
+    this._current = null;
+  }
+
+  /**
+   * Register a screen factory.
+   * @param {string}   name
+   * @param {function} factory  — (view, router, params) => (cleanup | void)
+   */
+  register(name, factory) {
+    this._screens.set(name, factory);
+    return this;
+  }
+
+  /** Push a new screen onto the stack (the previous screen is paused). */
+  push(name, params = {}) {
+    const factory = this._screens.get(name);
+    if (!factory) throw new Error(`TRouter: unknown screen "${name}"`);
+    this._suspend();
+    this._view.clear();
+    const _cr = factory(this._view, this, params);
+    const cleanup = typeof _cr === 'function' ? _cr : () => {};
+    this._stack.push({ name, params, cleanup });
+    this._current = name;
+    this._view.focus();
+    this.emit('push', { name, params, depth: this._stack.length });
+    this.emit('navigate', { name, params, action: 'push' });
+    return this;
+  }
+
+  /** Pop the current screen and resume the previous one. */
+  pop(result) {
+    if (this._stack.length <= 1) return this;
+    const top = this._stack.pop();
+    top.cleanup?.();
+    this._view.clear();
+    const prev = this._stack[this._stack.length - 1];
+    this._current = prev.name;
+    // Re-run the previous screen's factory (resume)
+    const _resumed = this._screens.get(prev.name)?.(this._view, this, prev.params);
+    prev.cleanup = typeof _resumed === 'function' ? _resumed : () => {};
+    this._view.focus();
+    this.emit('pop', { from: top.name, to: prev.name, result });
+    this.emit('navigate', { name: prev.name, params: prev.params, action: 'pop', result });
+    return this;
+  }
+
+  /** Replace the current screen without growing the stack. */
+  replace(name, params = {}) {
+    const factory = this._screens.get(name);
+    if (!factory) throw new Error(`TRouter: unknown screen "${name}"`);
+    if (this._stack.length > 0) { const top = this._stack.pop(); top.cleanup?.(); }
+    this._view.clear();
+    const _rr = factory(this._view, this, params);
+    const cleanup = typeof _rr === 'function' ? _rr : () => {};
+    this._stack.push({ name, params, cleanup });
+    this._current = name;
+    this._view.focus();
+    this.emit('replace', { name, params });
+    this.emit('navigate', { name, params, action: 'replace' });
+    return this;
+  }
+
+  /** Go to a specific depth in the stack (0 = root). */
+  go(delta) {
+    if (delta < 0) { for (let i=0;i<Math.abs(delta)&&this._stack.length>1;i++) this.pop(); }
+    return this;
+  }
+
+  /** Reset to root and push a new screen. */
+  reset(name, params = {}) {
+    while (this._stack.length > 0) { const top=this._stack.pop(); top.cleanup?.(); }
+    this._view.clear();
+    return this.push(name, params);
+  }
+
+  get current()    { return this._current; }
+  get stackDepth() { return this._stack.length; }
+  get canPop()     { return this._stack.length > 1; }
+
+  _suspend() {
+    // Run cleanup of current top without re-rendering previous
+    if (this._stack.length > 0) {
+      const top = this._stack[this._stack.length - 1];
+      top.cleanup?.();
+    }
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §11  Terminal  —  top-level bootstrap object
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Terminal  — boots the entire kit in one call.
+ *
+ * @example
+ *   const { kitdef } = require('./kitdef');
+ *   const { Terminal } = kitdef;
+ *
+ *   const term = new Terminal({ theme: 'dark', mouse: true });
+ *   term.on('ready', () => {
+ *     const [top, main, status] = term.screen.cutWeighted([0.08, 0.84, 0.08]);
+ *     term.log.setView(main);
+ *     term.log.info('Terminal ready', { cols: term.cols, rows: term.rows });
+ *   });
+ */
+class Terminal extends EventEmitter {
+  /**
+   * @param {object}  [opts]
+   * @param {boolean} [opts.altScreen=true]   — enter alternate screen buffer
+   * @param {boolean} [opts.mouse=true]        — enable mouse tracking
+   * @param {string}  [opts.theme='dark']      — initial TTheme
+   * @param {string}  [opts.logLevel='info']   — TLog level
+   * @param {string}  [opts.logFile]           — optional log file path
+   * @param {object}  [opts.env]               — extra env vars for TEnv / TShell
+   * @param {boolean} [opts.exitOnCtrlC=true]  — graceful Ctrl-C handler
+   */
+  constructor(opts = {}) {
+    super();
+    const {
+      altScreen    = true,
+      mouse        = true,
+      theme        = 'dark',
+      logLevel     = 'info',
+      logFile,
+      env          = {},
+      exitOnCtrlC  = true,
+    } = opts;
+
+    // ── Core singletons ────────────────────────────────────────────────────
+    this.input  = inputManager;
+    this.theme  = new TTheme(theme);
+    this.env    = new TEnv({ source: { ...process.env, ...env } });
+    this.log    = new TLog({ level: logLevel, file: logFile });
+    this.shell  = new TShell({ env });
+
+    // ── Full-screen root view ──────────────────────────────────────────────
+    this.screen = createFullscreen({ autoRegister: false, fps: 30 });
+    this.input.register(this.screen);
+
+    // ── Router (uses root screen) ──────────────────────────────────────────
+    this.router = new TRouter(this.screen, this.input);
+
+    // ── Start input ───────────────────────────────────────────────────────
+    this.input.start({ mouse });
+    if (altScreen) {
+      process.stdout.write(ansi.altScreenOn + ansi.clear + ansi.cursorHome);
+      this._altScreen = true;
+    }
+
+    // ── Terminal resize → screen resize ───────────────────────────────────
+    this.input.on('resize', ({ rows, cols }) => {
+      this.screen.resize(rows, cols);
+      this.emit('resize', { rows, cols });
+    });
+
+    // ── Graceful exit ─────────────────────────────────────────────────────
+    if (exitOnCtrlC) {
+      this.input.on('sigint', () => this.exit(0));
+    }
+
+    // Expose dimensions as getters
+    Object.defineProperty(this, 'rows', { get: () => process.stdout.rows    || 24 });
+    Object.defineProperty(this, 'cols', { get: () => process.stdout.columns || 80 });
+
+    setImmediate(() => this.emit('ready', this));
+  }
+
+  /**
+   * Gracefully shut down everything and exit.
+   * @param {number} [code=0]
+   */
+  exit(code = 0) {
+    this.emit('exit', code);
+    this.input.disableMouse();
+    this.input.stop();
+    this.log.close();
+    if (this._altScreen) process.stdout.write(ansi.altScreenOff);
+    process.stdout.write(ansi.showCursor + '\n');
+    // Give one tick for final writes to flush
+    setImmediate(() => process.exit(code));
+  }
+
+  /**
+   * Create a TView pre-wired to the active theme's colors.
+   * @param {object} opts — passed to TView constructor
+   */
+  createView(opts = {}) {
+    return new TView({
+      defaultFg: this.theme.get('fg'),
+      defaultBg: this.theme.get('bg'),
+      ...opts,
+    });
+  }
+
+  /**
+   * Render the whole screen (useful after layout changes).
+   */
+  render() { this.screen.render(); return this; }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+//  §12  module.exports
+// ═════════════════════════════════════════════════════════════════════════════
+
+const kitdef = {
+  // ── tview ─────────────────────────────────────────────────────────────────
+  TVPixel,
+  TView,
+  InputManager,
+  inputManager,
+  createFullscreen,
+  px,
+  ansi,
+  BORDER_STYLES,
+  KEY_MAP,
+
+  // ── tshell ────────────────────────────────────────────────────────────────
+  TShell,
+
+  // ── tenv ──────────────────────────────────────────────────────────────────
+  TEnv,
+
+  // ── tlog ──────────────────────────────────────────────────────────────────
+  TLog,
+
+  // ── ttheme ────────────────────────────────────────────────────────────────
+  TTheme,
+
+  // ── twidget ───────────────────────────────────────────────────────────────
+  TWidget,
+
+  // ── trouter ───────────────────────────────────────────────────────────────
+  TRouter,
+
+  // ── Terminal bootstrap ────────────────────────────────────────────────────
+  Terminal,
+};
+
+module.exports = { kitdef };