@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/dist/types/render/render-utils.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Shared utilities and constants for tool renderers.
+ *
+ * Provides consistent formatting, truncation, and display patterns across all
+ * tool renderers to ensure a unified TUI experience.
+ */
+import { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Ellipsis } from "@oh-my-pi/pi-natives";
+import type { Theme } from "../theme/theme.js";
+import type { Component } from "../tui.js";
+export { Ellipsis } from "@oh-my-pi/pi-natives";
+export { replaceTabs, truncateToWidth, wrapTextWithAnsi } from "../utils.js";
+/** A thinking selector configured as a concrete level or automatic selection. */
+export type ConfiguredThinkingLevel = ThinkingLevel | "auto";
+/**
+ * Normalize stray carriage returns in model-authored display text. Some models
+ * (observed with GLM via OpenRouter) degenerate into injecting `\r` runs between
+ * words inside JSON string values; CommonMark treats a lone `\r` as a line
+ * ending, which splatters the text one word per row. CRLF becomes LF, CR runs
+ * collapse to a single space — word separators in prose, one indent unit in
+ * mangled code previews.
+ */
+export declare function sanitizeCarriageReturns(text: string): string;
+/**
+ * Sanitize raw ask option labels into unique, action-safe display copies.
+ * Degenerate input can sanitize alike (`Retry\rnow`/`Retry now`) or match a
+ * runtime action row (`Other (type your own)`); both would answer the wrong
+ * row, so colliding entries take a numeric suffix. Order and length are
+ * preserved, so indices still align with the original labels for mapping
+ * answers and dialog state back. Every ask race participant (local dialog,
+ * guest selector) must call this with the same `reservedLabels` so a
+ * question renders identically wherever it is answered.
+ */
+export declare function disambiguateDisplayLabels(rawLabels: string[], reservedLabels: readonly string[]): string[];
+/** Set the maximum inline image width in terminal columns; zero leaves it uncapped. */
+export declare function setInlineImageMaxColumns(maxColumns: number): void;
+/** Set the maximum inline image height in terminal rows; zero uses the viewport limit. */
+export declare function setInlineImageMaxRows(maxRows: number): void;
+/** Resolve inline image dimension caps from the configured limits and viewport. */
+export declare function resolveImageOptions(): {
+    maxWidthCells: number;
+    maxHeightCells?: number;
+};
+/** Preview limits for collapsed/expanded views */
+export declare const PREVIEW_LIMITS: {
+    /** Lines shown in collapsed view */
+    readonly COLLAPSED_LINES: 3;
+    /** Lines shown in expanded view */
+    readonly EXPANDED_LINES: 12;
+    /** Items (files, results) shown in collapsed view */
+    readonly COLLAPSED_ITEMS: 8;
+    /** Output preview lines in collapsed view */
+    readonly OUTPUT_COLLAPSED: 3;
+    /** Output preview lines in expanded view */
+    readonly OUTPUT_EXPANDED: 10;
+    /** Computer script lines shown in collapsed view */
+    readonly COMPUTER_CODE_COLLAPSED: 10;
+    /** Max hunks shown when collapsed (edit tool) */
+    readonly DIFF_COLLAPSED_HUNKS: 8;
+    /** Max diff lines shown when collapsed (edit tool) */
+    readonly DIFF_COLLAPSED_LINES: 40;
+};
+/** Default number of terminal output rows shown before expansion. */
+export declare const DEFAULT_TERMINAL_PREVIEW_LINES = 10;
+/** Match a Markdown fenced-code opener and capture its indentation and marker. */
+export declare const FENCE_RE: RegExp;
+/** Shared empty link-target lookup for renderers without interactive links. */
+export declare const EMPTY_LINK_TARGETS: ReadonlyMap<string, string>;
+/** Default display width reserved for a resolved model badge. */
+export declare const FEED_MODEL_BADGE_WIDTH = 30;
+/** Set whether feed rows display their resolved model badge. */
+export declare function setFeedModelBadgeEnabled(enabled: boolean): void;
+/** Return whether resolved model badges are enabled. */
+export declare function isFeedModelBadgeEnabled(): boolean;
+/** Compact glyph for a configured thinking level; empty for `inherit` (nothing to show). */
+export declare function thinkingLevelGlyph(level: ConfiguredThinkingLevel, uiTheme: Theme): string;
+/**
+ * Compact feed-row prefix: explicit thinking glyph, sanitized model identity,
+ * then advisor eye. Keep fitting icons if no model fits; preserve literal identity suffixes.
+ */
+export declare function formatFeedModelBadge(modelIdentity: string | undefined, thinkingLevel: ConfiguredThinkingLevel | undefined, advisor: boolean | undefined, uiTheme: Theme, maxWidth?: number): string;
+/** Truncation lengths for different content types */
+export declare const TRUNCATE_LENGTHS: {
+    /** Short titles, labels */
+    readonly TITLE: 60;
+    /** Medium-length content (messages, previews) */
+    readonly CONTENT: 80;
+    /** Longer content (code, explanations) */
+    readonly LONG: 100;
+    /** Full line content */
+    readonly LINE: 110;
+    /** Very short (task previews, badges) */
+    readonly SHORT: 40;
+    /** Idle recap status line (~40-word LLM reply) */
+    readonly RECAP: 280;
+};
+/** Human-readable key currently bound to tool-output expansion, e.g. `Ctrl+O`. */
+export declare function expandKeyHint(): string;
+/** Select a leading line window and count the lines hidden after it. */
+export declare function cappedHeadLines(lines: readonly string[], max: number): {
+    lines: readonly string[];
+    hidden: number;
+};
+/** Get the first nonblank preview lines, trimmed and width-capped. */
+export declare function getPreviewLines(text: string, maxLines: number, maxLineLen: number, ellipsis?: Ellipsis): string[];
+/**
+ * Collapse a possibly multi-line string into a single line, then truncate it to
+ * `maxWidth` display cells. {@link truncateToWidth} alone caps width but
+ * newlines are zero-width, so multi-line content (markdown briefs, tool args,
+ * provider errors) would otherwise spill a single status row across several
+ * visual lines. Whitespace runs collapse to one space, so tabs are handled too.
+ */
+export declare function previewLine(text: string, maxWidth: number, ellipsis?: Ellipsis): string;
+/**
+ * Extract domain from URL, stripping www. prefix.
+ */
+export declare function getDomain(url: string): string;
+export { formatAge, formatBytes, formatCount, formatDuration, formatNumber, pluralize } from "@oh-my-pi/pi-utils";
+/**
+ * Get the appropriate status icon with color for a given state.
+ * Standardizes status icon usage across all renderers.
+ */
+export declare function formatStatusIcon(status: ToolUIStatus, theme: Theme, spinnerFrame?: number): string;
+/**
+ * Format the expand hint with proper theming.
+ * Returns empty string if already expanded or there is nothing more to show.
+ */
+export declare function formatExpandHint(theme: Theme, expanded?: boolean, hasMore?: boolean): string;
+/**
+ * Format a badge like [done] or [failed] with brackets and color.
+ */
+export declare function formatBadge(label: string, color: ToolUIColor, theme: Theme): string;
+/**
+ * Build a "more items" suffix line for truncated lists.
+ * Uses consistent wording pattern.
+ */
+export declare function formatMoreItems(remaining: number, itemType: string): string;
+/** Tail-window height for collapsed command/code previews. */
+export declare function previewWindowRows(): number;
+/**
+ * Cap a pre-rendered command preview to a viewport-sized tail window: the end
+ * of the command stays visible (it is the live edge while args stream) behind
+ * an "… N earlier lines" marker on top. The same window applies while
+ * streaming and after completion so the block never jumps; only `expanded`
+ * (ctrl+o) uncaps it.
+ *
+ * `prefix` (raw, e.g. a dim tree gutter) is prepended to the marker line so
+ * nested previews stay aligned. `expandHint: false` drops the "ctrl+o: Expand"
+ * suffix for callers that cap even inside the expanded view (task recent
+ * output), where the hint would point the wrong way.
+ */
+export declare function capPreviewLines(lines: string[], theme: Theme, options?: {
+    max?: number;
+    expanded?: boolean;
+    prefix?: string;
+    expandHint?: boolean;
+}): string[];
+/** Join metadata with the theme separator and muted styling. */
+export declare function formatMeta(meta: string[], theme: Theme): string;
+/**
+ * Split multi-line tool text into TUI-safe display lines.
+ * Splits CRLF/LF, collapses stray `\r` progress overwrites to the final
+ * segment (mirroring terminal rendering), and expands tabs — so raw
+ * subprocess or fetched output (e.g. Windows ssh emitting CRLF, tab-indented
+ * web content) can't corrupt the framed block layout with cursor-moving
+ * control characters or tab-stop width mismatches.
+ */
+export declare function sanitizeDisplayLines(text: string): string[];
+/** Render a sanitized error message with its status icon. */
+export declare function formatErrorMessage(message: string | undefined, theme: Theme): string;
+/**
+ * Error message rendered as a subordinate detail line beneath a status header
+ * that already carries the error icon (e.g. `✘ Write: <path>`). The header's
+ * icon already signals failure, so this omits the redundant error symbol and
+ * "Error:" prefix that `formatErrorMessage` adds for standalone single-line
+ * errors, indenting two columns to sit under the header title instead.
+ */
+export declare function formatErrorDetail(message: string | undefined, theme: Theme): string;
+/** Render a muted empty-state message with a warning icon. */
+export declare function formatEmptyMessage(message: string, theme: Theme): string;
+/** Marker displayed in the gutter of a code frame. */
+export type CodeFrameMarker = "" | " " | "*" | "+" | "-" | ">";
+/** Format a code-frame row with a padded line-number gutter. */
+export declare function formatCodeFrameLine(marker: CodeFrameMarker, lineNumber: string | number, content: string, lineNumberWidth: number): string;
+/** Status states supported by shared tool renderer icons. */
+export type ToolUIStatus = "success" | "done" | "error" | "warning" | "info" | "pending" | "running" | "aborted";
+/** Semantic foreground colors used by tool renderer labels. */
+export type ToolUIColor = "success" | "error" | "warning" | "accent" | "muted";
+/** Presentation options for a tool title. */
+export interface ToolUITitleOptions {
+    bold?: boolean;
+}
+/** Render a themed tool title with optional bold emphasis. */
+export declare function formatTitle(label: string, theme: Theme, options?: ToolUITitleOptions): string;
+/** Parsed diagnostic location, severity, and optional source and code metadata. */
+export interface ParsedDiagnostic {
+    filePath: string;
+    line: number;
+    col: number;
+    severity: "error" | "warning" | "info" | "hint";
+    source?: string;
+    message: string;
+    code?: string;
+}
+/** Expand tabs in diagnostic text for terminal display. */
+export declare function sanitizeDiagnosticDisplayText(text: string): string;
+/** Parse a diagnostic location and message, including optional source and code. */
+export declare function parseDiagnosticMessage(msg: string): ParsedDiagnostic | null;
+/** Render diagnostic summaries and optionally expanded messages. */
+export declare function formatDiagnostics(diag: {
+    errored: boolean;
+    summary: string;
+    messages: string[];
+}, expanded: boolean, theme: Theme, getLangIcon: (filePath: string) => string, options?: {
+    title?: string;
+}): string;
+/** Added and removed line counts and hunk metadata for a diff. */
+export interface DiffStats {
+    added: number;
+    removed: number;
+    hunks: number;
+    lines: number;
+}
+/** Count added lines, removed lines, and hunks in a unified diff. */
+export declare function getDiffStats(diffText: string): DiffStats;
+/** Render a compact themed summary of diff counts. */
+export declare function formatDiffStats(added: number, removed: number, hunks: number, theme: Theme): string;
+/** Truncate a unified diff at hunk boundaries within the supplied preview limits. */
+export declare function truncateDiffByHunk(diffText: string, maxHunks: number, maxLines: number, options?: {
+    fromTail?: boolean;
+}): {
+    text: string;
+    hiddenHunks: number;
+    hiddenLines: number;
+};
+/** Replace a leading home directory with a portable tilde prefix. */
+export declare function shortenPath(filePath: unknown, homeDir?: string): string;
+/** Shorten embedded home paths; normalize Windows separators unless the caller preserves native error text. */
+export declare function shortenEmbeddedPaths(text: string, homeDir?: string, preserveSeparators?: boolean): string;
+/** Sanitize warning text before showing it in TUI, including embedded home paths. */
+export declare function sanitizeDisplayWarning(text: string): string;
+/** Sanitize and bound warning text before showing it in TUI. */
+export declare function sanitizeDisplayWarnings(warnings: readonly string[]): string[];
+/** Format a tool working directory when it differs from the project directory. */
+export declare function formatToolWorkingDirectory(workdir: string | undefined, projectDir: string): string | undefined;
+/** Wrap text in the theme-specific bracket pair. */
+export declare function wrapBrackets(text: string, theme: Theme): string;
+/** Maximum number of parse errors displayed in expanded details. */
+export declare const PARSE_ERRORS_LIMIT = 20;
+/** Deduplicate parse errors while preserving their original order. */
+export declare function dedupeParseErrors(errors: string[] | undefined): string[];
+/** Format deduplicated parse errors with a bounded detail list. */
+export declare function formatParseErrors(errors: string[], total?: number): string[];
+/**
+ * Cap an upstream parse-error list to {@link PARSE_ERRORS_LIMIT} unique entries,
+ * preserving the original deduplicated total. Use this at the source so tool
+ * details never carry thousands of per-file parse errors into traces or
+ * renderers.
+ */
+export declare function capParseErrors(errors: string[] | undefined, limit?: number): {
+    errors: string[];
+    total: number;
+};
+/**
+ * Standard width+expand keyed render cache used by every search-style tool
+ * renderer. `compute` re-runs only when the cache key changes; the returned
+ * Component is the canonical `{ render, invalidate }` pair.
+ */
+export declare function createCachedComponent(getExpanded: () => boolean, compute: (width: number, expanded: boolean) => string[], options?: {
+    paddingX?: number;
+}): Component;
+/**
+ * Single-slot memo for an expensive rendered string (syntax highlighting, diff
+ * coloring) keyed by the exact inputs that shape the bytes: theme instance,
+ * expanded state, a caller-chosen salt (path/language), and the source content.
+ * Field-wise comparison instead of a concatenated key string: a cache hit costs
+ * one string value-compare (engines short-circuit on length) and a miss never
+ * allocates a key. Comparing the {@link Theme} by reference is sound because
+ * theme switches replace the instance wholesale (`setTheme`/`previewTheme`/
+ * `setSymbolPreset` in pi-tui theme/theme.ts) — themes are never mutated in
+ * place.
+ */
+export interface RenderedStringCache {
+    theme: Theme | null;
+    expanded: boolean;
+    salt: string;
+    content: string;
+    value: string;
+}
+/** Create an empty memo for rendered tool strings. */
+export declare function createRenderedStringCache(): RenderedStringCache;
+/** Drop the memo so the next lookup re-renders (e.g. the render function identity changed). */
+export declare function invalidateRenderedStringCache(cache: RenderedStringCache): void;
+/** Reuse a rendered string while its theme, expansion, content, and salt match. */
+export declare function cachedRenderedString(cache: RenderedStringCache | undefined, theme: Theme, expanded: boolean, salt: string, content: string, render: () => string): string;
+/**
+ * Append the indented bullet list of parse errors (capped at
+ * {@link PARSE_ERRORS_LIMIT}) to `lines`, with an overflow summary line if the
+ * total exceeds the cap. No-op when `parseErrors` is empty.
+ */
+export declare function appendParseErrorsBulletList(lines: string[], parseErrors: readonly string[] | undefined, theme: Theme, total?: number): void;
+/**
+ * Human-readable summary string for the parse-issues count, capped by
+ * {@link PARSE_ERRORS_LIMIT}.
+ */
+export declare function formatParseErrorsCountLabel(parseErrors: readonly string[], total?: number): string;
+/**
+ * Normalize a path argument that may arrive as a single string, a JSON-encoded
+ * string array (`'["a.ts"]'`), or an actual array into a flat `string[]`.
+ * Delimited single strings (`"a.ts b.ts"`) remain literal.
+ */
+export declare function toPathList(input: string | string[] | undefined): string[];

