feat: add bottom_buffer_fraction config for prompt positioning

- adds bottom_buffer_fraction to prompt config (default 1.0, disabled)
- implements ensure_bottom_buffer() to scroll terminal when needed
- integrates into both R mainloop and standalone modes
- clamps values to 0.0, 1.0 range via builder pattern
- adds 4 tests for config parsing and defaults
- updates JSON schema and snapshots

fraction values: 0.0=pinned top, 0.5=upper half, 1.0=disabled (default)

Author: brancengregory

artifacts/arf.schema.json

@@ -108,6 +108,7 @@
     "prompt": {
       "$ref": "#/$defs/PromptConfig",
       "default": {
+        "bottom_buffer_fraction": 1.0,
         "continuation": "+  ",
         "format": "{status}R {version}> ",
         "indicators": {
@@ -1705,6 +1706,12 @@
       "description": "Prompt configuration.",
       "type": "object",
       "properties": {
+        "bottom_buffer_fraction": {
+          "description": "Fraction of terminal height to reserve as bottom buffer.\n\nThis keeps the prompt away from the bottom of the terminal by scrolling\nup when the cursor would go below this fraction of the terminal height.\n\n- 0.0: Prompt stays at top of terminal\n- 0.5: Prompt stays in upper half (reserve bottom 50%)\n- 1.0: No buffer, prompt at bottom (default, current behavior)\n\nValues outside [0.0, 1.0] are clamped to this range.",
+          "type": "number",
+          "format": "float",
+          "default": 1.0
+        },
         "continuation": {
           "description": "Continuation prompt for multiline input.",
           "type": "string",

crates/arf-console/src/config/mod.rs

@@ -986,4 +986,40 @@ auto_match = false
         // Restore permissions so tempdir cleanup succeeds
         std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
     }
+
+    #[test]
+    fn test_default_bottom_buffer_fraction() {
+        let config = Config::default();
+        assert_eq!(config.prompt.bottom_buffer_fraction, 1.0);
+    }
+
+    #[test]
+    fn test_parse_bottom_buffer_fraction() {
+        let toml_str = r#"
+[prompt]
+bottom_buffer_fraction = 0.5
+"#;
+        let config: Config = toml::from_str(toml_str).unwrap();
+        assert_eq!(config.prompt.bottom_buffer_fraction, 0.5);
+    }
+
+    #[test]
+    fn test_parse_bottom_buffer_fraction_top() {
+        let toml_str = r#"
+[prompt]
+bottom_buffer_fraction = 0.0
+"#;
+        let config: Config = toml::from_str(toml_str).unwrap();
+        assert_eq!(config.prompt.bottom_buffer_fraction, 0.0);
+    }
+
+    #[test]
+    fn test_parse_bottom_buffer_fraction_disabled() {
+        let toml_str = r#"
+[prompt]
+bottom_buffer_fraction = 1.0
+"#;
+        let config: Config = toml::from_str(toml_str).unwrap();
+        assert_eq!(config.prompt.bottom_buffer_fraction, 1.0);
+    }
 }

crates/arf-console/src/config/prompt.rs

@@ -22,6 +22,22 @@ pub struct PromptConfig {
     pub status: StatusConfig,
     /// Vi mode indicator configuration.
     pub vi: ViConfig,
+    /// Fraction of terminal height to reserve as bottom buffer.
+    ///
+    /// This keeps the prompt away from the bottom of the terminal by scrolling
+    /// up when the cursor would go below this fraction of the terminal height.
+    ///
+    /// - 0.0: Prompt stays at top of terminal
+    /// - 0.5: Prompt stays in upper half (reserve bottom 50%)
+    /// - 1.0: No buffer, prompt at bottom (default, current behavior)
+    ///
+    /// Values outside [0.0, 1.0] are clamped to this range.
+    #[serde(default = "default_bottom_buffer_fraction")]
+    pub bottom_buffer_fraction: f32,
+}
+
+fn default_bottom_buffer_fraction() -> f32 {
+    1.0
 }
 
 impl Default for PromptConfig {
@@ -34,6 +50,7 @@ impl Default for PromptConfig {
             indicators: Indicators::default(),
             status: StatusConfig::default(),
             vi: ViConfig::default(),
+            bottom_buffer_fraction: default_bottom_buffer_fraction(),
         }
     }
 }

crates/arf-console/src/config/snapshots/arf__config__tests__schema_tests__config_schema.snap

@@ -112,6 +112,7 @@ expression: schema
     "prompt": {
       "$ref": "#/$defs/PromptConfig",
       "default": {
+        "bottom_buffer_fraction": 1.0,
         "continuation": "+  ",
         "format": "{status}R {version}> ",
         "indicators": {
@@ -1709,6 +1710,12 @@ expression: schema
       "description": "Prompt configuration.",
       "type": "object",
       "properties": {
+        "bottom_buffer_fraction": {
+          "description": "Fraction of terminal height to reserve as bottom buffer.\n\nThis keeps the prompt away from the bottom of the terminal by scrolling\nup when the cursor would go below this fraction of the terminal height.\n\n- 0.0: Prompt stays at top of terminal\n- 0.5: Prompt stays in upper half (reserve bottom 50%)\n- 1.0: No buffer, prompt at bottom (default, current behavior)\n\nValues outside [0.0, 1.0] are clamped to this range.",
+          "type": "number",
+          "format": "float",
+          "default": 1.0
+        },
         "continuation": {
           "description": "Continuation prompt for multiline input.",
           "type": "string",

crates/arf-console/src/config/snapshots/arf__config__tests__schema_tests__default_config.snap

@@ -30,6 +30,7 @@ format = "{status}R {version}> "
 continuation = "+  "
 shell_format = "[{shell}] $ "
 mode_indicator = "prefix"
+bottom_buffer_fraction = 1.0
 
 [prompt.indicators]
 reprex = "[reprex] "

crates/arf-console/src/repl/mod.rs

@@ -20,7 +20,7 @@ use crate::highlighter::{CombinedHighlighter, MetaCommandHighlighter};
 use crate::history::FuzzyHistory;
 use anyhow::Result;
 use crossterm::{
-    ExecutableCommand,
+    ExecutableCommand, cursor,
     style::Stylize,
     terminal::{self, ClearType},
 };
@@ -32,6 +32,7 @@ use reedline::{
 };
 use std::cell::RefCell;
 use std::io;
+use std::io::Write;
 use std::sync::atomic::{AtomicU16, Ordering};
 
 use crate::editor::keybindings::{
@@ -102,6 +103,48 @@ fn sync_r_width() {
     }
 }
 
+/// Ensure the prompt maintains a buffer from the bottom of the terminal.
+///
+/// When `fraction` is less than 1.0, this function scrolls the terminal up
+/// to ensure the prompt stays above the specified fraction of terminal height.
+/// For example, with fraction 0.5, the prompt will stay in the upper half.
+///
+/// - fraction = 0.0: Prompt stays at top of terminal  
+/// - fraction = 0.5: Prompt stays in upper half (reserve bottom 50%)
+/// - fraction = 1.0: No buffer, prompt at bottom (disabled)
+fn ensure_bottom_buffer(fraction: f32) {
+    // Disabled when fraction >= 1.0 or <= 0.0
+    if fraction >= 1.0 || fraction <= 0.0 {
+        return;
+    }
+
+    let Ok((_, cursor_row)) = cursor::position() else {
+        return;
+    };
+    let Ok((_, term_rows)) = terminal::size() else {
+        return;
+    };
+
+    // Calculate the target row based on fraction
+    // fraction 0.0 -> row 2 (leave small margin at top), fraction 0.5 -> middle, etc.
+    let min_top_margin = 2u16;
+    let target_row = (term_rows as f32 * fraction.clamp(0.0, 1.0)).max(min_top_margin as f32) as u16;
+
+    // If cursor is at or below the target row, we need to scroll up and move cursor
+    if cursor_row >= target_row {
+        let lines_to_scroll = cursor_row.saturating_sub(target_row) + 1;
+
+        // Scroll terminal up to create space, then move cursor to target row
+        let mut stdout = io::stdout();
+        for _ in 0..lines_to_scroll {
+            let _ = stdout.execute(terminal::ScrollUp(1));
+        }
+        // Move cursor to the target row (column 0)
+        let _ = stdout.execute(cursor::MoveTo(0, target_row));
+        let _ = stdout.flush();
+    }
+}
+
 /// Prefix for arf messages to distinguish them from R output.
 /// Uses R comment syntax so messages don't interfere with R code.
 pub(crate) const ARF_PREFIX: &str = "# [arf]";
@@ -408,6 +451,7 @@ impl Repl {
             self.config.prompt.vi.clone(),
             self.config.colors.prompt.vi.clone(),
         )
+        .bottom_buffer_fraction(self.config.prompt.bottom_buffer_fraction)
         .build();
 
         // Get history paths for :history commands
@@ -598,6 +642,9 @@ impl Repl {
         let mut dir_stack: Vec<std::path::PathBuf> = Vec::new();
 
         loop {
+            // Apply bottom buffer to keep prompt away from terminal bottom
+            ensure_bottom_buffer(self.config.prompt.bottom_buffer_fraction);
+
             match line_editor.read_line(&prompt) {
                 Ok(Signal::Success(line)) => {
                     let trimmed = line.trim();
@@ -879,6 +926,12 @@ fn read_console_callback(r_prompt: &str) -> Option<String> {
             // keeping graphics windows (plot(), help browser) responsive.
             arf_libr::process_r_events();
 
+            // Apply bottom buffer to keep prompt away from terminal bottom
+            // Only for command prompts, not continuation or menu prompts
+            if is_r_command_prompt(r_prompt) {
+                ensure_bottom_buffer(state.prompt_config.bottom_buffer_fraction());
+            }
+
             // Track whether we're in a non-standard prompt mode (menu selection, etc.)
             let is_menu_prompt = !is_r_command_prompt(r_prompt) && !r_prompt.starts_with('+');
 

crates/arf-console/src/repl/state.rs

@@ -170,6 +170,9 @@ pub struct PromptRuntimeConfig {
     vi_config: ViConfig,
     /// Vi mode colors for prompt indicator.
     vi_colors: ViColorConfig,
+    /// Bottom buffer fraction to keep prompt away from terminal bottom.
+    /// 0.0 = top of terminal, 0.5 = middle, 1.0 = no buffer (default).
+    bottom_buffer_fraction: f32,
 }
 
 impl PromptRuntimeConfig {
@@ -414,6 +417,16 @@ impl PromptRuntimeConfig {
         self.autoformat_enabled
     }
 
+    /// Get the bottom buffer fraction for keeping prompt away from terminal bottom.
+    ///
+    /// Returns a value between 0.0 and 1.0:
+    /// - 0.0: Prompt at top of terminal
+    /// - 0.5: Prompt in upper half (reserve bottom 50%)
+    /// - 1.0: No buffer, prompt at bottom (disabled/default)
+    pub fn bottom_buffer_fraction(&self) -> f32 {
+        self.bottom_buffer_fraction
+    }
+
     pub fn toggle_autoformat(&mut self) {
         self.autoformat_enabled = !self.autoformat_enabled;
     }
@@ -519,6 +532,7 @@ pub struct PromptRuntimeConfigBuilder {
     spinner_config: SpinnerConfig,
     vi_config: ViConfig,
     vi_colors: ViColorConfig,
+    bottom_buffer_fraction: f32,
 }
 
 impl PromptRuntimeConfigBuilder {
@@ -549,6 +563,7 @@ impl PromptRuntimeConfigBuilder {
             spinner_config: SpinnerConfig::default(),
             vi_config: ViConfig::default(),
             vi_colors: ViColorConfig::default(),
+            bottom_buffer_fraction: 1.0, // Disabled by default
         }
     }
 
@@ -616,6 +631,11 @@ impl PromptRuntimeConfigBuilder {
         self
     }
 
+    pub fn bottom_buffer_fraction(mut self, fraction: f32) -> Self {
+        self.bottom_buffer_fraction = fraction.clamp(0.0, 1.0);
+        self
+    }
+
     pub fn build(self) -> PromptRuntimeConfig {
         // Initialize spinner in arf-libr
         arf_libr::set_spinner_frames(&self.spinner_config.frames);
@@ -647,6 +667,7 @@ impl PromptRuntimeConfigBuilder {
             spinner_config: self.spinner_config,
             vi_config: self.vi_config,
             vi_colors: self.vi_colors,
+            bottom_buffer_fraction: self.bottom_buffer_fraction,
         }
     }
 }