fix: Added better support for non-graphical terminfos

Author: DanielHauge

docs/src/installation.md

@@ -63,6 +63,14 @@ h5v works in regular terminals, but **image previews and chart previews work bes
 
 h5v uses `ratatui-image` to detect and drive terminal image backends such as Kitty, Sixel, and iTerm2. If no graphics protocol is available, preview quality depends on the available fallback path and will usually be less crisp than in Kitty-class terminals.
 
+If your terminal shows a blank or badly garbled screen, start h5v with:
+
+```bash
+h5v --no-terminal-graphics path/to/file.h5
+```
+
+That disables terminal graphics probing and forces the safer text-only preview path. It is especially useful in browser-backed terminals and other xterm-like environments with partial graphics support.
+
 ## Write mode
 
 h5v opens files read-only unless you pass `-w`:

docs/src/troubleshooting.md

@@ -20,6 +20,18 @@ Check the HDF5 image metadata first:
 
 If those attributes are missing, h5v falls back to normal dataset handling.
 
+## The UI is blank or badly garbled
+
+Some terminals partially respond to graphics capability probes but do not render the resulting protocol correctly.
+
+Start h5v with:
+
+```bash
+h5v --no-terminal-graphics file.h5
+```
+
+That forces the safer text-only preview path and is a good first workaround on browser-backed or otherwise unusual terminal emulators.
+
 ## A compound dataset does not show in matrix mode
 
 That is expected for the compound container itself. The root compound node shows a recursive schema preview. Drill down to a projected leaf field if you want normal preview or matrix rendering.

src/main.rs

@@ -52,6 +52,10 @@ struct Args {
     /// Validate startup commands and print a summary without launching the UI.
     #[clap(long = "script-test")]
     script_test: bool,
+
+    /// Disable terminal graphics probing and force text-only preview rendering.
+    #[clap(long = "no-terminal-graphics")]
+    no_terminal_graphics: bool,
 }
 
 fn main() -> Result<(), AppError> {
@@ -76,11 +80,18 @@ fn main() -> Result<(), AppError> {
             Args::command().print_long_help()?;
             std::process::exit(1);
         }
-        [single] => ui::app::init(single.clone(), false, args.write, &startup.commands),
+        [single] => ui::app::init(
+            single.clone(),
+            false,
+            args.write,
+            args.no_terminal_graphics,
+            &startup.commands,
+        ),
         multiple => ui::app::init(
             linking::link(multiple)?,
             true,
             args.write,
+            args.no_terminal_graphics,
             &startup.commands,
         ),
     }
@@ -323,6 +334,7 @@ mod tests {
             commands: Vec::new(),
             scripts: Vec::new(),
             script_test: false,
+            no_terminal_graphics: false,
         }
     }
 

src/ui/app.rs

@@ -380,6 +380,7 @@ pub fn init(
     filename: String,
     link: bool,
     writable: bool,
+    no_terminal_graphics: bool,
     startup_commands: &[StartupCommand],
 ) -> Result<()> {
     stdout().execute(EnterAlternateScreen)?;
@@ -397,6 +398,7 @@ pub fn init(
             filename.clone(),
             link,
             writable,
+            no_terminal_graphics,
             startup_commands,
         ) {
             Ok(_) => break,
@@ -469,6 +471,7 @@ fn main_recover_loop(
     filename: String,
     link: bool,
     writable: bool,
+    no_terminal_graphics: bool,
     startup_commands: &[StartupCommand],
 ) -> Result<IntendedMainLoopBreak> {
     let h5f = h5f::H5F::open(filename.clone(), link, writable).map_err(|e| {
@@ -480,7 +483,11 @@ fn main_recover_loop(
 
     let (tx_events, rx_events) = channel();
     #[allow(deprecated)]
-    let mut picker = Picker::from_query_stdio().unwrap_or(Picker::from_fontsize((7, 14)));
+    let mut picker = if no_terminal_graphics {
+        Picker::halfblocks()
+    } else {
+        Picker::from_query_stdio().unwrap_or(Picker::halfblocks())
+    };
     let (bg_r, bg_g, bg_b) = color_consts::rgb_channels(color_consts::BG_COLOR);
     picker.set_background_color(Rgba([bg_r, bg_g, bg_b, 255]));
     let image_cell_size = picker.font_size();