package/dist/types/render/sixel.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns whether SIXEL passthrough is explicitly enabled.
+ *
+ * Both gates must be enabled to preserve SIXEL control sequences:
+ * - PI_FORCE_IMAGE_PROTOCOL=sixel
+ * - PI_ALLOW_SIXEL_PASSTHROUGH=1
+ */
+export declare function isSixelPassthroughEnabled(): boolean;
+/** Returns true when the text contains a SIXEL start sequence. */
+export declare function containsSixelSequence(text: string): boolean;
+/**
+ * Returns a boolean mask indicating which lines belong to a SIXEL sequence block.
+ * Supports multi-line SIXEL payloads generated by libsixel.
+ */
+export declare function getSixelLineMask(lines: readonly string[]): boolean[];
+/** Returns true when the line contains a SIXEL start sequence. */
+export declare function isSixelLine(line: string): boolean;
+/**
+ * Sanitizes text while preserving embedded SIXEL sequences when passthrough is enabled.
+ */
+export declare function sanitizeWithOptionalSixelPassthrough(text: string, sanitize: (text: string) => string): string;

package/dist/types/render/status-line.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../theme/theme.js";
+import { type ToolUIStatus } from "./render-utils.js";
+/** Status icon, title, description, and metadata for a single header row. */
+export interface StatusLineOptions {
+    icon?: ToolUIStatus;
+    /** Pre-rendered glyph that replaces the status icon (e.g. a magnifier for
+     * search-family tools). Takes precedence over `icon`. */
+    iconOverride?: string;
+    spinnerFrame?: number;
+    title: string;
+    titleColor?: ThemeColor;
+    description?: string;
+    badge?: {
+        label: string;
+        color: ThemeColor;
+    };
+    meta?: string[];
+}
+/** Render a single-line status header, flattening multiline fields. */
+export declare function renderStatusLine(options: StatusLineOptions, theme: Theme): string;

