@oh-my-pi/pi-tui 18.16.0 → 18.17.0

package/dist/types/chat/spotlight.d.ts

@@ -0,0 +1,203 @@
+import type { TspPropNode, TspTone } from "@oh-my-pi/pi-wire";
+import type { NativeNode, NativeUiEvent } from "../native/node.js";
+import type { Component } from "../tui.js";
+/** Original lines a result's heat and the sheet cover; later lines are shown in neither. */
+export declare const SPOTLIGHT_VIEW_LINES = 5000;
+/** The original of a result whose text shaping changed. */
+export interface SpotlightOriginal {
+    /** Session artifact holding the original text (`artifact://N`). */
+    url: string;
+    /** Its line count. */
+    lines: number;
+    /** Line number of its first line: a `read` window's first file line, else 1. */
+    start: number;
+    /** The file a `read` showed (picks the sheet's grammar). */
+    path?: string;
+    /**
+     * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): Spotlight's score as
+     * `0`–`9` relative to the result's hottest line, `-` for a line it never scored. Lines past the end are unscored.
+     */
+    heat: string;
+    /** Runs of original lines the model was shown verbatim, `[first, last]` 1-based positions in the original. */
+    kept: [number, number][];
+    /**
+     * One {@link SpotlightReason} character per original line, over the span {@link heat} covers: why shaping showed or
+     * hid the line. Absent on traces written before it.
+     */
+    why?: string;
+    /** How the step that cut by rank chose its lines; absent when no step ranked them. */
+    rank?: SpotlightRank;
+    /**
+     * One entry per line of the text the model saw (of a held-out result: the text it would have seen): the original
+     * line it shows (1-based position in the original), the `[first, last]` run a marker stands for, or null for a line
+     * of its own (a shaping note).
+     */
+    map?: (number | [number, number] | null)[];
+    /** A held-out result's would-be text, the cut the model was not shown (`artifact://N`). */
+    shapedUrl?: string;
+}
+/**
+ * Why shaping showed or hid one original line ({@link SpotlightOriginal.why}). Shown: `a` won on its score, `s`
+ * structure kept regardless of score (head and tail lines, signatures, headings, table headers), `n` named by the
+ * intent or the conversation, `c` context (a neighbour of a chosen line, or a lone gap filled). Hidden: `b` ranked
+ * below the cutoff or past the budget, `r` seen in an earlier call, `f` folded by structure (an outline body, a doc
+ * section, test-run noise, dump rows). `-` unknown.
+ */
+export type SpotlightReason = "a" | "s" | "n" | "c" | "b" | "r" | "f" | "-";
+/** Whether a {@link SpotlightReason} shows the line. */
+export declare function reasonShows(reason: SpotlightReason): boolean;
+/** The reason for original line `i` (0-based), or undefined past the trace or without one. */
+export declare function reasonAt(why: string | undefined, i: number): SpotlightReason | undefined;
+/**
+ * The ranking of the step that cut by rank ({@link SpotlightOriginal.rank}): a line's score is the sum of its parts,
+ * and the step kept the best lines while its budget lasted.
+ */
+export interface SpotlightRank {
+    /**
+     * The parts a score adds up, in order, each in [0, 1] (shaping writes one; older traces may carry two, the ranks of
+     * `Spotlight` and of `word overlap`).
+     */
+    parts: string[];
+    /** The highest score a line can reach. */
+    max: number;
+    /** Per part, its value on every original line over the span {@link SpotlightOriginal.heat} covers ({@link encodeRankPart}). */
+    values: string[];
+    /** The lowest score the step kept on rank. */
+    cutoff: number;
+    /** Characters the step could show, and how many it showed; absent for a step with no character budget. */
+    budget?: number;
+    used?: number;
+    /** The last line kept on rank (1-based position in the original) and the characters it cost. */
+    last?: {
+        line: number;
+        chars: number;
+    };
+}
+/** One {@link SpotlightRank.values} entry: two base-36 digits per line, each value relative to `max`. */
+export declare function encodeRankPart(values: readonly number[], max: number): string;
+/** The value of original line `i` (0-based) in an {@link encodeRankPart} string; 0 past its end. */
+export declare function rankPartAt(encoded: string, i: number, max: number): number;
+/**
+ * What a result's Spotlight requests sent besides the output lines they ranked (`POST /v1/spotlight`): the agent's
+ * state at the call, the command that produced the output, the question its lines were ranked under, and the model.
+ */
+export interface SpotlightRequestParams {
+    /** The user's first message of the session. */
+    task: string;
+    /** Up to three earlier bash commands of the session, oldest first. */
+    commands: string[];
+    /** The agent's text before the call. */
+    said: string;
+    /** The call's intent argument. */
+    intent: string;
+    /** The command, code or `read <path>` that produced the output. */
+    source: string;
+    /** The probe the lines were ranked under: Spotlight scores each line's relevance to the agent's current call. */
+    probe: string;
+    model: string;
+    thinking: string;
+}
+/** `details.spotlight`: one tool result as shaping left it. */
+export interface SpotlightDetails {
+    tool: string;
+    /** The shaping steps that ran (`outline`, `window`, …; `none` for a passthrough). */
+    steps: string[];
+    inChars: number;
+    outChars: number;
+    /** o200k tokens of the original and of the text the model saw. */
+    inTokens: number;
+    outTokens: number;
+    /**
+     * Size of the plain (unshaped) result for the same call (a spilled output's capped text, a read's page), notices
+     * included. Absent on traces written before pi recorded it.
+     */
+    plainChars?: number;
+    plainTokens?: number;
+    /**
+     * `plainTokens - outTokens` for a changed (or held-out) result, else 0: negative for a column-cap cut longer than
+     * the preview it replaced. On older traces `inTokens - outTokens`.
+     */
+    savedTokens: number;
+    /** The score-free coin skipped Spotlight: the result was shaped by the no-score rules. Absent otherwise. */
+    scoreFree?: boolean;
+    /**
+     * The cut saved too few tokens against the plain result to apply, so the model got the plain text (`steps` ends
+     * with `plain-cap`, the out sizes are the plain text's): the would-be cut's size. Absent otherwise.
+     */
+    cappedChars?: number;
+    cappedTokens?: number;
+    /**
+     * Shaping would have changed the text, but the result was held out at random: the model saw the plain result. The
+     * sizes, steps and {@link original} describe the would-be cut. Absent otherwise.
+     */
+    holdout?: boolean;
+    /**
+     * Transcripts from before the edit gate was removed: the gate kept a read pi guessed the agent would edit whole, and
+     * the model got the plain page. Like {@link holdout}, the sizes, steps and {@link original} describe the would-be
+     * cut, but `savedTokens` is 0. pi no longer writes it.
+     */
+    gated?: boolean;
+    /** Present only when shaping changed the text, or would have ({@link holdout}, {@link gated}). */
+    original?: SpotlightOriginal;
+    /** Present with {@link original} when Spotlight ranked the result's lines. */
+    request?: SpotlightRequestParams;
+}
+/**
+ * Tokens the shaped text saves against the plain result (negative: it costs more), or against the original on
+ * traces without {@link SpotlightDetails.plainTokens}.
+ */
+export declare function spotlightSaving(spotlight: SpotlightDetails): number;
+/** The trace a result's details carry, or undefined when the experiment did not shape it. */
+export declare function spotlightDetails(details: unknown): SpotlightDetails | undefined;
+/** The {@link SpotlightOriginal.heat} of per-line scores: each relative to the best, in ten steps. */
+export declare function encodeHeat(scores: readonly (number | null)[]): string;
+/** The heat of original line `i` (0-based) in [0, 1], or undefined when Spotlight never scored it. */
+export declare function heatAt(heat: string, i: number): number | undefined;
+/** {@link SpotlightOriginal.kept} of a per-line kept mask. */
+export declare function keptRanges(kept: readonly boolean[]): [number, number][];
+/** Whether original line `i` (0-based) scored hot: a heat digit of {@link HOT_DIGIT} or more. */
+export declare function spotlightHot(heat: string, i: number): boolean;
+/**
+ * The tone the sheet and the notice give original line `i` (0-based): why shaping showed it (`accent` score,
+ * `neutral` structure, `user` named, `info` context), `error` for a hidden line that scored hot; undefined for any
+ * other hidden line and for a line without a reason.
+ */
+export declare function spotlightTone(original: SpotlightOriginal, i: number): TspTone | undefined;
+/**
+ * The hover card of a changed result's notice: its heat as at most {@link NOTICE_BARS} bars (each the hottest of its
+ * lines, tinted by the most notable reason among them), then how many lines the model was shown, or of a held-out
+ * result would have been.
+ */
+export declare function spotlightNoticeCard(original: SpotlightOriginal, heldOut?: boolean): TspPropNode;
+/**
+ * The notice row under one tool card (role `omp.tool.spotlight`, key `spotlight:<toolCallId>`): muted for a
+ * passthrough (its star alone, named by its tooltip) and for a held-out result, accent for a changed result
+ * ({@link noticeSpans}). One with an original (changed or held out) has a hover card charting its heat
+ * ({@link spotlightNoticeCard}) and a click that opens its sheet through the host's transcript actions. A native
+ * transcript block of its own, placed right after its card ({@link Component.nativeTrailers}), so it shows while the
+ * card is collapsed; nothing in the terminal rows.
+ */
+export declare class SpotlightNotice implements Component {
+    #private;
+    constructor(toolCallId: string, spotlight: SpotlightDetails, reduced: string);
+    update(spotlight: SpotlightDetails, reduced: string): void;
+    /** Hidden with its card (tool activity hidden). */
+    setHidden(hidden: boolean): void;
+    describe(): NativeNode;
+    /** Never mounted in the terminal rows. */
+    render(): readonly string[];
+    invalidate(): void;
+    handleNativeEvent(event: NativeUiEvent): void;
+}
+/** The notices of one transcript block's calls, in the order the calls first reported a trace. */
+export declare class SpotlightNotices {
+    #private;
+    /** Records call `toolCallId`'s final result; true when a notice appeared or went. */
+    set(toolCallId: string, details: unknown, reduced: string): boolean;
+    setHidden(hidden: boolean): void;
+    /**
+     * The notice blocks, the same array while none came or went; `shown` drops the notices of calls a
+     * transcript presenter hides (a fresh array then).
+     */
+    list(shown?: (toolCallId: string) => boolean): readonly Component[];
+}

