@badliveware/pi-footer-framework 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # pi-footer-framework
 
-Configurable footer replacement for Pi. It gives you a stable two-line footer and lets you choose which status items appear where.
+Configurable footer replacement for Pi. It owns footer layout, formatting, color, truncation, and placement while other extensions publish structured status/data for it to render.
 
-Use it when the default footer is too cramped, when you want context/model/branch/PR state in predictable places, or when other extensions need a shared place to publish compact status items.
+Use it when you want to customize Pi's footer through a configurable framework that agents can inspect and reconfigure from natural-language prompts.
 
 ## Install
 
@@ -18,31 +18,228 @@ No external services or credentials are required.
 /footerfx on
 /footerfx item context line 1
 /footerfx item context after model
-/footerfx gap 1 10
+/footerfx item pr line 3
+/footerfx anchor all right
 /footerfx save user
 ```
 
-The extension replaces the default footer only while enabled. Disable it with:
+The default layout uses two footer lines. If you place an item on another positive line number, the footer grows to include that line. Disable the replacement footer with:
 
 ```text
 /footerfx off
 ```
 
-## What it shows
+## Showcase
 
-Built-in items include:
+This is a real Pi terminal using TS render closures, theme-aware styles, right-anchored layout, responsive column placement, PR state, and an adapted extension status item:
 
-- `cwd`
-- `model` with thinking level
-- `branch`
-- `stats`
-- `context` usage, such as `ctx 52.2% 142K/272K`
-- `pr` state from compatible PR extensions
-- `ext` status text from other extensions
+![Footer framework showcase with cwd, PR, model, token stats, context, and watchdog status](assets/footer-framework-showcase.png)
 
-Items can be shown/hidden and positioned by line, left/right zone, relative order, or fixed column.
+The screenshot demonstrates:
 
-## Configuration
+- combined render output: cwd plus branch/PR label in one item
+- token-level styling: labels, model id, thinking level, token stats, context, and cost use different Pi theme colors/attributes
+- built-in Pi data: `cwd`, `branch`, `model`, `stats`, `context`, and `pr`
+- extension status adaptation: `compaction-continue` status becomes `watchdog:on`
+- flexible placement: line 1 and line 2 are right-anchored, while line 3 uses responsive `column` placement for middle and center-right items
+
+<details>
+<summary>Config used for the screenshot</summary>
+
+Save this as `~/.pi/agent/footer-framework.config.ts`. The same file ships as `examples/footer-framework.config.ts` in the npm package.
+
+```ts
+import type { FooterFrameworkConfig } from "@badliveware/pi-footer-framework";
+
+function shortPath(value: string, maxWidth = 48, tailSegments = 2): string {
+  const normalized = value.replace(/^\/home\/[^/]+/, "~");
+  const prefix = normalized.startsWith("~/") ? "~/" : normalized.startsWith("/") ? "/" : "";
+  const parts = normalized.slice(prefix.length).split("/").filter(Boolean);
+  const compact = parts.length > tailSegments ? `${prefix}…/${parts.slice(-tailSegments).join("/")}` : normalized;
+  return compact.length > maxWidth ? `…${compact.slice(-(maxWidth - 1))}` : compact;
+}
+
+const config = {
+  enabled: true,
+  lineAnchors: { 1: "right", 2: "right", 3: "left" },
+  minGap: 2,
+  maxGap: 24,
+  items: {
+    branch: { visible: false },
+    ext: { visible: false },
+    cwd: {
+      visible: true,
+      line: 1,
+      zone: "left",
+      order: 10,
+      render: ({ pi, span, fn }) => [
+        span("cwd", "muted"),
+        " ",
+        span(shortPath(pi.cwd.trim(), 48, 2), "dim"),
+        span(" · ", "muted"),
+        span(fn.truncate(pi.branch?.label ?? "", 22), "accent"),
+      ],
+    },
+    model: {
+      visible: true,
+      line: 1,
+      zone: "right",
+      order: 10,
+      render: ({ pi, span }) => [
+        span("model:", "muted"),
+        span(pi.model.id ?? "no-model", "accent"),
+        span("/", "muted"),
+        span(pi.model.thinking ?? "", "thinkingXhigh,bold"),
+      ],
+    },
+    stats: {
+      visible: true,
+      line: 2,
+      zone: "left",
+      order: 10,
+      render: ({ pi, span }) => [
+        span("↑", "dim"), span(pi.stats.inputText ?? "0", "dim"), " ",
+        span("↓", "dim"), span(pi.stats.outputText ?? "0", "dim"), " ",
+        span("$", "accent"), span(pi.stats.costText ?? "0.000", "success"),
+      ],
+    },
+    context: {
+      visible: true,
+      line: 3,
+      zone: "left",
+      order: 10,
+      column: "50%",
+      render: ({ pi, span }) => {
+        if (!pi.context) return undefined;
+        const tone = pi.context.tone ?? "muted";
+        return [span("ctx", tone), " ", span(pi.context.percentText ?? "?%", tone), " ", span(pi.context.tokenText ?? "?/?", tone)];
+      },
+    },
+    pr: {
+      visible: true,
+      line: 3,
+      zone: "left",
+      order: 20,
+      column: "66%",
+      render: ({ pi, span }) => {
+        if (!pi.pr) return undefined;
+        return [span("PR ", "muted"), span(pi.pr.checkGlyph ?? "•", pi.pr.checkTone ?? "muted"), span(pi.pr.commentsText ?? "", "muted")];
+      },
+    },
+  },
+  adapters: {
+    watchdog: {
+      source: "extensionStatus",
+      key: "compaction-continue",
+      itemId: "watchdog",
+      match: "(on|off)",
+      group: 1,
+      urlPath: "url",
+      placement: { visible: true, line: 2, zone: "right", order: 20 },
+      render: ({ value, span }) => [span("watchdog:", "muted"), span(value ?? "", "accent,bold")],
+    },
+  },
+} satisfies FooterFrameworkConfig;
+
+export default config;
+```
+
+String `column` positions such as `"50%"`, `"66%"`, and `"center"` are resolved from the current terminal width, so they keep their relative position after resize. Numeric columns remain fixed absolute terminal columns.
+
+</details>
+
+## How it works
+
+Footer-framework renders normalized footer items from adapter mappings, direct TS/JS item renderers, and extension-published items. Adapter mappings can read three source types:
+
+| Source | Use it for |
+| --- | --- |
+| `pi` | Built-in Pi/session/footer data such as `cwd`, `model`, `stats`, `context`, `branch`, `pr`, and `extensionStatuses`. |
+| `extensionStatus` | Existing `ctx.ui.setStatus()` footer/status entries from other extensions. |
+| `sessionEntry` | The latest custom session entry written by an extension with `pi.appendEntry()`. |
+
+The built-in footer items (`cwd`, `model`, `branch`, `stats`, `context`, `pr`) are regular default adapters unless you replace them with `items.<id>.render` in TS/JS config. User/project config overrides built-in defaults and producer hints.
+
+Agents can inspect concise footer-relevant data with `footer_framework_sources`, then add adapter rules with `footer_framework_adapter_config` or adjust layout with `footer_framework_config`. Runtime metadata such as tools, commands, skills, descriptions, and `sourceInfo` is opt-in via `includeTools`, `includeCommands`, `includeSkills`, and `includeDetails`.
+
+## Templates and styles
+
+Adapters can render with a restricted Liquid-style interpolation subset:
+
+```liquid
+{{ pi.stats.costText }}
+{{ "EUR" }}
+{{ "EUR" | style: "accent" }}{{ pi.stats.costText | style: "success,bold" }}
+```
+
+Quoted strings are literals. Unquoted terms are variables, so missing variables are reported as template diagnostics instead of being guessed as text. Diagnostics appear in `/footerfx-debug`, `footer_framework_state`, and `footer_framework_sources`.
+
+Useful template context:
+
+| Path | Meaning |
+| --- | --- |
+| `value`, `label`, `status`, `data`, `url` | The current adapter source. |
+| `pi.cwd` | Current working directory. |
+| `pi.model.id`, `pi.model.provider`, `pi.model.thinking` | Current model information. |
+| `pi.stats.inputText`, `pi.stats.outputText`, `pi.stats.costText` | Formatted session token/cost stats. Raw numbers are `input`, `output`, and `cost`. |
+| `pi.context.percentText`, `pi.context.tokenText`, `pi.context.tone` | Context usage and recommended tone. |
+| `pi.branch.name`, `pi.branch.label` | Git branch values. Use `truncate` in templates when you want a shorter display. |
+| `pi.pr.number`, `pi.pr.url`, `pi.pr.checkGlyph`, `pi.pr.checkTone`, `pi.pr.commentsText` | Pull request state when available. |
+
+Supported filters:
+
+| Filter | Example |
+| --- | --- |
+| `style` / `color` | `{{ value | style: "accent,bold" }}` |
+| `bg` / `background` | `{{ value | bg: "toolSuccessBg" }}` |
+| `bold`, `italic`, `underline`, `inverse`, `strikethrough` | `{{ value | underline }}` |
+| `link` | `{{ pi.pr.number | link: pi.pr.url }}` |
+| `truncate` | `{{ pi.branch.label | truncate: 22 }}` limits any value to 22 cells with an ellipsis. |
+| `compactPath` | `{{ pi.cwd | compactPath: 48, 2 }}` keeps the last 2 path segments when the path is wider than 48 cells. |
+| `default` | `{{ data.state | default: "unknown" }}` |
+
+Style strings use Pi theme tokens and text attributes. Foreground examples: `accent`, `muted`, `dim`, `success`, `warning`, `error`, `text`, `mdLink`, `toolDiffAdded`, and the other Pi theme foreground tokens. Backgrounds use `bg:<token>`, such as `bg:toolSuccessBg`. Attributes are `bold`, `italic`, `underline`, `inverse`, and `strikethrough`.
+
+## TypeScript render config
+
+For personal formatting logic, use a normal TS/JS config file with render closures. Footer-framework still owns data collection, layout, clipping, diagnostics, and final rendering; the closure only returns text/spans for one item.
+
+```ts
+import type { FooterFrameworkConfig } from "@badliveware/pi-footer-framework";
+
+function shortPath(value: string, maxWidth = 48, tailSegments = 2) {
+  const normalized = value.replace(/^\/home\/[^/]+/, "~");
+  const prefix = normalized.startsWith("~/") ? "~/" : normalized.startsWith("/") ? "/" : "";
+  const parts = normalized.slice(prefix.length).split("/").filter(Boolean);
+  const compact = parts.length > tailSegments ? `${prefix}…/${parts.slice(-tailSegments).join("/")}` : normalized;
+  return compact.length > maxWidth ? `…${compact.slice(-(maxWidth - 1))}` : compact;
+}
+
+export default {
+  items: {
+    branch: { visible: false },
+    ext: { visible: false },
+    cwd: {
+      line: 1,
+      zone: "left",
+      order: 10,
+      render: ({ pi, span, fn }) => [
+        span("cwd", "muted"),
+        " ",
+        span(shortPath(pi.cwd.trim(), 48, 2), "dim"),
+        span(" · ", "muted"),
+        span(fn.truncate(pi.branch?.label ?? "", 22), "accent"),
+      ],
+    },
+  },
+} satisfies FooterFrameworkConfig;
+```
+
+Render functions are synchronous and may return strings, spans, arrays, `null`, or `undefined`. Use `span(text, style, { url })` for token-level style/link metadata and `fn.text`, `fn.width`, `fn.truncate`, or `fn.compactPath` for footer-safe helpers. Adapter render functions also receive `value`, `label`, `status`, `data`, `url`, and `source`.
+
+`/footerfx-debug`, `footer_framework_state`, and `footer_framework_sources` show which TS/JS renderers loaded plus each rendered item's final tokens, width, placement, and diagnostics. If a render closure throws or returns a promise, the footer item is skipped and a diagnostic is recorded.
+
+## Configuration files
 
 User settings persist to:
 
@@ -50,13 +247,21 @@ User settings persist to:
 ~/.pi/agent/footer-framework.json
 ```
 
