@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/src/core/ui/controller.mjs

@@ -0,0 +1,192 @@
+/**
+ * AnimationController — decides whether animation is allowed and manages timers/cursor.
+ *
+ * Respects: NO_COLOR, TERM=dumb, !isTTY, CI, --json, --fast/pace=0,
+ * CIRVIX_NO_ANIM, CIRVIX_REDUCED_MOTION, FORCE_COLOR override.
+ *
+ * Every animation cleans up its own intervals/timeouts and restores cursor.
+ */
+
+import { isInteractive } from "../format.mjs";
+
+export function shouldAnimate({ pace, json, force } = {}) {
+  if (json) return false;
+  if (pace === 0) return false;
+  if (process.env.CIRVIX_NO_ANIM === "1") return false;
+  if (process.env.CIRVIX_REDUCED_MOTION === "1") return false;
+  if (force === false) return false;
+  if (force === true) return true;
+  // format.mjs already handles NO_COLOR / TERM=dumb / !isTTY / FORCE_COLOR
+  // but CI gate is extra: CI without FORCE_COLOR should not animate
+  if (process.env.CI !== undefined && process.env.FORCE_COLOR !== "1" && process.env.FORCE_COLOR !== "true") {
+    return false;
+  }
+  return isInteractive();
+}
+
+/** Hide cursor, remember to show it on exit. */
+export function hideCursor(stream = process.stdout) {
+  if (!stream.isTTY) return () => {};
+  try {
+    stream.write("\u001b[?25l");
+  } catch {}
+  let shown = false;
+  const show = () => {
+    if (shown) return;
+    shown = true;
+    try {
+      stream.write("\u001b[?25h");
+    } catch {}
+  };
+  const onExit = () => show();
+  // Ensure cleanup on ctrl+c or exit.
+  process.once("SIGINT", onExit);
+  process.once("SIGTERM", onExit);
+  process.once("exit", onExit);
+  return () => {
+    show();
+    process.off("SIGINT", onExit);
+    process.off("SIGTERM", onExit);
+    process.off("exit", onExit);
+  };
+}
+
+/** Spinner frames — subtle, not gamey. */
+export const SPINNER_FRAMES = ["◌", "◎", "◉", "◎"];
+export const SPINNER_ASCII = ["-", "\\", "|", "/"];
+
+export class Spinner {
+  constructor(label, { stream = process.stdout, enabled = shouldAnimate({}) } = {}) {
+    this.label = label;
+    this.stream = stream;
+    this.enabled = enabled;
+    this.interval = null;
+    this.frame = 0;
+    this.restoreCursor = null;
+  }
+
+  start() {
+    if (!this.enabled) {
+      this.stream.write(`${this.label}\n`);
+      return this;
+    }
+    this.restoreCursor = hideCursor(this.stream);
+    this.interval = setInterval(() => {
+      const ch = SPINNER_FRAMES[this.frame % SPINNER_FRAMES.length];
+      this.frame++;
+      // Rewrite same line.
+      try {
+        this.stream.write(`\r\x1b[2K  ${ch} ${this.label}`);
+      } catch {}
+    }, 80);
+    // Initial draw.
+    try {
+      this.stream.write(`  ${SPINNER_FRAMES[0]} ${this.label}`);
+    } catch {}
+    return this;
+  }
+
+  succeed(text) {
+    this.stop();
+    try {
+      this.stream.write(`  \u2713 ${text ?? this.label}\n`);
+    } catch {}
+    return this;
+  }
+
+  fail(text) {
+    this.stop();
+    try {
+      this.stream.write(`  \u2715 ${text ?? this.label}\n`);
+    } catch {}
+    return this;
+  }
+
+  stop() {
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+      // Clear spinner line.
+      try {
+        this.stream.write("\r\x1b[2K");
+      } catch {}
+    }
+    if (this.restoreCursor) {
+      this.restoreCursor();
+      this.restoreCursor = null;
+    }
+    return this;
+  }
+}
+
+/** Sequential step runner: shows spinner per step, ✓ on success, ✕ on fail. */
+export class StepSequence {
+  constructor({ stream = process.stdout, enabled = shouldAnimate({}) } = {}) {
+    this.stream = stream;
+    this.enabled = enabled;
+    this.steps = [];
+    this.timers = [];
+  }
+
+  add(label, fn) {
+    this.steps.push({ label, fn });
+    return this;
+  }
+
+  async run({ interval = 120 } = {}) {
+    const results = [];
+    for (const step of this.steps) {
+      const spinner = new Spinner(step.label, { stream: this.stream, enabled: this.enabled });
+      if (this.enabled) spinner.start();
+      let ok = false;
+      let error = null;
+      try {
+        const res = await step.fn();
+        // fn may return {ok, detail} or boolean; truthy means success.
+        if (res && typeof res === "object" && "ok" in res) ok = Boolean(res.ok);
+        else if (typeof res === "boolean") ok = res;
+        else ok = true;
+      } catch (err) {
+        ok = false;
+        error = err;
+      }
+      if (this.enabled) {
+        // Small delay so spinner is visible, but not blocking.
+        await new Promise((r) => {
+          const t = setTimeout(r, interval);
+          this.timers.push(t);
+        });
+        spinner.stop();
+        if (ok) {
+          try {
+            this.stream.write(`  \x1b[32m\u2713\x1b[39m ${step.label}\n`);
+          } catch {}
+        } else {
+          try {
+            this.stream.write(`  \x1b[31m\u2715\x1b[39m ${step.label}${error ? ` — ${error.message}` : ""}\n`);
+          } catch {}
+        }
+      } else {
+        const sym = ok ? "\u2713" : "\u2715";
+        try {
+          this.stream.write(`  ${sym} ${step.label}\n`);
+        } catch {}
+      }
+      results.push({ label: step.label, ok, error });
+    }
+    return results;
+  }
+
+  cleanup() {
+    for (const t of this.timers) clearTimeout(t);
+    this.timers = [];
+  }
+}
+
+/** Simple sleep that tracks timer for cleanup. */
+export function sleep(ms, tracker) {
+  return new Promise((resolve) => {
+    const t = setTimeout(resolve, ms);
+    if (tracker) tracker.push(t);
+  });
+}

