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

package/dist/types/overlays/usage-dashboard.d.ts

@@ -0,0 +1,94 @@
+import { type UsageLimit, type UsageReport } from "@oh-my-pi/pi-ai";
+import { type Component } from "../index.js";
+/** Local calendar-day activity consumed by the usage heatmap. */
+export interface DailyActivityPoint {
+    day: string;
+    cost: number;
+    requests: number;
+}
+/** One quota bucket on a provider card: the account-aggregate of one window group. */
+export interface CardWindowRow {
+    /** Display label (limit label with tier folded in). */
+    label: string;
+    /** Window label/id shown dim after the label when sibling rows share a label. */
+    windowTag?: string;
+    /** Mean used fraction across accounts (0..1, >1 = overage); undefined when unreported. */
+    fraction: number | undefined;
+    status: UsageLimit["status"];
+    /** Reset countdown of the worst account, ms from now, when in the future. */
+    resetMs?: number;
+    /** Absolute one-sided amount (e.g. `$12.34 used`, `100 credits left`) for limits without a fraction. */
+    usedText?: string;
+}
+/** Compact per-provider summary backing one card in the subscriptions grid. */
+export interface ProviderCard {
+    provider: string;
+    name: string;
+    /** Number of accounts reporting for this provider. */
+    accounts: number;
+    /** Window rows sorted most-pressing first. */
+    windows: CardWindowRow[];
+    /** True when every account reports no limits (e.g. enterprise plans). */
+    unlimited: boolean;
+    /** True when nothing is used anywhere (or there are no limits): collapses to a tick. */
+    idle: boolean;
+}
+/**
+ * Collapse usage reports into one compact card per provider: limits grouped by
+ * quota bucket (label + window), each bucket showing the mean used fraction
+ * across accounts (matching the classic report's aggregate "% free") with the
+ * most-used account's reset countdown. Cards sort most-pressing first so
+ * what's burning is on top-left; fully idle providers collapse into a tick.
+ */
+export declare function buildProviderCards(reports: UsageReport[], nowMs: number): ProviderCard[];
+/** GitHub-style week-per-column heatmap grid derived from daily activity. */
+export interface HeatmapLayout {
+    /** Per week column: short month name when the column starts a new month. */
+    monthLabels: (string | undefined)[];
+    /** 7 rows (Mon..Sun) × N week columns; 0..4 intensity, null = future day. */
+    cells: (number | null)[][];
+    totalCost: number;
+    totalRequests: number;
+}
+export declare const HEATMAP_DAY_LABELS: string[];
+/**
+ * Lay out daily activity into a Monday-first week grid ending at `today`'s
+ * week. Intensity levels are magnitude-scaled against the busiest day
+ * (square-root compressed so mid-size days stay distinguishable from
+ * outliers), over per-day cost — falling back to request counts when nothing
+ * in range has priced usage. Unlike GitHub's rank quartiles, intensity tracks
+ * *how much* work a day carried.
+ */
+export declare function buildHeatmapLayout(points: DailyActivityPoint[], weeks: number, today?: Date): HeatmapLayout;
+/** Callbacks and data sources for {@link UsageDashboardComponent}. */
+export interface UsageDashboardOptions {
+    reports: UsageReport[];
+    /**
+     * Full classic `/usage` report for the expanded detail view; re-invoked per
+     * terminal width.
+     */
+    renderDetail: (width: number) => string;
+    /**
+     * Stream daily activity into the heatmap: push cached DB rows immediately,
+     * then push again after an incremental session sync. Resolves when the sync
+     * settles; rejection renders as a dim unavailable note. `signal` aborts when
+     * the dashboard closes so an in-flight sync can stop early.
+     */
+    loadActivity: (push: (points: DailyActivityPoint[]) => void, signal: AbortSignal) => Promise<void>;
+    requestRender: () => void;
+    onClose: () => void;
+}
+/**
+ * Sanitize activity loading error text for safe single-line display in the TUI overlay.
+ * Strips ANSI/control sequences, expands tabs, collapses whitespace runs/newlines,
+ * shortens home directory paths to ~, and removes trailing dots.
+ */
+export declare function formatActivityErrorDetail(error: string, homeDir?: string): string;
+export declare class UsageDashboardComponent implements Component {
+    #private;
+    constructor(options: UsageDashboardOptions);
+    invalidate(): void;
+    dispose(): void;
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+}

