Skip to main content

glass_dev/tui/
mod.rs

1//! Decomposed full Glass Dev terminal application.
2
3mod command;
4mod file_view;
5mod projection;
6/// Rendering primitives and frame composition for the development TUI.
7pub mod render;
8mod snapshot;
9/// Public reducer state and surface-selection types for the development TUI.
10pub mod state;
11mod syntax;
12
13use crossterm::event::{
14    self, DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
15    EnableFocusChange, EnableMouseCapture, Event, KeyCode, KeyEventKind, KeyModifiers,
16};
17use crossterm::execute;
18use crossterm::terminal::{
19    Clear, ClearType, EnterAlternateScreen, LeaveAlternateScreen, disable_raw_mode, enable_raw_mode,
20};
21use glass_browser::browser::policy::PolicyPreset;
22use glass_browser::browser_workspace::{BrowserConnectionPhase, BrowserWorkspaceIntent};
23use glass_browser::cli::args::{
24    TuiLayout, TuiLiveBackend, TuiLiveFit, TuiLiveMode, TuiLiveQuality,
25};
26use glass_browser::presentation::{
27    BrowserFrame, CaptureScale, FrameDamage, FrameDropCounts, FrameEncoding,
28    PRESENTATION_CONTRACT_SCHEMA_VERSION, PixelSize, TargetResourceIdentity,
29};
30use glass_browser::terminal_graphics::{GraphicsMode, PaneArea, TerminalGraphics};
31use glass_browser::tui::live_view::{
32    VisualPath, decide_path, frame_fit, frame_interval_ms, pane_size, png_dimensions,
33};
34use glass_browser::tui::{HerdrEnvironment, HerdrEvent, HerdrFrame, HerdrGraphicsWorker};
35use ratatui::Terminal;
36use ratatui::backend::CrosstermBackend;
37use ratatui::layout::Rect;
38use std::io::{self, IsTerminal, Write};
39use std::path::Path;
40use std::time::{Duration, Instant};
41
42/// Public TUI state, selected surface, product mode, and responsive class.
43pub use state::{DevSurface, DevTuiState, ProductMode, ResponsiveClass};
44
45/// Visual settings used to select the live browser preview path.
46#[derive(Debug, Clone, Copy)]
47pub struct TuiVisualOptions {
48    /// Requested live-rendering mode.
49    pub mode: TuiLiveMode,
50    /// Preferred rendering backend.
51    pub backend: TuiLiveBackend,
52    /// Requested image quality.
53    pub quality: TuiLiveQuality,
54    /// Frame fit policy.
55    pub fit: TuiLiveFit,
56}
57
58const KITTY_CLEAR: &[u8] = b"\x1b_Ga=d,d=A\x1b\\";
59
60struct VisualRuntime {
61    path: VisualPath,
62    live: bool,
63    quality: TuiLiveQuality,
64    fit: TuiLiveFit,
65    herdr: Option<HerdrGraphicsWorker>,
66    kitty: Option<TerminalGraphics>,
67    kitty_generation: u64,
68    kitty_pane: Option<PaneArea>,
69    kitty_drawn: bool,
70}
71
72impl VisualRuntime {
73    fn new(
74        options: TuiVisualOptions,
75    ) -> Result<Self, glass_browser::terminal_graphics::GraphicsError> {
76        let herdr_available = HerdrEnvironment::from_process().is_some();
77        let path = decide_path(options.mode, options.backend, herdr_available);
78        let herdr = matches!(&path, VisualPath::Herdr)
79            .then(|| HerdrEnvironment::from_process().map(HerdrGraphicsWorker::spawn))
80            .flatten();
81        let kitty = if matches!(&path, VisualPath::Kitty) {
82            Some(Self::new_kitty_renderer()?)
83        } else {
84            None
85        };
86        let live = matches!(
87            &path,
88            VisualPath::Herdr | VisualPath::Kitty | VisualPath::Ansi
89        ) && matches!(options.mode, TuiLiveMode::On | TuiLiveMode::Auto);
90        Ok(Self {
91            path,
92            live,
93            quality: options.quality,
94            fit: options.fit,
95            herdr,
96            kitty,
97            kitty_generation: 0,
98            kitty_pane: None,
99            kitty_drawn: false,
100        })
101    }
102
103    fn new_kitty_renderer()
104    -> Result<TerminalGraphics, glass_browser::terminal_graphics::GraphicsError> {
105        let identity = TargetResourceIdentity::new("glass-tui", Some("kitty-live".into()))?;
106        TerminalGraphics::new(GraphicsMode::Kitty, identity)
107    }
108
109    fn request_live(&mut self, live: bool) -> Option<String> {
110        if !live {
111            self.live = false;
112            return None;
113        }
114        match &self.path {
115            VisualPath::Herdr if self.herdr.is_some() => {
116                self.live = true;
117                None
118            }
119            VisualPath::Kitty => {
120                self.live = true;
121                None
122            }
123            VisualPath::Ansi => {
124                self.live = true;
125                None
126            }
127            VisualPath::SemanticOnly { reason } => {
128                self.live = false;
129                Some(reason.clone())
130            }
131            VisualPath::Herdr => {
132                self.live = false;
133                Some("Herdr pane graphics are unavailable in this terminal".into())
134            }
135        }
136    }
137
138    fn sync_state(&self, state: &mut DevTuiState) {
139        state.browser_visual_live = self.live;
140        let browser = state.browser_workspace.state_mut();
141        if !self.live {
142            browser.presentation =
143                glass_browser::browser_workspace::BrowserPresentationPath::SemanticOnly;
144            browser.presentation_reason = match &self.path {
145                VisualPath::SemanticOnly { reason } => Some(reason.clone()),
146                _ => {
147                    Some("visual presentation is off; semantic inspection remains available".into())
148                }
149            };
150            return;
151        }
152        match self.path {
153            VisualPath::Herdr => {
154                browser.presentation =
155                    glass_browser::browser_workspace::BrowserPresentationPath::Herdr;
156                browser.presentation_reason =
157                    Some("waiting for the Herdr pane graphics stream".into());
158            }
159            VisualPath::Kitty => {
160                browser.presentation =
161                    glass_browser::browser_workspace::BrowserPresentationPath::Kitty;
162                browser.presentation_reason =
163                    Some("waiting for a Kitty terminal graphics frame".into());
164            }
165            VisualPath::Ansi => {
166                browser.presentation =
167                    glass_browser::browser_workspace::BrowserPresentationPath::Ansi;
168                browser.presentation_reason =
169                    Some("waiting for a bounded ANSI frame; semantic inspector stays live".into());
170            }
171            VisualPath::SemanticOnly { .. } => {}
172        }
173    }
174
175    fn poll_events(&self) -> Vec<HerdrEvent> {
176        let Some(herdr) = self.herdr.as_ref() else {
177            return Vec::new();
178        };
179        let mut events = Vec::new();
180        while let Some(event) = herdr.try_event() {
181            events.push(event);
182        }
183        events
184    }
185
186    fn submit_herdr(&self, png: Vec<u8>, columns: u16, rows: u16) -> bool {
187        let Some(herdr) = self.herdr.as_ref() else {
188            return false;
189        };
190        let (image_width, image_height) = png_dimensions(&png).unwrap_or((1, 1));
191        herdr.try_send(HerdrFrame {
192            png,
193            image_width,
194            image_height,
195            viewport_col: 0,
196            viewport_row: 3,
197            grid_cols: u32::from(columns),
198            grid_rows: u32::from(rows.saturating_sub(6).max(1)),
199        })
200    }
201
202    fn sync_kitty_area(
203        &mut self,
204        pane: Option<PaneArea>,
205        terminal: &mut TerminalGuard,
206    ) -> io::Result<()> {
207        if !matches!(self.path, VisualPath::Kitty) {
208            return Ok(());
209        }
210        if self.kitty_pane != pane && self.kitty_drawn {
211            terminal.write_bytes(KITTY_CLEAR)?;
212            self.kitty_drawn = false;
213        }
214        self.kitty_pane = pane;
215        Ok(())
216    }
217
218    fn submit_kitty(
219        &mut self,
220        png: &[u8],
221        pane: PaneArea,
222        browser_revision: u64,
223    ) -> Result<Vec<u8>, String> {
224        let (image_width, image_height) =
225            png_dimensions(png).ok_or_else(|| "screenshot payload was not a PNG".to_string())?;
226        let viewport = PixelSize::new(image_width, image_height);
227        viewport
228            .validate("screenshot")
229            .map_err(|error| error.to_string())?;
230
231        let reset = self
232            .kitty
233            .as_ref()
234            .is_none_or(|graphics| browser_revision < graphics.browser_revision());
235        if reset {
236            self.kitty = Some(Self::new_kitty_renderer().map_err(|error| error.to_string())?);
237            self.kitty_pane = Some(pane);
238            self.kitty_drawn = false;
239        }
240        let graphics = self
241            .kitty
242            .as_mut()
243            .ok_or_else(|| "Kitty renderer is unavailable".to_string())?;
244        graphics
245            .resize(
246                pane,
247                viewport,
248                viewport,
249                CaptureScale::FULL,
250                browser_revision,
251            )
252            .map_err(|error| error.to_string())?;
253        self.kitty_generation = self.kitty_generation.saturating_add(1).max(1);
254        let frame = BrowserFrame {
255            schema_version: PRESENTATION_CONTRACT_SCHEMA_VERSION,
256            generation: self.kitty_generation,
257            identity: TargetResourceIdentity::new("glass-tui", Some("kitty-live".into()))
258                .map_err(|error| error.to_string())?,
259            acquired_at_ms: self.kitty_generation,
260            viewport,
261            content: viewport,
262            capture_scale: CaptureScale::FULL,
263            encoding: FrameEncoding::Png,
264            keyframe: true,
265            damage: FrameDamage::Full,
266            browser_revision,
267            geometry_revision: graphics.geometry_revision(),
268            dropped: FrameDropCounts::default(),
269        };
270        graphics
271            .submit(frame, png)
272            .map_err(|error| error.to_string())?;
273        graphics
274            .present_pending()
275            .map_err(|error| error.to_string())?;
276        let rendered = graphics
277            .render_current("")
278            .map_err(|error| error.to_string())?;
279        if rendered.mode != GraphicsMode::Kitty {
280            return Err("Kitty renderer returned a semantic frame".into());
281        }
282        Ok(rendered.bytes)
283    }
284
285    fn mark_kitty_drawn(&mut self) {
286        self.kitty_drawn = true;
287    }
288
289    fn shutdown(&mut self) -> Vec<u8> {
290        self.kitty
291            .as_mut()
292            .map(TerminalGraphics::shutdown)
293            .unwrap_or_default()
294    }
295}
296
297/// Run the interactive Glass Dev TUI until the user exits.
298///
299/// Requires interactive stdin and stdout. `root` is the project workspace;
300/// `layout` selects the desktop/phone composition and `visual_options`
301/// selects the optional browser preview path. Non-interactive callers should
302pub fn run(
303    root: impl AsRef<Path>,
304    layout: TuiLayout,
305    visual_options: TuiVisualOptions,
306    yolo_mode: bool,
307    policy_preset: PolicyPreset,
308) -> Result<(), Box<dyn std::error::Error>> {
309    if !io::stdin().is_terminal() || !io::stdout().is_terminal() {
310        return Err("Glass Dev TUI requires an interactive terminal; use a CLI subcommand or --mcp for non-interactive use".into());
311    }
312    let mut state = DevTuiState::open_for_tui_with_policy(root, layout, yolo_mode, policy_preset)?;
313    let mut visual = VisualRuntime::new(visual_options)?;
314    visual.sync_state(&mut state);
315    let mut worker = snapshot::SnapshotWorker::spawn(&state);
316    worker.request_refresh();
317    let mut guard = TerminalGuard::enter()?;
318    let mut last_refresh = Instant::now();
319    let mut last_visual = Instant::now();
320    let mut last_render = Instant::now() - Duration::from_millis(33);
321    let mut previous_overlay_mask = 0_u16;
322    loop {
323        let size = guard.terminal.size()?;
324        let overlay_mask = terminal_overlay_mask(&state);
325        if overlay_mask != previous_overlay_mask {
326            guard
327                .terminal
328                .resize(Rect::new(0, 0, size.width, size.height))?;
329            previous_overlay_mask = overlay_mask;
330        }
331        state.set_terminal_size(size.width, size.height);
332        let kitty_area =
333            render::browser_visual_area(&state, Rect::new(0, 0, size.width, size.height))
334                .map(|area| PaneArea::new(area.x, area.y, area.width, area.height));
335        visual.sync_kitty_area(kitty_area, &mut guard)?;
336        if last_render.elapsed() >= Duration::from_millis(33) {
337            guard.terminal.draw(|frame| render::render(frame, &state))?;
338            last_render = Instant::now();
339        }
340        if state.quit {
341            break;
342        }
343        if event::poll(Duration::from_millis(50))? {
344            match event::read()? {
345                Event::Key(key) if key.kind == KeyEventKind::Press => {
346                    // The quit modal is the strongest user-facing guard.
347                    if state.quit_confirmation {
348                        match key.code {
349                            KeyCode::Enter | KeyCode::Char('y' | 'Y') => state.confirm_quit(),
350                            KeyCode::Esc | KeyCode::Char('n' | 'N') => state.cancel_quit(),
351                            _ => {}
352                        }
353                    } else if state.editor_exit_prompt.is_some() {
354                        state.handle_editor_exit_key(key.code);
355                    } else if key.code == KeyCode::Char('c')
356                        && key.modifiers.contains(KeyModifiers::CONTROL)
357                        && state.code_edit_mode
358                    {
359                        state.request_editor_exit();
360                    } else if key.code == KeyCode::Char('c')
361                        && key.modifiers.contains(KeyModifiers::CONTROL)
362                    {
363                        state.request_quit();
364                    } else if state.help_open {
365                        match key.code {
366                            KeyCode::Esc | KeyCode::Char('?') => state.toggle_help(),
367                            KeyCode::Up | KeyCode::Char('k') => state.scroll_help(-1),
368                            KeyCode::Down | KeyCode::Char('j') => state.scroll_help(1),
369                            KeyCode::PageUp => state.scroll_help(-8),
370                            KeyCode::PageDown => state.scroll_help(8),
371                            KeyCode::Home => state.help_scroll = 0,
372                            _ => {}
373                        }
374                    } else if key.code == KeyCode::Char('?')
375                        && !state.composer_mode
376                        && !state.command_mode
377                        && !state.code_edit_mode
378                    {
379                        state.toggle_help();
380                    } else if state.menu_open {
381                        match key.code {
382                            KeyCode::Esc => state.close_menu(),
383                            KeyCode::Enter => {
384                                let was_live = state.browser_visual_live;
385                                let visual_requested = state.surface == DevSurface::App
386                                    && state
387                                        .surface_actions()
388                                        .get(state.menu_selection)
389                                        .is_some_and(|action| action.command == "browser view");
390                                state.run_menu_action();
391                                if visual_requested && state.browser_visual_live != was_live {
392                                    let live = state.browser_visual_live;
393                                    if let Some(reason) = visual.request_live(live) {
394                                        state.browser_visual_live = false;
395                                        state.status = format!("Live view unavailable · {reason}");
396                                    } else {
397                                        visual.sync_state(&mut state);
398                                        state.status = if live {
399                                            "Live view starting · screenshot worker will update the pane"
400                                                .into()
401                                        } else {
402                                            "Live view off · semantic inspection remains available"
403                                                .into()
404                                        };
405                                    }
406                                }
407                            }
408                            KeyCode::Up | KeyCode::Char('k') => state.move_menu_selection(-1),
409                            KeyCode::Down | KeyCode::Char('j') => state.move_menu_selection(1),
410                            _ => {}
411                        }
412                    } else if state.browser_target_picker && state.surface == DevSurface::App {
413                        match key.code {
414                            KeyCode::Esc => state.close_browser_target_picker(),
415                            KeyCode::Enter => state.select_browser_target(),
416                            KeyCode::Up | KeyCode::Char('k') => {
417                                state.move_browser_target_selection(-1)
418                            }
419                            KeyCode::Down | KeyCode::Char('j') => {
420                                state.move_browser_target_selection(1)
421                            }
422                            KeyCode::Backspace => state.browser_target_backspace(),
423                            KeyCode::Char('u') if key.modifiers.contains(KeyModifiers::CONTROL) => {
424                                state.clear_browser_target_query()
425                            }
426                            KeyCode::Char(character) => {
427                                state.insert_browser_target_query(character)
428                            }
429                            _ => {}
430                        }
431                    } else if state.browser_recovery.is_some() && state.surface == DevSurface::App {
432                        match key.code {
433                            KeyCode::Esc => {
434                                state.browser_recovery = None;
435                                state.pending_browser_navigation = None;
436                                state.status = "Recovery dismissed".into();
437                            }
438                            KeyCode::Char('1') => state.accept_browser_recovery(0, &mut worker),
439                            KeyCode::Char('2') => state.accept_browser_recovery(1, &mut worker),
440                            KeyCode::Char('3')
441                                if state
442                                    .browser_recovery
443                                    .as_ref()
444                                    .is_some_and(|offer| offer.compatible_endpoint) =>
445                            {
446                                state.accept_browser_recovery(2, &mut worker)
447                            }
448                            _ => {}
449                        }
450                    } else if state.git_diff_open && state.surface == DevSurface::Git {
451                        match key.code {
452                            KeyCode::Esc => state.close_git_diff(),
453                            KeyCode::Up | KeyCode::Char('k') => state.scroll_surface(-1),
454                            KeyCode::Down | KeyCode::Char('j') => state.scroll_surface(1),
455                            KeyCode::Enter | KeyCode::Char('d') => {
456                                state.queue_git_diff(&mut worker)
457                            }
458                            KeyCode::PageUp => state.scroll_surface(-10),
459                            KeyCode::PageDown => state.scroll_surface(10),
460                            KeyCode::Home => state.scroll_home(),
461                            KeyCode::End => state.scroll_end(),
462                            _ => {}
463                        }
464                    } else if state.pending_agent_approval.is_some() {
465                        match key.code {
466                            KeyCode::Enter | KeyCode::Char('y' | 'Y') => {
467                                state.resolve_agent_approval(true, &mut worker);
468                            }
469                            KeyCode::Esc | KeyCode::Char('n' | 'N') => {
470                                state.resolve_agent_approval(false, &mut worker);
471                            }
472                            _ => {}
473                        }
474                    } else if state.pending_confirmation.is_some() {
475                        match key.code {
476                            KeyCode::Enter | KeyCode::Char('y' | 'Y') => {
477                                state.approve_confirmation_async(&mut worker);
478                            }
479                            KeyCode::Esc | KeyCode::Char('n' | 'N') => {
480                                state.deny_confirmation();
481                            }
482                            _ => {}
483                        }
484                    } else if state.code_edit_mode {
485                        match key.code {
486                            KeyCode::Esc => state.request_editor_exit(),
487                            _ => state.edit_code_key(key.code, key.modifiers),
488                        }
489                    } else if state.composer_mode {
490                        match (key.code, key.modifiers) {
491                            (KeyCode::Esc, _) => state.close_composer(),
492                            (KeyCode::Enter, _) => state.submit_composer(&mut worker),
493                            (KeyCode::Backspace, _) => state.composer_backspace(),
494                            (KeyCode::Char('u'), value)
495                                if value.contains(KeyModifiers::CONTROL) =>
496                            {
497                                state.composer_input.clear();
498                                state.composer_cursor = 0;
499                            }
500                            (KeyCode::Char('a'), value)
501                                if value.contains(KeyModifiers::CONTROL) =>
502                            {
503                                state.composer_cursor = 0;
504                            }
505                            (KeyCode::Char('e'), value)
506                                if value.contains(KeyModifiers::CONTROL) =>
507                            {
508                                state.composer_cursor = state.composer_input.len();
509                            }
510                            (KeyCode::Char('w'), value)
511                                if value.contains(KeyModifiers::CONTROL) =>
512                            {
513                                state.delete_composer_word();
514                            }
515                            (KeyCode::Char('x'), value)
516                                if value.contains(KeyModifiers::CONTROL) =>
517                            {
518                                state.abort_selected_agent(&mut worker);
519                            }
520                            (KeyCode::Char('d'), value)
521                                if value.contains(KeyModifiers::CONTROL) =>
522                            {
523                                state.toggle_composer_steer();
524                            }
525                            (KeyCode::Left, _) => state.move_composer_cursor(false),
526                            (KeyCode::Right, _) => state.move_composer_cursor(true),
527                            (KeyCode::Home, _) => state.composer_cursor = 0,
528                            (KeyCode::End, _) => {
529                                state.composer_cursor = state.composer_input.len();
530                            }
531                            (KeyCode::Char(character), _) => {
532                                state.insert_composer_text(&character.to_string());
533                            }
534                            _ => {}
535                        }
536                    } else if state.command_mode {
537                        match (key.code, key.modifiers) {
538                            (KeyCode::Esc, _) => state.close_palette(),
539                            (KeyCode::Enter, _) => {
540                                let was_live = state.browser_visual_live;
541                                state.submit_palette(&mut worker);
542                                if state.browser_visual_live != was_live {
543                                    let live = state.browser_visual_live;
544                                    if let Some(reason) = visual.request_live(live) {
545                                        state.browser_visual_live = false;
546                                        state.status = format!("Live view unavailable · {reason}");
547                                    } else {
548                                        visual.sync_state(&mut state);
549                                        state.status = if live {
550                                            "Live view starting · screenshot worker will update the pane"
551                                                .into()
552                                        } else {
553                                            "Live view off · semantic inspection remains available"
554                                                .into()
555                                        };
556                                    }
557                                }
558                            }
559                            (KeyCode::Backspace, _) => state.palette_backspace(),
560                            (KeyCode::Char('u'), value)
561                                if value.contains(KeyModifiers::CONTROL) =>
562                            {
563                                state.command_input.clear();
564                                state.command_cursor = 0;
565                                state.palette_error = None;
566                                state.palette_scroll = 0;
567                                state.palette_selection = 0;
568                            }
569                            (KeyCode::Char('p'), value)
570                                if value.contains(KeyModifiers::CONTROL) =>
571                            {
572                                state.navigate_palette_history(true);
573                            }
574                            (KeyCode::Char('n'), value)
575                                if value.contains(KeyModifiers::CONTROL) =>
576                            {
577                                state.navigate_palette_history(false);
578                            }
579                            (KeyCode::Left, _) => state.move_palette_cursor(false),
580                            (KeyCode::Right, _) => state.move_palette_cursor(true),
581                            (KeyCode::Up, _) | (KeyCode::Char('k'), _) => {
582                                state.move_palette_selection(-1)
583                            }
584                            (KeyCode::Down, _) | (KeyCode::Char('j'), _) => {
585                                state.move_palette_selection(1)
586                            }
587                            (KeyCode::PageUp, _) => state.scroll_palette(-1),
588                            (KeyCode::PageDown, _) => state.scroll_palette(1),
589                            (KeyCode::Tab, _) if state.command_input.trim().is_empty() => {
590                                state.move_palette_selection(1)
591                            }
592                            (KeyCode::Tab, _) => state.complete_palette(),
593                            (KeyCode::Char(character), _) => state.insert_palette_char(character),
594                            _ => {}
595                        }
596                    } else {
597                        match (key.code, key.modifiers) {
598                            (KeyCode::Esc, _) if state.running_tool_job.is_some() => {
599                                state.status =
600                                    "Background operation is bounded · Ctrl-C opens quit confirmation"
601                                        .into();
602                            }
603                            (KeyCode::Char('s'), _) if state.surface == DevSurface::Terminal => {
604                                state.request_detected_dev();
605                            }
606                            (KeyCode::Char('d'), _) if state.surface == DevSurface::Git => {
607                                state.queue_git_diff(&mut worker);
608                            }
609                            (KeyCode::Enter, _) if state.surface == DevSurface::Agent => {
610                                state.start_agent_interaction();
611                            }
612                            (KeyCode::Up | KeyCode::Char('k'), _)
613                                if state.surface == DevSurface::Git =>
614                            {
615                                state.move_git_selection(-1);
616                            }
617                            (KeyCode::Down | KeyCode::Char('j'), _)
618                                if state.surface == DevSurface::Git =>
619                            {
620                                state.move_git_selection(1);
621                            }
622                            (KeyCode::Enter, _) if state.surface == DevSurface::Git => {
623                                state.queue_git_diff(&mut worker);
624                            }
625                            (KeyCode::Enter, _) if state.surface == DevSurface::Code => {
626                                state.open_selected_file_for_edit();
627                            }
628                            (KeyCode::Char(']'), _) if state.surface == DevSurface::Agent => {
629                                state.cycle_agent_selection(1)
630                            }
631                            (KeyCode::Char('['), _) if state.surface == DevSurface::Agent => {
632                                state.cycle_agent_selection(-1)
633                            }
634                            (KeyCode::Char(']'), _) if state.surface == DevSurface::Code => {
635                                state.cycle_editor_buffer(1)
636                            }
637                            (KeyCode::Char('['), _) if state.surface == DevSurface::Code => {
638                                state.cycle_editor_buffer(-1)
639                            }
640                            (KeyCode::Char('T' | 't'), _) if state.surface == DevSurface::App => {
641                                state.queue_browser_targets(&mut worker);
642                            }
643                            (KeyCode::Enter, _) if state.surface == DevSurface::App => {
644                                state.queue_browser_intent(BrowserWorkspaceIntent::ActivateSelected)
645                            }
646                            (KeyCode::PageUp, _) => state.scroll_surface(-10),
647                            (KeyCode::PageDown, _) => state.scroll_surface(10),
648                            (KeyCode::Home, _) => state.scroll_home(),
649                            (KeyCode::End, _) => state.scroll_end(),
650                            (KeyCode::Left, modifiers)
651                                if !modifiers.contains(KeyModifiers::ALT) =>
652                            {
653                                state.previous_surface()
654                            }
655                            (KeyCode::Right, modifiers)
656                                if !modifiers.contains(KeyModifiers::ALT) =>
657                            {
658                                state.next_surface()
659                            }
660                            (KeyCode::Left, modifiers)
661                                if modifiers.contains(KeyModifiers::ALT)
662                                    && state.surface == DevSurface::App =>
663                            {
664                                state.queue_browser_intent(BrowserWorkspaceIntent::Back)
665                            }
666                            (KeyCode::Right, modifiers)
667                                if modifiers.contains(KeyModifiers::ALT)
668                                    && state.surface == DevSurface::App =>
669                            {
670                                state.queue_browser_intent(BrowserWorkspaceIntent::Forward)
671                            }
672                            (KeyCode::Char('r'), modifiers)
673                                if modifiers.contains(KeyModifiers::CONTROL)
674                                    && state.surface == DevSurface::App =>
675                            {
676                                state.queue_browser_intent(BrowserWorkspaceIntent::Reload)
677                            }
678                            (KeyCode::Up, _) | (KeyCode::Char('k'), _)
679                                if state.surface == DevSurface::Code =>
680                            {
681                                state.move_file_selection(-1)
682                            }
683                            (KeyCode::Down, _) | (KeyCode::Char('j'), _)
684                                if state.surface == DevSurface::Code =>
685                            {
686                                state.move_file_selection(1)
687                            }
688                            (KeyCode::Up, _) | (KeyCode::Char('k'), _)
689                                if state.surface == DevSurface::App =>
690                            {
691                                let _ = state
692                                    .browser_workspace
693                                    .reduce(BrowserWorkspaceIntent::MoveSelection { delta: -1 });
694                                state.browser = state.browser_workspace_summary();
695                                state.status =
696                                    "Selection moved · Enter activates the selected entity".into();
697                            }
698                            (KeyCode::Down, _) | (KeyCode::Char('j'), _)
699                                if state.surface == DevSurface::App =>
700                            {
701                                let _ = state
702                                    .browser_workspace
703                                    .reduce(BrowserWorkspaceIntent::MoveSelection { delta: 1 });
704                                state.browser = state.browser_workspace_summary();
705                                state.status =
706                                    "Selection moved · Enter activates the selected entity".into();
707                            }
708                            (KeyCode::Up, _) | (KeyCode::Char('k'), _) => state.scroll_surface(-1),
709                            (KeyCode::Down, _) | (KeyCode::Char('j'), _) => state.scroll_surface(1),
710                            (KeyCode::Tab, modifiers)
711                                if modifiers.contains(KeyModifiers::SHIFT) =>
712                            {
713                                state.previous_surface()
714                            }
715                            (KeyCode::Tab, _) => state.next_surface(),
716                            (KeyCode::Char(character), _) => state.handle_printable(character),
717                            _ => {}
718                        }
719                    }
720                }
721                Event::Paste(text) if state.command_mode => state.insert_palette_text(&text),
722                Event::Paste(text) if state.composer_mode => state.insert_composer_text(&text),
723                Event::Mouse(mouse) => match mouse.kind {
724                    crossterm::event::MouseEventKind::ScrollUp => state.scroll_surface(-3),
725                    crossterm::event::MouseEventKind::ScrollDown => state.scroll_surface(3),
726                    crossterm::event::MouseEventKind::Down(crossterm::event::MouseButton::Left)
727                        if !state.quit_confirmation
728                            && state.editor_exit_prompt.is_none()
729                            && !state.help_open
730                            && !state.menu_open
731                            && !state.command_mode
732                            && !state.composer_mode
733                            && !state.code_edit_mode
734                            && state.pending_confirmation.is_none()
735                            && state.pending_agent_approval.is_none()
736                            && !state.browser_target_picker
737                            && state.browser_recovery.is_none()
738                            && !state.git_diff_open =>
739                    {
740                        let responsive =
741                            state.responsive_class(state.terminal_width, state.terminal_height);
742                        let header_height = if state.composer_mode { 3 } else { 2 };
743                        if let Some(surface) = navigation_surface_at(
744                            responsive,
745                            header_height,
746                            mouse.column,
747                            mouse.row,
748                        ) {
749                            state.surface = surface;
750                            state.status = format!("{} selected", surface.label());
751                        }
752                    }
753                    _ => {}
754                },
755                Event::FocusLost => {
756                    let _ = state
757                        .browser_workspace
758                        .reduce(BrowserWorkspaceIntent::CloseOverlay);
759                }
760                Event::Resize(width, height) => state.set_terminal_size(width, height),
761                Event::Key(_) | Event::Paste(_) | Event::FocusGained => {}
762            }
763        }
764        if state.agent_login_requested {
765            state.agent_login_requested = false;
766            run_agent_login(&mut state, &mut guard);
767            worker.request_refresh();
768        }
769        if let Some(name) = state.harness_launch_requested.take() {
770            run_external_harness(&mut state, &mut guard, &name);
771            worker.request_refresh();
772        }
773
774        for event in visual.poll_events() {
775            match event {
776                HerdrEvent::Connected if visual.live => {
777                    state.browser_workspace.state_mut().presentation =
778                        glass_browser::browser_workspace::BrowserPresentationPath::Herdr;
779                    state.browser_workspace.state_mut().presentation_reason =
780                        Some("Herdr pane graphics stream connected".into());
781                    state.status = "Live view ready · Herdr pane graphics".into();
782                }
783                HerdrEvent::Failed(reason) => {
784                    visual.live = false;
785                    visual.sync_state(&mut state);
786                    state.browser_workspace.state_mut().presentation_reason =
787                        Some(format!("Herdr graphics unavailable: {reason}"));
788                    state.status = format!("Live view unavailable · Herdr: {reason}");
789                }
790                HerdrEvent::Stopped if visual.live => {
791                    visual.live = false;
792                    visual.sync_state(&mut state);
793                    state.browser_workspace.state_mut().presentation_reason =
794                        Some("Herdr pane graphics stream stopped".into());
795                    state.status =
796                        "Live view stopped · semantic inspection remains available".into();
797                }
798                HerdrEvent::Connected | HerdrEvent::Stopped => {}
799            }
800        }
801        if state.git_diff_requested {
802            state.git_diff_requested = false;
803            state.queue_git_diff(&mut worker);
804        }
805        if last_refresh.elapsed() >= Duration::from_millis(250) {
806            worker.request_refresh();
807            last_refresh = Instant::now();
808        } else if worker.is_busy() && last_render.elapsed() >= Duration::from_millis(100) {
809            // Conversation tail keeps streaming while a full pass is in flight.
810            worker.request_conversation();
811            state.conversation_cursor = worker.conversation_cursor();
812        }
813        if state.browser_visual_live
814            && visual.live
815            && matches!(
816                state.browser_workspace.state().connection,
817                BrowserConnectionPhase::Connected
818            )
819            && last_visual.elapsed() >= Duration::from_millis(frame_interval_ms(visual.quality))
820        {
821            let available = (
822                state.terminal_width.saturating_sub(42),
823                state.terminal_height.saturating_sub(12),
824            );
825            let (columns, rows) = pane_size(visual.quality, available);
826            worker.submit_screenshot(columns, rows);
827            last_visual = Instant::now();
828        }
829        if let Ok(Some(result)) = worker.try_job_result() {
830            let browser_start = result.tool == "glass.browser.start" && result.result.is_ok();
831            let browser_observe = result.tool == "glass.browser.observe" && result.result.is_ok();
832            state.apply_tool_job_result(result);
833            if browser_start {
834                state.continue_pending_browser_navigation(&mut worker);
835            } else if browser_observe && state.pending_browser_navigation.is_some() {
836                state.submit_pending_browser_navigation(&mut worker);
837            } else {
838                state.queue_browser_observe(&mut worker);
839            }
840        }
841        if let Ok(Some(result)) = worker.try_visual_result() {
842            match &visual.path {
843                VisualPath::Herdr if visual.live => match visual_png(&result) {
844                    Ok(png) => {
845                        if visual.submit_herdr(png, result.columns, result.rows) {
846                            let browser = state.browser_workspace.state_mut();
847                            browser.presentation =
848                                glass_browser::browser_workspace::BrowserPresentationPath::Herdr;
849                            browser.frame_revision = browser.browser_revision;
850                            browser.presentation_reason =
851                                Some("Herdr pane graphics frame queued".into());
852                            state.status = "Live view updated · Herdr pane".into();
853                        }
854                    }
855                    Err(error) => {
856                        visual.live = false;
857                        visual.sync_state(&mut state);
858                        state.browser_workspace.state_mut().presentation_reason =
859                            Some(error.clone());
860                        state.status = format!("Live view unavailable · {error}");
861                    }
862                },
863                VisualPath::Kitty if visual.live => match visual_png(&result) {
864                    Ok(png) => {
865                        let pane = render::browser_visual_area(
866                            &state,
867                            Rect::new(0, 0, state.terminal_width, state.terminal_height),
868                        )
869                        .map(|area| PaneArea::new(area.x, area.y, area.width, area.height));
870                        if let Some(pane) = pane {
871                            let browser_revision = state
872                                .browser_workspace
873                                .state()
874                                .browser_revision
875                                .unwrap_or(0);
876                            match visual.submit_kitty(&png, pane, browser_revision) {
877                                Ok(bytes) => {
878                                    guard.write_bytes(&bytes)?;
879                                    visual.mark_kitty_drawn();
880                                    let browser = state.browser_workspace.state_mut();
881                                    browser.presentation =
882                                        glass_browser::browser_workspace::BrowserPresentationPath::Kitty;
883                                    browser.frame_revision = browser.browser_revision;
884                                    browser.presentation_reason = Some(
885                                        "Kitty terminal graphics frame emitted · semantic controls remain authoritative"
886                                            .into(),
887                                    );
888                                    state.status = "Live view updated · Kitty graphics".into();
889                                }
890                                Err(error) => {
891                                    visual.live = false;
892                                    visual.sync_state(&mut state);
893                                    visual.sync_kitty_area(None, &mut guard)?;
894                                    state.browser_workspace.state_mut().presentation_reason =
895                                        Some(error.clone());
896                                    state.status = format!("Live view unavailable · {error}");
897                                }
898                            }
899                        }
900                    }
901                    Err(error) => {
902                        visual.live = false;
903                        visual.sync_state(&mut state);
904                        visual.sync_kitty_area(None, &mut guard)?;
905                        state.browser_workspace.state_mut().presentation_reason =
906                            Some(error.clone());
907                        state.status = format!("Live view unavailable · {error}");
908                    }
909                },
910                VisualPath::Kitty => {}
911                VisualPath::Ansi => {
912                    state.apply_visual_job_result_with_fit(result, frame_fit(visual.fit));
913                }
914                VisualPath::SemanticOnly { .. } => {}
915                VisualPath::Herdr => {}
916            }
917        }
918        if let Some(snapshot) = worker.take_pending() {
919            state.apply_snapshot(&snapshot);
920        }
921    }
922
923    let kitty_cleanup = visual.shutdown();
924    guard.write_bytes(&kitty_cleanup)?;
925    drop(worker);
926    Ok(())
927}
928fn terminal_overlay_mask(state: &DevTuiState) -> u16 {
929    let mut mask = 0_u16;
930    if state.command_mode {
931        mask |= 1 << 0;
932    }
933    if state.composer_mode {
934        mask |= 1 << 1;
935    }
936    if state.menu_open {
937        mask |= 1 << 2;
938    }
939    if state.help_open {
940        mask |= 1 << 3;
941    }
942    if state.code_edit_mode {
943        mask |= 1 << 4;
944    }
945    if state.browser_target_picker {
946        mask |= 1 << 5;
947    }
948    if state.browser_recovery.is_some() {
949        mask |= 1 << 6;
950    }
951    if state.git_diff_open {
952        mask |= 1 << 7;
953    }
954    if state.pending_confirmation.is_some() {
955        mask |= 1 << 8;
956    }
957    if state.pending_agent_approval.is_some() {
958        mask |= 1 << 9;
959    }
960    if state.quit_confirmation {
961        mask |= 1 << 10;
962    }
963    if state.editor_exit_prompt.is_some() {
964        mask |= 1 << 11;
965    }
966    mask
967}
968
969/// Map a left-click on the desktop or compact navigation column to a surface.
970/// The caller supplies the rendered header height so composer mode stays aligned.
971fn navigation_surface_at(
972    responsive: ResponsiveClass,
973    header_height: u16,
974    column: u16,
975    row: u16,
976) -> Option<DevSurface> {
977    let nav_width = match responsive {
978        ResponsiveClass::Desktop => 24,
979        ResponsiveClass::Compact => 22,
980        ResponsiveClass::Phone => return None,
981    };
982    let first_item_row = header_height.saturating_add(1);
983    if column >= nav_width || row < first_item_row {
984        return None;
985    }
986    DevSurface::PRIMARY
987        .into_iter()
988        .nth(usize::from(row - first_item_row))
989}
990
991fn visual_png(result: &snapshot::VisualJobResult) -> Result<Vec<u8>, String> {
992    let value = result.result.as_ref().map_err(|error| error.clone())?;
993    let encoded = value
994        .get("base64")
995        .and_then(serde_json::Value::as_str)
996        .ok_or_else(|| "screenshot payload did not contain base64 PNG data".to_string())?;
997    use base64::Engine as _;
998    base64::engine::general_purpose::STANDARD
999        .decode(encoded)
1000        .map_err(|error| format!("screenshot payload was not valid base64: {error}"))
1001}
1002
1003fn run_agent_login(state: &mut DevTuiState, guard: &mut TerminalGuard) {
1004    if let Err(error) = guard.suspend() {
1005        state.status = format!("Could not hand the terminal to Pi: {error}");
1006        return;
1007    }
1008    let result = crate::pi_runtime::setup_pi_runtime(None, None, false, true);
1009    let resume = guard.resume();
1010    match (result, resume) {
1011        (Ok(_), Ok(())) => match state.refresh_agent_readiness() {
1012            Ok(true) => {
1013                state.status = "Pi is ready · press Enter or start typing to chat".into();
1014            }
1015            Ok(false) => {
1016                state.status =
1017                    "Pi needs setup · use :agent setup or :agent setup login, then Enter to chat"
1018                        .into();
1019            }
1020            Err(error) => state.status = format!("Pi readiness check failed: {error}"),
1021        },
1022        (Err(error), Ok(())) => {
1023            state.status = format!("Pi login failed: {error}");
1024        }
1025        (Ok(_), Err(error)) => {
1026            state.status = format!("Pi login finished, but TUI could not resume: {error}");
1027            state.quit = true;
1028        }
1029        (Err(error), Err(resume_error)) => {
1030            state.status = format!("Pi login failed: {error}; TUI resume failed: {resume_error}");
1031            state.quit = true;
1032        }
1033    }
1034}
1035
1036fn run_external_harness(state: &mut DevTuiState, guard: &mut TerminalGuard, name: &str) {
1037    let resolved = match crate::harness::resolve(name) {
1038        Ok(resolved) => resolved,
1039        Err(error) => {
1040            state.status = format!("Harness launch unavailable · {error}");
1041            return;
1042        }
1043    };
1044    let root = state.ws().map(|workspace| workspace.root().to_path_buf());
1045    let root = match root {
1046        Ok(root) => root,
1047        Err(error) => {
1048            state.status = format!("Harness launch unavailable · {error}");
1049            return;
1050        }
1051    };
1052    if let Err(error) = guard.suspend() {
1053        state.status = format!(
1054            "Could not hand the terminal to {}: {error}",
1055            resolved.spec.label
1056        );
1057        return;
1058    }
1059    let result = crate::harness::launch_resolved(&resolved, &root);
1060    let resume = guard.resume();
1061    match (result, resume) {
1062        (Ok(status), Ok(())) if status.success() => {
1063            state.status = format!("{} exited · Glass workspace resumed", resolved.spec.label);
1064        }
1065        (Ok(status), Ok(())) => {
1066            state.status = format!(
1067                "{} exited with {} · Glass workspace resumed",
1068                resolved.spec.label,
1069                status
1070                    .code()
1071                    .map_or_else(|| "a signal".into(), |code| format!("status {code}"))
1072            );
1073        }
1074        (Err(error), Ok(())) => {
1075            state.status = format!("{} failed to start: {error}", resolved.spec.label);
1076        }
1077        (Ok(_), Err(error)) => {
1078            state.status = format!(
1079                "{} exited, but Glass could not resume: {error}",
1080                resolved.spec.label
1081            );
1082            state.quit = true;
1083        }
1084        (Err(error), Err(resume_error)) => {
1085            state.status = format!(
1086                "{} failed to start: {error}; Glass resume failed: {resume_error}",
1087                resolved.spec.label
1088            );
1089            state.quit = true;
1090        }
1091    }
1092}
1093
1094struct TerminalGuard {
1095    terminal: Terminal<CrosstermBackend<io::Stdout>>,
1096}
1097
1098impl TerminalGuard {
1099    fn enter() -> io::Result<Self> {
1100        enable_raw_mode()?;
1101        let mut stdout = io::stdout();
1102        execute!(
1103            stdout,
1104            EnterAlternateScreen,
1105            EnableMouseCapture,
1106            EnableFocusChange,
1107            EnableBracketedPaste
1108        )?;
1109        let terminal = Terminal::new(CrosstermBackend::new(stdout))?;
1110        Ok(Self { terminal })
1111    }
1112
1113    fn write_bytes(&mut self, bytes: &[u8]) -> io::Result<()> {
1114        if bytes.is_empty() {
1115            return Ok(());
1116        }
1117        let backend = self.terminal.backend_mut();
1118        backend.write_all(bytes)?;
1119        backend.flush()
1120    }
1121    fn suspend(&mut self) -> io::Result<()> {
1122        disable_raw_mode()?;
1123        if let Err(error) = execute!(
1124            self.terminal.backend_mut(),
1125            DisableBracketedPaste,
1126            DisableFocusChange,
1127            DisableMouseCapture,
1128            LeaveAlternateScreen
1129        ) {
1130            let _ = enable_raw_mode();
1131            return Err(error);
1132        }
1133        self.terminal.show_cursor()
1134    }
1135
1136    fn resume(&mut self) -> io::Result<()> {
1137        execute!(
1138            self.terminal.backend_mut(),
1139            EnterAlternateScreen,
1140            EnableMouseCapture,
1141            EnableFocusChange,
1142            EnableBracketedPaste
1143        )?;
1144        enable_raw_mode()?;
1145        // `Terminal::clear` queries the cursor position so it can preserve it. That query
1146        // is not supported by every terminal multiplexer/PTY (and can hang after a child
1147        // process returns), so clear the fullscreen surface directly and force Ratatui to
1148        // redraw both buffers instead.
1149        execute!(
1150            self.terminal.backend_mut(),
1151            Clear(ClearType::All),
1152            crossterm::cursor::MoveTo(0, 0)
1153        )?;
1154        self.terminal.current_buffer_mut().reset();
1155        self.terminal.swap_buffers();
1156        Ok(())
1157    }
1158}
1159
1160impl Drop for TerminalGuard {
1161    fn drop(&mut self) {
1162        let _ = disable_raw_mode();
1163        let _ = execute!(
1164            self.terminal.backend_mut(),
1165            DisableBracketedPaste,
1166            DisableFocusChange,
1167            DisableMouseCapture,
1168            LeaveAlternateScreen
1169        );
1170        let _ = self.terminal.show_cursor();
1171    }
1172}
1173
1174#[cfg(test)]
1175mod tests {
1176    use super::*;
1177
1178    #[test]
1179    fn mouse_navigation_maps_rows_inside_the_visible_list() {
1180        assert_eq!(
1181            navigation_surface_at(ResponsiveClass::Desktop, 2, 2, 3),
1182            Some(DevSurface::Agent)
1183        );
1184        assert_eq!(
1185            navigation_surface_at(ResponsiveClass::Desktop, 2, 2, 4),
1186            Some(DevSurface::Code)
1187        );
1188        assert_eq!(
1189            navigation_surface_at(ResponsiveClass::Desktop, 2, 2, 9),
1190            Some(DevSurface::Debug)
1191        );
1192        assert_eq!(
1193            navigation_surface_at(ResponsiveClass::Desktop, 2, 2, 2),
1194            None
1195        );
1196        assert_eq!(
1197            navigation_surface_at(ResponsiveClass::Desktop, 2, 24, 3),
1198            None
1199        );
1200        assert_eq!(navigation_surface_at(ResponsiveClass::Phone, 2, 2, 3), None);
1201        assert_eq!(
1202            navigation_surface_at(ResponsiveClass::Compact, 3, 2, 4),
1203            Some(DevSurface::Agent)
1204        );
1205    }
1206}