+Optional user TS/JS config files live next to it:
+
+```text
+~/.pi/agent/footer-framework.config.ts
+~/.pi/agent/footer-framework.config.js
+```
+
 Project settings can override them:
 
 ```text
 <project>/.pi/footer-framework.json
+<project>/.pi/footer-framework.config.ts
 ```
 
-Use `/footerfx save project` only when you intentionally want a project-specific footer layout.
+Load order is defaults, user TS/JS, user JSON, project TS/JS, then project JSON. `/footerfx` commands write JSON overrides; they do not rewrite TS/JS source. Use `/footerfx save project` only when you intentionally want a project-specific footer layout.
 
 ## Commands
 
@@ -64,42 +269,71 @@ Use `/footerfx save project` only when you intentionally want a project-specific
 | --- | --- |
 | `/footerfx` | Show current config and source. |
 | `/footerfx on` / `/footerfx off` | Enable or disable the replacement footer. |
+| `/footerfx config` | Show loaded config source and config paths. |
 | `/footerfx load` | Reload user/project config files. |
 | `/footerfx save user` | Save current settings as the user default. |
 | `/footerfx save project` | Save current settings for the current project. |
 | `/footerfx reset` | Restore defaults and persist them to user config. |
+| `/footerfx section <cwd|stats|context|model|branch|pr|ext> <on|off>` | Convenience alias for item visibility. |
 | `/footerfx item <id> <show|hide|reset>` | Control item visibility. |