package/dist/types/render/tool-card.d.ts

@@ -0,0 +1,71 @@
+import type { Theme, ThemeColor } from "../theme/theme.js";
+import type { Component } from "../tui.js";
+import { type StatusLineOptions } from "./status-line.js";
+import type { State } from "./types.js";
+/** Lifecycle distinctions shared by tool call and result cards. */
+export type ToolCardPhase = "pending" | "running" | "partial" | "success" | "warning" | "error" | "info";
+/** Fixed card topology. Framed cards own their border; plain cards flow inline. */
+export type ToolCardVariant = "framed" | "plain";
+/** Lazily rendered slot content. Components retain their own width caches. */
+export type ToolCardContent = readonly string[] | Component | ((width: number) => readonly string[] | Component);
+/** A labeled body section in a tool card. */
+export interface ToolCardSection {
+    label?: string;
+    content: ToolCardContent;
+    separator?: boolean;
+}
+/** Snapshot returned by a ToolCard builder on each render. */
+export interface ToolCardSnapshot {
+    /** Pre-rendered header. Prefer `status` for ordinary tool lifecycle rows. */
+    header?: string;
+    /** Structured status header, rendered by the shared status-line primitive. */
+    status?: StatusLineOptions;
+    headerMeta?: string;
+    phase?: ToolCardPhase;
+    body?: ToolCardContent;
+    sections?: readonly ToolCardSection[];
+    footer?: ToolCardContent;
+    applyBg?: boolean;
+    contentPaddingLeft?: number;
+    contentPaddingRight?: number;
+    borderColor?: ThemeColor;
+}
+/** Width information supplied to a ToolCard's lazy snapshot builder. */
+export interface ToolCardBuildContext {
+    width: number;
+    /** Inner width for the default one-column framed padding. */
+    contentWidth: number;
+    /** Compute an inner width when this snapshot opts into custom frame padding. */
+    contentWidthFor(contentPaddingLeft?: number, contentPaddingRight?: number): number;
+}
+/** Construction options whose topology remains fixed for a card's lifetime. */
+export interface ToolCardOptions {
+    variant: ToolCardVariant;
+    paddingX?: number;
+    paddingY?: number;
+    ignoreTight?: boolean;
+    onInvalidate?: () => void;
+    onDispose?: () => void;
+}
+/** Map transcript lifecycle terminology onto the output frame's visual states. */
+export declare function toolCardState(phase: ToolCardPhase | undefined): State | undefined;
+/**
+ * Cached tool-card layout with lazy body/section/footer children. The builder
+ * may read mutable streaming state at render time; unchanged snapshots retain
+ * their rendered array identity through CachedOutputBlock or Text.
+ */
+export declare class ToolCard implements Component {
+    #private;
+    constructor(theme: Theme, options: ToolCardOptions, build: (context: ToolCardBuildContext) => ToolCardSnapshot);
+    render(width: number): readonly string[];
+    get debugChildren(): readonly Component[];
+    get wantsKeyRelease(): boolean;
+    handleInput(data: string): void;
+    setIgnoreTight(ignore: boolean): void;
+    invalidate(): void;
+    dispose(): void;
+}
+/** Construct a lazy framed tool card. */
+export declare function framedToolCard(theme: Theme, build: (context: ToolCardBuildContext) => ToolCardSnapshot, options?: Omit<ToolCardOptions, "variant">): ToolCard;
+/** Construct a lazy inline tool card, optionally state-tinted. */
+export declare function plainToolCard(theme: Theme, build: (context: ToolCardBuildContext) => ToolCardSnapshot, options?: Omit<ToolCardOptions, "variant">): ToolCard;

