@jack-yang/pi-tps-meter 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.0] - 2026-11-03
+
+- New default display `right`: one line below the editor, right-aligned so it ends in the last
+  column, directly above the footer. Other extensions' footer statuses (such as pi-lens's
+  `LSP Inactive`) can no longer push it around. `/tps` now cycles right → status → widget → off;
+  a saved `mode` in config.json still wins.
+- The thinking particle stream from opencode-tps-meter is back: while the model streams its
+  reasoning, braille particles flow away from the reading, newest brightest, fading per cell.
+  Configurable via `spinner` (`theme` tech / red / none, `colors`, `intervalMs`, `cells`, `enabled`).
+
 ## [0.1.1] - 2026-11-03
 
 - Published from GitHub Actions through npm Trusted Publishing, so this and later versions

package/README.md

@@ -9,20 +9,17 @@
 ## 显示效果
 
 ```
-TPS 42.5 | AVG 38.2 | TTFT 0.8s
+⠔⠀⠈⠀⠤⠔ TPS 42.5 | AVG 38.2 | TTFT 0.8s
 ```
 
-底部状态条（`/tps status`，默认），流式输出中：
+默认显示在编辑器下方、右对齐（`/tps right`），紧贴 footer，和下方的模型名右侧对齐；位置固定，不会被其他扩展的 footer 状态（比如 pi-lens 的 `LSP Inactive`）挤开。下图是模型思考时的样子，读数左边是思考粒子流：
 
-![底部状态条模式：流式输出中，TPS 40.8 / AVG 39.8 / TTFT 2.0s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-status.png)
-
-编辑器上方组件（`/tps widget`）：
-
-![编辑器上方组件模式：TPS 40.2 / AVG 38.1 / TTFT 3.2s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-widget.png)
+![编辑器下方右对齐：思考中，粒子流 + TPS 26.0 / AVG 33.7 / TTFT 3.9s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-right.png)
 
 - **TPS**：流式输出时的实时速度，基于 5 秒滑动窗口，约 10Hz 刷新；超过 1.5 秒没有新 token 时显示 `--`。
 - **AVG**：会话级累计平均。所有已完成消息的权威 token 数之和，除以各消息生成时长之和。
 - **TTFT**：从本轮请求开始到第一个文本或思考 token 的时间。首个 token 到达立即显示，一直保留到下一次生成开始。
+- **思考粒子流**：模型流式输出思考内容时，一串盲文点从读数旁流出：最新的一格最亮，越旧越淡，亮色随时间沿渐变色漂移；开始输出正文就消失。只在思考时出现，平时不占位。
 
 流结束后 AVG / TTFT 摘要不会清空：工具执行期间、等待下一轮响应期间都保持可见，下一条助手消息开始时才更新。
 
@@ -65,32 +62,43 @@ pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写
 
 | 命令 | 作用 |
 |---|---|
-| `/tps` | 循环切换 status → widget → off |
-| `/tps status` | 显示在底部状态条（footer），和其他扩展的状态共用一行 |
-| `/tps widget` | 显示为编辑器上方的单行组件 |
+| `/tps` | 循环切换 right → status → widget → off |
+| `/tps right` | 编辑器下方、右对齐（默认）：紧贴 footer，位置固定 |
+| `/tps status` | footer 的扩展状态行，和其他扩展共用一行，按扩展名排序 |
+| `/tps widget` | 编辑器上方的单行组件 |
 | `/tps off` | 完全隐藏。计量仍在后台进行，切回来立即显示当前读数 |
 
 模式写入配置文件，下次启动沿用。
 
