leetcode-capture-helper 0.0.0-stage → 0.1.1

package/runtime/companion/terminal-format.js

@@ -0,0 +1,330 @@
+// companion/terminal-format.js - color/prompt styling and markdown rendering
+// for companion.js's terminal output.
+//
+// Deliberately isolated from companion.js so the styling decision (TTY or
+// not, NO_COLOR or not) is made in exactly one place, computed once at
+// import time, and every exported helper already honors it internally - no
+// caller needs its own isTTY branch. This also keeps companion.js's own
+// stdout-vs-pipe branch (printAboveInput) untouched: it still just receives
+// an opaque string to print, whether or not that string carries ANSI codes.
+//
+// Why the styling decision is made ourselves rather than left to chalk's or
+// marked-terminal's own auto-detection: this environment sometimes runs
+// with FORCE_COLOR set even when stdout is a plain pipe (confirmed via
+// `node -e '...' | cat` still reporting chalk level 3), which would defeat
+// the "stay plain in pipes" requirement if we trusted ambient detection.
+// process.stdout.isTTY is checked directly instead, plus the NO_COLOR
+// (https://no-color.org) convention.
+
+import { Chalk } from 'chalk';
+import { marked } from 'marked';
+import TerminalRenderer, { markedTerminal } from 'marked-terminal';
+
+// marked-terminal's own listitem() only reflow-wraps a *loose* list item
+// (one with a blank line between bullets - marked hands it 'paragraph'-type
+// tokens): it forwards to marked's own Parser.parse(item.tokens,
+// !!item.loose), and marked's Parser only routes a 'text'-type token
+// through paragraph rendering - and therefore through reflowText - when
+// that `top` flag is true (see marked's Parser.prototype.parse's "text"
+// case). A *tight* item (the common case - no blank line between bullets,
+// which is what an LLM's own list output almost always looks like) carries
+// plain 'text' tokens instead, so with top=false its text comes out
+// completely unwrapped; whatever line break then appears on screen is only
+// the raw terminal's own hardware auto-wrap-at-column-N, which can land
+// mid-word with zero hanging indent - confirmed live once PR #36 removed
+// the old fixed-width cap and made a long single-sentence bullet an
+// everyday occurrence rather than a rare edge case (see companion/AGENTS.md
+// and the PR that added this fix for the live repro).
+//
+// Patched once here, directly on marked-terminal's shared
+// TerminalRenderer.prototype (rather than inside configureMarkedTerminal
+// below, which re-registers on every terminal resize - wrapping listitem()
+// again on every one of those would stack redundant wrappers), by forcing
+// every item to look "loose" to marked's Parser. Confirmed this doesn't
+// change what's rendered for an already-loose item (identical either way)
+// or for a tight *task*/checkbox item (whose tokens[0] is 'text' rather
+// than the 'paragraph' the loose branch expects, so it falls through to the
+// same unshift-a-checkbox-token behavior either way) - every other item
+// just takes the same parser.parse(item.tokens, true) call a genuinely
+// loose item's text already took, which is what actually turns reflowText
+// on for it.
+const originalListitem = TerminalRenderer.prototype.listitem;
+TerminalRenderer.prototype.listitem = function (item) {
+  if (item && typeof item === 'object' && !item.loose) {
+    item = { ...item, loose: true };
+  }
+  return originalListitem.call(this, item);
+};
+
+export function stylingEnabled(stream = process.stdout) {
+  return Boolean(stream && stream.isTTY) && !process.env.NO_COLOR;
+}
+
+const enabled = stylingEnabled();
+
+// Forced to level 1 (standard 16-color ANSI) rather than left to chalk's own
+// ambient detection - readable on both light and dark backgrounds without
+// depending on truecolor support, and avoids the FORCE_COLOR quirk noted
+// above ever leaking a color decision we didn't intend.
+const c = new Chalk({ level: enabled ? 1 : 0 });
+
+// Visual width of turnMarker()'s own text ('•' plus its one trailing space -
+// see turnMarker below), ignoring ANSI codes: the bullet is a single-column
+// glyph in a monospace terminal. This is the hanging-indent column every
+// wrapped/continuation line of a turnMarker-led reply aligns under (see
+// indentContinuation below), and also how much narrower marked-terminal's
+// own reflow width needs to be so an indented line still fits the terminal
+// instead of running TURN_MARKER_WIDTH columns past it.
+const TURN_MARKER_WIDTH = 2;
+
+// marked-terminal's own list rendering adds a further indent on top of
+// whatever reflowText already wrapped a list item's text to: a tab-stop
+// (marked-terminal's own default `tab` option, left unset here so it's 4)
+// plus the bullet marker's own width (its internal BULLET_POINT constant,
+// '* ' - 2 columns), applied to every line of a list via
+// indentLines/bulletPointLines *after* reflow already ran - see
+// marked-terminal's Renderer.prototype.list. Unlike TURN_MARKER_WIDTH
+// above, neither of those is subtracted from the width reflowText wraps
+// to, so a list item's own continuation line could still run past
+// contentWidth() once that indent lands on top of an already
+// maximally-reflowed line - confirmed live in a real 260-column tmux pane:
+// a hyphenated word ("off-by-one", which reflowText correctly never
+// splits internally - it isn't whitespace) landed exactly on that
+// unaccounted overhang and got hard-split by the terminal's own hardware
+// wrap instead, the exact same mid-word-break symptom this file's list-
+// item reflow fix (below) exists to prevent. Covers exactly one level of
+// list nesting - the common case an LLM reply actually produces; a list
+// nested inside a list item could still overflow by a further
+// LIST_INDENT_OVERHEAD per extra nesting level, not accounted for here as
+// disproportionate to the reported bug. Subtracted from the *global*
+// reflow width (which also governs paragraphs, which don't need it)
+// rather than only for list rendering specifically - marked-terminal
+// doesn't expose a per-element-type width, and paragraphs losing a few
+// columns of a terminal that's often 200+ wide is a non-issue next to a
+// list item actually overflowing and hard-breaking mid-word.
+const LIST_INDENT_OVERHEAD = 6; // marked-terminal's default tab (4) + BULLET_POINT width (2)
+
+// The box rule and prose wrap track the real terminal width exactly, with
+// no upper bound - this used to cap at a fixed ~80 columns (later raised to
+// a 120-column ceiling) regardless of how wide the terminal actually was,
+// which read as "the width isn't tracking the window" on anything wider
+// than that (confirmed live: a 100+ col terminal still rendered an 80-col
+// rule with visible unused space to its right). Thomson confirmed he wants
+// this literally uncapped - a fullscreen monitor is often 200-300+ columns,
+// and even 120 still read as capped - so there is deliberately no ceiling
+// here any more. `|| 80` only covers the case where the terminal hasn't
+// reported a column count at all (columns is undefined/0), not a readability
+// cap.
+function contentWidth() {
+  return process.stdout.columns || 80;
+}
+
+// Registers marked-terminal's renderer with the current width. Callable
+// more than once - re-registering with a fresh width is exactly how a
+// terminal resize is picked up (see refreshWidth below), since marked's own
+// `use()` replaces the previously-registered renderer rather than stacking
+// on top of it.
+function configureMarkedTerminal() {
+  marked.use(
+    markedTerminal({
+      // Reserves TURN_MARKER_WIDTH columns for the hanging indent every
+      // rendered reply gets on top of this (renderMarkdown/
+      // createMarkdownStreamer are only ever used for backend replies,
+      // which always carry turnMarker()'s indent - see companion.js's
+      // sendAndPrintTurn) - without this, a paragraph reflowed right up to
+      // contentWidth() would then get indented past it once
+      // indentContinuation runs, overflowing the terminal's actual column
+      // count instead of staying within the terminal's own width. Also
+      // reserves LIST_INDENT_OVERHEAD (see above) for the further indent
+      // list rendering adds on top of that.
+      width: contentWidth() - TURN_MARKER_WIDTH - LIST_INDENT_OVERHEAD,
+      // Reflow (word-wrap) prose text to the width above rather than
+      // leaving lines exactly as the model generated them - the width
+      // above already matches the terminal's own edge (minus the hanging
+      // indent), so without this, text generated with its own line breaks
+      // (e.g. a numbered list item) could still run past it.
+      reflowText: true,
+    })
+  );
+}
+
+if (enabled) configureMarkedTerminal();
+
+// Re-registers marked-terminal's renderer against the terminal's *current*
+// width - call this after a resize (companion.js listens for
+// process.stdout's 'resize' event) so markdown rendered from here on wraps
+// to the new size instead of whatever was captured at import time. A no-op
+// when styling is off, matching every other helper in this module - nothing
+// uses marked-terminal's renderer over a pipe anyway.
+export function refreshWidth() {
+  if (enabled) configureMarkedTerminal();
+}
+
+// De-emphasizes companion's own status/system lines (startup banner, relay
+// server lifecycle, warnings, errors) relative to actual conversation
+// content. A no-op string pass-through when styling is off.
+export function dim(text) {
+  return enabled ? c.dim(text) : text;
+}
+
+// The readline prompt marker. Plain '> ' when styling is off, matching the
+// prompt this program has always used; a one-space left margin plus the
+// colored ">" when styling is on, so the prompt lines up under boxRule's own
+// matching one-space margin below rather than starting flush at column 0 -
+// no "you"/role text (see turnMarker below for the tutor-reply side of the
+// same convention).
+export function promptString() {
+  return enabled ? ` ${c.cyanBright.bold('>')} ` : '> ';
+}
+
+// The marker opening a tutor reply turn - a single bullet, replacing the
+// old "tutor" role label and framing rule. '' when styling is off, same
+// convention as the rest of this module's labels: callers must skip adding
+// it entirely in that case, not print an empty prefix, so non-TTY output
+// stays exactly the raw reply text.
+export function turnMarker() {
+  if (!enabled) return '';
+  return `${c.magentaBright('•')} `;
+}
+
+// Indents every line of `text` except its very first by TURN_MARKER_WIDTH
+// spaces, so a multi-line turnMarker-led reply's wrapped/continuation lines
+// align under where the text starts after the bullet - a hanging indent -
+// rather than wrapping back to column 0. Matches a Claude Code CLI
+// transcript's own look (see companion/AGENTS.md's "message padding" note).
+// Blank lines are left untouched rather than padded with trailing
+// whitespace, so a blank separator row between blocks still reads as
+// genuinely empty. `indentFirstLine: true` indents the first line too - for
+// a streamed reply's second-or-later piece (see companion.js's
+// writeReplyPiece), which starts on its own fresh line that still needs the
+// same indent as every other continuation line, unlike the very first piece
+// where turnMarker() itself already occupies that column. A no-op when
+// styling is off, same convention as the rest of this module: there is no
+// marker or indent to align under over a pipe.
+export function indentContinuation(text, { indentFirstLine = false } = {}) {
+  if (!enabled) return text;
+  const pad = ' '.repeat(TURN_MARKER_WIDTH);
+  return text
+    .split('\n')
+    .map((line, i) => ((i === 0 && !indentFirstLine) || line === '' ? line : pad + line))
+    .join('\n');
+}
+
+// A thin rule marking off the pinned input box from the conversation above
+// it, at the same width prose wraps to (minus the one-space left margin
+// below, so the rule's right edge still lands at the terminal's own edge
+// rather than running one column past it). A one-space left margin -
+// matching promptString's own - gives the box a consistent inset rather than
+// starting flush at column 0; companion.js's drawBoxRaw also prints a blank
+// line above this rule for breathing room from whatever chat content
+// precedes it. '' when styling is off - there is no persistent input box
+// over a pipe.
+export function boxRule() {
+  if (!enabled) return '';
+  return ` ${c.dim('─'.repeat(contentWidth() - 1))}`;
+}
+
+// Renders markdown (headers, bold/emphasis, lists, fenced code blocks with
+// syntax highlighting) to ANSI-styled text for a real TTY, wrapped to the
+// width above. Returns the text unchanged when styling is off, so piped
+// output keeps showing the raw markdown exactly as before this feature
+// existed.
+export function renderMarkdown(text) {
+  if (!enabled) return text;
+  // marked-terminal pads block elements with blank lines; collapse runs of
+  // 3+ into a single blank line and trim trailing whitespace so replies
+  // don't accumulate extra vertical space compared to before.
+  return marked.parse(text).replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+// --- streaming reply support -------------------------------------------
+//
+// Two pieces on top of the styling/rendering above: rendering markdown
+// safely as it streams in rather than only once a reply is fully done, and
+// a spinner while waiting on the backend. companion.js owns *when* a reply
+// starts/ends and how each piece reaches the terminal (it has the readline
+// instance and the pinned input box); this module only owns what each piece
+// looks like.
+
+// One frame of the "waiting for the backend" spinner, cycling through
+// SPINNER_FRAME_COUNT frames on request - callers own the timing
+// (setInterval) and where each frame is drawn, since that needs readline
+// coordination this module doesn't have. Plain, unstyled text when styling
+// is off (companion.js's spinner is itself a no-op in that case, but the
+// frame text stays meaningful if ever printed directly, e.g. in a test).
+const SPINNER_GLYPHS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPINNER_FRAME_COUNT = SPINNER_GLYPHS.length;
+export function spinnerFrame(i) {
+  const glyph = SPINNER_GLYPHS[((i % SPINNER_GLYPHS.length) + SPINNER_GLYPHS.length) % SPINNER_GLYPHS.length];
+  const text = `${glyph} thinking`;
+  // A one-space left margin, matching boxRule/promptString's own - the
+  // spinner temporarily occupies the same column position the box's prompt
+  // normally does, so it should line up with it rather than sitting one
+  // column further left.
+  return enabled ? ` ${c.dim(text)}` : text;
+}
+
+// Feeds a reply in incrementally, rendering complete markdown as soon as a
+// safe boundary is reached: a blank line outside a fenced code block, or the
+// close of a fenced code block itself. Never mid-fence, never mid-block -
+// marked-terminal renders those as broken/uncoloured text. push() returns
+// text ready to print now ('' if nothing new is complete yet); finish()
+// flushes whatever's left once the stream ends, complete or not (the common
+// case: a reply's last block has no trailing blank line).
+//
+// When styling is off, this is a pure pass-through - each push() returns
+// its chunk unchanged, finish() has nothing left to flush - since raw
+// markdown is never rendered either way (see renderMarkdown above), the
+// same as a non-streaming reply already looks over a pipe.
+export function createMarkdownStreamer() {
+  if (!enabled) {
+    return { push: (chunk) => chunk, finish: () => '' };
+  }
+
+  let buffer = '';
+
+  return {
+    push(chunk) {
+      buffer += chunk;
+      const splitAt = findSafeSplit(buffer);
+      if (splitAt <= 0) return '';
+      const complete = buffer.slice(0, splitAt);
+      buffer = buffer.slice(splitAt);
+      return renderMarkdown(complete);
+    },
+    finish() {
+      if (!buffer) return '';
+      const rendered = renderMarkdown(buffer);
+      buffer = '';
+      return rendered;
+    },
+  };
+}
+
+// Single left-to-right scan tracking fenced-code-block open/close state,
+// returning the end index of the latest position it's safe to cut at:
+// right after a closing fence's own line, or a blank line encountered while
+// not inside an open fence. -1 if no such point exists yet. A plain scan
+// rather than a regex split specifically so an odd/open fence count is
+// tracked incrementally and blank lines inside it are correctly ignored.
+function findSafeSplit(text) {
+  let fenceCount = 0;
+  let lastSafe = -1;
+  let i = 0;
+  while (i < text.length) {
+    if (text.startsWith('```', i)) {
+      fenceCount += 1;
+      i += 3;
+      if (fenceCount % 2 === 0) {
+        const lineEnd = text.indexOf('\n', i);
+        if (lineEnd !== -1) lastSafe = lineEnd + 1;
+      }
+      continue;
+    }
+    if (fenceCount % 2 === 0 && text.startsWith('\n\n', i)) {
+      lastSafe = i + 2;
+    }
+    i += 1;
+  }
+  return lastSafe;
+}

package/runtime/companion/vault-summary.js

@@ -0,0 +1,168 @@
+// companion/vault-summary.js - vault auto-summary logic
+//
+// Split out from companion.js so this feature's actual logic (building the
+// addendum, parsing the model's reply, writing the notes) can be exercised
+// directly by tests without booting companion.js's interactive readline
+// loop or relay-server lifecycle. See companion.js for how this gets wired
+// into the capture handling path.
+//
+// The core constraint shaping this file: reuse the same backend response
+// already being shown in the terminal for a Submit, and never make a
+// second LLM call just for the vault note. So buildVaultAddendum appends
+// one extra instruction to the Submit message, asking the model to tack a
+// machine-readable block onto the very end of the same reply it was
+// already going to give; extractVaultBlock then peels that block back off
+// before the reply is printed, so the chat experience is unchanged.
+//
+// The model infers both the submitted code's complexity and the best
+// achievable complexity, so the resulting star rating is a judgment call.
+// Topic names are local vault metadata and never enter the addendum.
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const vaultNotes = require('../vault-tool/vault-notes.js');
+
+export const defaultVaultPath = vaultNotes.defaultVaultPath;
+export const resolveVaultConfig = vaultNotes.resolveVaultConfig;
+export const validateVaultPath = vaultNotes.validateVaultPath;
+
+const VAULT_JSON_RE = /<<<VAULT_JSON>>>([\s\S]*?)<<<END_VAULT_JSON>>>/;
+export const AI_NOTES_HEADER = '## AI Notes';
+export const AI_TOPIC_INDEX_HEADER = '## AI Topic Index';
+
+export function clampInt(value, min, max) {
+  const n = Math.round(Number(value));
+  if (!Number.isFinite(n)) return null;
+  return Math.min(max, Math.max(min, n));
+}
+
+export function starRatingLine(stars) {
+  const full = Math.max(0, Math.min(5, stars ?? 0));
+  return `${'⭐'.repeat(full)}${'☆'.repeat(5 - full)} (${stars ?? '?'}/5)`;
+}
+
+// Keeps captured tags in local vault metadata and builds a tag-free addendum
+// instructing the model to emit the structured block. Returns null if the capture
+// doesn't carry enough to act on (missing slug/title - shouldn't happen
+// with a current extension build, but captures can predate a field).
+export function prepareVaultContext({ capture, vaultPath, algorithmsSubfolder }) {
+  if (!capture.problemSlug || !capture.problemTitle) return null;
+
+  const tags = Array.isArray(capture.problemTags)
+    ? capture.problemTags.filter((t) => typeof t === 'string' && t.trim())
+    : [];
+
+  const problemNotePath = vaultNotes.ensurePerProblemNoteFile(
+    vaultPath,
+    { problemSlug: capture.problemSlug, problemTitle: capture.problemTitle },
+    algorithmsSubfolder
+  );
+
+  // Only tags that already have a curated Study/Algorithms/<Tag>.md note get
+  // linked - this deliberately doesn't invent a new topic note for
+  // every raw LeetCode tag (see vault-notes.js's findTopicNoteByTagName).
+  const matchedTopics = [];
+  const topicNotePaths = {};
+  for (const tag of tags) {
+    const topicPath = vaultNotes.findTopicNoteByTagName(vaultPath, tag, algorithmsSubfolder);
+    if (!topicPath) continue;
+    matchedTopics.push(tag);
+    topicNotePaths[tag] = topicPath;
+  }
+
+  const addendum = buildVaultAddendum();
+  return { problemNotePath, tags, matchedTopics, topicNotePaths, addendum };
+}
+
+export function buildVaultAddendum() {
+  const lines = [
+    '',
+    '---',
+    "This was a Submit capture with the vault auto-summary feature on. After your tutoring response above, append exactly one more block at the very end, between the literal markers <<<VAULT_JSON>>> and <<<END_VAULT_JSON>>>, containing a single-line JSON object (no markdown, no code fence around it) with these exact keys:",
+    '- "rightThings": string, 1-3 sentences on what the student\'s submitted code does right, based on your analysis above.',
+    '- "notConnecting": string, 1-3 sentences on what the student does not seem to be connecting or missing. If the solution is already fully correct and optimal, say so plainly here instead of inventing a gap.',
+    '- "problemStars": integer 1-5, rating purely how this code\'s inferred time complexity compares to the best achievable time complexity for this exact problem. Matching the optimal is 5, regardless of what the optimal actually is. This is your best inference, not a verified fact.',
+    '- "complexityNote": string, one sentence stating the inferred complexity of the submitted code and the inferred optimal complexity for this problem.',
+    '- "topicProficiency": an empty object. Topic tags stay in the local vault writer.',
+  ];
+  return lines.join('\n');
+}
+
+// Splits a backend reply into the text meant for the terminal and the
+// parsed vault JSON block, if the addendum's marker is present. Always
+// strips the raw block from displayText, even if JSON.parse fails, so a
+// malformed block never leaks into the chat transcript. `warn`, if given, is
+// called with a message when the block is present but unparseable.
+export function extractVaultBlock(text, { warn } = {}) {
+  const match = text.match(VAULT_JSON_RE);
+  if (!match) return { displayText: text, vaultData: null };
+
+  const displayText = (text.slice(0, match.index) + text.slice(match.index + match[0].length))
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+
+  let vaultData = null;
+  try {
+    vaultData = JSON.parse(match[1].trim());
+  } catch (err) {
+    if (warn) warn(`could not parse vault auto-summary JSON (${err.message})`);
+  }
+  return { displayText, vaultData };
+}
+
+// Rewrites a per-problem note's "AI Notes" section and every matched topic
+// note's "AI Topic Index" section in place. The topic index is rebuilt as
+// an overall proficiency line plus one wikilinked bullet per problem
+// attempted under that topic, keyed by title so updating one problem's line
+// never disturbs the others.
+export function writeVaultAutoSummary({ capture, vaultContext, vaultData }) {
+  const stars = clampInt(vaultData.problemStars, 1, 5);
+  const topicsLine = vaultContext.tags.length
+    ? vaultContext.tags.map((tag) => (vaultContext.matchedTopics.includes(tag) ? `[[${tag}]]` : tag)).join(', ')
+    : '(none captured)';
+  const updatedAt = new Date().toISOString();
+
+  const aiNotesBody = [
+    `**Rating:** ${starRatingLine(stars)}`,
+    `**Complexity:** ${vaultData.complexityNote || '(not provided)'}`,
+    `**Topics:** ${topicsLine}`,
+    '',
+    `**Doing right:** ${vaultData.rightThings || '(not provided)'}`,
+    '',
+    `**Not connecting:** ${vaultData.notConnecting || '(not provided)'}`,
+    '',
+    `*Last updated ${updatedAt} after submit attempt #${capture.attemptSeq ?? '?'}. Rating is an AI inference, not a verified fact - both the optimal complexity for this problem and this code's complexity are estimated by the model, not looked up. Reliable for well-known problems, may be wrong on obscure ones.*`,
+  ].join('\n');
+
+  const problemContent = fs.readFileSync(vaultContext.problemNotePath, 'utf8');
+  fs.writeFileSync(vaultContext.problemNotePath, vaultNotes.upsertSection(problemContent, AI_NOTES_HEADER, aiNotesBody));
+
+  for (const topic of vaultContext.matchedTopics) {
+    const topicPath = vaultContext.topicNotePaths[topic];
+    const proficiency = clampInt(vaultData.topicProficiency && vaultData.topicProficiency[topic], 1, 10);
+    const topicContent = fs.readFileSync(topicPath, 'utf8');
+    const existingBody = vaultNotes.readSection(topicContent, AI_TOPIC_INDEX_HEADER);
+
+    const bulletsByTitle = new Map();
+    if (existingBody) {
+      for (const line of existingBody.split('\n')) {
+        const m = line.match(/^- \[\[(.+?)\]\] - (.+)$/);
+        if (m) bulletsByTitle.set(m[1], m[2]);
+      }
+    }
+    bulletsByTitle.set(capture.problemTitle, starRatingLine(stars));
+
+    const sortedTitles = Array.from(bulletsByTitle.keys()).sort((a, b) => a.localeCompare(b));
+    const overallLine =
+      proficiency !== null
+        ? `**Overall proficiency:** ${proficiency}/10 (AI holistic judgment)`
+        : existingBody?.match(/^\*\*Overall proficiency:.*$/m)?.[0] || '**Overall proficiency:** (not yet rated)';
+    const newBody = [overallLine, '', ...sortedTitles.map((title) => `- [[${title}]] - ${bulletsByTitle.get(title)}`)].join(
+      '\n'
+    );
+
+    fs.writeFileSync(topicPath, vaultNotes.upsertSection(topicContent, AI_TOPIC_INDEX_HEADER, newBody));
+  }
+}

package/runtime/companion/virtual-terminal.js

@@ -0,0 +1,138 @@
+// companion/virtual-terminal.js - a small ANSI escape-code interpreter that
+// replays a raw byte stream companion.js wrote to stdout into the 2D grid a
+// real terminal would actually be showing, given the current cursor
+// position and the escape codes companion.js/readline emitted along the
+// way.
+//
+// Exists specifically because some of companion.js's box-pinning bugs (see
+// AGENTS.md - the readline `prevRows` desync behind "a capture arriving
+// while a long typed line occupies the prompt corrupts everything above the
+// box") are about *interpreted* rendering: a `moveCursor` + `clearScreenDown`
+// sequence overwrites text that's still physically present, byte for byte,
+// earlier in the raw captured stream. A plain text/line search over raw
+// output (the technique box-padding.test.js already uses for the simpler
+// padding-math case, where padding really is just literal '\n' characters)
+// can't tell "this text is still on screen" apart from "this text was
+// already erased by a later escape sequence" - both leave the same bytes
+// sitting in the capture. Only replaying the escapes against a real cursor
+// position/grid, the way a terminal does, can.
+//
+// Scoped deliberately narrow: only the escape sequences companion.js itself
+// emits directly (see its readline.clearLine/cursorTo/moveCursor calls and
+// its own literal '\x1b[2J\x1b[H'/'\x1b[?1049h' writes) and the ones node's
+// own readline._refreshLine emits internally on rl.prompt(true) (moveCursor,
+// cursorTo, clearScreenDown - confirmed empirically, see this file's own
+// test for the exact bytes) - not a general-purpose terminal emulator.
+// Private-mode sequences (`\x1b[?...h`/`l`, e.g. the alternate-screen and
+// mouse-tracking toggles) and SGR color codes (`\x1b[...m`) are recognized
+// and ignored (no visible effect on the grid) rather than mishandled.
+
+const CSI_RE = /\x1b\[([0-9;?]*)([A-Za-z])/g;
+
+export function replayToScreen(raw, { cols, rows }) {
+  const screen = Array.from({ length: rows }, () => new Array(cols).fill(' '));
+  let row = 0;
+  let col = 0;
+
+  function clearRow(r, fromCol, toCol) {
+    for (let c = fromCol; c <= toCol; c += 1) screen[r][c] = ' ';
+  }
+
+  function scrollUp() {
+    screen.shift();
+    screen.push(new Array(cols).fill(' '));
+  }
+
+  function newline() {
+    row += 1;
+    col = 0;
+    if (row >= rows) {
+      scrollUp();
+      row = rows - 1;
+    }
+  }
+
+  function putChar(ch) {
+    if (col >= cols) newline();
+    screen[row][col] = ch;
+    col += 1;
+  }
+
+  let i = 0;
+  while (i < raw.length) {
+    const ch = raw[i];
+    if (ch === '\x1b' && raw[i + 1] === '[') {
+      CSI_RE.lastIndex = i;
+      const match = CSI_RE.exec(raw);
+      if (!match || match.index !== i) {
+        // Not a well-formed CSI sequence after all - skip just the ESC so
+        // we don't get stuck in an infinite loop on stray bytes.
+        i += 1;
+        continue;
+      }
+      const params = match[1];
+      const final = match[2];
+      const isPrivate = params.startsWith('?');
+      const nums = isPrivate ? [] : params.split(';').filter(Boolean).map(Number);
+      if (!isPrivate) {
+        switch (final) {
+          case 'A': // cursor up
+            row = Math.max(0, row - (nums[0] || 1));
+            break;
+          case 'B': // cursor down
+            row = Math.min(rows - 1, row + (nums[0] || 1));
+            break;
+          case 'G': // cursor to column (1-indexed)
+            col = Math.max(0, (nums[0] || 1) - 1);
+            break;
+          case 'H': { // cursor position (row;col, 1-indexed)
+            row = Math.max(0, Math.min(rows - 1, (nums[0] || 1) - 1));
+            col = Math.max(0, (nums[1] || 1) - 1);
+            break;
+          }
+          case 'K': { // erase in line
+            const mode = nums[0] || 0;
+            if (mode === 0) clearRow(row, col, cols - 1);
+            else if (mode === 1) clearRow(row, 0, col);
+            else clearRow(row, 0, cols - 1);
+            break;
+          }
+          case 'J': { // erase in display
+            const mode = nums[0] || 0;
+            if (mode === 0) {
+              clearRow(row, col, cols - 1);
+              for (let r = row + 1; r < rows; r += 1) clearRow(r, 0, cols - 1);
+            } else if (mode === 2) {
+              for (let r = 0; r < rows; r += 1) clearRow(r, 0, cols - 1);
+            }
+            break;
+          }
+          default:
+            break; // SGR ('m') and anything else - no visible grid effect
+        }
+      }
+      // Private-mode toggles (alternate screen, mouse tracking) have no
+      // visible grid effect either - nothing to do for them.
+      i = match.index + match[0].length;
+      continue;
+    }
+    if (ch === '\x1b') {
+      i += 1; // a lone/malformed escape - skip it, don't loop forever
+      continue;
+    }
+    if (ch === '\n') {
+      newline();
+      i += 1;
+      continue;
+    }
+    if (ch === '\r') {
+      col = 0;
+      i += 1;
+      continue;
+    }
+    putChar(ch);
+    i += 1;
+  }
+
+  return screen.map((r) => r.join('').replace(/\s+$/, ''));
+}