package/dist/types/chat/tool-execution.d.ts

@@ -11,11 +11,18 @@ export interface ToolExecutionUi {
     requestComponentRender(component: Component): void;
     resetDisplay(): void;
     imageBudget?: TUI["imageBudget"];
+    showOverlay?: TUI["showOverlay"];
+    setFocus?: TUI["setFocus"];
+    terminal?: {
+        readonly rows: number;
+    };
 }
 export interface ToolExecutionOptions {
     showImages?: boolean;
     /** Allow the name-keyed renderer registry only when the active tool is the built-in implementation. */
     useBuiltInRenderer?: boolean;
+    /** Ask the extension transcript presenters; false for a replayed transcript (overlays). Default: true. */
+    transcriptPresenters?: boolean;
 }
 /** A tool result or progress frame as a card shows it. */
 export interface ToolResultFrame {
@@ -59,21 +66,25 @@ export declare function isSettledJobFrame(details: unknown): boolean;
  * a cancelled one keeps the output it got to and seals the card as cancelled.
  */
 export declare function settleWithJobFrame(component: ToolExecutionHandle, frame: ToolResultFrame, toolCallId: string): void;
-/** 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;
 /** Stop the shared spinner ticker and drop every registered live block.
  *  Called on interactive-mode teardown so a stray live block cannot keep the
- *  process-wide 80ms interval alive past shutdown (lingering event-loop
+ *  process-wide spinner timer alive past shutdown (lingering event-loop
  *  handles pin the process; cf. `postmortem.quit`). Test files that assert on
  *  ticker arming also use this to start from a clean slate. */
 export declare function stopSharedSpinnerTicker(): void;
+/** Whether the shared spinner ticker has a tick armed. Test seam: other timers on a fake clock
+ *  (collab relay heartbeats) make a raw timer count ambiguous. */
+export declare function sharedSpinnerTickerArmed(): boolean;
 /**
  * Component that renders a tool call with its result (updateable)
  */
 export declare class ToolExecutionComponent extends Container {
     #private;
     constructor(toolName: string, args: unknown, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: ToolExecutionUi, _cwd?: string, toolCallId?: string);
+    /** Handle exactly the shared native action vocabulary; inspector uses this same controller. */
+    shellVizAction(action: string): void;
+    /** Open the focused inspector without intercepting composer input while it is closed. */
+    openShellVisualizer(): void;
     updateArgs(args: unknown, _toolCallId?: string): void;
     /**
      * Signal that args are complete (tool is about to execute).
@@ -146,6 +157,16 @@ export declare class ToolExecutionComponent extends Container {
     setExpanded(expanded: boolean): void;
     /** Mirrors the card collapsed or expanded in the terminal, so `Ctrl+O` and native toggles share one state. */
     handleNativeEvent(event: NativeUiEvent): void;
+    /**
+     * Blocks of their own right after the card: the result's Spotlight notice (visible while it is
+     * collapsed), and late diagnostics the card absorbed while a presenter compacts or hides it, so
+     * they stay visible.
+     */
+    nativeTrailers(): readonly Component[];
+    refreshTranscriptPresentation(ids?: ReadonlySet<string>): boolean;
+    /** The streamed call's id changed (or an empty one was filled in): presenters see, and refresh by, the new one. */
+    renameToolCallId(toolCallId: string): void;
+    isTranscriptBlockCompact(): boolean;
     /** Whether this call targets `filePath` (the late-diagnostics router matches with it). */
     matchesPath(filePath: string): boolean;
     /**
@@ -163,7 +184,7 @@ export declare class ToolExecutionComponent extends Container {
      * `elapsed` timer in the head and terminal-local collapse clamped to the
      * view's preview. Renderers without describe hooks (and extension tools
      * with only render hooks) get the generic card. Hidden tool activity stays
-     * mounted so toggling it is one prop change.
+     * mounted so toggling it is one prop change; a presenter's answer applies on top.
      */
     describe(cx?: DescribeContext): NativeNode;
     /** Apply the transcript allocator's current viewport reservation. */

package/dist/types/chat/transcript-actions.d.ts

@@ -4,6 +4,7 @@
  * the interactive host registers the one handler that runs omp's existing
  * commands for them, so a click and the key binding take the same path.
  */
+import type { SpotlightDetails } from "./spotlight.js";
 export type TranscriptAction = 
 /** Retry the last failed turn (`app.retry`). */
 {
@@ -26,6 +27,16 @@ export type TranscriptAction =
  | {
     readonly act: "copy";
     readonly text: string;
+}
+/**
+ * Open the Spotlight sheet of a shaped tool result: its original beside `reduced`, the text the model saw (a
+ * held-out result's sheet shows the would-be text its trace's `shapedUrl` names instead).
+ */
+ | {
+    readonly act: "spotlight";
+    readonly toolCallId: string;
+    readonly spotlight: SpotlightDetails;
+    readonly reduced: string;
 };
 type Handler = (action: TranscriptAction) => void;
 /** Register (or clear, with `undefined`) the host's handler. */

package/dist/types/chat/transcript-browser.d.ts

@@ -79,8 +79,17 @@ export declare class TranscriptBrowser implements Component {
     handleScrollKey(data: string): boolean;
     scrollToTop(): void;
     scrollToBottom(): void;
+    /** Whether the view shows the first body row. */
+    get atTop(): boolean;
+    /** One past the last logical body row in view. */
+    get visibleEnd(): number;
     /** Whether an anchor identity has successfully been applied to the viewport. */
     hasAnchored(id: string): boolean;
+    /**
+     * What to add to a body row of the last frame to get its logical body row, as
+     * {@link toContentPoint} maps it; it follows the scroll, so a content row keeps its sum.
+     */
+    get frameRowOffset(): number;
     /**
      * Translate a 0-based frame mouse point into the logical, scrolled body.
      * Returns undefined for borders, header/footer rows, and unpainted body rows.

package/dist/types/chat/transcript-presentation.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Extension transcript presenters (`pi.registerTranscriptPresenter`). The host installs them with
+ * {@link setTranscriptPresenters}; each presentable block draws from its
+ * {@link TranscriptPresentationState}.
+ */
+import type { TspText } from "@oh-my-pi/pi-wire";
+import { type Component, Container } from "../tui.js";
+import { type DescribeContext, type NativeNode, type NativeUiEvent } from "../native/node.js";
+import type { AnimationFrame, CompactTranscriptBlock } from "../chrome/transcript-container.js";
+import type { TranscriptBlock, TranscriptPresentation, TranscriptPresenter } from "./extension-types.js";
+import { type BashExecutionMessage, type CustomMessage, type HookMessage, type PythonExecutionMessage } from "./messages.js";
+/** A block's presentation once every presenter has answered. */
+export type ResolvedPresentation = {
+    readonly mode: "full";
+} | {
+    readonly mode: "hidden";
+} | {
+    readonly mode: "compact";
+    readonly label?: TspText;
+    readonly rows: readonly TspText[];
+};
+export type CompactPresentation = Extract<ResolvedPresentation, {
+    mode: "compact";
+}>;
+/**
+ * Install the presenters the transcript draws with, in extension load order; true when the set
+ * changed. They are called as given: the installer guards them (the extension runner reports a
+ * throw or an unknown answer, and answers `"full"` instead).
+ */
+export declare function setTranscriptPresenters(next: readonly TranscriptPresenter[]): boolean;
+/** An extension registered or disposed a presenter; the host installs the set again and refreshes. */
+export declare function notifyTranscriptPresentersChanged(): void;
+/** Call `listener` on {@link notifyTranscriptPresentersChanged}; returns the unsubscribe. */
+export declare function onTranscriptPresentersChanged(listener: () => void): () => void;
+/**
+ * Call `listener` when a block draws a presentation other than the one it last drew, outside a
+ * refresh (a late result, say): the host replays the scrollback when that block has rows in it.
+ * Returns the unsubscribe.
+ */
+export declare function onTranscriptPresentationRedrawn(listener: (owner: Component) => void): () => void;
+/**
+ * A presenter's answer as plain data when it is a {@link TranscriptPresentation}; `null` for
+ * anything else (a misspelt mode, the Promise of an async presenter, a `compact` that is not a
+ * plain object), which draws the block in full. It reads every field the transcript uses once,
+ * so a throwing getter or Proxy in the answer throws here, inside the caller's guard, and never
+ * while drawing. Labels and rows that are not `TspText` are dropped.
+ */
+export declare function readTranscriptPresentation(answer: unknown): TranscriptPresentation | null;
+/**
+ * One block's presentation, resolved lazily after {@link markStale}. The resolved object keeps
+ * its identity while the answer is the same, so it can sit in render memo keys.
+ */
+export declare class TranscriptPresentationState {
+    #private;
+    /**
+     * `snapshot` is the block presenters see (`undefined`: always full); `expanded` tells whether
+     * the user expanded it, which always draws it in full. `owner` is the transcript block it draws
+     * ({@link onTranscriptPresentationRedrawn} names it).
+     */
+    constructor(snapshot: () => TranscriptBlock | undefined, expanded: () => boolean, owner?: Component);
+    /** The block's data changed: ask again before the next draw. */
+    markStale(): void;
+    /** What the block draws now. */
+    get shown(): ResolvedPresentation;
+    /** The last answer {@link shown} resolved, without asking the presenters again. */
+    get resolved(): ResolvedPresentation;
+    /** {@link shown}, for the block's render or description: what {@link refresh} compares against. */
+    draw(): ResolvedPresentation;
+    /**
+     * The block's data changed where nothing may draw it again (rows retired to scrollback): ask now,
+     * and report an answer other than the drawn one as {@link draw} would. What was drawn stays the
+     * baseline until the block draws again.
+     */
+    recheck(): void;
+    /**
+     * Ask again now when `ids` selects this block (every block when `undefined`); true when the
+     * answer differs from what the block last drew. A block in terminal scrollback is not drawn
+     * again, so a change its data made since (a late result) still counts. A change it reports is
+     * the caller's to redraw, so the next draw does not report it again.
+     */
+    refresh(ids?: ReadonlySet<string>): boolean;
+}
+/** A transcript block whose display presenters choose. */
+export interface TranscriptPresentable {
+    /**
+     * Ask again for the parts whose id is in `ids` (all when `undefined`); true when the drawing
+     * changed. True obliges the caller to redraw the block (and replay scrollback holding its rows):
+     * the change is not reported again.
+     */
+    refreshTranscriptPresentation(ids?: ReadonlySet<string>): boolean;
+}
+export declare function isTranscriptPresentable(component: Component): component is Component & TranscriptPresentable;
+/**
+ * A compact block's terminal rows: `• <head>` (the presenter's `label` replacing `head`), then one
+ * indented row per presenter row. Plain strings arrive sanitized (see `normalize`) and keep their
+ * spacing; span arrays are styled.
+ */
+export declare function compactRows(head: string, presentation: CompactPresentation, width: number, glyph?: string): string[];
+/** omp's own one-row head: the bold title, then a muted detail (raw input, sanitized to one line). */
+export declare function compactHead(title: string, detail?: string): string;
+/** How a block names itself in a compact native card when its full drawing is not a `tool` node. */
+export interface CompactNativeHead {
+    readonly role: string;
+    readonly title: string;
+    readonly target?: TspText;
+}
+/**
+ * A block's native drawing under `presentation`. Hidden stays mounted through the `hidden` prop.
+ * Compact folds a `tool` node to one inline, collapsed row (its toggle asks for the full block);
+ * any other drawing becomes the body of a collapsed card headed by `head`.
+ */
+export declare function presentNative(full: NativeNode, presentation: ResolvedPresentation, head: CompactNativeHead): NativeNode;
+type WrappedTranscriptBlock = Exclude<TranscriptBlock, {
+    type: "toolCall";
+}>;
+/** The `message` block of a session message: its id is the decimal `timestamp`. */
+export declare function messageBlock(message: CustomMessage | HookMessage | BashExecutionMessage | PythonExecutionMessage): WrappedTranscriptBlock;
+/** A process-unique id for an `event` block. */
+export declare function eventBlockId(kind: string): string;
+/** Transcript hooks a wrapped component may have; the wrapper forwards the ones it has. */
+interface WrappedComponent extends Component, CompactTranscriptBlock {
+    setExpanded?(expanded: boolean): void;
+    /**
+     * Whether the user expanded it, including through a nested disclosure no root toggle reports
+     * (the skill's `prompt`). True forces the block full, so it must default to false.
+     */
+    isExpanded?(): boolean;
+    setToolActivityVisible?(visible: boolean): void;
+    isTranscriptBlockFinalized?(): boolean;
+    setTranscriptAllocation?(rows: number, frame: AnimationFrame): void;
+}
+/**
+ * A non-tool transcript block (advisor, skill, late diagnostics, `!`/`$` run, background job,
+ * supervised process, TTSR, todo reminder) with the presenters' answer applied around the
+ * component that draws it. In full it draws and describes as `inner` does; expansion, native
+ * events, tool-activity visibility and finalization reach `inner`.
+ */
+export declare class PresentedBlock<T extends WrappedComponent = WrappedComponent> extends Container implements TranscriptPresentable {
+    #private;
+    readonly inner: T;
+    /** Only where `inner` has it: the transcript container detects tool activity by its presence. */
+    readonly setToolActivityVisible?: (visible: boolean) => void;
+    constructor(inner: T, block: WrappedTranscriptBlock);
+    get block(): WrappedTranscriptBlock;
+    /**
+     * The block's data changed (a `!`/`$` run was recorded, TTSR rules merged in). A block already
+     * in scrollback is not drawn again, so a changed answer is reported now for a one-time replay.
+     */
+    setBlock(block: WrappedTranscriptBlock): void;
+    setExpanded(expanded: boolean): void;
+    /** The compact row's toggle, or `inner`'s own root toggle, expands the block. */
+    handleNativeEvent(event: NativeUiEvent): void;
+    refreshTranscriptPresentation(ids?: ReadonlySet<string>): boolean;
+    isTranscriptBlockFinalized(): boolean;
+    /** A squeezed compact block keeps its head and as many rows as fit; in full, `inner` decides. */
+    setTranscriptAllocation(rows: number, frame: AnimationFrame): void;
+    /** Compact while drawn as compact rows; in full, as compact as `inner` says. */
+    isTranscriptBlockCompact(): boolean;
+    /** The cached head row carries theme colours and glyphs. */
+    invalidate(): void;
+    render(width: number): readonly string[];
+    describe(cx: DescribeContext): NativeNode | null;
+}
+export {};

package/dist/types/chat/ttsr-notification.d.ts

@@ -16,6 +16,8 @@ export declare class TtsrNotificationComponent extends Container {
     #private;
     constructor(rules: NotificationRule[]);
     setToolActivityVisible(visible: boolean): void;
+    /** A snapshot: {@link addRules} grows the block's own list in place. */
+    get rules(): readonly NotificationRule[];
     /** Merge additional rules into this block (deduped by rule name). */
     addRules(rules: NotificationRule[]): void;
     setExpanded(expanded: boolean): void;

package/dist/types/chrome/message-frame.d.ts

@@ -59,4 +59,6 @@ export declare class FramedMessageComponent<M extends FramedMessage> extends Con
      */
     describe(): NativeNode;
     handleNativeEvent(event: NativeUiEvent): void;
+    /** Packs with neighboring compact blocks while the extension renderer's component reports compact rows. */
+    isTranscriptBlockCompact(): boolean;
 }

package/dist/types/chrome/transcript-container.d.ts

@@ -1,5 +1,5 @@
 import { type Component, Container, type HistoryBatch } from "../tui.js";
-import type { NativeNode } from "../native/node.js";
+import type { DescribeContext, NativeNode } from "../native/node.js";
 /** Shared animation time supplied by the constrained transcript root. */
 export interface AnimationFrame {
     readonly tick: number;
@@ -42,6 +42,17 @@ export interface AppendOnlyTranscriptBlock {
      */
     resetTranscriptStableRows?(): void;
 }
+/**
+ * Lets a block pack against its neighbors. Two consecutive compact blocks
+ * (blocks that draw nothing between them don't count) have no blank separator
+ * row between them in the terminal, and a native (TSP) surface groups each
+ * such run into one gapless entry. The hook is read every frame, so a block
+ * may change its answer at any time (expanded, collapsed, re-presented).
+ */
+export interface CompactTranscriptBlock {
+    /** Whether the block's current presentation is compact rows. */
+    isTranscriptBlockCompact?(): boolean;
+}
 /**
  * Block lifecycle:
  * - `active`: still mutating; renders live and counts against tool admission.
@@ -156,17 +167,27 @@ export declare class TranscriptContainer extends Container {
      */
     renderTail(width: number, maxRows: number): readonly string[];
     /**
-     * The transcript's blocks for a native (TSP) surface, one component per
-     * `main` child in transcript order; ids follow component identity, so
+     * The transcript's blocks for a native (TSP) surface, one `main` child
+     * per block in transcript order; ids follow component identity, so
      * inserts, removals (rewind, displacement) and reorders become targeted ops.
      * Finalized blocks are settled as a hint; they stay editable, so a later
      * expansion, late result or reaction still reaches them wherever they sit.
+     * A block's {@link Component.nativeTrailers} follow it as blocks of their own.
      * No retirement happens on this path: the whole transcript is one document.
-     * Returns the same array while the block list is unchanged.
+     *
+     * Each run of two or more consecutive compact blocks
+     * ({@link CompactTranscriptBlock}), with any blocks between them that
+     * describe nothing at `cx`, is one gapless entry whose members stay
+     * component children, keeping their own description, wire id and native
+     * events. A compact block's trailers are members of its run; a trailer of
+     * any other block is not. The entry is the same object while the same block
+     * leads the run, and it never settles: a member joining later may still be live.
+     *
+     * Returns the same array while the entries are unchanged.
      */
-    nativeBlocks(): readonly Component[];
+    nativeBlocks(cx: DescribeContext): readonly Component[];
     /** Embedded as a child (transcript viewers): a stack of the {@link nativeBlocks}. */
-    describe(): NativeNode;
+    describe(cx: DescribeContext): NativeNode;
     /** Full semantic render used by exports and non-terminal commands. */
     render(width: number): readonly string[];
     /** Rendered row where a child's block begins in the last full render() (transcript deep-links). */

package/dist/types/components/loader.d.ts

@@ -3,8 +3,6 @@ import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.
 import { type ShimmerPalette } from "../theme/shimmer.js";
 import type { TUI } from "../tui.js";
 import { Text } from "./text.js";
-/** Milliseconds between spinner-frame advances; exported so time-derived spinners elsewhere tick at the Loader cadence. */
-export declare const SPINNER_ADVANCE_MS = 80;
 /** A working-row variant (§6.5): a retry countdown, or context compaction. */
 export type WorkingRowVariant = {
     readonly kind: "retry";

package/dist/types/components/markdown.d.ts

@@ -138,7 +138,8 @@ export declare function getMarkdownLinkUrls(text: string): string[];
  * Each function takes text and returns styled text with ANSI codes.
  */
 export interface MarkdownTheme {
-    heading: (text: string) => string;
+    /** Color a heading; `depth` is its level, 1–6. Bold/underline/`#` prefix are already applied. */
+    heading: (text: string, depth: number) => string;
     link: (text: string) => string;
     linkUrl: (text: string) => string;
     /** Resolve the OSC 8 destination without changing visible text; undefined preserves the authored URL. */
@@ -154,6 +155,15 @@ export interface MarkdownTheme {
     italic: (text: string) => string;
     strikethrough: (text: string) => string;
     underline: (text: string) => string;
+    /**
+     * Style `**strong**` spans, including their weight. Omitted → {@link bold}.
+     * A theme that colors them owns the span's foreground over a `proseFg` default.
+     */
+    strong?: (text: string) => string;
+    /** Style `*emphasis*` spans, including their slant. Omitted → {@link italic}; colors win like {@link strong}. */
+    emphasis?: (text: string) => string;
+    /** Style table header cells, including their weight. Omitted → {@link bold}; colors win like {@link strong}. */
+    tableHeader?: (text: string) => string;
     highlightCode?: (code: string, lang?: string) => string[];
     /**
      * Create a stateful incremental highlighter for one streaming code fence.

package/dist/types/components/settings-list.d.ts

@@ -3,6 +3,8 @@ import type { TspPrefsControl, TspPrefsRow, TspPrefsSection } from "@oh-my-pi/pi
 import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node.js";
 import type { Component } from "../tui.js";
 import { FormField, type FormFieldOptions, type FormFieldTheme } from "./form.js";
+/** Builds a row's editor from its current value; `done` closes it, with the value picked if one was. */
+export type SettingEditor = (currentValue: string, done: (selectedValue?: string) => void) => Component;
 export interface SettingItem {
     /** Unique identifier for this setting */
     id: string;
@@ -17,7 +19,12 @@ export interface SettingItem {
     /** If provided, Enter/Space cycles through these values */
     values?: string[];
     /** If provided, Enter opens this submenu. Receives current value and done callback. */
-    submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
+    submenu?: SettingEditor;
+    /**
+     * A `values` row's choices as a menu: a native settings page's popup button
+     * opens it ({@link SettingsList.openSubmenuFor}); Enter/Space still cycle.
+     */
+    menu?: SettingEditor;
     /** True when the displayed setting differs from its default value. */
     changed?: boolean;
     /** The default, as a native settings page names it in the changed dot's title. */
@@ -142,7 +149,10 @@ export declare class SettingsList implements Component {
     prefsEditing(inlineMenu: (id: string) => boolean): PrefsEditing | null;
     /** Applies `value` to a cycling (boolean/enum) row the way Enter does: the row shows it and `onChange` runs. */
     applyValue(id: string, value: string): void;
-    /** Opens row `id`'s submenu the way Enter does (leaving one already open for it); returns it. */
+    /**
+     * Opens row `id`'s submenu (a cycling row's `menu`) the way Enter opens a
+     * submenu, leaving one already open for it; returns it.
+     */
     openSubmenuFor(id: string): Component | undefined;
     /** Resize the visible viewport (fullscreen hosts call this every render). */
     setMaxVisible(rows: number): void;

package/dist/types/frame-rate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The frame-rate ceiling (`tui.maxFps`): the render scheduler paints no closer than
+ * {@link minFrameIntervalMs}, except frames a keystroke is waiting on. Dependency-free: the host's
+ * flag table imports it during CLI bootstrap.
+ */
+/** Default ceiling, in frames per second (the historical scheduler cadence). */
+export declare const DEFAULT_MAX_FPS = 30;
+/** Shortest interval between two frames at the live ceiling, in milliseconds. */
+export declare function minFrameIntervalMs(): number;
+/** Set the ceiling; callers pass a value {@link parseMaxFps} accepted. Applies from the next scheduled frame. */
+export declare function setMaxFps(next: number): void;
+/**
+ * Canonicalize a configured ceiling: an integer from 1 to 120. Numeric strings are accepted so one
+ * parser serves the CLI flag, the environment variable, and the setting.
+ *
+ * @throws Error on a non-numeric, fractional, or out-of-range value.
+ */
+export declare function parseMaxFps(value: unknown): number;