From d404d8ffd96304e7a6dc150f307582dc1f0c7818 Mon Sep 17 00:00:00 2001 From: Greg Shuflin Date: Thu, 12 Feb 2026 01:11:57 -0800 Subject: [PATCH] More buffer design changes --- docs/architecture/buffer-types.md | 223 ++++++++++++++++++++++-------- 1 file changed, 169 insertions(+), 54 deletions(-) diff --git a/docs/architecture/buffer-types.md b/docs/architecture/buffer-types.md index 9406c0a..b0f1ca5 100644 --- a/docs/architecture/buffer-types.md +++ b/docs/architecture/buffer-types.md @@ -92,94 +92,209 @@ Special buffers in Emacs are distinguished by convention and properties, not by ### Kakoune -The prompt line is a regular buffer. Kakoune treats everything uniformly -- buffers are buffers, and their role comes from context/properties rather than identity. +The prompt line is a regular buffer that supports normal editing commands. You can use movement, selection, and editing primitives to compose your command — the same muscle memory works everywhere. This is a notable improvement over Vim, where the command line is a separate input context with its own limited editing model. (Vim's `q:` cmdwin partially addresses this but is clunky.) ### Xi Editor Every view is just a buffer with metadata attached. No special-cased IDs. -## Design Space for pane-editor +### Command Palettes (VS Code, Sublime, etc.) -There's a spectrum between Neovim's explicit enum and Emacs's emergent properties: +The command palette pattern treats command input as a prominent UI element — typically a floating centered or top-anchored panel with: +- Real-time filtering/fuzzy matching +- Hints and documentation alongside candidates +- Categorized results (commands, files, symbols, etc.) -### Option A: `BufferRole` enum (Neovim-like) +The key insight is that this is a *presentation* concern. The underlying buffer holding the user's input text is the same regardless of whether it renders as a vim-style bottom line or a centered floating palette. The pane layout / rendering layer decides how and where to display it. -```rust -enum BufferRole { - Document, // normal file editing - Command, // command-line input (single-line, always insert mode) - Prompt, // general single-line input (save confirmation, etc.) - Finder, // search/picker - Help, // read-only informational - Scratch, // no file, writable -} -``` +## Decomposing the Command Buffer -`TextBuffer` gets a `role: BufferRole` field. Core logic checks `buffer.role()` instead of `buffer_id == COMMAND_BUFFER_ID`. +Before choosing an approach, it's worth asking: what actually makes the command buffer special? Here's every special behavior in the current code, and what property would express it: -**Pros:** Simple, explicit, easy to reason about. The core knows all possible roles at compile time. -**Cons:** Every new kind of buffer requires a new enum variant. Roles are mutually exclusive. +| Current behavior | Where | Property | +|---|---|---| +| Always in Insert mode | `core.rs:69` — `set_mode(Mode::Insert)` at creation | **Remove this.** Command buffer should support Normal mode like any other buffer (Kakoune-style). You should be able to hjkl around and edit your command. | +| Enter submits instead of inserting `\n` | `configuration.rs:49` — `(Mode::Insert, true) => Command(Execute)` | Submit behavior lives in the input mapping layer (Configuration / future DSL), keyed off buffer properties. Not inherently tied to single-line — a multi-line command buffer could submit on e.g. Ctrl+Enter or a keybinding. | +| Escape returns to previous buffer | `configuration.rs:58` — `(_, true) => FocusPreviousBuffer` | `ephemeral: true` (Escape on ephemeral buffer = defocus) | +| Tab triggers completion | `configuration.rs:62` — `(Mode::Insert, true) => Command(Tab)` | Tab behavior is context-dependent, lives in input mapping | +| Cleared on focus | `core.rs:254` — clears when `target == COMMAND_BUFFER_ID` | `ephemeral: true` | +| Cleared on defocus | `core.rs:265` — clears when leaving command buffer | `ephemeral: true` | +| Doesn't replace main display | `core.rs:115` — `main_display_buffer()` skips it | `listed: false` (unlisted buffers don't claim the main editing area) | +| Not in tab bar | implicit | `listed: false` | -### Option B: Capability flags / properties (Emacs-like) +Almost every behavior decomposes into generic properties (`ephemeral`, `listed`). But there is one irreducible property: *this buffer's contents are commands to be interpreted by the editor's command system*. That's not the same as "ephemeral" — a finder buffer is ephemeral too, but submitting it opens a file rather than executing a command. The core needs to know which buffer to read command text from when `CommandAction::Execute` fires, and that's a property of the buffer itself: `command: bool`. + +### What Vim Gets Wrong Here + +In Vim, the command line (`:` prompt) is a separate input context with its own limited editing model. You can't use Normal mode motions to edit your command — only basic readline-style bindings. Vim's `q:` cmdwin partially addresses this by opening an actual buffer, but it's a separate workflow. This is an unnecessary inconsistency. + +In pane-editor, the command buffer is just a buffer. It starts in Insert mode (because you're typing a command), but you can Escape to Normal mode and use the full editing vocabulary — hjkl, word motions, etc. — then `i` back to Insert to keep typing. The same keybindings, the same muscle memory, everywhere. + +## Design: Properties-Only (Emacs-like) + +Drop `BufferKind` entirely. Buffer behavior is determined by composable properties on `TextBuffer`. The properties are minimal — they capture what the *core* needs to know to handle buffer lifecycle. Everything else (keybindings, submit behavior, rendering position) lives in other layers. + +### Three Layers of "Buffer Behavior" + +It's important to separate what lives where: + +1. **Buffer properties** (on `TextBuffer`) — intrinsic buffer state that the core needs for lifecycle management: Is it listed? Is it ephemeral? Is it read-only? Does it have a backing file? + +2. **Input mapping** (in `Configuration` / future DSL) — what keystrokes do in a given buffer context. Enter submits vs inserts newline. Tab completes vs inserts tab. Escape defocuses vs transitions to Normal mode. This is user-configurable and can vary per buffer properties, per mode, per anything. + +3. **Presentation** (in pane layout / rendering) — where and how a buffer is displayed. Bottom command line vs centered floating palette vs side panel. This is orthogonal to both buffer properties and input mapping. + +This separation is what makes it possible to have the same command buffer render as a vim-style bottom line OR a VS Code-style command palette — the buffer doesn't change, only the pane layout does. + +### Buffer Properties ```rust struct BufferProperties { - file_backed: bool, // has a backing file - writable: bool, // can be edited - single_line: bool, // constrained to one line - ephemeral: bool, // cleared on defocus, no save semantics - listed: bool, // appears in buffer list / tab bar - on_submit: Option<...>, // callback when Enter is pressed + /// Buffer appears in tab bar / buffer list and claims the main editing area. + listed: bool, + + /// Buffer is cleared on focus and defocus. No unsaved-changes warning. + ephemeral: bool, + + /// Buffer contents cannot be modified. Mode::Insert doesn't apply — + /// `TransitionToMode(Mode::Insert)` is a no-op on a read-only buffer. + read_only: bool, + + /// Buffer contents are interpreted as editor commands on submit. + /// The core reads this buffer's text when CommandAction::Execute fires. + command: bool, } ``` -Buffer "type" is emergent from the combination of properties. A command buffer is `{ single_line: true, ephemeral: true, on_submit: Some(execute_command), listed: false }`. +Four properties. Note what's *not* here: -**Pros:** Composable, open-ended. New buffer behaviors don't require new enum variants. Properties can be changed at runtime. -**Cons:** Harder to reason about -- you need to check multiple flags. Possible to create nonsensical combinations. More complex. +- **No `single_line`.** Whether a buffer is constrained to one line is a rendering/UI concern, not an intrinsic buffer property. A command buffer could be single-line in a vim-style bottom bar and multi-line in a command palette. The buffer itself doesn't care. +- **No `on_submit` callback.** The `command` flag tells the core *where submission goes* (the command system). The input mapping layer decides *when* submission happens (Enter, Ctrl+Enter, whatever). Other buffer types (finder, prompt) would have their own semantic flags and their own submit routing. +- **No mode override.** The command buffer supports Normal mode just like any other buffer. It starts in Insert mode because that's natural, but you can Escape to Normal, edit with motions, and `i` back. -### Option C: Hybrid (recommended starting point) +### Constructing Buffers by Role -A small `BufferKind` enum for the core categories the editor fundamentally understands, plus property flags for the orthogonal behavioral dimensions: +Convenience constructors express common configurations: ```rust -/// What kind of content this buffer holds. Determines core editor behavior. -enum BufferKind { - Document, // file or scratch text editing - Command, // command-line input - Info, // read-only informational (help, about, etc.) -} +impl BufferProperties { + /// A normal file-editing buffer. + fn document() -> Self { + BufferProperties { listed: true, ephemeral: false, read_only: false, command: false } + } -/// Behavioral properties orthogonal to kind. -struct BufferProperties { - listed: bool, // appears in tab bar / buffer list - ephemeral: bool, // no unsaved-changes warning - single_line: bool, // constrain to one line of input - // ... extend as needed + /// A command-line input buffer (the `:` prompt). + fn command() -> Self { + BufferProperties { listed: false, ephemeral: true, read_only: false, command: true } + } + + /// A read-only informational buffer (help text, about, etc.) + fn info() -> Self { + BufferProperties { listed: false, ephemeral: false, read_only: true, command: false } + } } ``` -This gives you the benefits of explicit categorization where it matters (the core needs to know "is this a command buffer?" to handle Enter/Escape/focus semantics) while keeping orthogonal properties composable. +A "finder" buffer is `{ listed: false, ephemeral: true, read_only: false, command: false }` — ephemeral like a command buffer, but its submit action is "open the selected file" (handled by finder-specific logic, not the command system). A "scratch" buffer is `document()` with no backing file. + +### How the Core Uses Properties + +The core never asks "is this the command buffer?" — it asks about capabilities: + +```rust +// Instead of: if target == COMMAND_BUFFER_ID { self.clear_command_buffer(); } +if buffer.properties.ephemeral { + buffer.clear(); +} + +// Instead of: if self.active_buffer == COMMAND_BUFFER_ID { return previous } +if !active_buffer.properties.listed { + // unlisted buffer doesn't claim the main display area + return self.previous_buffer(); +} + +// Instead of: force Insert mode on command buffer +// Nothing. The buffer starts in whatever mode it starts in. Mode transitions +// are handled normally. read_only buffers reject TransitionToMode(Insert). +``` + +### How Configuration Uses Properties + +`Configuration::get_editor_action` receives `&BufferProperties` instead of a `BufferId`: + +```rust +fn get_editor_action(&self, input: Input, props: &BufferProperties, mode: Mode, ...) { + match input { + // Escape in an ephemeral buffer defocuses. In a non-ephemeral buffer, + // transitions to Normal (from Insert) or is a no-op (already Normal). + Input::Escape if props.ephemeral => FocusPreviousBuffer, + Input::Escape => match mode { + Mode::Insert => TransitionToMode(Mode::Normal), + Mode::Normal => None, + }, + + // Enter in Insert mode in a command buffer submits to the command system. + // In a non-command buffer, inserts a newline. The future DSL will allow + // full customization of this per buffer property. + Input::Newline => match (mode, props.command) { + (Mode::Insert, true) => Command(CommandAction::Execute), + (Mode::Insert, false) => InsertCharacter('\n'), + _ => None, + }, + + // Normal mode works everywhere — hjkl, i, etc. + // The same bindings apply in a command buffer as in a document buffer. + Input::Character(ch) => match mode { + Mode::Insert if !props.read_only => InsertCharacter(ch), + Mode::Normal if ch == 'i' && !props.read_only => TransitionToMode(Mode::Insert), + Mode::Normal if ch == ':' => FocusCommandBuffer, + // hjkl etc. — same in all buffers + // ... + }, + // ... + } +} +``` + +Notice: `is_command` (the identity check) disappears. The configuration checks `props.command`, `props.ephemeral`, and `props.read_only` — meaningful properties, not magic IDs. The same Normal mode keybindings work in every buffer. + +### Mode and read_only Interaction + +`Mode::Insert` simply doesn't apply to a read-only buffer: +- `TransitionToMode(Mode::Insert)` is a no-op (or never generated — Configuration checks `read_only` before emitting it) +- The buffer is always effectively in Normal mode +- This covers help buffers, about screens, etc. naturally + +### What About the Future DSL? + +All of the hardcoded `match` arms in Configuration are temporary. The future scripting/DSL layer will allow users to define arbitrary input mappings per buffer property, per mode, per any predicate. The point of `BufferProperties` is that it provides stable, meaningful predicates for those mappings to key off of — not to encode behavior directly. ## What Changes -Regardless of which option, the refactor involves: +1. **Add `BufferProperties` to `TextBuffer`.** Four fields: `listed`, `ephemeral`, `read_only`, `command`. Plus convenience constructors `document()`, `command()`, `info()`. -1. **Remove `COMMAND_BUFFER_ID` constant.** Buffer identity no longer implies role. +2. **Remove `COMMAND_BUFFER_ID` constant.** Buffer identity no longer implies role. -2. **Add role/kind/properties to `TextBuffer`.** The buffer itself knows what it is. +3. **Remove forced `set_mode(Mode::Insert)` on command buffer.** The command buffer starts in Insert mode naturally (the `FocusBuffer` action could transition to Insert, or it just stays in whatever mode — the user can switch freely). -3. **Replace identity checks with property checks.** `id == COMMAND_BUFFER_ID` becomes `buffer.is_command()` or `buffer.kind() == BufferKind::Command`. +4. **Replace identity checks with property checks in `EditorCore`:** + - `main_display_buffer()` checks `!listed` instead of `== COMMAND_BUFFER_ID` + - `FocusBuffer` clears buffer if `ephemeral` instead of `== COMMAND_BUFFER_ID` + - `FocusPreviousBuffer` clears buffer if `ephemeral` + - `command_buffer()` / `command_buffer_is_active()` become property-based queries or go away entirely -4. **Find command buffer(s) by query, not by ID.** `EditorCore` could cache the active command buffer ID, or search: `self.buffers.values().find(|b| b.is_command())`. +5. **Update `Configuration`:** + - Receives `&BufferProperties` instead of `BufferId` + - Checks `props.command`, `props.ephemeral`, `props.read_only` instead of `is_command` + - No longer imports `COMMAND_BUFFER_ID` + - Normal mode keybindings work uniformly across all buffers -5. **Generalize focus semantics.** The "clear on focus, restore previous buffer on defocus" behavior currently hardcoded for the command buffer becomes driven by buffer properties (e.g., `ephemeral` buffers always clear and restore). - -6. **`Configuration` stops importing `COMMAND_BUFFER_ID`.** Input mapping checks buffer properties instead: `if buffer.is_command()` rather than `if active_buffer_id == COMMAND_BUFFER_ID`. +6. **Core tracks command buffer by `Option`** rather than a constant. Set when a command buffer is created/focused, cleared when it's destroyed. ## Open Questions -- Should `BufferKind` be extensible (e.g., plugins can register new kinds)? Probably not yet -- start simple. -- Should the command buffer be created lazily (only when `:` is pressed) or eagerly at startup? Currently eager. Lazy creation would mean the command buffer truly is "just another buffer" that gets created and destroyed on demand. -- How does this interact with the `Mode` system? Currently the command buffer is always in Insert mode. Should `BufferKind::Command` imply Insert mode, or should that remain a separate property? -- Should `BufferKind` affect rendering, or should rendering be driven entirely by pane layout position? (Currently the command pane is rendered based on layout position, which is good separation.) +- **Lazy vs eager creation.** Should the command buffer be created lazily (only when `:` is pressed) or eagerly at startup? Currently eager. Lazy creation means the command buffer is truly "just another buffer" that gets created and destroyed on demand, but adds complexity to the `:` keybinding path. +- **Presentation layer.** Rendering is currently driven by pane layout position (the command pane is always at the bottom). `BufferProperties` should not dictate rendering — the same `ephemeral` buffer could render as a bottom bar or a floating palette depending on pane layout configuration. Is the current pane layout system flexible enough for this, or does it need extension? +- **Label / prompt prefix.** The `:` prefix in the command line is a rendering concern. Should there be a `label: Option` on the buffer or on the pane layout entry? Probably the latter (presentation, not buffer state). +- **Submit semantics.** `command: true` tells the core where submission goes (the command system). But what about non-command buffers that also have submit behavior (finder, prompt)? Each would need its own flag, or there could be a more general `submit_target: Option` enum. For now `command: bool` is sufficient — generalize when a second submit target actually appears. +- **History.** Vim's command line has history (up/down to cycle previous commands). If the command buffer is ephemeral (cleared on focus), history would need to live outside the buffer — in the command system. This is probably the right place for it anyway.