jeopi-cli 16.2.14 → 16.2.17

package/dist/types/modes/components/snapcompact-shape-preview.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Live preview for the `snapcompact.shape` setting: renders a sample session
+ * transcript through the real snapcompact rasterizer as a miniature page and
+ * shows it zoomed, so cell size, ink hues, highlight bands, and dim tool-result
+ * spans are legible at terminal scale.
+ *
+ * The mini-frame (a {@link SRC_FRAME_PX}px page) is upscaled with
+ * nearest-neighbor so the glyph pixels stay crisp when the terminal scales the
+ * placement box. Graphics display requires the Kitty unicode-placeholder path —
+ * `renderImage` returning `lines` is the gate — because the bordered settings
+ * frame re-fits every row, which direct cursor-positioned placements (iTerm2,
+ * Sixel, Kitty `a=p`) do not survive. Everything else falls back to the stats
+ * line plus a dim notice.
+ */
+import { type ShapeTarget } from "jeopi-snapcompact";
+import { type Component, type ImageBudget } from "jeopi-tui";
+export interface SnapcompactShapePreviewOptions {
+    /** Active model (api + id); resolves what `auto` maps to for this reader. */
+    model?: ShapeTarget;
+    /** Shared TUI image budget: stable graphics ids, transmit-once, exit cleanup. */
+    imageBudget?: ImageBudget;
+    /** Schedules a re-render once an async sample render completes. */
+    requestRender?: () => void;
+}
+export declare class SnapcompactShapePreview implements Component {
+    #private;
+    constructor(currentValue: string, options?: SnapcompactShapePreviewOptions);
+    /** Track the highlighted option; the next render reflects it. */
+    setValue(value: string): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/status-line/component.d.ts

@@ -0,0 +1,94 @@
+import { type Component } from "jeopi-tui";
+import type { AgentSession } from "../../../session/agent-session";
+import type { CollabStatus, EffectiveStatusLineSettings, StatusLineSettings } from "./types";
+export declare class StatusLineComponent implements Component {
+    #private;
+    private session;
+    constructor(session: AgentSession);
+    /**
+     * Re-point the status line at another session (focus proxy). Invalidate: model/context/usage all derive
+     * from it. `focusedAgentId` is the focused subagent id while the view is proxied, undefined for main.
+     */
+    setSession(session: AgentSession, focusedAgentId?: string): void;
+    updateSettings(settings: StatusLineSettings): void;
+    getEffectiveSettingsForTest(): EffectiveStatusLineSettings;
+    setAutoCompactEnabled(enabled: boolean): void;
+    setSubagentCount(count: number): void;
+    /**
+     * Compatibility shim for callers predating the simplified subagent badge.
+     * The status line now intentionally shows only the active count.
+     */
+    setSubagentHubHint(_hint: string | undefined): void;
+    /** Active subagent count as currently displayed (collab state mirroring). */
+    get subagentCount(): number;
+    /**
+     * Reset the currently-attached session's active-time accumulators so
+     * the `time_spent` segment starts from zero. Called from `/clear`,
+     * fresh-session, and joined-collab paths; both the completed
+     * accumulator and any in-flight window are dropped, so a reset
+     * mid-turn ignores the running window (the matching `markActivityEnd`
+     * will see an idle meter and no-op).
+     */
+    resetActiveTime(): void;
+    /**
+     * Mark the currently-attached session as having started a unit of
+     * active processing. Idempotent: a second start while a window is
+     * already open is a no-op, so reentrant `agent_start` events (e.g.
+     * nested auto-compaction loops, focus-controller mid-turn attach onto
+     * an already-running window) do not double-count.
+     */
+    markActivityStart(): void;
+    /**
+     * Close the currently-attached session's open active-processing
+     * window, folding its elapsed time into the accumulator. Idempotent
+     * when the meter is already idle so callers can fire it on every
+     * `agent_end` without guarding.
+     */
+    markActivityEnd(): void;
+    /**
+     * Snapshot of total active-processing time for the currently-attached
+     * session, including any in-flight window. Exposed for the segment
+     * context builder; tests assert against this too.
+     */
+    getActiveMs(): number;
+    setPlanModeStatus(status: {
+        enabled: boolean;
+        paused: boolean;
+    } | undefined): void;
+    setLoopModeStatus(status: {
+        enabled: boolean;
+    } | undefined): void;
+    setGoalModeStatus(status: {
+        enabled: boolean;
+        paused: boolean;
+    } | undefined): void;
+    setCollabStatus(status: CollabStatus | null): void;
+    setHookStatus(key: string, text: string | undefined): void;
+    watchBranch(onBranchChange: () => void): void;
+    dispose(): void;
+    invalidate(): void;
+    /**
+     * Startup redraws only arm a short-delayed task; timeout releases the render
+     * cadence while a late successful fetch can still refresh the cached segment.
+     */
+    refreshUsageInBackground(): void;
+    /**
+     * Used-tokens / context-window totals for the status-line context% segment,
+     * memoized so the per-event redraw stays O(1) when nothing changed.
+     *
+     * The numerator comes from `session.getContextUsage()`, which anchors on the
+     * last assistant's real prompt-token count — so the bar matches the provider
+     * and the `/context` panel — and reports `null` while that count is unknown
+     * (right after compaction, before the next response). Exposed (non-private)
+     * for unit tests and the collab host's state broadcast.
+     */
+    getCachedContextBreakdown(): {
+        usedTokens: number;
+        contextWindow: number;
+    };
+    getTopBorder(width: number): {
+        content: string;
+        width: number;
+    };
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/status-line/component.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modes/components/status-line/context-thresholds.d.ts

@@ -0,0 +1,10 @@
+import type { ThemeColor } from "../../../modes/theme/theme";
+export type ContextUsageLevel = "normal" | "warning" | "purple" | "error";
+export declare function getContextUsageLevel(contextPercent: number, contextWindow: number): ContextUsageLevel;
+/**
+ * Format context usage as `<percent>%/<window>` when the model window is known.
+ * Unknown windows render as `<tokens>/?`, because `0.0%/0` suggests a real
+ * empty context instead of missing provider metadata.
+ */
+export declare function formatContextUsage(contextPercent: number | null | undefined, contextWindow: number, usedTokens?: number): string;
+export declare function getContextUsageThemeColor(level: ContextUsageLevel): ThemeColor;

package/dist/types/modes/components/status-line/git-utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract "owner/repo" from a GitHub remote URL.
+ * Handles HTTPS, SSH (scp-style), and git:// protocols.
+ *
+ * @returns "owner/repo" or null if the URL isn't a recognized GitHub remote.
+ */
+export declare function parseGitHubRepo(remoteUrl: string): string | null;
+/**
+ * Extract the branch name from a remote HEAD ref like "origin/main".
+ * Returns the portion after the first "/" or the whole string if no "/" is present.
+ */
+export declare function parseDefaultBranch(ref: string): string;
+export interface PrCacheContext {
+    branch: string;
+    repoId: string | null;
+}
+export declare function createPrCacheContext(branch: string, repoId: string | null): PrCacheContext;
+export declare function isSamePrCacheContext(a: PrCacheContext | undefined, b: PrCacheContext | undefined): boolean;
+export declare function canReuseCachedPr(cachedPr: {
+    number: number;
+    url: string;
+} | null | undefined, cachedContext: PrCacheContext | undefined, currentContext: PrCacheContext | null): boolean;

package/dist/types/modes/components/status-line/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./component";
+export * from "./presets";
+export * from "./segments";
+export * from "./separators";
+export * from "./types";

package/dist/types/modes/components/status-line/presets.d.ts

@@ -0,0 +1,3 @@
+import type { PresetDef, StatusLinePreset } from "./types";
+export declare const STATUS_LINE_PRESETS: Record<StatusLinePreset, PresetDef>;
+export declare function getPreset(name: StatusLinePreset): PresetDef;

package/dist/types/modes/components/status-line/segments.d.ts

@@ -0,0 +1,5 @@
+import type { RenderedSegment, SegmentContext, StatusLineSegment, StatusLineSegmentId } from "./types";
+export type { SegmentContext } from "./types";
+export declare const SEGMENTS: Record<StatusLineSegmentId, StatusLineSegment>;
+export declare function renderSegment(id: StatusLineSegmentId, ctx: SegmentContext): RenderedSegment;
+export declare const ALL_SEGMENT_IDS: StatusLineSegmentId[];

package/dist/types/modes/components/status-line/separators.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from "../../../modes/theme/theme";
+import type { SeparatorDef, StatusLineSeparatorStyle } from "./types";
+export declare function getSeparator(style: StatusLineSeparatorStyle, theme: Theme): SeparatorDef;

package/dist/types/modes/components/status-line/token-rate.d.ts

@@ -0,0 +1,10 @@
+type MaybeAssistantMessage = {
+    role?: string;
+    timestamp?: number;
+    duration?: number;
+    usage?: {
+        output?: number;
+    };
+};
+export declare function calculateTokensPerSecond(messages: ReadonlyArray<MaybeAssistantMessage>, isStreaming: boolean, nowMs?: number): number | null;
+export {};

package/dist/types/modes/components/status-line/types.d.ts

@@ -0,0 +1,150 @@
+import type { CollabSessionState } from "../../../collab/protocol";
+import type { StatusLinePreset, StatusLineSegmentId, StatusLineSeparatorStyle } from "../../../config/settings-schema";
+import type { AgentSession } from "../../../session/agent-session";
+import type { ActiveRepoContext } from "../../../utils/active-repo-context";
+export type { StatusLinePreset, StatusLineSegmentId, StatusLineSeparatorStyle };
+/** Collab session indicator + (guest-only) host-state override for segments. */
+export interface CollabStatus {
+    role: "host" | "guest";
+    participantCount: number;
+    /** Guest only: host footer snapshot that overrides locally computed values. */
+    stateOverride?: CollabSessionState | null;
+}
+export interface StatusLineSegmentOptions {
+    model?: {
+        showThinkingLevel?: boolean;
+    };
+    path?: {
+        abbreviate?: boolean;
+        maxLength?: number;
+        stripWorkPrefix?: boolean;
+    };
+    git?: {
+        showBranch?: boolean;
+        showStaged?: boolean;
+        showUnstaged?: boolean;
+        showUntracked?: boolean;
+    };
+    time?: {
+        format?: "12h" | "24h";
+        showSeconds?: boolean;
+    };
+}
+export interface StatusLineSettings {
+    preset?: StatusLinePreset;
+    leftSegments?: StatusLineSegmentId[];
+    rightSegments?: StatusLineSegmentId[];
+    separator?: StatusLineSeparatorStyle;
+    segmentOptions?: StatusLineSegmentOptions;
+    showHookStatus?: boolean;
+    sessionAccent?: boolean;
+    /** Drop the theme's `statusLineBg` fill and powerline caps so the bar
+     *  inherits the terminal's default background. */
+    transparent?: boolean;
+    /** Replace the model-segment icon with the thinking-level glyph and drop the
+     *  " · <level>" suffix, so the thinking level reads as a single compact icon. */
+    compactThinkingLevel?: boolean;
+}
+export type EffectiveStatusLineSettings = Required<Pick<StatusLineSettings, "leftSegments" | "rightSegments" | "separator" | "segmentOptions">> & StatusLineSettings;
+export type RGB = readonly [number, number, number];
+export interface SegmentContext {
+    session: AgentSession;
+    /** Focused subagent id while the view is proxied at its session, undefined otherwise. */
+    focusedAgentId?: string | undefined;
+    activeRepo: ActiveRepoContext | null;
+    width: number;
+    options: StatusLineSegmentOptions;
+    /** Render the model segment's thinking level as a compact leading glyph. */
+    compactThinkingLevel: boolean;
+    planMode: {
+        enabled: boolean;
+        paused: boolean;
+    } | null;
+    loopMode: {
+        enabled: boolean;
+    } | null;
+    goalMode: {
+        enabled: boolean;
+        paused: boolean;
+    } | null;
+    collab: CollabStatus | null;
+    usageStats: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        premiumRequests: number;
+        cost: number;
+        tokensPerSecond: number | null;
+    };
+    /** Context usage percent, or null when unknown (e.g. right after compaction). */
+    contextPercent: number | null;
+    contextTokens: number;
+    contextWindow: number;
+    autoCompactEnabled: boolean;
+    subagentCount: number;
+    /**
+     * Active processing time accumulated this session, in ms — the union of
+     * every `agent_start`→`agent_end` window plus the currently-streaming
+     * window if the agent is running. Idle wall-clock never contributes, so
+     * this is what {@link StatusLineSegmentId.time_spent} renders instead of
+     * `Date.now() - sessionStart`.
+     */
+    activeMs: number;
+    git: {
+        branch: string | null;
+        status: {
+            staged: number;
+            unstaged: number;
+            untracked: number;
+        } | null;
+        pr: {
+            number: number;
+            url: string;
+        } | null;
+    };
+    /**
+     * Set when the path cwd is a *linked* git worktree, naming the shared
+     * primary checkout (the project). Lets the path segment collapse the
+     * base-prefixed `<base>/<project>/<worktree>` path to the project name —
+     * the worktree/branch is already shown by the git segment.
+     */
+    worktree: {
+        projectName: string;
+        worktreeName: string;
+    } | null;
+    usage: {
+        tier?: string;
+        fiveHour?: {
+            percent: number;
+            resetMinutes?: number;
+        };
+        sevenDay?: {
+            percent: number;
+            resetHours?: number;
+        };
+    } | null;
+}
+export interface RenderedSegment {
+    content: string;
+    visible: boolean;
+}
+export interface StatusLineSegment {
+    id: StatusLineSegmentId;
+    render(ctx: SegmentContext): RenderedSegment;
+}
+export interface SeparatorDef {
+    left: string;
+    right: string;
+    endCaps?: {
+        left: string;
+        right: string;
+        useBgAsFg: boolean;
+    };
+}
+export interface PresetDef {
+    leftSegments: StatusLineSegmentId[];
+    rightSegments: StatusLineSegmentId[];
+    separator: StatusLineSeparatorStyle;
+    segmentOptions?: StatusLineSegmentOptions;
+}

package/dist/types/modes/components/theme-selector.d.ts

@@ -0,0 +1,11 @@
+import { Container, SelectList, type SgrMouseEvent } from "jeopi-tui";
+/**
+ * Component that renders a theme selector.
+ * Themes must be pre-loaded and passed to the constructor.
+ */
+export declare class ThemeSelectorComponent extends Container {
+    #private;
+    constructor(currentTheme: string, themes: string[], onSelect: (themeName: string) => void, onCancel: () => void, onPreview: (themeName: string) => void);
+    getSelectList(): SelectList;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/modes/components/thinking-selector.d.ts

@@ -0,0 +1,11 @@
+import type { Effort } from "jeopi-ai";
+import { Container, SelectList, type SgrMouseEvent } from "jeopi-tui";
+/**
+ * Component that renders a thinking level selector with borders
+ */
+export declare class ThinkingSelectorComponent extends Container {
+    #private;
+    constructor(currentLevel: Effort, availableLevels: Effort[], onSelect: (level: Effort) => void, onCancel: () => void);
+    getSelectList(): SelectList;
+    routeMouse(event: SgrMouseEvent, line: number, col: number): void;
+}

package/dist/types/modes/components/tiny-title-download-progress.d.ts

@@ -0,0 +1,11 @@
+import { type Component } from "jeopi-tui";
+import { type TinyTitleLocalModelKey } from "../../tiny/models";
+import type { TinyTitleProgressEvent } from "../../tiny/title-protocol";
+export declare class TinyTitleDownloadProgressComponent implements Component {
+    #private;
+    constructor(modelKey: TinyTitleLocalModelKey);
+    update(event: TinyTitleProgressEvent): void;
+    isComplete(): boolean;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/todo-reminder.d.ts

@@ -0,0 +1,15 @@
+import { Container } from "jeopi-tui";
+import type { TodoItem } from "../../tools/todo";
+/**
+ * Component that renders a todo completion reminder notification, committed into
+ * the transcript like a TTSR notification so it stays anchored in history rather
+ * than floating above the editor.
+ * Shows when the agent stops with incomplete todos.
+ */
+export declare class TodoReminderComponent extends Container {
+    #private;
+    private readonly todos;
+    private readonly attempt;
+    private readonly maxAttempts;
+    constructor(todos: TodoItem[], attempt: number, maxAttempts: number);
+}

package/dist/types/modes/components/tool-execution.d.ts

@@ -0,0 +1,124 @@
+import type { AgentTool } from "jeopi-agent-core";
+import type { SnapshotStore } from "jeopi-hashline";
+import { type Component, Container, type NativeScrollbackLiveRegion, type TUI } from "jeopi-tui";
+/**
+ * Transcript-side probe telling a block whether it is still inside the live
+ * (repaintable) region. Implemented by `TranscriptContainer`; injected rather
+ * than imported so the component stays decoupled from the transcript.
+ */
+export interface TranscriptLiveRegionProbe {
+    isBlockInLiveRegion(component: Component): boolean;
+}
+export interface ToolExecutionOptions {
+    snapshots?: SnapshotStore;
+    showImages?: boolean;
+    editFuzzyThreshold?: number;
+    editAllowFuzzy?: boolean;
+    /** Live-region probe used to settle detached task progress once the block
+     * leaves the repaintable transcript region. */
+    liveRegion?: TranscriptLiveRegionProbe;
+}
+export interface ToolExecutionHandle {
+    updateArgs(args: any, toolCallId?: string): void;
+    updateResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+            data?: string;
+            mimeType?: string;
+        }>;
+        details?: any;
+        isError?: boolean;
+    }, isPartial?: boolean, toolCallId?: string): void;
+    setArgsComplete(toolCallId?: string): void;
+    setExpanded(expanded: boolean): void;
+}
+/** Drive pending-tool redraws at 30fps for live tool headers and displaceable
+ * poll blocks. The TUI throttles at the same cadence, and static frames diff to
+ * a no-op redraw at ~zero cost. */
+export declare const SPINNER_RENDER_INTERVAL_MS: number;
+/** Advance the spinner glyph at its classic ~12.5fps step, decoupled from the
+ * render cadence (mirrors `Loader`). */
+export declare const SPINNER_GLYPH_ADVANCE_MS = 80;
+/** Phase-locked spinner glyph index shared by every live tool block so parallel
+ * spinners advance in lockstep instead of each tracking its own start time. */
+export declare function sharedSpinnerFrame(frameCount: number, now?: number): number;
+/**
+ * Component that renders a tool call with its result (updateable)
+ */
+export declare class ToolExecutionComponent extends Container implements NativeScrollbackLiveRegion {
+    #private;
+    constructor(toolName: string, args: any, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: TUI, cwd?: string, _toolCallId?: string);
+    updateArgs(args: any, _toolCallId?: string): void;
+    /**
+     * Signal that args are complete (tool is about to execute).
+     * This triggers an immediate final diff computation for edit-like tools.
+     */
+    setArgsComplete(_toolCallId?: string): void;
+    /**
+     * Await the streaming diff recompute kicked off by the most recent
+     * `updateArgs`/`setArgsComplete`. The recompute reads the file and re-runs the
+     * whole-file Myers diff off the render path, signalling completion only via a
+     * throttled `requestRender`. Tests await this to sample a *settled* preview
+     * deterministically instead of racing the spinner's render ticks.
+     */
+    whenPreviewSettled(): Promise<void>;
+    updateResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+            data?: string;
+            mimeType?: string;
+        }>;
+        details?: any;
+        isError?: boolean;
+    }, isPartial?: boolean, _toolCallId?: string): void;
+    /**
+     * Standalone harnesses may mount a tool component directly under `TUI`
+     * instead of inside `TranscriptContainer`. In that shape the component must
+     * report its own live-region seam for provisional previews, or the core
+     * renderer treats it like shell output and commits tail-window edit/eval/bash
+     * previews to immutable native scrollback before the result replaces them.
+     */
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+    /**
+     * Whether this block has reached a terminal state for transcript freezing.
+     * Reports `false` while it can still visually change so the
+     * {@link TranscriptContainer} keeps it inside the repaintable live region:
+     * a foreground tool awaiting its result, or one streaming partial output.
+     * A final (non-partial) result, a background-async tool the agent has moved
+     * past, or an explicit {@link seal} flips it to `true`.
+     */
+    isTranscriptBlockFinalized(): boolean;
+    /**
+     * Whether this still-live block's settled rows may enter native scrollback
+     * (see `FinalizableBlock.isTranscriptBlockCommitStable`). Renderers classify
+     * pending views by durability instead of by tool name: a provisional view is
+     * allowed to be useful on screen, but finalization may replace or re-anchor
+     * it wholesale, so committing any of its rows would strand stale preview
+     * bytes in immutable scrollback. Non-provisional views stream rows whose
+     * committed prefix survives the remaining transitions.
+     */
+    isTranscriptBlockCommitStable(): boolean;
+    /**
+     * Mark the tool terminal even though no result arrived (the turn aborted or
+     * abandoned it) and stop animating, so it can freeze and stops pinning the
+     * transcript live region.
+     */
+    seal(): void;
+    /**
+     * Whether this block is a supersedable result snapshot that has not been
+     * sealed. Such a block never finalized, so none of its rows entered native
+     * scrollback and the whole block can be removed when a follow-up matching
+     * tool call supersedes it.
+     */
+    isDisplaceableBlock(): boolean;
+    canBeDisplacedBy(nextToolName: string | undefined): boolean;
+    /**
+     * Stop spinner animation and cleanup resources.
+     */
+    stopAnimation(): void;
+    setExpanded(expanded: boolean): void;
+    setShowImages(show: boolean): void;
+    invalidate(): void;
+}

