@pellux/goodvibes-tui 0.27.0 → 0.28.0

package/src/renderer/model-picker-overlay.ts

@@ -1,5 +1,6 @@
 import { type Line } from '../types/grid.ts';
 import { fitDisplay, getDisplayWidth, truncateDisplay } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 import type { ModelPickerModal } from '../input/model-picker.ts';
 import { EFFORT_DESCRIPTIONS } from '@pellux/goodvibes-sdk/platform/providers';
 import { getQualityTier, getQualityTierFromScore } from '@pellux/goodvibes-sdk/platform/providers';
@@ -15,9 +16,7 @@ import { getOverlaySurfaceMetrics } from './overlay-viewport.ts';
 
 /** Format a context window number into a short human-readable string. */
 function fmtContext(n: number): string {
-  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(0)}M`;
-  if (n >= 1000) return `${Math.round(n / 1000)}k`;
-  return String(n);
+  return abbreviateCount(n, { rounding: 'round', decimals: 0 });
 }
 
 /** Title text per picker mode. */
@@ -360,6 +359,12 @@ export function renderModelPickerOverlay(
     putRowText(promptRow, layout.margin + 2, contentW, fitDisplay(`${promptLabel} ${inputDisplay}`, contentW), '#ffffff');
     lines.push(promptRow);
 
+    if (picker.contextCapError) {
+      const errRow = createOverlayContentLine(width, layout, borderFg, DEFAULT_OVERLAY_PALETTE.bodyBg);
+      putRowText(errRow, layout.margin + 2, contentW, fitDisplay(picker.contextCapError, contentW), '#ff6666');
+      lines.push(errRow);
+    }
+
     lines.push(createOverlayContentLine(width, layout, borderFg, DEFAULT_OVERLAY_PALETTE.bodyBg));
 
     const hintText = `Leave blank to use default (current: ${currentCtx}, source: ${provenance})`;
@@ -458,7 +463,7 @@ function getRenderCacheKey(
   } else if (picker.mode === 'effort') {
     base.push(objectId(picker.effortLevels), picker.effortLevels.join('\u001f'), picker.pendingModel?.registryKey ?? picker.pendingModel?.id ?? '');
   } else if (picker.mode === 'contextCap') {
-    base.push(picker.contextCapQuery, picker.contextCapPendingModel?.registryKey ?? picker.contextCapPendingModel?.id ?? '');
+    base.push(picker.contextCapQuery, picker.contextCapPendingModel?.registryKey ?? picker.contextCapPendingModel?.id ?? '', picker.contextCapError ?? '');
   }
 
   return base.join('\u001e');

package/src/renderer/model-workspace.ts

@@ -11,6 +11,7 @@ import type { ModelPickerTargetInfo } from '../input/model-picker.ts';
 import type { Line } from '../types/grid.ts';
 import { createEmptyLine, createStyledCell } from '../types/grid.ts';
 import { getDisplayWidth, wrapText } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 import { GLYPHS, UI_TONES } from './ui-primitives.ts';
 
 const PALETTE = {
@@ -129,9 +130,7 @@ function stableWindow(total: number, selected: number, visible: number): { start
 
 function formatContext(value: number | undefined): string {
   if (!value) return '-';
-  if (value >= 1_000_000) return `${Math.round(value / 1_000_000)}M`;
-  if (value >= 1000) return `${Math.round(value / 1000)}k`;
-  return String(value);
+  return abbreviateCount(value, { rounding: 'round', decimals: 0 });
 }
 
 function modelKey(model: ModelDefinition): string {

package/src/renderer/panel-composite.ts

@@ -4,7 +4,6 @@ import type { InputHandler } from '../input/handler.ts';
 import type { PanelManager } from '../panels/panel-manager.ts';
 import type { PanelCompositeData } from './compositor.ts';
 import { createSplitPaneLayout } from './layout-engine.ts';
-import { renderPanelTabBar } from './panel-tab-bar.ts';
 import { renderPanelWorkspaceBar } from './panel-workspace-bar.ts';
 
 /**
@@ -108,33 +107,22 @@ export function buildPanelCompositeData(
   const workspaceBar = renderPanelWorkspaceBar(workspaceTabs, panelWidth, input.panelFocused);
 
   let topContent: Line[];
-  let topTabBar: Line | undefined;
-  let bottomTabBar: Line | undefined;
   let bottomContent: Line[] | undefined;
 
   const topActivePanel = topPane.panels[topPane.activeIndex] ?? null;
 
   if (hasBottom) {
-    topTabBar = renderPanelTabBar(
-      topPane.panels,
-      topPane.activeIndex,
-      panelWidth,
-      input.panelFocused && focusedPane === 'top',
-      'top',
-    );
-    const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio);
+    // Single consolidated workspace bar (1 row) + h-separator (1 row); the rest
+    // splits between the two panes' content.
+    const paneLayout = createSplitPaneLayout(Math.max(0, panelHeight - 1), verticalSplitRatio, {
+      topTabRows: 0,
+      bottomTabRows: 0,
+    });
     const topH = paneLayout.topContentRows;
     const bottomH = paneLayout.bottomContentRows;
     topContent = topActivePanel ? renderPanel(topActivePanel, panelWidth, topH) : [];
 
     const bottomActivePanel = bottomPane.panels[bottomPane.activeIndex] ?? null;
-    bottomTabBar = renderPanelTabBar(
-      bottomPane.panels,
-      bottomPane.activeIndex,
-      panelWidth,
-      input.panelFocused && focusedPane === 'bottom',
-      'bottom',
-    );
     bottomContent = bottomActivePanel ? renderPanel(bottomActivePanel, panelWidth, bottomH) : [];
   } else {
     const topH = Math.max(0, panelHeight - 1);
@@ -144,10 +132,9 @@ export function buildPanelCompositeData(
   return {
     panelData: {
       workspaceBar,
-      topTabBar,
       topContent,
       topFocused: input.panelFocused && focusedPane === 'top',
-      bottomTabBar,
+      hasBottomPane: hasBottom,
       bottomContent,
       bottomFocused: input.panelFocused && focusedPane === 'bottom',
       separator: true,

package/src/renderer/panel-workspace-bar.ts

@@ -1,21 +1,26 @@
 import type { Line } from '../types/grid.ts';
 import type { WorkspaceTab } from '../panels/panel-manager.ts';
-import { renderTabStrip } from './tab-strip.ts';
+import { renderTabStrip, type TabHitRegion } from './tab-strip.ts';
+import { UI_TONES } from './ui-primitives.ts';
 
-const ACTIVE_FG = '#e2e8f0';
-const ACTIVE_BG = '#0f172a';
-const INACTIVE_FG = '#94a3b8';
-const SEPARATOR_FG = '238';
-const LABEL_FG = '#cbd5e1';
-const LABEL_BG = '#1e293b';
+// Theme tokens (no raw hex) — keeps the bar in sync with the shared palette.
+const ACTIVE_FG = UI_TONES.fg.primary;       // selected tab text
+const ACTIVE_BG = UI_TONES.bg.selected;      // selected tab fill (stronger contrast)
+const INACTIVE_FG = UI_TONES.fg.muted;       // unselected tabs
+const SEPARATOR_FG = UI_TONES.fg.dim;        // │ separators
+const LABEL_FG = UI_TONES.fg.secondary;      // PANELS prefix label
+const LABEL_BG = UI_TONES.bg.title;          // prefix label background when focused
+const FOCUS_ACCENT_FG = UI_TONES.state.active; // the one focused tab
 
 export function renderPanelWorkspaceBar(
   tabs: readonly WorkspaceTab[],
   width: number,
   focused: boolean,
+  onLayout?: (regions: readonly TabHitRegion[]) => void,
 ): Line {
   return renderTabStrip({
     width,
+    onLayout,
     tabs: tabs.map((tab) => ({
       // tab.active = selected in its own pane (drives highlighted background).
       // tab.focused = has keyboard focus (drives brighter text / focus indicator).
@@ -32,7 +37,8 @@ export function renderPanelWorkspaceBar(
       activeBold: focused,
       inactiveFg: INACTIVE_FG,
       separatorFg: SEPARATOR_FG,
-      labelFg: LABEL_FG,
+      // Accent the PANELS chip when focused so it ties to the focus border.
+      labelFg: focused ? FOCUS_ACCENT_FG : LABEL_FG,
       labelBg: focused ? LABEL_BG : '',
       labelBold: focused,
       overflowFg: SEPARATOR_FG,

package/src/renderer/progress.ts

@@ -1,6 +1,7 @@
 import { type Line } from '../types/grid.ts';
 import { UIFactory } from './ui-factory.ts';
 import { getDisplayWidth, padDisplayEnd } from '../utils/terminal-width.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
 
 // Rich spinner frames (used by progress indicators)
 export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -51,8 +52,8 @@ export function renderTokenBar(
   const lines: Line[] = [];
 
   // Stats row
-  const usedK = used >= 1000 ? `${(used / 1000).toFixed(1)}k` : String(used);
-  const maxK = max >= 1000 ? `${(max / 1000).toFixed(1)}k` : String(max);
+  const usedK = abbreviateCount(used, { noM: true });
+  const maxK = abbreviateCount(max, { noM: true });
   const pct = max > 0 ? Math.min(100, Math.round((used / max) * 100)) : 0;
   const toolStr = toolCount > 0 ? `  tools:${toolCount}` : '';
   const statsText = ` ${model}  in:${usedK}/${maxK} (${pct}%)${toolStr}`;

package/src/renderer/tab-strip.ts

@@ -21,46 +21,148 @@ export interface TabStripStyle {
   readonly trailingFg?: string;
 }
 
+/** Absolute column range a rendered tab occupies, for click hit-testing. */
+export interface TabHitRegion {
+  /** Index into the original `tabs` array. */
+  readonly index: number;
+  /** First column (inclusive) the tab occupies on the line. */
+  readonly startCol: number;
+  /** Last column (exclusive) the tab occupies on the line. */
+  readonly endCol: number;
+}
+
 export interface TabStripConfig {
   readonly width: number;
   readonly tabs: readonly TabStripItem[];
   readonly style: TabStripStyle;
   readonly prefixLabel?: string;
   readonly suffixLabel?: string;
+  /** Right-side overflow glyph (more tabs after the window). Default '›'. */
   readonly overflowIndicator?: string;
+  /** Left-side overflow glyph (more tabs before the window). Default '‹'. */
+  readonly overflowIndicatorLeft?: string;
+  /**
+   * Optional callback invoked with the absolute column ranges of each rendered
+   * tab. Used by the compositor to hit-test mouse clicks onto tabs. Additive —
+   * the function still returns a `Line` so existing callers are unaffected.
+   */
+  readonly onLayout?: (regions: readonly TabHitRegion[]) => void;
+}
+
+const SEPARATOR = '│';
+
+interface WindowResult {
+  segments: StyledPanelSegment[];
+  /** Per-tab column ranges relative to the start of the tab block. */
+  regions: Array<{ index: number; startCol: number; endCol: number }>;
+  overflowLeft: boolean;
+  overflowRight: boolean;
 }
 
+/**
+ * Build the visible tab segments, windowed so the ACTIVE tab is always shown.
+ *
+ * Tabs are laid out left-to-right, but when they don't all fit we keep a
+ * contiguous window that contains the active tab and grow it outward (biased
+ * toward following tabs) until the budget is exhausted. Left/right overflow is
+ * reported so the caller can render `‹`/`›` indicators.
+ */
 function makeSegments(
   tabs: readonly TabStripItem[],
   style: TabStripStyle,
   maxWidth: number,
-): { segments: StyledPanelSegment[]; hasOverflow: boolean } {
-  const segments: StyledPanelSegment[] = [];
-  let used = 0;
-  let hasOverflow = false;
-  for (const tab of tabs) {
-    const separatorWidth = getDisplayWidth('│');
-    const labelText = tab.active ? `[${tab.label}]` : tab.label;
-    const labelWidth = getDisplayWidth(labelText);
-    const entryWidth = separatorWidth + labelWidth + 1;
-    if (used + entryWidth > maxWidth) {
-      hasOverflow = true;
-      break;
+  indicatorWidth: number,
+): WindowResult {
+  const empty: WindowResult = { segments: [], regions: [], overflowLeft: false, overflowRight: false };
+  if (tabs.length === 0 || maxWidth <= 0) return empty;
+
+  const sepWidth = getDisplayWidth(SEPARATOR);
+  // Per-tab entry width: leading separator + (bracketed if active) label + trailing space.
+  const labelText = (tab: TabStripItem) => (tab.active ? `[${tab.label}]` : tab.label);
+  const entryWidths = tabs.map((tab) => sepWidth + getDisplayWidth(labelText(tab)) + 1);
+
+  const activeIndex = Math.max(0, tabs.findIndex((t) => t.active));
+  const n = tabs.length;
+  const closing = sepWidth; // trailing │ after the last visible tab
+  const totalAll = entryWidths.reduce((a, b) => a + b, 0) + closing;
+
+  let start = activeIndex;
+  let end = activeIndex; // inclusive
+  let used = entryWidths[activeIndex] + closing;
+
+  if (totalAll <= maxWidth) {
+    // Everything fits — show all tabs, no windowing.
+    start = 0;
+    end = n - 1;
+  } else {
+    // Need windowing. Reserve room for indicators on whichever side still has
+    // hidden tabs; the reserve is recomputed each step so reaching an edge
+    // frees its indicator column.
+    const budget = maxWidth;
+    let leftDone = start === 0;
+    let rightDone = end === n - 1;
+    let preferRight = true;
+
+    const fits = (extra: number, nextStart: number, nextEnd: number) => {
+      const leftRes = nextStart > 0 ? indicatorWidth : 0;
+      const rightRes = nextEnd < n - 1 ? indicatorWidth : 0;
+      return used + extra + leftRes + rightRes <= budget;
+    };
+
+    while (!leftDone || !rightDone) {
+      const goRight = !rightDone && (preferRight || leftDone);
+      if (goRight) {
+        const ne = end + 1;
+        if (fits(entryWidths[ne], start, ne)) {
+          end = ne;
+          used += entryWidths[ne];
+          if (end === n - 1) rightDone = true;
+          preferRight = false;
+        } else {
+          rightDone = true;
+        }
+      } else if (!leftDone) {
+        const ns = start - 1;
+        if (fits(entryWidths[ns], ns, end)) {
+          start = ns;
+          used += entryWidths[ns];
+          if (start === 0) leftDone = true;
+          preferRight = true;
+        } else {
+          leftDone = true;
+        }
+      } else {
+        break;
+      }
     }
-    segments.push({ text: '│', fg: style.separatorFg });
+  }
+
+  const segments: StyledPanelSegment[] = [];
+  const regions: Array<{ index: number; startCol: number; endCol: number }> = [];
+  let col = 0;
+  for (let i = start; i <= end; i++) {
+    const tab = tabs[i];
+    const text = labelText(tab);
+    const entryStart = col;
+    segments.push({ text: SEPARATOR, fg: style.separatorFg });
     segments.push({
-      text: `${labelText} `,
+      text: `${text} `,
       fg: tab.active ? style.activeFg : style.inactiveFg,
       bg: tab.active ? style.activeBg : style.inactiveBg,
       bold: tab.active ? (style.activeBold ?? false) : false,
     });
-    used += entryWidth;
+    col += entryWidths[i];
+    regions.push({ index: i, startCol: entryStart, endCol: col });
   }
+  // Closing separator.
+  segments.push({ text: SEPARATOR, fg: style.separatorFg });
 
-  if (segments.length > 0 && used + getDisplayWidth('│') <= maxWidth) {
-    segments.push({ text: '│', fg: style.separatorFg });
-  }
-  return { segments, hasOverflow };
+  return {
+    segments,
+    regions,
+    overflowLeft: start > 0,
+    overflowRight: end < n - 1,
+  };
 }
 
 export function renderTabStrip(config: TabStripConfig): Line {
@@ -70,18 +172,18 @@ export function renderTabStrip(config: TabStripConfig): Line {
     style,
     prefixLabel,
     suffixLabel,
-  overflowIndicator = '›',
+    overflowIndicator = '›',
+    overflowIndicatorLeft = '‹',
+    onLayout,
   } = config;
 
+  const prefixWidth = prefixLabel ? getDisplayWidth(prefixLabel) + 1 : 0;
   const reservedSuffixWidth = suffixLabel ? getDisplayWidth(suffixLabel) : 0;
-  const reservedOverflowWidth = getDisplayWidth(overflowIndicator);
-  const maxTabWidth = Math.max(
-    0,
-    width
-      - (prefixLabel ? getDisplayWidth(prefixLabel) + 1 : 0)
-      - (suffixLabel ? reservedSuffixWidth : 0)
-      - reservedOverflowWidth,
+  const indicatorWidth = Math.max(
+    getDisplayWidth(overflowIndicator),
+    getDisplayWidth(overflowIndicatorLeft),
   );
+  const maxTabWidth = Math.max(0, width - prefixWidth - reservedSuffixWidth);
 
   const baseSegments: StyledPanelSegment[] = [];
   if (prefixLabel) {
@@ -94,15 +196,27 @@ export function renderTabStrip(config: TabStripConfig): Line {
     baseSegments.push({ text: ' ', fg: style.separatorFg });
   }
 
-  const { segments: tabSegments, hasOverflow } = makeSegments(tabs, style, maxTabWidth);
+  const { segments: tabSegments, regions, overflowLeft, overflowRight } =
+    makeSegments(tabs, style, maxTabWidth, indicatorWidth);
+
+  const leftSegments: StyledPanelSegment[] = [];
+  if (overflowLeft) {
+    leftSegments.push({ text: overflowIndicatorLeft, fg: style.overflowFg ?? style.separatorFg });
+  }
+
   const suffixSegments: StyledPanelSegment[] = [];
-  if (hasOverflow) suffixSegments.push({ text: overflowIndicator, fg: style.overflowFg ?? style.separatorFg });
+  if (overflowRight) {
+    suffixSegments.push({ text: overflowIndicator, fg: style.overflowFg ?? style.separatorFg });
+  }
   if (suffixLabel) {
-    suffixSegments.push({
-      text: suffixLabel,
-      fg: style.trailingFg ?? style.inactiveFg,
-    });
+    suffixSegments.push({ text: suffixLabel, fg: style.trailingFg ?? style.inactiveFg });
+  }
+
+  // Report absolute hit regions: prefix + optional left indicator, then tabs.
+  if (onLayout) {
+    const offset = prefixWidth + (overflowLeft ? getDisplayWidth(overflowIndicatorLeft) : 0);
+    onLayout(regions.map((r) => ({ index: r.index, startCol: offset + r.startCol, endCol: offset + r.endCol })));
   }
 
-  return buildStyledPanelLine(width, [...baseSegments, ...tabSegments, ...suffixSegments]);
+  return buildStyledPanelLine(width, [...baseSegments, ...leftSegments, ...tabSegments, ...suffixSegments]);
 }

package/src/renderer/ui-factory.ts

@@ -6,6 +6,8 @@ import type { GitHeaderInfo } from './git-status.ts';
 import { renderConversationFragment, renderConversationStatusLine, type ConversationStatusSegment } from './conversation-surface.ts';
 import { GLYPHS } from './ui-primitives.ts';
 import { formatElapsed } from '../utils/format-elapsed.ts';
+import { abbreviateCount } from '../utils/format-number.ts';
+import { computeContextUsage } from '../core/context-usage.ts';
 
 /** Number of frames before the animated gradient completes one full cycle. */
 const GRADIENT_CYCLE_FRAMES = 50;
@@ -30,11 +32,7 @@ function buildGitSegment(gitInfo: GitHeaderInfo): { text: string; width: number
 
 /** Format a number: up to 999, then 1.0k, 1.0M, 1.0B, 1.0T */
 function fmtNum(n: number): string {
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return (n / 1000).toFixed(1) + 'k';
-  if (n < 1_000_000_000) return (n / 1_000_000).toFixed(1) + 'M';
-  if (n < 1_000_000_000_000) return (n / 1_000_000_000).toFixed(1) + 'B';
-  return (n / 1_000_000_000_000).toFixed(1) + 'T';
+  return abbreviateCount(n, { bSuffix: true });
 }
 
 /**
@@ -312,7 +310,7 @@ export class UIFactory {
       const label = '   Context Usage: ';
       const suffix = ` [ ${fmtNum(ctxTokens)} / ${fmtNum(contextWindow)} ]`;
       const barWidth = Math.max(10, Math.min(30, width - getDisplayWidth(label) - getDisplayWidth(suffix) - 8));
-      const ctxPct = Math.min(1, ctxTokens / contextWindow);
+      const ctxPct = computeContextUsage(ctxTokens, contextWindow).clampedRatio;
       // Clamp threshold to [0..1]; undefined/0 means no threshold marker.
       const thresholdFraction = (compactThreshold !== undefined && compactThreshold > 0)
         ? Math.min(1, compactThreshold)

package/src/runtime/ui/model-picker/health-enrichment.ts

@@ -154,6 +154,9 @@ export function enrichModelEntries(
     // Determine source: custom/local providers carry provenance on ModelDefinition;
     // for catalog models, if getContextWindowForModel returned more than the
     // static contextWindow it came from OpenRouter, else it's the registry value.
+    // NOTE: This is a best-effort heuristic. When the OpenRouter live value equals
+    // the static registry value the badge shows 'registry' even though OpenRouter
+    // was consulted. The contextWindow value itself is always accurate.
     let contextWindowSource: ModelPickerEntry['contextWindowSource'];
     if (model.contextWindowProvenance) {
       contextWindowSource = model.contextWindowProvenance;

package/src/runtime/ui/model-picker/types.ts

@@ -97,6 +97,10 @@ export interface ModelPickerEntry {
    * - `fallback`       — default constant (no config or API source)
    * - `openrouter`     — sourced from OpenRouter model data (built-in catalog models)
    * - `registry`       — static value in the built-in model registry
+   *
+   * For built-in catalog models this badge is best-effort: when the OpenRouter
+   * resolved value equals the static registry value the source shows 'registry'
+   * even if OpenRouter was consulted at runtime.
    */
   readonly contextWindowSource:
     | 'provider_api'

package/src/utils/format-duration.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared ms-duration formatters for the panel layer.
+ *
+ * Three families are exported, each matching a distinct behavior cluster.
+ * DO NOT replace these with formatElapsed from utils/format-elapsed.ts —
+ * formatElapsed floors to integer seconds and lacks the null/'?ms' guards
+ * that the latency panels require.
+ */
+
+/**
+ * Format a latency value in milliseconds with sub-second precision.
+ *
+ * Used by: debug-panel, provider-health-panel, provider-stats-panel
+ *
+ *   ms <= 0     → 'n/a'
+ *   ms >= 10000 → '12.3s'    (one decimal)
+ *   ms >= 1000  → '1.23s'   (two decimals)
+ *   else        → '500ms'   (integer ms)
+ */
+export function formatLatencyMs(ms: number): string {
+  if (ms <= 0)      return 'n/a';
+  if (ms >= 10_000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms >= 1_000)  return `${(ms / 1000).toFixed(2)}s`;
+  return `${Math.round(ms)}ms`;
+}
+
+/**
+ * Format a task/agent duration with minute-rolling notation.
+ *
+ * Used by: tool-inspector-panel, agent-inspector-shared
+ *
+ *   ms < 1000   → '500ms'
+ *   ms < 60000  → '3.5s'
+ *   else        → '1m30s'
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000)  return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m${Math.floor((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Format a short eval/forensics duration; treats undefined as '?ms'.
+ *
+ * Used by: forensics-panel, eval-panel
+ *
+ *   undefined → '?ms'
+ *   ms < 1000 → '500ms'
+ *   else      → '1.5s'
+ */
+export function formatShortDuration(ms: number | undefined): string {
+  if (ms === undefined) return '?ms';
+  if (ms < 1000)        return `${ms}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}