package/src/core/ui/decisions.mjs

@@ -0,0 +1,55 @@
+/**
+ * DecisionRenderer — compact for ALLOW, expanded for DENY/CRITICAL/HOLD.
+ *
+ * Every label includes text (ALLOW/BLOCKED etc.) so color is never the only signal.
+ */
+
+import { bold, dim, blue, stripAnsi } from "../format.mjs";
+import { toneForDecision, toneForRisk } from "./theme.mjs";
+import { safeTarget } from "./primitives.mjs";
+
+export function renderCompact(event) {
+  const dt = toneForDecision(event.decision);
+  const rt = toneForRisk(event.risk);
+  const decisionLabel = String(event.decision ?? "unknown").toUpperCase().replace(/_/g, " ").padEnd(12);
+  const riskLabel = String(event.risk ?? "—").toUpperCase().padEnd(8);
+  const tool = String(event.tool ?? event.action ?? "—").padEnd(20);
+  const target = safeTarget(event.resource ?? event.command ?? "", 38);
+  const latency = `${event.latency_ms ?? "—"}ms`;
+  const policy = event.policy ?? event.rule ?? "";
+
+  // ALLOW: quiet, one line.
+  // Icon per spec: ✓ ALLOW (green), ◈ SANITIZED (blue), etc.
+  const icon = event.decision === "allow" ? "✓" : event.decision === "sanitize" ? "◈" : event.decision === "deny" ? "✕" : event.decision === "require_approval" ? "⏸" : "·";
+  return `  ${dt(icon)} ${dt(decisionLabel)} ${rt(riskLabel)} ${tool} ${dim(target.padEnd(38))}  ${dim(latency.padEnd(8))} ${dim(policy)}`;
+}
+
+export function renderExpanded(event) {
+  const dt = toneForDecision(event.decision);
+  const rt = toneForRisk(event.risk);
+  const lines = [];
+  const icon = event.decision === "deny" ? "✕" : event.decision === "sanitize" ? "◈" : event.decision === "require_approval" ? "⏸" : "✓";
+  const label = String(event.decision ?? "unknown").toUpperCase().replace(/_/g, " ");
+  lines.push(`  ${dt(`${icon} ${label}`)} ${dim(String(event.tool ?? event.action ?? ""))}`);
+  if (event.resource || event.command) {
+    lines.push(`    ${dim(safeTarget(event.resource ?? event.command, 60))}`);
+    lines.push("");
+  }
+  lines.push(`    ${dim("Risk".padEnd(10))} ${rt(String(event.risk ?? "—").toUpperCase())}`);
+  lines.push(`    ${dim("Policy".padEnd(10))} ${event.policy ?? event.rule ?? dim("—")}`);
+  if (event.latency_ms !== undefined) lines.push(`    ${dim("Latency".padEnd(10))} ${event.latency_ms}ms`);
+  if (event.reason) lines.push(`    ${dim(event.reason)}`);
+  return lines.join("\n");
+}
+
+/** Choose compact vs expanded per risk/decision. */
+export function renderDecision(event) {
+  const critical = String(event.risk ?? "").toLowerCase() === "critical";
+  const denied = event.decision === "deny";
+  const held = event.decision === "require_approval";
+  const high = String(event.risk ?? "").toLowerCase() === "high";
+  if (denied || held || critical || high) {
+    return renderExpanded(event);
+  }
+  return renderCompact(event);
+}