package/dist/types/overlays/usage-display.d.ts

@@ -0,0 +1,5 @@
+import type { UsageLimit, UsageReport } from "@oh-my-pi/pi-ai";
+/** Include the usage tier in a limit title unless its label already names it. */
+export declare function formatLimitTitle(limit: UsageLimit): string;
+/** Collapse routing-specific copies of a shared quota for user-facing usage views. */
+export declare function collapseSharedUsageReports(reports: UsageReport[]): UsageReport[];

package/dist/types/overlays/usage-row.d.ts

@@ -0,0 +1,17 @@
+import type { Usage } from "@oh-my-pi/pi-ai";
+import { Container } from "../index.js";
+/**
+ * Prompt→yield wall time for a turn, from pure local timestamps: the user
+ * prompt's timestamp to the response's completion time (`completedAt`, stamped
+ * by the session at `message_end`). No provider-reported duration is involved —
+ * messages persisted before the stamp existed simply have no span.
+ * Undefined when either end is unknown (mid-attach or unstamped message).
+ */
+export declare function turnElapsedMs(turnStartedAt: number | undefined, message: {
+    completedAt?: number;
+}): number | undefined;
+/** Format the metrics shared by standalone usage blocks and compact tool groups. */
+export declare function formatUsageRow(usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number, turnElapsedMs?: number): string;
+/** Whether `component` is a per-turn usage/metrics row from {@link createUsageRowBlock}. */
+export declare function isUsageRowBlock(component: object): boolean;
+export declare function createUsageRowBlock(usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number, turnElapsedMs?: number): Container;

package/dist/types/prompt/attachment-chips.d.ts

@@ -0,0 +1,19 @@
+import { type Component, type ImageBudget } from "../index.js";
+import type { CustomEditor } from "./custom-editor.js";
+/**
+ * The composer attachment band: one rounded card per staged attachment, rendered directly above
+ * the prompt box. Image and video cards show a live thumbnail (Kitty Unicode placeholders — the only
+ * protocol whose output is plain text cells and therefore composable inside a border row) with
+ * the pixel dimensions as the bottom caption; text-paste cards show the leading snippet with a
+ * `+N lines` / `N chars` caption. The top caption is the same `<icon> #N` token that sits in
+ * the editor buffer, in the same identity color. Cards that no longer fit the terminal width
+ * are omitted rather than wrapped. Renders to nothing while no attachment is staged.
+ */
+export declare class AttachmentChipsBand implements Component {
+    #private;
+    private readonly editor;
+    private readonly budget;
+    private readonly requestRender;
+    constructor(editor: CustomEditor, budget: ImageBudget, requestRender: () => void);
+    render(width: number): readonly string[];
+}

package/dist/types/prompt/composer-attachments.d.ts

