@iseoane/agent-depot 0.6.13 → 0.6.15

package/dist/src/tui/package-actions.js

@@ -1,10 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { quoteText } from "../preview-model.js";
 import { displayPackageSelection } from "../package-model.js";
 import { errorText } from "./batch.js";
+import { isYes } from "./keys.js";
 import { movePreviewCursor } from "./mode-keys.js";
 import { installedEvidenceLabel, packagePlanLines } from "./package-rows.js";
-import { PreviewConfirm } from "./panel-parts.js";
-import { previewViewport } from "./preview-window.js";
+import { PagedPreview } from "./panel-parts.js";
+import { usePreviewGeometry } from "./preview-window.js";
 import { busy } from "./working-model.js";
 /** The per-row keys of a Package; Enter is approval, handled beside these. */
 export const PACKAGE_ACTION_KEYS = new Map([
@@ -58,7 +60,7 @@ export async function startPackageAction(context, target, input) {
                 manage.setMode({ kind: "package-confirm", plan, approval, cursor: 0 });
             return;
         }
-        await manage.finish({ kind: "error", text: `The action ${JSON.stringify(input)} is not available for Packages` });
+        await manage.finish({ kind: "error", text: `The action ${quoteText(input)} is not available for Packages` });
     }
     catch (error) {
         await manage.finish({ kind: "error", text: errorText(error) });
@@ -132,28 +134,32 @@ function packagePreview(mode) {
         case "package-approve":
             return {
                 lines: mode.lines,
-                chrome: reviewChrome("Package approval", `Approve this install declaration for ${mode.target.name}? y/n`),
+                chrome: { title: "Package approval", action: "Approve the install declaration",
+                    consequence: `Approve this install declaration for ${mode.target.name}? y/n` },
             };
         case "package-forget":
             return {
                 lines: mode.lines,
-                chrome: reviewChrome("Forget Package selection", `Forget the selection record of ${mode.target.name}? y/n`),
+                chrome: { title: "Forget Package selection", action: "Forget the selection record",
+                    consequence: `Forget the selection record of ${mode.target.name}? y/n` },
             };
-        case "package-confirm":
+        case "package-confirm": {
+            const { action, descriptor } = mode.plan;
+            const needsApproval = mode.approval === "needs approval";
             return {
                 lines: packagePlanLines(mode.plan, mode.approval),
-                chrome: reviewChrome(`Package ${mode.plan.action} confirmation`, mode.approval === "needs approval"
-                    ? "Approve this declaration and continue? y/n"
-                    : `${mode.plan.action} ${mode.plan.descriptor.name}? y/n`),
+                chrome: {
+                    title: `Package ${action} confirmation`,
+                    action: needsApproval ? `Approve and ${action} ${descriptor.name}` : `${action[0].toUpperCase()}${action.slice(1)} ${descriptor.name}`,
+                    consequence: needsApproval ? "Approve this declaration and continue? y/n" : `${action} ${descriptor.name}? y/n`,
+                },
             };
+        }
     }
 }
-function reviewChrome(title, question) {
-    return { title, questions: [question], footerRows: 2 };
-}
 /**
- * Pages the declaration with the arrows, PgUp/PgDn and j/k. `y` answers from any page: the panel shows
- * the `Review N of M` position and the row window while more remains. `n` and Esc run nothing.
+ * Pages the declaration with the arrows, PgUp/PgDn and j/k. `y` answers only once the whole declaration
+ * has been displayed. `n` and Esc run nothing.
  */
 export function handlePackageKey(context, mode, input, key) {
     const { manage, packages } = context;
@@ -162,7 +168,7 @@ export function handlePackageKey(context, mode, input, key) {
         manage.browse();
     };
     const { lines, chrome } = packagePreview(mode);
-    const viewport = previewViewport(lines, mode.cursor, context.terminalRows, context.terminalColumns, chrome);
+    const viewport = context.previewGeometry(lines, mode.cursor, chrome);
     const cursor = movePreviewCursor(mode.cursor, viewport.total, input, key, viewport.height);
     if (cursor !== undefined) {
         manage.setMode({ ...mode, cursor });
@@ -172,7 +178,7 @@ export function handlePackageKey(context, mode, input, key) {
         cancel("Package action cancelled");
         return;
     }
-    if (input !== "y")
+    if (!isYes(input, key) || !viewport.reachedEnd)
         return;
     switch (mode.kind) {
         case "package-approve":
@@ -190,8 +196,9 @@ export function handlePackageKey(context, mode, input, key) {
             return;
     }
 }
-/** Renders a Package prompt with the existing preview panel and y/n confirmation. */
+/** Renders a Package prompt with the shared paged preview. */
 export function PackagePanel({ mode }) {
     const { lines, chrome } = packagePreview(mode);
-    return _jsx(PreviewConfirm, { title: chrome.title, lines: lines, cursor: mode.cursor, question: chrome.questions[0], chrome: chrome });
+    const viewport = usePreviewGeometry()(lines, mode.cursor, chrome);
+    return _jsx(PagedPreview, { lines: lines, viewport: viewport });
 }

package/dist/src/tui/package-rows.js

@@ -1,10 +1,11 @@
 import { classifyUpdate } from "../package-host-plans.js";
+import { quoteText } from "../preview-model.js";
 import { displayPackageCoordinates, displayPackageSelection, } from "../package-model.js";
 /** Version evidence as a short label; `unknown` when the host or the bundle states none. */
 export function packageVersionLabel(evidence, commit) {
     if (evidence === undefined)
         return "unknown";
-    return evidence.kind === "manifest-version" ? versionWithCommit(evidence.version, commit) : evidence.commit.slice(0, 7);
+    return evidence.kind === "manifest-version" ? versionWithCommit(evidence.version, commit) : `commit ${evidence.commit.slice(0, 7)}`;
 }
 function versionWithCommit(version, commit) {
     return `${version}${commit === undefined ? "" : ` (${commit.slice(0, 7)})`}`;
@@ -46,9 +47,13 @@ export function recordedVersionLabel(record) {
     if (record.verified !== undefined)
         return packageVersionLabel(record.verified);
     if (record.lastDelegatedCommit !== undefined)
-        return record.lastDelegatedCommit.slice(0, 7);
+        return `commit ${record.lastDelegatedCommit.slice(0, 7)}`;
     return "unknown";
 }
+/** The version the host reports when it states one, else what the selection record remembers. */
+export function installedVersionLabel({ installed, observed }) {
+    return observed?.kind === "installed" && observed.version !== undefined ? observed.version : recordedVersionLabel(installed);
+}
 export function packageRow(record, inspection) {
     return {
         selection: record.selection,
@@ -57,7 +62,7 @@ export function packageRow(record, inspection) {
         ...(inspection.installed.kind === "installed" && inspection.installed.version !== undefined
             ? { installedVersion: versionWithCommit(inspection.installed.version, inspection.installed.commit) }
             : inspection.installed.kind === "installed" && inspection.installed.commit !== undefined
-                ? { installedVersion: inspection.installed.commit.slice(0, 7) }
+                ? { installedVersion: `commit ${inspection.installed.commit.slice(0, 7)}` }
                 : {}),
         available: packageVersionLabel(inspection.available, inspection.availableCommit),
         status: packageRowStatus(record.selection, inspection),
@@ -98,7 +103,7 @@ export function packagePlanLines(plan, approval) {
         ...(plan.commands.length === 0
             ? ["This action runs no host command."]
             : plan.commands.flatMap((command, position) => [
-                `Step ${position + 1} (${command.purpose}): ${JSON.stringify([command.executable, ...command.args])}`,
+                `Step ${position + 1} (${command.purpose}): [${[command.executable, ...command.args].map(quoteText).join(",")}]`,
                 `Executable: ${command.resolvedPath ?? command.executable}`,
             ])),
         `Blast radius: ${plan.affects.map((coordinates) => displayPackageCoordinates(selection.source, coordinates)).join(", ")}`,

package/dist/src/tui/panel-parts.js

@@ -1,12 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { Box, Text, useWindowSize } from "ink";
+import { Box } from "ink";
+import { PreEscapedText, Text } from "./safe-text.js";
 import { useEffect, useState } from "react";
 import { theme } from "./theme.js";
-import { previewViewport } from "./preview-window.js";
+import { escapeControlText, sliceSpans } from "./preview-window.js";
 import { animationEnabled, formatElapsed, SPINNER_FRAMES, SPINNER_TICK_MS, STATIC_GLYPH } from "./working-model.js";
 /** A titled, color-independent boundary for a focused interaction or result. */
 export function BorderPanel({ title, children }) {
-    return (_jsxs(Box, { borderStyle: "round", borderColor: theme.border, paddingX: 1, flexDirection: "column", children: [_jsx(Text, { color: theme.title, bold: true, children: title }), children] }));
+    return (_jsxs(Box, { borderStyle: "round", borderColor: theme.border, paddingX: 1, flexDirection: "column", children: [typeof title === "string"
+                ? _jsx(Text, { color: theme.title, bold: true, children: title })
+                : title.map((row, position) => _jsx(PreEscapedText, { color: theme.title, bold: true, wrap: "truncate", children: row }, position)), children] }));
 }
 export function FieldLine({ label, value }) {
     return _jsxs(Text, { children: [_jsx(Text, { color: theme.field, children: label }), _jsxs(Text, { color: theme.value, children: [" ", value] })] });
@@ -40,7 +43,6 @@ export function ChecklistLines({ choices, cursor, isSelected, keyOf, label }) {
 export function HostChecklist({ choices, cursor, selected }) {
     return _jsx(ChecklistLines, { choices: choices, cursor: cursor, isSelected: (host) => selected.includes(host), keyOf: (host) => host, label: (host) => host });
 }
-/** Preview lines; `warnFirst` colors the first one as a warning. */
 const PREVIEW_FIELD_LABELS = [
     "File:", "Name:", "Platform:", "Status:", "Homepage:", "Owned Skills:",
     "App:", "Environment:", "Version:", "argv:", "Executable:", "Manual:",
@@ -106,51 +108,66 @@ function profilePreviewSpans(line) {
             previewSpan(` ${hosts[2]}`, theme.version)];
     return undefined;
 }
-function visiblePreviewSpans(spans, offset, length) {
-    const end = offset + length;
-    let spanStart = 0;
-    const visible = [];
-    for (const span of spans) {
-        const spanEnd = spanStart + span.text.length;
-        const start = Math.max(offset, spanStart);
-        const stop = Math.min(end, spanEnd);
-        if (start < stop)
-            visible.push({ ...span, text: span.text.slice(start - spanStart, stop - spanStart) });
-        spanStart = spanEnd;
-    }
-    return visible;
+/** The colour of a warning, host exposure notice or refusal, which the flows indent to different depths. */
+function noticeColor(line) {
+    const text = line.trimStart();
+    if (text.startsWith("WARNING:") || text.startsWith("ADDITIONAL HOST EXPOSURE:") || text.startsWith("Skipped "))
+        return theme.warning;
+    return text.startsWith("Cannot install ") ? theme.error : undefined;
+}
+/** The hanging prefix of a continuation row, drawn in the gutter colour, then the part of the line's spans the row shows. */
+function rowSpans(spans, prefix, offset, length) {
+    return [...(prefix === "" ? [] : [previewSpan(prefix, theme.field)]), ...sliceSpans(spans, offset, length)];
 }
-function PreviewLine({ line, position, warnFirst, logicalLine, offset = 0 }) {
+function PreviewLine({ line, position, logicalLine, offset = 0, prefixLength = 0 }) {
+    const prefix = line.slice(0, prefixLength);
+    const textLength = line.length - prefixLength;
     const profileSpans = logicalLine === undefined ? profilePreviewSpans(line) : profilePreviewSpans(logicalLine);
     if (profileSpans) {
-        const spans = logicalLine === undefined ? profileSpans : visiblePreviewSpans(profileSpans, offset, line.length);
-        return _jsx(Text, { children: spans.map((span, index) => _jsx(Text, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
+        const spans = logicalLine === undefined ? profileSpans : rowSpans(profileSpans, prefix, offset, textLength);
+        return _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
     }
     const field = previewField(logicalLine ?? line);
     if (field) {
         const fieldSpans = [previewSpan(field.label, theme.field), previewSpan(field.value, theme.value)];
-        const spans = logicalLine === undefined ? fieldSpans : visiblePreviewSpans(fieldSpans, offset, line.length);
-        return _jsx(Text, { children: spans.map((span, index) => _jsx(Text, { color: span.color, children: span.text }, index)) }, position);
+        const spans = logicalLine === undefined ? fieldSpans : rowSpans(fieldSpans, prefix, offset, textLength);
+        return _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { color: span.color, children: span.text }, index)) }, position);
     }
-    return _jsx(Text, { color: warnFirst && position === 0 ? theme.warning : theme.value, children: line }, position);
+    return _jsx(PreEscapedText, { color: noticeColor(logicalLine ?? line) ?? theme.value, children: line }, position);
 }
-export function PreviewLines({ lines, warnFirst = false }) {
-    return _jsx(_Fragment, { children: lines.map((line, position) => _jsx(PreviewLine, { line: line, position: position, warnFirst: warnFirst }, position)) });
+export function PreviewLines({ lines }) {
+    return _jsx(_Fragment, { children: lines.map((line, position) => _jsx(PreviewLine, { line: escapeControlText(line), position: position }, position)) });
 }
 /** Under a list: the window indicator, how many items are marked, and the last result. */
 export function ListFooter({ indicator, selectedCount, message }) {
     return (_jsxs(_Fragment, { children: [indicator ? _jsx(Text, { color: theme.muted, children: indicator }) : null, selectedCount > 0 ? _jsxs(Text, { color: theme.muted, children: [selectedCount, " selected"] }) : null, message ? (_jsx(BorderPanel, { title: message.kind === "error" ? "Result · failed" : "Result · complete", children: _jsx(Text, { color: message.kind === "error" ? theme.error : theme.success, children: message.text }) })) : null] }));
 }
-/** A preview followed by a y/n question. */
-export function PreviewConfirm({ title = "Confirmation", lines, question, warnFirst, cursor, chrome }) {
-    const { rows, columns } = useWindowSize();
-    const viewport = cursor === undefined ? undefined : previewViewport(lines, cursor, rows || 24, columns || 80, chrome ?? { title, questions: [question], footerRows: 2 });
-    const shown = viewport?.rows ?? lines;
-    return (_jsxs(BorderPanel, { title: title, children: [viewport ? shown.map((line, position) => {
-                const sourceLine = viewport.sourceLines[position];
-                return _jsx(PreviewLine, { line: line, position: position, warnFirst: Boolean(warnFirst && viewport.start === 0), logicalLine: lines[sourceLine], offset: viewport.sourceOffsets[position] }, position);
-            }) : _jsx(PreviewLines, { lines: shown, warnFirst: warnFirst }), viewport && viewport.total > viewport.height ? _jsxs(Text, { color: theme.muted, children: [viewport.start + 1, "\u2013", viewport.end, " of ", viewport.total] }) : null, viewport ? _jsxs(Text, { color: theme.legend, children: ["Review ", viewport.cursor + 1, " of ", viewport.total, " \u00B7 arrows/Pg page"] }) : null, question.includes("y/n") ? (() => {
-                const marker = question.indexOf("y/n");
-                return _jsxs(Text, { children: [_jsx(Text, { color: theme.warning, children: question.slice(0, marker) }), _jsx(Text, { color: theme.success, bold: true, children: "y" }), _jsx(Text, { color: theme.legend, children: "/" }), _jsx(Text, { color: theme.error, children: "n" }), _jsx(Text, { color: theme.legend, children: question.slice(marker + 3) })] });
-            })() : _jsx(Text, { color: theme.legend, children: question })] }));
+function footerColor(role, reachedEnd) {
+    switch (role) {
+        case "read": return { color: theme.success };
+        case "reading": return { color: theme.warning };
+        case "consequence": return { color: theme.warning };
+        case "yes": return { color: theme.success, bold: true };
+        case "no": return { color: theme.error };
+        case "action": return reachedEnd ? { color: theme.success, bold: true } : { color: theme.muted };
+        case "position":
+        case "cancel": return { color: theme.legend };
+    }
+}
+/**
+ * A paged preview with the shared two-row footer: reading progress, then what `y` does. `[y]` stays
+ * dimmed until `viewport` reaches the end; callers ignore `y` until then using the same viewport.
+ */
+export function PagedPreview({ lines: rawLines, styled: rawStyled, viewport }) {
+    // The same escape `previewViewport` applied, so rows, offsets and spans describe the same text. The rows themselves are already
+    // escaped, hence `PreEscapedText`; only the title goes through `BorderPanel`.
+    const lines = rawLines.map(escapeControlText);
+    const styled = rawStyled?.map((line) => line?.map((span) => ({ ...span, text: escapeControlText(span.text) })));
+    return (_jsxs(BorderPanel, { title: viewport.titleRows, children: [viewport.rows.map((line, position) => {
+                const logical = viewport.sourceLines[position];
+                const custom = styled?.[logical];
+                return custom === undefined
+                    ? _jsx(PreviewLine, { line: line, position: position, logicalLine: lines[logical], offset: viewport.sourceOffsets[position], prefixLength: viewport.prefixLengths[position] }, position)
+                    : _jsx(PreEscapedText, { children: rowSpans(custom, line.slice(0, viewport.prefixLengths[position]), viewport.sourceOffsets[position], line.length - viewport.prefixLengths[position]).map((span, index) => _jsx(PreEscapedText, { color: span.color, bold: span.bold, children: span.text }, index)) }, position);
+            }), viewport.footer.map((spans, row) => _jsx(PreEscapedText, { children: spans.map((span, index) => _jsx(PreEscapedText, { ...footerColor(span.role, viewport.reachedEnd), children: span.text }, index)) }, `footer-${row}`))] }));
 }

package/dist/src/tui/preview-render.js

@@ -0,0 +1,93 @@
+import { commandLine, itemWarnings } from "../preview-model.js";
+import { theme } from "./theme.js";
+export const span = (text, color, bold = false) => bold ? { text, color, bold } : { text, color };
+// Ink drops the height of an empty Text, so a blank separator keeps one space.
+const BLANK = [span(" ", theme.value)];
+export function lineText(line) {
+    return line.map(({ text }) => text).join("");
+}
+export function textLine(text) {
+    return [span(text, theme.value)];
+}
+export function fieldLine(label, value) {
+    return [span(label, theme.field), span(` ${value}`, theme.value)];
+}
+const ROW_INDENT = "   ";
+// The views escape control characters once, as they draw.
+const TERMINAL = { terminal: true };
+// A recipe's manual text can span lines; escaped inside one line, its breaks would show as `\x0a`.
+const LINE_BREAK = /\r\n|\r|\n/u;
+function rowLines(row) {
+    switch (row.kind) {
+        case "field": {
+            const [first = "", ...rest] = row.value.split(LINE_BREAK);
+            return [
+                [span(`${ROW_INDENT}${row.label}:`, theme.field), ...(first === "" ? [] : [span(` ${first}`, theme.value)])],
+                ...rest.map((line) => [span(`${ROW_INDENT}${line}`, theme.value)]),
+            ];
+        }
+        case "text":
+            return [[span(`${ROW_INDENT}${"  ".repeat(row.indent ?? 0)}${row.text}`, theme.value)]];
+        case "warning":
+            return [[span(`${ROW_INDENT}⚠ ${row.text}`, theme.warning)]];
+        case "command": {
+            const where = [row.executable, row.cwd === undefined ? undefined : `in ${row.cwd}`].filter((part) => part !== undefined);
+            return [
+                [span(`${ROW_INDENT}$ ${commandLine(row.argv, TERMINAL)}`, theme.value)],
+                ...(where.length === 0 ? [] : [[span(`${ROW_INDENT}${where.join(" · ")}`, theme.legend)]]),
+            ];
+        }
+    }
+}
+function itemLines(item) {
+    const title = [span(` ${item.title}`, theme.value, true)];
+    if (item.detail !== undefined)
+        title.push(span(`  ${item.detail}`, theme.legend));
+    if (item.version !== undefined)
+        title.push(span(`  ${item.version.from} → ${item.version.to}`, theme.version));
+    return [title, ...item.rows.flatMap(rowLines)];
+}
+/** One block per step joined by a tree gutter: what the step runs or asks for, then dimmed where it runs. */
+export function stepBlockLines(steps) {
+    return steps.flatMap((step, index) => {
+        const last = index === steps.length - 1;
+        const branch = last ? "└" : index === 0 ? "┌" : "├";
+        const row = (...spans) => [span(last ? "   " : " │ ", theme.field), ...spans];
+        const where = [`in ${step.cwd}`, ...(step.environment ? [`on ${step.environment}`] : [])].join(" · ");
+        return [
+            [span(` ${branch} ${step.step}`, theme.field)],
+            ...(step.argv ? [row(span(`$ ${commandLine(step.argv, TERMINAL)}`, theme.value))] : []),
+            ...(step.manual ? step.manual.split(LINE_BREAK).map((line, position) => row(span(position === 0 ? `Manual: ${line}` : line, theme.value))) : []),
+            ...(step.declaration ? [row(span(step.declaration, theme.value))] : []),
+            ...(step.pattern ? [row(span(`Version pattern: ${step.pattern}`, theme.value))] : []),
+            step.argv && step.executable === undefined
+                ? row(span(`${commandLine(step.argv.slice(0, 1), TERMINAL)} not found in PATH`, theme.warning), span(` · ${where}`, theme.legend))
+                : row(span(step.executable ? `${step.executable} · ${where}` : where, theme.legend)),
+            ...(step.warning ? [row(span(`⚠ ${step.warning}`, theme.warning))] : []),
+        ];
+    });
+}
+/** The document as preview lines: action and counts, context, every warning, one section per type, then the failures. */
+export function renderPreviewDocument(document) {
+    const warnings = [
+        ...document.warnings,
+        ...document.sections.flatMap(({ items }) => items.flatMap((item) => itemWarnings(item).map((warning) => `${item.title}: ${warning}`))),
+    ];
+    const lines = [
+        [span(document.action, theme.accent, true), span(`  ${document.summary}`, theme.legend)],
+        ...document.context.map((line) => [span(` ${line}`, theme.legend)]),
+        ...warnings.map((warning) => [span(` ⚠ ${warning}`, theme.warning)]),
+    ];
+    for (const section of document.sections) {
+        lines.push(BLANK, [span(section.heading, theme.field, true)]);
+        section.items.forEach((item, position) => {
+            if (position > 0)
+                lines.push(BLANK);
+            lines.push(...itemLines(item));
+        });
+    }
+    if (document.failures.length > 0) {
+        lines.push(BLANK, [span("FAILED", theme.error, true)], ...document.failures.map((failure) => [span(` ${failure}`, theme.error)]));
+    }
+    return lines;
+}

package/dist/src/tui/preview-window.js

@@ -1,51 +1,216 @@
+import { useWindowSize } from "ink";
 import stringWidth from "string-width";
 import { headerTabRowCount } from "./header-layout.js";
+import { ESCAPE_TEXT, namesEscapedCharacter, textUnits, UNSAFE_PATTERN } from "./text-wrap.js";
 const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
-function wrapLine(line, width) {
-    const segments = [...graphemes.segment(line)];
+// Text shown in the TUI comes from recipes, Sources, Skills and Hosts. Raw, an ESC or carriage return redraws the terminal over the
+// lines under review and a bidi override reorders them; both also change the width the `y` gate was computed for. The zero-width joiner
+// stays because emoji sequences such as a person at a laptop are made with it.
+// A backslash run before text shaped like an escape we print (`\x1b`, `\u202e`, `\u{1f600}`), or before a character we escape.
+const ESCAPABLE = new RegExp(`(\\\\+)(?:(${ESCAPE_TEXT})|(?=${UNSAFE_PATTERN}))|${UNSAFE_PATTERN}`, "giu");
+/**
+ * `text` with control, format and line-separator characters replaced by visible escapes (`\x1b`, `\u202e`). A backslash run right
+ * before text that looks like one of those escapes is doubled, so a typed `\x1b` cannot pass for a real ESC; other backslashes,
+ * such as those of a Windows path, are left alone. Not idempotent: escape text once, where it enters a view.
+ */
+export function escapeControlText(text) {
+    return text.replace(ESCAPABLE, (match, backslashes, typed) => {
+        if (backslashes !== undefined) {
+            return typed !== undefined && !namesEscapedCharacter(typed) ? match : backslashes.repeat(2) + (typed ?? "");
+        }
+        const code = match.codePointAt(0);
+        const hex = code.toString(16);
+        if (code <= 0xff)
+            return `\\x${hex.padStart(2, "0")}`;
+        return code <= 0xffff ? `\\u${hex.padStart(4, "0")}` : `\\u{${hex}}`;
+    });
+}
+function escapeChrome(chrome) {
+    return {
+        ...chrome,
+        title: escapeControlText(chrome.title),
+        ...(chrome.action === undefined ? {} : { action: escapeControlText(chrome.action) }),
+        ...(chrome.consequence === undefined ? {} : { consequence: escapeControlText(chrome.consequence) }),
+        ...(chrome.cancel === undefined ? {} : { cancel: escapeControlText(chrome.cancel) }),
+    };
+}
+const TREE_GUTTER = /^( *)([│┌├└])?( *)/u;
+/**
+ * What continuation rows of a wrapped line start with: its indent and, in a step tree, the gutter that
+ * keeps running below its branch (`│` under `┌` and `├`, nothing under `└`). Empty when the prefix would
+ * leave less than half the width for text.
+ */
+function hangingPrefix(line, width) {
+    const [, before = "", glyph = "", after = ""] = TREE_GUTTER.exec(line) ?? [];
+    const continued = glyph === "" ? "" : glyph === "└" ? " " : "│";
+    const prefix = `${before}${continued}${after}`;
+    return stringWidth(prefix) * 2 <= width ? prefix : "";
+}
+function wrapLine(line, width, hang = false) {
+    const segments = textUnits(line, width);
     if (segments.length === 0)
-        return [{ row: "", offset: 0 }];
+        return [{ row: "", offset: 0, prefixLength: 0 }];
+    const prefix = hang ? hangingPrefix(line, width) : "";
     const wrapped = [];
     let row = "";
     let rowWidth = 0;
     let rowOffset = 0;
+    let prefixLength = 0;
+    let hasText = false;
     for (const { segment, index } of segments) {
         const segmentWidth = stringWidth(segment);
-        if (row !== "" && rowWidth + segmentWidth > width) {
-            wrapped.push({ row, offset: rowOffset });
-            row = "";
-            rowWidth = 0;
+        if (hasText && rowWidth + segmentWidth > width) {
+            wrapped.push({ row, offset: rowOffset, prefixLength });
+            row = prefix;
+            rowWidth = stringWidth(prefix);
+            prefixLength = prefix.length;
+            hasText = false;
             rowOffset = index;
         }
         row += segment;
         rowWidth += segmentWidth;
+        hasText = true;
     }
-    wrapped.push({ row, offset: rowOffset });
+    wrapped.push({ row, offset: rowOffset, prefixLength });
     return wrapped;
 }
-export function previewViewport(lines, cursor, terminalRows, terminalColumns, chrome = { title: "Confirmation", questions: ["Scroll to end before y; n cancels.", "Confirm? y/n"] }) {
+const MAX_BAR_WIDTH = 12;
+/** The consequence with its `y/n` keys picked out, as in a one-screen confirmation. */
+function consequenceSpans(consequence) {
+    const marker = consequence.indexOf("y/n");
+    if (marker < 0)
+        return [{ text: consequence, role: "consequence" }];
+    return [
+        { text: consequence.slice(0, marker), role: "consequence" },
+        { text: "y", role: "yes" },
+        { text: "/", role: "position" },
+        { text: "n", role: "no" },
+        ...(marker + 3 < consequence.length ? [{ text: consequence.slice(marker + 3), role: "position" }] : []),
+    ];
+}
+/** The progress line and the action line, before wrapping. */
+function footerSpans(state, chrome, width) {
+    const range = (total, start, end) => ` · ${start}–${end} of ${total}`;
+    const position = (cursor, start, end) => `Review ${cursor} of ${state.total}${state.windowed ? range(state.total, start, end) : ""}`;
+    // Sized for the widest position text so the bar, and so the footer height, never changes while paging.
+    const widest = position(state.total, state.total, state.total);
+    const barWidth = Math.min(Math.max(width - stringWidth(`read  100% · ${widest}`), 0), MAX_BAR_WIDTH);
+    const read = state.total === 0 ? 1 : state.end / state.total;
+    const filled = Math.floor(read * barWidth);
+    const bar = barWidth === 0 ? "" : `${"█".repeat(filled)}${"░".repeat(barWidth - filled)} `;
+    const progress = state.reachedEnd
+        ? [{ text: "read ✓", role: "read" }]
+        : [{ text: `read ${bar}${Math.floor(read * 100)}%`, role: "reading" }];
+    if (state.total > 0)
+        progress.push({ text: ` · ${position(state.cursor + 1, state.start + 1, state.end)}`, role: "position" });
+    if (!state.reachedEnd)
+        progress.push({ text: " · arrows/Pg page", role: "position" });
+    else if (chrome.consequence !== undefined)
+        progress.push({ text: " · ", role: "position" }, ...consequenceSpans(chrome.consequence));
+    const actions = chrome.action === undefined ? [] : [{ text: `[y] ${chrome.action}`, role: "action" }, { text: "  ", role: "cancel" }];
+    actions.push({ text: chrome.cancel ?? "[n] cancel", role: "cancel" });
+    return [progress, actions];
+}
+/** The spans covering `length` UTF-16 units of their joined text from `offset`. */
+export function sliceSpans(spans, offset, length) {
+    const end = offset + length;
+    let spanStart = 0;
+    const visible = [];
+    for (const span of spans) {
+        const spanEnd = spanStart + span.text.length;
+        const start = Math.max(offset, spanStart);
+        const stop = Math.min(end, spanEnd);
+        if (start < stop)
+            visible.push({ ...span, text: span.text.slice(start - spanStart, stop - spanStart) });
+        spanStart = spanEnd;
+    }
+    return visible;
+}
+function wrapSpans(spans, width) {
+    return wrapLine(spans.map(({ text }) => text).join(""), width).map(({ row, offset }) => sliceSpans(spans, offset, row.length));
+}
+/** `rows` cut to `maxRows`, the last kept row ending in an ellipsis when something was cut. */
+function clipRows(rows, maxRows) {
+    if (rows.length <= maxRows)
+        return rows;
+    const last = [...rows[maxRows - 1]];
+    const tail = last.pop();
+    const shortened = [...graphemes.segment(tail.text)].slice(0, -1).map(({ segment }) => segment).join("");
+    return [...rows.slice(0, maxRows - 1), [...last, ...(shortened ? [{ ...tail, text: shortened }] : []), { ...tail, text: "…" }]];
+}
+/**
+ * The footer lines wrapped to `width` within `maxRows`: the progress row, which carries the
+ * consequence, keeps all but one row if it needs them, the action row the rest. A cut row ends in an
+ * ellipsis instead of pushing the panel past the terminal.
+ */
+function layoutFooter([progressLine, actionLine], width, maxRows) {
+    const progress = wrapSpans(progressLine, width);
+    const actions = wrapSpans(actionLine, width);
+    const progressRows = Math.min(progress.length, Math.max(maxRows - 1, 1));
+    return [...clipRows(progress, progressRows), ...clipRows(actions, Math.max(maxRows - progressRows, 1))];
+}
+/** Footer rows for the widest position and both reading states, so paging never changes the height. */
+function reservedFooterRows(total, windowed, chrome, width, maxRows) {
+    const widest = { cursor: Math.max(total - 1, 0), start: Math.max(total - 1, 0), end: total, total, windowed };
+    return Math.max(layoutFooter(footerSpans({ ...widest, reachedEnd: false }, chrome, width), width, maxRows).length, layoutFooter(footerSpans({ ...widest, reachedEnd: true }, chrome, width), width, maxRows).length);
+}
+/** `title` cut, with an ellipsis, to the longest start that wraps to at most `maxRows` once escaped. */
+function clipTitle(title, width, maxRows) {
+    const fits = (text) => wrapLine(escapeControlText(text), width).length <= maxRows;
+    if (fits(title))
+        return title;
+    const parts = [...graphemes.segment(title)].map(({ segment }) => segment);
+    let low = 0;
+    let high = parts.length;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (fits(`${parts.slice(0, middle).join("")}…`))
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return `${parts.slice(0, low).join("")}…`;
+}
+export function previewViewport(rawLines, cursor, terminalRows, terminalColumns, rawChrome) {
+    const lines = rawLines.map(escapeControlText);
+    const chrome = escapeChrome(rawChrome);
     const contentWidth = Math.max(terminalColumns - 8, 1);
-    const wrapped = lines.flatMap((line, sourceLine) => wrapLine(line, contentWidth).map(({ row, offset }) => ({ row, sourceLine, offset })));
+    const wrapped = lines.flatMap((line, sourceLine) => wrapLine(line, contentWidth, true).map((wrappedRow) => ({ ...wrappedRow, sourceLine })));
     const previewRows = wrapped.map(({ row }) => row);
+    const total = previewRows.length;
     const headerRows = headerTabRowCount(contentWidth) + 3;
-    const titleRows = wrapLine(chrome.title, contentWidth).length;
-    const questionRows = Math.max(...chrome.questions.map(question => wrapLine(question, contentWidth).length));
-    const panelChromeRows = 2 + titleRows + questionRows + (chrome.footerRows ?? 1);
     const reservedRows = chrome.reservedRows !== undefined && chrome.reservedRows > 0 ? Math.ceil(chrome.reservedRows) : 0;
-    const availableRows = Math.max(terminalRows - headerRows - 1 - panelChromeRows - reservedRows, 1);
-    const height = previewRows.length > availableRows ? Math.max(availableRows - 1, 1) : availableRows;
-    const selected = Math.min(Math.max(cursor, 0), Math.max(previewRows.length - 1, 0));
-    const start = Math.min(Math.max(selected - Math.floor(height / 2), 0), Math.max(previewRows.length - height, 0));
-    const end = Math.min(start + height, previewRows.length);
+    // The footer, with its question and its action, is reserved first; the title takes what remains after a row of content.
+    const footerRows = Math.max(reservedFooterRows(total, false, chrome, contentWidth, Infinity), reservedFooterRows(total, true, chrome, contentWidth, Infinity));
+    const titleBudget = Math.max(terminalRows - headerRows - 1 - 2 - reservedRows - 1 - footerRows, 1);
+    const titleRows = wrapLine(escapeControlText(clipTitle(rawChrome.title, contentWidth, titleBudget)), contentWidth).map(({ row }) => row);
+    const fixedRows = headerRows + 1 + 2 + titleRows.length + reservedRows;
+    // At least one preview row stays visible; the footer is cut to what remains.
+    const maxFooterRows = Math.max(terminalRows - fixedRows - 1, 2);
+    const rowsWithFooter = (windowed) => Math.max(terminalRows - fixedRows - reservedFooterRows(total, windowed, chrome, contentWidth, maxFooterRows), 1);
+    const windowed = total > rowsWithFooter(false);
+    const height = rowsWithFooter(windowed);
+    const selected = Math.min(Math.max(cursor, 0), Math.max(total - 1, 0));
+    const start = Math.min(Math.max(selected - Math.floor(height / 2), 0), Math.max(total - height, 0));
+    const end = Math.min(start + height, total);
+    const reachedEnd = end === total;
     return {
+        titleRows,
         rows: previewRows.slice(start, end),
         sourceLines: wrapped.slice(start, end).map(({ sourceLine }) => sourceLine),
         sourceOffsets: wrapped.slice(start, end).map(({ offset }) => offset),
+        prefixLengths: wrapped.slice(start, end).map(({ prefixLength }) => prefixLength),
         start,
         end,
-        total: previewRows.length,
+        total,
         cursor: selected,
         height,
-        reachedEnd: end === previewRows.length,
+        reachedEnd,
+        footer: layoutFooter(footerSpans({ reachedEnd, cursor: selected, start, end, total, windowed }, chrome, contentWidth), contentWidth, maxFooterRows),
     };
 }
+/** The viewport of a preview at the current terminal size; key handling and rendering share it. */
+export function usePreviewGeometry() {
+    const { rows, columns } = useWindowSize();
+    return (lines, cursor, chrome) => previewViewport(lines, cursor, rows || 24, columns || 80, chrome);
+}