-| `/footerfx item <id> line <1|2>` | Move an item to a footer line. |
+| `/footerfx item <id> line <n>` / `row <n>` | Move an item to any positive footer line. |
 | `/footerfx item <id> zone <left|right>` | Move an item between left/right zones. |
-| `/footerfx item <id> before <other-id>` | Place an item before another item. |
-| `/footerfx item <id> after <other-id>` | Place an item after another item. |
-| `/footerfx item <id> column <n|off>` | Pin or unpin an item column. |
-| `/footerfx anchor <line1|line2|all> <gap|left|center|right|spread>` | Control line alignment. |
+| `/footerfx item <id> before <other-id>` / `after <other-id>` | Place an item relative to another item. |
+| `/footerfx item <id> column <n|center|middle|percent|off>` | Pin, center, percentage-place, or unpin an item. Percent examples: `50%`, `66%`. |
+| `/footerfx anchor <line|all> <gap|left|center|right|spread>` | Control line alignment. `line3` and `3` both work. |
+| `/footerfx adapter` | List configured adapters. |
+| `/footerfx adapter <id> pi <source-key> [label]` | Adapt a built-in Pi source. |
+| `/footerfx adapter <id> status <status-key> [label]` | Adapt an existing extension status key. |
+| `/footerfx adapter <id> custom <custom-type> <path> [label]` | Adapt the latest matching custom session entry. |
+| `/footerfx adapter <id> template <template>` | Set the adapter's render template. |
+| `/footerfx adapter <id> empty-template <template>` | Set the template used for an empty adapter value. |
+| `/footerfx adapter <id> style <style>` | Apply a default style to the rendered adapter text. |
+| `/footerfx adapter <id> remove` | Remove an adapter. For built-ins, hide the item with `/footerfx item <id> hide`. |
 | `/footerfx gap <min> <max>` | Set spacing bounds. |
