# 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`.