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

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.3.0] - 2026-11-04
+
+- New default display `footer`: the meter sits at the right end of pi's footer line with the
+  working directory, in line with the model name below it, without taking an extra line. pi's
+  own `FooterComponent` still renders the whole footer (the stats and status lines are
+  byte-for-byte pi's); the meter is merged into its first line. On a narrow terminal the
+  directory is shortened first, so the reading stays whole.
+- If pi's footer cannot be wrapped (for example a future pi changes its internals), pi's own
+  footer is restored and the meter falls back to `right`, with a one-time notice.
+- `/tps` cycles footer → right → status → widget → off; a saved `mode` still wins.
+
 ## [0.2.0] - 2026-11-03
 
 - New default display `right`: one line below the editor, right-aligned so it ends in the last

package/README.md

@@ -12,9 +12,9 @@
 ⠔⠀⠈⠀⠤⠔ TPS 42.5 | AVG 38.2 | TTFT 0.8s
 ```
 
-默认显示在编辑器下方、右对齐（`/tps right`），紧贴 footer，和下方的模型名右侧对齐；位置固定，不会被其他扩展的 footer 状态（比如 pi-lens 的 `LSP Inactive`）挤开。下图是模型思考时的样子，读数左边是思考粒子流：
+默认显示在 footer 的目录那一行右端（`/tps footer`），和下一行的模型名右对齐，不额外占行；其他扩展的 footer 状态（比如 pi-lens 的 `LSP Inactive`）也挤不动它。下图是模型思考时的样子，读数左边是思考粒子流：
 
-![编辑器下方右对齐：思考中，粒子流 + TPS 26.0 / AVG 33.7 / TTFT 3.9s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-right.png)
+![footer 目录行右端：思考中，粒子流 + TPS 38.2 / AVG 62.2 / TTFT 1.9s](https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-footer.png)
 
 - **TPS**：流式输出时的实时速度，基于 5 秒滑动窗口，约 10Hz 刷新；超过 1.5 秒没有新 token 时显示 `--`。
 - **AVG**：会话级累计平均。所有已完成消息的权威 token 数之和，除以各消息生成时长之和。
@@ -62,15 +62,16 @@ pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写
 
 | 命令 | 作用 |
 |---|---|
-| `/tps` | 循环切换 right → status → widget → off |
-| `/tps right` | 编辑器下方、右对齐（默认）：紧贴 footer，位置固定 |
+| `/tps` | 循环切换 footer → right → status → widget → off |
+| `/tps footer` | footer 的目录那一行右端（默认），不额外占行 |
+| `/tps right` | 编辑器下方单独一行，右对齐，紧贴 footer |
 | `/tps status` | footer 的扩展状态行，和其他扩展共用一行，按扩展名排序 |
 | `/tps widget` | 编辑器上方的单行组件 |
 | `/tps off` | 完全隐藏。计量仍在后台进行，切回来立即显示当前读数 |
 
 模式写入配置文件，下次启动沿用。
 
-为什么右对齐是单独一行，而不是放进 footer 状态行的右端：pi 把所有扩展的状态按名字排序、左对齐拼成一行，扩展没法指定位置；要放到右端只能整个替换 pi 的 footer，不值得。编辑器下方的组件是自己渲染的，可以按终端宽度右对齐，窗口缩放时也贴着右边。
+`footer` 模式是怎么做的：pi 的 footer 没有给扩展留定位的口子（扩展状态只能左对齐拼在最后一行），所以这里用 `setFooter` 挂了一个包装层：里面跑的就是 pi 自己导出的 `FooterComponent`，统计行、状态行都由 pi 自己渲染，实测和原装 footer 逐字符、连颜色都一致；只是在目录那一行右端补上读数。终端变窄时先截短目录（和 pi 一样用 `...`），读数保持完整；中文目录名按双宽字符计算。如果将来某个 pi 版本改了 footer 内部导致包装失败，会自动恢复 pi 原装 footer、退回 `right` 模式并提示一次，不会把 footer 弄坏。
 
 如果也嫌 pi-lens 的 `LSP Inactive` 占地方，pi-lens 自己有开关：在 `~/.pi-lens/config.json` 里设 `ui.compactLspStatus: true`（压成一个图标）或 `ui.hideLspStatus: true`（不显示）。
 
@@ -80,7 +81,7 @@ pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写
 
 ```json
 {
-  "mode": "right",
+  "mode": "footer",
   "tiers": {
     "tps":  { "slow": 20, "normal": 50, "fast": 100 },
     "ttft": { "fast": 10000, "ok": 20000 }
@@ -91,7 +92,7 @@ pi -e npm:@jack-yang/pi-tps-meter          # 只在本次启动试用，不写
 
 | 键 | 默认值 | 说明 |
 |---|---|---|
-| `mode` | `"right"` | `right` / `status` / `widget` / `off`。`/tps` 只改写这个键，其他内容原样保留 |
+| `mode` | `"footer"` | `footer` / `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"` 关闭粒子流 |
@@ -153,7 +154,7 @@ TTFT 从 `turn_start` 开始计时（在 pi 里，一个 turn 就是一次模型
 
 - **不流式输出的推理**：有些模型按推理 token 计费，但不把推理内容流式发出来。这时校准比率会顶到 3.0 上限，AVG 也会偏高（原版同样如此）。
 - **一次性返回工具参数的 provider**（如 Gemini）：消息末尾会出现一个短暂的 TPS 尖峰，消息结束后立即清除。
-- **`status` 模式依赖 pi 的默认 footer**：如果另一个扩展换掉了 footer，并且不渲染扩展状态（比如 awesome-pi-themes 的 look-pack），用默认的 `right` 或 `widget`。
+- **`footer` 和其他替换 footer 的扩展互斥**：pi 同一时间只有一个 footer，后设置的生效。如果还开着 awesome-pi-themes 的 look-pack 这类扩展，改用 `/tps right`。`status` 模式也依赖 pi 的默认 footer（look-pack 不渲染扩展状态）。
 - **AVG 和校准只在当前会话内累计**：`/new`、`/resume`、`/fork`、`/reload` 会重新开始；不会从历史记录里重建。
 - **TTFT 包含客户端准备时间**：包括请求前的上下文处理（实测约 7ms）和 provider 层的自动重试等待，也就是用户实际等待的时间。
 - **时间戳取自 pi 把事件派发给扩展的时刻**：其他扩展的慢 handler 会推迟派发，从而影响读数。

package/extensions/index.ts

@@ -2,12 +2,13 @@
 //
 // 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.
+// host layer: pi events in; the meter out on pi's footer line (by wrapping pi's own footer), a
+// right-aligned line below the editor, a footer status, or a line above the editor.
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent"
+import type { ExtensionAPI, ExtensionContext, ReadonlyFooterDataProvider } 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 { mergeFooterLine } from "../src/footer.ts"
 import { alignRight, renderLine, withSpinner } from "../src/format.ts"
 import { advanceSpinner, createSpinner, spinnerCells, type Rgb, type SpinnerState } from "../src/spinner.ts"
 
@@ -21,12 +22,61 @@ const REFRESH_MS = 100
 const SPINNER_MUTED: Rgb = { r: 128, g: 132, b: 142 }
 
 type UI = ExtensionContext["ui"]
+type Model = NonNullable<ExtensionContext["model"]>
+
+// The part of pi's AgentSession that pi's FooterComponent reads, rebuilt from what an extension
+// can see. pi does not hand extensions its session, but its footer only needs these members.
+export type SessionView = {
+  readonly sessionManager: ExtensionContext["sessionManager"]
+  readonly model: ExtensionContext["model"]
+  readonly state: { model: ExtensionContext["model"]; thinkingLevel: string }
+  readonly routedModel: { model: Model; thinkingLevel?: string } | undefined
+  readonly modelRuntime: { isUsingSubscription(provider: string): boolean }
+  getContextUsage(): ReturnType<ExtensionContext["getContextUsage"]>
+}
+
+export type FooterLike = { render(width: number): string[]; invalidate(): void; dispose?(): void; setAutoCompactEnabled(enabled: boolean): void }
+
+// pi runtime pieces the footer mode needs; loaded on demand (and injected in tests, which run on
+// plain Node without pi).
+export type FooterKit = {
+  createFooter(session: SessionView, footerData: ReadonlyFooterDataProvider): FooterLike
+  visibleWidth(text: string): number
+  truncateToWidth(text: string, width: number, ellipsis?: string): string
+}
+
+export type Deps = { loadFooterKit?: () => Promise<FooterKit> }
+
+async function loadPiFooterKit(): Promise<FooterKit> {
+  const [core, tuiLib] = await Promise.all([import("@earendil-works/pi-coding-agent"), import("@earendil-works/pi-tui")])
+  type Session = ConstructorParameters<typeof core.FooterComponent>[0]
+  return {
+    createFooter: (session, footerData) => {
+      // SAFETY: FooterComponent is typed to take pi's whole AgentSession, which extensions never
+      // get. In pi 1.5.0 (dist/modes/interactive/components/footer.js) it reads exactly the members
+      // SessionView provides: sessionManager.{getCwd, getEntries, getEntryCount, getLeafId,
+      // getSessionId, getSessionName}, model, state.{model, thinkingLevel}, routedModel,
+      // modelRuntime.isUsingSubscription and getContextUsage(). If a later pi reads anything else,
+      // render() throws, the wrapper catches it, and fallBack() restores pi's own footer.
+      const agentSession = session as unknown as Session
+      return new core.FooterComponent(agentSession, footerData)
+    },
+    visibleWidth: tuiLib.visibleWidth,
+    truncateToWidth: tuiLib.truncateToWidth,
+  }
+}
 
 export default function tpsMeter(pi: ExtensionAPI): void {
+  createTpsMeter(pi)
+}
+
+export function createTpsMeter(pi: ExtensionAPI, deps: Deps = {}): void {
+  const loadFooterKit = deps.loadFooterKit ?? loadPiFooterKit
   let state: MeterState = createMeterState()
   // Defaults until session_start reads the file: the factory may run in invocations that never
   // start a session, so it does no IO and starts no timers.
   let config: MeterConfig = resolveConfig(undefined)
+  let ctxRef: ExtensionContext | undefined
   let ui: UI | undefined
   let tui = false
   let ticker: ReturnType<typeof setInterval> | undefined
@@ -34,18 +84,22 @@ export default function tpsMeter(pi: ExtensionAPI): void {
   // 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
+  // The mounted component's host (widget or footer), told to redraw when the line changes.
+  let host: { requestRender(): void } | undefined
+  // Bumped on every mode change, so a footer mount still loading for an older mode is dropped.
+  let mountEpoch = 0
 
   // Handlers re-bind from their own ctx; the ticker only ever uses the latest binding.
   const bind = (ctx: ExtensionContext): void => {
+    ctxRef = ctx
     ui = ctx.hasUI ? ctx.ui : undefined
     // 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.
+  // just be noise at 10Hz). A fresh stream starts each time thinking starts. Next to a
+  // right-aligned reading it goes on the left, so the reading itself never moves.
   const decorate = (target: UI, line: string, now: number): string => {
     if (!tui || !config.spinner.enabled || !state.thinking) {
       spinner = undefined
@@ -54,29 +108,120 @@ export default function tpsMeter(pi: ExtensionAPI): void {
     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")
+    const side = config.mode === "right" || config.mode === "footer" ? "before" : "after"
+    return withSpinner(line, spinnerCells(spinner, config.spinner, SPINNER_MUTED), paint, side)
   }
 
   // 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
+    target.setWidget(KEY, (h) => {
+      host = h
       return { render: (width: number) => [alignRight(shownLine ?? "", width)], invalidate() {} }
     }, { placement: "belowEditor" })
   }
 
+  // pi's own footer, fed a SessionView, with the meter merged into its first (directory) line.
+  // Everything else on the footer stays pi's rendering.
+  const sessionView: SessionView = {
+    // Only read inside a mounted footer, which exists only after bind(); a throw here is caught
+    // by the footer's render() and ends in fallBack().
+    get sessionManager() {
+      if (!ctxRef) throw new Error("no session bound")
+      return ctxRef.sessionManager
+    },
+    get model() { return ctxRef?.model },
+    get state() { return { model: ctxRef?.model, thinkingLevel: pi.getThinkingLevel() } },
+    // As pi's AgentSession.routedModel: under a virtual model, the physical model of the latest
+    // successful response.
+    get routedModel() {
+      const model = ctxRef?.model
+      if (!ctxRef || !model || model.api !== "pi-virtual") return undefined
+      const branch = ctxRef.sessionManager.getBranch()
+      for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i]
+        if (entry.type !== "message" || entry.message.role !== "assistant") continue
+        const m = entry.message
+        if (m.stopReason === "error" || m.stopReason === "aborted") continue
+        const physical = ctxRef.modelRegistry.find(m.provider, m.model)
+        return physical ? { model: physical, thinkingLevel: (m as { thinkingLevel?: string }).thinkingLevel } : undefined
+      }
+      return undefined
+    },
+    // As pi's ModelRuntime.isUsingSubscription: OAuth credentials for a subscription provider.
+    // The footer asks this about the current model's provider; ModelRegistry.isUsingOAuth takes
+    // the model and reads its provider.
+    modelRuntime: {
+      isUsingSubscription: (provider) => {
+        const registry = ctxRef?.modelRegistry
+        const model = ctxRef?.model
+        if (!registry || model?.provider !== provider || !registry.isUsingOAuth(model)) return false
+        const p = registry.getProvider(provider) as { auth?: { oauth?: { isSubscription?: boolean } } } | undefined
+        return p?.auth?.oauth?.isSubscription === true
+      },
+    },
+    getContextUsage: () => ctxRef?.getContextUsage(),
+  }
+
+  // If pi's footer cannot be wrapped (an older or newer pi changed it), never leave the user
+  // without a footer: restore pi's, fall back to the line below the editor, say so once.
+  // If pi's footer cannot be wrapped (an older or newer pi changed it), never leave the user
+  // without a footer: fall back to the line below the editor (leaving footer mode is what restores
+  // pi's own footer, in render()) and say so once. A mount that is no longer current (the mode
+  // changed, or the session was replaced, since it started) is ignored, so a stale UI is never used.
+  const fallBack = (target: UI, epoch: number, reason: unknown): void => {
+    if (epoch !== mountEpoch || ui !== target || config.mode !== "footer") return
+    config = { ...config, mode: "right" }
+    target.notify(`tps-meter: footer mode unavailable here (${reason instanceof Error ? reason.message : String(reason)}), using right`, "warning")
+    render()
+  }
+
+  const mountFooter = (target: UI, epoch: number): void => {
+    loadFooterKit().then((kit) => {
+      if (epoch !== mountEpoch || ui !== target) return
+      target.setFooter((h, theme, footerData) => {
+        host = h
+        const inner = kit.createFooter(sessionView, footerData)
+        const unsubscribe = footerData.onBranchChange(() => h.requestRender())
+        const fns = { visibleWidth: kit.visibleWidth, truncate: (text: string, width: number) => kit.truncateToWidth(text, width, theme.fg("dim", "...")) }
+        return {
+          render(width: number): string[] {
+            try {
+              // pi feeds this flag to its own footer instance; ours reads the same setting.
+              inner.setAutoCompactEnabled(pi.getSettings().compaction?.enabled ?? true)
+              const lines = inner.render(width)
+              if (lines.length > 0 && shownLine) lines[0] = mergeFooterLine(lines[0], shownLine, width, fns)
+              return lines
+            } catch (err) {
+              // Not from inside pi's render pass: swap the footer once this frame is done.
+              queueMicrotask(() => fallBack(target, epoch, err))
+              return []
+            }
+          },
+          invalidate() { inner.invalidate() },
+          dispose() {
+            unsubscribe()
+            inner.dispose?.()
+          },
+        }
+      })
+    }, (err: unknown) => fallBack(target, epoch, err))
+  }
+
   const render = (): void => {
     if (!ui) return
     const mode = config.mode
     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" || shownMode === "right") ui.setWidget(KEY, undefined)
-      rightHost = undefined
+      if (shownMode === "widget" || shownMode === "right" || (shownMode === "footer" && !tui)) ui.setWidget(KEY, undefined)
+      if (shownMode === "footer" && tui) ui.setFooter(undefined)
+      host = undefined
+      mountEpoch++
       shownMode = mode
       shownLine = undefined
       if (mode === "right" && tui) mountRight(ui)
+      if (mode === "footer" && tui) mountFooter(ui, mountEpoch)
     }
     if (mode === "off") return
     const now = Date.now()
@@ -85,8 +230,9 @@ export default function tpsMeter(pi: ExtensionAPI): void {
     shownLine = line
     if (mode === "status") ui.setStatus(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()
+    // RPC has no custom footers or component widgets; there the line goes out as plain text
+    // below the editor.
+    else if (tui) host?.requestRender()
     else ui.setWidget(KEY, [line], { placement: "belowEditor" })
   }
 
@@ -162,16 +308,18 @@ export default function tpsMeter(pi: ExtensionAPI): void {
   })
 
   pi.on("session_shutdown", () => {
-    // pi resets extension UI itself when it reloads or replaces the runtime; the timer and the
-    // reference to this session's UI are the only things left for us to drop.
+    // pi resets extension UI itself when it reloads or replaces the runtime (including a custom
+    // footer); the timer and the references to this session are the only things left to drop.
     stopTicker()
+    mountEpoch++
     ui = undefined
-    rightHost = undefined
+    ctxRef = undefined
+    host = undefined
     spinner = undefined
   })
 
   pi.registerCommand("tps", {
-    description: "TPS meter display: /tps cycles right → status → widget → off, /tps right|status|widget|off sets it",
+    description: "TPS meter display: /tps cycles footer → right → status → widget → off, /tps footer|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.
@@ -183,7 +331,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 right | status | widget | off)`, "error")
+        ctx.ui.notify(`tps-meter: unknown mode "${arg}" (use footer | 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.2.0",
+  "version": "0.3.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-right.png"
+    "image": "https://raw.githubusercontent.com/yangwudong/pi-tps-meter/main/docs/screenshot-footer.png"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/config.ts

@@ -13,12 +13,13 @@ import { dirname, join } from "node:path"
 import type { Tiers } from "./format.ts"
 import { parseHex, THEME_PRESETS, type Rgb, type SpinnerConfig } from "./spinner.ts"
 
-// 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"
+// footer: the right end of pi's own footer line with the working directory (pi's footer is wrapped,
+// not replaced); right: one line below the editor, right-aligned; status: pi's footer status line;
+// widget: a line above the editor.
+export type DisplayMode = "footer" | "right" | "status" | "widget" | "off"
 
 // Also the cycle order of a bare `/tps`.
-export const DISPLAY_MODES: readonly DisplayMode[] = ["right", "status", "widget", "off"]
+export const DISPLAY_MODES: readonly DisplayMode[] = ["footer", "right", "status", "widget", "off"]
 
 export type MeterConfig = { mode: DisplayMode; tiers: Tiers; spinner: SpinnerConfig }
 
@@ -49,7 +50,7 @@ export function resolveConfig(raw: unknown): MeterConfig {
   const custom = hexColors(sp.colors)
   const preset = hexColors(THEME_PRESETS[theme] ?? THEME_PRESETS.tech)
   return {
-    mode: isDisplayMode(o.mode) ? o.mode : "right",
+    mode: isDisplayMode(o.mode) ? o.mode : "footer",
     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) },

package/src/footer.ts

@@ -0,0 +1,27 @@
+// Puts the meter on the right end of the first line of pi's own footer (the working directory
+// line), the way pi itself right-aligns the model name on the line below. Pure: the terminal
+// width functions are injected (pi-tui's in pi, simple ones in tests), so this runs on plain Node.
+
+export type WidthFns = {
+  // Terminal columns of a string: ANSI codes take none, CJK characters take two.
+  visibleWidth(text: string): number
+  // Cut a string to at most `width` columns; the caller decides the ellipsis (pi uses a dim "...").
+  truncate(text: string, width: number): string
+}
+
+// Columns kept free between the directory and the meter.
+export const FOOTER_GAP = 2
+
+// The meter is the point of this line, so on a narrow terminal the directory gives way first
+// (truncated with an ellipsis, as pi itself does); the meter is only dropped when even it alone
+// would not fit. Returns exactly `width` columns, padded between the two parts.
+export function mergeFooterLine(left: string, meter: string, width: number, fns: WidthFns): string {
+  const meterWidth = fns.visibleWidth(meter)
+  if (meter === "" || meterWidth > width) return left
+  const room = width - meterWidth - FOOTER_GAP
+  let head = left
+  if (room <= 0) head = ""
+  else if (fns.visibleWidth(left) > room) head = fns.truncate(left, room)
+  const pad = width - fns.visibleWidth(head) - meterWidth
+  return head + " ".repeat(Math.max(0, pad)) + meter
+}