@pi-unipi/footer 0.1.3 → 2.0.0

package/src/help.ts

@@ -0,0 +1,160 @@
+/**
+ * @pi-unipi/footer — Footer help overlay
+ *
+ * Shows an overlay listing all enabled segments grouped by zone,
+ * with icons, short labels, and descriptions.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { FooterSegment, SegmentZone } from "./types.js";
+import { getIcon } from "./rendering/icons.js";
+import { loadFooterSettings, isSegmentEnabled } from "./config.js";
+import { getPreset } from "./presets.js";
+
+/** Zone display names and order */
+const ZONE_META: Record<SegmentZone, { title: string; order: number }> = {
+  left: { title: "LEFT ZONE (Identity)", order: 0 },
+  center: { title: "CENTER ZONE (Metrics)", order: 1 },
+  right: { title: "RIGHT ZONE (Time)", order: 2 },
+};
+
+/** Build the help content lines */
+function buildHelpLines(
+  segments: FooterSegment[],
+  presetName: string,
+): string[] {
+  const settings = loadFooterSettings();
+  const preset = getPreset(presetName);
+  const enabledIds = new Set([
+    ...preset.leftSegments,
+    ...preset.rightSegments,
+    ...preset.secondarySegments,
+  ]);
+
+  // Filter to enabled segments only
+  const enabled = segments.filter(seg => {
+    if (!enabledIds.has(seg.id)) return false;
+    return isSegmentEnabled(getGroupForSegment(seg.id), seg.id);
+  });
+
+  if (enabled.length === 0) {
+    return ["No segments enabled."];
+  }
+
+  // Group by zone
+  const zones: Record<SegmentZone, FooterSegment[]> = { left: [], center: [], right: [] };
+  for (const seg of enabled) {
+    zones[seg.zone].push(seg);
+  }
+
+  const lines: string[] = [];
+
+  for (const zoneKey of (["left", "center", "right"] as SegmentZone[])) {
+    const zoneSegs = zones[zoneKey];
+    if (zoneSegs.length === 0) continue;
+
+    const meta = ZONE_META[zoneKey];
+    lines.push(`  ${meta.title}`);
+    lines.push("");
+
+    for (const seg of zoneSegs) {
+      const icon = getIcon(seg.id);
+      const label = seg.shortLabel;
+      const desc = seg.description;
+      const iconStr = icon ? `${icon} ` : "  ";
+      lines.push(`    ${iconStr}${label.padEnd(6)} ${desc}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines;
+}
+
+/** Simple group lookup for help */
+function getGroupForSegment(segId: string): string {
+  const coreIds = ["model", "api_state", "tool_count", "git", "context_pct", "cost", "tokens_total", "tokens_in", "tokens_out", "session", "hostname", "time", "tps", "clock", "duration", "thinking_level"];
+  if (coreIds.includes(segId)) return "core";
+  const compactorIds = ["session_events", "compactions", "tokens_saved", "compression_ratio", "cocoindex_status", "sandbox_runs", "search_queries"];
+  if (compactorIds.includes(segId)) return "compactor";
+  if (["project_count", "total_count", "consolidations"].includes(segId)) return "memory";
+  if (["servers_total", "servers_active", "tools_total", "servers_failed"].includes(segId)) return "mcp";
+  if (["active_loops", "total_iterations", "loop_status"].includes(segId)) return "ralph";
+  if (["current_command", "sandbox_level", "command_duration"].includes(segId)) return "workflow";
+  if (["docs_count", "tasks_done", "tasks_total", "task_pct"].includes(segId)) return "kanboard";
+  if (["platforms_enabled", "last_sent"].includes(segId)) return "notify";
+  if (segId === "extension_statuses") return "status_ext";
+  return "core";
+}
+
+/**
+ * Show the footer help overlay.
+ * Lists all enabled segments grouped by zone with descriptions.
+ */
+export function showFooterHelp(
+  pi: ExtensionAPI,
+  segments: FooterSegment[],
+  presetName: string,
+): void {
+  const lines = buildHelpLines(segments, presetName);
+
+  // Use pi's custom UI overlay
+  const ctx = (pi as any)._ctx;
+  if (ctx?.ui?.custom) {
+    ctx.ui.custom((tui: import("@mariozechner/pi-tui").TUI) => {
+      let scrollOffset = 0;
+
+      return {
+        dispose() {},
+        render(width: number, height: number): string[] {
+          const maxVisible = height - 2; // border lines
+          const visibleLines = lines.slice(scrollOffset, scrollOffset + maxVisible);
+
+          const result: string[] = [];
+
+          // Top border
+          const title = " ? Footer Segment Guide ";
+          const borderLen = Math.max(width - 2, title.length + 4);
+          result.push(`\x1b[2m┌${"─".repeat(borderLen)}┐\x1b[0m`);
+
+          // Title
+          result.push(`\x1b[2m│\x1b[0m \x1b[1m${title}\x1b[0m${" ".repeat(Math.max(0, borderLen - title.length - 1))}\x1b[2m│\x1b[0m`);
+
+          // Content
+          for (const line of visibleLines) {
+            const padded = line.length > borderLen - 2
+              ? line.slice(0, borderLen - 2)
+              : line + " ".repeat(Math.max(0, borderLen - 2 - line.length));
+            result.push(`\x1b[2m│\x1b[0m ${padded} \x1b[2m│\x1b[0m`);
+          }
+
+          // Bottom border
+          result.push(`\x1b[2m├${"─".repeat(borderLen)}┤\x1b[0m`);
+          result.push(`\x1b[2m│\x1b[0m \x1b[2m↑↓ scroll · q close\x1b[0m${" ".repeat(Math.max(0, borderLen - 20))} \x1b[2m│\x1b[0m`);
+          result.push(`\x1b[2m└${"─".repeat(borderLen)}┘\x1b[0m`);
+
+          return result;
+        },
+        handleInput(key: string): boolean {
+          if (key === "q" || key === "Escape" || key === "Enter") {
+            return false; // Close overlay
+          }
+          if (key === "ArrowUp" || key === "k") {
+            scrollOffset = Math.max(0, scrollOffset - 1);
+            return true;
+          }
+          if (key === "ArrowDown" || key === "j") {
+            scrollOffset = Math.min(Math.max(0, lines.length - 5), scrollOffset + 1);
+            return true;
+          }
+          return true; // Consume all other keys
+        },
+      };
+    });
+  } else {
+    // Fallback: print to console
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
+}

package/src/index.ts

@@ -5,7 +5,8 @@
  * initializes renderer on session_start.
  */
 
-import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, Theme, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { UNIPI_EVENTS, emitEvent, UNIPI_PREFIX, FOOTER_COMMANDS } from "@pi-unipi/core";
 import { FooterRegistry, getFooterRegistry } from "./registry/index.js";
 import { FooterRenderer } from "./rendering/renderer.js";
@@ -27,6 +28,7 @@ import { STATUS_EXT_SEGMENTS } from "./segments/status-ext.js";
 
 import type { FooterGroup, FooterSegment } from "./types.js";
 import { rainbowBorder } from "./segments/core.js";
+import { tpsTracker } from "./tps-tracker.js";
 
 /** All segment groups */
 const ALL_GROUPS: FooterGroup[] = [
@@ -61,10 +63,10 @@ export interface FooterState {
   unsubscribeEvents: (() => void) | null;
   piContext: unknown;
   footerData: unknown;
-  tuiRef: any;
+  tuiRef: import("@mariozechner/pi-tui").TUI | null | undefined;
   refreshTimer: ReturnType<typeof setInterval> | null;
   /** Re-register footer + widgets with pi UI (for live enable) */
-  setupUI: ((pi: ExtensionAPI, ctx: any) => void) | null;
+  setupUI: ((pi: ExtensionAPI, ctx: ExtensionContext) => void) | null;
 }
 
 export default function footerExtension(pi: ExtensionAPI): void {
@@ -77,7 +79,7 @@ export default function footerExtension(pi: ExtensionAPI): void {
     registry: getFooterRegistry(),
     renderer: new FooterRenderer(
       getFooterRegistry(),
-      { get: (id: string) => segmentLookup.get(id) },
+      { get: (id: string) => segmentLookup.get(id), allIds: () => Array.from(segmentLookup.keys()) },
       loadFooterSettings().preset,
     ),
     segmentLookup,
@@ -110,7 +112,7 @@ export default function footerExtension(pi: ExtensionAPI): void {
 
     // Setup footer + widgets
     setupFooterUI(pi, ctx, state);
-    state.setupUI = (p: ExtensionAPI, c: any) => setupFooterUI(p, c, state);
+    state.setupUI = (p: ExtensionAPI, c: ExtensionContext) => setupFooterUI(p, c, state);
   });
 
   pi.on("session_shutdown", async () => {
@@ -124,6 +126,7 @@ export default function footerExtension(pi: ExtensionAPI): void {
       state.refreshTimer = null;
     }
     state.tuiRef = null;
+    tpsTracker.reset();
   });
 
   // ─── Register commands ──────────────────────────────────────────────────
@@ -133,10 +136,10 @@ export default function footerExtension(pi: ExtensionAPI): void {
   // ─── Emit MODULE_READY ──────────────────────────────────────────────────
 
   pi.on("session_start", async () => {
-    emitEvent(pi as any, UNIPI_EVENTS.MODULE_READY, {
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: "@pi-unipi/footer",
       version: "0.1.0",
-      commands: [`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER}`, `${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_SETTINGS}`],
+      commands: [`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER}`, `${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_SETTINGS}`, `${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_HELP}`],
       tools: [],
     });
   });
@@ -144,14 +147,36 @@ export default function footerExtension(pi: ExtensionAPI): void {
 
 // ─── Footer UI setup ────────────────────────────────────────────────────────
 
-function setupFooterUI(pi: ExtensionAPI, ctx: any, state: FooterState): void {
+function setupFooterUI(pi: ExtensionAPI, ctx: ExtensionContext, state: FooterState): void {
   // Register footer (minimal — handles branch changes)
-  ctx.ui.setFooter((tui: any, _theme: Theme, footerData: any) => {
+  ctx.ui.setFooter((tui, _theme, footerData) => {
     state.tuiRef = tui;
 
     // Start periodic refresh for time-sensitive segments (e.g. clock)
     if (!state.refreshTimer) {
       state.refreshTimer = setInterval(() => {
+        // Feed TPS tracker with per-message data
+        try {
+          const piCtx = state.piContext as Record<string, unknown> | undefined;
+          if (piCtx?.sessionManager) {
+            const sm = (piCtx as any).sessionManager;
+            const events = sm?.getBranch?.() ?? [];
+            let msgIndex = 0;
+            for (const e of events) {
+              if (!e || typeof e !== "object") continue;
+              if (e.type !== "message") continue;
+              const m = e.message;
+              if (!m || m.role !== "assistant") continue;
+              if (m.stopReason === "error" || m.stopReason === "aborted") continue;
+              const output = m.usage?.output ?? 0;
+              const hasStop = !!m.stopReason;
+              tpsTracker.onMessageUpdate(msgIndex, output, hasStop);
+              msgIndex++;
+            }
+          }
+        } catch {
+          // Silently ignore — TPS is best-effort
+        }
         state.renderer.resetLayoutCache();
         state.tuiRef?.requestRender();
       }, 1_000);
@@ -175,7 +200,7 @@ function setupFooterUI(pi: ExtensionAPI, ctx: any, state: FooterState): void {
   });
 
   // Top row widget
-  ctx.ui.setWidget("footer-top", (_tui: any, theme: Theme) => {
+  ctx.ui.setWidget("footer-top", (_tui, theme) => {
     // Update the renderer's theme-like
     const themeLike = { fg: (color: string, text: string) => theme.fg(color as any, text) };
     // We need to patch the context with proper theme
@@ -187,30 +212,38 @@ function setupFooterUI(pi: ExtensionAPI, ctx: any, state: FooterState): void {
         state.renderer.resetLayoutCache();
       },
       render(width: number): string[] {
-        if (!state.enabled || !state.piContext) return [];
+        if (!state.enabled || !state.piContext || width <= 0) return [];
 
         // Build layout with proper theme by creating segment contexts
         const layout = state.renderer.computeLayout(width);
-        return layout.topContent ? [layout.topContent] : [];
+        if (!layout.topContent) return [];
+
+        // Hard safety net: never return a line wider than the terminal.
+        // This catches any edge cases in layout math or visibleWidth()
+        // inconsistencies with PUA characters + ANSI codes.
+        const line = layout.topContent;
+        return [visibleWidth(line) > width ? truncateToWidth(line, width) : line];
       },
     };
   }, { placement: "aboveEditor" });
 
   // Secondary row widget
-  ctx.ui.setWidget("footer-secondary", (_tui: any, _theme: Theme) => {
+  ctx.ui.setWidget("footer-secondary", (_tui, _theme) => {
     return {
       dispose() {},
       invalidate() {
         state.renderer.resetLayoutCache();
       },
       render(width: number): string[] {
-        if (!state.enabled || !state.piContext) return [];
+        if (!state.enabled || !state.piContext || width <= 0) return [];
 
         const lines: string[] = [];
 
         const layout = state.renderer.computeLayout(width);
         if (layout.secondaryContent) {
-          lines.push(layout.secondaryContent);
+          // Hard safety net: never return a line wider than the terminal.
+          const line = layout.secondaryContent;
+          lines.push(visibleWidth(line) > width ? truncateToWidth(line, width) : line);
         }
 
         return lines;

package/src/presets.ts

@@ -2,8 +2,11 @@
  * @pi-unipi/footer — Presets system
  *
  * Preset definitions: default, minimal, compact, full, nerd, ascii.
- * Each preset defines which segments appear on left, right, and secondary rows,
+ * Each preset defines which segments appear (left/center/right/secondary),
  * plus separator style and color scheme.
+ *
+ * Segments are grouped by their zone field regardless of which array they're
+ * listed in. The arrays define ordering within the preset.
  */
 
 import type { PresetDef, SeparatorStyle, ColorScheme } from "./types.js";
@@ -12,100 +15,106 @@ import { getDefaultColors } from "./rendering/theme.js";
 /** Default preset — balanced view */
 const DEFAULT_PRESET: PresetDef = {
   leftSegments: [
-    "model", "api_state", "tool_count", "git", "context_pct", "cost",
+    "model", "api_state", "tool_count", "git",
   ],
   rightSegments: [
-    "compactions", "tokens_saved", "project_count", "loop_status",
+    "tps", "context_pct", "cost",
+    "compactions", "tokens_saved", "project_count",
+    "current_command", "loop_status", "extension_statuses",
+    "clock", "duration",
   ],
   secondarySegments: [
-    "current_command", "session_events",
+    "session",
   ],
-  separator: "powerline-thin",
   colors: getDefaultColors(),
 };
 
 /** Minimal preset — just the essentials */
 const MINIMAL_PRESET: PresetDef = {
   leftSegments: [
-    "git", "context_pct",
+    "model", "git",
+  ],
+  rightSegments: [
+    "context_pct",
+    "clock",
   ],
-  rightSegments: [],
   secondarySegments: [],
-  separator: "pipe",
   colors: getDefaultColors(),
 };
 
 /** Compact preset — core + key stats */
 const COMPACT_PRESET: PresetDef = {
   leftSegments: [
-    "model", "git", "cost", "context_pct",
+    "model", "git",
   ],
   rightSegments: [
-    "compactions", "total_count",
+    "tps", "context_pct", "cost",
+    "clock", "duration",
   ],
   secondarySegments: [],
-  separator: "dot",
   colors: getDefaultColors(),
 };
 
 /** Full preset — everything */
 const FULL_PRESET: PresetDef = {
   leftSegments: [
-    "model", "api_state", "tool_count", "git", "context_pct", "cost",
-    "tokens_total", "tokens_in", "tokens_out",
+    "model", "api_state", "tool_count", "git", "current_command", "session",
   ],
   rightSegments: [
-    "session_events", "compactions", "tokens_saved", "compression_ratio",
-    "indexed_docs", "sandbox_runs", "search_queries",
-    "project_count", "total_count", "consolidations",
-    "servers_total", "servers_active", "tools_total", "servers_failed",
-    "active_loops", "total_iterations", "loop_status",
-    "current_command", "command_duration",
-    "docs_count", "tasks_done", "tasks_total", "task_pct",
+    "tps", "context_pct", "cost", "tokens_total",
+    "session_events", "compactions", "tokens_saved",
+    "project_count", "total_count",
+    "servers_total", "servers_active", "tools_total",
+    "active_loops", "loop_status",
+    "docs_count", "tasks_done", "task_pct",
     "extension_statuses",
+    "clock", "duration",
   ],
   secondarySegments: [
-    "hostname", "time",
+    "hostname",
+    "tokens_in", "tokens_out",
+    "compression_ratio", "cocoindex_status",
     "platforms_enabled", "last_sent",
+    "thinking_level",
   ],
-  separator: "powerline-thin",
   colors: getDefaultColors(),
 };
 
 /** Nerd preset — maximum detail for Nerd Font users */
 const NERD_PRESET: PresetDef = {
   leftSegments: [
-    "model", "api_state", "tool_count", "git", "context_pct", "cost",
-    "tokens_total",
+    "model", "api_state", "tool_count", "git", "current_command", "session",
   ],
   rightSegments: [
+    "tps", "context_pct", "cost", "tokens_total",
     "session_events", "compactions", "tokens_saved",
     "project_count", "total_count",
     "servers_total", "servers_active", "tools_total",
     "active_loops", "loop_status",
-    "current_command",
-    "docs_count", "tasks_done", "tasks_total", "task_pct",
+    "docs_count", "tasks_done", "task_pct",
     "extension_statuses",
+    "clock", "duration",
   ],
   secondarySegments: [
-    "session", "hostname", "time",
-    "compression_ratio", "indexed_docs",
+    "hostname",
+    "tokens_in", "tokens_out",
+    "compression_ratio", "cocoindex_status",
     "platforms_enabled", "last_sent",
+    "thinking_level",
   ],
-  separator: "powerline",
   colors: getDefaultColors(),
 };
 
 /** ASCII preset — safe for any terminal */
 const ASCII_PRESET: PresetDef = {
   leftSegments: [
-    "model", "git", "context_pct", "cost",
+    "model", "git",
   ],
   rightSegments: [
-    "compactions", "tokens_saved", "project_count",
+    "tps", "context_pct", "cost",
+    "clock", "duration",
   ],
   secondarySegments: [],
-  separator: "ascii",
   colors: getDefaultColors(),
 };
 

package/src/registry/index.ts

@@ -156,5 +156,5 @@ export function resetFooterRegistry(): void {
 
 // Expose on globalThis for cross-package access
 if (typeof globalThis !== "undefined") {
-  (globalThis as Record<string, unknown>).__unipi_footer_registry = getFooterRegistry();
+  globalThis.__unipi_footer_registry = getFooterRegistry();
 }