pi-minimal-footer 0.3.3 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-07
+
+### Changed
+
+- Restructure README with separate left/right feature lists, clearer context and subscription usage guidance, explicit adapter verification limits, and source installation under development
+- Refresh the vision contract for the two-cell baseline, bracketed bars, and nine-second timeout
+- Explain cache retention, refresh jitter, exact-model quota selection, and readability thresholds with rationale comments; update the source footer example to show brackets
+
+### Fixed
+
+- Restore reset-label-only usage on terminals too narrow for a bracketed cell, with regression coverage for reset-only, hidden-usage, and one-cell width boundaries
+- Align usage detection and regression expectations with bracketed bars, the two-cell baseline, bracket-aware width allocation, and ten-cell rounding for small percentages
+
+## [0.4.0] - 2026-10-07
+
+### Added
+
+- `minFooter.maxUsageBarCells` (default `10`) to cap the subscription usage bar length; use a positive integer such as `4` for a compact bar, excluding brackets and reset time
+
+### Changed
+
+- Reduce the compact subscription usage bar baseline from five to two cells before expanding into spare space up to the configured cap
+- Add one space at each footer edge, reserving those columns when fitting narrow terminals
+- Refresh README and package-gallery PNG previews with the current footer, edge padding, and live OpenAI Codex subscription usage
+
 ## [0.3.3] - 2026-10-07
 
 ### Changed

package/README.md

@@ -9,18 +9,26 @@
 
 An opinionated, compact one-line footer for [Pi](https://github.com/earendil-works/pi).
 
-Path and branch on the left; extension statuses, model, context, and subscription usage bar on the right. Shrinks to fit narrow terminals. Interactive terminal UI only.
+![Footer preview: ~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · [⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h](media/github-preview.png)
 
-![Footer preview: ~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · ⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h](media/github-preview.png)
+**Left**
+
+- Working directory: `~/git/project`
+- Git branch: ` main`
+
+**Right**
+
+- Extension statuses: ` 🧠 Karpathy  🪽 Icarus`
+- Model: `model`
+- Context usage: `42/200k`
+- Subscription usage bar with reset time: `[⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h`
 
 ## Install
 
-Requires Node.js >=22.19.0.
+Requires Node.js >=22.19.0. Interactive terminal UI only.
 
 ```bash
 pi install npm:pi-minimal-footer
-# Or install from source:
-pi install git:github.com/Ryu-CZ/pi-minimal-footer
 ```
 
 ## Commands
@@ -44,27 +52,42 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
     "showPath": true,
     "showModel": true,
     "showContext": true,
-    "powerlineSeparator": true
+    "powerlineSeparator": true,
+    "maxUsageBarCells": 10
   }
 }
 ```
 
 - `showSkills` shows **extension status text**, not installed skills. The footer does not add the example statuses itself.
 - Set `powerlineSeparator` to `false` for plain spaces instead of `` / `` if your font lacks those glyphs. The git icon `` also needs a compatible font; hide it with `showGitBranch: false` if needed.
-- Context `42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
+- `maxUsageBarCells` caps the Braille bar length (excluding brackets and reset time). Use a positive integer, e.g. `4` for a compact bar; invalid values fall back to `10`.
+
+## Reading the footer
+
+### Context
 
