Use Inline Mode

Inline mode renders into a region at the bottom of the terminal instead of taking over the whole screen, leaving the shell's scrollback visible above.

Overview

inline() reserves a fixed number of rows at the bottom of the terminal; the normal buffer and its scrollback stay put above them. That suits pickers and prompts that live inside a session and hand a result back to the calling code, rather than owning the terminal until the user quits.

Render in a region

Call inline() with the number of rows to reserve:

use Phui\Screen;

Screen::mount(BranchPicker::class)
    ->inline(10)
    ->run();

The region is clamped to the window height, and components do not see the difference — $this->system->screenSize() reports the region's size, and layout and mouse coordinates are relative to it. When the app exits, the last frame is left in place and the shell continues below it.

Return a value to the caller

A prompt's job is to hand a value back. From inside the component, end the run with $this->system->complete(), and run() returns what you passed:

public function bindings(): array
{
    return [
        Binding::keypress(
            Keypress::ENTER,
            fn () => $this->system->complete($this->items[$this->selected]),
        ),
    ];
}

The calling script receives that value straight back from run():

$branch = Screen::mount(BranchPicker::class)->inline(10)->run();

echo "Switching to {$branch}\n";

Quitting instead of completing (Ctrl+C) returns null.

Print above the region

From inside the component, $this->system->printAbove() writes lines into the scrollback above the region — log output, completed steps, anything meant to outlive the app:

$this->system->printAbove("✓ {$file} uploaded");

Lines are queued and flushed at the start of the next frame, and the region re-anchors below them. In a full-screen (non-inline) app printAbove() does nothing.