@@ -0,0 +1,71 @@
+/** Attachment chip kinds staged in the composer: images, video previews, and large text pastes. */
+export type ChipKind = "image" | "video" | "paste";
+/** Compact atomic composer token for an invoked skill in the active symbol preset. */
+export declare function skillChipLabel(name: string): string;
+/** Compact atomic composer token for a model mention in the active symbol preset. */
+export declare function modelMentionChipLabel(name: string): string;
+/** Canonical `/skill:<name>` token a skill chip expands to on submit. */
+export declare function skillToken(name: string): string;
+/**
+ * Soft-pill styling for a skill chip: bold skill label color over the custom-message
+ * tint. `restore` re-arms the surrounding foreground/background after the chip.
+ */
+export declare function skillChipStyle(label: string, restore?: string): string;
+/** Soft-pill styling for a model mention, restoring the surrounding colors afterward. */
+export declare function modelChipStyle(label: string, restore?: string): string;
+/**
+ * Replaces `/skill:<name>` tokens for known skills with compact chip labels and
+ * registers each label's token as its atomic editor expansion. Leaves the text
+ * untouched when skill tokens are not invocations in this draft (see
+ * {@link allowsSkillTokens}).
+ */
+export declare function collapseSkillTokens(text: string, isKnown: (name: string) => boolean, register: (label: string, expansion: string) => void): string;
+/**
+ * Replaces mentionable model selectors with their display chips and registers
+ * each chip's canonical selector as its atomic editor expansion.
+ */
+export declare function collapseModelMentions(text: string, labelFor: (selector: string) => string | undefined, register: (label: string, expansion: string) => void): string;
+/** Compact atomic composer token for attachment `n` in the active symbol preset. */
+export declare function chipLabel(kind: ChipKind, n: number): string;
+/** Infers an attachment kind from a chip label emitted by any configured symbol preset. */
+export declare function chipLabelKind(label: string): ChipKind;
+/** Stable RGB color assigned to attachment `n`; each attachment type uses a distinct palette offset. */
+export declare function attachmentRgb(kind: ChipKind, n: number): readonly [number, number, number];
+/** ANSI truecolor foreground sequence for the color assigned by {@link attachmentRgb}. */
+export declare function attachmentSgr(kind: ChipKind, n: number): string;
+/** Matches expanded image, video, and paste markers, including optional marker metadata. */
+export declare const PLACEHOLDER_REGEX: RegExp;
+/** Matches an expanded attachment marker, a compact attachment chip, or a skill chip. */
+export declare const COMPOSER_TOKEN_REGEX: RegExp;
+/** Add the registered model-chip labels to the composer placeholder matcher. */
+export declare function composerTokenRegex(mentionLabels: Iterable<string>): RegExp;
+/** Offsets image marker indices, including matching `attachment://` references. */
+export declare function shiftImageMarkers(text: string, offset: number): string;
+/**
+ * Replaces valid expanded image markers with compact tokens and registers each
+ * token's original marker as its atomic editor expansion.
+ */
+export declare function collapseImageMarkers(text: string, imageCount: number, register: (label: string, expansion: string) => void): string;
+/**
+ * Drops unreferenced vision attachments from a submission and densely remaps
+ * retained image/video markers. Returns `null` when no compaction is needed.
+ */
+export declare function compactImageMarkers(text: string, imageCount: number): {
+    text: string;
+    keep: number[];
+} | null;
+/** Attachment kinds understood by placeholder renderers. */
+export type PlaceholderKind = "image" | "video" | "paste";
+/** Rendering callbacks for plain text and parsed attachment references. */
+export interface PlaceholderRenderers {
+    /** Renders text outside attachment references. */
+    renderText: (text: string) => string;
+    /** Renders one parsed marker or compact chip token. */
+    renderReference: (label: string, kind: PlaceholderKind, index: number, form: "marker" | "chip") => string;
+    /** Renders one skill chip (`<icon> <name>`). */
+    renderSkill: (label: string, name: string) => string;
+    /** Renders one registered model mention chip. */
+    renderMention: (label: string) => string;
+}
+/** Renders text while treating expanded markers, attachment chips, skill chips, and model mentions as distinct references. */
+export declare function renderPlaceholders(text: string, renderers: PlaceholderRenderers, tokenRegex?: RegExp): string;

package/dist/types/prompt/composer-cache.d.ts

@@ -0,0 +1,37 @@
+import "@oh-my-pi/pi-utils/env";
+import type { LspServerInfo, RecentSession } from "./welcome.js";
+import type { ComposerPreferences, ComposerStatusSnapshot } from "./composer.js";
+import type { SymbolPreset } from "../theme/theme.js";
+/** Theme inputs cached from the last resolved settings load for stable prepaint colors. */
+export interface ComposerThemePreferences {
+    readonly symbolPreset?: SymbolPreset;
+    readonly colorBlindMode?: boolean;
+    readonly darkTheme?: string;
+    readonly lightTheme?: string;
+}
+/** Last authoritative model labels shown in the welcome component. */
+export interface ComposerWelcomeCache {
+    readonly modelName: string;
+    readonly providerName: string;
+}
+/** Speculative composer state read before the settings/session graph is available. */
+export interface ComposerStartupCache {
+    readonly preferences?: ComposerPreferences;
+    readonly theme?: ComposerThemePreferences;
+    readonly welcome?: ComposerWelcomeCache;
+    readonly recentSessions: RecentSession[];
+    readonly lspServers: LspServerInfo[];
+    readonly status?: ComposerStatusSnapshot;
+}
+/** Read all speculative composer caches synchronously before the first terminal paint. */
+export declare function readComposerStartupCache(cwd: string): ComposerStartupCache;
+/** Persist resolved theme and composer settings for the next prepaint. */
+export declare function writeComposerUiCache(cwd: string, preferences: ComposerPreferences, theme: ComposerThemePreferences): Promise<void>;
+/** Persist authoritative model/provider labels for the next welcome prepaint. */
+export declare function writeComposerWelcomeCache(cwd: string, welcome: ComposerWelcomeCache): Promise<void>;
+/** Persist placeholder-only status chrome for speculative first-frame rendering. */
+export declare function writeComposerStatusCache(cwd: string, status: ComposerStatusSnapshot): Promise<void>;
+/** Persist the latest recent-session rows as a compact JSONL speculation cache. */
+export declare function writeComposerRecentSessionsCache(cwd: string, sessions: readonly RecentSession[]): Promise<void>;
+/** Persist the latest detected project LSP rows for the next prepaint. */
+export declare function writeComposerLspCache(cwd: string, servers: readonly LspServerInfo[]): Promise<void>;

