Bottom anchored editor research

Question

Can Pi extensions make the prompt editor stay anchored to the bottom and grow upward, with autocomplete menus rendered above the editor as overlays that may cover the status bar, or does that require a Pi TUI layout change outside extension APIs?

Findings

Pi's interactive layout is a linear top-to-bottom component stack. During initialization, interactive-mode.js adds the header container, loaded resources, chat, pending messages, status, widgets above the editor, the editor container, widgets below the editor, and then the footer. There is no flex spacer, bottom dock, or extension-controlled layout manager in this stack. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js.

Pi extension widgets are limited to persistent content above or below the editor. The TUI docs document ctx.ui.setWidget("key", content) above the editor by default and { placement: "belowEditor" } below it. The source implementation stores widgets in above or below maps and rerenders those widget containers, but it does not expose a way to move the editor stack to the terminal bottom. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js.

Replacing or hiding the footer does not bottom-anchor the editor. ctx.ui.setFooter() swaps the footer component, but the footer is still simply the final child in the same linear stack. An empty custom footer removes footer text, but it does not add a bottom dock or change where previous components render. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js.

The underlying Container component simply concatenates child render lines. It calls each child's render(width) and appends every returned line to one array. That component model has no layout constraints such as grow, shrink, align-bottom, or overlay-by-default children. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/tui.js.

Pi's overlay system can draw components at terminal-relative positions, including bottom anchors, but it is separate from the normal editor stack. The TUI docs document ctx.ui.custom(..., { overlay: true, overlayOptions: { anchor: "bottom-center", ... } }), and the TUI implementation pads to the terminal height for overlay placement and composites overlays over existing lines. This can place a separate component at the bottom, but it does not make the built-in editor itself bottom anchored. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/tui.js.

Extensions can replace the editor component with ctx.ui.setEditorComponent(). The docs describe this for custom editor behavior, and the implementation creates the custom editor inside the existing editorContainer, copies the default editor submit/change handlers, copies autocomplete providers when supported, and focuses the replacement editor. This is enough to change editor rendering and autocomplete order inside the editor component, but not enough to change the editor container's position in the main stack. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js.

The built-in editor currently renders autocomplete below the editor box. In Editor.render(), it renders the top border, visible editor lines, bottom border, and then appends autocompleteList.render(contentWidth) when autocomplete is active. Therefore the current menu pushes content below the editor rather than overlaying above it. Source: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/components/editor.js.

A custom editor subclass could probably move the autocomplete list above the prompt box because the default editor's autocomplete state and list are normal JavaScript fields in the distributed code. However, that would be a fragile implementation detail rather than a public autocomplete-placement API, and it would still leave the editor container in the linear top-flow layout. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/components/editor.js; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md.

A pure extension hack could render blank lines in an above-editor widget to push the editor downward. That would require estimating the height of all content above the widget from terminal rows and previous render state, and it would be vulnerable to streaming output, overlays, terminal resize, autocomplete, and other extensions. No public Pi extension API provides the needed stable measurement or a flexible spacer primitive. Sources: /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md; /nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/tui.js.

Answer

Pi extensions cannot cleanly make the built-in prompt editor stay bottom anchored and grow upward with the current public APIs. They can hide or replace the footer, add widgets above or below the editor, replace the editor component inside the same editor slot, and show independent overlays. Those APIs do not move the editor slot to the bottom of the terminal or make autocomplete an above-editor overlay.

The desired behavior should be specified as a Pi TUI layout change, not as a durable extension-only implementation. The likely core change is a bottom-docked input area whose fixed bottom stack contains status, editor, and optional footer, while the transcript area occupies the remaining space above it. Autocomplete should be rendered as an overlay anchored immediately above the editor, with status as lower-priority content it may cover.

Implementation implications

For the current prototype, keep the compact status widget and hidden footer as a visual draft, but do not treat its remaining dead space as fixable through setWidget(). A short-term experiment may subclass CustomEditor to render autocomplete above the editor, but that should be labeled a throwaway spike. The robust path is an upstream Pi change or local Pi patch that introduces bottom docking and editor-owned overlay autocomplete placement.

Limitations

This research is based on the installed Pi 0.82.1 documentation and distributed JavaScript source. It did not patch Pi or build a replacement TUI layout.

Citations

/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/interactive-mode.js.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/tui.js.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-tui/dist/components/editor.js.

8.0 KiB Raw Blame History