package/dist/types/modes/components/transcript-container.d.ts

@@ -0,0 +1,88 @@
+import { type Component, Container, type NativeScrollbackCommittedRows, type NativeScrollbackLiveRegion, type RenderStablePrefix, type ViewportTailProvider } from "jeopi-tui";
+/**
+ * Transcript container that renders every block's current content each frame
+ * and reports the live-region seam (`NativeScrollbackLiveRegion`) that gates
+ * the engine's append-only scrollback commits.
+ *
+ * The engine never rewrites committed history: rows above the seam that have
+ * entered the tape keep whatever bytes they were committed with ("let the
+ * history be"), while the visible window always repaints from each block's
+ * latest render — a late tool result, a post-finalize error pin, or an expand
+ * toggle is always reflected on screen. Blocks that are still mutating (an
+ * unfinalized tool, a streaming assistant message) stay below the seam so
+ * their rows do not enter history while they can still change; a streaming
+ * block whose render grows append-only deepens the seam through its settled
+ * head so a long reply's scrolled-off rows still reach scrollback mid-stream.
+ *
+ * Assembly is incremental: the returned array is persistent and mutated in
+ * place. Each block's render is still called every frame, but a block whose
+ * render returned the same array reference at an unchanged offset reuses its
+ * previously assembled rows; the array is truncated and re-pushed only from
+ * the first divergent block. The leading byte-identical row count is reported
+ * through {@link RenderStablePrefix} so the engine can skip marker scanning,
+ * line preparation, and the committed-prefix audit for those rows.
+ */
+export declare class TranscriptContainer extends Container implements NativeScrollbackLiveRegion, NativeScrollbackCommittedRows, RenderStablePrefix, ViewportTailProvider {
+    #private;
+    invalidate(): void;
+    clear(): void;
+    setNativeScrollbackCommittedRows(rows: number): void;
+    getRenderStablePrefixRows(): number;
+    getNativeScrollbackLiveRegionStart(): number | undefined;
+    getNativeScrollbackCommitSafeEnd(): number | undefined;
+    getNativeScrollbackSnapshotSafeEnd(): number | undefined;
+    /**
+     * Whether `component` sits below a still-mutating block — i.e. inside the
+     * live region, where its rows cannot have been committed to native
+     * scrollback yet (commits are prefix-only and stop at the first
+     * still-live block). Callers that retract ephemeral blocks (IRC cards)
+     * must check this: removing a block whose rows may already be in history
+     * is an interior deletion of the committed prefix, which the engine can
+     * only repair by recommitting everything below it — duplication.
+     */
+    isWithinLiveRegion(component: Component): boolean;
+    /**
+     * Whether `component` is inside the live (repaintable) region exactly as
+     * {@link render} computes it: at/after the first still-mutating block, or
+     * the transcript tail when every block has finalized. Unlike
+     * {@link isWithinLiveRegion} (strictly below a still-mutating block, i.e.
+     * guaranteed-uncommitted), this also counts the trailing block that anchors
+     * the live region. Self-animating finalized blocks (a detached task's
+     * shimmering progress rows) poll this to stop animating — and settle on
+     * static bytes — the moment they sit above the seam, where their rows
+     * become commit-eligible native-scrollback history.
+     */
+    isBlockInLiveRegion(component: Component): boolean;
+    /**
+     * Render only the bottom `maxRows` rows of the transcript at `width`, walking
+     * blocks from the last toward the first and stopping the instant enough rows
+     * are collected — blocks above the fold are never rendered. The engine's
+     * resize viewport fast path uses this so a drag (a SIGWINCH burst, each event
+     * a fresh width that misses every per-width cache) re-lays-out only the
+     * handful of visible blocks instead of the whole history every event.
+     *
+     * State-isolated by contract: touches none of the persistent full-compose
+     * fields (#lines, #segments, the per-block diff snapshots, the commit/stable
+     * bookkeeping), so the authoritative full render on settle reconciles exactly
+     * as if this never ran. Calling each block's render() still warms its own
+     * per-width cache, which that settle render then reuses for free.
+     *
+     * Consecutive visible blocks are joined by exactly one blank separator, the
+     * same rule render() applies, so the result equals the bottom of a full
+     * render except for an at-most-one-row separator on the topmost included
+     * block — a transient discrepancy the settle paint overwrites.
+     */
+    renderViewportTail(width: number, maxRows: number): readonly string[];
+    render(width: number): readonly string[];
+}
+/**
+ * Groups a run of sibling rows (an IRC card's header + body, a file-mention
+ * list, a bordered command/version panel) into a single transcript child so the
+ * container spaces it as one block — one blank line above, none injected between
+ * its rows. Without this wrapper the rows would be top-level children and the
+ * container would put a blank line between each (and inside any border box).
+ * It is a plain {@link Container}; the named subclass documents intent and makes
+ * every manual block grouping greppable.
+ */
+export declare class TranscriptBlock extends Container {
+}

