@bahulam/code 0.1.1

package/src/ui/palette.mjs

@@ -0,0 +1,189 @@
+/**
+ * Kepler palette — semantic color tokens for the CLI.
+ *
+ * Every feature module imports from here, never from raw ANSI. Tokens resolve
+ * at call time so changing terminal capabilities (resize, `refresh()`) is
+ * picked up without restarting the process.
+ *
+ *   import { paint } from './palette.mjs';
+ *   process.stdout.write(paint.brand.primary('KEPLER'));
+ *
+ * Composition (multiple styles on one string):
+ *
+ *   paint.bold(paint.brand.primary('KEPLER'))
+ *
+ * Tier behavior:
+ *   truecolor → 24-bit RGB
+ *   ansi256   → nearest 256-color index
+ *   ansi16    → nearest basic color
+ *   none      → identity (input returned unchanged)
+ *
+ * Brand identity (Mission Control PRD-055):
+ *   primary  Abundance Cyan     #06b6d4
+ *   accent   Stellar Magenta    #ec4899
+ *   data     Neon Cyan          #22d3ee
+ *   success  Aligned green      #22c55e
+ *   warn     Soft amber         #eab308
+ *   danger   Failure red        #ef4444
+ *   dim      Sub-agent / hint   #6b7280
+ *   text     Primary text       #c9d1d9
+ */
+
+import { term } from './term.mjs';
+
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+
+// ── Brand tokens ─────────────────────────────────────────────────────────
+// Each token is { rgb: [r,g,b], ansi256: n, ansi16: 'fgName' }.
+// `ansi16` maps to a key in BASIC_FG below.
+
+export const TOKENS = Object.freeze({
+  // Brand
+  'brand.primary': { rgb: [6, 182, 212],   ansi256: 44,  ansi16: 'cyan'     }, // #06b6d4
+  'brand.accent':  { rgb: [236, 72, 153],  ansi256: 198, ansi16: 'magenta' }, // #ec4899
+  'brand.data':    { rgb: [34, 211, 238],  ansi256: 87,  ansi16: 'cyan'    }, // #22d3ee
+
+  // State
+  'state.success': { rgb: [34, 197, 94],   ansi256: 41,  ansi16: 'green'   }, // #22c55e
+  'state.warn':    { rgb: [234, 179, 8],   ansi256: 220, ansi16: 'yellow'  }, // #eab308
+  'state.danger':  { rgb: [239, 68, 68],   ansi256: 196, ansi16: 'red'     }, // #ef4444
+
+  // Text
+  'text.primary':  { rgb: [201, 209, 217], ansi256: 250, ansi16: 'white'   }, // #c9d1d9
+  'text.dim':      { rgb: [107, 114, 128], ansi256: 245, ansi16: 'gray'    }, // #6b7280
+  'text.muted':    { rgb: [156, 163, 175], ansi256: 247, ansi16: 'gray'    }, // #9ca3af
+});
+
+// ── ANSI 16-color foreground codes ───────────────────────────────────────
+
+const BASIC_FG = {
+  black:   30,
+  red:     31,
+  green:   32,
+  yellow:  33,
+  blue:    34,
+  magenta: 35,
+  cyan:    36,
+  white:   37,
+  gray:    90,
+};
+
+// ── Style codes (work at every tier) ─────────────────────────────────────
+
+const STYLE_CODES = {
+  bold:      [1, 22],
+  dim:       [2, 22],
+  italic:    [3, 23],
+  underline: [4, 24],
+  inverse:   [7, 27],
+  strike:    [9, 29],
+};
+
+// ── Open / close sequence builders ───────────────────────────────────────
+
+function openForToken(token, capability) {
+  const def = TOKENS[token];
+  if (!def) return '';
+
+  if (capability === 'truecolor') {
+    const [r, g, b] = def.rgb;
+    return `${ESC}38;2;${r};${g};${b}m`;
+  }
+  if (capability === 'ansi256') {
+    return `${ESC}38;5;${def.ansi256}m`;
+  }
+  if (capability === 'ansi16') {
+    return `${ESC}${BASIC_FG[def.ansi16] || BASIC_FG.white}m`;
+  }
+  return '';
+}
+
+function wrap(open) {
+  if (!open) return (input) => String(input ?? '');
+  // Re-open after every embedded reset so nested styles compose.
+  // Cheap and predictable; most tool output is short enough that the cost
+  // is negligible compared to writing to the TTY.
+  return (input) => {
+    const text = String(input ?? '');
+    if (!text) return '';
+    if (!text.includes(RESET)) return `${open}${text}${RESET}`;
+    return `${open}${text.split(RESET).join(`${RESET}${open}`)}${RESET}`;
+  };
+}
+
+function styleWrap(openCode, closeCode) {
+  return (input) => {
+    const text = String(input ?? '');
+    if (!text) return '';
+    // No color tier check here — styles like bold/dim work even in ansi16.
+    if (!term().color) return text;
+    const open = `${ESC}${openCode}m`;
+    const close = `${ESC}${closeCode}m`;
+    if (!text.includes(close)) return `${open}${text}${close}`;
+    return `${open}${text.split(close).join(`${close}${open}`)}${close}`;
+  };
+}
+
+// ── Build a structured `paint` object once per token ─────────────────────
+
+function buildPaint() {
+  const paint = {};
+
+  // Brand / state / text colorizers, nested by namespace.
+  for (const token of Object.keys(TOKENS)) {
+    const [ns, name] = token.split('.');
+    if (!paint[ns]) paint[ns] = {};
+    paint[ns][name] = (input) => {
+      const t = term();
+      if (!t.color) return String(input ?? '');
+      return wrap(openForToken(token, t.colorLevel))(input);
+    };
+  }
+
+  // Style colorizers (callable directly).
+  for (const [style, [open, close]] of Object.entries(STYLE_CODES)) {
+    paint[style] = styleWrap(open, close);
+  }
+
+  // Compose helper — apply multiple styles left-to-right.
+  paint.compose = (...fns) => (input) =>
+    fns.reduce((acc, fn) => (typeof fn === 'function' ? fn(acc) : acc), input);
+
+  // Raw token accessor for callers that need to inject codes around their
+  // own text (e.g. status bar repaint loops that re-style a buffer).
+  paint.token = (key) => {
+    const t = term();
+    if (!t.color) return { open: '', close: '' };
+    return { open: openForToken(key, t.colorLevel), close: RESET };
+  };
+
+  return paint;
+}
+
+export const paint = buildPaint();
+
+// ── Plain-text helper (always strips colors) ─────────────────────────────
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+export function strip(input) {
+  return String(input ?? '').replace(ANSI_RE, '');
+}
+
+/**
+ * Visible length of a string (ignoring ANSI codes).
+ * Surrogate pairs (emoji) count as 1 visual cell for layout purposes — this
+ * is consistent with most terminals' rendering of single-codepoint emoji.
+ */
+export function width(input) {
+  const plain = strip(input);
+  // Strip variation selectors so "🛰️" measures as one cell.
+  return [...plain.replace(/︎|️/g, '')].length;
+}
+
+// ── Backwards compatibility re-exports ───────────────────────────────────
+// `ansi.mjs` and other legacy modules import these names. New code should
+// prefer `paint.brand.primary(...)` etc.
+
+export const RESET_CODE = RESET;