package/dist/types/render/tree-list.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+import type { Theme } from "../theme/theme.js";
+import type { TreeContext } from "./types.js";
+/** Tree items and callbacks controlling their presentation. */
+export interface TreeListOptions<T> {
+    items: T[];
+    expanded?: boolean;
+    maxCollapsed?: number;
+    /** Strict total-line budget for collapsed mode. When set (and not expanded),
+     *  rendered item lines plus the trailing summary line must fit within this budget.
+     */
+    maxCollapsedLines?: number;
+    itemType?: string;
+    truncateFrom?: "start" | "end";
+    /** Caller-supplied trailing summary line. When set (and not expanded),
+     *  `renderTreeList` renders exactly the provided `items` (the caller has
+     *  already applied its own selection/cap) and appends this text as the
+     *  final `└` row, with the last item using `├`. Empty string renders the
+     *  items with no summary. Bypasses the built-in truncation/`maxCollapsed`
+     *  path. */
+    trailingSummary?: string;
+    /** Called once per item with `isLast: false` during budget calculation;
+     *  line count MUST NOT vary based on `isLast`. */
+    renderItem: (item: T, context: TreeContext) => string | string[];
+}
+/** Render tree items with themed branches and optional expansion. */
+export declare function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[];

package/dist/types/render/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared types for TUI rendering components.
+ */
+import type { Theme } from "../theme/theme.js";
+/** Visual state of a rendered tool output. */
+export type State = "pending" | "running" | "success" | "error" | "warning";
+/** Position and theme context passed to tree item renderers. */
+export interface TreeContext {
+    index: number;
+    isLast: boolean;
+    depth: number;
+    theme: Theme;
+    prefix: string;
+    continuePrefix: string;
+    /** Maximum rendered branch/continuation prefix width reserved during pre-rendering. */
+    prefixWidth?: number;
+}