-| `/footerfx branch-width <n>` | Set max branch label width. |
-| `/footerfx-debug` | Show render snapshot, settings, and layout telemetry. |
+| `/footerfx-debug` | Show render snapshot, settings, template/render diagnostics, loaded TS/JS renderers, and layout telemetry. |
 
 ## Agent tools
 
-The extension exposes two tools so agents can inspect and adjust the footer without asking you to run commands:
+The extension exposes tools so agents can inspect and adjust the footer without asking you to run commands:
 
 - `footer_framework_state`
+- `footer_framework_sources`
 - `footer_framework_config`
+- `footer_framework_adapter_config`
 
-## Extension item API
+`footer_framework_sources` is concise by default. Pass `includeTools`, `includeCommands`, `includeSkills`, and `includeDetails` only when runtime metadata is directly useful.
 
-Other extensions can publish footer items through Pi's event bus:
+## Extension data API
+
+Compatible extensions should publish data, not pre-rendered layout. The framework decides final text, color, position, and truncation. Producers may include hints, but user config wins.
 
 ```ts
 pi.events.emit("footer-framework:item", {
-  id: "my-extension:status",
-  text: "cache warm",
-  placement: { line: 2, zone: "right", order: 50 }
+  id: "cache:status",
+  label: "cache",
+  value: "warm",
+  tone: "success",
+  data: { entries: 42 },
+  hint: {
+    icon: "◇",
+    format: "label-value",
+    placement: { line: 2, zone: "right", order: 50 }
+  }
 });
 ```
 
+Legacy `text` and top-level `placement` fields still work for existing extensions, but new integrations should prefer `label`, `value`, `status`, `data`, and `hint`.
+
 Remove an item with:
 
 ```ts
-pi.events.emit("footer-framework:item", { id: "my-extension:status", remove: true });
+pi.events.emit("footer-framework:item", { id: "cache:status", remove: true });
 ```