package/src/core/ui/index.mjs

@@ -0,0 +1,49 @@
+/**
+ * TerminalUI facade — auto-disables for non-TTY/NO_COLOR/CI/json.
+ */
+
+export * from "./controller.mjs";
+export * from "./theme.mjs";
+export * from "./primitives.mjs";
+export * from "./decisions.mjs";
+export * from "./intercept.mjs";
+export * from "./live.mjs";
+
+import { shouldAnimate } from "./controller.mjs";
+import { brandHeader, panel } from "./primitives.mjs";
+import { bold, dim, green, red, amber, blue } from "../format.mjs";
+
+export function createUI({ stream = process.stdout, pace, json } = {}) {
+  const enabled = shouldAnimate({ pace, json });
+  return {
+    enabled,
+    brandHeader,
+    panel,
+    write(s) {
+      try {
+        stream.write(s);
+      } catch {}
+    },
+    writeln(s = "") {
+      try {
+        stream.write(s + "\n");
+      } catch {}
+    },
+  };
+}
+
+/** Small helper to render a status dot with color, but text label always present. */
+export function statusDot(ok, tone) {
+  const dot = "●";
+  return tone ? tone(`${dot}`) : dot;
+}
+
+/** Format a count line: "0 blocked · 0 approvals · 0 violations" */
+export function countsLine({ blocked = 0, approvals = 0, violations = 0, sanitized = 0 } = {}) {
+  const parts = [];
+  parts.push(`${blocked} blocked`);
+  if (sanitized) parts.push(`${sanitized} sanitized`);
+  parts.push(`${approvals} approvals`);
+  parts.push(`${violations} violations`);
+  return dim(parts.join("  ·  "));
+}

package/src/core/ui/intercept.mjs