package/src/ui/render-queue.mjs

@@ -0,0 +1,500 @@
+/**
+ * Render queue — THE single writer for the rich-TTY screen.
+ *
+ * Every glitch class the old pipeline suffered (flicker, dock overlap,
+ * wrap artifacts, resize mangling, approval gaps) traced to the same root:
+ * multiple modules moved the cursor independently — spinner interval,
+ * content flush timer, dock repaints, approval prompts — with the single
+ * VT100 save/restore slot as their only (broken) coordination.
+ *
+ * Discipline (Ink's core insight, without adopting Ink):
+ *   1. Exactly ONE module writes to the terminal in rich mode. This one.
+ *   2. Every operation is a complete transaction: position → write →
+ *      re-park. No saveCursor/restoreCursor anywhere.
+ *   3. Cursor position is tracked exactly — possible only because raw
+ *      writes are banned. process.stdout/stderr are patched to REDIRECT
+ *      through queue.content() (not merely observe), so a stray
+ *      console.log from any dependency is serialized instead of
+ *      corrupting the screen.
+ *   4. The transient status line (spinner) is coalesced last-wins and is
+ *      always cleared before content lands, then redrawn after — content
+ *      and spinner can no longer interleave.
+ *
+ * Plain / non-TTY mode: the queue degrades to a pass-through (content →
+ * stdout, status dropped, no cursor ops) so piped transcripts stay clean.
+ *
+ * Cell-width accounting: `cellWidth()` measures terminal CELLS (East
+ * Asian Wide/Fullwidth = 2, combining marks/ZWJ = 0, tabs → next stop),
+ * unlike palette.width() which counts codepoints. Wrap math that feeds
+ * cursor tracking MUST use cells, or CJK/emoji output drifts the dock.
+ */
+
+import { term, onResize } from './term.mjs';
+
+const ESC = '\x1b[';
+
+// ── ANSI / OSC stripping ─────────────────────────────────────────────────
+// CSI (incl. private + intermediate bytes), OSC (BEL or ST terminated),
+// charset selection, and simple ESC-letter sequences.
+const ANSI_RE = new RegExp([
+  '\\x1b\\[[0-?]*[ -/]*[@-~]',          // CSI
+  '\\x1b\\][^\\x07\\x1b]*(?:\\x07|\\x1b\\\\)', // OSC ... BEL|ST
+  '\\x1b[()][A-Za-z0-9]',               // charset
+  '\\x1b[@-Z\\\\-_]',                   // 2-byte ESC sequences
+].join('|'), 'g');
+
+export function stripSequences(text) {
+  return String(text ?? '').replace(ANSI_RE, '');
+}
+
+// ── Cell width ───────────────────────────────────────────────────────────
+
+function isZeroWidth(cp) {
+  return (
+    (cp >= 0x0300 && cp <= 0x036f) || // combining diacriticals
+    (cp >= 0x1ab0 && cp <= 0x1aff) ||
+    (cp >= 0x1dc0 && cp <= 0x1dff) ||
+    (cp >= 0x20d0 && cp <= 0x20ff) ||
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+    cp === 0x200d ||                  // ZWJ
+    cp === 0xfeff
+  );
+}
+
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) ||  // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) ||  // CJK radicals, punctuation
+    (cp >= 0x3041 && cp <= 0x33ff) ||  // Hiragana..CJK compat
+    (cp >= 0x3400 && cp <= 0x4dbf) ||
+    (cp >= 0x4e00 && cp <= 0x9fff) ||  // CJK unified
+    (cp >= 0xa000 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||  // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe4f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||  // fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) || // emoji blocks
+    (cp >= 0x20000 && cp <= 0x3fffd)
+  );
+}
+
+/** Terminal cell width of `text` after stripping escape sequences. */
+export function cellWidth(text) {
+  const plain = stripSequences(text);
+  let w = 0;
+  for (const ch of plain) {
+    const cp = ch.codePointAt(0);
+    if (cp === 0x09) { w = (Math.floor(w / 8) + 1) * 8; continue; }
+    if (cp < 0x20 || cp === 0x7f) continue;
+    if (isZeroWidth(cp)) continue;
+    w += isWide(cp) ? 2 : 1;
+  }
+  return w;
+}
+
+// ── Queue state ──────────────────────────────────────────────────────────
+
+let active = false;           // rich mode engaged (dock mounted)
+let out = process.stderr;     // the one true stream in rich mode
+let rawStderrWrite = null;    // originals captured at activate()
+let rawStdoutWrite = null;
+
+let row = 1;                  // tracked content cursor (1-based)
+let col = 1;
+let regionBottom = null;      // scroll-region bottom (content area)
+let statusLines = [];         // current transient status block ([] = none)
+let statusPaintedRows = 0;    // rows painted by the last paintStatus()
+let statusVisible = false;
+let parked = null;            // {row, col} where input echo expects the cursor
+let inTransaction = 0;        // reentrancy guard for queue-internal writes
+let contentEscapeCarry = '';  // incomplete ESC sequence crossing write chunks
+
+function rawWrite(s) {
+  // Always bypass the redirect patch for queue-internal writes.
+  (rawStderrWrite || process.stderr.write.bind(process.stderr))(s);
+}
+
+function seq(s) { rawWrite(ESC + s); }
+function moveTo(r, c) { seq(`${r};${c}H`); }
+function clearLine() { seq('2K'); }
+
+function cols() {
+  return Math.max(20, term().columns || out.columns || 80);
+}
+
+function bottom() {
+  return regionBottom ?? Math.max(10, term().rows || 24);
+}
+
+// ── Exact tracking ───────────────────────────────────────────────────────
+// Advance the tracked (row, col) as the terminal will after printing
+// `text`. Only printable content passes through here — queue ops position
+// with moveTo(), never with embedded CSI in content.
+
+function advance(text) {
+  const width = cols();
+  const plain = stripSequences(text);
+  for (const ch of plain) {
+    const cp = ch.codePointAt(0);
+    if (cp === 0x0a) { row = Math.min(bottom(), row + 1); col = 1; continue; }
+    if (cp === 0x0d) { col = 1; continue; }
+    if (cp === 0x09) { col = (Math.floor((col - 1) / 8) + 1) * 8 + 1; }
+    else if (cp < 0x20 || cp === 0x7f || isZeroWidth(cp)) { continue; }
+    else { col += isWide(cp) ? 2 : 1; }
+    if (col > width) { row = Math.min(bottom(), row + 1); col = 1; }
+  }
+}
+
+// ── Status line (spinner) discipline ─────────────────────────────────────
+
+function eraseStatus() {
+  if (!statusVisible) return;
+  const anchor = Math.min(bottom(), row);
+  const count = Math.max(1, statusPaintedRows);
+  for (let i = 0; i < count && anchor + i <= bottom(); i++) {
+    moveTo(anchor + i, 1);
+    clearLine();
+  }
+  statusPaintedRows = 0;
+  statusVisible = false;
+}
+
+// ANSI-aware truncation to N terminal cells. Escape sequences pass
+// through at zero width; printable chars accumulate cell width until the
+// budget is hit. A trailing reset prevents color bleed on truncation.
+const TOKEN_RE = new RegExp(`(${ANSI_RE.source})|([\\s\\S])`, 'g');
+
+export function fitCells(text, maxCells) {
+  const s = String(text ?? '');
+  let out = '';
+  let w = 0;
+  let truncated = false;
+  TOKEN_RE.lastIndex = 0;
+  let m;
+  while ((m = TOKEN_RE.exec(s)) !== null) {
+    if (m[1] !== undefined) { out += m[1]; continue; }
+    const ch = m[2];
+    const cp = ch.codePointAt(0);
+    if (cp < 0x20 || cp === 0x7f) continue;      // control chars never printable here
+    const cw = isZeroWidth(cp) ? 0 : (isWide(cp) ? 2 : 1);
+    if (w + cw > maxCells - 1) { truncated = true; break; }
+    out += ch;
+    w += cw;
+  }
+  if (truncated) out += '…\x1b[0m';
+  return out;
+}
+
+function paintStatus() {
+  if (!statusLines.length) return;
+  const anchor = Math.min(bottom(), row);
+  const width = Math.max(8, cols() - 1);
+  let painted = 0;
+  for (const line of statusLines) {
+    const r = anchor + painted;
+    if (r > bottom()) break;
+    moveTo(r, 1);
+    clearLine();
+    // Clamp to the drawable width — a status line that reaches the final
+    // column triggers terminal autowrap, which scrolls the region and
+    // turns the "transient" line into permanent transcript content (one
+    // leaked line per animation frame). Newlines are equally forbidden.
+    rawWrite(fitCells(String(line).replace(/[\r\n]+/g, ' '), width));
+    painted++;
+  }
+  statusPaintedRows = painted;
+  statusVisible = painted > 0;
+}
+
+function repark() {
+  if (parked) moveTo(parked.row, parked.col);
+  else moveTo(Math.min(bottom(), row), col);
+}
+
+// ── Public API ───────────────────────────────────────────────────────────
+
+/**
+ * Engage rich mode. The queue captures both std streams and becomes the
+ * sole writer. `initial` seeds the tracked cursor (dock mount computes it).
+ */
+export function activate({ initialRow = 1, initialCol = 1, bottom: b = null } = {}) {
+  if (active) return true;
+  const t = term();
+  if (!t.isTTY || t.plain) return false;
+  active = true;
+  row = Math.max(1, initialRow);
+  col = Math.max(1, initialCol);
+  regionBottom = b;
+  rawStdoutWrite = process.stdout.write.bind(process.stdout);
+  rawStderrWrite = process.stderr.write.bind(process.stderr);
+  // REDIRECT, don't observe: stray writers become serialized content.
+  process.stdout.write = redirectedWrite;
+  process.stderr.write = redirectedWrite;
+  return true;
+}
+
+export function deactivate() {
+  if (!active) return;
+  if (rawStdoutWrite) { process.stdout.write = rawStdoutWrite; rawStdoutWrite = null; }
+  if (rawStderrWrite) { process.stderr.write = rawStderrWrite; rawStderrWrite = null; }
+  active = false;
+  regionBottom = null;
+  statusLines = [];
+  statusPaintedRows = 0;
+  statusVisible = false;
+  parked = null;
+  contentEscapeCarry = '';
+}
+
+export function isActive() { return active; }
+
+function redirectedWrite(chunk, encoding, cb) {
+  if (inTransaction > 0) {
+    // Queue-internal writes that (incorrectly) went through the patched
+    // stream — pass straight through.
+    rawWrite(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk ?? ''));
+  } else {
+    content(Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk ?? ''));
+  }
+  if (typeof encoding === 'function') encoding();
+  else if (typeof cb === 'function') cb();
+  return true;
+}
+
+// Content is TEXT, not cursor commands (Ink's discipline). SGR color
+// sequences pass through; cursor movement / erase / scroll sequences are
+// stripped — a content writer that embeds CUU/ED/DECSTBM would move the
+// real cursor without tracking following (the old approval-redraw gap
+// bug). Positioning belongs to the queue alone.
+function sanitizeContent(s) {
+  const input = contentEscapeCarry + String(s ?? '');
+  contentEscapeCarry = '';
+  let out = '';
+
+  for (let i = 0; i < input.length;) {
+    const ch = input[i];
+    if (ch !== '\x1b') {
+      out += ch;
+      i++;
+      continue;
+    }
+
+    if (i + 1 >= input.length) {
+      contentEscapeCarry = input.slice(i);
+      break;
+    }
+
+    const next = input[i + 1];
+
+    // CSI: ESC [ params/intermediates final. Preserve only SGR (`m`).
+    if (next === '[') {
+      let j = i + 2;
+      while (j < input.length) {
+        const code = input.charCodeAt(j);
+        if (code >= 0x40 && code <= 0x7e) break;
+        j++;
+      }
+      if (j >= input.length) {
+        contentEscapeCarry = input.slice(i);
+        break;
+      }
+      const seqText = input.slice(i, j + 1);
+      if (input[j] === 'm') out += seqText;
+      i = j + 1;
+      continue;
+    }
+
+    // OSC: ESC ] ... BEL or ST. Strip, buffering incomplete sequences.
+    if (next === ']') {
+      let j = i + 2;
+      let completeAt = -1;
+      while (j < input.length) {
+        if (input[j] === '\x07') { completeAt = j; break; }
+        if (input[j] === '\x1b' && input[j + 1] === '\\') { completeAt = j + 1; break; }
+        j++;
+      }
+      if (completeAt < 0) {
+        contentEscapeCarry = input.slice(i);
+        break;
+      }
+      i = completeAt + 1;
+      continue;
+    }
+
+    // Charset selection: ESC ( X / ESC ) X. Strip, buffering if split.
+    if (next === '(' || next === ')') {
+      if (i + 2 >= input.length) {
+        contentEscapeCarry = input.slice(i);
+        break;
+      }
+      i += 3;
+      continue;
+    }
+
+    // Other two-byte ESC commands. Strip the ESC command byte too.
+    i += 2;
+  }
+
+  return out;
+}
+
+/**
+ * Append transcript content at the tracked position. Multi-line safe.
+ * Clears the status line first and repaints it after, so spinner and
+ * content can never interleave.
+ */
+export function content(text) {
+  const s = String(text ?? '');
+  if (!s) return;
+  if (!active) { (rawStdoutWrite || process.stdout.write.bind(process.stdout))(s); return; }
+  const clean = sanitizeContent(s);
+  if (!clean) return;
+  inTransaction++;
+  try {
+    eraseStatus();
+    moveTo(Math.min(bottom(), row), col);
+    rawWrite(clean);
+    advance(clean);
+    paintStatus();
+    repark();
+  } finally {
+    inTransaction--;
+  }
+}
+
+/**
+ * Set / update the transient status block. Last-wins; a repaint happens
+ * only when the rendered content actually changed. Single-line callers
+ * use status(line); multi-line (sub-agent tool window) use
+ * statusBlock(lines). Rows are clamped to the space between the content
+ * cursor and the region bottom.
+ */
+export function statusBlock(lines) {
+  if (!active) return;
+  const next = (Array.isArray(lines) ? lines : [lines])
+    .map(l => String(l ?? ''))
+    .filter((l, i) => l !== '' || i === 0);
+  const isEmpty = !next.length || (next.length === 1 && !next[0]);
+  const same = statusVisible
+    && next.length === statusLines.length
+    && next.every((l, i) => l === statusLines[i]);
+  if (same) return;
+  inTransaction++;
+  try {
+    eraseStatus();
+    statusLines = isEmpty ? [] : next;
+    if (!isEmpty) paintStatus();
+    repark();
+  } finally {
+    inTransaction--;
+  }
+}
+
+export function status(line) {
+  statusBlock([String(line ?? '')]);
+}
+
+export function clearStatus() { statusBlock([]); }
+
+/**
+ * Absolute-positioned write for dock frame rows. Does NOT touch content
+ * tracking. `clear` wipes the line first.
+ */
+export function at(r, c, text, { clear = true } = {}) {
+  if (!active) return;
+  inTransaction++;
+  try {
+    moveTo(r, c);
+    if (clear) clearLine();
+    if (text) rawWrite(String(text));
+  } finally {
+    inTransaction--;
+  }
+}
+
+/** Set the scroll region (content area 1..b). */
+export function setRegion(top, b) {
+  if (!active) return;
+  inTransaction++;
+  try {
+    seq(`${top};${b}r`);
+    regionBottom = b;
+    row = Math.min(b, row);
+  } finally {
+    inTransaction--;
+  }
+}
+
+export function clearRegion() {
+  if (!active) return;
+  inTransaction++;
+  try { seq('r'); regionBottom = null; } finally { inTransaction--; }
+}
+
+/**
+ * Batch several at()/setRegion() calls (a dock repaint) and finish with
+ * the cursor parked for input echo. Single place where parking happens.
+ */
+export function frame(fn, { park = null } = {}) {
+  if (!active) { if (typeof fn === 'function') fn(); return; }
+  inTransaction++;
+  try {
+    if (typeof fn === 'function') fn();
+    if (park) parked = { row: park.row, col: park.col };
+    repark();
+  } finally {
+    inTransaction--;
+  }
+}
+
+/**
+ * Serialized raw write for trusted frame painters (the input dock). The
+ * caller owns positioning via embedded escape sequences; content tracking
+ * is not touched. Bypasses the redirect patch.
+ */
+export function raw(s) {
+  if (!active) { (rawStderrWrite || process.stderr.write.bind(process.stderr))(String(s ?? '')); return; }
+  inTransaction++;
+  try { rawWrite(String(s ?? '')); } finally { inTransaction--; }
+}
+
+/** Park the input-echo cursor. Every op re-parks here afterwards. */
+export function park(r, c) {
+  if (!active) return;
+  parked = r == null ? null : { row: r, col: c ?? 1 };
+  inTransaction++;
+  try { repark(); } finally { inTransaction--; }
+}
+
+/** Tracked content cursor (exact — no simulation drift). */
+export function contentCursor() {
+  return { row, col };
+}
+
+/** Hard re-anchor after resize: tracking through a reflow is fiction. */
+export function reanchor({ row: r, col: c = 1, bottom: b = null } = {}) {
+  if (!active) return;
+  if (b != null) regionBottom = b;
+  row = Math.max(1, Math.min(bottom(), r ?? bottom()));
+  col = Math.max(1, c);
+  statusVisible = false; // old status row is gone after reflow
+}
+
+/** Reset tracked cursor without touching the screen (dock mount). */
+export function seed({ row: r = 1, col: c = 1, bottom: b = null } = {}) {
+  row = Math.max(1, r);
+  col = Math.max(1, c);
+  if (b != null) regionBottom = b;
+}
+
+// Test-only accessors.
+export function _internals() {
+  return {
+    state: () => ({ active, row, col, regionBottom, statusLines, statusPaintedRows, statusVisible, parked }),
+    advance,
+    cellWidth,
+    stripSequences,
+    sanitizeContent,
+  };
+}