@linxiraos/pi-tui 1.4.0 → 1.4.1

package/src/autocomplete.d.ts

@@ -39,6 +39,12 @@ export interface AutocompleteItem {
     state?: string;
     /** Dim hint text shown inline after cursor when this item is selected */
     hint?: string;
+    /**
+     * Slash command matched only through its description, not its name or an alias:
+     * a browse hit, so Enter submits the typed text instead of running it unless the
+     * user moved the selection onto it.
+     */
+    descriptionMatch?: boolean;
 }
 type Awaitable<T> = T | Promise<T>;
 export interface SlashCommand {

package/src/autocomplete.ts

@@ -226,6 +226,12 @@ export interface AutocompleteItem {
 	state?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
+	/**
+	 * Slash command matched only through its description, not its name or an alias:
+	 * a browse hit, so Enter submits the typed text instead of running it unless the
+	 * user moved the selection onto it.
+	 */
+	descriptionMatch?: boolean;
 }
 
 type Awaitable<T> = T | Promise<T>;
@@ -332,14 +338,18 @@ function getCommandAliases(cmd: CommandEntry): string[] {
 }
 
 function getStaticCommandDescription(cmd: CommandEntry): string {
-	return cmd.description ?? "";
+	const raw: unknown = cmd.description;
+	const description = typeof raw === "function" ? (raw as () => string)() : raw;
+	return typeof description === "string" ? description : "";
 }
 
 function getAutocompleteCommandDescription(cmd: CommandEntry): string {
-	if ("getAutocompleteDescription" in cmd && typeof cmd.getAutocompleteDescription === "function") {
-		return cmd.getAutocompleteDescription() ?? cmd.description ?? "";
-	}
-	return cmd.description ?? "";
+	const candidate: unknown =
+		"getAutocompleteDescription" in cmd && typeof cmd.getAutocompleteDescription === "function"
+			? cmd.getAutocompleteDescription()
+			: cmd.description;
+	const description = typeof candidate === "function" ? (candidate as () => string)() : candidate;
+	return typeof description === "string" && description.length > 0 ? description : getStaticCommandDescription(cmd);
 }
 
 /**
@@ -437,6 +447,7 @@ function buildSlashCommandCompletions(
 						...(cmd.iconName && { iconName: cmd.iconName }),
 						...(fullDesc && { description: fullDesc }),
 						...nativeTextMemo,
+						...(nameScore === 0 && { descriptionMatch: true }),
 					};
 				}
 
@@ -444,7 +455,11 @@ function buildSlashCommandCompletions(
 					for (const alias of getCommandAliases(cmd)) {
 						if (alias === name) continue;
 						const aliasScore = scoreCommandTextMatch(lowerPrefix, alias.toLowerCase());
-						if (aliasScore === 0 || (best && aliasScore <= best.score)) continue;
+						if (aliasScore === 0) continue;
+						// An alias can match even when the description outranks it; Enter
+						// must still accept the command rather than submit the raw query.
+						if (best?.descriptionMatch) delete best.descriptionMatch;
+						if (best && aliasScore <= best.score) continue;
 						const fullDesc = resolveFullDesc();
 						best = {
 							value: alias,

package/src/chat/skill-message.ts

@@ -14,8 +14,8 @@ import { collapseSkillTokens, skillChipLabel, skillChipStyle, skillToken } from
 import { tuiText, tuiTextFmt } from "../i18n";
 import { type UserBubbleOptions, UserMessageComponent, userBubbleColor } from "./user-message";
 import type { TspSpan } from "@linxiraos/pi-wire";
-import { card, md, node, span, text } from "../native/describe";
-import { type NativeChild, type NativeNode, type NativeUiEvent, rootToggleExpanded } from "../native/node";
+import { card, md, node, span } from "../native/describe";
+import { type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
 import { Memo } from "../native/memo";
 
 /**
@@ -64,8 +64,7 @@ export class SkillMessageComponent extends Container {
 	}
 
 	handleNativeEvent(event: NativeUiEvent): void {
-		const expanded = rootToggleExpanded(event);
-		if (expanded !== undefined) this.setExpanded(expanded);
+		if (event.type === "toggle" && event.key === "prompt") this.setExpanded(!event.collapsed);
 	}
 
 	/**
@@ -101,20 +100,20 @@ export class SkillMessageComponent extends Container {
 			const children: NativeChild[] = [];
 			if (draft) children.push(md(draft));
 			const promptText = this.#expanded ? this.#extractText() : "";
-			if (promptText) {
-				children.push(
-					node(
-						"section",
-						{ head: [span("prompt", "muted")], role: "zeta.skill.prompt" },
-						[md(promptText)],
-						"prompt",
-					),
-				);
-			}
-			return card(
-				{ role: "zeta.skill", tone: "user", head, collapsible: true, collapsed: !this.#expanded },
-				children.length > 0 ? children : [text([span(label, "muted")])],
+			children.push(
+				node(
+					"section",
+					{
+						head: [span("prompt", "muted")],
+						role: "zeta.skill.prompt",
+						collapsible: true,
+						collapsed: !this.#expanded,
+					},
+					promptText ? [md(promptText)] : [],
+					"prompt",
+				),
 			);
+			return card({ role: "zeta.skill", tone: "user", head }, children);
 		});
 	}
 

package/src/chat/tool-execution.ts

@@ -438,6 +438,8 @@ export class ToolExecutionComponent extends Container {
 	#spinnerActive = false;
 	// Todo write completion strikethrough reveal animation
 	#todoStrikeInterval?: NodeJS.Timeout;
+	// Once-a-second repaint for renderers that show live elapsed time (`tickElapsed`)
+	#elapsedTicker?: NodeJS.Timeout;
 	// Track if args are still being streamed (for edit/write spinner)
 	#argsComplete = false;
 	#executionStarted = false;
@@ -474,6 +476,8 @@ export class ToolExecutionComponent extends Container {
 		argsComplete?: boolean;
 		executionStarted?: boolean;
 		renderContext?: Record<string, unknown>;
+		/** Live: read at render time, so a ticking spinner advances it. */
+		readonly elapsedMs?: number;
 	} = {
 		expanded: false,
 		isPartial: true,
@@ -491,6 +495,10 @@ export class ToolExecutionComponent extends Container {
 		toolCallId?: string,
 	) {
 		super();
+		Object.defineProperty(this.#renderState, "elapsedMs", {
+			get: () => this.#elapsedMs(this.#nativeStatus()),
+			enumerable: true,
+		});
 		ensureThemeSync();
 		this.#toolCallId = toolCallId;
 		this.#toolName = toolName;
@@ -772,6 +780,32 @@ export class ToolExecutionComponent extends Container {
 				this.#renderState.spinnerFrame = undefined;
 			}
 		}
