Reserve space for path navigation and completion

Accepted · 2026-09-05

• Decision owners: Quirl maintainers

Context

The rich viewport previously kept the prompt fixed near the bottom and painted completion panels over recent output. That hid filenames people needed while writing a command. Automatic filesystem suggestions also looked selectable but left Enter bound to execution, submitting incomplete paths instead of accepting the visible directory. The maintainer requested space below the input and successive Enter presses to navigate directory components.

Decision

• Partition transcript, context/editor, diagnostics, information panel, and status into disjoint rectangles. Reserve the requested bounded panel height before drawing history. Its oldest visible rows scroll upward; the newest output remains above the input. Retained history is unchanged.
• Use the existing panel row limits and terminal-size limits. Narrow layouts omit documentation and reserve only the required result rows. Tiny terminals prioritize the editor and status; scrolling history suppresses input panels.
• Enter accepts a visible filesystem suggestion without executing a command. Directory acceptance starts a fresh bounded completion request for children. Escape then Enter executes an intermediate directory. File acceptance closes the menu. Informational command/flag suggestions retain their existing Enter execution behavior until the user selects completion navigation.
• A complete filename is ready to execute. Automatic suggestions must not consume Enter for a no-op replacement or a longer sibling filename; explicit Tab still permits choosing alternatives.

Failure model and validation

Overlapping rectangles can erase history, stale completion responses can replace the next directory's children, and a rejected oversized edit must not trigger a request for a path that was never inserted. Compute drawing and hit-testing from the same bounded layout, cancel the prior request before refreshing children, and retain the editor's resource diagnostic if replacement fails.

Home completion must use the same private HOME as execution. Publish a shared raw UTF-8 path once per environment generation, before converting environment values to inspector display text. Retain at most 64 KiB; missing, invalid, or oversized values clear previous completion state without falling back to the process-global home. Requests clone a shared handle rather than the environment. Execution retains its separate expansion limit and actionable diagnostics.

Frame tests cover full history, narrow documentation suppression, resize, dismissal, scrolled history, and tiny terminal dimensions. A real-PTY journey fills the viewport, accepts nested paths and a spaced filename, checks recent output remains above completion, executes the selected path, and verifies prompt restoration. These changes preserve ADR 0022's bounded transcript ownership.