@pi-unipi/footer 3.0.0-alpha.3 → 3.0.0-alpha.30

package/README.md

@@ -1,149 +1,90 @@
-# @pi-unipi/footer
+# Footer
 
-Persistent status bar at the bottom of the terminal. Shows live stats from all Unipi packages — compactor tokens saved, memory count, MCP status, Ralph loops, workflow state, kanboard tasks, notifications.
+Frames the input box and shows live session stats at the bottom of the terminal.
 
-Subscribes to events from every package and renders segments using Pi's `setFooter` + `setWidget` APIs. Responsive layout adjusts to terminal width, with a secondary row for narrow terminals.
+`@pi-unipi/footer` · part of [UniPi](../../README.md)
 
-## Glance Footer (new in 2.12)
+![Glance footer: a framed input box with the branch, model and a session stats line](../../docs/assets/screenshots/glance-footer.png)
 
-An experimental input surface, on by default and toggleable in `/unipi:settings` (Footer) → **Glance mode**:
+## What it does
 
+- Puts a frame around the input box (**the glance frame**, always on when the footer is enabled).
+- Shows a stats line below the input: input/output tokens, cost, average time to first token (TTFT), tokens per second, turns, steps, model and tool time, cache hit rate, and compactions.
+- Shows a line above the input with counts of background tasks: running, stopped, failed and done.
+- Adapts to the terminal: parts of the stats line drop by priority when the terminal is narrow, badges leave the frame titles before the branch or model truncate, and on very short terminals the stats and task lines hide.
+
+## Quick start
+
+UniPi installs this package:
+
+```bash
+pi install npm:@pi-unipi/unipi
 ```
-╭─ 󰚩 UNIPI │  feat/footer-default-v2 │ ───────────────────────────╮
-│ Type your prompt here...                                        │
-╰─ 󰉋 unipi ────────────────────── 42%/1.0M │ GLM-5.3 │ thinking:high ─╯
-              2 turn · 20 steps | 00:12:14 · tool 00:02 | 20ms avg ttft · 120 tok/s | 90% cache hit
+
+To install this package alone:
+
+```bash
+pi install npm:@pi-unipi/footer
 ```
 
-- **Top border:** animated lolcat-gradient UNIPI brand + git branch (turns rainbow-frame animated while thinking is max/xhigh)
-- **Bottom border:** workspace · context %/window · model · thinking level
-- **Session strip:** turns/steps, wall + tool wall time, average TTFT, tok/s, cache hit % — colored per stat, honest across restarts (derived from persisted session timestamps when live hooks are unavailable; provider-reported `usage.output` anchors token counts whenever present)
-- **Process line (new in 2.13):** centered one-liner directly above the frame while background work is in flight — `● 3 running  ● 1 stopped  ● 1 failed  ● 2 done` — green ● running, yellow ● stopped (killed), red ● failed, gray ● done. Covers every task type (shell jobs, delegates, fusion workflows) via direct registry reads; zero-count buckets are omitted and the line hides when idle. Counts reset per session.
-- The classic segment status line is suppressed while glance mode is on; toggle it back for the classic footer
+The footer starts with the session. Open `/unipi:settings` → **Footer** to change it.
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/unipi:footer` | Toggle footer on/off |
-| `/unipi:footer on` / `/unipi:footer off` | Enable/disable explicitly |
-| `/unipi:settings` | Hub — preset, separator, zone separator, icon style, glance mode, per-segment toggles (Footer group) |
-| `/unipi:footer-help` | Show footer segment guide |
-
-## Special Triggers
-
-Footer subscribes to events from every Unipi package:
-
-| Group | Events | Segments |
-|-------|--------|----------|
-| core | Pi SDK | model, thinking, path, git, context_pct, cost, tokens, session |
-| compactor | Pi session data + `COMPACTOR_COMPACTED` | session_events, compactions, tokens_saved, compression_ratio |
-| memory | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` | project_count, total_count, consolidations |
-| mcp | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` | servers_total, servers_active, tools_total |
-| ralph | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` | active_loops, total_iterations, loop_status |
-| workflow | `WORKFLOW_START`/`END` | current_command, sandbox_level, command_duration |
-| kanboard | Direct registry read | docs_count, tasks_done, tasks_total, task_pct |
-| notify | `NOTIFICATION_SENT` | platforms_enabled, last_sent |
-
-Footer works even if packages load after it — late-arriving events update the cache.
-
-## Presets
-
-| Preset | Description |
-|--------|-------------|
-| `default` | Glance-era: UNIPI brand, model, thinking, directory, git \| context/tokens, tps, cost, clock |
-| `classic` | The pre-2.12 balanced layout: model, api, tools, git \| tps, context, cost + compactor + memory + ralph |
-| `minimal` | Essentials only: path, git, context |
-| `compact` | Core + key stats: model, git, cost, context |
-| `full` | Everything from all groups |
-| `ascii` | Core segments with ASCII icons |
-
-## Segment Groups
-
-| Group | Default | Data Source |
-|-------|---------|-------------|
-| **core** | ON | Pi SDK (ctx.sessionManager, footerData) |
-| **compactor** | ON | Live Pi session data; last-compaction event |
-| **memory** | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
-| **mcp** | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
-| **ralph** | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
-| **workflow** | ON | `WORKFLOW_START`/`END` events |
-| **kanboard** | ON | Kanboard registry (direct read) |
-| **notify** | OFF | `NOTIFICATION_SENT` event |
-| **status_ext** | ON | `footerData.getExtensionStatuses()` |
-
-## Configurables
-
-Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
-
-```json
-{
-  "unipi": {
-    "footer": {
-      "enabled": true,
-      "preset": "default",
-      "glanceMode": true,
-      "separator": "powerline-thin",
-      "iconStyle": "nerd",
-      "colorMode": "auto",
-      "groups": {
-        "compactor": {
-          "show": true,
-          "segments": {
-            "session_events": true,
-            "compactions": true,
-            "tokens_saved": true
-          }
-        }
-      }
-    }
-  }
-}
-```
+| Command | What it does |
+|---|---|
+| `/unipi:footer` | Turns the footer on or off. |
+| `/unipi:footer on` | Turns the footer on. |
+| `/unipi:footer off` | Turns the footer off (plain pi editor). |
 