+
+## Troubleshooting
+
+### Blank space below the footer
+
+If blank rows sometimes appear below the footer and disappear after you send a prompt, check `/footerfx-debug` or `footer_framework_state`. When `lastFooterSnapshot.lines` contains only the expected footer lines, the framework is not rendering extra rows. This is usually Pi's TUI viewport/differential rendering leaving unused terminal space below the last rendered component.
+
+A Pi-side workaround is `terminal.clearOnShrink: true` in `~/.pi/agent/settings.json`, but that can add redraw flicker. Footer-framework does not change this setting.

package/examples/footer-framework.config.ts

@@ -0,0 +1,115 @@
+import type { FooterFrameworkConfig } from "@badliveware/pi-footer-framework";
+
+function shortPath(value: string, maxWidth = 48, tailSegments = 2): string {
+  const normalized = value.replace(/^\/home\/[^/]+/, "~");
+  const prefix = normalized.startsWith("~/") ? "~/" : normalized.startsWith("/") ? "/" : "";
+  const parts = normalized.slice(prefix.length).split("/").filter(Boolean);
+  const compact = parts.length > tailSegments ? `${prefix}…/${parts.slice(-tailSegments).join("/")}` : normalized;
+  return compact.length > maxWidth ? `…${compact.slice(-(maxWidth - 1))}` : compact;
+}
+
+const config = {
+  enabled: true,
+  lineAnchors: {
+    1: "right",
+    2: "right",
+    3: "left",
+  },
+  minGap: 2,
+  maxGap: 24,
+  items: {
+    branch: { visible: false },
+    ext: { visible: false },
+    cwd: {
+      visible: true,
+      line: 1,
+      zone: "left",
+      order: 10,
+      render: ({ pi, span, fn }) => [
+        span("cwd", "muted"),
+        " ",
+        span(shortPath(pi.cwd.trim(), 48, 2), "dim"),
+        span(" · ", "muted"),
+        span(fn.truncate(pi.branch?.label ?? "", 22), "accent"),
+      ],
+    },
+    model: {
+      visible: true,
+      line: 1,
+      zone: "right",
+      order: 10,
+      render: ({ pi, span }) => [
+        span("model:", "muted"),
+        span(pi.model.id ?? "no-model", "accent"),
+        span("/", "muted"),
+        span(pi.model.thinking ?? "", "thinkingXhigh,bold"),
+      ],
+    },
+    stats: {
+      visible: true,
+      line: 2,
+      zone: "left",
+      order: 10,
+      render: ({ pi, span }) => [
+        span("↑", "dim"),
+        span(pi.stats.inputText ?? "0", "dim"),
+        " ",
+        span("↓", "dim"),
+        span(pi.stats.outputText ?? "0", "dim"),
+        " ",
+        span("$", "accent"),
+        span(pi.stats.costText ?? "0.000", "success"),
+      ],
+    },
+    context: {
+      visible: true,
+      line: 3,
+      zone: "left",
+      order: 10,
+      column: "50%",
+      render: ({ pi, span }) => {
+        if (!pi.context) return undefined;
+        const tone = pi.context.tone ?? "muted";
+        return [
+          span("ctx", tone),
+          " ",
+          span(pi.context.percentText ?? "?%", tone),
+          " ",
+          span(pi.context.tokenText ?? "?/?", tone),
+        ];
+      },
+    },
+    pr: {
+      visible: true,
+      line: 3,
+      zone: "left",
+      order: 20,
+      column: "66%",
+      render: ({ pi, span }) => {
+        if (!pi.pr) return undefined;
+        return [
+          span("PR ", "muted"),
+          span(pi.pr.checkGlyph ?? "•", pi.pr.checkTone ?? "muted"),
+          span(pi.pr.commentsText ?? "", "muted"),
+        ];
+      },
+    },
+  },
+  adapters: {
+    watchdog: {
+      source: "extensionStatus",
+      key: "compaction-continue",
+      itemId: "watchdog",
+      match: "(on|off)",
+      group: 1,
+      urlPath: "url",
+      placement: { visible: true, line: 2, zone: "right", order: 20 },
+      render: ({ value, span }) => [
+        span("watchdog:", "muted"),
+        span(value ?? "", "accent,bold"),
+      ],
+    },
+  },
+} satisfies FooterFrameworkConfig;
+
+export default config;