pi-compact-tools 0.6.3 → 0.7.8

package/README.md

@@ -1,183 +1,151 @@
-# pi-compact-tools
-
-Compact, expandable rendering for Pi's built-in tools, with a polished GitHub Dark theme.
-
-> Formerly `@nedleeds/pi-compact-ui`. New installations should use `pi-compact-tools`.
-
-## Demo
-
-The recordings below use the optional [Nerd Font](#nerd-font-spinner-preset) spinner preset. **The default configuration does not require a Nerd Font**.
-
-### Compact tool workflow
-
-Active, successful, and failed tool calls stay compact while preserving useful status and timing information.
-
-![Compact tool workflow with Nerd Font](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/nerd-font-workflow-optimized.gif)
-
-### Spinner and duration display
-
-The spinner animates during execution, then returns to a green success circle or red failure circle. Elapsed time remains visible in the neutral control color.
-
-![Spinner and elapsed-time display](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/spinner-duration-optimized.gif)
-
-### Initially visible edit diffs
-
-Completed `edit` rows show their full diff initially by default. The per-tool `auto_compact` setting controls which tools start with their result hidden without disabling click or `Ctrl+O` interaction.
-
-![Edit diff](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/edit-diff.gif)
-
-## Features
-
-- Compact rendering for `read`, `write`, `edit`, `bash`, `powershell`, `grep`, `find`, and `ls`
-- Animated configurable spinner in fullscreen TUI mode
-- Four-step `Ctrl+T` thinking cycle when provider detail is available: summary, detail, summary, then hidden
-- Millisecond-precision duration and completed output line counts with neutral status text
-- Per-tool initial compaction and global-toggle participation with `auto_compact: true` or `false`
-- Primary invocation targets such as paths, patterns, and shell commands stay visible
-- Click toggles one result between hidden and fully visible; `Ctrl+O` toggles all participating rows
-- Full output on expansion and initially visible edit diffs by default
-- Width-cached expanded results and edit-diff processing for responsive fullscreen scrolling
-- Dark `│` and `└─` visual grouping
-- Distinct cool-blue thinking text
-- Windows, Unix, and classic Mac line-ending support
-- No Nerd Font requirement
-
-## Install
-
-```bash
-pi install npm:pi-compact-tools
-```
-
-Or install from GitHub:
-
-```bash
-pi install git:github.com/nedleeds/pi-compact-tools
-```
-
-Restart Pi or run `/reload`.
-
-Migrating from the previous package name:
-
-```bash
-pi remove npm:@nedleeds/pi-compact-ui
-pi install npm:pi-compact-tools
-```
-
-## Theme
-
-Select `github-dark-pro` in Pi's settings, or add it to `~/.pi/agent/settings.json`:
-
-```json
-{
-  "theme": "github-dark-pro"
-}
-```
-
-## Configuration
-
-Configuration is optional. Create `~/.pi/agent/compact-tools.json` for global settings or `<project>/.pi/compact-tools.json` for a trusted project.
-
-Default configuration:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/schemas/compact-tools.schema.json",
-  "tools": ["read", "write", "edit", "bash"],
-  "auto_compact": {
-    "read": true,
-    "write": true,
-    "edit": false,
-    "bash": true
-  },
-  "spinner": {
-    "frames": ["◐", "◓", "◑", "◒"],
-    "intervalMs": 120
-  }
-}
-```
-
-Successful call titles use a green `●`, while failed call titles use a red `●`. `Done`, `Failed`, and elapsed time use the same neutral control color. Fast tools finish immediately; no artificial spinner delay is added.
-
-For a minimal blinking spinner, copy [`examples/compact-tools-2.json`](examples/compact-tools-2.json). Its frames use `● ● (blank) ● ●` at 120 ms intervals. The renderer's built-in frame dimming turns this into a fade-out/fade-in animation. Rename it to `compact-tools.json` or copy its contents to the active configuration path.
-
-`auto_compact` controls each tool's initial state and whether it participates in the global `Ctrl+O` toggle:
-
-- `true` starts with the result hidden and participates in `Ctrl+O`.
-- `false` starts with the full result visible and is unaffected by `Ctrl+O`.
-- Clicking any compact-rendered row still toggles that row's result.
-
-Unspecified entries inherit the previous configuration layer. By default, `read`, `write`, and `bash` start compact and participate in the global toggle, while `edit` starts expanded and remains unaffected so code diffs stay visible.
-
-To enable all Unix-compatible tools:
-
-```json
-{
-  "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"]
-}
-```
-
-Add `"powershell"` on Windows if desired.
-
-## Nerd Font spinner preset
-
-If your terminal uses a [Nerd Font](https://www.nerdfonts.com/), this preset enables all eight tools and the spinner shown in the demos:
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/schemas/compact-tools.schema.json",
-  "tools": ["read", "write", "edit", "bash", "powershell", "grep", "find", "ls"],
-  "spinner": {
-    "frames": ["✽", "✻", "✲", "✢", "✲", "✻"],
-    "intervalMs": 80
-  }
-}
-```
-
-Remove `"powershell"` on systems where it is unavailable.
-
-## Controls
-
-`Ctrl+T` cycles every thinking block through:
-
-```text
-one-line summary → summary + │-indented detail → one-line summary → Thinking...
-```
-
-Standalone bold lines and Markdown headings split one provider thinking run into logical sections. Each section gets its own summary and optional `│`-indented detail. The control row appears only on sections for which the provider returned expandable detail; when no thinking detail exists, no toggle hint is shown and `Ctrl+T` falls back to Pi's normal visible/hidden toggle instead of showing a duplicate detail phase. While thinking streams, a text-color highlight sweeps across summaries using streaming updates; no spinner glyph or title circle is shown. The transformation is display-only; complete thinking remains unchanged in the session and model context.
-
-Primary invocation targets stay visible, including paths, patterns, and shell commands. After every supported tool completes, the status reports the expanded result size as `Done in …s (N lines)` instead of repeating options such as context and limit. Counts use the returned text for reads, searches, listings, and shell commands, written content for `write`, and the rendered diff for `edit`. The count is computed once after completion and cached with the row, so streaming and repeated expansion do not add ongoing work. Large payloads represented as results, such as write content and edit diffs, follow the result toggle.
-
-A mouse click toggles one row's result:
-
-```text
-result hidden ↔ full result
-```
-
-`Ctrl+O` operates on all rows whose tool has `auto_compact: true`:
-
-- If any participating row is not fully expanded, it expands all participating rows.
-- If every participating row is fully expanded, it collapses all participating rows.
-- Rows whose tool has `auto_compact: false` are left unchanged.
-
-The extension handles and consumes `Ctrl+O` directly, so no Pi keybinding changes are required. With the default `edit: false`, edit diffs start visible and are excluded from the global toggle, while clicking an edit row still collapses or expands it.
-
-## Notes
-
-- Pi `0.85.1+` and Node.js 20+ are recommended.
-- Fullscreen TUI mode is required for spinner animation and mouse interaction; `Ctrl+O` also works in regular mode.
-- Duration covers the full rendered tool-call lifecycle, including streamed `write` and `edit` arguments.
-- Selected tools override Pi's built-in definitions; other extensions overriding the same names may conflict by load order.
-
-## Development
-
-```bash
-npm install
-npm run check
-pi -e .
-```
-
-Pi extensions execute with full system access. Review third-party extension source before installation.
-
-## License
-
-MIT
+# pi-compact-tools
+
+Compact, expandable rendering for Pi's built-in tools, with a polished GitHub Dark theme.
+
+> Formerly `@nedleeds/pi-compact-ui`. New installations should use `pi-compact-tools`.
+
+## Demo
+
+The UI uses portable Unicode symbols and does not require a Nerd Font.
+
+### Compact tool workflow
+
+Active, successful, and failed tool calls stay compact while preserving useful status and timing information.
+
+![Compact tool workflow with Nerd Font](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/nerd-font-workflow-optimized.gif)
+
+### Progress and duration display
+
+The working label above the prompt uses the Thinking summary color with a soft white light sweep. Every tool state uses the same `⦁` glyph; running tools use a fourteen-frame cosine-eased RGB pulse between dim and bright gray, then settle to green on success or red on failure. Elapsed time remains visible in the neutral control color.
+
+![Spinner and elapsed-time display](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/spinner-duration-optimized.gif)
+
+### Bounded result previews
+
+Completed `edit` rows show only the lines actually removed (`-`) or added (`+`), without unchanged context, hunk metadata, or success prose. The per-tool `auto_compact` setting chooses between hidden results and a bounded preview; click or `Ctrl+O` uses Pi's normal expansion flow to reveal all changed lines.
+
+![Edit diff](https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/assets/edit-diff.gif)
+
+## Features
+
+- Compact rendering for `read`, `write`, `edit`, `bash`, `powershell`, `grep`, `find`, and `ls`
+- One continuously glowing working label above the input prompt across thinking and tool execution
+- Semantic built-in progress labels and automatically cleaned custom/MCP tool names; collapsed text-search rows include the searched pattern
+- Four-step `Ctrl+T` thinking cycle when provider detail is available: summary, detail, summary, then hidden
+- Millisecond-precision duration and completed output line counts with neutral status text
+- Per-tool hidden or persistent bounded-preview collapsed state with `auto_compact: true` or `false`
+- Primary invocation targets such as paths and patterns stay visible, including common collapsed shell file operations
+- Click and `Ctrl+O` follow Pi's built-in expansion state while preview rows collapse back to their preview
+- Edit patches display only removed (`-`) and added (`+`) lines, omitting unchanged context
+- Configurable `previewLines` prevents large diffs, HTML, and shell output from flooding the transcript
+- Width-cached expanded results, edit-diff processing, and unchanged result reuse during status animation
+- Dark `│` and `└─` visual grouping
+- Distinct cool-blue thinking text
+- Truecolor and 256-color terminal support, plus Windows, Unix, and classic Mac line endings
+- No Nerd Font requirement
+
+## Install
+
+```bash
+pi install npm:pi-compact-tools
+```
+
+Or install from GitHub:
+
+```bash
+pi install git:github.com/nedleeds/pi-compact-tools
+```
+
+Restart Pi or run `/reload`.
+
+Migrating from the previous package name:
+
+```bash
+pi remove npm:@nedleeds/pi-compact-ui
+pi install npm:pi-compact-tools
+```
+
+## Theme
+
+Select `github-dark-pro` in Pi's settings, or add it to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "theme": "github-dark-pro"
+}
+```
+
+## Configuration
+
+Configuration is optional. Create `~/.pi/agent/compact-tools.json` for global settings or `<project>/.pi/compact-tools.json` for a trusted project.
+
+Default configuration:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/schemas/compact-tools.schema.json",
+  "tools": ["read", "write", "edit", "bash"],
+  "previewLines": 10,
+  "auto_compact": {
+    "read": true,
+    "write": true,
+    "edit": false,
+    "bash": true
+  }
+}
+```
+
+Every tool call title uses `⦁`. Pending calls use dark gray; active calls smoothly pulse through fourteen cosine-eased RGB frames at a 45 ms interval without disappearing. Animation starts while arguments stream, so `write` and `edit` remain visibly active before their filesystem operation begins. Successful titles use green, and failed titles use red. `Done`, `Failed`, elapsed time, and line counts use the same neutral control color without printing inline click or keyboard hints. A single Pi working label animates independently of token arrival and reports `Thinking…`, `Responding…`, semantic built-in states such as `Reading file…`, or cleaned custom states such as `Using jira search…`. Invocation arguments remain in the tool row instead of being duplicated above the prompt. No separate spinner glyph is shown above the prompt.
+
+`auto_compact` controls each tool's initial result state:
+
+- `true` starts with the result hidden.
+- `false` starts with at most `previewLines` rendered rows visible.
+- Clicking or pressing `Ctrl+O` expands the complete result through Pi's built-in expansion state.
+
+`previewLines` accepts `1`–`100` and defaults to `10`. It limits the collapsed preview; the complete result remains available. Unspecified entries inherit the previous configuration layer. By default, `read`, `write`, and `bash` start hidden, while `edit` starts with a short changed-lines preview.
+
+To enable all Unix-compatible tools:
+
+```json
+{
+  "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"]
+}
+```
+
+Add `"powershell"` on Windows if desired.
+
+## Controls
+
+`Ctrl+T` cycles every thinking block through:
+
+```text
+one-line summary → summary + │-indented detail → one-line summary → Thinking...
+```
+
+Standalone bold lines and Markdown headings split one provider thinking run into logical sections. Each section gets its own summary and optional `│`-indented detail. Summary-only views stay uncluttered with no control hint; the control row appears only while provider-supplied detail is visible. When no thinking detail exists, `Ctrl+T` falls back to Pi's normal visible/hidden toggle instead of showing a duplicate detail phase. While thinking streams, a slightly faster highlight sweeps from the Thinking summary color to white across Pi's working label at a steady interval rather than depending on token updates. The transcript summary remains visually stable. The transformation is display-only; complete thinking remains unchanged in the session and model context.
+
+Primary file and search targets stay visible. Collapsed `bash` and `powershell` rows describe intent—such as `Run tests` or `Check repository status`. Text searches retain their primary pattern (for example, `Search text "TODO|FIXME"`), and common file commands retain their operands (for example, `Run rm "build"` or `Find files "*.test.ts" in "src"`). Expanding the row reveals the exact command. After every supported tool completes, the status reports the expanded result size as `Done in …s (N lines)` instead of repeating options such as context and limit. Counts use the returned text for reads, searches, listings, and shell commands, written content for `write`, and only the displayed `-`/`+` lines for `edit`. The count is computed once after completion and cached with the row, so streaming and repeated expansion do not add ongoing work. Large payloads represented as results follow the result toggle.
+
+A mouse click toggles one row using Pi's native result state. `Ctrl+O` remains owned by Pi and expands or collapses all tool rows consistently, including tools not rendered by this extension. A row with `auto_compact: false` cycles predictably between its bounded preview and the complete result, so repeated clicks never remove the row and fall through to a neighboring Thinking block. The extension does not intercept the global keybinding.
+
+## Notes
+
+- Pi `0.85.1+` and Node.js `22.19.0+` are recommended.
+- The working indicator and mouse interaction are provided by Pi's TUI; `Ctrl+O` also works in regular mode.
+- Duration covers the full rendered tool-call lifecycle, including streamed `write` and `edit` arguments.
+- Selected tools override definitions with the same names so their compact renderers are restored reliably after `/reload`; other extensions overriding those tools may conflict by load order.
+
+## Development
+
+```bash
+npm install
+npm run check
+pi -e .
+```
+
+Pi extensions execute with full system access. Review third-party extension source before installation.
+
+## License
+
+MIT

