@aiwayds/dsh-tui-pi 0.1.0

package/lib/messages.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Transcript rendering: turns dsh session events into pi-tui components.
+ *
+ * Incremental by design (pi-turbo lesson): every event does O(event) work —
+ * streaming deltas update one Text in place, tool cards are keyed by callId,
+ * and nothing ever re-scans the session log.
+ *
+ * Streaming strategy: during `assistant/chunk` the raw text grows in a plain
+ * Text component; on the assembled `assistant/message` the streaming component
+ * is replaced by proper Markdown rendering. This keeps per-token cost at
+ * O(accumulated text) instead of re-parsing markdown on every delta.
+ *
+ * Panels: think blocks and tool cards render as boxed rows — a full box
+ * border (top border + header row + body rows + bottom border). The
+ * configured height counts the DISPLAYED rows — the header line plus the
+ * content rows ('5' shows five rows; the two box borders add two more
+ * physical rows, so a '5' box is seven terminal rows tall). The height is
+ * configurable through the `dsh-tui` settings namespace ('5'/'7'/'10'
+ * displayed rows, or 'all' to print the full body without a row cap). The
+ * transcript doc is a plain Container
+ * inside the outer ScrollView, so pi-tui 0.84.2 never lays out nested
+ * components (a Container without a layout node renders by simple
+ * concatenation — verified in dist/layout.js) and an inner ScrollView can
+ * never obtain a viewport. The body is therefore a padded tail of the last
+ * body-row budget (or every row, in 'all' mode) rather than an internal
+ * scroll; every row (borders included) carries the panel background. In
+ * 'all' mode the unbounded content stays bounded on screen: a streaming
+ * reasoning panel boxes only a STREAMING_TAIL_LINES live tail while chunks
+ * are in flight (the assembled message renders the full body), and a settled
+ * tool card keeps at most ALL_TOOL_RESULT_LINES rows with a drop marker.
+ *
+ * Theme hot-switch: every applied operation is appended to `replay` (O(1)
+ * per event — never a render-path scan). `setTheme` is an explicit user
+ * action, so it may do a one-off full rebuild: clear the doc and re-apply
+ * the buffered operations against the new theme. Streaming and tool cards
+ * rebuild exactly as they were applied, so an in-flight stream simply
+ * continues `setText` on its rebuilt component. (The live Todos/Agents
+ * widgets live outside the transcript — see live-widgets.ts.)
+ *
+ * Welcome banner: the first replay op, pushed at construction (the doc is
+ * cleared first, replacing tui.ts's startup placeholder). It stays at the
+ * top of the doc — the event flow appends below it, and every rebuild
+ * (relayout/setTheme) reproduces it first with the current theme.
+ */
+import { Container } from '@earendil-works/pi-tui';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type TuiTheme } from './theme/index.ts';
+/**
+ * Configurable think/tool panel height. Fixed values count the DISPLAYED
+ * rows — the header line plus the content rows (the two box borders are not
+ * counted; they add two more physical rows); 'all' prints the full body
+ * with no row cap (every row still clips to one terminal line).
+ */
+export type PanelHeight = '5' | '7' | '10' | 'all';
+/**
+ * Default displayed height of a think/tool panel: the header line plus the
+ * content rows. The single default for every '5' fallback (the renderer
+ * constructor, the settings schema default/entry/narrowing) — other heights
+ * are set through the `panelHeight` setting.
+ */
+export declare const DEFAULT_PANEL_HEIGHT: PanelHeight;
+/**
+ * 'all' streaming cap: while a reasoning stream is in flight, the panel boxes
+ * only this many trailing rows. Without the cap every chunk would re-box the
+ * whole accumulated body — O(accumulated) per chunk, O(n²) over the stream
+ * (3000 lines ≈ 22s vs 155ms at a fixed height). The live tail is transient:
+ * the assembled `assistant/message` reasoning block (and the replay rebuilds)
+ * render the full body.
+ */
+export declare const STREAMING_TAIL_LINES = 200;
+/**
+ * 'all' settle cap: a settled tool card keeps at most this many body rows,
+ * with a `… (+N lines)` marker for the drop. The unlimited body would
+ * otherwise hitch the frame and balloon memory on a 50k-line tool result.
+ */
+export declare const ALL_TOOL_RESULT_LINES = 2000;
+/**
+ * Terminal columns a panel body row's CONTENT may occupy so the whole
+ * bordered row renders on exactly one physical line: the body Text wraps at
+ * `width - paddingX*2` (paddingX = 1), every row carries 4 columns of box
+ * chrome (`│ ` … ` │`), and tool rows add a 2-column indent — hence the -6
+ * (think) and -8 (tool, indent = 2) headroom.
+ */
+export declare function panelLineCap(columns: number | undefined, indent?: number): number;
+/** Full visible width of one bordered panel row, box chrome included. */
+export declare function panelBoxWidth(columns: number | undefined): number;
+/**
+ * Clip an unstyled line to one physical panel row. Must run BEFORE styling:
+ * clipToWidth counts per grapheme, so the ASCII fragments of an SGR code
+ * would count as visible columns (verified against pi-tui 0.84.2) — clipping
+ * plain text first, then applying ANSI, keeps the accounting exact.
+ * `indent` is the leading content indent the row carries (2 for tool rows).
+ * Carriage returns are stripped first: pi-tui's wrapTextWithAnsi splits on
+ * `/\r\n|\r|\n/`, so a bare \r (progress bars, CRLF tool output) would break
+ * the fixed panel rows just like a wrap would — the panel line is one row,
+ * not a line record.
+ */
+export declare function clipPanelLine(text: string, indent?: number): string;
+/**
+ * Compose the bordered body Text content (boxed rows plus the bottom border)
+ * from already-styled, already-clipped lines: keep the tail — newest rows
+ * win — pad short content with empty boxed rows, then append the bottom
+ * border. `bodyRows` is the panel's body-row budget (default PANEL_BODY_LINES)
+ * or 'all': with 'all' every line is kept verbatim, nothing is padded, and
+ * only the bottom border is appended (the box stays closed). Every row is
+ * one `boxWidth`-wide boxed line (`│ ` … ` │`, see borderedRow);
+ * `borderFg` is the panelBorder SGR prefix (no trailing RESET — the panel
+ * bg function terminates the row). Pad rows carry the box characters, so
+ * they survive Text's `text.trim() === ''` fast path, which would otherwise
+ * drop a body of only empty rows; the border SGR does not touch the
+ * background, so the panel bg function still paints the full row width.
+ * Callers clip each line with `clipPanelLine` BEFORE styling — otherwise a
+ * styled line that outgrows `width - paddingX*2` wraps and the panel
+ * exceeds its configured rows.
+ */
+export declare function panelBodyText(lines: readonly string[], boxWidth: number, borderFg: string, bodyRows?: number | 'all'): string;
+/**
+ * The tool header's subject word: the file path for read/write-style tools,
+ * the command's first word for cli-style tools ('git', 'python') — the first
+ * whitespace token of the highest-priority string argument (same key
+ * priority as callDetail's summary). '' when the arguments carry no usable
+ * string (the header then shows the bare tool name).
+ */
+export declare function toolSubject(rawArguments: string): string;
+export declare class TranscriptRenderer {
+    private readonly doc;
+    private theme;
+    private readonly requestRender;
+    /** Configured panel height ('5'/'7'/'10' total rows, or 'all' = uncapped). */
+    private panelHeight;
+    private streaming;
+    private readonly toolCards;
+    /** Text of the prompt echoed locally on submit; the matching session event is deduped. */
+    private lastEcho;
+    /**
+     * Append-only buffer of every applied operation (O(1) per event). The
+     * render path never scans it; `setTheme` — an explicit user action — is
+     * the only reader, replaying it once against the new theme.
+     */
+    private readonly replay;
+    /**
+     * The session's daily quote — rolled once here, so every rebuild
+     * (relayout/setTheme replay) re-renders the same line and only a fresh
+     * session rolls a new one (see quotes.ts).
+     */
+    private readonly dailyQuote;
+    constructor(doc: Container, theme: TuiTheme, requestRender: () => void, panelHeight?: PanelHeight);
+    /**
+     * Content-row budget for the configured panel height: the displayed row
+     * count minus the header row ('5' → 4 content rows), or 'all' when the
+     * panel prints its full body. The box borders are not part of the budget.
+     */
+    private panelBodyRows;
+    /**
+     * Switch the configured panel height. Returns whether the height actually
+     * changed — the settings watch sink relayouts only then; `relayout` is the
+     * replay rebuild that repaints every panel (streaming, tool cards, settled
+     * cards) at the new row budget.
+     */
+    setPanelHeight(panelHeight: PanelHeight): boolean;
+    applyEvent(event: SessionEvent): void;
+    /** Render a submitted prompt immediately, before the session echoes it back. */
+    renderPromptEcho(text: string): void;
+    /** Render one executed slash command line with its outcome. */
+    renderCommandEcho(line: string, error?: string, text?: string): void;
+    /**
+     * Append a transcript line that has no matching session event (a
+     * transient status notice or the sole on-screen record of an error).
+     * Buffered as a replay op like echoes, so a theme-switch rebuild keeps it.
+     * `error` lines get the ✘ danger treatment; `info` lines the attention
+     * color (the Ctrl+C cancel hint) without a prefix.
+     */
+    renderNotice(text: string, level?: 'error' | 'info'): void;
+    /**
+     * Repaint the whole transcript against a new theme: clear the doc and
+     * replay the buffered operations. Per-op requestRenders coalesce into a
+     * single pi-tui frame (requestRender is nextTick-throttled), so the switch
+     * repaints once, with no intermediate flicker. An in-flight stream keeps
+     * its accumulated text — the replay rebuilds its Text and later chunks
+     * continue setText on it. No-op when the theme bundle is unchanged
+     * (themes are module singletons; the settings watcher may echo our own
+     * write).
+     */
+    setTheme(theme: TuiTheme): void;
+    /**
+     * Repaint the whole transcript at the current terminal width — the resize
+     * counterpart of `setTheme`. On stdout `resize` pi-tui re-renders every
+     * component with the new columns, but bordered panel rows were padded to
+     * the OLD box width, so a narrowing terminal wraps every row and shatters
+     * the fixed-height panels. Clear and re-apply the buffered operations
+     * exactly like a theme switch: an in-flight stream keeps its accumulated
+     * text (the replay rebuilds its Text and later chunks continue setText on
+     * it), tool cards keep their settle state, todos reappear. No-op when the
+     * replay is empty — that guards the doc emptied by /new (clear()), which
+     * must stay empty until the next prompt: the welcome banner is the startup
+     * screen of a TUI run and must not resurrect here.
+     */
+    relayout(): void;
+    /**
+     * Drop everything rendered so far (`/new`). The next prompt opens a fresh
+     * agent; the welcome banner goes with the rest — it is the startup screen
+     * of a TUI run, not persistent transcript chrome.
+     */
+    clear(): void;
+    /** Re-apply one buffered operation against the current theme. */
+    private applyOp;
+    /**
+     * The startup welcome banner (whale pixel art + pixel-letter wordmark)
+     * with the daily quote caption beneath it, as the doc's first content:
+     * a leading spacer, the banner Text, a spacer, the quote Text, then the
+     * trailing spacer that matches the message-block rhythm. The leading
+     * spacer keeps the banner from pressing against the top of the transcript
+     * (the startup placeholder line it replaces sat flush at row 0). The
+     * whale and the letters keep their brand blue across themes — the banner
+     * is theme-independent (gaps stay transparent over the terminal default
+     * background — see welcome.ts); the quote is the one theme-tinted line
+     * (fgSubtle, rebuilt with the live theme by the replay). The banner is
+     * built at the current terminal width: below 96 columns it degrades to
+     * the whale alone, and every rebuild (relayout/setTheme replay) reads the
+     * width afresh, so narrowing drops the wordmark and widening restores it.
+     * The quote line is clipped to the terminal width before styling (the
+     * repo rule — ANSI never goes through the clipper), so it never wraps.
+     */
+    private renderWelcome;
+    private renderUserMessage;
+    private renderUserText;
+    private applyChunk;
+    private finalizeStreaming;
+    /** Keep streaming components as-is but detach state (user message arrived). */
+    private dropStreaming;
+    /** Full box width and panelBorder SGR prefix for one panel, per current theme. */
+    private panelBox;
+    /** Top border line plus bordered header row — the header Text's two lines. */
+    private panelTop;
+    /**
+     * Thinking color style, italic-on. The style terminates with a targeted
+     * italic-off (`\x1b[23m`) — NOT a full RESET: the panel bg function paints
+     * the whole row width, and a `\x1b[0m` here would clear the background and
+     * leave the row's right side unpainted. Without the italic-off the leak is
+     * visible in the box chrome: wrapTextWithAnsi carries ANSI state across
+     * lines within one Text, so the row's right border, the following body
+     * rows and the bottom border would all render italic.
+     */
+    private thinkStyle;
+    /**
+     * Styled, boxed tail of a reasoning text at the configured height (bottom
+     * border included). `streaming` marks the in-flight live path (per-chunk
+     * setBody): 'all' then boxes only the bounded STREAMING_TAIL_LINES tail so
+     * every chunk stays O(tail) — the full body renders once the assembled
+     * `assistant/message` (and the replay rebuilds) call without the flag.
+     * Fixed heights are already tail-bounded and behave identically either way.
+     */
+    private thinkingBody;
+    /**
+     * Build the thinking panel (default 5 rows, configurable height): top
+     * border + header row + body rows + bottom border, all on the thinking
+     * panel background.
+     * Header icon: '⟡' (U+27E1) renders as a tofu box on the user's terminal;
+     * emoji render fine there (footer ⚙✔✘⏹ all verified), so '💭' is used.
+     * The fixed header text is clipped at the plain-text stage like every
+     * other panel line — below 17 terminal columns it would otherwise outgrow
+     * the header row's budget and wrap, breaking the panel shape.
+     */
+    private createThinkingPanel;
+    private renderAssistantMessage;
+    /**
+     * Styled tool header content (icon + name + subject, no box chrome, no
+     * trailing RESET). The subject is the argument's first word — the file
+     * path for read/write, the command for cli (see toolSubject) — so the
+     * first line reads like "⚙ read src/welcome.ts" / "⚙ cli python".
+     */
+    private toolHeader;
+    private addToolCard;
+    private settleToolCard;
+    private renderTurnEnd;
+    private appendLine;
+}