-## Reading subscription usage
+`42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
 
-`⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h` shows **subscription allowance used**, not context usage.
+### Subscription usage
 
-- Bar: shown as `[cells]` with 5–10 cells, expanding into spare space; green below 85%, amber from 85%, red from 92%. The brackets keep the bar’s beginning and end visible even when it is empty. Dim means cached after a refresh failure. Very narrow terminals may show fewer cells or only the reset label.
+`[⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h` shows **subscription allowance used**, not context usage.
+
+- **Bar:** expands into spare space, using 2–10 cells by default, capped by `maxUsageBarCells`. Smaller caps and very narrow terminals may show fewer cells or only the reset label.
+- **Colors:** green below 85%, amber from 85%, red from 92%.
+- **Cached data:** dim after a refresh failure.
 - Reset: local `↻HH:mm` through 24 hours; whole days/hours above 24 hours (`↻1d8h`); whole days above 10 days (`↻12d`). Remaining durations round down. No reset reported means bar only.
 - Shows the shortest available usage window for the selected provider. Missing credentials, unsupported/local models, or absent limits hide the usage bar. Custom proxy endpoints are not polled.
 
-Supported adapters: **OpenAI Codex, Claude OAuth, GitHub Copilot, Gemini CLI, MiniMax, Kimi Coding, and OpenCode Go**. Uses Pi's existing credentials; ordinary Claude API keys do not expose subscription usage. Provider availability varies; authenticated endpoints remain unverified live.
+Implemented adapters: **OpenAI Codex, Claude OAuth, GitHub Copilot, Gemini CLI, MiniMax, Kimi Coding, and OpenCode Go**. Uses Pi's existing credentials; ordinary Claude API keys do not expose subscription usage. Authenticated endpoints remain unverified live; see [verification limits](VISION.md).
 
 ## Development & design
 
+Install from source:
+
+```bash
+pi install git:github.com/Ryu-CZ/pi-minimal-footer
+```
+
 See [VISION.md](VISION.md) for design constraints, local development, provider details, and verification limits. Release history: [CHANGELOG.md](CHANGELOG.md).
 
 ## Credits

package/VISION.md

@@ -18,9 +18,9 @@ The [README](README.md) is the user manual. This document records current design
 
 Reserve the usage bar and model/context before allocating location and statuses. Statuses and location may shorten or disappear; on sufficiently narrow terminals, model/context can also shorten or disappear.
 
-Lay out other fields with a five-cell usage bar first. Grow the bar only into leftover columns, up to ten cells—never truncate another field solely to enlarge it. At extreme widths, shrink below five cells, show only the reset label, or hide the usage bar if the label cannot fit.
+Lay out other fields with a two-cell usage bar first. Grow the bar only into leftover columns, up to ten cells—never truncate another field solely to enlarge it. At extreme widths, shrink to one cell, show only the reset label, or hide usage if neither can fit. Brackets keep an empty bar's edges visible and count toward its width, but not its cell cap.
 
-Five cells give 2.5% steps; ten give 1.25%. Fill rounds to the nearest eighth-cell step. Only the final partially filled cell uses an intermediate shade:
+Two cells give 6.25% steps; ten give 1.25%. Fill rounds to the nearest eighth-cell step. Only the final partially filled cell uses an intermediate shade:
 
 | Cell | Fill |
 |---|---|
@@ -57,7 +57,7 @@ Reuse Pi's selected-provider credentials. Copilot uses the GitHub login token fr
 - Consume passive Codex response headers/stream events and Claude quota headers when available.
 - Otherwise fetch on startup/provider switch, then roughly every four minutes without a fresh response update. Sample independent uniform ±⅛ jitter (3.5–4.5 minutes) for each attempt or fresh displayed-window update to spread fallback requests across sessions. Keep that deadline across unrelated window updates; a reported reset time still triggers an earlier refresh.
 - Merge partial windows. A weekly-only signal must not replace a cached shorter window or postpone its refresh.
-- Bound authentication, fetch, and response-body parsing by a shared five-second timeout. Release stalled work so polling can recover.
+- Bound authentication, fetch, and response-body parsing by a shared nine-second timeout. Release stalled work so polling can recover.
 - Provider switches clear usage immediately, cancel pending work, and invalidate late results. Gemini model switches also refresh model-specific usage.
 - Missing credentials and explicit empty/unlimited responses clear usage. Temporary authentication, network, or parsing failures retain only the current provider's cached usage, dimmed; without cache, hide it.
 - Invalid optional reset metadata must not discard otherwise valid usage. Zero usage is an empty bar, not an absent usage bar.

package/extensions/index.ts

@@ -1,7 +1,7 @@
 /**
  * Minimal footer — replaces pi's default footer with a clean status line:
  *
- *   ~/path/to/dir   main        status1  status2  sonnet · 12/128k · ⣿⣶⠀⠀⠀↻16:40
+ *   ~/path/to/dir   main        status1  status2  sonnet · 12/128k · [⣿⣶⠀⠀⠀]↻16:40
  *
  * Settings are persisted in the agent directory (usually ~/.pi/agent)
  * settings.json under "minFooter".
@@ -30,6 +30,7 @@ interface Settings {
     showModel?: boolean;
     showContext?: boolean;
     powerlineSeparator?: boolean;
+    maxUsageBarCells?: number;
   };
 }
 
@@ -43,6 +44,7 @@ const DEFAULT_SETTINGS: FooterSettings = {
   showModel: true,
   showContext: true,
   powerlineSeparator: true,
+  maxUsageBarCells: MAX_BAR_CELLS,
 };
 
 function settingsPath(): string {
@@ -74,7 +76,11 @@ function writeSettings(patch: Partial<Settings>): void {
 
 function readConfig(): FooterSettings {
   const s = readSettings();
-  return { ...DEFAULT_SETTINGS, ...s.minFooter };
+  const config = { ...DEFAULT_SETTINGS, ...s.minFooter };
+  if (typeof config.maxUsageBarCells !== "number" || !Number.isSafeInteger(config.maxUsageBarCells) || config.maxUsageBarCells < 1) {
+    config.maxUsageBarCells = MAX_BAR_CELLS;
+  }
+  return config;
 }
 
 function writeEnabled(v: boolean): void {
@@ -135,18 +141,21 @@ function updateState(ctx: ExtensionContext, state: FooterState): void {
 const MODEL_GAP = " · ";
 const USAGE_GAP = " · ";
 const LOCATION_GAP_WIDTH = 3;
+// Below these budgets, ellipses dominate text and status tabs stop being useful at a glance.
 const MIN_TEXT_WIDTH = 4;
 const MIN_STATUS_WIDTH = 12;
 
 function buildLine(
   width: number, path: string, statuses: string, branch: string, model: string, context: string,
   usage: (available: number, maxCells?: number) => string | null,
-  statusSeparator: string, locationSeparator: string,
+  statusSeparator: string, locationSeparator: string, maxUsageBarCells: number,
 ): string {
   if (width <= 0) return "";
+  if (width <= 2) return " ".repeat(width);
+  width -= 2;
   let core = [model, context].filter(Boolean).join(MODEL_GAP);
   // Budget the compact bar first; its expanded size must not drive truncation decisions.
-  const usageBar = usage(width) ?? "";
+  const usageBar = usage(width, Math.min(BASE_BAR_CELLS, maxUsageBarCells)) ?? "";
   const usageGapWidth = usageBar && core ? USAGE_GAP.length : 0;
   const coreBudget = Math.max(0, width - visibleWidth(usageBar) - usageGapWidth);
   if (usageBar && coreBudget < MIN_TEXT_WIDTH) {
@@ -182,11 +191,11 @@ function buildLine(
     // A dropped left group needs no divider; those columns belong to the usage bar instead.
     const interGroupGapWidth = left && right ? LOCATION_GAP_WIDTH : 0;
     const spareWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - interGroupGapWidth);
-    const expandedUsageBar = usage(visibleWidth(usageBar) + spareWidth, MAX_BAR_CELLS) ?? usageBar;
+    const expandedUsageBar = usage(visibleWidth(usageBar) + spareWidth, maxUsageBarCells) ?? usageBar;
     const expandedCore = [core, expandedUsageBar].filter(Boolean).join(USAGE_GAP);
     right = [fittedStatuses, expandedCore].filter(Boolean).join(statusSeparator);
   }
-  return left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right;
+  return " " + left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right + " ";
 }
 
 // ── Extension ─────────────────────────────────────────────────────────
@@ -251,6 +260,7 @@ export default function (pi: ExtensionAPI) {
             (available, maxCells = BASE_BAR_CELLS) => usageLimits.line(available, theme, maxCells),
             statusSeparator,
             config.powerlineSeparator ? theme.fg("dim", "  ") : " ",
+            config.maxUsageBarCells ?? MAX_BAR_CELLS,
           );
           return [line];
         },

package/extensions/lib/usage-limits.ts

@@ -14,7 +14,7 @@ const CELL_STEPS = 8;
 const PARTIAL_CELL_FILLS = ["", "⡀", "⣀", "⣄", "⣤", "⣦", "⣶", "⣷"];
 
 // Start compact so extra precision never steals space from the other footer fields.
-export const BASE_BAR_CELLS = 5;
+export const BASE_BAR_CELLS = 2;
 export const MAX_BAR_CELLS = 10;
 
 function formatResetLabel(resetAt: number | null, now: number): string {
@@ -186,6 +186,7 @@ export class UsageLimits {
     this.render();
   }
 
+  // Independent deadlines spread fallback requests across sessions sharing a subscription.
   private randomizeRefresh(): void {
     this.refreshDelay = REFRESH_MS + (Math.random() * 2 - 1) * REFRESH_JITTER_MS;
   }
@@ -246,8 +247,11 @@ export class UsageLimits {
     if (!this.ctx || !window) return null;
     const now = Date.now();
     const resetLabel = formatResetLabel(window.resetAt, now);
-    // Reserve two columns for brackets so an empty bar still has clear edges.
-    if (width < (resetLabel.length || 1) + 3) return null;
+    // Keep the reset useful when the terminal cannot fit even one bracketed cell.
+    if (width < resetLabel.length + 3) {
+      return resetLabel && width >= resetLabel.length ? theme.fg("dim", resetLabel) : null;
+    }
+    // Brackets keep the edges of a zero-usage bar visible.
     const cells = Math.min(maxCells, Math.max(1, width - resetLabel.length - 2));
     const steps = Math.round(window.used / 100 * cells * CELL_STEPS);
     const filled = "⣿".repeat(Math.floor(steps / CELL_STEPS)) + PARTIAL_CELL_FILLS[steps % CELL_STEPS];

package/extensions/lib/usage-providers.ts

@@ -136,6 +136,8 @@ export function parseUsageWindows(provider: string, model: string, payload: unkn
     if (window) windows[key] = window;
     else malformed = true;
   };
+  // Valid siblings remain useful; explicit absence clears cache, while malformed
+  // snapshots throw so a temporary provider failure retains dimmed cached usage.
   const finish = () => {
     if (Object.keys(windows).length) return windows;
     if (recognized && !malformed) return null;
@@ -247,6 +249,7 @@ export function parseUsageWindows(provider: string, model: string, payload: unkn
     if (!ok) malformed = true;
     return ok;
   });
+  // A malformed exact match must not substitute another model family's quota.
   const hasExact = buckets.some((b) => b.modelId === model);
   const family = model.toLowerCase().includes("flash") ? "flash" : model.toLowerCase().includes("pro") ? "pro" : null;
   const selected = valid.filter((b) => hasExact ? b.modelId === model : family && String(b.modelId).toLowerCase().includes(family));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-minimal-footer",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "An opinionated minimal footer extension for Pi — clean status line with path, extension statuses, model, and context usage.",
   "keywords": [
     "pi-package",