@@ -0,0 +1,103 @@
+/**
+ * SecurityIntercept — visually distinctive blocked-action panel.
+ *
+ * Animation MUST NOT delay enforcement. Decision is already computed.
+ * This only visualizes it with a short 300-800ms sequence.
+ */
+
+import { bold, dim, red, stripAnsi } from "../format.mjs";
+import { shouldAnimate, sleep } from "./controller.mjs";
+import { boxChars, truncate, padVisible } from "./theme.mjs";
+
+export function interceptBox(event) {
+  const W = 58;
+  const ch = boxChars();
+  const useAscii = ch.tl === "+";
+  // Use red border for intercept.
+  const h = useAscii ? ch.h : "═";
+  const v = useAscii ? ch.v : "║";
+  const tl = useAscii ? ch.tl : "╔";
+  const tr = useAscii ? ch.tr : "╗";
+  const bl = useAscii ? ch.bl : "╚";
+  const br = useAscii ? ch.br : "╝";
+  const mj = useAscii ? ch.lt : "╠";
+  const mid = mj + h.repeat(W + 2) + (useAscii ? ch.rt : "╣");
+
+  const rows = [
+    ["Agent", event.agent ?? "—"],
+    ["Tool", event.tool ?? event.action ?? "—"],
+    ["Target", event.resource ?? event.destination ?? "—"],
+    ["Risk", String(event.risk ?? "—").toUpperCase()],
+    ["Decision", "BLOCKED"],
+    ["Policy", event.policy ?? event.rule ?? "default-deny"],
+    ["Latency", `${event.latency_ms ?? "—"}ms`],
+  ];
+
+  const pad = (text) => {
+    const s = String(text);
+    const vis = stripAnsi(s).length;
+    if (vis > W) return s.slice(0, W - 1) + "…";
+    return s + " ".repeat(W - vis);
+  };
+
+  const lines = [];
+  lines.push(`  ${red(tl + h.repeat(W + 2) + tr)}`);
+  lines.push(`  ${red(v)} ${bold(pad("CIRVIX SECURITY INTERCEPT"))} ${red(v)}`);
+  lines.push(`  ${red(mid)}`);
+  for (const [k, val] of rows) {
+    const body = `${k}:`.padEnd(11) + String(val);
+    const painted = k === "Risk" || k === "Decision" ? red(pad(body)) : pad(body);
+    lines.push(`  ${red(v)} ${painted} ${red(v)}`);
+  }
+  lines.push(`  ${red(bl + h.repeat(W + 2) + br)}`);
+
+  const reason = event.reason ? `\n  ${dim(truncate(event.reason, 72))}\n` : "";
+  return lines.join("\n") + reason;
+}
+
+/**
+ * Animated intercept: spinner → risk → BLOCKED → policy.
+ * Total 300-800ms, but decision already made.
+ */
+export async function animateIntercept(event, { stream = process.stdout, pace = 700 } = {}) {
+  const enabled = shouldAnimate({ pace, json: false });
+  if (!enabled) {
+    stream.write(interceptBox(event) + "\n");
+    return;
+  }
+  const write = (s) => {
+    try {
+      stream.write(s);
+    } catch {}
+  };
+  const timers = [];
+  const hide = () => {
+    try {
+      stream.write("\u001b[?25l");
+    } catch {}
+  };
+  const show = () => {
+    try {
+      stream.write("\u001b[?25h");
+    } catch {}
+  };
+  hide();
+  // Phase 1: evaluating
+  write("  ◌ evaluating request...\r");
+  await sleep(Math.min(260, pace * 0.35), timers);
+  write("\x1b[2K");
+  // Phase 2: risk
+  const riskTone = event.risk === "critical" ? red : event.risk === "high" ? "\u001b[33m" : "";
+  write(`  ${riskTone}⚠ ${String(event.risk ?? "").toUpperCase()}\u001b[39m\n`);
+  await sleep(Math.min(160, pace * 0.2), timers);
+  // Phase 3: BLOCKED
+  write(`  ${red("✕ BLOCKED")}\n`);
+  await sleep(Math.min(160, pace * 0.2), timers);
+  // Phase 4: policy
+  write(`  ${dim(String(event.policy ?? event.rule ?? ""))}\n`);
+  await sleep(Math.min(120, pace * 0.15), timers);
+  // Phase 5: full box
+  write(interceptBox(event) + "\n");
+  show();
+  for (const t of timers) clearTimeout(t);
+}

package/src/core/ui/live.mjs

@@ -0,0 +1,51 @@
+/**
+ * LiveStream — `cirvix logs --watch` live security stream.
+ *
+ * Line-based updates, no full redraw, readable.
+ */
+
+import { dim, bold } from "../format.mjs";
+import { renderDecision } from "./decisions.mjs";
+
+export class LiveStream {
+  constructor({ stream = process.stdout, title = "CIRVIX LIVE · protection active" } = {}) {
+    this.stream = stream;
+    this.title = title;
+    this.started = false;
+  }
+
+  header() {
+    if (this.started) return;
+    this.started = true;
+    try {
+      this.stream.write(`\n  ${bold(this.title)}\n`);
+      this.stream.write(`  ${dim("─".repeat(60))}\n\n`);
+    } catch {}
+  }
+
+  push(event) {
+    this.header();
+    const line = renderDecision(event);
+    // For live, compact is preferred even for DENY to keep stream readable,
+    // but DENY still gets expanded with context on next line.
+    try {
+      // event already has ts; render with clock if present.
+      const clock = event.ts ? String(event.ts).slice(11, 19) : new Date().toISOString().slice(11, 19);
+      // If decision renderer already includes multiline, just prefix clock.
+      if (line.includes("\n")) {
+        const parts = line.split("\n");
+        this.stream.write(`  ${dim(clock)} ${parts[0].trimStart()}\n`);
+        for (let i = 1; i < parts.length; i++) this.stream.write(parts[i] + "\n");
+      } else {
+        this.stream.write(`  ${dim(clock)} ${line.trimStart()}\n`);
+      }
+    } catch {}
+  }
+
+  footer(stats) {
+    if (!stats) return;
+    try {
+      this.stream.write(`\n  ${dim(`${stats.records ?? 0} decisions · P99 ${stats.latency?.p99 ?? 0}ms`)}\n\n`);
+    } catch {}
+  }
+}

