pi-minimal-footer 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-07
+
+### Fixed
+
+- Point pi.dev package preview metadata to a dedicated 16:9 PNG (1280×720), preserving the footer image without stretching or cropping
+
+## [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
@@ -167,7 +186,10 @@ First npm-ready release.
 
 - Project scaffold — `extensions/index.ts` with basic footer structure, `package.json` with pi extension manifest, `README.md`, `LICENSE` (MIT)
 
-[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.0...v0.3.1

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, with one space of padding at each edge. Interactive terminal UI only.
-
 ![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
@@ -53,20 +61,33 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
 - `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.
 - `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`.
-- Context `42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
 
-## Reading subscription usage
+## Reading the footer
+
+### Context
+
+`42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
+
+### Subscription usage
 
 `[⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h` shows **subscription allowance used**, not context usage.
 
-- Bar: shown as `[cells]` with 2–10 cells by default, expanding into spare space up to `maxUsageBarCells` (or fewer when the cap is below 2); 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.
+- **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".
@@ -141,6 +141,7 @@ 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;
 

package/extensions/lib/usage-limits.ts

@@ -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.4.0",
+  "version": "0.4.2",
   "description": "An opinionated minimal footer extension for Pi — clean status line with path, extension statuses, model, and context usage.",
   "keywords": [
     "pi-package",
@@ -49,6 +49,6 @@
     "extensions": [
       "./extensions"
     ],
-    "image": "https://raw.githubusercontent.com/Ryu-CZ/pi-minimal-footer/main/media/preview.png"
+    "image": "https://raw.githubusercontent.com/Ryu-CZ/pi-minimal-footer/main/media/pi-preview.png"
   }
 }