-### Separator Styles
+## The glance frame
 
-| Style | Look |
-|-------|------|
-| `powerline` | Thick powerline arrows |
-| `powerline-thin` | Thin powerline arrows (default) |
-| `slash` | / |
-| `pipe` | \| |
-| `dot` | Middle dot |
-| `ascii` | > < |
+The frame has three parts:
 
-### Icon Styles
+- **Top border.** The UNIPI brand, the long-horizon mode, the git branch, and the plan and permission mode. The brand shows a moving rainbow. The frame also shows the rainbow when the thinking level is `xhigh` or `max` (unless **Rainbow** is `brand-only`).
+- **Bottom border.** The workspace name, context use and window size, the model and the thinking level. With a [Fusion](../fusion/README.md) pair, it shows the lead and the sidekick. It also shows Kanboard claims.
+- **Stats line.** The line below the input. A part stays hidden until it has data. For example, compactions show only after the first compaction.
 
-| Style | Description |
-|-------|-------------|
-| `nerd` | Nerd Font glyphs (auto-detected) |
-| `emoji` | Unicode symbols (works on most terminals) |
-| `text` | Plain text labels (works everywhere). Glance frame drops the robot glyph: `UNIPI │ branch:main`, `workspace:unipi` |
+The background-task line reads the [Background Tasks](../background-tasks/README.md) registry. It shows nothing when no task exists.
 
-When `iconStyle` is not set, footer auto-detects Nerd Font support and defaults to `nerd` if available, `emoji` otherwise.
+## Responsive behavior
 
-### Color Mode
+- **Width.** Each stats-line part has a priority. When the line does not fit, the lowest-priority parts drop whole (never mid-part), in this order: compactions, cache, time, turns, speed, cost — tokens always survive. The frame titles degrade the same way: the Kanboard label, the Fusion pair, the plan/permission cluster and the mode label drop (lowest value first) before the branch or model ever truncate.
+- **Width safety.** Nothing ever writes the last terminal column (a full-width line desyncs wrapping terminals).
+- **Height.** Below 20 terminal rows the stats line and the background-task line hide; the frame stays.
 
-| Mode | Description |
-|------|-------------|
-| `auto` | Detect terminal support from environment (default) |
-| `truecolor` | Force 24-bit ANSI color |
-| `256` | Force xterm-256 color fallback |
-| `none` | Disable footer color escapes |
+## Settings
 
-`auto` uses truecolor where supported and downgrades to xterm-256 colors for terminals such as Apple Terminal that do not reliably render 24-bit color escapes.
+Open `/unipi:settings` → **Footer**. The file is `~/.unipi/config/footer/config.json`. A project file at `.unipi/config/footer/config.json` overrides it.
 
-### Responsive Layout
+| Key | Default | What it does |
+|---|---|---|
+| `enabled` | `true` | Turns the footer on or off. `false` leaves the plain pi editor. |
+| `iconStyle` | `nerd` | Icon set: `nerd` (needs a Nerd Font), `emoji` or `text`. |
+| `colorMode` | `auto` | `auto`, `truecolor`, `256` or `none`. The legacy value `mono` loads as `none`. |
+| `rainbow` | `always` | `always` animates the brand (and the whole frame at `xhigh`/`max` thinking); `brand-only` never animates the whole frame; `off` disables the animation. |
+| `processLine` | `true` | Shows the background-task line above the input. |
+| `strip.turns` | `true` | Turn and step counters. |
+| `strip.time` | `true` | Model time and tool time. |
+| `strip.speed` | `true` | Average TTFT and tokens per second. |
+| `strip.tokens` | `true` | Session input and output tokens. |
+| `strip.cost` | `true` | Session cost, or `sub` when the model runs on a subscription. |
+| `strip.compactions` | `true` | Compaction count, sizes and recency. |
+| `strip.cache` | `true` | Cache hit percentage. |
+| `badges.mode` | `true` | Long-horizon mode label beside the brand. |
+| `badges.planPermission` | `true` | PLAN badge and permission mode in the top border. |
+| `badges.fusion` | `true` | Fusion lead and sidekick in the bottom border. |
+| `badges.kanboard` | `true` | Kanboard claims label in the top border. |
 
