pmacs/docs/gpu-minibuffer-framing.md

GPU minibuffer — framing + as-built

pmacs-gpu couldn't render the minibuffer, so M-x, find-file, switch-buffer, and the LSP rename prompt were invisible in the GUI — both prior arcs (search, context menu) had to route around this gap. This arc closed it. The build landed close to the framing (the third surface in the SearchPrompt / MenuPrompt family); the "As-built" notes record where it differed.

Decided (with the user):

• Render-only. The minibuffer logic already lived entirely in the core; the GPU already round-tripped keys while one was open (dispatch_idle goes false). So this was a wire-message + GPU render-surface arc — no new input logic.
• Vertical dropdown for candidates (Vertico / Telescope style), not the TUI's inline [selected]. The GPU leads the TUI here; the cross-frontend divergence is accepted (discussed against how Emacs and Neovim converged on a vertical list).

What the core already exposed

A single global EditorCore::minibuffer (not per-buffer). While a prompt is open, MinibufferSession carries everything a renderer needs: prompt (e.g. "M-x "), the typed input (minibuffer.contents()), the cursor (byte offset), candidates: Vec<String> (already filtered + fuzzy-sorted best-first, plain strings), and selected: Option<usize>. Input is fully handled by MinibufferAction::from_chord (RET accept, TAB complete, C-g/Esc cancel, Up/Down history, M-n/M-p cycle candidates, motion, self-insert). These fields are all public, so the producer reads them directly — the core was untouched, exactly the family bet.

Architecture

Q#MB1 — A MinibufferPrompt semantic message, mirroring the family

InstanceMessage::MinibufferPrompt (protocol v12), produced by semantic_render::minibuffer_prompt_msg with the same cached-compare suppression as search_prompt_msg / menu_prompt_msg, daemon-gated >= 12. The GPU mirrors it into a MinibufferLocal and renders. The minibuffer is global, so the message is bufferless — the producer caches a single value (not a per-buffer HashMap) and emits only from the active-buffer viewport so the bufferless message ships once per frame.

Q#MB2 — The prompt line lives in the bottom band

When the minibuffer is open, compose_status_left returns exactly prompt + input, taking over the band ahead of the search prompt and status. The buffer caret is hidden; a band caret quad draws at the input cursor. As-built: the caret x uses the band font's monospace advance — the shaped status-left width ÷ its char count, times prompt_chars + cursor — rather than a per-glyph measurement (Q#MB4). Exact for the ASCII command names / filenames that dominate; a multibyte-exact caret is deferred.

Q#MB3 — The candidate dropdown floats above the band

A vertical popup anchored just above the band at the input's left edge, growing upward, best match at the top, the selected row highlighted. As-built: it's a third TextRenderer (mb_text_renderer) over bg/selection quads — the menu's popup pattern, reusing the menu's colors — not "a second" renderer (the menu already owns one). It only appears when there are candidates, so free-form prompts (project.search, rename) stay a single line. The list is a scrolled window: the producer sends a bounded slice (≤ MB_VISIBLE = 10) around selected plus total, so a 1000-command M-x ships ~10 strings per keystroke, not 1000, and the selected row stays in view as you cycle.

Q#MB4 — Cursor as a codepoint offset

The message carries cursor as the count of codepoints before the cursor in input (computed in the producer via char_indices). See Q#MB2 for how the GPU turns it into the band caret x.

Q#MB5 — Forwarding the chords that open the minibuffer

The GPU withholds command chords by default, so M-x and the C-x prefix never reached the daemon — the minibuffer couldn't even be opened. is_minibuffer_open_chord now forwards them: M-x (→ execute-command, from which any command incl. find-file / switch-buffer is reachable by name) and the C-x prefix (so the bound C-x b / C-x C-f work). Both flip the daemon into a state (minibuffer active / pending prefix) that makes dispatch_idle go false, after which the intercept gate round-trips every key. Mirrors is_search_entry_chord / is_clipboard_chord; no optimistic local flip (the search precedent). General Emacs-chord forwarding stays a separate thread; this arc forwarded only what opens a prompt.

Wire (protocol v12)

Additive over v11; SUPPORTED = [6..12]:

InstanceMessage::MinibufferPrompt {
    prompt: Option<String>,   // None = minibuffer closed (clears the GUI)
    input: String,
    cursor: u32,              // codepoints before the cursor in `input`
    candidates: Vec<String>,  // windowed slice (≤ MB_VISIBLE)
    selected: Option<u32>,    // highlighted row *within* `candidates`
    total: u32,               // full candidate count
}

Cached-compare suppressed like SearchPrompt; first sight while closed stays silent. Daemon-gated >= 12. The TUI ignores the variant (it paints the minibuffer via its own bottom row). The whole shape (incl. candidates) landed at v12, so the dropdown phase needed no second bump.

Phasing (delivered; each commit binary-build-green)

1. Wire + prompt line — protocol v12 + producer + daemon gate + GPU handler + the band prompt line (prompt + input + caret) + the opening-chord forwarding (M-x, C-x). M-x opens, typing works, RET runs. User-validated.
2. Candidate dropdown — GPU-render-only: the vertical popup above the band, consuming the candidates already on the wire. User-validated.
3. Docs — this consolidation.

Phase 1 made the minibuffer work in the GUI; phase 2 made it pleasant. The v12 bump means the daemon + pmacs-gpu must both be rebuilt to negotiate it.

Categorical bets (all held)

• The family pattern generalized a third time. MinibufferPrompt + the band/popup surfaces dropped in as the same shape as search and the menu; the producer/cached-compare/gate machinery reused cleanly and the core stayed untouched.
• A windowed candidate slice was enough. ~10 around the selection keeps the wire cheap and the dropdown correct as you cycle.
• Forwarding only the opening chords was the right cut. M-x + C-x make the minibuffer reachable without the general chord-forwarding can of worms.

As-built divergences from the framing

1. Caret via monospace advance (Q#MB2/Q#MB4), not a per-glyph width measurement — simpler, exact for the ASCII case that dominates.
2. A third TextRenderer for the dropdown, not "a second" — the menu already owns its own popup renderer; the dropdown got a dedicated one and reuses the menu's colors.
3. Dropdown ordering pinned to best-at-top, growing upward — the framing left it unspecified; top-to-bottom reading with M-n moving the highlight down was the least surprising.
4. total ships but isn't rendered — the "i/total" hint is deferred (below).

Deferred (named, not silently dropped)

• General Emacs-chord forwarding in the GPU (every binding, not just the prompt-openers) — the separate thread this arc brushes against.
• The "i/total" count hint and a Telescope-style preview pane beside the list.
• Candidate annotations (kind / docstring) — the core's candidates are bare strings today.
• Bringing the TUI's inline [selected] up to the same dropdown (unify the frontends); for now the GPU leads.
• Multibyte-exact caret positioning in the band.