+为什么右对齐是单独一行，而不是放进 footer 状态行的右端：pi 把所有扩展的状态按名字排序、左对齐拼成一行，扩展没法指定位置；要放到右端只能整个替换 pi 的 footer，不值得。编辑器下方的组件是自己渲染的，可以按终端宽度右对齐，窗口缩放时也贴着右边。
+
+如果也嫌 pi-lens 的 `LSP Inactive` 占地方，pi-lens 自己有开关：在 `~/.pi-lens/config.json` 里设 `ui.compactLspStatus: true`（压成一个图标）或 `ui.hideLspStatus: true`（不显示）。
+
 ## 配置
 
 配置文件位于 `~/.pi/agent/pi-tps-meter/config.json`；设置了 `PI_CODING_AGENT_DIR` 时，位于该目录下的 `pi-tps-meter/config.json`。
 
 ```json
 {
-  "mode": "status",
+  "mode": "right",
   "tiers": {
     "tps":  { "slow": 20, "normal": 50, "fast": 100 },
     "ttft": { "fast": 10000, "ok": 20000 }
-  }
+  },
+  "spinner": { "theme": "tech", "intervalMs": 100, "cells": 6 }
 }
 ```
 
 | 键 | 默认值 | 说明 |
 |---|---|---|
-| `mode` | `"status"` | `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
+| `mode` | `"right"` | `right` / `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
 | `tiers.tps` | `{ slow: 20, normal: 50, fast: 100 }` | TPS 与 AVG 的分档阈值（tok/s） |
 | `tiers.ttft` | `{ fast: 10000, ok: 20000 }` | TTFT 分档阈值（毫秒） |
+| `spinner.theme` | `"tech"` | 粒子流配色：`"tech"`（青 → 蓝 → 紫）、`"red"`（KITT 风格红）；`"none"` 关闭粒子流 |
+| `spinner.colors` | 随 theme | 自定义渐变色，`"#rrggbb"` / `"#rgb"` 数组，优先于 theme |
+| `spinner.intervalMs` | `100` | 粒子前进一格的间隔（毫秒） |
+| `spinner.cells` | `6` | 粒子流格数（宽度），至少 2 |
+| `spinner.enabled` | `true` | `false` 关闭粒子流 |
 
 - 所有键都可省略，按字段覆盖默认值，例如只写 `{ "tiers": { "tps": { "fast": 80 } } }`。不是数字的值会被忽略。
 - 文件在会话启动时读取，手动修改后执行 `/reload` 生效。
@@ -138,14 +146,14 @@ TTFT 从 `turn_start` 开始计时（在 pi 里，一个 turn 就是一次模型
 - 下一条助手消息开始时清空 TTFT，原版要等到下一个首 token 才覆盖。
 - toolcall delta 计入 TPS 和校准，因为 pi 的 `usage.output` 包含工具调用参数的 token；原版只统计文本和推理。TTFT 仍然只认文本和思考。
 - 权威 token 数直接用 `usage.output`：pi 的 output 已经包含推理 token，原版需要把 output 和 reasoning 相加。
-- 没有移植思考粒子动画，pi 自带工作指示器。
+- 思考粒子流已移植（配色预设、渐变、FIFO 流动、配置项都和原版一致），并做了原版想做但受限于 opencode 做不到的一点：每个粒子单独着色，真正从亮到暗渐隐（原版受 opentui 限制，整串只能用一种颜色）。右对齐时粒子流放在读数左边、方向镜像，读数本身不会移动。
 - 颜色用 ANSI 基本色：红 31、黄 33、绿 32、青 36，标签用暗色；原版用的是 opencode 主题槽位。
 
 ## 已知限制
 
 - **不流式输出的推理**：有些模型按推理 token 计费，但不把推理内容流式发出来。这时校准比率会顶到 3.0 上限，AVG 也会偏高（原版同样如此）。
 - **一次性返回工具参数的 provider**（如 Gemini）：消息末尾会出现一个短暂的 TPS 尖峰，消息结束后立即清除。
-- **底部状态条依赖 pi 的默认 footer**：如果另一个扩展换掉了 footer，并且不渲染扩展状态（比如 awesome-pi-themes 的 look-pack），请改用 `/tps widget`。
+- **`status` 模式依赖 pi 的默认 footer**：如果另一个扩展换掉了 footer，并且不渲染扩展状态（比如 awesome-pi-themes 的 look-pack），用默认的 `right` 或 `widget`。
 - **AVG 和校准只在当前会话内累计**：`/new`、`/resume`、`/fork`、`/reload` 会重新开始；不会从历史记录里重建。
 - **TTFT 包含客户端准备时间**：包括请求前的上下文处理（实测约 7ms）和 provider 层的自动重试等待，也就是用户实际等待的时间。
 - **时间戳取自 pi 把事件派发给扩展的时刻**：其他扩展的慢 handler 会推迟派发，从而影响读数。