package/src/core/ui/primitives.mjs

@@ -0,0 +1,123 @@
+/**
+ * Primitives — Panel, Table, Badge, Logo, Status helpers.
+ *
+ * Zero deps, unicode with ASCII fallback, respects NO_COLOR via format.mjs.
+ */
+
+import { bold, dim, stripAnsi, supportsUnicode } from "../format.mjs";
+import { boxChars, truncate, padVisible } from "./theme.mjs";
+
+/** CIRVIX ASCII logo (5 lines). Compact, premium, not gamey. */
+export const LOGO_LINES = [
+  " ██████╗██╗██████╗ ██╗   ██╗██╗██╗  ██╗",
+  "██╔════╝██║██╔══██╗██║   ██║██║╚██╗██╔╝",
+  "██║     ██║██████╔╝██║   ██║██║ ╚███╔╝ ",
+  "██║     ██║██╔══██╗╚██╗ ██╔╝██║ ██╔██╗ ",
+  "╚██████╗██║██║  ██║ ╚████╔╝ ██║██╔╝ ██╗",
+  " ╚═════╝╚═╝╚═╝  ╚═╝  ╚═══╝  ╚═╝╚═╝  ╚═╝",
+];
+
+export const LOGO_SUBTITLE = "AI AGENT RUNTIME GOVERNANCE";
+
+/**
+ * Draw a rounded panel with optional title.
+ *
+ * @param {object} opts
+ * @param {string} [opts.title]
+ * @param {string[]} opts.lines — already formatted (may contain ANSI)
+ * @param {number} [opts.width] — inner width, default 58
+ * @param {boolean} [opts.heavy] — use heavy border for intercept
+ */
+export function panel({ title, lines = [], width = 58, heavy = false } = {}) {
+  const ch = boxChars();
+  const h = heavy ? ch.hHeavy : ch.h;
+  const v = heavy ? ch.vHeavy : ch.v;
+
+  // Compute actual inner width from content if not provided.
+  let inner = width;
+  if (!width) {
+    inner = Math.max(...lines.map((l) => stripAnsi(l).length), title ? stripAnsi(title).length : 0) + 2;
+    inner = Math.max(40, Math.min(72, inner));
+  }
+
+  const top = `╭${h.repeat(inner + 2)}╮`;
+  const bottom = `╰${h.repeat(inner + 2)}╯`;
+  // For ascii fallback, boxChars returns +/-, so above uses unicode literals.
+  // Rebuild with actual chars for ascii.
+  const useAscii = !supportsUnicode();
+  const topLine = useAscii ? `${ch.tl}${ch.h.repeat(inner + 2)}${ch.tr}` : top;
+  const bottomLine = useAscii ? `${ch.bl}${ch.h.repeat(inner + 2)}${ch.br}` : bottom;
+  const vert = useAscii ? ch.v : v;
+
+  const out = [];
+  out.push(`  ${topLine}`);
+  if (title) {
+    const t = truncate(title, inner);
+    out.push(`  ${vert} ${padVisible(t, inner)} ${vert}`);
+    out.push(`  ${vert} ${" ".repeat(inner)} ${vert}`);
+  } else {
+    out.push(`  ${vert} ${" ".repeat(inner)} ${vert}`);
+  }
+  for (const line of lines) {
+    const clean = truncate(stripAnsi(line), inner);
+    // Preserve ANSI: pad based on visible length.
+    const padded = padVisible(line, inner);
+    // Ensure we truncate ANSI correctly — if original had ANSI, we need to re-truncate safely.
+    // Simpler: use padded which already uses visibleWidth.
+    out.push(`  ${vert} ${padded} ${vert}`);
+  }
+  out.push(`  ${vert} ${" ".repeat(inner)} ${vert}`);
+  out.push(`  ${bottomLine}`);
+  return out.join("\n");
+}
+
+/**
+ * Render the full brand header — logo boxed.
+ */
+export function brandHeader({ width = 58 } = {}) {
+  const ch = boxChars();
+  const useAscii = !supportsUnicode();
+  const h = ch.h;
+  const top = useAscii ? `${ch.tl}${h.repeat(width + 2)}${ch.tr}` : `╭${h.repeat(width + 2)}╮`;
+  const bottom = useAscii ? `${ch.bl}${h.repeat(width + 2)}${ch.br}` : `╰${h.repeat(width + 2)}╯`;
+  const vert = useAscii ? ch.v : ch.v;
+
+  const lines = [];
+  lines.push(`  ${top}`);
+  lines.push(`  ${vert} ${" ".repeat(width)} ${vert}`);
+  for (const l of LOGO_LINES) {
+    const padded = l.padStart(Math.floor((width + l.length) / 2)).padEnd(width);
+    lines.push(`  ${vert} ${padded} ${vert}`);
+  }
+  lines.push(`  ${vert} ${" ".repeat(width)} ${vert}`);
+  const sub = LOGO_SUBTITLE.padStart(Math.floor((width + LOGO_SUBTITLE.length) / 2)).padEnd(width);
+  lines.push(`  ${vert} ${dim(sub)} ${vert}`);
+  lines.push(`  ${vert} ${" ".repeat(width)} ${vert}`);
+  lines.push(`  ${bottom}`);
+  return lines.join("\n");
+}
+
+/** Simple key/value rows aligned. */
+export function keyValueRows(rows, { keyWidth } = {}) {
+  const w = keyWidth ?? Math.max(...rows.map(([k]) => stripAnsi(String(k)).length));
+  return rows.map(([k, v]) => `  ${String(k).padEnd(w + 2)}${v}`);
+}
+
+/** Separator line. */
+export function separator(width = 60, char = "─") {
+  const ch = supportsUnicode() ? char : "-";
+  return dim("  " + ch.repeat(width));
+}
+
+/** Badge: ● ONLINE / ● ENFORCING etc. with color. */
+export function badge(label, state, tone) {
+  const dot = "●";
+  return `${tone(`${dot} ${state}`)} ${dim(label)}`;
+}
+
+/** Truncate path for display, never show secret values. */
+export function safeTarget(value, max = 44) {
+  const s = String(value ?? "");
+  if (s.length <= max) return s;
+  return "…" + s.slice(-(max - 1));
+}

