quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/main.js

@@ -0,0 +1,244 @@
+import React from 'react';
+import { render } from 'ink';
+import { realpathSync } from 'node:fs';
+import { App } from './app.js';
+import { inkRenderOptions, inkStdout } from './term.js';
+import { createDemoApi } from './demo.js';
+import { DEMO_LABEL } from './demo.fixtures.js';
+import { PASTE_ON } from './keys.js';
+import { shouldShowWelcome, markWelcomeSeen } from './welcome.js';
+import { loadRules, rulesContext } from './rules.js';
+import { createTranscript } from './transcript.js';
+import { parseModelArg } from './model.js';
+import { applySettings } from './slash/settings.js';
+import { headOf, RUNNING_ROOT, execRestart, checkRestart } from './slash/restart.js';
+
+const FLAGS = new Set(['-p', '--profile', '--verbose', '--demo', '--print', '--output', '--conversation', '--turn-id', '--timeout', '--color', '--no-clear', '-n', '--name', '--service-key', '--demo-onboarding', '--provider', '--model', '--resume', '-h', '--help', '--']);
+const isFlag = (a) => FLAGS.has(a) || /^--(profile|verbose|print|output|conversation|turn-id|timeout|provider|model|resume)=/.test(a);
+
+export function parseArgs(argv) {
+  const o = { profile: null, verbose: 'on', demo: false, help: false, print: false, prompt: null, output: 'text', conversation: null, turnId: null, timeout: 0, color: false, noClear: false, name: null, serviceKey: false, demoOnboarding: false, provider: null, resume: null, verboseSet: false, errors: [] };
+  let rawProvider = null, rawModel = null;
+  const value = (flag, i) => { const v = argv[i + 1]; if (v === undefined || (v.startsWith('-') && isFlag(v))) { o.errors.push(`${flag} needs a value`); return undefined; } return v; };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { const rest = argv.slice(i + 1).join(' '); if (rest) o.prompt = rest; break; }
+    if (a === '-p' || a === '--profile') { const v = value(a, i); if (v !== undefined) { o.profile = v; i++; } }
+    else if (a.startsWith('--profile=')) o.profile = a.slice(10);
+    else if (a === '--verbose') { o.verboseSet = true; const v = argv[i + 1]; if (['off', 'on', 'full'].includes(v)) { o.verbose = v; i++; } else o.verbose = 'on'; } // no value means on
+    else if (a.startsWith('--verbose=')) { o.verboseSet = true; o.verbose = a.slice(10); }
+    else if (a === '--resume') { const v = argv[i + 1]; if (v !== undefined && !v.startsWith('-')) { o.resume = v; i++; } else o.resume = true; } // alone: the picker
+    else if (a.startsWith('--resume=')) o.resume = a.slice(9) || true;
+    else if (a === '-n' || a === '--name') { const v = value(a, i); if (v !== undefined) { o.name = v; i++; } }
+    else if (a.startsWith('--name=')) o.name = a.slice(7);
+    else if (a === '--demo') o.demo = true;
+    else if (a === '--demo-onboarding') o.demoOnboarding = true;
+    else if (a === '--print') { o.print = true; const n = argv[i + 1]; if (n !== undefined && !isFlag(n)) { o.prompt = n; i++; } }
+    else if (a.startsWith('--print=')) { o.print = true; o.prompt = a.slice(8); }
+    else if (a === '--output') { const v = value(a, i); if (v !== undefined) { o.output = v; i++; } }
+    else if (a.startsWith('--output=')) o.output = a.slice(9);
+    else if (a === '--conversation') { const v = value(a, i); if (v !== undefined) { o.conversation = v; i++; } }
+    else if (a === '--turn-id') { const v = value(a, i); if (v !== undefined) { o.turnId = v; i++; } }
+    else if (a === '--timeout') { const v = value(a, i); if (v !== undefined) { o.timeout = Number(v) || 0; i++; } }
+    else if (a === '--color') o.color = true;
+    else if (a === '--no-clear') o.noClear = true;
+    else if (a === '--service-key') o.serviceKey = true;
+    else if (a === '--provider' || a === '--model') { const v = value(a, i); if (v !== undefined) { if (a === '--provider') rawProvider = v; else rawModel = v; i++; } }
+    else if (a.startsWith('--provider=')) rawProvider = a.slice(11);
+    else if (a.startsWith('--model=')) rawModel = a.slice(8);
+    else if (a === '--prompt-profile') { const v = value(a, i); if (v !== undefined) { o.promptProfile = v; i++; } }
+    else if (a.startsWith('--prompt-profile=')) o.promptProfile = a.slice(17);
+    else if (a === '-h' || a === '--help') o.help = true;
+    else if (!a.startsWith('-') && o.prompt === null && argv.includes('--print')) o.prompt = a; // `--print` given earlier or later; this is its prompt
+    else o.errors.push(a.startsWith('-') ? `unknown option ${a}` : `unexpected argument ${a}`);
+  }
+  if (rawModel && !rawProvider) o.errors.push('--model needs --provider (e.g. --provider openai --model gpt-5.4)');
+  else if (rawProvider) {
+    const m = parseModelArg(rawModel ? `${rawProvider} ${rawModel}` : rawProvider);
+    if (!m.ok) o.errors.push(m.error); else o.provider = m.choice || 'auto'; // 'auto' = this run ignores the saved /model choice
+  }
+  if (o.promptProfile !== undefined && !['compact', 'full'].includes(o.promptProfile)) { o.errors.push(`invalid --prompt-profile "${o.promptProfile}" (use compact or full)`); delete o.promptProfile; }
+  if (!['off', 'on', 'full'].includes(o.verbose)) o.verbose = 'on';
+  if (!['text', 'json'].includes(o.output)) { o.errors.push(`invalid --output "${o.output}" (use text or json)`); o.output = 'text'; }
+  return o;
+}
+
+export const USAGE = 'quox [-p|--profile <name>] [-n|--name <session name>] [--conversation <id>] [--resume [id|name]] [--verbose off|on|full] [--demo] [--no-clear] [--service-key] [--provider openai|anthropic|ollama|openrouter|huggingface|groq|together|lmstudio|vllm|custom|auto [--model <id>]]   (quoxon is an alias; the old menu is `quox tui`)\n  quox --conversation <id>   resume that conversation interactively (its saved turns load into the window)\n  quox --resume [id|name]   pick up a recent conversation; alone it opens a picker\n  quox --print "<prompt>" [--output text|json] [--conversation <id>] [--turn-id <id>] [--timeout <s>] [--provider <p> [--model <id>]] [--prompt-profile compact|full]   (prompt from stdin if absent or -; use -- before a prompt that starts with -)\n  exit: 0 completed, 1 other, 2 held for approval, 3 interrupted or abandoned, 4 not signed in, 5 ended without server confirmation\n  --provider asks the server for that provider this run (default: your /model choice for this profile, else auto); turn.started from the server says what ran\n  --service-key lets chat use an ambient QUOX_SERVICE_KEY when the profile has no login (never used silently)\n  --demo plays a simulated journey on its own (no server, nothing real runs)\n  --demo-onboarding walks Getting started with a dry-run install (nothing is downloaded, built or started)';
+
+/** Default profile: a resident (agent) login cannot chat, so use the single logged-in human profile. */
+export function pickProfile(explicit, cfgMod) {
+  if (explicit) return { name: explicit, note: null };
+  const probe = cfgMod.loadConfig();
+  const active = probe.getActiveProfileName?.();
+  const residents = new Set((probe.listResidentProfiles?.() || []).map(r => r.name));
+  return choosePick(active, residents, probe.listProfiles?.() || []);
+}
+export function choosePick(active, residents, profiles) {
+  if (!residents.has(active)) return { name: undefined, note: null };
+  const humans = profiles.filter(p => !residents.has(p.name) && p.loggedIn);
+  if (humans.length === 1) return { name: humans[0].name, note: null }; // the status line shows the profile; no transcript noise
+  return { name: undefined, note: `The default profile "${active}" is an agent login and cannot chat. Pass -p <your profile>.` };
+}
+
+/**
+ * Chat identity gate. A named profile that does not exist is an error (never created on the fly), and an
+ * ambient QUOX_SERVICE_KEY is only a credential when the user asked for it (--service-key or FORCE).
+ * -> null when chat may proceed, else { message }.
+ */
+export function chatCredentialProblem({ profileArg, profiles, hasStoredLogin, profileName, env = process.env, serviceKeyFlag = false }) {
+  if (profileArg && !profiles.some(p => p.name === profileArg)) return { message: `profile ${profileArg} does not exist; create it with: quox login -p ${profileArg}` };
+  if (hasStoredLogin) return null;
+  if ((serviceKeyFlag || env.QUOX_FORCE_SERVICE_KEY) && env.QUOX_SERVICE_KEY) return null;
+  return { message: `Not signed in for chat on profile ${profileName}. Run: quox login -p ${profileName}${env.QUOX_SERVICE_KEY ? ' (an ambient QUOX_SERVICE_KEY is ignored unless you pass --service-key)' : ''}` };
+}
+
+/**
+ * Is this a machine with no Quox server configured at all? Then bare `quox` is Getting started, and --print
+ * says how to get there. Reads profiles only (no network).
+ */
+export async function noServerConfigured(opts, cfgMod, env = process.env) {
+  const { needsGettingStarted } = await import('./onboarding/detect.js');
+  const { loadJourney } = await import('./onboarding/journey.js');
+  const probe = cfgMod.loadConfig();
+  return needsGettingStarted({ profiles: probe.listProfiles?.() || [], residents: probe.listResidentProfiles?.() || [], profileArg: opts.profile, env, serviceKeyFlag: opts.serviceKey, journey: loadJourney() });
+}
+
+/** --print without a usable login: today's message, plus the way in when no server exists yet. */
+export function printAuthMessage(problem, gettingStarted, hint) {
+  return `quox: ${problem.message}\n${gettingStarted ? `quox: ${hint}\n` : ''}`;
+}
+
+/** Keys typed before the app is ready: raw mode now, so nothing is cooked-echoed, buffered for the composer. */
+export function captureEarlyInput(stdin = process.stdin, stdout = process.stdout) {
+  if (!stdin?.isTTY) return null;
+  const chunks = [];
+  const fn = (d) => chunks.push(typeof d === 'string' ? d : d.toString('utf8'));
+  try { stdin.setRawMode?.(true); stdin.resume?.(); } catch { /* not a tty after all */ }
+  stdin.on('data', fn);
+  if (stdout?.isTTY) stdout.write(PASTE_ON);
+  return { chunks, detach: () => stdin.off('data', fn) };
+}
+
+/**
+ * Clear the screen before the chat client? Never right after Getting started: its finale (the one-time
+ * dashboard link, a password shown once) is on screen and in scrollback, and ESC[3J would erase both.
+ */
+export function shouldClearBeforeChat({ isTTY, noClear, fromGettingStarted }) {
+  return Boolean(isTTY) && !noClear && !fromGettingStarted;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.help) { console.log(USAGE); return; }
+  if (opts.errors.length) { process.stderr.write(`quox: ${opts.errors.join('; ')}\n${USAGE}\n`); process.exitCode = 1; return; }
+  // Raw mode FIRST: the awaits below (module loads, config, health) must not leave the tty cooked.
+  const early = !opts.print ? captureEarlyInput() : null;
+  const cwd = process.cwd().replace(process.env.HOME || '\0', '~');
+  const { resolveCliVersion } = await import('../core/version.js');
+  let version = '0.2.0';
+  try { version = resolveCliVersion?.() || version; } catch { /* keep default */ }
+  if (opts.print) return mainPrint(opts);
+  let replay = null;
+  let fromGettingStarted = false;
+  if (opts.demoOnboarding || (!opts.demo && await noServerConfigured(opts, await import('../core/config.js')))) {
+    // Getting started (FIRST_RUN_JOURNEY.md C2a): a separate view, never the chat client talking.
+    if (process.stdout.isTTY && !opts.noClear) process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+    const welcome = shouldShowWelcome({ print: false });
+    if (welcome && !opts.demoOnboarding) markWelcomeSeen();
+    const { runGettingStarted } = await import('./onboarding/index.js');
+    const r = await runGettingStarted({ version, cwd, welcome, earlyInput: early, demo: opts.demoOnboarding });
+    if (r?.action !== 'connected') return;
+    // signed in (an existing server, or the one just installed): carry on into the conversation,
+    // and a fresh install replays the original request as the first real turn
+    replay = r.replay || null;
+    fromGettingStarted = true;
+  }
+  let props;
+  let restart = null; // set by /restart: run the installed quox here once the app has let go of the terminal
+  if (opts.demo) {
+    // /restart works in the demo too (a fresh demo, nothing to resume): the same hand-over, testable with no server
+    props = { api: createDemoApi(), profile: 'demo', org: 'demo-org', demoLabel: DEMO_LABEL, autoplay: 'Show me what you can do (demo)', onRestart: (r) => { restart = { ...r, conversationId: null }; }, restartCheck: checkRestart };
+  } else {
+    const cfgMod = await import('../core/config.js');
+    const { createAuth } = await import('../core/auth.js');
+    const { createClient } = await import('../core/client.js');
+    const { createApi } = await import('./api.js');
+    const probe = cfgMod.loadConfig();
+    const profiles = probe.listProfiles?.() || [];
+    const missing = opts.profile && !profiles.some(p => p.name === opts.profile);
+    const pick = pickProfile(opts.profile, cfgMod);
+    const config = missing ? probe : cfgMod.loadConfig(pick.name);
+    const auth = createAuth(config);
+    const client = createClient(config, auth);
+    const api = createApi({ client, config, auth });
+    const pname = missing ? opts.profile : (config.getActiveProfileName?.() || 'default');
+    const problem = chatCredentialProblem({ profileArg: opts.profile, profiles, hasStoredLogin: missing ? false : Boolean(config.getAuth?.()?.access_token), profileName: pname, serviceKeyFlag: opts.serviceKey });
+    // The health probe runs inside the app (background); the UI is up and typing works immediately.
+    const startup = async () => {
+      if (problem) return problem.message;
+      if (pick.note) return pick.note;
+      const hl = await api.health(8000);
+      return hl.ok ? null : hl.absent ? `No QuoxCORE running at ${hl.url}` : `QuoxCORE at ${hl.url} is not answering (${hl.status}); messages may be slow`;
+    };
+    const saved = api.settings();
+    applySettings(saved);
+    if (!opts.verboseSet && ['off', 'on', 'full'].includes(saved.verbose)) opts.verbose = saved.verbose;
+    props = { api, modelChoice: opts.provider, resume: opts.resume ?? null, onRestart: (r) => { restart = r; }, restartCheck: checkRestart, startSha: headOf(RUNNING_ROOT), rules: loadRules(), profile: pname, org: missing ? null : (config.getAuth?.()?.org_name || null), startup, blocked: problem ? problem.message : null, autoplay: replay };
+  }
+  // Interactive start: a clean screen under the intro (never when piped; NO_COLOR still clears),
+  // except straight after Getting started, whose finale must stay readable.
+  if (shouldClearBeforeChat({ isTTY: process.stdout.isTTY, noClear: opts.noClear, fromGettingStarted })) process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
+  const welcome = shouldShowWelcome({ print: opts.print });
+  if (welcome) markWelcomeSeen();
+  const transcript = opts.demo ? null : createTranscript({ meta: { version, cols: process.stdout.columns, rows: process.stdout.rows, profile: props.profile, org: props.org, cwd } });
+  const onResize = () => transcript?.resize(process.stdout.columns, process.stdout.rows);
+  if (transcript) process.stdout.on('resize', onResize);
+  const app = render(React.createElement(App, { ...props, welcome, version, cwd, verbose: opts.verbose, earlyInput: early, sessionName: opts.name, resumeConversation: opts.conversation || null, invite: Boolean(process.stdout.isTTY) && !opts.name, transcript }), inkRenderOptions(process.stdout));
+  try { await app.waitUntilExit(); transcript?.end(restart ? 'restart' : 'exit'); }
+  catch (e) { transcript?.end(`crash: ${e?.message || e}`); throw e; }
+  finally { process.stdout.off('resize', onResize); }
+  if (!restart) return;
+  // The app preflighted the installed quox before letting go, so a failure here is rare (it changed in between).
+  const r = execRestart({ argv, conversationId: restart.conversationId, profile: opts.demo ? null : props.profile, name: restart.name || opts.name || null, bin: restart.bin || undefined });
+  if (r.error) { process.stderr.write(`quox: could not restart (${r.bin}: ${r.error})${restart.conversationId ? `; resume with: quox --resume ${restart.conversationId}` : ''}\n`); process.exitCode = 1; return; }
+  process.exitCode = r.code;
+}
+
+async function mainPrint(opts) {
+  const { runPrint, resolvePrompt, EXIT } = await import('./print.js');
+  const out = (s) => process.stdout.write(s);
+  const err = (s) => process.stderr.write(s);
+  const prompt = await resolvePrompt(opts.prompt, process.stdin);
+  let api;
+  if (opts.demo) api = createDemoApi({ speed: 20 });
+  else {
+    const cfgMod = await import('../core/config.js');
+    const { createAuth } = await import('../core/auth.js');
+    const { createClient } = await import('../core/client.js');
+    const { createApi } = await import('./api.js');
+    const probe = cfgMod.loadConfig();
+    const profiles = probe.listProfiles?.() || [];
+    const missing = opts.profile && !profiles.some(p => p.name === opts.profile);
+    const pick = pickProfile(opts.profile, cfgMod);
+    if (pick.note) err(pick.note + '\n');
+    const config = missing ? probe : cfgMod.loadConfig(pick.name);
+    const auth = createAuth(config);
+    const pname = missing ? opts.profile : (config.getActiveProfileName?.() || 'default');
+    const problem = chatCredentialProblem({ profileArg: opts.profile, profiles, hasStoredLogin: missing ? false : Boolean(config.getAuth?.()?.access_token), profileName: pname, serviceKeyFlag: opts.serviceKey });
+    if (problem) {
+      const { NO_SERVER_PRINT } = await import('./onboarding/copy.js');
+      err(printAuthMessage(problem, await noServerConfigured(opts, cfgMod), NO_SERVER_PRINT));
+      process.exitCode = EXIT.auth; return;
+    }
+    api = createApi({ client: createClient(config, auth), config, auth });
+    if (opts.conversation && api.conversationExists) {
+      const c = await api.conversationExists(opts.conversation);
+      if (c.exists === false) { err(`quox: conversation not found: ${opts.conversation}\n`); process.exitCode = EXIT.error; return; }
+      if (c.exists === null) err(`quox: could not verify conversation ${opts.conversation} (${c.reason}); continuing\n`);
+    }
+  }
+  const rules = opts.demo ? null : loadRules();
+  for (const s of rules?.skipped || []) err(`quox: ignoring ${s.path}: ${s.reason}\n`);
+  const choice = opts.provider === 'auto' ? null : opts.provider || api.modelChoice?.() || null;
+  process.exitCode = await runPrint({ api, choice, promptProfile: opts.promptProfile, context: rulesContext(rules), prompt, output: opts.output, conversation: opts.conversation, turnId: opts.turnId || undefined, timeoutS: opts.timeout, color: opts.color, out, err });
+}

