@north-light/crouter 0.3.170 → 0.3.171

package/dist/core/termrender/termrender.js

@@ -0,0 +1,795 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, statSync, mkdirSync, openSync, closeSync, unlinkSync, renameSync, accessSync, realpathSync, constants, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import stringWidth from 'string-width';
+import { TERMRENDER_VERSION } from './version.js';
+// ── The sole org-wide termrender binding ─────────────────────────────────────
+//
+// termrender is crouter's sole org-wide renderer binding: a pure-Python tool
+// pinned to TERMRENDER_VERSION and installed into a venv crouter owns. The binary is
+// resolved by ABSOLUTE PATH inside that venv — never `$PATH` — so a user's
+// own `pip install termrender` can never shadow or break the pin.
+const RENDERER_CACHE_DIR = join(resolve(process.env.XDG_CACHE_HOME || join(homedir(), '.cache')), 'crouter', 'termrender', TERMRENDER_VERSION);
+const VENV_DIR = join(RENDERER_CACHE_DIR, 'venv');
+const VENV_BIN = join(VENV_DIR, 'bin/termrender');
+const VENV_PYTHON = join(VENV_DIR, 'bin/python');
+// Readiness marker written by the single authoritative provisioning transition
+// after a verified install. It fingerprints the ACTUAL verified environment —
+// launcher + interpreter (mtime, size, mode) and the interpreter's realpath —
+// so steady-state validation is a handful of cheap fs stats (no subprocess),
+// yet a stripped exec bit, a swapped venv Python, or a rewritten launcher all
+// invalidate it. Deeper corruption an fs stat can't see (e.g. mangled
+// site-packages under an unchanged launcher) is caught by the other half of
+// the contract: any `ready` invocation that fails to RUN invalidates this
+// marker (see invalidateRenderer), so the next process repairs. Together these
+// remove the ~149ms `termrender -h` + `importlib.metadata` spawn tax from the
+// steady path without letting a stale marker trust a broken renderer forever.
+const VENV_STAMP = join(VENV_DIR, '.crtr-termrender-stamp.json');
+// Provisioning lock — lives OUTSIDE .venv (which `uv venv --clear` wipes) so it
+// survives a reinstall. The user cache stays writable when crouter is installed
+// in a read-only runtime image, and serializes venv mutation + stamp publication
+// across processes: a stamp can never certify a concurrently-changing venv.
+const VENV_LOCK = join(RENDERER_CACHE_DIR, '.crtr-termrender.lock');
+// A lock older than this is from a crashed process and may be stolen. Set
+// comfortably above the worst-case held path (uv probe 5s + venv 60s + install
+// 120s + re-verify ~10s ≈ 195s) so a slow-but-alive holder is never judged
+// stale while it still holds.
+const LOCK_STALE_MS = 300_000;
+// Absolute cap on how long a waiter spins before giving up to plaintext for
+// this session (the next launch retries) — a safety valve so a wedged holder
+// can never hang a process, WITHOUT ever stealing a lock we can't prove stale.
+const LOCK_GIVE_UP_MS = LOCK_STALE_MS + 60_000;
+let rendererState = 'unchecked';
+function isFp(x) {
+    const e = x;
+    return !!e && typeof e.mtimeMs === 'number' && typeof e.size === 'number' && typeof e.mode === 'number';
+}
+function fingerprint(path) {
+    try {
+        const s = statSync(path);
+        return { mtimeMs: s.mtimeMs, size: s.size, mode: s.mode };
+    }
+    catch {
+        return null;
+    }
+}
+function fpMatch(a, b) {
+    return !!a && a.mtimeMs === b.mtimeMs && a.size === b.size && a.mode === b.mode;
+}
+function readStamp() {
+    try {
+        const p = JSON.parse(readFileSync(VENV_STAMP, 'utf8'));
+        if (p && typeof p.version === 'string' && isFp(p.bin) && isFp(p.python) && typeof p.pythonRealpath === 'string') {
+            return p;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Publish the readiness marker for the state we just verified. Failure to
+// persist is surfaced explicitly (not swallowed): the renderer works for THIS
+// process, but every future launch re-verifies the slow way until the marker
+// can be written — the operator should know why launches stay slow.
+function publishStamp() {
+    const bin = fingerprint(VENV_BIN);
+    const python = fingerprint(VENV_PYTHON);
+    if (!bin || !python) {
+        process.stderr.write('[crtr] termrender stamp skipped: venv files vanished immediately after verify\n');
+        return;
+    }
+    let pythonRealpath;
+    try {
+        pythonRealpath = realpathSync(VENV_PYTHON);
+    }
+    catch {
+        pythonRealpath = VENV_PYTHON;
+    }
+    const stamp = { version: TERMRENDER_VERSION, bin, python, pythonRealpath };
+    // Atomic publish: write a temp then rename, so a crash mid-write can't leave
+    // a half-written stamp and a concurrent reader never observes a torn file.
+    const tmp = `${VENV_STAMP}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(stamp));
+        renameSync(tmp, VENV_STAMP);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* nothing to clean up */ }
+        process.stderr.write(`[crtr] termrender ready but stamp not persisted (${err instanceof Error ? err.message : String(err)}); ` +
+            'future launches will re-verify the slow way\n');
+    }
+}
+// Invalidate the readiness marker when a supposedly-ready renderer misbehaves
+// in a way that implicates the environment (spawn fault, or a `doc render`
+// failure — render is best-effort by contract, so ANY failure means the tool,
+// not the input, is broken; this catches site-packages corruption an fs stat
+// can't see). Removes the on-disk marker so the next process repairs, and
+// downgrades THIS process to plaintext to avoid retry thrash within the session.
+function invalidateRenderer(reason) {
+    let removed = true;
+    try {
+        unlinkSync(VENV_STAMP);
+    }
+    catch (err) {
+        // ENOENT means it's already gone (still invalidated); any other error means
+        // the marker SURVIVES and will keep certifying — say so honestly rather
+        // than promising a repair that can't happen until the file is removable.
+        if (err.code !== 'ENOENT')
+            removed = false;
+    }
+    rendererState = 'unavailable';
+    if (removed) {
+        process.stderr.write(`[crtr] termrender invocation failed (${reason}); invalidated readiness, future launches will repair\n`);
+    }
+    else {
+        process.stderr.write(`[crtr] termrender invocation failed (${reason}) but its readiness marker could not be removed; ` +
+            `future launches may keep trusting a broken renderer until ${VENV_STAMP} is deleted\n`);
+    }
+}
+// True when a spawn was killed by its own timeout rather than failing to run —
+// usually a slow/large document, not a broken environment. Excluded from
+// invalidation so a reliably-slow render can't oscillate a healthy renderer
+// (invalidate → slow re-verify → re-stamp) every session.
+function isTimeout(err) {
+    const e = err;
+    return e?.code === 'ETIMEDOUT' || (!!e?.killed && !!e?.signal);
+}
+// Cheap steady-state trust — all fs stats, no subprocess. The pinned launcher
+// is present, executable, and byte-for-byte the one the stamp verified; the
+// interpreter it targets is the same file at the same realpath. Any of these
+// drifting (version bump, stripped exec bit, rewritten launcher, swapped venv
+// Python) forces the authoritative re-provision transition.
+function stampValid() {
+    const stamp = readStamp();
+    if (!stamp || stamp.version !== TERMRENDER_VERSION)
+        return false;
+    try {
+        accessSync(VENV_BIN, constants.X_OK);
+    }
+    catch {
+        return false;
+    }
+    if (!fpMatch(fingerprint(VENV_BIN), stamp.bin))
+        return false;
+    if (!fpMatch(fingerprint(VENV_PYTHON), stamp.python))
+        return false;
+    try {
+        if (realpathSync(VENV_PYTHON) !== stamp.pythonRealpath)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function lockIsStale() {
+    try {
+        const at = JSON.parse(readFileSync(VENV_LOCK, 'utf8')).at;
+        if (typeof at === 'number')
+            return Date.now() - at > LOCK_STALE_MS;
+    }
+    catch {
+        // Unreadable/malformed lock — fall through to mtime.
+    }
+    try {
+        return Date.now() - statSync(VENV_LOCK).mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return true; // vanished — the retry loop re-acquires
+    }
+}
+// Run `provision` while holding the exclusive provisioning lock. If another
+// live process holds it, wait for that process to publish (re-checking the
+// stamp) rather than mutating the venv concurrently. Stale locks are stolen.
+// Steal a lock judged stale by renaming it to a unique name first: rename is
+// atomic, so if two waiters race only the one whose rename succeeds owns (and
+// deletes) it — the loser gets ENOENT and re-loops. This can never delete a
+// lock a peer has freshly re-acquired (that peer holds a DIFFERENT inode at the
+// same path; our rename of the old name either already happened or fails).
+function stealStaleLock() {
+    const tmp = `${VENV_LOCK}.steal.${process.pid}.${Date.now()}`;
+    try {
+        renameSync(VENV_LOCK, tmp);
+    }
+    catch {
+        return; // lost the steal race or already gone — caller re-loops
+    }
+    try {
+        unlinkSync(tmp);
+    }
+    catch { /* best effort */ }
+}
+function withProvisionLock(provision) {
+    try {
+        mkdirSync(RENDERER_CACHE_DIR, { recursive: true });
+    }
+    catch (err) {
+        rendererState = 'unavailable';
+        process.stderr.write(`[crtr] termrender unavailable — renderer cache cannot be created (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+        return;
+    }
+    const giveUpAt = Date.now() + LOCK_GIVE_UP_MS;
+    for (;;) {
+        let fd;
+        try {
+            fd = openSync(VENV_LOCK, 'wx'); // O_CREAT | O_EXCL — atomic acquire
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST') {
+                rendererState = 'unavailable';
+                process.stderr.write(`[crtr] termrender unavailable — renderer cache cannot be locked (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+                return;
+            }
+            if (lockIsStale()) {
+                stealStaleLock();
+                continue;
+            }
+            // A live process is provisioning — give it a chance, then adopt its result.
+            // Never steal a lock we can't prove stale; if we wait too long, give up to
+            // plaintext this session rather than break mutual exclusion.
+            if (Date.now() > giveUpAt) {
+                rendererState = 'unavailable';
+                return;
+            }
+            sleepSync(200);
+            if (stampValid()) {
+                rendererState = 'ready';
+                return;
+            }
+            continue;
+        }
+        try {
+            writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+        }
+        catch { /* lock held regardless of whether the marker body wrote */ }
+        try {
+            provision();
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch { /* already closed */ }
+            try {
+                unlinkSync(VENV_LOCK);
+            }
+            catch { /* stolen as stale by another process */ }
+        }
+        return;
+    }
+}
+function binaryOk() {
+    if (!existsSync(VENV_BIN))
+        return false;
+    try {
+        // v2 contract: no --version flag; use -h (exit 0) as a liveness check.
+        execFileSync(VENV_BIN, ['-h'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Returns the termrender version installed in the managed venv (via
+// importlib.metadata), or null if the venv is missing/broken or termrender is
+// not installed. Used by ensureRenderer() to detect drift from the pin and
+// trigger a reinstall — otherwise a venv provisioned at an older pin sticks
+// forever (binaryOk passes for any working binary, regardless of version).
+function installedVersion() {
+    if (!existsSync(VENV_PYTHON))
+        return null;
+    try {
+        const out = execFileSync(VENV_PYTHON, ['-c', 'import importlib.metadata as m; print(m.version("termrender"))'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function uvAvailable() {
+    try {
+        execFileSync('uv', ['--version'], { stdio: 'pipe', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
+ *
+ * Invoked at postinstall AND lazily on the first render/check/display call,
+ * so `npm ci --ignore-scripts` consumers still self-heal on first use.
+ */
+export function ensureRenderer() {
+    if (rendererState !== 'unchecked')
+        return;
+    if (process.platform === 'win32') {
+        rendererState = 'unavailable';
+        return;
+    }
+    // Steady state: trust the stamp — zero subprocess spawns.
+    if (stampValid()) {
+        rendererState = 'ready';
+        return;
+    }
+    // No/invalid stamp → the single authoritative transition, serialized so no
+    // two processes mutate the venv (or certify it) concurrently.
+    provisionAndPublish();
+}
+// The one invalid-stamp transition. Under the exclusive lock: adopt a stamp a
+// racing process just published; else verify the current venv (a healthy venv
+// with no/stale stamp — an interrupted publish, or a peer
+// that finished the venv but not the stamp — needs only re-verification, not a
+// reinstall); reinstall via `uv` only when genuinely missing/drifted; then
+// verify and publish. Every success path ends by publishing the stamp.
+function provisionAndPublish() {
+    withProvisionLock(() => {
+        // A peer may have published between our unlocked stampValid() in
+        // ensureRenderer and our acquiring the lock here — adopt it, don't reinstall.
+        if (stampValid()) {
+            rendererState = 'ready';
+            return;
+        }
+        let verified = binaryOk() && installedVersion() === TERMRENDER_VERSION;
+        if (!verified) {
+            if (!uvAvailable()) {
+                process.stderr.write('[crtr] termrender unavailable — install uv to enable rich rendering:\n' +
+                    '  curl -LsSf https://astral.sh/uv/install.sh | sh\n');
+                rendererState = 'unavailable';
+                return;
+            }
+            try {
+                // (Re)create the venv whenever the interpreter is missing — covers both
+                // "directory absent" and "directory present but bin/python stripped"
+                // (seen when pnpm rebuilds/dedupes node_modules or uv rotates its
+                // managed Python store). `--clear` wipes any partial state rather than
+                // refusing on the existing dir. Intact interpreter → reuse the venv.
+                if (!existsSync(VENV_PYTHON)) {
+                    execFileSync('uv', ['venv', '--clear', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+                }
+                // `--reinstall` forces uv to rebuild the package and rewrite its entry
+                // point even when the pinned version already appears satisfied — so this
+                // path actually REPAIRS a corrupt-but-present install (the case that
+                // drove us here via invalidation), not just a clean version drift.
+                execFileSync('uv', ['pip', 'install', '--reinstall', '--python', VENV_PYTHON, `termrender==${TERMRENDER_VERSION}`], { stdio: 'pipe', timeout: 120000 });
+            }
+            catch (err) {
+                process.stderr.write(`[crtr] termrender install failed (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+                rendererState = 'unavailable';
+                return;
+            }
+            verified = binaryOk() && installedVersion() === TERMRENDER_VERSION;
+        }
+        if (!verified) {
+            rendererState = 'unavailable';
+            process.stderr.write('[crtr] termrender install completed but health check failed; using plaintext fallback\n');
+            return;
+        }
+        publishStamp();
+        rendererState = 'ready';
+    });
+}
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
+export function isRendererReady() {
+    if (rendererState === 'ready')
+        return true;
+    if (rendererState === 'unavailable')
+        return false;
+    return process.platform !== 'win32' && stampValid();
+}
+// ── Plaintext fallback helpers (kept here so this is the only termrender site) ─
+const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
+function sanitize(text) {
+    if (typeof text !== 'string')
+        return '';
+    return text.replace(CONTROL_CHARS_RE, '');
+}
+function sliceByWidth(s, maxWidth) {
+    let w = 0;
+    let out = '';
+    for (const ch of s) {
+        const cw = stringWidth(ch);
+        if (w + cw > maxWidth)
+            break;
+        out += ch;
+        w += cw;
+    }
+    if (out === '' && s.length > 0)
+        out = [...s][0];
+    return out;
+}
+function wrap(text, maxWidth) {
+    if (maxWidth < 1)
+        return [text];
+    const out = [];
+    const paragraphs = text.split('\n');
+    for (let p = 0; p < paragraphs.length; p++) {
+        const para = paragraphs[p];
+        if (para === '') {
+            out.push('');
+            continue;
+        }
+        const words = para.split(/[ \t]+/).filter(Boolean);
+        let current = '';
+        for (let word of words) {
+            while (stringWidth(word) > maxWidth) {
+                if (current) {
+                    out.push(current);
+                    current = '';
+                }
+                const piece = sliceByWidth(word, maxWidth);
+                out.push(piece);
+                word = word.slice(piece.length);
+            }
+            const candidate = current ? `${current} ${word}` : word;
+            if (stringWidth(candidate) <= maxWidth) {
+                current = candidate;
+            }
+            else {
+                if (current)
+                    out.push(current);
+                current = word;
+            }
+        }
+        if (current)
+            out.push(current);
+    }
+    return out.length > 0 ? out : [''];
+}
+// ── Render surface ───────────────────────────────────────────────────────────
+const _bodyCache = new Map();
+/** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
+export function renderMarkdown(md, width) {
+    const key = `${md}\0${width}`;
+    const cached = _bodyCache.get(key);
+    if (cached)
+        return cached;
+    ensureRenderer();
+    if (rendererState === 'ready') {
+        try {
+            const out = execFileSync(VENV_BIN, ['doc', 'render', '--width', String(width), '--color', 'on'], {
+                input: md,
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const lines = out.split('\n');
+            if (lines.length > 0 && lines[lines.length - 1] === '')
+                lines.pop();
+            _bodyCache.set(key, lines);
+            return lines;
+        }
+        catch (err) {
+            // `doc render` is best-effort, so a non-timeout failure implicates the
+            // tool, not the markdown: invalidate so the next process repairs. A
+            // timeout is a slow/large doc, not corruption — just fall to plaintext.
+            if (!isTimeout(err))
+                invalidateRenderer('doc render');
+        }
+    }
+    const fallback = wrap(sanitize(md), width);
+    _bodyCache.set(key, fallback);
+    return fallback;
+}
+/** Block types allowed to use the full pane width instead of the prose cap:
+ *  a diagram is a picture, not prose, so a readability column limit only
+ *  shrinks it below what the pane could show. */
+const WIDE_BLOCK_TYPES = new Set(['mermaid']);
+/** Validate + normalize `doc render --line-map` JSON into a RenderedDoc.
+ *  Null block bounds (a scanner edge case) are filled from neighbors and
+ *  clamped into the source range; an empty block list gets one whole-doc
+ *  block so callers can always anchor. Malformed shape → null (tool fault). */
+function parseRenderedDoc(out, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        return null;
+    }
+    const p = parsed;
+    if (!Array.isArray(p.lines) || !Array.isArray(p.rows) || !Array.isArray(p.spans) || !Array.isArray(p.blocks))
+        return null;
+    if (p.rows.length !== p.lines.length || p.spans.length !== p.lines.length)
+        return null;
+    if (!p.lines.every((l) => typeof l === 'string'))
+        return null;
+    const blockCount = p.blocks.length;
+    if (!p.rows.every((r) => r === null || (typeof r === 'number' && Number.isInteger(r) && r >= 0 && r < blockCount)))
+        return null;
+    const totalSource = Math.max(1, source.split('\n').length);
+    const blocks = [];
+    let prevEnd = 0;
+    for (const raw of p.blocks) {
+        if (typeof raw !== 'object' || raw === null)
+            return null;
+        // The block type is what lets callers render diagrams differently from
+        // prose; a map without it cannot drive block-aware rendering at all.
+        if (typeof raw.type !== 'string' || raw.type === '')
+            return null;
+        // Bounds are integers or null — a fractional bound would otherwise flow
+        // into a recorded comment's line/endLine instead of tripping tool-fault.
+        if (raw.start != null && !Number.isInteger(raw.start))
+            return null;
+        if (raw.end != null && !Number.isInteger(raw.end))
+            return null;
+        const start = typeof raw.start === 'number' ? raw.start : prevEnd + 1;
+        const end = typeof raw.end === 'number' ? Math.max(raw.end, start) : start;
+        const s = Math.max(1, Math.min(start, totalSource));
+        const e = Math.max(s, Math.min(end, totalSource));
+        blocks.push({ type: raw.type, start: s, end: e });
+        prevEnd = e;
+    }
+    if (blocks.length === 0)
+        blocks.push({ type: 'paragraph', start: 1, end: totalSource });
+    const spans = [];
+    for (let r = 0; r < p.spans.length; r++) {
+        const raw = p.spans[r];
+        if (raw === null) {
+            spans.push(null);
+            continue;
+        }
+        // Same strictness as rows: a span is [start, end], 1-indexed inclusive
+        // integers in order, inside the source — these values flow straight into
+        // a recorded comment's line/endLine, so an out-of-range endpoint is tool
+        // fault to reject, never something to clamp into the wrong line.
+        if (!Array.isArray(raw) || raw.length !== 2)
+            return null;
+        const [s, e] = raw;
+        if (!Number.isInteger(s) || !Number.isInteger(e))
+            return null;
+        if (s < 1 || e < s || e > totalSource)
+            return null;
+        // Relational contract: a separator row (rows[r] === null) carries no
+        // span, and a leaf span stays inside its owning block's source range. A
+        // map that disagrees with its own rows/blocks would let a comment on a
+        // visible row record against unrelated source text.
+        const rowBlock = p.rows[r];
+        if (rowBlock === null)
+            return null;
+        const owner = blocks[rowBlock];
+        if (s < owner.start || e > owner.end)
+            return null;
+        spans.push([s, e]);
+    }
+    return { lines: p.lines, rows: p.rows, spans, blocks };
+}
+/** Renderer-free mapped render: group consecutive non-blank source lines into
+ *  paragraph blocks and word-wrap each — the same shape as the termrender map,
+ *  with degraded (plaintext) rendering. Each source line is wrapped on its own
+ *  and spans exactly itself, so leaf anchoring degrades to true line-by-line. */
+function fallbackDocWithMap(md, width) {
+    const src = sanitize(md).split('\n');
+    const blocks = [];
+    let openAt = null;
+    for (let i = 0; i < src.length; i++) {
+        if (src[i].trim() !== '') {
+            if (openAt === null)
+                openAt = i;
+        }
+        else if (openAt !== null) {
+            blocks.push({ type: 'paragraph', start: openAt + 1, end: i });
+            openAt = null;
+        }
+    }
+    if (openAt !== null)
+        blocks.push({ type: 'paragraph', start: openAt + 1, end: src.length });
+    if (blocks.length === 0)
+        blocks.push({ type: 'paragraph', start: 1, end: Math.max(1, src.length) });
+    const lines = [];
+    const rows = [];
+    const spans = [];
+    blocks.forEach((b, bi) => {
+        if (bi > 0) {
+            lines.push('');
+            rows.push(null);
+            spans.push(null);
+        }
+        // wrap() treats each '\n'-separated line as its own paragraph, so wrapping
+        // line-by-line emits the exact rows the joined-block wrap produced.
+        for (let ln = b.start; ln <= b.end; ln++) {
+            for (const l of wrap(src[ln - 1] ?? '', width)) {
+                lines.push(l);
+                rows.push(bi);
+                spans.push([ln, ln]);
+            }
+        }
+    });
+    return { lines, rows, spans, blocks };
+}
+const _mapCache = new Map();
+/** Render markdown with a row→source-line map via the pinned binary
+ *  (`doc render --line-map`); plaintext paragraph-block fallback. */
+export function renderMarkdownWithMap(md, width) {
+    const key = `${md}\0${width}`;
+    const cached = _mapCache.get(key);
+    if (cached)
+        return cached;
+    ensureRenderer();
+    if (rendererState === 'ready') {
+        try {
+            const out = execFileSync(VENV_BIN, ['doc', 'render', '--width', String(width), '--color', 'on', '--line-map'], {
+                input: md,
+                encoding: 'utf-8',
+                timeout: 5000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                // JSON-escaped ANSI inflates well past execFileSync's 1MB default.
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            const doc = parseRenderedDoc(out.trim(), md);
+            if (doc !== null) {
+                _mapCache.set(key, doc);
+                return doc;
+            }
+            // A working renderer never emits a malformed map — tool fault.
+            invalidateRenderer('doc render --line-map (malformed output)');
+        }
+        catch (err) {
+            // Same contract as renderMarkdown: non-timeout failure implicates the
+            // tool; a timeout is a slow/large doc — just fall to the local map.
+            if (!isTimeout(err))
+                invalidateRenderer('doc render --line-map');
+        }
+    }
+    // The fallback is cheap to recompute and deliberately NOT cached: a
+    // transient failure (e.g. a timeout) must not pin degraded block anchoring
+    // for the rest of the session when a later re-render could succeed.
+    return fallbackDocWithMap(md, width);
+}
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export function renderMarkdownBlockAware(md, proseWidth, paneWidth) {
+    const base = renderMarkdownWithMap(md, proseWidth);
+    if (paneWidth <= proseWidth)
+        return base;
+    if (!base.blocks.some((b) => WIDE_BLOCK_TYPES.has(b.type)))
+        return base;
+    const wide = renderMarkdownWithMap(md, paneWidth);
+    // Same source, so the two renders describe the same top-level blocks. A
+    // disagreement means one of the two maps is degraded (renderer failure mid
+    // session) — render the narrow one rather than splice mismatched rows.
+    if (wide.blocks.length !== base.blocks.length)
+        return base;
+    const lines = [];
+    const rows = [];
+    const spans = [];
+    for (let r = 0; r < base.lines.length; r++) {
+        const bi = base.rows[r] ?? null;
+        if (bi === null || !WIDE_BLOCK_TYPES.has(base.blocks[bi].type)) {
+            lines.push(base.lines[r]);
+            rows.push(bi);
+            spans.push(base.spans[r] ?? null);
+            continue;
+        }
+        // First row of this block's run: emit the wide render's rows for the same
+        // block, then skip the narrow run (a block's rows are contiguous).
+        if (r === 0 || base.rows[r - 1] !== bi) {
+            for (let q = 0; q < wide.lines.length; q++) {
+                if (wide.rows[q] !== bi)
+                    continue;
+                lines.push(wide.lines[q]);
+                rows.push(bi);
+                spans.push(wide.spans[q] ?? null);
+            }
+        }
+    }
+    return { lines, rows, spans, blocks: base.blocks };
+}
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export function renderMarkdownBlockAwareLines(md, proseWidth, paneWidth) {
+    return renderMarkdownBlockAware(md, proseWidth, paneWidth).lines;
+}
+/** Validate markdown via `termrender doc check`. */
+export function checkMarkdown(md) {
+    ensureRenderer();
+    // Renderer unavailable → don't block validation; the body just renders as
+    // plaintext later. Bricking deck validation here would be the wrong default.
+    if (rendererState !== 'ready')
+        return { ok: true };
+    const result = spawnSync(VENV_BIN, ['doc', 'check'], {
+        input: md,
+        encoding: 'utf-8',
+        timeout: 5000,
+    });
+    if (result.error) {
+        // A timeout (slow doc) is not an environment fault; anything else is a
+        // spawn fault → invalidate so the next process repairs.
+        const timedOut = result.error.code === 'ETIMEDOUT' || result.signal === 'SIGTERM';
+        if (!timedOut)
+            invalidateRenderer('doc check');
+        return { ok: false, error: `termrender: invocation failed: ${result.error.message}` };
+    }
+    let parsed = null;
+    const rawStdout = typeof result.stdout === 'string' ? result.stdout : '';
+    if (rawStdout) {
+        try {
+            parsed = JSON.parse(rawStdout.trim());
+        }
+        catch {
+            // stdout not parseable — fall through to exit-code handling
+        }
+    }
+    if (parsed !== null) {
+        if (parsed.ok)
+            return { ok: true };
+        const first = Array.isArray(parsed.errors) ? parsed.errors[0] : undefined;
+        const msg = (first && typeof first.message === 'string' && first.message) ? first.message : 'invalid markdown';
+        return { ok: false, error: `termrender: ${msg}` };
+    }
+    // exit code 2 = invalid per contract; any non-zero is an error
+    if (result.status !== 0) {
+        return { ok: false, error: `termrender: doc check exited ${result.status}` };
+    }
+    return { ok: true };
+}
+/**
+ * Spawn termrender into a live tmux pane. The pane-budget policy (whether to
+ * split vs open a new window) is decided by the caller (`src/surfaces/
+ * display.ts`); this is the thin managed-binary spawn it delegates to.
+ */
+export function displayInPane(path, opts = {}) {
+    ensureRenderer();
+    if (rendererState !== 'ready')
+        return {};
+    // Always watch: a displayed pane is a live view of the file by definition.
+    const args = ['pane', 'open', path, '--watch'];
+    args.push('--window', opts.newWindow ? 'new' : 'split');
+    const result = spawnSync(VENV_BIN, args, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // A spawn fault (binary broke) invalidates readiness; a non-zero exit (e.g.
+    // tmux refused, bad path) is not an environment fault and must not.
+    if (result.error) {
+        invalidateRenderer('pane open');
+        return {};
+    }
+    if (result.status !== 0)
+        return {};
+    // `encoding: 'utf-8'` makes spawnSync return stdout as a string.
+    const rawStdout = result.stdout;
+    if (!rawStdout)
+        return {};
+    let parsed = null;
+    try {
+        parsed = JSON.parse(rawStdout.trim());
+    }
+    catch {
+        return {};
+    }
+    if (parsed && typeof parsed.pane_id === 'string' && parsed.pane_id) {
+        return { paneId: parsed.pane_id };
+    }
+    return {};
+}