package/extensions/index.ts

@@ -1,20 +1,25 @@
 // pi-tps-meter — live TPS / AVG / TTFT for the pi coding agent.
 //
-// Port of opencode-tps-meter: the measurement core (src/core.ts) and the formatting
-// (src/format.ts) are the original's. This file is the replaced host layer: pi events in,
-// a footer status line or a widget above the editor out.
+// Port of opencode-tps-meter: the measurement core (src/core.ts), the formatting (src/format.ts)
+// and the thinking particle stream (src/spinner.ts) are the original's. This file is the replaced
+// host layer: pi events in; a right-aligned line below the editor, a footer status, or a line
+// above the editor out.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
 import { DISPLAY_MODES, isDisplayMode, loadConfig, nextMode, resolveConfig, saveMode, type DisplayMode, type MeterConfig } from "../src/config.ts"
 import { abandonMessage, completeMessage, createMeterState, readMeter, recordDelta, startMessage, startTurn, type DeltaKind, type MeterState } from "../src/core.ts"
-import { renderLine } from "../src/format.ts"
+import { alignRight, renderLine, withSpinner } from "../src/format.ts"
+import { advanceSpinner, createSpinner, spinnerCells, type Rgb, type SpinnerState } from "../src/spinner.ts"
 
-// One key for both surfaces: the footer status entry and the widget.
+// One key for every surface: the footer status entry and the widget.
 const KEY = "tps-meter"
 
 // ~10Hz: smooth enough for a rolling number without re-rendering on every delta.
 const REFRESH_MS = 100
 