package/dist/types/render/utils.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared helpers for tool-rendered UI components.
+ */
+import type { Theme, ThemeBg } from "../theme/theme.js";
+import type { State } from "./types.js";
+/**
+ * Incremental xxHash64 key builder.
+ *
+ * Chains `Bun.hash.xxHash64` calls via seeding — each fed value
+ * mixes into the running hash without intermediate string allocations.
+ * Accepts strings, numbers (u32), booleans, bigints, and `undefined`/`null`
+ * (hashed as a sentinel byte) natively.
+ */
+export declare class Hasher {
+    #private;
+    /** Feed a string. */
+    str(s: string): this;
+    /** Feed an unsigned 32-bit integer. */
+    u32(n: number): this;
+    /** Feed a 64-bit bigint. */
+    u64(n: bigint): this;
+    /** Feed a boolean (single byte: 1 = true, 0 = false). */
+    bool(b: boolean): this;
+    /** Feed a value that may be `undefined` or `null` (hashed as a 0xFF sentinel byte). */
+    optional(v: string | undefined | null): this;
+    /** Return the final hash digest. */
+    digest(): bigint;
+}
+/** Render-cache entry used by tool renderers. */
+export interface RenderCache {
+    key: bigint;
+    lines: string[];
+}
+/** Build indentation and continuing branches for ancestor levels. */
+export declare function buildTreePrefix(ancestors: boolean[], theme: Theme): string;
+/** Return the branch glyph for a final or continuing tree item. */
+export declare function getTreeBranch(isLast: boolean, theme: Theme): string;
+/** Return the continuation prefix for subsequent lines of a tree item. */
+export declare function getTreeContinuePrefix(isLast: boolean, theme: Theme): string;
+/** Pad or truncate visible text to exactly `width` columns and optionally apply a background. */
+export declare function padToWidth(text: string, width: number, bgFn?: (s: string) => string): string;
+/** Resolve a tool output state to its background color token. */
+export declare function getStateBgColor(state: State): ThemeBg;