package/lib/quoxon/markdown.js

@@ -0,0 +1,317 @@
+/**
+ * Terminal markdown for QUOXON. `marked` supplies the LEXER only; every token is
+ * rendered by our own Ink components in the Quox style (no marked-terminal).
+ *
+ * Streaming contract:
+ *   splitSettled(text) -> { settled, rest }   settled = complete top-level blocks
+ *                                             (safe to move to <Static>), rest = the
+ *                                             unfinished tail (re-rendered live).
+ *   healInline(text)                          hides half-typed syntax in the live tail
+ *                                             (`**bo`, `` `co ``, `[txt](ht`).
+ *   An unclosed ``` fence is a single code token to the end of text, so it renders
+ *   as code while streaming and never as raw backticks.
+ */
+import React from 'react';
+import { Box, Text, Transform } from 'ink';
+import { Lexer } from 'marked';
+import { graphemes } from './textBuffer.js';
+import { c, mono, clip, gradient, bulletRole } from './theme.js';
+
+const h = React.createElement;
+
+export const lex = (src) => new Lexer({ gfm: true, breaks: false }).lex(src);
+
+export function splitSettled(text) {
+  const tokens = lex(text);
+  let last = -1;
+  for (let i = tokens.length - 1; i >= 0; i--) if (tokens[i].type !== 'space') { last = i; break; }
+  if (last <= 0) return { settled: '', rest: text };
+  let off = 0;
+  for (let i = 0; i < last; i++) off += tokens[i].raw.length;
+  return { settled: text.slice(0, off), rest: text.slice(off) };
+}
+
+export function healInline(text) {
+  let t = text;
+  const fence = (t.match(/^ {0,3}(```|~~~)/gm) || []).length;
+  if (fence % 2 === 1) return t; // inside an open fence: leave verbatim, it renders as code
+  const cut = (i) => { t = t.slice(0, i); };
+  const ticks = (t.match(/`/g) || []).length;
+  if (ticks % 2 === 1) cut(t.lastIndexOf('`'));
+  const bold = t.split('**').length - 1;
+  if (bold % 2 === 1) cut(t.lastIndexOf('**'));
+  const tilde = t.split('~~').length - 1;
+  if (tilde % 2 === 1) cut(t.lastIndexOf('~~'));
+  const lb = t.lastIndexOf('[');
+  if (lb >= 0 && !/\]\([^)]*\)/.test(t.slice(lb)) && /^\[[^\]]*(\]\(?[^)\s]*)?$/.test(t.slice(lb))) cut(lb);
+  return t;
+}
+
+// ---- wrapped text ------------------------------------------------------------------------------
+/**
+ * Ink wraps with wrap-ansi `trim: false`: when a row fills the width exactly, the space before the next
+ * word starts the continuation row (" AI agents."). Drop that one space on wrapped rows (index > 0),
+ * after any leading colour codes. Width is unchanged, so layout and row counts are unaffected.
+ */
+export const dropLeadSpace = (line, i) => (i > 0 ? line.replace(/^((?:\x1b\[[0-9;]*m)*) /, '$1') : line);
+/** <Text> whose wrapped continuation rows never start with a stray space. */
+export const WText = (props) => h(Transform, { transform: dropLeadSpace }, h(Text, props));
+
+// ---- hyperlinks (OSC 8) --------------------------------------------------------------------------
+export function supportsHyperlinks(env = process.env, isTTY = Boolean(process.stdout?.isTTY)) {
+  if (!isTTY || env.NO_COLOR || env.QUOX_HYPERLINKS === '0') return false;
+  if (env.QUOX_HYPERLINKS === '1') return true;
+  if (env.KITTY_WINDOW_ID || env.WT_SESSION) return true;
+  if (['iTerm.app', 'WezTerm', 'vscode', 'ghostty'].includes(env.TERM_PROGRAM)) return true;
+  return Number(env.VTE_VERSION) >= 5000;
+}
+const osc8 = (url, text) => `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+
+// ---- inline ----------------------------------------------------------------------------------
+export function inlineText(tokens = []) {
+  return tokens.map(t => {
+    if (t.tokens) return inlineText(t.tokens);
+    if (t.type === 'br') return ' ';
+    return t.text ?? t.raw ?? '';
+  }).join('').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+
+/** A heading word painted sky -> indigo -> violet, bold (plain bold under NO_COLOR). */
+export const Heading = ({ text, underline = false }) => h(Text, { bold: true, underline },
+  ...(mono() ? [String(text)] : gradient(text).map((g, i) => h(Text, { key: i, color: g.color }, g.ch))));
+
+/** Prose with numbers and quantities picked out in the number role. Characters unchanged. */
+const NUM = /(?<![\w.#/-])\d+(?:[.,:-]\d+)*(?:%|ms|s|k|m|h|d|x|KB|MB|GB)?(?!\w)/g;
+export function numberRuns(text, key = 'n') {
+  const s = String(text);
+  if (mono()) return [s];
+  const out = [];
+  let i = 0;
+  for (const m of s.matchAll(NUM)) {
+    if (m.index > i) out.push(s.slice(i, m.index));
+    out.push(h(Text, { key: `${key}#${m.index}`, color: c('number') }, m[0]));
+    i = m.index + m[0].length;
+  }
+  if (i < s.length) out.push(s.slice(i));
+  return out;
+}
+
+const unesc = (s) => String(s).replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+
+function inline(tokens = [], style = {}, key = 'i') {
+  return tokens.map((t, i) => {
+    const k = `${key}.${i}`;
+    switch (t.type) {
+      case 'strong': return h(Text, { key: k, bold: true, color: c('value') }, ...inline(t.tokens, style, k));
+      case 'em': return h(Text, { key: k, italic: true }, ...inline(t.tokens, style, k));
+      case 'del': return h(Text, { key: k, strikethrough: true }, ...inline(t.tokens, style, k));
+      case 'codespan': return mono()
+        ? h(Text, { key: k }, '`' + unesc(t.text) + '`')
+        : h(Text, { key: k, color: c('code'), backgroundColor: c('codeBg') }, ' ' + unesc(t.text) + ' ');
+      case 'br': return h(Text, { key: k }, '\n');
+      case 'link': {
+        const label = inlineText(t.tokens) || t.href;
+        const shown = supportsHyperlinks() ? osc8(t.href, label) : label;
+        return h(Text, { key: k }, h(Text, { color: c('sky'), underline: true }, shown),
+          label !== t.href ? h(Text, { color: c('muted') }, ` (${t.href})`) : null);
+      }
+      case 'image': return h(Text, { key: k, color: c('dim') }, `[image: ${t.text || t.href}]`);
+      case 'escape': return h(Text, { key: k }, t.text);
+      case 'html': return h(Text, { key: k, color: c('dim') }, t.text);
+      case 'text': return t.tokens ? h(Text, { key: k }, ...inline(t.tokens, style, k)) : h(Text, { key: k }, ...numberRuns(unesc(t.text), k));
+      default: return h(Text, { key: k }, unesc(t.text ?? t.raw ?? ''));
+    }
+  });
+}
+
+// ---- tables ----------------------------------------------------------------------------------
+const w = (s) => graphemes(s).length;
+const padTo = (s, n) => s + ' '.repeat(Math.max(0, n - w(s)));
+
+/** Plain-text table layout: returns { mode: 'grid'|'vertical', lines: [{ text, head? }] }. Pure, for tests. */
+export function layoutTable(header, rows, cols) {
+  const n = header.length;
+  const widths = header.map((hd, i) => Math.max(w(hd), ...rows.map(r => w(r[i] ?? '')), 1));
+  const total = widths.reduce((a, b) => a + b, 0) + 3 * (n - 1);
+  if (total <= cols) {
+    const line = (r) => r.map((cell, i) => padTo(cell ?? '', widths[i])).join(' │ ').replace(/\s+$/, '');
+    const rule = widths.map(x => '─'.repeat(x)).join('─┼─');
+    return { mode: 'grid', lines: [{ text: line(header), head: true }, { text: rule, rule: true }, ...rows.map(r => ({ text: line(r) }))] };
+  }
+  // too wide: vertical key: value, one block per row
+  const lines = [];
+  const keyW = Math.min(Math.max(...header.map(w)), Math.floor(cols / 3));
+  rows.forEach((r, ri) => {
+    if (ri) lines.push({ text: '' });
+    header.forEach((hd, i) => lines.push({ text: `${padTo(clip(hd, keyW), keyW)}  ${r[i] ?? ''}`, key: keyW }));
+  });
+  return { mode: 'vertical', lines };
+}
+
+function Table({ t, cols }) {
+  const header = t.header.map(x => inlineText(x.tokens));
+  const rows = t.rows.map(r => r.map(x => inlineText(x.tokens)));
+  const lay = layoutTable(header, rows, cols);
+  return h(Box, { flexDirection: 'column' }, ...lay.lines.map((l, i) => h(Text, {
+    key: i, bold: l.head, color: l.rule ? c('muted') : (l.head ? c('label') : undefined), wrap: 'truncate-end'
+  }, l.text || ' ')));
+}
+
+// ---- blocks ----------------------------------------------------------------------------------
+const rule = (cols, label) => {
+  if (!label) return '─'.repeat(cols);
+  const lead = `── ${label} `;
+  return lead + '─'.repeat(Math.max(0, cols - w(lead)));
+};
+
+/** Fenced code top rule: dim teal line, the language label in the icon role. Same characters as rule(). */
+function codeRule(cols, label) {
+  const line = rule(cols, label);
+  if (!label) return h(Text, { color: c('codeRule') }, line);
+  return h(Text, null, h(Text, { color: c('codeRule') }, '── '), h(Text, { color: c('icon') }, label), h(Text, { color: c('codeRule') }, line.slice(3 + label.length)));
+}
+
+function List({ t, cols, depth }) {
+  const start = typeof t.start === 'number' ? t.start : 1;
+  return h(Box, { flexDirection: 'column' }, ...t.items.map((it, i) => {
+    const marker = t.ordered ? `${start + i}.` : (depth % 2 ? '◦' : '•');
+    const mw = w(marker) + 1;
+    return h(Box, { key: i },
+      h(Box, { width: mw, flexShrink: 0 }, h(Text, { color: c(bulletRole(depth)) }, marker)),
+      h(Box, { flexDirection: 'column', flexGrow: 1, flexShrink: 1 }, ...blocks(it.tokens, cols - mw, depth + 1, `li${i}`)));
+  }));
+}
+
+function blocks(tokens = [], cols, depth = 0, key = 'b') {
+  const out = [];
+  tokens.forEach((t, i) => {
+    const k = `${key}.${i}`;
+    switch (t.type) {
+      case 'space': return;
+      case 'heading': {
+        out.push(h(Box, { key: k, marginTop: depth ? 0 : 1 }, h(Transform, { transform: dropLeadSpace }, h(Heading, { text: inlineStr(t.tokens), underline: t.depth === 1 && mono() }))));
+        return;
+      }
+      case 'paragraph': case 'text':
+        out.push(h(Box, { key: k }, h(WText, null, ...inline(t.tokens || [{ type: 'text', text: t.text }], {}, k))));
+        return;
+      case 'code': {
+        const lines = String(t.text).split('\n');
+        out.push(h(Box, { key: k, flexDirection: 'column', width: cols },
+          codeRule(cols, t.lang ? String(t.lang).split(/\s+/)[0] : ''),
+          ...lines.map((ln, j) => h(Text, { key: j, color: c('text') }, ln || ' ')),
+          h(Text, { color: c('codeRule') }, rule(cols))));
+        return;
+      }
+      case 'list': out.push(h(List, { key: k, t, cols, depth })); return;
+      case 'blockquote':
+        out.push(h(Box, { key: k },
+          h(Box, { width: 2, flexShrink: 0 }, h(Text, { color: c('label') }, '▎ ')),
+          h(Box, { flexDirection: 'column', flexGrow: 1, flexShrink: 1 }, ...blocks(t.tokens, cols - 2, depth + 1, k))));
+        return;
+      case 'hr': out.push(h(Text, { key: k, color: c('dim') }, '─'.repeat(cols))); return;
+      case 'table': out.push(h(Table, { key: k, t, cols })); return;
+      case 'html': out.push(h(Text, { key: k, color: c('dim') }, t.text.trim())); return;
+      case 'def': return;
+      default: out.push(h(Text, { key: k }, unesc(t.raw || '')));
+    }
+  });
+  return out;
+}
+
+/** Render markdown text. live = unfinished tail of a streaming answer. */
+export function Markdown({ text, cols, live = false }) {
+  const src = live ? healInline(text) : text;
+  if (!src.trim()) return null;
+  const kids = blocks(lex(src), cols).map((el, i) => h(Box, { key: el.key ?? i, marginTop: i ? 1 : 0, flexDirection: 'column' }, el));
+  return h(Box, { flexDirection: 'column', width: cols }, ...kids);
+}
+
+// ---- height (sizes the live region; must match what Ink lays out) ---------------------------------
+/** Rows one line takes in Ink's Text wrap (wrap-ansi 9, trim: false, hard: true), plain text only. */
+function wrapLineRows(line, cols) {
+  if (cols <= 0) return 1;
+  const words = line.split(' ');
+  const rows = [0];
+  words.forEach((word, i) => {
+    let len = rows[rows.length - 1];
+    const wl = w(word);
+    if (i !== 0) {
+      if (len >= cols) { rows.push(0); len = 0; }
+      rows[rows.length - 1] = ++len;
+    }
+    if (wl > cols) { // hard-break a word longer than the line
+      const remaining = cols - len;
+      const startHere = 1 + Math.floor((wl - remaining - 1) / cols);
+      const startNext = Math.floor((wl - 1) / cols);
+      if (startNext < startHere) rows.push(0);
+      let vis = rows[rows.length - 1];
+      const chars = graphemes(word);
+      chars.forEach((_, k) => {
+        if (vis + 1 <= cols) rows[rows.length - 1] = ++vis;
+        else { rows.push(1); vis = 1; }
+        if (vis === cols && k < chars.length - 1) { rows.push(0); vis = 0; }
+      });
+      if (!vis && rows.length > 1 && rows[rows.length - 1] === 0) rows.pop();
+      return;
+    }
+    if (len + wl > cols && len > 0 && wl > 0) { rows.push(0); len = 0; }
+    rows[rows.length - 1] = len + wl;
+  });
+  return rows.length;
+}
+
+/** Rows a plain string takes when Ink wraps it at `cols`. */
+export function wrapRows(text, cols) {
+  return String(text).replace(/\r\n/g, '\n').split('\n').reduce((n, l) => n + wrapLineRows(l, cols), 0);
+}
+
+function inlineStr(tokens = []) {
+  return tokens.map(t => {
+    switch (t.type) {
+      case 'strong': case 'em': case 'del': return inlineStr(t.tokens);
+      case 'codespan': return mono() ? '`' + unesc(t.text) + '`' : ' ' + unesc(t.text) + ' ';
+      case 'br': return '\n';
+      case 'link': { const label = inlineText(t.tokens) || t.href; return label + (label !== t.href ? ` (${t.href})` : ''); }
+      case 'image': return `[image: ${t.text || t.href}]`;
+      case 'escape': case 'html': return t.text;
+      case 'text': return t.tokens ? inlineStr(t.tokens) : unesc(t.text);
+      default: return unesc(t.text ?? t.raw ?? '');
+    }
+  }).join('');
+}
+
+/** Heights of the elements blocks() would produce, in order (space/def produce none). */
+function blockRows(tokens = [], cols, depth = 0) {
+  const out = [];
+  for (const t of tokens) {
+    switch (t.type) {
+      case 'space': case 'def': break;
+      case 'heading': out.push(wrapRows(inlineStr(t.tokens), cols) + (depth ? 0 : 1)); break;
+      case 'paragraph': case 'text': out.push(wrapRows(inlineStr(t.tokens || [{ type: 'text', text: t.text }]), cols)); break;
+      case 'code': out.push(2 + String(t.text).split('\n').reduce((n, ln) => n + wrapRows(ln || ' ', cols), 0)); break;
+      case 'list': {
+        out.push(t.items.reduce((n, it, i) => {
+          const marker = t.ordered ? `${(typeof t.start === 'number' ? t.start : 1) + i}.` : '•';
+          const inner = blockRows(it.tokens, cols - (w(marker) + 1), depth + 1).reduce((a, b) => a + b, 0);
+          return n + Math.max(1, inner);
+        }, 0));
+        break;
+      }
+      case 'blockquote': out.push(Math.max(1, blockRows(t.tokens, cols - 2, depth + 1).reduce((a, b) => a + b, 0))); break;
+      case 'hr': out.push(1); break;
+      case 'table': out.push(layoutTable(t.header.map(x => inlineText(x.tokens)), t.rows.map(r => r.map(x => inlineText(x.tokens))), cols).lines.length); break;
+      case 'html': out.push(wrapRows(t.text.trim(), cols)); break;
+      default: out.push(wrapRows(unesc(t.raw || ''), cols));
+    }
+  }
+  return out;
+}
+
+/** Rows <Markdown text cols live/> occupies. Pure; mirrors Markdown() above. */
+export function markdownRows(text, cols, live = false) {
+  const src = live ? healInline(text) : text;
+  if (!src.trim()) return 0;
+  const rows = blockRows(lex(src), cols);
+  return rows.reduce((a, b) => a + b, 0) + Math.max(0, rows.length - 1);
+}