@north-light/crouter 0.3.213 → 0.3.215

package/dist/clients/attach/chrome/inbox-strip.js

@@ -0,0 +1,187 @@
+// chrome/inbox-strip.ts — the pending-request strip pinned at the top of the
+// pane, below the recap goal line.
+//
+// One row per pending human ticket raised by THIS node or any node in its
+// subtree (self + descendants, convo children excluded), newest first. A
+// dedicated binding moves the highlight up into it (roster-style — no real
+// focus steal); ↑/↓ and j/k move, Enter opens the ticket's page inline in the
+// cockpit (chrome/ticket-panel.ts), Esc / ↓ off the bottom / typing returns to
+// the editor. Zero pending → zero rows, invisible.
+//
+// The strip owns the SUBTREE ticket scan and caches it: the viewer's inbox
+// surface merges `pendingTickets()` into its own scan so an Enter-opened
+// child ticket is present in the surface it seats.
+import { Container, Text, decodeKittyPrintable, matchesKey } from '@earendil-works/pi-tui';
+import { DynamicBorder } from '@earendil-works/pi-coding-agent';
+import { scanInbox, scanPageHistory } from '../../../core/human/scan.js';
+import { fillBar, fillWidth, navLabel, stripSgr, truncate, REVERSE, YELLOW, RESET } from '../../../core/canvas/nav-render.js';
+/** Ticket rows shown at once; the window follows the selection. */
+const MAX_ROWS = 3;
+function ticketTime(t) {
+    return t.kind === 'page' ? t.emittedAt : t.blockedSince;
+}
+function ageLabel(iso) {
+    const ms = Date.now() - Date.parse(iso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return 'now';
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return 'now';
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+export function createInboxStrip(s, hooks) {
+    const { nodeId, remote, canvasSource, tui, pal } = s;
+    const component = new Container();
+    let tickets = [];
+    let nodes = new Map();
+    let selDir; // undefined ⇒ strip inactive (editor owns the cursor)
+    let top = 0; // first visible ticket row
+    const rowLine = (t) => {
+        const origin = t.source.nodeId;
+        const from = origin !== undefined && origin !== nodeId
+            ? ` · ${navLabel(nodes.get(origin) ?? null, origin)}`
+            : '';
+        return truncate(` ${YELLOW}⚑${RESET} ${t.title}${pal.faint(` · ${ageLabel(ticketTime(t))}${from}`)}`);
+    };
+    const paint = () => {
+        hooks.syncCursor();
+        component.clear();
+        if (tickets.length > 0 && !hooks.suppressed()) {
+            const i = selDir === undefined ? -1 : tickets.findIndex((t) => t.dir === selDir);
+            if (i >= 0)
+                top = Math.min(Math.max(top, i - MAX_ROWS + 1), i);
+            top = Math.max(0, Math.min(top, Math.max(0, tickets.length - MAX_ROWS)));
+            for (const t of tickets.slice(top, top + MAX_ROWS)) {
+                const line = rowLine(t);
+                component.addChild(new Text(t.dir === selDir ? fillBar(stripSgr(line), fillWidth(), REVERSE) : line, 1, 0));
+            }
+            const hidden = tickets.length - Math.min(MAX_ROWS, tickets.length - top);
+            if (hidden > 0)
+                component.addChild(new Text(pal.faint(`   +${hidden} more`), 1, 0));
+            component.addChild(new DynamicBorder(pal.border));
+        }
+        tui.requestRender();
+    };
+    /** Self + descendants through subscriptions, skipping convo (human-kind) children. */
+    const subtreeNodes = async () => {
+        const out = new Map();
+        const visit = async (id) => {
+            if (out.has(id))
+                return;
+            const meta = await canvasSource.getNode(id).catch(() => null);
+            if (id !== nodeId && meta?.kind === 'human')
+                return;
+            out.set(id, meta);
+            const refs = await canvasSource.subscriptionsOf(id).catch(() => []);
+            for (const ref of refs)
+                await visit(ref.node_id);
+        };
+        await visit(nodeId);
+        return out;
+    };
+    const refresh = async () => {
+        if (remote)
+            return; // a remote attach cannot read this canvas's ticket dirs
+        nodes = await subtreeNodes();
+        // Same pending merge the inbox surface does — inbox-projected tickets plus
+        // reply-bearing no-inbox pages — but for every subtree node, then scoped to
+        // tickets whose origin is in the subtree.
+        const merged = new Map();
+        for (const item of scanInbox())
+            merged.set(item.dir, item);
+        for (const id of nodes.keys()) {
+            for (const page of scanPageHistory(id)) {
+                if (page.state !== 'pending' || !page.awaitsResponse || page.inbox)
+                    continue;
+                if (!merged.has(page.dir))
+                    merged.set(page.dir, page);
+            }
+        }
+        tickets = [...merged.values()]
+            .filter((t) => t.source.nodeId !== undefined && nodes.has(t.source.nodeId))
+            .sort((a, b) => ticketTime(b).localeCompare(ticketTime(a)) || a.id.localeCompare(b.id));
+        // The selected row may have vanished (answered, canceled) — drop back to
+        // the editor so no ghost highlight lingers.
+        if (selDir !== undefined && !tickets.some((t) => t.dir === selDir))
+            selDir = undefined;
+        paint();
+    };
+    const exit = () => {
+        if (selDir !== undefined) {
+            selDir = undefined;
+            paint();
+        }
+    };
+    const toggle = () => {
+        if (remote)
+            return;
+        if (selDir !== undefined) {
+            exit();
+            return;
+        }
+        if (tickets.length === 0) {
+            hooks.setNotice('No pending human requests in this subtree');
+            return;
+        }
+        hooks.exitRoster();
+        selDir = tickets[0].dir;
+        top = 0;
+        paint();
+    };
+    const openSelected = () => {
+        const ticket = tickets.find((t) => t.dir === selDir);
+        if (ticket === undefined)
+            return;
+        exit();
+        hooks.openTicket(ticket);
+    };
+    const handleKey = (data) => {
+        if (selDir === undefined)
+            return false;
+        const i = tickets.findIndex((t) => t.dir === selDir);
+        // j/k are printable nav keys here, like the graph and browse lists — decode
+        // them so they move the highlight instead of falling to the typed-key exit.
+        const ch = decodeKittyPrintable(data) ?? (data.length === 1 ? data : undefined);
+        if (matchesKey(data, 'up') || ch === 'k') {
+            if (i > 0) {
+                selDir = tickets[i - 1].dir;
+                paint();
+            }
+            return true;
+        }
+        if (matchesKey(data, 'down') || ch === 'j') {
+            if (i >= 0 && i < tickets.length - 1) {
+                selDir = tickets[i + 1].dir;
+                paint();
+            }
+            else
+                exit(); // ↓ off the bottom returns to the editor
+            return true;
+        }
+        if (matchesKey(data, 'enter')) {
+            openSelected();
+            return true;
+        }
+        if (matchesKey(data, 'escape')) {
+            exit();
+            return true;
+        }
+        // Any other key (the user started typing) returns to the editor AND passes
+        // through, so the keystroke lands in the input.
+        exit();
+        return false;
+    };
+    return {
+        component,
+        refresh,
+        handleKey,
+        toggle,
+        active: () => selDir !== undefined,
+        pendingTickets: () => [...tickets],
+    };
+}

package/dist/clients/attach/chrome/roster.d.ts

@@ -19,6 +19,8 @@ export interface RosterHooks {
      *  the cron wait row routes to `schedule` and the bash row to `jobs`; the
      *  native Inspector owns details for both. */
     openInspector: (section: 'overview' | 'schedule' | 'jobs') => void;
+    /** Recompute the editor's hollow-cursor state (session/pane-focus.ts). */
+    syncCursor: () => void;
 }
 export interface AttachRoster {
     /** Rebuild the rows from the canvas source, reconcile the selection, repaint. */
@@ -26,7 +28,9 @@ export interface AttachRoster {
     /** Roster key routing, called BEFORE the editor sees the key. Returns true
      *  when the roster consumed it (the editor must not see it). */
     handleKey(data: string): boolean;
-    /** Report real tmux-pane focus (DECSET 1004). Repaints the editor cursor. */
-    setPaneFocused(focused: boolean): void;
+    /** True while the roster holds the highlight. */
+    active(): boolean;
+    /** Drop the highlight back to the editor (the inbox strip activating). */
+    exit(): void;
 }
 export declare function createRoster(s: RosterSession, hooks: RosterHooks): AttachRoster;

package/dist/clients/attach/chrome/roster.js

@@ -4,53 +4,31 @@
 // editor's visual bottom drops the cursor into the list; within it ↑/↓ move the
 // highlight, ↑ off the TOP row returns to the editor, ↓ CLAMPS at the bottom,
 // Enter opens the row (SWAPS this pane in place onto a node, or opens the wait
-// detail surface for a human/cron/bash row: a human row opens the inbox, a cron
-// row the Inspector's schedule section, a bash row the Inspector's jobs section,
-// a review row the review's companion viewer),
+// detail surface for a cron/bash/review row: a cron row the Inspector's
+// schedule section, a bash row the Inspector's jobs section, a review row the
+// review's companion viewer),
 // Esc / any typed key returns to the editor. Disabled entirely for a REMOTE
 // attach: a remote graph id has no local pane to swap into and no local
 // jobs/crons to inspect.
 //
-// TWO EDITOR COUPLINGS ARE OWNED HERE, deliberately and exclusively:
-//   • `editor.onCursorDownAtBottom` — the boundary handoff. The editor owns
-//     native ↓ navigation and calls this only after both its visual cursor and
-//     its prompt history are exhausted, which makes the handoff a direct
-//     boundary transition rather than a global-listener replay.
-//   • `editor.paneFocused` — the hollow-cursor state. The cursor is dimmed
-//     whenever the tmux pane is blurred OR the roster holds the cursor: while
-//     scrolling the list the editor is "away", so it must read exactly like an
-//     unfocused pane. The viewer feeds pane focus in through `setPaneFocused`;
-//     the roster half of that conjunction is private to this module.
+// ONE EDITOR COUPLING IS OWNED HERE, deliberately and exclusively:
+// `editor.onCursorDownAtBottom` — the boundary handoff. The editor owns native
+// ↓ navigation and calls this only after both its visual cursor and its prompt
+// history are exhausted, which makes the handoff a direct boundary transition
+// rather than a global-listener replay. The hollow-cursor state lives in
+// session/pane-focus.ts; the roster reports its held highlight through
+// `active()` and pokes `hooks.syncCursor` on every repaint.
 //
 // Repainting a selection is purely local: canvas reads can traverse the whole
 // graph, so `refresh()` rebuilds the cached rows asynchronously while arrow
 // movement only reverses the selected cached row and renders immediately.
-import { execFile, execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { Text, decodeKittyPrintable, matchesKey } from '@earendil-works/pi-tui';
 import { cliClient } from '../../../commands/api-client.js';
 import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
 import { contextDir } from '../../../core/canvas/paths.js';
 import { fillBar, fillWidth, stripSgr, REVERSE } from '../../../core/canvas/nav-render.js';
 import { buildCanvasPanelLines } from './canvas-panels.js';
-/** Seed pane focus from the pane's REAL active state, not an unconditional
- *  `true`. tmux only emits DECSET 1004 focus events on a TRANSITION, so a viewer
- *  spawned into a non-active pane (a `split -d` beside another node — the
- *  auto-viewer for a background child) starts unfocused and NEVER receives a
- *  FOCUS_OUT, leaving a solid cursor drawn until the user swaps in and back out.
- *  Query `#{pane_active}` for our own pane once at startup so an unfocused split
- *  renders hollow immediately; default true when not in tmux or the query fails. */
-function initialPaneActive() {
-    const pane = process.env['TMUX_PANE'];
-    if (pane === undefined || pane === '')
-        return true;
-    try {
-        const out = execFileSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_active}'], { encoding: 'utf8' }).trim();
-        return out !== '0';
-    }
-    catch {
-        return true;
-    }
-}
 /** How long an armed `x` waits for its `y`. */
 const ARM_TIMEOUT_MS = 15_000;
 export function createRoster(s, hooks) {
@@ -63,18 +41,14 @@ export function createRoster(s, hooks) {
     let autoSelect = process.env['CRTR_ATTACH_ROSTER'];
     if (autoSelect !== undefined)
         delete process.env['CRTR_ATTACH_ROSTER'];
-    let paneFocused = initialPaneActive();
     // Armed job cancellation: `x` on the bash row names the job, `y` confirms.
     // Held here (not in the item list) so any other key, a selection move, or a
     // rebuild that retires the job drops it — a stale confirmation must never
     // kill a job the user is no longer looking at.
     let pendingKill;
     let killTimer;
-    const syncCursorDim = () => {
-        editor.paneFocused = paneFocused && selKey === undefined;
-    };
     const paint = () => {
-        syncCursorDim();
+        hooks.syncCursor();
         reports.clear();
         for (const item of items) {
             const selected = item.key === selKey;
@@ -191,15 +165,6 @@ export function createRoster(s, hooks) {
         const item = items.find((candidate) => candidate.key === selKey);
         if (item === undefined || remote)
             return;
-        if (item.kind === 'human') {
-            if (role !== 'controller') {
-                hooks.setNotice('Read-only observer attach — cannot open the human inbox');
-                return;
-            }
-            exit();
-            execFile('hl', ['inbox', 'open'], () => { });
-            return;
-        }
         if (item.kind === 'crons') {
             exit();
             hooks.openInspector('schedule');
@@ -306,9 +271,5 @@ export function createRoster(s, hooks) {
         exit();
         return false;
     };
-    const setPaneFocused = (focused) => {
-        paneFocused = focused;
-        syncCursorDim();
-    };
-    return { refresh, handleKey, setPaneFocused };
+    return { refresh, handleKey, active: () => selKey !== undefined, exit };
 }

package/dist/clients/attach/chrome/ticket-panel.d.ts

@@ -0,0 +1,29 @@
+import type { Component } from '@earendil-works/pi-tui';
+import type { TicketSummary } from '../../../core/human/types.js';
+import type { AttachSession } from '../session/context.js';
+export type PanelSession = Pick<AttachSession, 'tui' | 'pal'>;
+export interface TicketPanelHooks {
+    /** Recompute the editor's hollow-cursor state (session/pane-focus.ts). */
+    syncCursor: () => void;
+    /** Repaint the strip — its rows hide while the panel is their expansion. */
+    refreshStrip: () => void;
+    setNotice: (msg: string) => void;
+    /** Fallback: the full-pane inbox surface seated on this ticket dir. */
+    openInbox: (dir: string) => void;
+    /** Release the terminal to $EDITOR for the comment roundtrip. */
+    suspendForChild: () => () => void;
+}
+export interface TicketPanel {
+    /** Mounted once into the frame's `ticketPanel` slot; empty while closed. */
+    readonly component: Component;
+    /** Open a ticket's page inline; review/unreadable tickets fall back. */
+    open(ticket: TicketSummary): void;
+    /** Panel key routing — consumes EVERY chunk while open. */
+    handleKey(data: string): boolean;
+    close(): void;
+    /** True while a page is open (the editor's cursor hollows). */
+    active(): boolean;
+    /** The open ticket's dir, for escalating to the full inbox surface. */
+    currentDir(): string | undefined;
+}
+export declare function createTicketPanel(s: PanelSession, hooks: TicketPanelHooks): TicketPanel;

package/dist/clients/attach/chrome/ticket-panel.js

@@ -0,0 +1,236 @@
+// chrome/ticket-panel.ts — the inline ticket page at the top of the pane.
+//
+// Enter on an inbox-strip row opens the ticket's page HERE, directly beneath
+// the recap header where the strip's notification row sat — the row expands
+// into the full page. It takes only the rows the page needs, growing all the
+// way down to the cockpit for a tall page (the transcript compresses to zero
+// before the editor gives a row), instead of the full-pane inbox surface.
+// While open it owns every keystroke — pages carry text inputs — so the
+// global key listener routes chunks to `handleKey` ahead of the strip and
+// roster; Esc at the page top closes back to the editor.
+//
+// The claim lifecycle mirrors the inbox surface's detail screen: claim on
+// open, heartbeat every 10s, watch the ticket dir (page.json → reload, other
+// activity → close if resolved elsewhere), resolve through the daemon on
+// complete, release on close. Review tickets and unreadable pages fall back
+// to the full-pane inbox seated on the row.
+import { watch } from 'node:fs';
+import { claimTicket, heartbeatClaim, releaseClaim } from '../../../core/human/claim.js';
+import { readPageTicket, readTicketResult } from '../../../core/human/tickets.js';
+import { resolvePageComponents } from '../../../core/config.js';
+import { fillBar, stripSgr, truncate, REVERSE } from '../../../core/canvas/nav-render.js';
+import { visibleWidth } from '../../inbox/tui/ansi.js';
+import { PageAdapter } from '../../inbox/page-adapter.js';
+import { decodeInboxKey } from '../../inbox/tui/keys.js';
+import { daemonErrorMessage, resolveFailureKind, resolveTicketPage } from '../../inbox/resolve.js';
+import { editBufferInEditor } from '../../inbox/review/roundtrip.js';
+export function createTicketPanel(s, hooks) {
+    const { tui, pal } = s;
+    let session;
+    let submitting = false;
+    let lastCols = 0;
+    let lastRows = 0;
+    /** Content rows offered to the page: everything but the recap header and the
+     *  cockpit's minimum (activity · padding · editor · status) plus our own
+     *  title bar and closing rule. The frame clips to the rows actually free. */
+    const capRows = () => Math.max(3, tui.terminal.rows - 10);
+    const closeSession = (release) => {
+        const open = session;
+        if (open === undefined)
+            return;
+        session = undefined;
+        clearInterval(open.heartbeat);
+        open.watcher?.close();
+        open.adapter.close();
+        if (release)
+            releaseClaim(open.dir, open.token);
+        hooks.syncCursor();
+        hooks.refreshStrip();
+        tui.requestRender();
+    };
+    const complete = async (open, responses) => {
+        submitting = true;
+        try {
+            await resolveTicketPage(open.dir, responses);
+            closeSession(false);
+            hooks.setNotice('Response sent');
+        }
+        catch (error) {
+            const failure = resolveFailureKind(error);
+            if (failure === 'unreachable' || failure === 'other') {
+                hooks.setNotice(daemonErrorMessage(error));
+                return; // keep the page open — nothing was submitted
+            }
+            closeSession(false);
+            hooks.setNotice(failure === 'already_resolved' ? resolvedElsewhereNotice(open.dir) : daemonErrorMessage(error));
+        }
+        finally {
+            submitting = false;
+        }
+    };
+    const reload = (open) => {
+        try {
+            open.adapter.reload(readPageTicket(open.dir));
+        }
+        catch {
+            hooks.setNotice('Page could not be read');
+        }
+    };
+    const editPageInput = (open) => {
+        const buffer = open.adapter.inputBuffer();
+        if (buffer === undefined)
+            return;
+        const resume = hooks.suspendForChild();
+        let result = { text: buffer };
+        try {
+            result = editBufferInEditor(buffer);
+        }
+        finally {
+            resume();
+            open.adapter.setInputBuffer(result.text);
+            if (result.error !== undefined)
+                hooks.setNotice(result.error);
+            tui.requestRender();
+        }
+    };
+    const open = (ticket) => {
+        if (session !== undefined)
+            closeSession(true);
+        if (ticket.kind !== 'page') {
+            hooks.openInbox(ticket.dir);
+            return;
+        }
+        const claim = claimTicket(ticket.dir);
+        if (claim === null) {
+            hooks.setNotice('Ticket is being edited by another inbox');
+            return;
+        }
+        let loaded;
+        try {
+            loaded = readPageTicket(ticket.dir);
+        }
+        catch {
+            releaseClaim(ticket.dir, claim.token);
+            hooks.openInbox(ticket.dir);
+            return;
+        }
+        lastCols = Math.max(20, tui.terminal.columns - 2);
+        lastRows = capRows();
+        const entry = {
+            dir: ticket.dir,
+            title: ticket.title,
+            token: claim.token,
+            adapter: new PageAdapter({
+                dir: ticket.dir,
+                ticket: loaded,
+                productKinds: resolvePageComponents(),
+                cols: lastCols,
+                rows: lastRows,
+                onDirty: () => tui.requestRender(),
+                onBack: () => closeSession(true),
+                onComplete: (responses) => { void complete(entry, responses); },
+                onEditorRequest: () => editPageInput(entry),
+            }),
+            watcher: undefined,
+            heartbeat: setInterval(() => {
+                if (session === entry)
+                    heartbeatClaim(entry.dir, entry.token);
+            }, 10_000),
+        };
+        try {
+            entry.watcher = watch(ticket.dir, (_event, file) => {
+                if (session !== entry || submitting)
+                    return;
+                if (file === 'page.json') {
+                    reload(entry);
+                    return;
+                }
+                const result = readTicketResult(entry.dir);
+                if (result !== null) {
+                    closeSession(true);
+                    hooks.setNotice(result.kind === 'canceled' ? 'Ticket was canceled by its requester' : 'Ticket was resolved elsewhere');
+                }
+            });
+        }
+        catch {
+            entry.watcher = undefined;
+        }
+        session = entry;
+        hooks.syncCursor();
+        hooks.refreshStrip();
+        tui.requestRender();
+    };
+    const handleKey = (data) => {
+        const entry = session;
+        if (entry === undefined)
+            return false;
+        const { input, key } = decodeInboxKey(data);
+        entry.adapter.handleKey(input, key);
+        tui.requestRender();
+        return true;
+    };
+    const component = {
+        render(width) {
+            const entry = session;
+            if (entry === undefined)
+                return [];
+            const cols = Math.max(20, width - 2);
+            const rows = capRows();
+            if (cols !== lastCols || rows !== lastRows) {
+                lastCols = cols;
+                lastRows = rows;
+                entry.adapter.resize(cols, rows);
+            }
+            // The strip row's highlight carries into the open page: the same
+            // reversed full-width bar, now a title bar, with a closing rule beneath
+            // the content so the page reads as one bounded region over the chat.
+            const header = fillBar(stripSgr(truncate(` ⚑ ${entry.title} · Esc closes`, width)), width, REVERSE);
+            // The body sits on the same background the crouter context cards use, so
+            // the open ticket reads as one solid panel distinct from the chat.
+            const bg = contextCardBg();
+            const body = trimTrailingBlank(entry.adapter.render()).map((line) => paintBg(` ${line}`, width, bg));
+            return [header, ...body, pal.border('─'.repeat(Math.max(0, width)))];
+        },
+        invalidate() { },
+    };
+    return {
+        component,
+        open,
+        handleKey,
+        close: () => closeSession(true),
+        active: () => session !== undefined,
+        currentDir: () => session?.dir,
+    };
+}
+function resolvedElsewhereNotice(dir) {
+    return readTicketResult(dir)?.kind === 'canceled' ? 'Ticket was already canceled' : 'Ticket was already resolved';
+}
+/** The SGR opening the theme's `customMessageBg` — the background the crouter
+ *  context cards use. pi shares its live theme across module loaders on this
+ *  well-known global (it exports no direct handle); a missing or incomplete
+ *  theme just means no fill, never a throw. */
+function contextCardBg() {
+    const t = globalThis[Symbol.for('@earendil-works/pi-coding-agent:theme')];
+    try {
+        return t?.getBgAnsi?.('customMessageBg');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fill one row with `bg` edge to edge, re-asserting it across the line's own
+ *  full resets and background resets so interior styling cannot punch holes. */
+function paintBg(line, width, bg) {
+    if (bg === undefined)
+        return line;
+    const kept = line.replaceAll('\x1b[0m', `\x1b[0m${bg}`).replaceAll('\x1b[49m', bg);
+    const pad = ' '.repeat(Math.max(0, width - visibleWidth(line)));
+    return `${bg}${kept}${pad}\x1b[49m`;
+}
+/** Short pages take only their rows: the adapter pads to its rectangle. */
+function trimTrailingBlank(lines) {
+    let end = lines.length;
+    while (end > 0 && stripSgr(lines[end - 1]).trim() === '')
+        end--;
+    return lines.slice(0, end);
+}

package/dist/clients/attach/render/card-presentation.d.ts

@@ -1,6 +1,8 @@
 import { type GeneratedCard } from '../../../shared/generated-context.js';
 /** What the one global detail toggle reveals for this kind.
- *  `section` names an element in the body; everything outside it stays folded. */
+ *  `section` names an element in the body; everything outside it stays folded.
+ *  `render` builds Markdown from the parsed card, for a body whose raw markup
+ *  is not what a person should read. */
 export type CardExpandedPolicy = {
     readonly disclose: 'never';
 } | {
@@ -8,6 +10,9 @@ export type CardExpandedPolicy = {
 } | {
     readonly disclose: 'section';
     readonly section: string;
+} | {
+    readonly disclose: 'render';
+    readonly render: (card: GeneratedCard) => string;
 };
 /** What is left of the card once its turn folds into one recap line. A boundary
  *  kind never reaches this field — `isGroupBoundaryKind` removes it from the
@@ -24,8 +29,8 @@ export interface CardPresentation {
 export declare function cardLabel(subject: string): string;
 /** The disclosure a card actually offers, given its policy and body. A kind
  *  whose section is missing from an old transcript offers nothing to expand. */
-export declare function cardDisclosure(presentation: CardPresentation, body: string): string;
-export declare function cardIsExpandable(presentation: CardPresentation, body: string): boolean;
+export declare function cardDisclosure(presentation: CardPresentation, card: GeneratedCard): string;
+export declare function cardIsExpandable(presentation: CardPresentation, card: GeneratedCard): boolean;
 /** The one lookup. Every display surface deciding how a card behaves resolves it
  *  here, so row, disclosure, and recap can never disagree about a kind. */
 export declare function presentationFor(kind: string): CardPresentation;