package/dist/types/render/width-aware-text.d.ts

@@ -0,0 +1,23 @@
+import type { Component } from "../tui.js";
+/**
+ * Text whose content is (re)formatted against the actual render width.
+ *
+ * A plain `Text` receives an already-formatted string and only wraps it at
+ * render time, so width-dependent layout (per-line truncation, inline previews)
+ * has to be decided before the width is known. Renderers used to cope by
+ * hard-capping output lines at a fixed column count (e.g. 80), which truncated
+ * to roughly a third of a wide terminal. This defers formatting to
+ * `render(width)`: it computes the same content width the inner `Text` uses
+ * (mirroring its tight-layout flag so the budget can't desync), hands that to
+ * the formatter, and delegates margins/background/vertical padding to the inner
+ * `Text`. Lines the formatter caps at `contentWidth` fit exactly and so never
+ * wrap.
+ */
+export declare class WidthAwareText implements Component {
+    #private;
+    constructor(format: (contentWidth: number) => string, paddingX?: number, paddingY?: number);
+    setCustomBgFn(customBgFn?: (text: string) => string): void;
+    setIgnoreTight(ignore: boolean): this;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/setup/lazy.d.ts

@@ -0,0 +1,3 @@
+import type { SetupHost } from "./scenes/types.js";
+/** Load and run provider setup without completing onboarding or replaying the welcome intro. */
+export declare function runProviderSetupWizard(ctx: SetupHost): Promise<void>;

package/dist/types/setup/scenes/composer.d.ts

@@ -0,0 +1,3 @@
+import type { SetupScene } from "./types.js";
+/** Select and persist the prompt composer layout. */
+export declare const composerSetupScene: SetupScene;

package/dist/types/setup/scenes/glyph.d.ts

@@ -0,0 +1,3 @@
+import type { SetupScene } from "./types.js";
+/** Preview and persist the terminal glyph preset. */
+export declare const glyphSetupScene: SetupScene;

package/dist/types/setup/scenes/model.d.ts

@@ -0,0 +1,3 @@
+import type { SetupScene } from "./types.js";
+/** Setup step that assigns one available model to the persisted default role. */
+export declare const modelSetupScene: SetupScene;

package/dist/types/setup/scenes/outro.d.ts

@@ -0,0 +1,2 @@
+export declare const SETUP_OUTRO_MS = 1200;
+export declare function renderSetupOutro(width: number, height: number, elapsedMs: number): string[];

package/dist/types/setup/scenes/providers.d.ts

@@ -0,0 +1,3 @@
+import type { SetupScene } from "./types.js";
+/** Configure provider sign-in and the preferred web search backend. */
+export declare const providersSetupScene: SetupScene;

package/dist/types/setup/scenes/sign-in.d.ts

@@ -0,0 +1,21 @@
+import { type SgrMouseEvent } from "../../mouse.js";
+import type { SetupSceneHost, SetupTab } from "./types.js";
+/**
+ * "Sign in" panel: lets the user authenticate one or more model providers via
+ * OAuth. Unlike a standalone scene it never auto-advances the wizard — the user
+ * may sign in to several providers and then continue with Esc.
+ */
+export declare class SignInTab implements SetupTab {
+    #private;
+    readonly id = "sign-in";
+    readonly label = "Sign in";
+    constructor(host: SetupSceneHost);
+    /** Modal while an OAuth flow is running so the scene won't switch tabs or finish. */
+    get modal(): boolean;
+    dispose(): void;
+    invalidate(): void;
+    handleInput(data: string): void;
+    /** Forward mouse to the provider selector; pointer is inert during an active login or code prompt. */
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+    render(width: number, maxLines?: number): readonly string[];
+}

package/dist/types/setup/scenes/splash.d.ts

@@ -0,0 +1,11 @@
+export declare const SETUP_SPLASH_MS = 2600;
+export declare const SETUP_TICK_MS = 33;
+export declare function renderStarfield(width: number, height: number, frame: number): string[];
+/**
+ * Animated setup splash, in the spirit of the omp landing page: the brand π
+ * mark rendered with the live diagonal gradient + shine sweep, rising out of a
+ * rippling, gradient-lit water surface, under a faint twinkling starfield. The
+ * mark and water share one continuous gradient so the sweep reads across the
+ * whole scene; the water surface drifts each frame.
+ */
+export declare function renderSetupSplash(width: number, height: number, elapsedMs: number): string[];

package/dist/types/setup/scenes/theme.d.ts

@@ -0,0 +1,3 @@
+import type { SetupScene } from "./types.js";
+/** Preview and persist the terminal color theme. */
+export declare const themeSetupScene: SetupScene;