+		this.#updateElapsedTicker(isBackgroundAsyncRunning);
+	}
+
+	/**
+	 * Repaint once a second while a `tickElapsed` renderer's call executes, so a
+	 * quiet command's elapsed time advances without the 30fps spinner ticker.
+	 */
+	#updateElapsedTicker(isBackgroundAsyncRunning: boolean): void {
+		const needsTicker =
+			this.#renderer?.tickElapsed === true &&
+			this.#executionStarted &&
+			this.#isPartial &&
+			!this.#sealed &&
+			!isBackgroundAsyncRunning &&
+			!isNativeRendering();
+		if (needsTicker && !this.#elapsedTicker) {
+			this.#elapsedTicker = setInterval(() => this.#ui.requestComponentRender(this), 1000);
+		} else if (!needsTicker) {
+			this.#stopElapsedTicker();
+		}
+	}
+
+	#stopElapsedTicker(): void {
+		if (!this.#elapsedTicker) return;
+		clearInterval(this.#elapsedTicker);
+		this.#elapsedTicker = undefined;
 	}
 
 	/**
@@ -917,6 +951,7 @@ export class ToolExecutionComponent extends Container {
 			this.#renderState.spinnerFrame = undefined;
 		}
 		this.#stopTodoStrikeAnimation();
+		this.#stopElapsedTicker();
 		this.#previewReady?.resolve();
 	}
 

package/src/chrome/transcript-container.ts

@@ -5,9 +5,9 @@ import { renderForScrollback } from "../components/image";
 import { col } from "../native/describe";
 import type { NativeNode } from "../native/node";
 import { isNativeSettled, settleNative } from "../native/settle";
-import { TERMINAL } from "../terminal-capabilities";
 import { isUsageRowBlock } from "../overlays/usage-row";
 import { isToolActivityComponent } from "./tool-activity";
+import { directPlacementLift, ImageProtocol, iterm2ImagePayload, TERMINAL } from "../terminal-capabilities";
 
 /** Shared animation time supplied by the constrained transcript root. */
 export interface AnimationFrame {
@@ -126,6 +126,14 @@ interface RowSplit {
 	readonly width: number;
 	readonly hash: number | bigint;
 	readonly text: string;
+	/**
+	 * Inline images in the committed rows, in order, each with its payload and
+	 * the length of `text` before it. Their reserved rows carry no content, so
+	 * relocating by `text` alone would stop above an image and make the
+	 * archived image live again at another width; payload and offset tell the
+	 * archived image apart from a replacement or one moved elsewhere.
+	 */
+	readonly images: readonly { readonly payload: string; readonly offset: number }[];
 	/** Seam of the last render it was located in; renders are memoized per frame. */
 	located?: { readonly rendered: readonly string[]; readonly count: number };
 }
@@ -188,7 +196,33 @@ function contentOf(rows: readonly string[]): string {
  */
 function rowSplit(scrollback: readonly string[], rows: number, width: number): RowSplit {
 	const committed = scrollback.slice(0, rows);
-	return { rows, width, hash: Bun.hash(committed.join("\n")), text: contentOf(committed) };
+	const images: { payload: string; offset: number }[] = [];
+	let text = "";
+	for (const row of committed) {
+		if (TERMINAL.isImageLine(row)) images.push({ payload: iterm2ImagePayload(row) ?? row, offset: text.length });
+		text += contentOf([row]);
+	}
+	return { rows, width, hash: Bun.hash(committed.join("\n")), text, images };
+}
+
+/**
+ * `cut` moved to just below an image it would split, on terminals that cannot
+ * draw part of an image (iTerm2's inline images). There the image row draws
+ * the whole picture upward over its reserved rows; once some of those rows are
+ * in scrollback, the picture has nowhere to go and is dropped, so the image
+ * must reach scrollback whole. Kitty and SIXEL draw the visible part instead.
+ */
+function cutBelowWholeImage(rows: readonly string[], cut: number): number {
+	const protocol = TERMINAL.imageProtocol;
+	if (protocol === null || protocol === ImageProtocol.Kitty || protocol === ImageProtocol.Sixel) return cut;
+	// Only reserved rows sit between a cut inside an image and its image row,
+	// so the first image row at or below the cut decides.
+	for (let index = Math.max(0, cut); index < rows.length; index++) {
+		const row = rows[index]!;
+		if (!TERMINAL.isImageLine(row)) continue;
+		return index - directPlacementLift(row) < cut ? index + 1 : cut;
+	}
+	return cut;
 }
 
 /** Whether `prefix` matches `rows` byte-for-byte from the top. */
@@ -842,13 +876,19 @@ export class TranscriptContainer extends Container {
 		// screen; the rest stays live, so a later shrink of the chrome or the
 		// tail refills the screen from live rows instead of opening a band no
 		// frame can fill (rows still on screen cannot return from scrollback).
+		// One exception: on a terminal that cannot draw part of an image, a cut
+		// inside an image moves below it (cutBelowWholeImage), so up to that
+		// image's height of on-screen rows commits early. A later shrink can then
+		// open a band that tall, which beats losing the image.
 		let split: { index: number; rows: readonly string[]; split: RowSplit } | undefined;
 		if (policy === "pressure" && keep > 0 && limit === this.#frontier + keep) {
 			const boundary = live[keep - 1]!;
 			const visible = room - tailRows - (tailRows > 0 ? 1 : 0);
 			if (boundary.entry.state === "settled" && visible > 0) {
 				const offer = this.#splitOffer(boundary.entry, width, visible);
-				if (offer !== undefined) {
+				if (offer === "whole") {
+					limit = boundary.index + 1;
+				} else if (offer !== undefined) {
 					split = { index: boundary.index, ...offer };
 					limit = boundary.index;
 				}
@@ -891,18 +931,23 @@ export class TranscriptContainer extends Container {
 	 * The head rows of settled `entry` beyond its committed prefix that leave
 	 * `visible` rows live, or undefined when nothing would remain committed
 	 * past that prefix or the scrollback render would not line up row for row.
+	 * `"whole"` when keeping an image whole moves the cut to the block's end:
+	 * the block then retires in full, with the blank row that separates it from
+	 * the next block, which a split never carries.
 	 */
 	#splitOffer(
 		entry: TranscriptEntry,
 		width: number,
 		visible: number,
-	): { rows: readonly string[]; split: RowSplit } | undefined {
+	): { rows: readonly string[]; split: RowSplit } | "whole" | undefined {
 		const measured = this.#measuredRows(entry, width);
 		const start = this.#emittedRowCount(entry, width);
-		const total = measured.length - visible;
-		if (total <= start) return undefined;
+		const cut = measured.length - visible;
+		if (cut <= start) return undefined;
 		const scrollback = renderForScrollback(() => this.#renderEntry(entry, width));
 		if (scrollback.length !== measured.length) return undefined;
+		const total = cutBelowWholeImage(scrollback, cut);
+		if (total >= scrollback.length) return "whole";
 		return { rows: scrollback.slice(start, total), split: rowSplit(scrollback, total, width) };
 	}
 
@@ -1119,13 +1164,40 @@ export class TranscriptContainer extends Container {
 			count = split.rows;
 		} else {
 			let consumed = 0;
-			while (count < rendered.length && consumed < split.text.length) {
-				const row = contentOf([rendered[count]!]);
-				// An empty-content row matches at any offset, so the walk cannot
-				// tell it apart from a revealed row history never received.
-				if (row.length === 0 || !split.text.startsWith(row, consumed)) break;
-				consumed += row.length;
-				count++;
+			let image = 0;
+			while (count < rendered.length && (consumed < split.text.length || image < split.images.length)) {
+				const row = rendered[count]!;
+				const content = contentOf([row]);
+				if (content.length > 0) {
+					if (!split.text.startsWith(content, consumed)) break;
+					consumed += content.length;
+					count++;
+					continue;
+				}
+				// An empty-content row matches at any offset, so the walk cannot tell it
+				// apart from a revealed row history never received; only the next
+				// archived image carries the seam on, through its own reserved rows to
+				// its row, whatever its height here.
+				let index = count;
+				while (
+					index < rendered.length &&
+					!TERMINAL.isImageLine(rendered[index]!) &&
+					contentOf([rendered[index]!]).length === 0
+				) {
+					index++;
+				}
+				const imageRow = rendered[index];
+				if (
+					imageRow === undefined ||
+					!TERMINAL.isImageLine(imageRow) ||
+					(iterm2ImagePayload(imageRow) ?? imageRow) !== split.images[image]?.payload ||
+					consumed !== split.images[image]?.offset ||
+					index - count !== directPlacementLift(imageRow)
+				) {
+					break;
+				}
+				count = index + 1;
+				image++;
 			}
 		}
 		split.located = { rendered, count };

package/src/components/editor.ts

@@ -704,6 +704,8 @@ export class Editor implements Component, Focusable {
 		| { line: number; startCol: number; endCol: number; original: string; cursorOffset: number }
 		| undefined;
 	#autocompletePrefix: string = "";
+	/** False while the popup's untouched top row is a description-only slash hit ({@link AutocompleteItem.descriptionMatch}): Enter then submits the typed text. */
+	#enterAcceptsSelection = true;
 	#autocompleteRequestId: number = 0;
 	#autocompletePendingRequest: AutocompleteRequest | undefined;
 	#autocompleteRequestRunning = false;
@@ -1921,6 +1923,7 @@ export class Editor implements Component, Focusable {
 						this.onAutocompleteUpdate?.();
 					} else {
 						this.#autocompleteList.handleInput(data);
+						this.#enterAcceptsSelection = true;
 						this.onAutocompleteUpdate?.();
 						return;
 					}
@@ -1965,8 +1968,11 @@ export class Editor implements Component, Focusable {
 					// Check for stale autocomplete state while an async refresh is pending
 					const currentLine = this.#state.lines[this.#state.cursorLine] ?? "";
 					const currentTextBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-					if (!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected)) {
-						// Autocomplete is stale - cancel and fall through to normal submission
+					if (
+						!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected) ||
+						!this.#enterAcceptsSelection
+					) {
+						// Stale, or a description-only hit the user never selected: submit the typed text.
 						this.#cancelAutocomplete();
 					} else {
 						if (selected && this.#autocompleteProvider) {
@@ -1998,10 +2004,12 @@ export class Editor implements Component, Focusable {
 					if (
 						!selected ||
 						!this.#autocompletePrefixMatchesCursorText(currentTextBeforeCursor, selected) ||
-						this.#selectedSlashArgumentIsAlreadyTyped(selected)
+						this.#selectedSlashArgumentIsAlreadyTyped(selected) ||
+						!this.#enterAcceptsSelection
 					) {
-						// Stale, or accepting would only append whitespace to an already fully
-						// typed slash-command argument (`/mcp list` + Enter): cancel and fall
+						// Stale, accepting would only append whitespace to an already fully
+						// typed slash-command argument (`/mcp list` + Enter), or the row is a
+						// description-only hit the user never selected: cancel and fall
 						// through to normal submission instead of swallowing the keypress.
 						this.#cancelAutocomplete();
 					} else {
@@ -2145,9 +2153,10 @@ export class Editor implements Component, Focusable {
 				) {
 					const syncResult = this.#autocompleteProvider.trySyncSlashCompletion(textBeforeCursor);
 					// The collapsed `/skill:` namespace row is not a runnable command; Enter submits
-					// immediately after applying, so only a real command may be completed here.
+					// immediately after applying, so only a real command may be completed here, and
+					// only one whose name matches: a description-only hit would run an unrelated command.
 					const selected = syncResult?.items.find(item => item.value !== SKILL_NAMESPACE);
-					if (syncResult && selected) {
+					if (syncResult && selected && !selected.descriptionMatch) {
 						// Invalidate any pending async autocomplete so its stale results are discarded
 						this.#autocompleteRequestId += 1;
 						// Apply the best match and submit the completed command
@@ -4876,6 +4885,7 @@ export class Editor implements Component, Focusable {
 	): void {
 		this.#autocompletePrefix = suggestions.prefix;
 		this.#autocompleteList = this.#createAutocompleteList(suggestions.prefix, suggestions.items);
+		this.#enterAcceptsSelection = !suggestions.items[0]?.descriptionMatch;
 		this.#autocompleteState = state;
 		this.onAutocompleteUpdate?.();
 	}

package/src/components/image.ts

@@ -1,5 +1,6 @@
 import { encodeSixelAsync } from "@linxiraos/pi-natives";
 import { getKittyGraphics } from "../kitty-graphics";
+import { ensureSixelRasterWidth } from "../sixel";
 import {
 	encodeSixelNow,
 	getCellDimensions,
@@ -736,7 +737,7 @@ export class Image implements Component {
 		const request: SixelEncode = { widthPx, heightPx, backgroundRgb };
 		this.#sixel = request;
 		const settle = (sequence: string | null): void => {
-			request.sequence = sequence;
+			request.sequence = sequence === null ? null : ensureSixelRasterWidth(sequence);
 			if (this.#sixel !== request || getTerminalBackgroundColor() !== backgroundRgb) return;
 			this.invalidate();
 			if (this.#options.requestRender) this.#options.requestRender();
@@ -845,9 +846,9 @@ export class Image implements Component {
 				// height. First (rows-1) lines are empty (TUI clears them); the last
 				// saves the final-row cursor, moves up to the image origin, emits the
 				// image sequence, then restores the final-row cursor. When the block
-				// straddles the viewport top, the renderer rewrites this line to the
-				// visible slice (encodeKittyPlacementLine) from the geometry
-				// registered below.
+				// straddles the viewport top, the renderer crops the source raster
+				// for SIXEL or rewrites the Kitty placement's visible source slice
+				// from the geometry registered below.
 				if (this.#imageId != null && this.#budget !== undefined) {
 					this.#budget.registerPlacementGeometry(
 						this.#imageId,

package/src/components/markdown.ts

@@ -4420,7 +4420,7 @@ export class Markdown implements Component {
 	 * Delegates to wrapTextWithAnsi() so ANSI codes + long tokens are handled
 	 * consistently with the rest of the renderer.
 	 */
-	#wrapCellText(text: string, maxWidth: number): string[] {
+	#wrapCellText(text: string, maxWidth: number, clampOversized = true): string[] {
 		const cellWidth = Math.max(1, maxWidth);
 		// Wrap the whole cell in one call so wrapTextWithAnsi() balances OSC 8
 		// hyperlink state across explicit newlines (e.g. `<br>` rendered as \n);
@@ -4435,7 +4435,14 @@ export class Markdown implements Component {
 		// (e.g. mdCode) would bleed into the "│" and the following cells.
 		// Terminate each line at default fg, clearing bold/italic but keeping
 		// any ambient background (message-bg rendering) intact.
-		return wrapped.map(line => `${line}\x1b[22m\x1b[23m\x1b[39m`);
+		// A wide glyph can exceed a one-cell column without wrapping (a 2-cell
+		// emoji in a column squeezed to 1), so clamp here before the row is
+		// spliced between borders; otherwise the overwide row is re-wrapped and
+		// the trailing border lands on its own line.
+		return wrapped.map(line => {
+			const fitted = clampOversized && visibleWidth(line) > cellWidth ? truncateToWidth(line, cellWidth) : line;
+			return `${fitted}\x1b[22m\x1b[23m\x1b[39m`;
+		});
 	}
 
 	/**
@@ -4626,7 +4633,8 @@ export class Markdown implements Component {
 				if (rowCellLines[openCell].length > settledLineCount) {
 					const width = columnWidths[openCell];
 					const kept = rowCellLines[openCell].slice(0, settledLineCount);
-					const last = width > 1 ? (this.#wrapCellText(kept[settledLineCount - 1], width - 1)[0] ?? "") : "";
+					const last =
+						width > 1 ? (this.#wrapCellText(kept[settledLineCount - 1], width - 1, false)[0] ?? "") : "";
 					kept[settledLineCount - 1] = `${visibleWidth(last) < width ? last : ""}…`;
 					rowCellLines[openCell] = kept;
 				}

package/src/components/sparkline.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One-row block sparklines (`▁▂▃▅▇█`) for ANSI renderers: the usage history
+ * in `zetacode usage`, a job widget's series in the `wait` card and status line.
+ */
+/** Block glyphs from lowest to highest. */
+export declare const SPARK_LEVELS: readonly ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+/** How {@link renderSparkline} maps values to glyphs and styles them. */
+export interface SparklineOptions {
+    /** Domain low end; values at or below it draw the lowest block. Default 0. */
+    readonly min?: number;
+    /** Domain high end; values at or above it draw the full block. Default the largest value. */
+    readonly max?: number;
+    /** Styles one glyph; `fraction` is the value's 0–1 position in the domain. */
+    readonly style?: (glyph: string, value: number, fraction: number) => string;
+    /** What a missing value draws, already styled. Default a space. */
+    readonly gap?: string;
+}
+/** The block glyph for a 0–1 fraction of the domain. */
+export declare function sparkGlyph(fraction: number): string;
+/** One cell per value, oldest first; `undefined` (and non-finite) values draw the gap. */
+export declare function renderSparkline(values: readonly (number | undefined)[], options?: SparklineOptions): string;
+/**
+ * `values` squeezed into at most `cells` points by equal-count bucket means,
+ * newest bucket last; shorter series come back unchanged.
+ */
+export declare function fitSparkValues(values: readonly number[], cells: number): readonly number[];
+/**
+ * The largest value per time bucket over `[sinceMs, nowMs]`, `cells` buckets
+ * wide; buckets without a point are `undefined` (a gap in the sparkline).
+ */
+export declare function peakBuckets(points: Iterable<{
+    readonly at: number;
+    readonly value: number;
+}>, sinceMs: number, nowMs: number, cells: number): (number | undefined)[];

package/src/components/sparkline.ts

@@ -0,0 +1,89 @@
+/**
+ * One-row block sparklines (`▁▂▃▅▇█`) for ANSI renderers: the usage history
+ * in `zetacode usage`, a job widget's series in the `wait` card and status line.
+ */
+
+/** Block glyphs from lowest to highest. */
+export const SPARK_LEVELS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+
+/** How {@link renderSparkline} maps values to glyphs and styles them. */
+export interface SparklineOptions {
+	/** Domain low end; values at or below it draw the lowest block. Default 0. */
+	readonly min?: number;
+	/** Domain high end; values at or above it draw the full block. Default the largest value. */
+	readonly max?: number;
+	/** Styles one glyph; `fraction` is the value's 0–1 position in the domain. */
+	readonly style?: (glyph: string, value: number, fraction: number) => string;
+	/** What a missing value draws, already styled. Default a space. */
+	readonly gap?: string;
+}
+
+/** The block glyph for a 0–1 fraction of the domain. */
+export function sparkGlyph(fraction: number): string {
+	const clamped = Number.isFinite(fraction) ? Math.min(Math.max(fraction, 0), 1) : 0;
+	return SPARK_LEVELS[Math.min(SPARK_LEVELS.length - 1, Math.floor(clamped * SPARK_LEVELS.length))]!;
+}
+
+/** One cell per value, oldest first; `undefined` (and non-finite) values draw the gap. */
+export function renderSparkline(values: readonly (number | undefined)[], options: SparklineOptions = {}): string {
+	const min = options.min ?? 0;
+	let max = options.max;
+	if (max === undefined) {
+		max = min;
+		for (const value of values) if (value !== undefined && Number.isFinite(value) && value > max) max = value;
+	}
+	const span = max - min;
+	const gap = options.gap ?? " ";
+	let out = "";
+	for (const value of values) {
+		if (value === undefined || !Number.isFinite(value)) {
+			out += gap;
+			continue;
+		}
+		const fraction = span > 0 ? (value - min) / span : value > min ? 1 : 0;
+		const glyph = sparkGlyph(fraction);
+		out += options.style ? options.style(glyph, value, Math.min(Math.max(fraction, 0), 1)) : glyph;
+	}
+	return out;
+}
+
+/**
+ * `values` squeezed into at most `cells` points by equal-count bucket means,
+ * newest bucket last; shorter series come back unchanged.
+ */
+export function fitSparkValues(values: readonly number[], cells: number): readonly number[] {
+	const count = Math.max(0, Math.floor(cells));
+	if (values.length <= count) return values;
+	const out: number[] = [];
+	for (let bucket = 0; bucket < count; bucket++) {
+		const from = Math.floor((bucket * values.length) / count);
+		const to = Math.max(from + 1, Math.floor(((bucket + 1) * values.length) / count));
+		let sum = 0;
+		for (let i = from; i < to; i++) sum += values[i]!;
+		out.push(sum / (to - from));
+	}
+	return out;
+}
+
+/**
+ * The largest value per time bucket over `[sinceMs, nowMs]`, `cells` buckets
+ * wide; buckets without a point are `undefined` (a gap in the sparkline).
+ */
+export function peakBuckets(
+	points: Iterable<{ readonly at: number; readonly value: number }>,
+	sinceMs: number,
+	nowMs: number,
+	cells: number,
+): (number | undefined)[] {
+	const span = Math.max(1, nowMs - sinceMs);
+	const count = Math.max(0, Math.floor(cells));
+	const buckets: (number | undefined)[] = Array.from({ length: count }, () => undefined);
+	if (count === 0) return buckets;
+	for (const point of points) {
+		const offset = Math.floor(((point.at - sinceMs) / span) * count);
+		const index = Math.min(count - 1, Math.max(0, offset));
+		const prev = buckets[index];
+		buckets[index] = prev === undefined ? point.value : Math.max(prev, point.value);
+	}
+	return buckets;
+}

package/src/index.d.ts

@@ -25,6 +25,7 @@ export * from "./components/section";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";
+export * from "./components/sparkline";
 export * from "./components/tab-bar";
 export * from "./components/table";
 export * from "./components/text";

package/src/index.ts

@@ -30,6 +30,7 @@ export * from "./components/section";
 export * from "./components/select-list";
 export * from "./components/settings-list";
 export * from "./components/spacer";
+export * from "./components/sparkline";
 export * from "./components/tab-bar";
 export * from "./components/table";
 export * from "./components/text";