@agi-fans/dsh-tui 0.18.0 → 0.20.0

package/lib/views/transcript-render.d.ts

@@ -20,6 +20,8 @@ import type { WelcomeTip } from '../chrome/welcome-tips.ts';
 import type { MotionMode } from '../session/tui-settings.ts';
 import { type Block, type TodoItem, type TranscriptState } from './transcript-types.ts';
 export interface ViewOptions {
+    /** Effective key for active-turn guidance, when the provider has an admission handler. */
+    steerKey?: string;
     /** Terminal width in columns. */
     width: number;
     /** Terminal height in rows; the view keeps the frame inside it. */
@@ -52,6 +54,8 @@ export interface ViewOptions {
     spinnerFrame?: number;
     /** Animation policy for streaming, activity marks, and the working label. */
     motion?: MotionMode;
+    mathMode?: import('../chrome/math.ts').MathMode;
+    mermaidMode?: import('../chrome/mermaid.ts').MermaidMode;
     /** 24-bit color; defaults to off so tests stay deterministic. */
     trueColor?: boolean;
     /** Shipped palette; defaults to dark. */
@@ -71,6 +75,12 @@ export interface ViewOptions {
     trajectory?: TrajectoryState;
     /** Keyboard-first full-screen descendant roster and inspector. */
     agentHub?: AgentHubState;
+    /** Terminal-owned graphics capability and measured cell geometry. */
+    imageProtocol?: import('../chrome/terminal-images.ts').ImageProtocol;
+    imageCellSize?: {
+        width: number;
+        height: number;
+    };
     /** Human-interaction selector; replaces the normal editor while active. */
     promptSelector?: PromptSelectorState;
     /** Effective local + agent-scoped slash command catalog. */
@@ -100,8 +110,10 @@ export interface ViewOptions {
      * the window to the latest lines — the OMP follow-tail default.
      */
     scrollStart?: number;
-    /** Open one transcript block at its first row instead of following the tail. */
+    /** Focus one transcript block instead of following the tail. */
     focusBlock?: number;
+    /** Which edge of the focused block to show; searches default to its start. */
+    focusBlockEdge?: 'start' | 'end';
     /**
      * Active transcript search. Matching block rows containing the query paint
      * inverse; `matches` are block indexes in render order and `focus` selects
@@ -113,35 +125,120 @@ export interface ViewOptions {
         focus: number;
         editing: boolean;
     };
-    /**
-     * When true, tool blocks paint their full output (OMP `ctrl+o`). Default
-     * is the collapsed preview of {@link TOOL_COLLAPSED_LINES} rows.
-     */
+    /** Legacy full-output override for direct callers and the tool catalog. */
     toolsExpanded?: boolean;
-    /** Individual tool calls expanded by the user. */
+    /** Tool calls whose complete inputs and results are visible. */
     expandedTools?: ReadonlySet<string>;
+    /** Effective application binding used in preview hints. */
+    toolDetailsKey?: string;
+    /** Effective application binding used in completed-turn expansion hints. */
+    turnDetailsKey?: string;
+    /** Legacy reasoning anchors retained for search and scroll mapping. */
+    expandedReasoning?: ReadonlySet<string>;
+    /** Process groups the reader opened, keyed by {@link ProcessGroup.key}. */
+    openedGroups?: ReadonlySet<string>;
 }
-/** Collapsed tool-output preview height (OMP `DEFAULT_TERMINAL_PREVIEW_LINES`). */
-export declare const TOOL_COLLAPSED_LINES = 10;
-export declare const TOOL_INPUT_COLLAPSED_LINES = 3;
+/** A settled turn's length, the way a person would say it. */
+export declare function formatElapsed(ms: number): string;
 /**
- * Render one transcript block to display lines. Pure; shared by the tty view
- * and the non-tty plain printer.
- * @param block - the block to render.
- * @param theme - active theme.
- * @param width - terminal width in columns.
- * @param spinnerFrame - activity spinner phase for running tools.
- * @param toolsExpanded - paint full tool output instead of the collapsed preview.
- * @returns display lines (already width-fitted).
+ * Render a block for the transcript or plain printer. Full output is available
+ * to direct callers; turn inspection uses previews. omitReasoning excludes
+ * thinking already drawn by a run.
  */
-export declare function blockLines(block: Block, theme: Theme, width: number, spinnerFrame?: number, toolsExpanded?: boolean): string[];
+export declare function blockLines(block: Block, theme: Theme, width: number, { toolsExpanded, omitReasoning, toolDetailsKey, mathMode, mermaidMode }?: {
+    toolsExpanded?: boolean;
+    omitReasoning?: boolean;
+    toolDetailsKey?: string;
+    mathMode?: import('../chrome/math.ts').MathMode;
+    mermaidMode?: import('../chrome/mermaid.ts').MermaidMode;
+}): string[];
+/** Why the transcript was replaced. */
+export type TranscriptSeam = 'session-opened' | 'cleared';
+/** The row that separates two documents in the terminal's history. */
+export declare function transcriptSeam(reason: TranscriptSeam): Block;
 /** Plain text of one block, used by transcript search and match painting. */
 export declare function blockSearchText(block: Block): string;
+/** One collapsible stretch of process: the calls and thoughts between two answers. */
+export interface ProcessGroup {
+    /** Index of the first block in the group. */
+    start: number;
+    /**
+     * Exclusive end of the whole stretch, including the answer and any process
+     * work that settled behind it. Those are the run's work too, so the header
+     * counts them; they render as the run's rows around the answer, which keeps
+     * the rows in the order the events arrived.
+     *
+     * The run's own members end at its {@link ProcessGroup.answer} when it had
+     * one — that is where a reply enters — and at this boundary otherwise, so
+     * there is no separate member end to keep in step.
+     */
+    until: number;
+    /**
+     * The reply that closed the run, when the stretch had one.
+     *
+     * It is the turn's answer, not part of the run: the run's work sits above and
+     * around it, and its words render as a row of their own. Naming it keeps the
+     * run's members, the answer and the work behind it from overlapping, which is
+     * how a run ended up painting its own header twice, or folding the reply it
+     * was supposed to leave visible.
+     */
+    answer?: number;
+    /**
+     * The run took the answer's step's thought as its last row, so those words
+     * are painted without it. The step is always {@link ProcessGroup.answer}, so
+     * this is a flag rather than a second index into the same block.
+     */
+    tookThought: boolean;
+    /** How many tool calls the run made. */
+    calls: number;
+    /** Failed calls and independent process notices in this run. */
+    failures: number;
+    /** True while the group still holds a call in flight or a thought still arriving. */
+    live: boolean;
+    /** The turn the run belongs to, when any of its steps says. */
+    turn?: number;
+    /**
+     * Identity derived from the group's first block, so a group that grows as the
+     * agent keeps working is still the same group to the reader who opened it.
+     */
+    key: string;
+}
+/**
+ * Project the transcript's turns into runs without touching the block list.
+ *
+ * A stretch of process blocks from one turn is one run. If the stretch ends on
+ * a reply, that reply is the turn's answer and stays outside; any reply before
+ * it was written on the way and is part of the run. A prompt, the per-turn
+ * changed-file record, or any notice that speaks to the reader ends the stretch,
+ * and so does a block from another turn — two turns with no prompt between
+ * them, such as a goal continuing itself, still read as two runs.
+ *
+ * The block list is deliberately left alone: a group is a rendering decision, so
+ * search, focus, and the row offsets keep addressing real blocks, and a group
+ * that is still growing cannot invalidate anything a reader already saw.
+ */
+export declare function processGroups(blocks: readonly Block[]): ProcessGroup[];
+/**
+ * The runs as the reader sees them now: {@link processGroups}, with the run a
+ * running turn is still adding to marked live.
+ *
+ * That run is live even between two events, when nothing is in flight — the
+ * model is choosing what to do next — and while the answer streams below it,
+ * so it becomes a group once, when the turn ends, rather than folding and
+ * unfolding at every pause. The host aims Ctrl+O with the same projection the
+ * renderer paints, so the two cannot disagree about what is folded.
+ */
+export declare function turnGroups(state: TranscriptState): ProcessGroup[];
 /** Rows moved per Shift+Arrow (OMP ScrollView `fastScrollLines`). */
 export declare const TRANSCRIPT_FAST_SCROLL = 5;
 /**
  * Window `body` into `budget` rows with ↑/↓ overflow markers.
  * `start` is the first body row to keep; non-finite values pin to the tail.
+ *
+ * `documentRows` says which of `body`'s rows the returned lines are, and where
+ * in the returned lines they start. A window that is nothing but an overflow
+ * marker carries none: `null`, because the frame drew no body rather than
+ * because the caller forgot to say.
  */
 export declare function windowTranscript(body: readonly string[], budget: number, start: number, theme: Theme): TranscriptScroll & {
     lines: string[];
@@ -167,6 +264,8 @@ export declare function renderInspectBanner(inspected: TuiInspectedSubagent | un
  * The row is bounded to a single line so it cannot squeeze the transcript.
  */
 export declare function renderTurnError(text: string, theme: Theme, width: number): string[];
+/** Human guidance remains visible until the Harness claims it for a model step. */
+export declare function renderSteering(inbox: readonly UserMessage[], theme: Theme, width: number): string[];
 /** Compact, unframed pending-message view placed immediately above the composer. */
 export declare function renderQueuedSubmissions(submissions: readonly TuiSubmission[], theme: Theme, width: number, inbox?: readonly UserMessage[]): string[];
 /**