package/src/core/ui/theme.mjs

@@ -0,0 +1,92 @@
+/**
+ * Theme — semantic palette + box characters, with NO_COLOR and ASCII fallbacks.
+ *
+ * Never rely on color alone; every semantic token also has a text label
+ * (ALLOW/BLOCKED etc.) rendered elsewhere.
+ */
+
+import { bold, dim, green, red, amber, blue, cyan, gray, stripAnsi, supportsUnicode } from "../format.mjs";
+
+export const palette = {
+  success: green,
+  critical: red,
+  warning: amber,
+  info: blue,
+  muted: dim,
+  subtle: gray,
+  accent: cyan,
+  strong: bold,
+};
+
+export const riskTone = {
+  low: dim,
+  medium: blue,
+  high: amber,
+  critical: red,
+};
+
+export const decisionTone = {
+  allow: green,
+  sanitize: blue,
+  require_approval: amber,
+  deny: red,
+  audit_only: dim,
+};
+
+export function toneForDecision(decision) {
+  return decisionTone[String(decision ?? "").toLowerCase()] ?? dim;
+}
+
+export function toneForRisk(risk) {
+  return riskTone[String(risk ?? "").toLowerCase()] ?? dim;
+}
+
+/** Box characters, unicode primary, ascii fallback. */
+export function boxChars() {
+  if (supportsUnicode()) {
+    return {
+      tl: "╭",
+      tr: "╮",
+      bl: "╰",
+      br: "╯",
+      h: "─",
+      v: "│",
+      lt: "├",
+      rt: "┤",
+      mt: "┬",
+      mb: "┴",
+      cross: "┼",
+      // heavy for intercept
+      hHeavy: "━",
+      vHeavy: "┃",
+    };
+  }
+  return {
+    tl: "+",
+    tr: "+",
+    bl: "+",
+    br: "+",
+    h: "-",
+    v: "|",
+    lt: "+",
+    rt: "+",
+    mt: "+",
+    mb: "+",
+    cross: "+",
+    hHeavy: "=",
+    vHeavy: "|",
+  };
+}
+
+/** Safe width truncation with ANSI stripped. */
+export function truncate(str, n) {
+  const s = String(str ?? "");
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + "…";
+}
+
+export function padVisible(str, width) {
+  const vis = stripAnsi(String(str)).length;
+  if (vis >= width) return String(str);
+  return String(str) + " ".repeat(width - vis);
+}