package/examples/compact-tools-2.json

@@ -1,14 +1,11 @@
 {
   "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/schemas/compact-tools.schema.json",
   "tools": ["read", "write", "edit", "bash"],
+  "previewLines": 10,
   "auto_compact": {
     "read": true,
     "write": true,
     "edit": false,
     "bash": true
-  },
-  "spinner": {
-    "frames": ["●", "●", " ", "●", "●"],
-    "intervalMs": 120
   }
 }

package/examples/compact-tools.json

@@ -1,14 +1,11 @@
 {
   "$schema": "https://raw.githubusercontent.com/nedleeds/pi-compact-tools/main/schemas/compact-tools.schema.json",
   "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"],
+  "previewLines": 10,
   "auto_compact": {
     "read": true,
     "write": true,
     "edit": false,
     "bash": true
-  },
-  "spinner": {
-    "frames": ["◐", "◓", "◑", "◒"],
-    "intervalMs": 120
   }
 }

package/extensions/compact-tools-color.ts

@@ -0,0 +1,65 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+export type Rgb = { r: number; g: number; b: number };
+type ThemeForeground = Parameters<Theme["getFgAnsi"]>[0];
+
+const ANSI_BASIC_RGB: readonly Rgb[] = [
+	{ r: 0, g: 0, b: 0 }, { r: 128, g: 0, b: 0 }, { r: 0, g: 128, b: 0 }, { r: 128, g: 128, b: 0 },
+	{ r: 0, g: 0, b: 128 }, { r: 128, g: 0, b: 128 }, { r: 0, g: 128, b: 128 }, { r: 192, g: 192, b: 192 },
+	{ r: 128, g: 128, b: 128 }, { r: 255, g: 0, b: 0 }, { r: 0, g: 255, b: 0 }, { r: 255, g: 255, b: 0 },
+	{ r: 0, g: 0, b: 255 }, { r: 255, g: 0, b: 255 }, { r: 0, g: 255, b: 255 }, { r: 255, g: 255, b: 255 },
+];
+
+function ansi256ToRgb(index: number): Rgb {
+	if (index < 16) return ANSI_BASIC_RGB[index] ?? { r: 192, g: 192, b: 192 };
+	if (index < 232) {
+		const value = index - 16;
+		const channel = (part: number) => part === 0 ? 0 : 55 + part * 40;
+		return {
+			r: channel(Math.floor(value / 36)),
+			g: channel(Math.floor((value % 36) / 6)),
+			b: channel(value % 6),
+		};
+	}
+	const gray = 8 + Math.min(23, index - 232) * 10;
+	return { r: gray, g: gray, b: gray };
+}
+
+function rgbToAnsi256(rgb: Rgb): number {
+	let bestIndex = 0;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (let index = 0; index < 256; index++) {
+		const candidate = ansi256ToRgb(index);
+		const distance = (rgb.r - candidate.r) ** 2 + (rgb.g - candidate.g) ** 2 + (rgb.b - candidate.b) ** 2;
+		if (distance >= bestDistance) continue;
+		bestIndex = index;
+		bestDistance = distance;
+	}
+	return bestIndex;
+}
+
+export function themeColorRgb(theme: Theme, color: ThemeForeground): Rgb | undefined {
+	if (typeof theme.getFgAnsi !== "function") return undefined;
+	const ansi = theme.getFgAnsi(color);
+	const trueColor = ansi.match(/\[38;2;(\d+);(\d+);(\d+)m/u);
+	if (trueColor) return { r: Number(trueColor[1]), g: Number(trueColor[2]), b: Number(trueColor[3]) };
+	const indexed = ansi.match(/\[38;5;(\d+)m/u);
+	return indexed ? ansi256ToRgb(Number(indexed[1])) : undefined;
+}
+
+export function interpolateRgb(from: Rgb, to: Rgb, amount: number): Rgb {
+	const bounded = Math.max(0, Math.min(1, amount));
+	const channel = (start: number, end: number) => Math.round(start + (end - start) * bounded);
+	return {
+		r: channel(from.r, to.r),
+		g: channel(from.g, to.g),
+		b: channel(from.b, to.b),
+	};
+}
+
+export function colorizeRgb(theme: Theme, color: Rgb, text: string): string {
+	if (typeof theme.getColorMode === "function" && theme.getColorMode() === "256color") {
+		return `\x1b[38;5;${rgbToAnsi256(color)}m${text}\x1b[39m`;
+	}
+	return `\x1b[38;2;${color.r};${color.g};${color.b}m${text}\x1b[39m`;
+}

package/extensions/compact-tools-config.ts

@@ -12,6 +12,7 @@ type JsonObject = Record<string, unknown>;
 
 export const DEFAULT_CONFIG: CompactToolsConfig = {
 	tools: ["read", "write", "edit", "bash"],
+	previewLines: 10,
 	auto_compact: {
 		read: true,
 		write: true,
@@ -22,10 +23,6 @@ export const DEFAULT_CONFIG: CompactToolsConfig = {
 		find: true,
 		ls: true,
 	},
-	spinner: {
-		frames: ["◐", "◓", "◑", "◒"],
-		intervalMs: 120,
-	},
 };
 
 function isObject(value: unknown): value is JsonObject {
@@ -40,10 +37,6 @@ function isIntegerInRange(value: unknown, minimum: number, maximum: number): val
 	return typeof value === "number" && Number.isInteger(value) && value >= minimum && value <= maximum;
 }
 
-function isNonEmptyStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === "string" && item.length > 0);
-}
-
 function parseTools(value: unknown, path: string): CompactToolName[] | undefined {
 	if (!Array.isArray(value)) {
 		warn(path, "tools must be an array; using previous values");
@@ -82,28 +75,6 @@ function parseAutoCompact(
 	return result;
 }
 
-function parseSpinner(
-	base: CompactToolsConfig["spinner"],
-	value: unknown,
-	path: string,
-): CompactToolsConfig["spinner"] {
-	if (value === undefined) return base;
-	if (!isObject(value)) {
-		warn(path, "spinner must be an object; using previous values");
-		return base;
-	}
-	const frames = value.frames;
-	const intervalMs = value.intervalMs;
-	const validFrames = isNonEmptyStringArray(frames);
-	const validInterval = isIntegerInRange(intervalMs, 40, 5_000);
-	if (frames !== undefined && !validFrames) warn(path, "spinner.frames must be a non-empty string array");
-	if (intervalMs !== undefined && !validInterval) warn(path, "spinner.intervalMs must be 40–5000");
-	return {
-		frames: validFrames ? frames : base.frames,
-		intervalMs: validInterval ? intervalMs : base.intervalMs,
-	};
-}
-
 export function mergeConfig(base: CompactToolsConfig, value: unknown, path: string): CompactToolsConfig {
 	if (value === undefined) return base;
 	if (!isObject(value)) {
@@ -112,8 +83,12 @@ export function mergeConfig(base: CompactToolsConfig, value: unknown, path: stri
 	}
 	const tools = value.tools === undefined ? base.tools : (parseTools(value.tools, path) ?? base.tools);
 	const auto_compact = parseAutoCompact(base.auto_compact, value.auto_compact, path);
-	const spinner = parseSpinner(base.spinner, value.spinner, path);
-	return { tools, auto_compact, spinner };
+	const previewLines = value.previewLines === undefined ? base.previewLines
+		: isIntegerInRange(value.previewLines, 1, 100) ? value.previewLines : base.previewLines;
+	if (value.previewLines !== undefined && !isIntegerInRange(value.previewLines, 1, 100)) {
+		warn(path, "previewLines must be 1–100; using previous value");
+	}
+	return { tools, auto_compact, previewLines };
 }
 
 function readJson(path: string): unknown {
@@ -133,13 +108,3 @@ export function loadConfig(cwd?: string, projectTrusted = false): CompactToolsCo
 	const projectPath = join(cwd, CONFIG_DIR_NAME, CONFIG_FILE);
 	return mergeConfig(globalConfig, readJson(projectPath), projectPath);
 }
-
-export function isFullscreenMode(argv = process.argv): boolean {
-	for (let index = 0; index < argv.length; index++) {
-		const argument = argv[index];
-		if (argument === "--tui-mode") return argv[index + 1] === "fullscreen";
-		if (argument?.startsWith("--tui-mode=")) return argument.slice("--tui-mode=".length) === "fullscreen";
-	}
-	const settings = readJson(join(getAgentDir(), "settings.json"));
-	return isObject(settings) && settings.tuiMode === "fullscreen";
-}

package/extensions/compact-tools-core.ts

@@ -2,6 +2,32 @@
 
 export type RowStatus = "pending" | "running" | "success" | "error";
 
+export type IndicatorTone = "borderAccent" | "border" | "borderMuted" | "success" | "error";
+
+export const RUNNING_INDICATOR_FRAME_COUNT = 14;
+const RUNNING_INDICATOR_MIN_STRENGTH = 0.08;
+
+export function indicatorStrength(status: RowStatus, frame = 0): number {
+	if (status !== "running") return 1;
+	const normalizedFrame = ((frame % RUNNING_INDICATOR_FRAME_COUNT) + RUNNING_INDICATOR_FRAME_COUNT)
+		% RUNNING_INDICATOR_FRAME_COUNT;
+	const wave = (Math.cos((normalizedFrame / RUNNING_INDICATOR_FRAME_COUNT) * Math.PI * 2) + 1) / 2;
+	return RUNNING_INDICATOR_MIN_STRENGTH + (1 - RUNNING_INDICATOR_MIN_STRENGTH) * wave;
+}
+
+/** Semantic fallback for themes whose foreground RGB values cannot be resolved. */
+export function indicatorTone(status: RowStatus, frame = 0): IndicatorTone {
+	if (status === "success") return "success";
+	if (status === "error") return "error";
+	if (status === "pending") return "borderAccent";
+	const strength = indicatorStrength(status, frame);
+	return strength >= 0.7 ? "borderAccent" : strength >= 0.35 ? "border" : "borderMuted";
+}
+
+export function indicatorGlyph(_status: RowStatus, _frame = 0): string {
+	return "⦁";
+}
+
 export function normalizeLineEndings(value: string): string {
 	return value.replace(/\r\n?|\n/g, "\n");
 }