ultracost 0.2.1 → 0.3.1

package/src/lexer.js

@@ -0,0 +1,227 @@
+// Minimal zero-dependency JavaScript tokenizer. NOT a full parser: it emits a flat
+// token stream rich enough to (a) locate real `agent(...)` / `agent?.(...)` call sites
+// (never inside strings, template literals, or comments), (b) read an options object
+// literal's `model`/`effort` values and detect spreads, and (c) recover the literal
+// text of a possibly-concatenated prompt argument. It resolves the regex-vs-divide
+// ambiguity, optional chaining, and nested template substitutions.
+
+export const TT = {
+  NAME: 'name', // identifier or keyword
+  PUNCT: 'punct', // operator / punctuation
+  STRING: 'string', // '...' or "..."
+  TEMPLATE: 'template', // `...` — value is the cooked text, or null when it has a ${} substitution
+  NUMBER: 'number',
+  REGEX: 'regex'
+};
+
+const isIdStart = (ch) =>
+  ch === '_' || ch === '$' ||
+  (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') ||
+  ch.charCodeAt(0) > 127;
+const isIdPart = (ch) => isIdStart(ch) || (ch >= '0' && ch <= '9');
+const isDigit = (ch) => ch >= '0' && ch <= '9';
+const isWS = (ch) =>
+  ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r' ||
+  ch === '\f' || ch === '\v' || ch === '\u00a0' || ch === '\ufeff';
+
+// Keywords after which a `/` starts a REGEX (they expect an expression next). After
+// any other name (identifier, this/true/null/...) a `/` is DIVISION.
+const KEYWORD_PREFIX = new Set([
+  'return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void',
+  'throw', 'do', 'else', 'yield', 'await', 'case'
+]);
+
+const PUNCT3 = new Set(['...', '===', '!==', '**=', '<<=', '>>=', '&&=', '||=', '??=', '>>>']);
+const PUNCT2 = new Set([
+  '?.', '=>', '==', '!=', '<=', '>=', '&&', '||', '??',
+  '+=', '-=', '*=', '/=', '%=', '&=', '|=', '^=', '++', '--', '**', '<<', '>>'
+]);
+
+function decodeEscapes(inner) {
+  if (inner.indexOf('\\') === -1) return inner;
+  let out = '';
+  for (let i = 0; i < inner.length; i++) {
+    if (inner[i] !== '\\') { out += inner[i]; continue; }
+    const c = inner[++i];
+    if (c === 'n') out += '\n';
+    else if (c === 't') out += '\t';
+    else if (c === 'r') out += '\r';
+    else if (c === 'b') out += '\b';
+    else if (c === 'f') out += '\f';
+    else if (c === 'v') out += '\v';
+    else if (c === '0') out += '\0';
+    else if (c === 'x') { out += String.fromCharCode(parseInt(inner.substr(i + 1, 2), 16) || 0); i += 2; }
+    else if (c === 'u') {
+      if (inner[i + 1] === '{') {
+        const e = inner.indexOf('}', i);
+        out += String.fromCodePoint(parseInt(inner.slice(i + 2, e), 16) || 0);
+        i = e;
+      } else { out += String.fromCharCode(parseInt(inner.substr(i + 1, 4), 16) || 0); i += 4; }
+    } else if (c === '\n') { /* line continuation: drop */ }
+    else if (c !== undefined) out += c;
+  }
+  return out;
+}
+
+export function tokenize(src) {
+  const tokens = [];
+  const n = src.length;
+  let i = 0;
+  let prev = null;
+  const push = (t) => { tokens.push(t); prev = t; };
+
+  const regexAllowed = () => {
+    if (!prev) return true;
+    if (prev.type === TT.NUMBER || prev.type === TT.STRING || prev.type === TT.TEMPLATE || prev.type === TT.REGEX) return false;
+    if (prev.type === TT.NAME) return KEYWORD_PREFIX.has(prev.value);
+    if (prev.type === TT.PUNCT) return !(prev.value === ')' || prev.value === ']' || prev.value === '}');
+    return true;
+  };
+
+  while (i < n) {
+    const ch = src[i];
+    if (isWS(ch)) { i++; continue; }
+
+    if (ch === '/' && src[i + 1] === '/') {
+      i += 2; while (i < n && src[i] !== '\n') i++; continue;
+    }
+    if (ch === '/' && src[i + 1] === '*') {
+      i += 2; while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++; i = Math.min(n, i + 2); continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      const start = i; const q = ch; i++;
+      let inner = '';
+      while (i < n) {
+        const c = src[i];
+        if (c === '\\') { inner += c + (src[i + 1] ?? ''); i += 2; continue; }
+        if (c === q) { i++; break; }
+        if (c === '\n') break; // unterminated
+        inner += c; i++;
+      }
+      push({ type: TT.STRING, value: decodeEscapes(inner), quote: q, start, end: i });
+      continue;
+    }
+
+    if (ch === '`') {
+      const start = i; i++;
+      let hasSub = false;
+      let cooked = '';
+      while (i < n) {
+        const c = src[i];
+        if (c === '\\') { cooked += c + (src[i + 1] ?? ''); i += 2; continue; }
+        if (c === '`') { i++; break; }
+        if (c === '$' && src[i + 1] === '{') {
+          hasSub = true; i += 2;
+          let depth = 1;
+          while (i < n && depth > 0) {
+            const d = src[i];
+            if (d === '{') { depth++; i++; }
+            else if (d === '}') { depth--; i++; }
+            else if (d === '`') { i = skipTemplate(src, i, n); }
+            else if (d === "'" || d === '"') { i = skipString(src, i, n); }
+            else i++;
+          }
+          continue;
+        }
+        cooked += c; i++;
+      }
+      push({ type: TT.TEMPLATE, value: hasSub ? null : decodeEscapes(cooked), hasSub, start, end: i });
+      continue;
+    }
+
+    if (ch === '/') {
+      if (regexAllowed()) {
+        const start = i; i++;
+        let inClass = false;
+        while (i < n) {
+          const c = src[i];
+          if (c === '\\') { i += 2; continue; }
+          if (c === '[') inClass = true;
+          else if (c === ']') inClass = false;
+          else if (c === '/' && !inClass) { i++; break; }
+          else if (c === '\n') break;
+          i++;
+        }
+        while (i < n && isIdPart(src[i])) i++; // flags
+        push({ type: TT.REGEX, value: src.slice(start, i), start, end: i });
+        continue;
+      }
+      // otherwise fall through: `/` or `/=` is a division/assignment punctuator
+    }
+
+    if (isDigit(ch) || (ch === '.' && isDigit(src[i + 1]))) {
+      const start = i; i++;
+      while (i < n) {
+        const c = src[i];
+        if ((c === '+' || c === '-')) { if (src[i - 1] === 'e' || src[i - 1] === 'E') { i++; continue; } break; }
+        if (isIdPart(c) || c === '.') { i++; continue; }
+        break;
+      }
+      push({ type: TT.NUMBER, value: src.slice(start, i), start, end: i });
+      continue;
+    }
+
+    if (isIdStart(ch)) {
+      const start = i; i++;
+      while (i < n && isIdPart(src[i])) i++;
+      push({ type: TT.NAME, value: src.slice(start, i), start, end: i });
+      continue;
+    }
+
+    const three = src.slice(i, i + 3);
+    if (PUNCT3.has(three)) { push({ type: TT.PUNCT, value: three, start: i, end: i + 3 }); i += 3; continue; }
+    const two = src.slice(i, i + 2);
+    if (PUNCT2.has(two)) { push({ type: TT.PUNCT, value: two, start: i, end: i + 2 }); i += 2; continue; }
+    push({ type: TT.PUNCT, value: ch, start: i, end: i + 1 }); i += 1;
+  }
+  return tokens;
+}
+
+// Skip a single- or double-quoted string starting at `from` (the quote). Returns the
+// index just past the closing quote.
+function skipString(src, from, n) {
+  const q = src[from];
+  let i = from + 1;
+  while (i < n) {
+    if (src[i] === '\\') { i += 2; continue; }
+    if (src[i] === q || src[i] === '\n') { return i + 1; }
+    i++;
+  }
+  return i;
+}
+
+// Skip a template literal starting at `from` (the backtick), including any nested
+// ${...} substitutions and nested templates. Returns the index past the closing tick.
+function skipTemplate(src, from, n) {
+  let i = from + 1;
+  while (i < n) {
+    const c = src[i];
+    if (c === '\\') { i += 2; continue; }
+    if (c === '`') return i + 1;
+    if (c === '$' && src[i + 1] === '{') {
+      i += 2; let depth = 1;
+      while (i < n && depth > 0) {
+        const d = src[i];
+        if (d === '{') { depth++; i++; }
+        else if (d === '}') { depth--; i++; }
+        else if (d === '`') { i = skipTemplate(src, i, n); }
+        else if (d === "'" || d === '"') { i = skipString(src, i, n); }
+        else i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return i;
+}
+
+// 1-based line and column for a source index (for findings).
+export function lineColAt(src, index) {
+  let line = 1;
+  let last = 0;
+  for (let i = 0; i < index && i < src.length; i++) {
+    if (src[i] === '\n') { line++; last = i + 1; }
+  }
+  return { line, column: index - last + 1 };
+}

package/src/log.js

@@ -1,18 +1,25 @@
-const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
-
-const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+import { color, bold, dim } from './render.js';
 
+// Back-compatible styling surface. `c.*` keeps the names the CLI already uses, now
+// backed by the brand palette in render.js (truecolor with 256/16/no-color fallback).
 export const c = {
-  bold: wrap('1'),
-  dim: wrap('2'),
-  red: wrap('31'),
-  green: wrap('32'),
-  yellow: wrap('33'),
-  cyan: wrap('36')
+  bold,
+  dim,
+  red: color.red,
+  green: color.green,
+  yellow: color.amber,
+  cyan: color.cyan,
+  violet: color.violet,
+  magenta: color.magenta,
+  amber: color.amber,
+  slate: color.slate
 };
 
 export const log = (msg = '') => console.log(msg);
-export const ok = (msg) => log(`${c.green('OK')} ${msg}`);
-export const warn = (msg) => log(`${c.yellow('!!')} ${msg}`);
-export const err = (msg) => log(`${c.red('XX')} ${msg}`);
-export const info = (msg) => log(c.dim(msg));
+export const ok = (msg) => log(`${color.green('✓')} ${msg}`);
+export const warn = (msg) => log(`${color.amber('!')} ${msg}`);
+export const err = (msg) => log(`${color.red('✗')} ${msg}`);
+export const info = (msg) => log(dim(msg));
+
+// Re-export the full render kit so callers can `import { panel, columns, bar } from './log.js'`.
+export * from './render.js';

package/src/loop.js

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CALIBRATION_PATH, LEDGER_PATH } from './paths.js';
+import { costFromUsage, modelPrice, totalTokens } from './cost.js';
+import { tierOfModel } from './classify.js';
+
+// The closed loop: turn the per-stage token sums from transcript.js into reconciled
+// cost (actual vs an all-opus baseline), a self-calibrating token prior, and a
+// persisted savings ledger. All offline; reuses the cost model in cost.js.
+
+const median = (arr) => {
+  if (!arr.length) return 0;
+  const s = [...arr].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+function ensureDir(file) {
+  const d = dirname(file);
+  if (!existsSync(d)) mkdirSync(d, { recursive: true });
+}
+
+// Effective input tokens — fold cache reads/writes into an input-equivalent at the
+// policy's multipliers so the estimator's single input number prices realistically.
+function effectiveInput(u, policy) {
+  const mult = policy?.estimation?.cacheMultipliers || { cacheRead: 0.1, cacheWrite: 1.25 };
+  return (u.input_tokens || 0) +
+    (u.cache_read_input_tokens || 0) * (mult.cacheRead ?? 0.1) +
+    (u.cache_creation_input_tokens || 0) * (mult.cacheWrite ?? 1.25);
+}
+
+// Reconcile one workflow run: actual cost per stage at its real model vs the all-opus
+// baseline (the same tokens re-priced at opus rates).
+export function reconcileRun(run, policy) {
+  const opusPrice = modelPrice('opus', policy);
+  const stages = run.stages.map((s) => {
+    const price = modelPrice(s.model, policy);
+    return {
+      ...s,
+      tier: tierOfModel(s.model),
+      tokens: totalTokens(s.usage),
+      actualCost: costFromUsage(s.usage, price, policy),
+      opusCost: costFromUsage(s.usage, opusPrice, policy)
+    };
+  });
+  const actual = stages.reduce((n, s) => n + s.actualCost, 0);
+  const allOpus = stages.reduce((n, s) => n + s.opusCost, 0);
+  return {
+    wfId: run.wfId,
+    dir: run.dir,
+    project: run.project,
+    ts: run.mtime ? new Date(run.mtime).toISOString() : null,
+    stages,
+    totals: {
+      actual,
+      allOpus,
+      saved: allOpus - actual,
+      savedPct: allOpus ? Math.round((1 - actual / allOpus) * 100) : 0,
+      tokens: stages.reduce((n, s) => n + s.tokens, 0)
+    }
+  };
+}
+
+// Build a calibrated token prior from real runs. tokencast-style: drop per-stage
+// outliers (> 3x or < 0.2x the median total) before taking medians.
+export function calibrationFromRuns(runs, policy) {
+  const stages = runs.flatMap((r) => r.stages || []);
+  let recs = stages
+    .map((s) => ({ inT: effectiveInput(s.usage, policy), outT: s.usage.output_tokens || 0, tot: totalTokens(s.usage), model: s.model }))
+    .filter((r) => r.tot > 0);
+  if (!recs.length) return null;
+  const medTot = median(recs.map((r) => r.tot));
+  recs = recs.filter((r) => r.tot <= medTot * 3 && r.tot >= medTot * 0.2);
+  if (!recs.length) return null;
+
+  const tokensPerStage = { input: Math.round(median(recs.map((r) => r.inT))), output: Math.round(median(recs.map((r) => r.outT))) };
+  const perModel = {};
+  for (const k of ['opus', 'sonnet']) {
+    const ms = recs.filter((r) => String(r.model || '').toLowerCase().includes(k));
+    if (ms.length) perModel[k] = { input: Math.round(median(ms.map((r) => r.inT))), output: Math.round(median(ms.map((r) => r.outT))), samples: ms.length };
+  }
+  return {
+    _asOf: new Date().toISOString().slice(0, 10),
+    runs: runs.length,
+    samples: recs.length,
+    droppedOutliers: stages.length - recs.length,
+    tokensPerStage,
+    perModel
+  };
+}
+
+export function readCalibration() {
+  if (!existsSync(CALIBRATION_PATH)) return null;
+  try { return JSON.parse(readFileSync(CALIBRATION_PATH, 'utf8')); } catch { return null; }
+}
+
+export function writeCalibration(cal) {
+  ensureDir(CALIBRATION_PATH);
+  writeFileSync(CALIBRATION_PATH, JSON.stringify(cal, null, 2) + '\n');
+  return CALIBRATION_PATH;
+}
+
+// Return a shallow policy clone whose estimator token prior comes from calibration
+// (if present). estimate.js stays pure — the CLI/gate opt in via this.
+export function applyCalibration(policy, cal = readCalibration()) {
+  if (!cal || !cal.tokensPerStage) return policy;
+  return { ...policy, estimation: { ...policy.estimation, tokensPerStage: cal.tokensPerStage }, _calibrated: true };
+}
+
+export function ledgerRead() {
+  if (!existsSync(LEDGER_PATH)) return [];
+  try {
+    return readFileSync(LEDGER_PATH, 'utf8').split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+  } catch { return []; }
+}
+
+// Reconcile every run and upsert one ledger line per workflow id (idempotent — re-running
+// does not double-count). Returns the full, deduped, date-sorted ledger.
+export function ledgerSync(runs, policy) {
+  const byId = new Map(ledgerRead().map((e) => [e.wfId, e]));
+  for (const run of runs) {
+    const r = reconcileRun(run, policy);
+    byId.set(r.wfId, {
+      wfId: r.wfId,
+      project: r.project,
+      ts: r.ts,
+      stages: r.stages.length,
+      actual: r.totals.actual,
+      allOpus: r.totals.allOpus,
+      saved: r.totals.saved,
+      savedPct: r.totals.savedPct,
+      tokens: r.totals.tokens
+    });
+  }
+  const entries = [...byId.values()].sort((a, b) => String(a.ts).localeCompare(String(b.ts)));
+  ensureDir(LEDGER_PATH);
+  writeFileSync(LEDGER_PATH, entries.map((e) => JSON.stringify(e)).join('\n') + (entries.length ? '\n' : ''));
+  return entries;
+}
+
+export function spentToday(entries = ledgerRead(), day = new Date().toISOString().slice(0, 10)) {
+  return entries.filter((e) => String(e.ts).slice(0, 10) === day).reduce((n, e) => n + (e.actual || 0), 0);
+}

package/src/paths.js

@@ -12,10 +12,20 @@ export const CLAUDE_DIR = process.env.CLAUDE_CONFIG_DIR
   : join(HOME, '.claude');
 export const CLAUDE_MD = join(CLAUDE_DIR, 'CLAUDE.md');
 export const SETTINGS = join(CLAUDE_DIR, 'settings.json');
+export const SETTINGS_LOCAL = join(CLAUDE_DIR, 'settings.local.json');
 export const ULTRACOST_DIR = join(CLAUDE_DIR, 'ultracost');
 export const POLICY_PATH = join(ULTRACOST_DIR, 'policy.json');
 export const PROJECTS_DIR = join(CLAUDE_DIR, 'projects');
 
+// Local data the closed-loop commands persist (calibration priors + savings ledger).
+export const CALIBRATION_PATH = join(ULTRACOST_DIR, 'calibration.json');
+export const LEDGER_PATH = join(ULTRACOST_DIR, 'ledger.jsonl');
+
+// Plugin delivery: Claude Code caches the plugin under plugins/cache/<owner>/<name>/<version>/.
+export const PLUGINS_DIR = join(CLAUDE_DIR, 'plugins');
+export const PLUGIN_CACHE_DIR = join(PLUGINS_DIR, 'cache', 'ultracost', 'ultracost');
+export const PLUGIN_ID = 'ultracost@ultracost';
+
 export const HOOK_PATH = join(ULTRACOST_DIR, 'reinject.mjs');
 
 export const DEFAULT_POLICY = join(ROOT, 'templates', 'policy.default.json');

package/src/policy.js

@@ -49,6 +49,16 @@ export function normalize(input) {
   p.estimation.tokensPerStage ??= { input: 2000, output: 1200 };
   p.estimation.effortOutputMultiplier ??= { low: 0.4, medium: 1, high: 1.8, xhigh: 3, max: 4 };
   p.estimation.assumedFanout ??= 5;
+  p.estimation.cacheMultipliers ??= { cacheRead: 0.1, cacheWrite: 1.25 };
+
+  p.classify ??= {};
+  p.classify.keywords ??= {};
+  p.classify.keywords.opus ??= [];
+  p.classify.keywords.sonnet ??= [];
+
+  p.budget ??= {};
+  p.budget.perRun ??= null;
+  p.budget.perDay ??= null;
 
   const errors = [];
   if (!p.tiers[p.default]) errors.push(`default tier "${p.default}" is not defined in tiers`);
@@ -61,6 +71,10 @@ export function normalize(input) {
       errors.push(`tier "${name}" uses model "${t.model}" which is listed in neverUse`);
     }
   }
+  for (const k of ['perRun', 'perDay']) {
+    const v = p.budget[k];
+    if (v !== null && !(typeof v === 'number' && v >= 0)) errors.push(`budget.${k} must be a non-negative number or null`);
+  }
   if (errors.length) throw new Error('Invalid policy:\n  - ' + errors.join('\n  - '));
   return p;
 }

package/src/render.js

@@ -0,0 +1,211 @@
+// Zero-dependency terminal rendering kit. Uses only Node stdlib: getColorDepth for
+// capability detection, stripVTControlCharacters + Intl.Segmenter for width-aware
+// alignment, and hand-rolled ANSI for truecolor/256/16 with graceful downsample.
+// Honors NO_COLOR and FORCE_COLOR. No npm dependencies (a hard project constraint).
+
+import { stripVTControlCharacters } from 'node:util';
+
+// ultracost brand palette — ported from scripts/generate-architecture-svg.py so the
+// CLI matches the docs/architecture diagram.
+export const COLORS = {
+  violet: '#a78bfa',
+  magenta: '#e879f9',
+  pink: '#f472b6',
+  cyan: '#22d3ee',
+  lilac: '#c4b5fd',
+  amber: '#fbbf24',
+  green: '#34d399',
+  red: '#fb7185',
+  clay: '#d97757',
+  slate: '#94a3b8'
+};
+
+export function colorDepth() {
+  if (process.env.NO_COLOR !== undefined) return 1;
+  const fc = process.env.FORCE_COLOR;
+  if (fc !== undefined) {
+    if (fc === '0' || fc === 'false') return 1;
+    if (fc === '1' || fc === 'true') return 4;
+    if (fc === '2') return 8;
+    return 24;
+  }
+  if (!process.stdout || !process.stdout.isTTY) return 1;
+  try { return process.stdout.getColorDepth(); } catch { return 4; }
+}
+
+export const supportsColor = () => colorDepth() > 1;
+
+function hexToRgb(hex) {
+  const h = hex.replace('#', '');
+  return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+}
+
+function rgbTo256(r, g, b) {
+  if (r === g && g === b) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return Math.round(((r - 8) / 247) * 24) + 232;
+  }
+  return 16 + 36 * Math.round((r / 255) * 5) + 6 * Math.round((g / 255) * 5) + Math.round((b / 255) * 5);
+}
+
+function rgbTo16(r, g, b) {
+  const bit = (v) => (v > 110 ? 1 : 0);
+  let code = 30 + (bit(r) | (bit(g) << 1) | (bit(b) << 2));
+  if ((r + g + b) / 3 > 150) code += 60;
+  return code;
+}
+
+// Wrap a string in a truecolor/256/16 foreground escape appropriate to the terminal.
+export function paint(str, hex) {
+  const d = colorDepth();
+  if (d <= 1) return String(str);
+  const [r, g, b] = hexToRgb(hex);
+  if (d >= 24) return `\x1b[38;2;${r};${g};${b}m${str}\x1b[39m`;
+  if (d >= 8) return `\x1b[38;5;${rgbTo256(r, g, b)}m${str}\x1b[39m`;
+  return `\x1b[${rgbTo16(r, g, b)}m${str}\x1b[39m`;
+}
+
+const sgr = (open, close) => (s) => (supportsColor() ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+export const bold = sgr(1, 22);
+export const dim = sgr(2, 22);
+export const italic = sgr(3, 23);
+export const underline = sgr(4, 24);
+
+// Named brand colorizers, e.g. color.violet('text').
+export const color = Object.fromEntries(Object.entries(COLORS).map(([k, hex]) => [k, (s) => paint(s, hex)]));
+
+// A left-to-right two-stop gradient across a string (truecolor only; else solid start).
+export function gradient(str, startHex, endHex) {
+  const s = String(str);
+  if (colorDepth() < 24) return paint(s, startHex);
+  const [r1, g1, b1] = hexToRgb(startHex);
+  const [r2, g2, b2] = hexToRgb(endHex);
+  const chars = [...s];
+  const n = Math.max(1, chars.length - 1);
+  return chars
+    .map((ch, i) => {
+      const t = i / n;
+      const r = Math.round(r1 + (r2 - r1) * t);
+      const g = Math.round(g1 + (g2 - g1) * t);
+      const b = Math.round(b1 + (b2 - b1) * t);
+      return `\x1b[38;2;${r};${g};${b}m${ch}`;
+    })
+    .join('') + '\x1b[39m';
+}
+
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+const WIDE = [
+  [0x1100, 0x115f], [0x2e80, 0x303e], [0x3041, 0x33ff], [0x3400, 0x4dbf],
+  [0x4e00, 0x9fff], [0xa000, 0xa4cf], [0xac00, 0xd7a3], [0xf900, 0xfaff],
+  [0xfe30, 0xfe4f], [0xff00, 0xff60], [0xffe0, 0xffe6], [0x1f300, 0x1faff],
+  [0x20000, 0x3fffd]
+];
+const isWide = (cp) => WIDE.some(([a, b]) => cp >= a && cp <= b);
+
+// Display width that ignores ANSI escapes and counts wide/emoji graphemes as 2.
+export function displayWidth(str) {
+  const plain = stripVTControlCharacters(String(str));
+  let w = 0;
+  for (const { segment } of segmenter.segment(plain)) {
+    const cp = segment.codePointAt(0);
+    if (cp === 0) continue;
+    w += segment.length > 1 || isWide(cp) ? 2 : 1;
+  }
+  return w;
+}
+
+export function truncate(str, max, ellipsis = '…') {
+  if (displayWidth(str) <= max) return String(str);
+  let out = '';
+  let w = 0;
+  for (const { segment } of segmenter.segment(stripVTControlCharacters(String(str)))) {
+    const cw = segment.length > 1 || isWide(segment.codePointAt(0)) ? 2 : 1;
+    if (w + cw > max - 1) break;
+    out += segment;
+    w += cw;
+  }
+  return out + ellipsis;
+}
+
+export function pad(str, width, align = 'left') {
+  const s = String(str);
+  const gap = Math.max(0, width - displayWidth(s));
+  if (align === 'right') return ' '.repeat(gap) + s;
+  if (align === 'center') {
+    const l = Math.floor(gap / 2);
+    return ' '.repeat(l) + s + ' '.repeat(gap - l);
+  }
+  return s + ' '.repeat(gap);
+}
+
+// A proportional bar built from eighth-blocks for sub-cell precision.
+export function bar(value, max, width = 24, hex = COLORS.green) {
+  const frac = max > 0 ? Math.max(0, Math.min(1, value / max)) : 0;
+  const units = frac * width;
+  const full = Math.floor(units);
+  const rem = units - full;
+  const eighths = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];
+  const tip = rem > 0 ? eighths[Math.round(rem * 8)] || '' : '';
+  const filled = '█'.repeat(full) + tip;
+  const used = full + (tip ? 1 : 0);
+  return paint(filled, hex) + dim('░'.repeat(Math.max(0, width - used)));
+}
+
+const SPARK = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+export function sparkline(values, hex) {
+  const nums = values.filter((v) => Number.isFinite(v));
+  if (!nums.length) return '';
+  const min = Math.min(...nums);
+  const max = Math.max(...nums);
+  const span = max - min || 1;
+  const s = values
+    .map((v) => (Number.isFinite(v) ? SPARK[Math.min(7, Math.floor(((v - min) / span) * 7.999))] : ' '))
+    .join('');
+  return hex ? paint(s, hex) : s;
+}
+
+export const hr = (width, hex = COLORS.slate, ch = '─') => paint(ch.repeat(Math.max(0, width)), hex);
+
+// A rounded panel with an optional title. `lines` is an array of already-styled rows.
+export function panel(lines, { title = '', hex = COLORS.violet, pad: padX = 1, minWidth = 0 } = {}) {
+  const body = Array.isArray(lines) ? lines : String(lines).split('\n');
+  const inner = Math.max(minWidth, displayWidth(title) + 2, ...body.map((l) => displayWidth(l)));
+  const w = inner + padX * 2;
+  const sp = ' '.repeat(padX);
+  const top = title
+    ? paint('╭─ ', hex) + bold(title) + ' ' + paint('─'.repeat(Math.max(0, w - displayWidth(title) - 3)) + '╮', hex)
+    : paint('╭' + '─'.repeat(w) + '╮', hex);
+  const mid = body.map((l) => paint('│', hex) + sp + pad(l, inner) + sp + paint('│', hex));
+  const bot = paint('╰' + '─'.repeat(w) + '╯', hex);
+  return [top, ...mid, bot].join('\n');
+}
+
+// Aligned columns (no grid borders). rows: array of arrays of (possibly styled) cells.
+export function columns(rows, { align = [], gap = 2, head = null, indent = 0 } = {}) {
+  const all = head ? [head, ...rows] : rows;
+  const cols = Math.max(0, ...all.map((r) => r.length));
+  const widths = [];
+  for (let c = 0; c < cols; c++) widths[c] = Math.max(0, ...all.map((r) => displayWidth(r[c] ?? '')));
+  const pre = ' '.repeat(indent);
+  const sep = ' '.repeat(gap);
+  const renderRow = (r) =>
+    pre + r.map((cell, c) => pad(cell ?? '', widths[c], align[c] || 'left')).join(sep).replace(/\s+$/, '');
+  const out = [];
+  if (head) {
+    out.push(pre + head.map((cell, c) => bold(pad(cell ?? '', widths[c], align[c] || 'left'))).join(sep).replace(/\s+$/, ''));
+  }
+  for (const r of rows) out.push(renderRow(r));
+  return out.join('\n');
+}
+
+export const symbols = {
+  ok: '✓',
+  warn: '!',
+  err: '✗',
+  bullet: '•',
+  arrow: '→',
+  dot: '●',
+  pin: '●',
+  none: '○'
+};