-```
-Wide terminal (>120 cols):
-  model | thinking | path | git | context | cost | compactions | tokens_saved | project_count
+`colorMode: auto` uses 24-bit color where the terminal supports it, 256 colors in terminals such as Apple Terminal, and no color when the `NO_COLOR` environment variable exists.
 
-Narrow terminal (<120 cols):
-  Row 1: model | thinking | path | git | context | cost
-  Row 2: compactions | tokens_saved | project_count | ralph | workflow
-```
+Old v2 keys (`preset`, `separator`, `zoneSeparator`, `showFullLabels`, `groups`, `glanceMode`) in existing config files are ignored.
+
+## How it works
+
+The footer listens to UniPi events on the [event bus](../../docs/architecture/event-bus.md) for mode, plan and permission state. Usage data comes from an incremental scan of the session branch: each second only new entries are processed (a compaction or branch change triggers a full rescan), the same pass filling a cached snapshot for the stats line. The TPS tracker is fed live by pi's streaming events and reconciled by the same scan. The footer redraws when something it displays changed — plus once a second while the rainbow animates.
 
-## License
+## See also
 
-MIT
+- [Info Screen](../info-screen/README.md)
+- [Settings reference](../../docs/reference/settings.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/footer",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.30",
   "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
   "type": "module",
   "main": "index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.3",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.3"
+    "@pi-unipi/core": "3.0.0-alpha.30",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.30"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/src/commands.ts

@@ -1,15 +1,14 @@
 /**
  * @pi-unipi/footer — Commands
  *
- * Footer commands: /unipi:footer (toggle) and /unipi:footer <preset>.
+ * /unipi:footer — toggle the footer on/off.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { UNIPI_PREFIX, FOOTER_COMMANDS } from "@pi-unipi/core";
-import { loadFooterSettings, saveFooterSettings } from "./config.js";
-import { showFooterHelp } from "./help.js";
-import type { FooterSegment } from "./types.js";
-import { applyGlanceMode, type FooterState } from "./index.js";
+import { saveFooterSettings } from "./config.js";
+import type { FooterState } from "./index.js";
+import { fullRescan } from "./index.js";
 
 /**
  * Register footer commands.
@@ -21,34 +20,17 @@ export function registerCommands(pi: ExtensionAPI, state: FooterState): void {
     handler: async (args, ctx) => {
       const arg = args?.trim().toLowerCase();
 
-      // on
-      if (arg === "on") {
-        state.enabled = true;
-        state.renderer.setActive(true);
-        saveFooterSettings({ enabled: true });
-        state.setupUI?.(pi, ctx);
-        ctx.ui.notify("Footer enabled", "info");
-        return;
-      }
+      let enable: boolean;
+      if (arg === "on") enable = true;
+      else if (arg === "off") enable = false;
+      else enable = !state.enabled;
 
-      // off
-      if (arg === "off") {
-        state.enabled = false;
-        state.renderer.setActive(false);
-        ctx.ui.setFooter(undefined);
-        ctx.ui.setWidget("footer-top", undefined);
-        ctx.ui.setWidget("footer-secondary", undefined);
-        saveFooterSettings({ enabled: false });
-        ctx.ui.notify("Footer disabled", "info");
-        return;
-      }
-
-      // Toggle (no args or unknown args)
-      state.enabled = !state.enabled;
-      state.renderer.setActive(state.enabled);
+      state.enabled = enable;
+      saveFooterSettings({ enabled: enable });
 
-      if (state.enabled) {
+      if (enable) {
         state.setupUI?.(pi, ctx);
+        fullRescan(state);
         ctx.ui.notify("Footer enabled", "info");
       } else {
         ctx.ui.setFooter(undefined);
@@ -56,17 +38,6 @@ export function registerCommands(pi: ExtensionAPI, state: FooterState): void {
         ctx.ui.setWidget("footer-secondary", undefined);
         ctx.ui.notify("Footer disabled", "info");
       }
-
-      saveFooterSettings({ enabled: state.enabled });
-    },
-  });
-
-  // /unipi:footer-help — show help overlay
-  pi.registerCommand(`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_HELP}`, {
-    description: "Show footer segment guide (icons, labels, descriptions)",
-    handler: async (_args, _ctx) => {
-      const allSegments = Array.from(state.segmentLookup.values());
-      showFooterHelp(pi, allSegments, state.renderer.getPresetName());
     },
   });
 }