@badliveware/pi-footer-framework 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,8 @@
 # pi-footer-framework
 
-A configurable footer framework extension that intentionally owns/hijacks the footer and lets users control layout sections.
+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.
 
-This is designed to pair with primitive-emitting extensions (for example `pr-upstream-status` via `pr-upstream:state`).
-
-It ships with a bundled skill (`footer-framework-config`) and advertises it via package metadata + `resources_discover`, so Pi can apply footer tuning commands automatically when this extension is active.
+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
 
@@ -12,94 +10,330 @@ It ships with a bundled skill (`footer-framework-config`) and advertises it via
 pi install npm:@badliveware/pi-footer-framework
 ```
 
-For local testing from this repository:
+No external services or credentials are required.
 
-```bash
-pi -e /path/to/pi/agent/extensions/public/footer-framework
+## Quick use
+
+```text
+/footerfx on
+/footerfx item context line 1
+/footerfx item context after model
+/footerfx item pr line 3
+/footerfx anchor all right
+/footerfx save user
+```
+
+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
+```
+
+## Showcase
+
+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:
+
+![Footer framework showcase with cwd, PR, model, token stats, context, and watchdog status](assets/footer-framework-showcase.png)
+
+The screenshot demonstrates:
+
+- 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" }}
 ```
 
-## Behavior
+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;
+```
 
-- Replaces the default footer when enabled.
-- Keeps a stable 2-line footer layout.
-- Composes built-in footer items:
-  - `cwd`, `model`, `branch`, `stats`, `context`, `pr`, `ext`
-  - the `model` item includes the active thinking level as `<model-id>:<thinking-level>`
-  - the `context` item shows current context-window usage as percent plus humanized `tokens/max` counts, for example `ctx 52.2% 142K/272K`
-- Supports extension-provided dynamic items via the event bus.
-- Lets users position each item independently by line, left/right zone, relative order, or absolute column.
+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`.
 
-## Persistence
+`/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.
 
-Footer settings automatically persist to the user config file by default:
+## Configuration files
+
+User settings persist to:
 
 ```text
 ~/.pi/agent/footer-framework.json
 ```
 
-If a project config exists, it overrides user settings for that project:
+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` to intentionally create/update the project config.
+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
 
-- `/footerfx` — show current config and source
-- `/footerfx config` — show user/project config paths and loaded source
-- `/footerfx load` — reload user/project config files
-- `/footerfx save user` — save current settings to user config
-- `/footerfx save project` — save current settings to project config
-- `/footerfx on` — enable framework footer
-- `/footerfx off` — disable and restore default footer
-- `/footerfx reset` — restore defaults and persist to user config
-- `/footerfx section <cwd|stats|context|model|branch|pr|ext> <on|off>` — legacy section toggles
-- `/footerfx item <id> <show|hide|reset>`
-- `/footerfx item <id> line <1|2>`
-- `/footerfx item <id> zone <left|right>`
-- `/footerfx item <id> order <n>`
-- `/footerfx item <id> before <other-id>` / `/footerfx item <id> after <other-id>`
-- `/footerfx item <id> column <n|off>` — absolute column placement
-- `/footerfx anchor <line1|line2|all> <gap|left|center|right|spread>` — line-level right-zone anchoring
-- `/footerfx gap <min> <max>` — spacing controls used by `gap`/`center`/`left` modes
-- `/footerfx branch-width <n>` — max branch label width
-- `/footerfx mcp-zero <hide|show>` — hide/show `MCP: 0/x servers`
-- `/footerfx-debug` — dump latest footer snapshot and settings
-  - includes per-line layout telemetry: left/right widths, pad width, right start/end columns, truncation
-
-## Extension item API
-
-Other extensions can contribute footer items by emitting:
+| Command | What it does |
+| --- | --- |
+| `/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 <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>` / `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-debug` | Show render snapshot, settings, template/render diagnostics, loaded TS/JS renderers, and layout telemetry. |
+
+## Agent tools
+
+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`
+
+`footer_framework_sources` is concise by default. Pass `includeTools`, `includeCommands`, `includeSkills`, and `includeDetails` only when runtime metadata is directly useful.
+
+## 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 }
+  }
 });
 ```
 
-Remove an item:
+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 });
 ```
 
-Users can then reposition the item with `/footerfx item my-extension:status ...` and those overrides persist automatically.
-
-## Agent automation primitives
-
-The extension exposes tools so the agent can introspect and tune the footer without asking the user to run commands:
+## Troubleshooting
 
-- `footer_framework_state` — returns settings + latest rendered footer snapshot + layout telemetry
-- `footer_framework_config` — applies the same syntax as `/footerfx ...`
+### Blank space below the footer
 
-## Notes
+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.
 
-- The extension stores latest settings in session custom entries (`footer-framework-state`).
-- It listens to event bus topic `pr-upstream:state` for PR primitives.
-- Extension statuses with empty rendered text are ignored so transient or
-  intentionally-cleared status providers do not leave phantom separators in the
-  footer.
+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;