Add artifact vault contents
This commit is contained in:
79
projects/dotfiles/058-pi-ui-tui-layout-research.md
Normal file
79
projects/dotfiles/058-pi-ui-tui-layout-research.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
status: resolved
|
||||
parent: "[[057-pi-ui-customization-map]]"
|
||||
blocked-by: []
|
||||
resolved-at: "2026-07-31T23:58:11-04:00"
|
||||
tags:
|
||||
- ticket/research
|
||||
---
|
||||
|
||||
# Pi TUI layout customization research
|
||||
|
||||
## Question
|
||||
|
||||
What can Pi extensions change about the prompt-area layout, footer, widgets above or below the editor, working indicator, and editor chrome, and can the current below-prompt information be consolidated into a status bar above the text prompt without patching Pi itself?
|
||||
|
||||
## Findings
|
||||
|
||||
Pi extensions can replace the built-in footer without patching Pi.
|
||||
The TUI docs describe `ctx.ui.setFooter((tui, theme, footerData) => component)` as the custom-footer API and state that it replaces the footer, while `ctx.ui.setFooter(undefined)` restores the built-in footer.
|
||||
The implementation confirms the replacement behavior: `setExtensionFooter` removes either the existing custom footer or built-in footer from the UI, creates the custom footer from the factory, and adds it to the UI.
|
||||
The same implementation restores the built-in footer when the factory is undefined.
|
||||
Sources: `docs/tui.md` section “Pattern 6: Custom Footer”; `docs/extensions.md` section “Widgets, Status, and Footer”; `dist/modes/interactive/interactive-mode.js` `setExtensionFooter`.
|
||||
|
||||
Pi extensions can add persistent widgets above the editor or below the editor.
|
||||
The documented `ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"])` call places a widget above the editor by default, and `ctx.ui.setWidget(..., { placement: "belowEditor" })` places it below the editor.
|
||||
The shipped `widget-placement.ts` example uses exactly those two calls on `session_start`.
|
||||
This gives an extension-supported way to put a custom status bar directly above the text prompt.
|
||||
Sources: `docs/tui.md` section “Pattern 5: Widgets Above/Below Editor”; `docs/extensions.md` section “Widgets, Status, and Footer”; `examples/extensions/widget-placement.ts`.
|
||||
|
||||
Pi extensions can customize the working indicator and working visibility.
|
||||
The docs expose `ctx.ui.setWorkingMessage`, `ctx.ui.setWorkingVisible`, and `ctx.ui.setWorkingIndicator`.
|
||||
This can reduce or alter the streaming “working” chrome, but it only affects the streaming loader row and indicator, not the entire prompt layout.
|
||||
Sources: `docs/extensions.md` section “Widgets, Status, and Footer”; `docs/tui.md` section “Pattern 4b: Working Indicator Customization”; `examples/extensions/working-indicator.ts`.
|
||||
|
||||
Pi extensions can replace the editor component, but that is a more invasive path.
|
||||
The TUI docs describe a `CustomEditor` pattern and advise extending `CustomEditor` rather than the base `Editor` to preserve app keybindings such as escape-to-abort, ctrl-d, and model switching.
|
||||
The extensions docs list `modal-editor.ts` as the example for `setEditorComponent`.
|
||||
The implementation exposes `setEditorComponent` and `getEditorComponent` in the extension UI context.
|
||||
This means editor replacement is possible if footer plus above-editor widget does not remove enough dead space, but it should not be the first prototype.
|
||||
Sources: `docs/tui.md` section “Pattern 7: Custom Editor”; `docs/extensions.md` examples reference; `dist/modes/interactive/interactive-mode.js` extension UI context.
|
||||
|
||||
Pi has a `setHeader` API in the implementation and a shipped `custom-header.ts` example, but the docs describe it as replacing the startup header rather than the prompt-area footer.
|
||||
It is not the right primary hook for moving footer information above the prompt.
|
||||
Sources: `examples/extensions/custom-header.ts`; `docs/extensions.md` examples reference; `dist/modes/interactive/interactive-mode.js` `setExtensionHeader`.
|
||||
|
||||
The built-in footer currently owns exactly the information the user wants to consolidate: cwd plus branch and session name, session usage totals, context usage, model, thinking level, and extension statuses.
|
||||
The implementation constructs a `pwdLine`, a stats/model line, and an optional extension-status line.
|
||||
The footer data provider exposes git branch and extension statuses to custom footers, while token stats and model info are expected to come from the session context and model.
|
||||
Sources: `dist/modes/interactive/components/footer.js`; `dist/core/footer-data-provider.js`; `examples/extensions/custom-footer.ts`.
|
||||
|
||||
## Answer
|
||||
|
||||
Yes, the target customization can be prototyped without patching Pi.
|
||||
The most promising extension-only design is:
|
||||
|
||||
1. Replace the built-in footer with a minimal or empty custom footer to remove below-prompt lines.
|
||||
2. Add a one-line widget above the editor to show cwd, branch, context usage, model, and thinking level.
|
||||
3. Customize or hide the working indicator only if the working row contributes meaningful dead space during streaming.
|
||||
4. Avoid editor replacement unless the footer-plus-widget prototype proves insufficient.
|
||||
|
||||
## Limitations
|
||||
|
||||
The docs and implementation establish that a widget can be placed above the editor and that the footer can be replaced.
|
||||
They do not prove the exact visual result will feel good in the live TUI.
|
||||
That needs the HITL prototype ticket.
|
||||
|
||||
The footer APIs can replace the footer, but they do not literally move the built-in footer component above the editor.
|
||||
The extension must recreate the desired data presentation in its own widget or custom footer.
|
||||
|
||||
## Citations
|
||||
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/tui.md`, sections “Pattern 5: Widgets Above/Below Editor”, “Pattern 6: Custom Footer”, and “Pattern 7: Custom Editor”.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`, section “Widgets, Status, and Footer” and examples reference table.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/widget-placement.ts`.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-footer.ts`.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-header.ts`.
|
||||
- `/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/dist/modes/interactive/components/footer.js`.
|
||||
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/core/footer-data-provider.js`.
|
||||
Reference in New Issue
Block a user