package/src/utils/format-number.ts

@@ -0,0 +1,71 @@
+/**
+ * Parametrised number abbreviation helper.
+ *
+ * Each call site can reproduce its exact current output by passing the
+ * appropriate options rather than a single "agreed" format being imposed.
+ *
+ * Ranges (default opts: guard=1_000, decimals=1, rounding='fixed'):
+ *   n <  guard          → String(n)            e.g. 999  → '999'
+ *   n <  1_000_000      → X.Xk                 e.g. 1500 → '1.5k'
+ *   n <  1_000_000_000  → X.XM                 e.g. 1.5M → '1.5M'
+ *   (with bSuffix)      → X.XB / X.XT
+ *   (with noM)          → always k, never M
+ */
+
+export interface AbbreviateCountOpts {
+  /**
+   * Values strictly below this are returned as-is via String(n).
+   * Default: 1_000
+   */
+  guard?: number;
+  /**
+   * Decimal places used for the k suffix (and for M when mDecimals is not set).
+   * Default: 1
+   */
+  decimals?: number;
+  /**
+   * Override decimal places for the M suffix only.
+   * Default: same as decimals.
+   */
+  mDecimals?: number;
+  /**
+   * 'fixed'  → value.toFixed(decimals)  (default)
+   * 'round'  → String(Math.round(value)) — always integer, decimals ignored
+   */
+  rounding?: 'fixed' | 'round';
+  /**
+   * When true, extend formatting to B (billions) and T (trillions).
+   * Default: false
+   */
+  bSuffix?: boolean;
+  /**
+   * When true, never produce M/B/T — format as k even for millions.
+   * Default: false
+   */
+  noM?: boolean;
+}
+
+/**
+ * Format a non-negative integer with k/M/B/T magnitude suffix.
+ *
+ * Preserves each call site's exact current format by accepting
+ * per-site option overrides (guard, decimals, rounding, etc.).
+ */
+export function abbreviateCount(n: number, opts?: AbbreviateCountOpts): string {
+  const guard     = opts?.guard     ?? 1_000;
+  const decimals  = opts?.decimals  ?? 1;
+  const mDecimals = opts?.mDecimals ?? decimals;
+  const rounding  = opts?.rounding  ?? 'fixed';
+  const noM       = opts?.noM       ?? false;
+  const bSuffix   = opts?.bSuffix   ?? false;
+
+  /** Render a scaled value according to the configured rounding mode. */
+  const fmt = (val: number, d: number): string =>
+    rounding === 'round' ? String(Math.round(val)) : val.toFixed(d);
+
+  if (n < guard)                      return String(n);
+  if (noM || n < 1_000_000)           return fmt(n / 1_000, decimals)          + 'k';
+  if (!bSuffix || n < 1_000_000_000)  return fmt(n / 1_000_000, mDecimals)     + 'M';
+  if (n < 1_000_000_000_000)          return fmt(n / 1_000_000_000, decimals)  + 'B';
+  return                                     fmt(n / 1_000_000_000_000, decimals) + 'T';
+}

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.27.0';
+let _version = '0.28.0';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8'));
   _version = pkg.version ?? _version;