codex/prs/bolinfest/study/PR-1695-study.md

DOs

• Keep app.rs lean: Drive the event loop and delegate event-specific handling to modules.

  // app.rs
  match event {
      TuiEvent::AttachImage { path, width, height, format_label } => {
          self.chat_widget.attach_image(path, width, height, format_label);
      }
      TuiEvent::Key(key) => self.chat_widget.handle_key_event(key),
      TuiEvent::Paste(s) => self.chat_widget.handle_paste(s),
      TuiEvent::Draw => self.redraw()?,
  }
  

• Generate rich events in the TUI layer: Map platform input to semantic TuiEvents before app.rs sees them.

  // tui.rs
  match crossterm_event {
      Event::Key(k) if is_ctrl_or_cmd_v(&k) => {
          if let Ok((path, info)) = paste_image_to_temp_png() {
              yield TuiEvent::AttachImage { path, width: info.width, height: info.height, format_label: info.encoded_format.label() };
          } else {
              yield TuiEvent::Key(k);
          }
      }
      Event::Paste(s) => yield TuiEvent::Paste(s),
      Event::Key(k) => yield TuiEvent::Key(k),
      Event::Resize(_, _) => yield TuiEvent::Draw,
      _ => {}
  }
  

• Handle cross-platform shortcuts: Don’t assume macOS Cmd maps to Control; accept Control, Super, or Meta for V.

  use crossterm::event::{KeyCode, KeyEvent, KeyEventKind, KeyModifiers};
  
  fn is_ctrl_or_cmd_v(k: &KeyEvent) -> bool {
      k.kind == KeyEventKind::Press
          && matches!(k.code, KeyCode::Char('v'))
          && (k.modifiers.contains(KeyModifiers::CONTROL)
              || k.modifiers.contains(KeyModifiers::SUPER)
              || k.modifiers.contains(KeyModifiers::META))
  }
  

• Model image formats with an enum, not strings: Add a label() to present user-friendly text.

  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
  enum EncodedImageFormat { Png }
  
  impl EncodedImageFormat {
      fn label(self) -> &'static str {
          match self { EncodedImageFormat::Png => "PNG" }
      }
  }
  

• Write clipboard images via tempfile and persist safely:

  use tempfile::NamedTempFile;
  
  let (png_bytes, info) = paste_image_as_png()?;
  let tmp = NamedTempFile::new()?;              // unique, race-free
  std::fs::write(tmp.path(), &png_bytes)?;
  let (_file, path) = tmp.keep()?;              // persist and get PathBuf
  

• Prefer small structs over tuples for clarity: Make stored state self-documenting.

  #[derive(Clone, Debug, PartialEq)]
  struct AttachedImage {
      placeholder: String,
      path: PathBuf,
  }
  

• Make image placeholders atomic UI elements and keep mappings in sync:

  // Insert atomic element so a single Backspace removes it.
  self.textarea.insert_element(&placeholder);
  self.attached_images.push(AttachedImage { placeholder, path });
  
  // On edit, keep only as many AttachedImage entries as visible placeholders.
  let visible = text_after.matches(&img.placeholder).count();
  

• Strip placeholders before submit; drain images separately:

  // composer.rs (on Enter)
  for img in &self.attached_images {
      text = text.replace(&img.placeholder, "");
  }
  text = text.trim().to_string();
  
  // chatwidget.rs
  let images = self.bottom_pane.take_recent_submission_images();
  self.submit_user_message(UserMessage { text, image_paths: images });
  

• Inline variables in logs and formats: Use modern capture in tracing/format! calls.

  tracing::info!("attach_image path={path:?} width={width} height={height} format={format_label}");
  let msg = format!("added {count} images from {source}");
  

• Use local imports and concise types; move imports to the module top:

  use std::path::PathBuf;           // at top of file
  // ...
  fn attach_image(&mut self, path: PathBuf, width: u32, height: u32, format_label: &str) { /* ... */ }
  

• Test user-visible behaviors thoroughly: Attach + submit, deletion at both ends, and duplicates.

  #[test]
  fn deleting_one_of_duplicate_image_placeholders_removes_matching_entry() {
      composer.attach_image(p1.clone(), 10, 5, "PNG");
      composer.handle_paste(" ".into());
      composer.attach_image(p2.clone(), 10, 5, "PNG");
      composer.textarea.set_cursor(end_of_first_placeholder);
      composer.handle_key_event(KeyEvent::new(KeyCode::Backspace, KeyModifiers::NONE));
      assert_eq!(1, composer.textarea.text().matches(&ph).count());
      assert_eq!(vec![p2], composer.take_recent_submission_images());
  }
  

• Treat @file-selected images as images (with fallback):

  if is_image_path(&sel_path) {
      if let Ok((w, h)) = image::image_dimensions(&sel_path) {
          self.attach_image(PathBuf::from(&sel_path), w, h, "PNG"); // or "JPEG"
          self.textarea.insert_str(" ");
      } else {
          self.insert_selected_path(&sel_path); // fallback
      }
  } else {
      self.insert_selected_path(&sel_path);
  }
  

DON’Ts

• Don’t put event logic in app.rs: Keep it for orchestration; push specifics into TUI/chat modules.

  // ❌ Heavy logic in app.rs
  if is_ctrl_or_cmd_v(&key) { do_clipboard_io_here(); }
  
  // ✅ Delegate
  TuiEvent::AttachImage { .. } => self.chat_widget.attach_image(...)
  

• Don’t assume Cmd==Control on macOS: Accept SUPER/META too; fall back gracefully.

  // ❌ Only CONTROL
  k.modifiers.contains(KeyModifiers::CONTROL)
  
  // ✅ Cross-platform
  k.modifiers.intersects(KeyModifiers::CONTROL | KeyModifiers::SUPER | KeyModifiers::META)
  

• Don’t write temp files with ad-hoc names in temp_dir: Avoid collisions and TOCTOU races.

  // ❌
  let mut p = std::env::temp_dir(); p.push("clipboard.png"); std::fs::write(p, &bytes)?;
  
  // ✅
  let tmp = tempfile::NamedTempFile::new()?;
  

• Don’t use ad-hoc strings for image format: Prefer a typed enum.

  // ❌
  struct PastedImageInfo { encoded_format_label: &'static str }
  
  // ✅
  struct PastedImageInfo { encoded_format: EncodedImageFormat }
  

• Don’t return meaningless booleans or keep dead code: Remove unused return values and placeholders.

  // ❌
  pub fn attach_image(&mut self, path: PathBuf, w: u32, h: u32, fmt: &str) -> bool { /* always true */ }
  
  // ✅
  pub fn attach_image(&mut self, path: PathBuf, w: u32, h: u32, fmt: &str) { /* ... */ }
  

• Don’t fully qualify common std types everywhere or import inside tests: Keep files tidy and readable.

  // ❌
  fn f(p: std::path::PathBuf) {}
  
  // ✅
  use std::path::PathBuf;
  fn f(p: PathBuf) {}
  

• Don’t let placeholders and image state drift: Always update mappings when text changes.

  // ❌ Forgetting to drop mapping when placeholder deleted.
  
  // ✅ Remove mapping when matching placeholder instance is removed.
  self.attached_images.remove(idx);
  

• Don’t log with positional/format-args noise: Use inline captures for clarity and consistency.

  // ❌
  tracing::info!("path: {:?}, width: {}, height: {}", path, width, height);
  
  // ✅
  tracing::info!("path={path:?} width={width} height={height}");