---
status: resolved
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
claimed-at: "2026-08-01T00:45:00-04:00"
parent: "[[082-pi-ui-bottom-anchored-editor-research]]"
blocked-by: []
resolved-at: "2026-08-01T01:05:00-04:00"
tags:
  - ticket/prototype/hitl
---

# Flex spacer bottom anchor prototype

## Question

Can a small Pi TUI patch prototype eliminate blank space below the prompt by inserting flexible empty space above the prompt/status/editor stack only when the rendered content is shorter than the terminal?

## Motivation

The screenshots show that the current editor looks good when enough transcript content pushes it to the bottom.
The bad case is not that the editor is always misplaced.
The bad case is that the linear Pi stack can be underfilled, leaving spare terminal rows after the editor.

The desired behavior is therefore narrower than a full prompt redesign.
When content is short, spare vertical rows should appear above the prompt area rather than below it.
When content is long, the current visual behavior should remain unchanged.

## Prototype shape

Build a throwaway local Pi patch or wrapper that preserves the existing component order but splits the rendered output into two conceptual groups:

1. Flow content: header, loaded resources, chat transcript, and other scrollable/top content.
2. Pinned input area: compact status widget, editor, below-editor widgets, and footer if enabled.

On render, compute available terminal rows.
If the combined flow and pinned lines are shorter than the terminal height, insert blank spacer lines between the flow content and pinned input area.
If the combined lines meet or exceed terminal height, insert no spacer and preserve normal scrolling behavior.

## Acceptance criteria

- In a short conversation, the editor appears at the terminal bottom with spare rows above the compact status/editor area.
- In a long conversation, the editor still appears naturally at the bottom with no extra gap inserted into the transcript.
- The compact status prototype remains visually attached to the editor.
- Hiding the footer does not create blank rows below the editor.
- Terminal resize recomputes the spacer without accumulating stale blank lines.
- Autocomplete behavior is observed and documented, even if not fixed in this prototype.
- The result is judged by HITL screenshots before any permanent spec chooses a Pi patch direction.

## Non-goals

Do not solve quota display in this ticket.
Do not make a durable dotfiles deployment in this ticket.
Do not replace Pi's whole TUI.
Do not claim this is extension-only unless the prototype actually avoids patching Pi internals.

## Prototype build

A throwaway patched Pi copy was created at:

```text
/home/alexion/.local/share/pi-flex-spacer-prototype/pi-monorepo
```

Launch it with:

```bash
/home/alexion/.local/share/pi-flex-spacer-prototype/pi-flex-spacer
```

The patch adds `FlexSpacerBottomLayout` in `dist/modes/interactive/interactive-mode.js`.
It renders header, loaded resources, and chat as flow content.
It renders pending messages, status, above-editor widgets, editor, below-editor widgets, and footer as the pinned input area.
When the combined lines are shorter than `ui.terminal.rows`, it inserts blank rows between those groups.

## HITL observations

The first launcher omitted Pi's Nix wrapper PATH additions for `fd` and `rg`.
That did not fully explain the `@` autocomplete failure.
Pi's tool lookup found `/home/alexion/.pi/agent/bin/fd` before `PATH`, and that downloaded generic Linux binary fails on NixOS with the stub-ld error.
The prototype now patches its copied `tools-manager.js` so `commandExists()` requires exit status `0` and the local tool path is validated before use.
This makes Pi fall back to the Nix `fd` on `PATH`.
A tmux-launched test confirmed `@` now opens file suggestions in `/home/alexion/wrk/dotfiles`.

Pi has a separate shrink-clearing issue after autocomplete.
The built-in editor renders autocomplete suggestions below the editor, and when suggestions disappear the TUI may leave stale rows because `terminal.clearOnShrink` defaults to `false`.
This can produce a massive apparent gap after an autocomplete interaction in both stock Pi and the prototype.
This ticket should distinguish that rendering artifact from the flex-spacer layout behavior.

## Verdict

HITL verdict is positive.
The flex-spacer behavior feels smooth and should be the preferred permanent layout direction.
It should be specified as a small Pi layout patch or upstreamable TUI layout change, not as a fragile extension spacer hack.

The prototype also effectively fixes the observed post-autocomplete gap in this prompt-area case because the rendered stack continues to fill the terminal height after the autocomplete list disappears.
That makes `terminal.clearOnShrink` less important for this customization.
Keep `clearOnShrink` as a separate Pi rendering knob for other stale-row cases, but do not make it the primary fix for prompt anchoring.

## Notes

`0x-rya/pi-local-mods` is relevant prior art because its `FixedBottomScrollLayout` separates scroll children from pinned children.
This ticket tests the simpler version first: a flexible spacer between the existing transcript flow and prompt area.