package/dist/types/modes/components/tree-selector.d.ts

@@ -0,0 +1,31 @@
+import { type Component, Container } from "jeopi-tui";
+import type { TreeFilterMode } from "../../config/settings-schema";
+import type { SessionTreeNode } from "../../session/session-entries";
+/** Filter mode for tree display */
+type FilterMode = TreeFilterMode;
+declare class TreeList implements Component {
+    #private;
+    private readonly currentLeafId;
+    private readonly maxVisibleLines;
+    onSelect?: (entryId: string) => void;
+    onCancel?: () => void;
+    onLabelEdit?: (entryId: string, currentLabel: string | undefined) => void;
+    constructor(tree: SessionTreeNode[], currentLeafId: string | null, maxVisibleLines: number, initialFilterMode?: FilterMode, initialSelectedId?: string);
+    invalidate(): void;
+    getSearchQuery(): string;
+    getSelectedNode(): SessionTreeNode | undefined;
+    updateNodeLabel(entryId: string, label: string | undefined): void;
+    render(width: number): readonly string[];
+    handleInput(keyData: string): void;
+}
+/**
+ * Component that renders a session tree selector for navigation
+ */
+export declare class TreeSelectorComponent extends Container {
+    #private;
+    private readonly onLabelChangeCallback?;
+    constructor(tree: SessionTreeNode[], currentLeafId: string | null, terminalHeight: number, onSelect: (entryId: string) => void, onCancel: () => void, onLabelChangeCallback?: ((entryId: string, label: string | undefined) => void) | undefined, initialFilterMode?: FilterMode);
+    handleInput(keyData: string): void;
+    getTreeList(): TreeList;
+}
+export {};