diff --git a/docs/gpu-minibuffer-framing.md b/docs/gpu-minibuffer-framing.md new file mode 100644 index 0000000..c51f61e --- /dev/null +++ b/docs/gpu-minibuffer-framing.md @@ -0,0 +1,161 @@ +# 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` (already +filtered + fuzzy-sorted best-first, plain strings), and +`selected: Option`. 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, // None = minibuffer closed (clears the GUI) + input: String, + cursor: u32, // codepoints before the cursor in `input` + candidates: Vec, // windowed slice (≤ MB_VISIBLE) + selected: Option, // 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. diff --git a/pmacs-gpu/src/main.rs b/pmacs-gpu/src/main.rs index 23bc7a1..44dbf2f 100644 --- a/pmacs-gpu/src/main.rs +++ b/pmacs-gpu/src/main.rs @@ -124,6 +124,17 @@ const MENU_MAX_WIDTH: f32 = 380.0; const MENU_BG: [f32; 4] = [0.16, 0.16, 0.20, 0.98]; const MENU_SELECTED_BG: [f32; 4] = [0.20, 0.40, 0.66, 1.0]; const MENU_SEPARATOR_BG: [f32; 4] = [0.30, 0.30, 0.36, 1.0]; + +// Minibuffer completion dropdown (Q#MB1). A vertical list anchored just +// above the bottom band, best match at the top; reuses the menu popup's +// colors. Width tracks the widest candidate (measured from the shaped +// buffer). +const MB_DROP_ROW_HEIGHT: f32 = 20.0; +const MB_DROP_FONT_SIZE: f32 = 13.0; +const MB_DROP_LINE_HEIGHT: f32 = 20.0; +const MB_DROP_PAD_X: f32 = 10.0; +const MB_DROP_MIN_WIDTH: f32 = 160.0; +const MB_DROP_MAX_WIDTH: f32 = 480.0; const QUAD_SHADER: &str = r" struct VertexOut { @builtin(position) pos: vec4, @@ -555,6 +566,10 @@ struct State { /// the buffer name; the matches highlight via `SearchMatch` /// decorations. search_prompt: Option, + /// Q#MB1 — the live minibuffer (protocol v12), or `None` when + /// closed. The prompt+input render in the bottom band; the + /// candidates (when present) render as a dropdown above it. + minibuffer: Option, /// Q#CM1 — the live context menu (protocol v11), or `None` when /// closed. The rows + highlight come from `MenuPrompt`; the popup /// draws at the pixel of the right-click. @@ -570,6 +585,14 @@ struct State { menu_text_renderer: TextRenderer, /// Popup background / highlight / separator quads (Q#CM1). menu_bg_vertex_buffer: ReusableVertexBuffer, + /// Shaped candidate text for the minibuffer dropdown (Q#MB1), one + /// line per candidate. + mb_buffer: Buffer, + /// Dedicated text renderer for the minibuffer dropdown (its own + /// layer over the buffer, like the menu's). + mb_text_renderer: TextRenderer, + /// Minibuffer dropdown background + selection quads (Q#MB1). + mb_bg_vertex_buffer: ReusableVertexBuffer, /// Minimap vertex bytes cached by [`MinimapCacheKey`] — /// rebuilding rescanned every line shape per frame. minimap_cache: Option<(MinimapCacheKey, Vec)>, @@ -598,6 +621,20 @@ struct SearchPromptLocal { invalid: bool, } +/// The live minibuffer (Q#MB1, protocol v12), mirrored from a +/// `MinibufferPrompt` whose `prompt` was `Some`. The prompt+input draw +/// in the bottom band with a caret; `candidates` (a windowed slice) feed +/// the dropdown. +#[derive(Clone, Debug, PartialEq)] +struct MinibufferLocal { + prompt: String, + input: String, + cursor: u32, + candidates: Vec, + selected: Option, + total: u32, +} + /// The live context menu (Q#CM1, protocol v11), mirrored from a /// `MenuPrompt` with non-empty rows. The popup draws at `anchor_px` /// (the right-click pixel, remembered locally — the daemon never sees @@ -828,6 +865,23 @@ impl ApplicationHandler for App { return; } + // Minibuffer-opening chords (Q#MB1): M-x (execute-command) + // and the C-x prefix. Forwarded though otherwise withheld + // so the GUI can open a prompt / enter a prefix; the + // daemon then flips `dispatch_idle` false (minibuffer + // active / pending prefix) and the intercept gate + // round-trips every following key. No optimistic local + // flip (the search-entry precedent). + if is_minibuffer_open_chord(pkey, pmods) { + if let Some(state) = self.state.as_mut() { + state.mark_cursor_stale_after_round_trip(); + } + if let Err(e) = client.send_key(pkey, pmods) { + eprintln!("pmacs-gpu: send_key (minibuffer open) failed: {e}"); + } + return; + } + // Session B2 forwards cursor motion + plain text editing // (Char / Backspace / Enter / Delete / Tab). Ctrl/Alt/ // Meta chords are withheld — they drive commands and @@ -1555,6 +1609,9 @@ impl State { // Q#CM1 — a second renderer so the menu draws as a top layer. let menu_text_renderer = TextRenderer::new(&mut atlas, &device, MultisampleState::default(), None); + // Q#MB1 — a third renderer for the minibuffer dropdown layer. + let mb_text_renderer = + TextRenderer::new(&mut atlas, &device, MultisampleState::default(), None); let quad_renderer = QuadRenderer::new(&device, surface_format); let squiggle_renderer = SquiggleRenderer::new(&device, surface_format); @@ -1595,6 +1652,15 @@ impl State { Some(MENU_MAX_WIDTH), Some(config.height as f32), ); + let mut mb_buffer = Buffer::new( + &mut font_system, + Metrics::new(MB_DROP_FONT_SIZE, MB_DROP_LINE_HEIGHT), + ); + mb_buffer.set_size( + &mut font_system, + Some(MB_DROP_MAX_WIDTH), + Some(config.height as f32), + ); buffer.set_text( &mut font_system, initial_text, @@ -1667,11 +1733,15 @@ impl State { status_left_text: String::new(), status_facts: None, search_prompt: None, + minibuffer: None, menu: None, menu_anchor_px: (0.0, 0.0), menu_buffer, menu_text_renderer, menu_bg_vertex_buffer: ReusableVertexBuffer::new(), + mb_buffer, + mb_text_renderer, + mb_bg_vertex_buffer: ReusableVertexBuffer::new(), minimap_cache: None, } } @@ -1692,9 +1762,13 @@ impl State { /// every key to the daemon's handler instead of optimistically /// applying it to the buffer. fn daemon_intercepts_keys(&self) -> bool { - // Q#CM1 — an open menu shadows the keymap like search: every key - // round-trips so the daemon's `dispatch_menu_key` drives it. - self.search_prompt.is_some() || self.menu.is_some() || !self.dispatch_idle + // Q#CM1 / Q#MB1 — an open menu or minibuffer shadows the keymap + // like search: every key round-trips so the daemon's + // `dispatch_menu_key` / minibuffer handler drives it. + self.search_prompt.is_some() + || self.menu.is_some() + || self.minibuffer.is_some() + || !self.dispatch_idle } /// Shared eligibility gates for the optimistic edit paths @@ -2474,6 +2548,27 @@ impl State { self.window.request_redraw(); None } + // Q#MB1 — the minibuffer prompt/input/candidates. `prompt: + // None` closes it. + InstanceMessage::MinibufferPrompt { + prompt, + input, + cursor, + candidates, + selected, + total, + } => { + self.minibuffer = prompt.map(|prompt| MinibufferLocal { + prompt, + input, + cursor, + candidates, + selected, + total, + }); + self.window.request_redraw(); + None + } _ => None, } } @@ -2897,6 +2992,12 @@ impl State { /// over the band like Emacs's echo area, returning to the buffer /// name + modified dot (v8 `StatusFacts`) when the search ends. fn compose_status_left(&self) -> String { + // Q#MB1 — an open minibuffer takes over the band: prompt + input + // (the candidates render separately as a dropdown). Measured by + // the band caret, so it must stay exactly `prompt + input`. + if let Some(mb) = self.minibuffer.as_ref() { + return format!("{}{}", mb.prompt, mb.input); + } if let Some(sp) = self .search_prompt .as_ref() @@ -3052,6 +3153,75 @@ impl State { rects_to_vertex_bytes(&rects, self.config.width, self.config.height) } + /// Re-shape the minibuffer dropdown candidates (Q#MB1), one line per + /// candidate, best match first. Empty when there are no candidates. + fn refresh_mb_buffer(&mut self) { + let text = self + .minibuffer + .as_ref() + .map_or_else(String::new, |mb| mb.candidates.join("\n")); + self.mb_buffer.set_text( + &mut self.font_system, + &text, + &Attrs::new().family(Family::Name("JetBrains Mono")), + Shaping::Advanced, + None, + ); + self.mb_buffer + .shape_until_scroll(&mut self.font_system, false); + } + + /// Dropdown geometry `(left, top_y, width)` when the minibuffer has + /// candidates: a list anchored just above the bottom band, growing + /// upward, as wide as the widest candidate (clamped). `None` when + /// closed or candidate-free. `refresh_mb_buffer` must have run so the + /// width measurement is current. + fn mb_dropdown_rect(&self) -> Option<(f32, f32, f32)> { + let mb = self.minibuffer.as_ref()?; + let n = mb.candidates.len(); + if n == 0 { + return None; + } + let widest = self + .mb_buffer + .layout_runs() + .map(|r| r.line_w) + .fold(0.0_f32, f32::max); + let width = (widest + 2.0 * MB_DROP_PAD_X).clamp(MB_DROP_MIN_WIDTH, MB_DROP_MAX_WIDTH); + let band_top = text_area_bottom(self.config.height); + let top_y = band_top - n as f32 * MB_DROP_ROW_HEIGHT; + Some((STATUS_TEXT_PAD, top_y, width)) + } + + /// Minibuffer dropdown background + selection-highlight quads (Q#MB1). + /// Empty when closed / candidate-free. + fn mb_dropdown_vertex_bytes(&self) -> Vec { + let Some(mb) = self.minibuffer.as_ref() else { + return Vec::new(); + }; + let Some((x, top_y, width)) = self.mb_dropdown_rect() else { + return Vec::new(); + }; + let n = mb.candidates.len(); + let mut rects = vec![MinimapRect { + x, + y: top_y, + w: width, + h: n as f32 * MB_DROP_ROW_HEIGHT, + color: MENU_BG, + }]; + if let Some(sel) = mb.selected { + rects.push(MinimapRect { + x, + y: top_y + sel as f32 * MB_DROP_ROW_HEIGHT, + w: width, + h: MB_DROP_ROW_HEIGHT, + color: MENU_SELECTED_BG, + }); + } + rects_to_vertex_bytes(&rects, self.config.width, self.config.height) + } + /// Bookkeeping for an outgoing Pointer event: it supersedes any /// unconfirmed optimistic-cursor prediction (the daemon's answer /// will be the click position, not the typing prediction), and @@ -3392,6 +3562,21 @@ impl State { &menu_vertices, ) .cloned(); + // Q#MB1 — the minibuffer dropdown quads (bg + selection), a top + // layer above the band. `refresh_mb_buffer` first so the width + // measurement in `mb_dropdown_vertex_bytes` is current. + self.refresh_mb_buffer(); + let mb_vertices = self.mb_dropdown_vertex_bytes(); + let mb_vertex_count = (mb_vertices.len() / QUAD_VERTEX_STRIDE as usize) as u32; + let mb_bg_buffer = self + .mb_bg_vertex_buffer + .upload( + &self.device, + &self.queue, + "pmacs-gpu minibuffer dropdown", + &mb_vertices, + ) + .cloned(); // The band's strip rides the bg quad batch so it draws under // the band text (text renders after the first quad draw). let mut bg_vertices = self.decoration_background_vertex_bytes(); @@ -3570,6 +3755,37 @@ impl State { ) .expect("menu text_renderer prepare"); + // Q#MB1 — prepare the minibuffer dropdown glyphs in their layer. + let mb_areas: Vec