Loaded through the root pi-ext package.
See root README.
Commands / tools / settings
Commands:
/footer: toggle footer visibility in TUI mode.
Shortcuts:
ctrl+alt+f: toggle footer visibility.
Tools: none.
Hooks:
session_start
session_shutdown
Events:
listens for footer:segment.
Settings: none.
Behavior
Owns the Pi footer through ctx.ui.setFooter() only when both ctx.hasUI is true and ctx.mode is tui.
RPC keeps UI capability for protocol interactions but does not mount the terminal footer.
JSON and print modes have no UI and do not mount it.
Visible footer has two lines normally and adds a third under LLM-segment pressure:
line 0: workspace segments plus current session name on the left, with extension statuses via ctx.ui.setStatus() right-aligned in the remaining space.
line 1: the first llm flow row.
line 2: the second llm flow row, shown only when content overflows line 1.
footer:segment payloads use id, text, and zone (workspace or llm).
Optional fields: variants, icon, color, bar, suffix, group, separator, gap, order, and an accept callback.
Adjacent segments with the same group stay together during line flow.
Grouped segments use one space internally unless a segment supplies a larger gap or the separator that precedes it.
Send { id, text: undefined } to remove a segment.
Segments sort by order, then by id so equal-priority segments remain deterministic; default order is 50.
Current session name is inserted in the workspace zone with order 0.5.
Render requests are coalesced.
Segments received before footer mount are retained for the first render without polling.
Malformed updates are ignored without replacing previously valid segments.
A producer rendering failure hides only that segment.
Branch changes trigger rerender.
Display text strips ANSI/control characters, collapses whitespace, and stays
single-line.
Footer lines are side-padded and width-truncated.
Progress bars render 10 block cells on a dim track.
Bar values clamp to 0..100.
The footer calls accept synchronously after validating and retaining an update, including updates received before mount.
TUI producers use that acknowledgement to clear their ctx.ui.setStatus() fallback; without acknowledgement they remain independently useful through status text.
Acknowledgement remains local to the runtime event bus, so nested runtimes cannot affect one another.
Hidden mode swaps in a footer component with no rendered content.
Pi fullscreen mode may still reserve layout space for that empty component.
Shutdown clears segments and footer context.
Debug
Opt in through debug contract.
Safe events: session.start, session.shutdown, footer.mount.start, footer.mount.finish.
# footer
Shared stable footer renderer for Pi.
## Install / load
Loaded through the root `pi-ext` package.
See [root README](../../README.md).
## Commands / tools / settings
- Commands:
- `/footer`: toggle footer visibility in TUI mode.
- Shortcuts:
- `ctrl+alt+f`: toggle footer visibility.
- Tools: none.
- Hooks:
- `session_start`
- `session_shutdown`
- Events:
- listens for `footer:segment`.
- Settings: none.
## Behavior
Owns the Pi footer through `ctx.ui.setFooter()` only when both `ctx.hasUI` is true and `ctx.mode` is `tui`.
RPC keeps UI capability for protocol interactions but does not mount the terminal footer.
JSON and print modes have no UI and do not mount it.
Visible footer has two lines normally and adds a third under LLM-segment pressure:
- line 0: `workspace` segments plus current session name on the left, with extension statuses via `ctx.ui.setStatus()` right-aligned in the remaining space.
- line 1: the first `llm` flow row.
- line 2: the second `llm` flow row, shown only when content overflows line 1.
`footer:segment` payloads use `id`, `text`, and `zone` (`workspace` or `llm`).
Optional fields: `variants`, `icon`, `color`, `bar`, `suffix`, `group`, `separator`, `gap`, `order`, and an `accept` callback.
Adjacent segments with the same `group` stay together during line flow.
Grouped segments use one space internally unless a segment supplies a larger `gap` or the separator that precedes it.
Send `{ id, text: undefined }` to remove a segment.
Segments sort by `order`, then by `id` so equal-priority segments remain deterministic; default order is `50`.
Current session name is inserted in the `workspace` zone with order `0.5`.
Render requests are coalesced.
Segments received before footer mount are retained for the first render without polling.
Malformed updates are ignored without replacing previously valid segments.
A producer rendering failure hides only that segment.
Branch changes trigger rerender.
Display text strips ANSI/control characters, collapses whitespace, and stays
single-line.
Footer lines are side-padded and width-truncated.
Progress bars render 10 block cells on a dim track.
Bar values clamp to `0..100`.
The footer calls `accept` synchronously after validating and retaining an update, including updates received before mount.
TUI producers use that acknowledgement to clear their `ctx.ui.setStatus()` fallback; without acknowledgement they remain independently useful through status text.
Acknowledgement remains local to the runtime event bus, so nested runtimes cannot affect one another.
Hidden mode swaps in a footer component with no rendered content.
Pi fullscreen mode may still reserve layout space for that empty component.
Shutdown clears segments and footer context.
## Debug
Opt in through [debug contract](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `footer.mount.start`, `footer.mount.finish`.