+// Older particles fade toward this neutral grey (the original faded toward the theme's muted text).
+const SPINNER_MUTED: Rgb = { r: 128, g: 132, b: 142 }
+
 type UI = ExtensionContext["ui"]
 
 export default function tpsMeter(pi: ExtensionAPI): void {
@@ -23,17 +28,42 @@ export default function tpsMeter(pi: ExtensionAPI): void {
   // start a session, so it does no IO and starts no timers.
   let config: MeterConfig = resolveConfig(undefined)
   let ui: UI | undefined
-  let color = false
+  let tui = false
   let ticker: ReturnType<typeof setInterval> | undefined
+  let spinner: SpinnerState | undefined
   // What is on screen right now, so unchanged readings cost no re-render.
   let shownMode: DisplayMode | undefined
   let shownLine: string | undefined
+  // The mounted right-aligned component's host, told to redraw when the line changes.
+  let rightHost: { requestRender(): void } | undefined
 
   // Handlers re-bind from their own ctx; the ticker only ever uses the latest binding.
   const bind = (ctx: ExtensionContext): void => {
     ui = ctx.hasUI ? ctx.ui : undefined
-    // The TUI renders ANSI in status text and widget lines; RPC clients get plain text.
-    color = ctx.mode === "tui"
+    // The TUI renders ANSI and components; RPC clients get plain text lines.
+    tui = ctx.mode === "tui"
+  }
+
+  // The particle stream exists only while reasoning streams, and only in the TUI (in RPC it would
+  // just be noise at 10Hz). A fresh stream starts each time thinking starts.
+  const decorate = (target: UI, line: string, now: number): string => {
+    if (!tui || !config.spinner.enabled || !state.thinking) {
+      spinner = undefined
+      return line
+    }
+    if (spinner === undefined) spinner = createSpinner(config.spinner.cells, now, Math.random)
+    else advanceSpinner(spinner, config.spinner, now, Math.random)
+    const paint = (text: string, c: Rgb) => target.theme.style(text, { fg: { kind: "rgb", r: c.r, g: c.g, b: c.b } })
+    return withSpinner(line, spinnerCells(spinner, config.spinner, SPINNER_MUTED), paint, config.mode === "right" ? "before" : "after")
+  }
+
+  // A component rather than a string widget: it right-aligns itself to the width of every render,
+  // so it stays in the corner across terminal resizes, and an update is only a redraw request.
+  const mountRight = (target: UI): void => {
+    target.setWidget(KEY, (host) => {
+      rightHost = host
+      return { render: (width: number) => [alignRight(shownLine ?? "", width)], invalidate() {} }
+    }, { placement: "belowEditor" })
   }
 
   const render = (): void => {
@@ -42,16 +72,22 @@ export default function tpsMeter(pi: ExtensionAPI): void {
     if (mode !== shownMode) {
       // Exactly one surface (or none) shows the meter: clear the one being left.
       if (shownMode === "status") ui.setStatus(KEY, undefined)
-      if (shownMode === "widget") ui.setWidget(KEY, undefined)
+      if (shownMode === "widget" || shownMode === "right") ui.setWidget(KEY, undefined)
+      rightHost = undefined
       shownMode = mode
       shownLine = undefined
+      if (mode === "right" && tui) mountRight(ui)
     }
     if (mode === "off") return
-    const line = renderLine(readMeter(state, Date.now()), config.tiers, color)
+    const now = Date.now()
+    const line = decorate(ui, renderLine(readMeter(state, now), config.tiers, tui), now)
     if (line === shownLine) return
     shownLine = line
     if (mode === "status") ui.setStatus(KEY, line)
-    else ui.setWidget(KEY, [line])
+    else if (mode === "widget") ui.setWidget(KEY, [line])
+    // RPC ignores component widgets; there the line goes out as plain text below the editor.
+    else if (tui) rightHost?.requestRender()
+    else ui.setWidget(KEY, [line], { placement: "belowEditor" })
   }
 
   const stopTicker = (): void => {
@@ -130,10 +166,12 @@ export default function tpsMeter(pi: ExtensionAPI): void {
     // reference to this session's UI are the only things left for us to drop.
     stopTicker()
     ui = undefined
+    rightHost = undefined
+    spinner = undefined
   })
 
   pi.registerCommand("tps", {
-    description: "TPS meter display: /tps cycles status → widget → off, /tps status|widget|off sets it",
+    description: "TPS meter display: /tps cycles right → status → widget → off, /tps right|status|widget|off sets it",
     getArgumentCompletions: (prefix) => {
       // Only strict prefixes: pi's editor makes Enter apply an open argument completion instead
       // of submitting, so a fully typed mode must close the popup or `/tps off` needs two Enters.
@@ -145,7 +183,7 @@ export default function tpsMeter(pi: ExtensionAPI): void {
       bind(ctx)
       const arg = args.trim().toLowerCase()
       if (arg && !isDisplayMode(arg)) {
-        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use status | widget | off)`, "error")
+        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use right | status | widget | off)`, "error")
         return
       }
       const mode = isDisplayMode(arg) ? arg : nextMode(config.mode)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@jack-yang/pi-tps-meter",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Live TPS / AVG / TTFT meter for the pi coding agent, calibrated against authoritative token counts (port of opencode-tps-meter)",
   "type": "module",
   "keywords": [
@@ -36,7 +36,7 @@
     "extensions": [
       "./extensions/index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-status.png"
+    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-right.png"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/config.ts

@@ -1,22 +1,26 @@
-// Display mode persistence and tier overrides — the only module that touches the filesystem.
+// Display mode persistence, tier and spinner overrides — the only module that touches the filesystem.
 //
 // File: <agent dir>/pi-tps-meter/config.json, where <agent dir> is $PI_CODING_AGENT_DIR or
 // ~/.pi/agent, resolved the same way pi resolves its own config directory.
 //
-//   { "mode": "status", "tiers": { "tps": { "slow": 20, "normal": 50, "fast": 100 },
-//                                  "ttft": { "fast": 10000, "ok": 20000 } } }
+//   { "mode": "right",
+//     "tiers": { "tps": { "slow": 20, "normal": 50, "fast": 100 }, "ttft": { "fast": 10000, "ok": 20000 } },
+//     "spinner": { "theme": "tech", "colors": ["#00e5ff", "#2979ff"], "intervalMs": 100, "cells": 6, "enabled": true } }
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join } from "node:path"
 import type { Tiers } from "./format.ts"
+import { parseHex, THEME_PRESETS, type Rgb, type SpinnerConfig } from "./spinner.ts"
 
-export type DisplayMode = "status" | "widget" | "off"
+// right: one line below the editor, right-aligned (a fixed spot that other extensions' footer
+// statuses cannot push around); status: pi's footer status line; widget: a line above the editor.
+export type DisplayMode = "right" | "status" | "widget" | "off"
 
 // Also the cycle order of a bare `/tps`.
-export const DISPLAY_MODES: readonly DisplayMode[] = ["status", "widget", "off"]
+export const DISPLAY_MODES: readonly DisplayMode[] = ["right", "status", "widget", "off"]
 
-export type MeterConfig = { mode: DisplayMode; tiers: Tiers }
+export type MeterConfig = { mode: DisplayMode; tiers: Tiers; spinner: SpinnerConfig }
 
 export type LoadedConfig = { config: MeterConfig; warning?: string }
 
@@ -33,17 +37,29 @@ export function nextMode(mode: DisplayMode): DisplayMode {
 // The original's resolveConfig override shape: `tiers.tps` / `tiers.ttft`, field by field over
 // the defaults. Values that are not finite numbers fall back to the default instead of reaching
 // the tier comparisons, where a string or null would silently mis-tier every reading.
+// `spinner` follows the original too: custom `colors` win over the `theme` preset, theme "none"
+// or `enabled: false` turns the stream off, `cells` is at least 2.
 export function resolveConfig(raw: unknown): MeterConfig {
   const o = isObject(raw) ? raw : {}
   const tiers = isObject(o.tiers) ? o.tiers : {}
   const tp = isObject(tiers.tps) ? tiers.tps : {}
   const tt = isObject(tiers.ttft) ? tiers.ttft : {}
+  const sp = isObject(o.spinner) ? o.spinner : {}
+  const theme = typeof sp.theme === "string" ? sp.theme : "tech"
+  const custom = hexColors(sp.colors)
+  const preset = hexColors(THEME_PRESETS[theme] ?? THEME_PRESETS.tech)
   return {
-    mode: isDisplayMode(o.mode) ? o.mode : "status",
+    mode: isDisplayMode(o.mode) ? o.mode : "right",
     tiers: {
       tps: { slow: num(tp.slow, 20), normal: num(tp.normal, 50), fast: num(tp.fast, 100) },
       ttft: { fast: num(tt.fast, 10_000), ok: num(tt.ok, 20_000) },
     },
+    spinner: {
+      enabled: sp.enabled !== false && theme !== "none",
+      colors: custom.length > 0 ? custom : preset,
+      intervalMs: positive(sp.intervalMs) ?? 100,
+      cells: (positive(sp.cells) ?? 0) >= 2 ? Math.floor(sp.cells as number) : 6,
+    },
   }
 }
 
@@ -105,3 +121,16 @@ function isObject(value: unknown): value is Record<string, unknown> {
 function num(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback
 }
+
+function positive(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+// The valid "#rrggbb" / "#rgb" entries of a config value, in order; anything else is dropped.
+function hexColors(value: unknown): Rgb[] {
+  if (!Array.isArray(value)) return []
+  return value.flatMap((c) => {
+    const rgb = typeof c === "string" ? parseHex(c) : undefined
+    return rgb ? [rgb] : []
+  })
+}

package/src/core.ts

@@ -36,6 +36,7 @@ export type MeterState = {
   lastDeltaAt: number | undefined // lastDeltaByMessage
   estimatedTokens: number // estimatedTokensByMessage
   ttftMs: number | undefined // liveTtftBySession
+  thinking: boolean // thinkingBySession: the latest delta was reasoning (drives the particle stream)
 }
 
 export type MeterReading = {
@@ -93,6 +94,7 @@ export function createMeterState(): MeterState {
     lastDeltaAt: undefined,
     estimatedTokens: 0,
     ttftMs: undefined,
+    thinking: false,
   }
 }
 
@@ -118,6 +120,7 @@ export function startMessage(state: MeterState, at: number): void {
   state.lastDeltaAt = undefined
   state.estimatedTokens = 0
   state.samples = []
+  state.thinking = false
 }
 
 // One streamed chunk (the original's recordDelta). Every kind feeds the window, the span and the
@@ -133,6 +136,9 @@ export function recordDelta(state: MeterState, at: number, delta: string, kind:
   if (state.firstDeltaAt === undefined) state.firstDeltaAt = at
   state.lastDeltaAt = at
   state.estimatedTokens += rawTokens
+  // As the original's setThinking: reasoning turns it on; text and the tool-call stream (the
+  // original cleared it on tool input start) turn it off.
+  state.thinking = kind === "thinking"
   if (kind === "toolcall" || state.ttftMs !== undefined || state.ttftOrigin === undefined) return false
   state.ttftMs = Math.max(0, at - state.ttftOrigin)
   return true
@@ -178,6 +184,7 @@ function endMessage(state: MeterState): void {
   state.lastDeltaAt = undefined
   state.estimatedTokens = 0
   state.samples = []
+  state.thinking = false
 }
 
 // What the meter shows at `now` (the original's MeterDisplay sync).

package/src/format.ts

@@ -1,7 +1,9 @@
-// Display formatting and tier colouring, ported from opencode-tps-meter/tui.tsx.
+// Display formatting and tier colouring, ported from opencode-tps-meter/tui.tsx, plus the layout
+// of the thinking particle stream and right alignment.
 // Pure: no pi imports. The caller decides whether the host renders ANSI.
 
 import type { MeterReading } from "./core.ts"
+import type { Rgb, SpinnerCell } from "./spinner.ts"
 
 export type TpsTiers = { slow: number; normal: number; fast: number }
 export type TtftTiers = { fast: number; ok: number }
@@ -102,3 +104,36 @@ export function renderLine(reading: MeterReading, tiers: Tiers, color: boolean):
   ]
   return cells.map((c) => (color ? paint(c.text, c.hue) : c.text)).join("")
 }
+
+// Gaps in the stream are U+2800, the empty braille cell: one column, blank on screen, and not
+// whitespace. pi's footer sanitizer collapses runs of spaces and trims both ends of a status (JS
+// trim() also strips no-break spaces), either of which would make the stream jitter in width.
+const GAP = "\u2800"
+
+// The particle stream flows away from the meter. After the reading (status / widget) it runs
+// left to right, newest cell next to TTFT, as in the original. Before a right-aligned reading it
+// is mirrored, newest cell next to TPS, so the reading itself never moves.
+export function withSpinner(
+  line: string,
+  cells: SpinnerCell[],
+  paintRgb: (text: string, color: Rgb) => string,
+  side: "before" | "after",
+): string {
+  const ordered = side === "after" ? cells : [...cells].reverse()
+  const stream = ordered.map((c) => (c.glyph === " " ? GAP : paintRgb(c.glyph, c.color))).join("")
+  return side === "after" ? `${line} ${stream}` : `${stream} ${line}`
+}
+
+// Terminal columns of a string produced here: ANSI SGR codes take none, and every character used
+// (ASCII, braille) takes exactly one.
+export function visibleWidth(text: string): number {
+  return [...text.replace(/\x1b\[[0-9;]*m/g, "")].length
+}
+
+// Pads `line` so it ends in the last column. A line too wide for the terminal loses its colours and
+// is cut, because a TUI line must never exceed the width it is given.
+export function alignRight(line: string, width: number): string {
+  const w = visibleWidth(line)
+  if (w <= width) return " ".repeat(width - w) + line
+  return [...line.replace(/\x1b\[[0-9;]*m/g, "")].slice(w - width).join("")
+}

package/src/spinner.ts

@@ -0,0 +1,84 @@
+// The "thinking" particle stream, ported from opencode-tps-meter/tui.tsx: while reasoning streams,
+// a short FIFO of braille dots flows away from the meter, newest cell brightest, older cells fading
+// into the muted colour, the bright colour drifting along a gradient over time.
+//
+// Pure: randomness and the clock are parameters. Colours are plain sRGB; the extension paints them
+// through pi's theme, which converts to truecolor or 256 colours for the terminal.
+
+export type Rgb = { r: number; g: number; b: number }
+
+export type SpinnerConfig = { enabled: boolean; colors: Rgb[]; intervalMs: number; cells: number }
+
+export type SpinnerState = { stream: string[]; hueFrame: number; lastFrameAt: number }
+
+export type SpinnerCell = { glyph: string; color: Rgb }
+
+export type Random = () => number
+
+const DOT_GLYPHS = ["⠁", "⠂", "⠄", "⠈", "⠐", "⠠", "⠒", "⠑", "⠡", "⠢", "⠤", "⠨", "⠰", "⠸", "⠘", "⠔", "⠖", "⠦"]
+
+// One full sweep of the gradient takes this many frames (6s at the default 100ms).
+const HUE_FRAMES = 60
+
+export const THEME_PRESETS: Record<string, string[]> = {
+  tech: ["#00e5ff", "#2979ff", "#651fff"],
+  red: ["#ff1744", "#ff5252", "#ff8a80"],
+}
+
+// "#rrggbb" or "#rgb". The leading # is required: without it, words such as "bad" or "add" would
+// read as three-digit colours.
+export function parseHex(hex: string): Rgb | undefined {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim())
+  if (!m) return undefined
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join("") : m[1]
+  return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) }
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t
+}
+
+export function lerpColor(a: Rgb, b: Rgb, t: number): Rgb {
+  return { r: Math.round(lerp(a.r, b.r, t)), g: Math.round(lerp(a.g, b.g, t)), b: Math.round(lerp(a.b, b.b, t)) }
+}
+
+// Position t in [0, 1] along a multi-stop gradient.
+export function gradientColor(colors: Rgb[], t: number): Rgb {
+  if (colors.length === 0) return { r: 136, g: 136, b: 136 }
+  if (colors.length === 1) return colors[0]
+  const c = Math.max(0, Math.min(1, t))
+  const seg = c * (colors.length - 1)
+  const i = Math.min(Math.floor(seg), colors.length - 2)
+  return lerpColor(colors[i], colors[i + 1], seg - i)
+}
+
+// Roughly one cell in five is a gap, so the stream reads as particles rather than a solid bar.
+function spawnGlyph(random: Random): string {
+  return random() < 0.18 ? " " : DOT_GLYPHS[Math.floor(random() * DOT_GLYPHS.length)]
+}
+
+// A fresh stream each time thinking starts, so consecutive thinking spans do not look identical.
+export function createSpinner(cells: number, now: number, random: Random): SpinnerState {
+  return { stream: Array.from({ length: cells }, () => spawnGlyph(random)), hueFrame: 0, lastFrameAt: now }
+}
+
+// Frames follow wall time (one per `intervalMs`), not render calls, so the stream keeps its speed
+// whatever the refresh rate. The frame count is capped so a long pause cannot loop for ages.
+export function advanceSpinner(state: SpinnerState, cfg: SpinnerConfig, now: number, random: Random): void {
+  const due = Math.floor((now - state.lastFrameAt) / cfg.intervalMs)
+  if (due <= 0) return
+  for (let i = 0; i < Math.min(due, cfg.cells); i++) {
+    state.stream.unshift(spawnGlyph(random))
+    if (state.stream.length > cfg.cells) state.stream.length = cfg.cells
+  }
+  state.hueFrame += due
+  state.lastFrameAt += due * cfg.intervalMs
+}
+
+// Cell 0 is the newest and carries the current gradient colour; each older cell fades a step
+// further toward `muted`. Gaps stay muted.
+export function spinnerCells(state: SpinnerState, cfg: SpinnerConfig, muted: Rgb): SpinnerCell[] {
+  const bright = gradientColor(cfg.colors, (state.hueFrame % HUE_FRAMES) / HUE_FRAMES)
+  const last = Math.max(1, state.stream.length - 1)
+  return state.stream.map((glyph, i) => ({ glyph, color: glyph === " " ? muted : lerpColor(bright, muted, i / last) }))
+}