package/dist/types/prompt/composer.d.ts

@@ -0,0 +1,159 @@
+import { type Terminal } from "../terminal.js";
+import { type Component, type ResizeScrollbackMode, type TerminalFramePlan, type TerminalFrameProvider, TUI, type TUIOptions, type ViewportSize } from "../tui.js";
+import { CustomEditor } from "./custom-editor.js";
+import { type LspServerInfo, type RecentSession, WelcomeComponent } from "./welcome.js";
+/** Live settings that affect the composer before and after session adoption. */
+export interface ComposerPreferences {
+    readonly quiet: boolean;
+    readonly composerShape: string;
+    readonly showHardwareCursor: boolean;
+    readonly maxInlineImages: number;
+    readonly resizeScrollback: ResizeScrollbackMode;
+    readonly imeSafeCursor: boolean;
+    readonly autocompleteMaxVisible: number;
+    readonly spellingTypoDetection: boolean;
+    readonly spellingAutocomplete: boolean;
+    readonly spellingAutocorrect: boolean;
+}
+/** Settings-schema-compatible defaults used when constructing a dependency-free composer. */
+export declare const COMPOSER_DEFAULTS: ComposerPreferences;
+/** Welcome data that can be supplied initially or patched as startup resolves it. */
+export interface ComposerWelcomeUpdate {
+    readonly version?: string;
+    readonly modelName?: string;
+    readonly providerName?: string;
+    readonly recentSessions?: readonly RecentSession[];
+    readonly lspServers?: readonly LspServerInfo[];
+}
+/**
+ * Placeholder-only status chrome replayed on the next first frame so the
+ * status band/border exists before the session-aware status line attaches.
+ * Bound to the composer shape it was rendered for; a different shape drops it.
+ */
+export interface ComposerStatusSnapshot {
+    readonly shape: string;
+    /** ANSI wrapper of the editor border at snapshot time (session accent or thinking color). */
+    readonly borderColor?: {
+        readonly prefix: string;
+        readonly suffix: string;
+    };
+    /** Status content embedded in the editor's top chrome (`top-border`, `top-band`, `top-rule-chip`). */
+    readonly topBorder?: {
+        readonly content: string;
+        readonly width: number;
+    };
+    /** Standalone bottom-bar rows (`pi`/`claude` shapes), gap row included. */
+    readonly bottomLines: readonly string[];
+}
+/** Optional dependencies and initial state for a standalone composer. */
+export interface ComposerOptions {
+    readonly terminal?: Terminal;
+    /** Extra TUI construction options (render scheduler injection for tests and `omp render`). */
+    readonly tuiOptions?: TUIOptions;
+    readonly preferences?: Partial<ComposerPreferences>;
+    readonly welcome?: ComposerWelcomeUpdate;
+    readonly status?: ComposerStatusSnapshot;
+    readonly exit?: (code: number) => void;
+    readonly now?: () => number;
+}
+/** Controls the first terminal paint for a composer that does not already own the terminal. */
+export interface ComposerStartOptions {
+    readonly clearScrollback?: boolean;
+    readonly playWelcomeIntro?: boolean;
+    /**
+     * Paint without owning stdin: the tty keeps cooked-mode echo/editing so
+     * typing stays visible while startup module loading blocks the event loop.
+     * {@link Composer.enableInput} later switches to raw input and replays the
+     * kernel-buffered keystrokes into the editor.
+     */
+    readonly deferInput?: boolean;
+}
+/** One click target's row span within the mutable viewport (half-open `[start, end)`). */
+export interface ViewportClickSpan {
+    start: number;
+    end: number;
+    /** Candidate subagent ids for a span-local row. */
+    candidates: (local: number) => string[];
+}
+/**
+ * Row-level click target: maps rendered rows to subagent ids. Implemented by
+ * the subagent HUD, whose rows are fixed 1:1 with visible sessions.
+ */
+export interface ViewportClickRowTarget {
+    getClickAgentAtRow(row: number): string | undefined;
+}
+/**
+ * Candidates under a mutable-viewport line: the first span containing it.
+ * Pure seam for tests; the caller intersects with the live registry, which
+ * decides focusability and recency.
+ */
+export declare function routeViewportClick(spans: readonly ViewportClickSpan[], index: number): string[];
+/**
+ * Reserved click-candidate id for the pinned HUD expander row. Checked before
+ * any registry lookup: its `@…:…` charset cannot collide with generated agent
+ * ids (word names, numeric and `-N` suffixes, dotted nesting).
+ */
+export declare const PINNED_HUD_TOGGLE_ID = "@omp:toggle-pinned-hud";
+/**
+ * Canonical interactive composer, usable before session/settings exist and updatable in place.
+ * It owns the terminal, welcome header, and editor; InteractiveMode later supplies authoritative
+ * data and mounts the session-aware runtime children without replacing the visible header.
+ */
+export declare class Composer implements TerminalFrameProvider {
+    #private;
+    readonly ui: TUI;
+    constructor(options?: ComposerOptions);
+    /** Compose the bounded mutable viewport and the next ordered history append. */
+    renderFrame(viewport: ViewportSize): TerminalFramePlan;
+    /**
+     * Candidate subagent ids under a mutable-viewport line, for click-to-focus.
+     * Empty when the line has no click target (chrome, separators, retired rows
+     * are never in the viewport). Callers intersect with the live registry.
+     */
+    viewportClickCandidates(index: number): string[];
+    /**
+     * Point the hover band at a click-candidate id (or clear it). Takes effect
+     * on the next frame; callers repaint only when the target actually changes.
+     */
+    setHoveredClickId(id: string | undefined): void;
+    /** Acknowledges one accepted header, replay, or transcript batch. */
+    acknowledgeHistory(id: number): void;
+    /** Render the semantic transcript tail while the terminal borrows its resize buffer. */
+    renderResizeFrame(viewport: ViewportSize): readonly string[];
+    /** Replays committed presentation without changing logical retirement state. */
+    beginHistoryReplay(): void;
+    /** Forces every currently eligible finalized prefix to retire before stop. */
+    beginHistoryFlush(): void;
+    /** Live editor whose draft survives startup and session adoption. */
+    get editor(): CustomEditor;
+    /** The welcome component currently mounted in the header, if quiet mode is off. */
+    get welcome(): WelcomeComponent | undefined;
+    /** Whether this composer already owns the terminal render/input loop. */
+    get started(): boolean;
+    /** Start terminal ownership and optionally begin the welcome intro. */
+    start(options?: ComposerStartOptions): void;
+    /** Take raw-input ownership after a deferred-input start. Idempotent. */
+    enableInput(): void;
+    /** Apply settings changes without replacing the editor or welcome component. */
+    setPreferences(update: Partial<ComposerPreferences>): void;
+    /** Patch welcome data in place as model, session, and project discovery complete. */
+    updateWelcome(update: ComposerWelcomeUpdate): void;
+    /** Replace optional header content around the stable welcome scene. */
+    setHeaderExtras(before: readonly Component[], after: readonly Component[]): void;
+    /** Update the canonical editor reference after InteractiveMode remounts a custom editor. */
+    setEditor(editor: CustomEditor): void;
+    /**
+     * Mount the session-aware status component into the slot below the editor.
+     * Drops the speculative snapshot; the caller installs the real top-border
+     * provider through its composer-shape sync.
+     */
+    setStatusComponent(component: Component): void;
+    /** Mount or replace session-aware root children while preserving the header and status hosts. */
+    setRuntimeChildren(children: readonly Component[]): void;
+    /** Play or replay the welcome intro against the stable header render target. */
+    playWelcomeIntro(): void;
+    /** Transfer terminal ownership to InteractiveMode without stopping the composer. */
+    transfer(): void;
+    /** Stop a composer that has not transferred terminal ownership. */
+    stop(): void;
+}