From cfac97e07ac71d332f41990be7c62afb055481d5 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:16:43 +0000 Subject: [PATCH 1/5] test: bisect the slideshow repaint with new placeholder_probe variants The existing variants bisect the draw: which ingredient of the slideshow's output makes a terminal render placeholder cells blank. They say nothing about the repair -- given a slide that came out wrong, what completes it. Five variants for that. `manual` is the control: it draws and waits while the tester switches tmux panes by hand, establishing that the draw reproduces the problem and that a pane switch fixes it, without which the rest prove nothing. `refresh` fires `tmux refresh-client`, `nudge` writes one unrelated cell far from the grid, and `rewrite` re-sends the placeholder cells in place. Each holds the draw, applies exactly one nudge, and holds again, so a single run shows before and after; nothing is written afterwards, since any further output is itself terminal traffic and would confound the result. `cycle-refresh` then repeats the slideshow's own navigation dance across three slides with a repaint standing in for the alternate-screen cycle, which `refresh` cannot settle: that variant repairs a first draw, where nothing has been deleted and no data is in flight. On Ghostty 1.3.1 + tmux only the variants that force a full client repaint complete the image. Unrelated traffic does not, so the terminal is not merely sitting on a stale frame, and re-sending the cells in place does not either. Co-Authored-By: Claude Opus 5 (1M context) --- examples/placeholder_probe.rs | 211 +++++++++++++++++++++++++++++++++- 1 file changed, 210 insertions(+), 1 deletion(-) diff --git a/examples/placeholder_probe.rs b/examples/placeholder_probe.rs index fcd6feb..6ec94fa 100644 --- a/examples/placeholder_probe.rs +++ b/examples/placeholder_probe.rs @@ -18,11 +18,29 @@ //! Each variant shows the image for four seconds, then cleans up after //! itself. Note which variants show the cat logo and which stay blank. //! +//! A second group bisects the *repair* rather than the draw: when a slide +//! renders clipped or blank, which nudge completes it without re-sending +//! image data the terminal already holds? +//! +//! ```sh +//! ./target/debug/examples/placeholder_probe manual # control: switch panes by hand +//! ./target/debug/examples/placeholder_probe refresh # tmux refresh-client +//! ./target/debug/examples/placeholder_probe nudge # one unrelated cell of traffic +//! ./target/debug/examples/placeholder_probe rewrite # re-send the grid cells in place +//! ./target/debug/examples/placeholder_probe cycle-refresh # navigation, repaired by refresh +//! ``` +//! +//! Run `manual` first: it establishes that this draw reproduces the problem +//! at all, and that a pane switch repairs it. Without that the other three +//! prove nothing. Each shows the draw, waits, applies exactly one nudge, +//! and waits again, so a single run shows before and after. +//! //! This is a debugging aid, not part of the kittyview CLI. use kittyview::terminal::Mux; use kittyview::{kitty, logo, placeholder}; use std::io::{self, Write}; +use std::process::{Command, Stdio}; use std::time::Duration; const COLS: u16 = 16; @@ -31,6 +49,14 @@ const ROWS: u16 = 8; /// slideshow's centring does. const ORIGIN_ROW: u16 = 3; const ORIGIN_COL: u16 = 5; +/// How long the nudge variants leave the screen alone for one observation. +const OBSERVE: Duration = Duration::from_secs(5); +/// Longer, for the variant whose nudge is a pane switch made by hand. +const MANUAL_OBSERVE: Duration = Duration::from_secs(15); +/// How long to let a draw land before asking tmux to repaint, mirroring the +/// slideshow's `VERIFY_SETTLE`: tmux drops passthrough while a redraw is +/// pending, so the transmission must be clear of the repaint at both ends. +const REPAINT_SETTLE: Duration = Duration::from_millis(200); fn main() -> io::Result<()> { let variant = std::env::args().nth(1).unwrap_or_default(); @@ -149,16 +175,199 @@ fn main() -> io::Result<()> { cleanup(&mut out, &mux, id_c, true) } + // Navigation with a tmux repaint standing in for the alternate- + // screen cycle: three slides, each drawn by the slideshow's own + // dance -- transmit the new data, delete the old image, erase, + // write the new grid -- and then repaired with `refresh-client` + // rather than by leaving and re-entering the alternate screen. + // + // This is what `refresh` does not settle. That variant repaints a + // first draw, where nothing has been deleted and no data is in + // flight; a slide change repaints while an image has just been + // dropped from the terminal's store and another has just arrived + // through passthrough. If every slide here renders, the cycle in + // `slideshow::show` -- and its flash, and its LEAVE_SETTLE -- can + // be replaced by a repaint. + "cycle-refresh" => { + if mux.is_empty() { + eprintln!("cycle-refresh needs tmux: $TMUX is not set"); + std::process::exit(2); + } + let ids = [ + image_id, + kitty::pick_image_id(&mux), + kitty::pick_image_id(&mux), + ]; + out.write_all(b"\x1b[?1049h\x1b[H\x1b[J")?; + out.flush()?; + std::thread::sleep(Duration::from_millis(1500)); + + let mut previous: Option = None; + for (n, &id) in ids.iter().enumerate() { + // New data first: an `a=T,U=1` transmission is invisible + // until cells reference it, so it can stream out while the + // previous slide is still on screen. + kitty::transmit_virtual(&png, &mut out, &mux, id, 1, COLS, ROWS)?; + if let Some(old) = previous { + kitty::delete_image(&mut out, &mux, old, true)?; + } + out.write_all(b"\x1b[H\x1b[J")?; + // Shift each slide right, so which draw is on screen is + // visible at a glance. + position_grid_at(&mut out, id, ORIGIN_ROW, ORIGIN_COL + 20 * n as u16)?; + status( + &mut out, + &format!( + "cycle-refresh: slide {} of {} -- repaint in progress", + n + 1, + ids.len() + ), + )?; + out.flush()?; + + std::thread::sleep(REPAINT_SETTLE); + let _ = Command::new("tmux") + .arg("refresh-client") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status(); + // Let the repaint finish before the next transmission goes + // out through passthrough. + std::thread::sleep(REPAINT_SETTLE); + std::thread::sleep(OBSERVE); + previous = Some(id); + } + + cleanup(&mut out, &mux, ids[ids.len() - 1], true)?; + eprintln!( + "cycle-refresh: all three slides rendered => a repaint is enough for slide \ + changes too, and the alternate-screen cycle can go. Any slide blank or \ + clipped => the cycle is doing something the repaint does not, and \ + refresh-client can only be added to it, not swapped for it." + ); + Ok(()) + } + // The repaint bisection. All four draw the same known-problematic + // shape -- alternate screen, transmit, positioned grid -- hold it + // long enough to see whether it came out wrong, apply exactly one + // nudge, and hold again. Nothing is written after the nudge: any + // further output is itself terminal traffic and would confound the + // result, which is also why the caption goes up front. + "manual" | "refresh" | "nudge" | "rewrite" => { + if variant == "refresh" && mux.is_empty() { + eprintln!("refresh needs tmux: $TMUX is not set"); + std::process::exit(2); + } + out.write_all(b"\x1b[?1049h\x1b[H\x1b[J")?; + out.flush()?; + std::thread::sleep(Duration::from_millis(1500)); + + transmit_and_position(&mut out, &mux, &png, image_id)?; + status(&mut out, &caption(&variant))?; + out.flush()?; + std::thread::sleep(if variant == "manual" { + MANUAL_OBSERVE + } else { + OBSERVE + }); + + match variant.as_str() { + // What switching panes does: repaint every visible pane + // out of tmux's own grid. No image data is re-sent -- the + // terminal already holds it, and the placeholder cells are + // ordinary text in tmux's grid. They survive the repaint + // because their image ID rides a 256-colour SGR, which a + // multiplexer relays verbatim (see `IdSpace::MuxSafe`). + "refresh" => { + let _ = Command::new("tmux") + .arg("refresh-client") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status(); + } + // One cell of traffic, far from the grid, reaching the + // terminal through tmux like any other pane output. It + // changes nothing about the image or the cells drawing + // it, so it can only repair a frame the terminal itself + // failed to paint. + "nudge" => { + write!(out, "\x1b[{};1H\x1b[2m.\x1b[0m", ORIGIN_ROW + ROWS + 4)?; + out.flush()?; + } + // The placeholder cells re-sent exactly as they were, as + // an in-place pane update. + "rewrite" => { + position_grid_at(&mut out, image_id, ORIGIN_ROW, ORIGIN_COL)?; + out.flush()?; + } + // "manual": the nudge is the pane switch, done by hand + // during the wait that just passed. + _ => {} + } + + std::thread::sleep(OBSERVE); + cleanup(&mut out, &mux, image_id, true)?; + eprintln!("{}", verdict(&variant)); + Ok(()) + } _ => { eprintln!( "usage: placeholder_probe \ - " + " ); std::process::exit(2); } } } +/// What the nudge variants put on screen before the wait, since nothing may +/// be written afterwards. +fn caption(variant: &str) -> String { + match variant { + "manual" => format!( + "manual: switch to another pane and back within {}s -- does the image complete?", + MANUAL_OBSERVE.as_secs() + ), + "refresh" => format!( + "refresh: `tmux refresh-client` fires in {}s", + OBSERVE.as_secs() + ), + "nudge" => format!( + "nudge: one unrelated cell is written in {}s", + OBSERVE.as_secs() + ), + _ => format!( + "rewrite: the grid cells are re-sent in {}s", + OBSERVE.as_secs() + ), + } +} + +/// How to read what just happened, printed once the screen is restored. +fn verdict(variant: &str) -> &'static str { + match variant { + "manual" => { + "manual: if the image was wrong and the pane switch completed it, this draw \ + reproduces the bug and the other three variants mean something. If it looked \ + right all along, the probe is not reproducing what the slideshow hits." + } + "refresh" => { + "refresh: completed => a full tmux client redraw is the fix, and the slideshow \ + can call refresh-client after each draw instead of cycling the alternate \ + screen -- no flash, no LEAVE_SETTLE." + } + "nudge" => { + "nudge: completed => the terminal painted a stale frame; any trivial traffic \ + after a draw is enough, and no tmux involvement is needed." + } + _ => { + "rewrite: completed => re-sending the placeholder cells in place is enough, \ + which is the cheapest fix of the three." + } + } +} + /// Write a dim status line below the grid area. fn status(out: &mut impl Write, text: &str) -> io::Result<()> { write!( From 93108b91612a397c6350c6ec6ef96f5f68f14035 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:16:43 +0000 Subject: [PATCH 2/5] fix: repaint the tmux client instead of cycling the alternate screen Ghostty through 1.3.1 renders placeholder images delivered as an in-place pane update blank or clipped -- with the data confirmed present in the terminal via the reply channel -- while a full repaint out of tmux's own grid renders them correctly. That is why switching tmux panes completes an image that came out partial. 0.1.6 bought that repaint by rebuilding every slide through the pane's main screen: leave the alternate screen, let the redraw settle, transmit, re-enter. It works, at the cost of a flash of the underlying pane on every slide change and a 250ms settle. `tmux refresh-client` is the same client repaint a pane switch triggers, without the pane switch, and re-sends nothing: the image is already in the terminal's store and the placeholder cells are already in tmux's grid, where they survive the repaint because their image ID rides a 256-colour SGR that a multiplexer relays verbatim. Every draw now ends with one. It is issued after the arrival check, never before -- tmux drops passthrough while a redraw is pending and would eat the question with it. The attempt loop now breaks with a `settled` flag rather than returning from five places, so the repaint runs once, on whatever draw is left standing. `can_repaint` restricts this to a lone tmux layer. Nested inside another multiplexer the repaint's own output reaches the outer layer as one more in-place update, which is the very thing that renders blank; screen has no equivalent command and was never the stack this was field-tested on. Those stacks keep the rebuild, which also remains the last-attempt fallback when transmissions are being lost, and what the `r` key forces by hand. Field-tested on Ghostty 1.3.1 + tmux: slides render fully, no flash between them, and Ctrl-Z/fg still resumes with the slide redrawn -- the path that matters most here, since the rebuild used to set `pending_enter` on its own. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 6 ++ src/slideshow.rs | 136 ++++++++++++++++++++++++++++++++++------- test/slideshow-test.sh | 7 ++- 3 files changed, 126 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c2640a..59f5226 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## upcoming + +- **Slideshow images render fully under tmux, without the flash**: Ghostty through 1.3.1 renders placeholder images delivered as an in-place pane update blank or clipped -- with the data confirmed present in the terminal via the reply channel -- while a full repaint out of tmux's own grid renders them correctly. That is why switching tmux panes completes an image that came out partial. Every draw under a lone tmux layer now ends with `tmux refresh-client`: the same client repaint a pane switch triggers, re-sending nothing (the image is already in the terminal's store, the placeholder cells already in tmux's grid) and costing nothing visible. It replaces the alternate-screen rebuild 0.1.6 used for the same purpose, so slide changes no longer flash the pane underneath, nor pay the 250ms settle that rebuild needed. The repaint is issued after the arrival check, never before, since tmux drops passthrough while a redraw is pending and would eat the question with it. Where a repaint cannot reach -- screen, which has no equivalent command, and tmux nested in another multiplexer, whose outer layer would receive the repaint as one more in-place update -- slide changes still rebuild by way of the pane's main screen; that rebuild remains the last-attempt fallback when transmissions are being lost, and what the `r` key forces by hand. +- `examples/placeholder_probe` gained a second group of variants (`manual`, `refresh`, `nudge`, `rewrite`, `cycle-refresh`) that bisect the *repair* rather than the draw: given a slide that rendered wrong, which nudge completes it. On Ghostty 1.3.1 + tmux only the two that force a full client repaint do -- unrelated terminal traffic does not, and re-sending the placeholder cells in place does not -- which is what settled the fix above. +- `test/slideshow-test.sh` now checks for the absence of the inter-slide flash it previously told the tester to expect, and asks directly whether any slide came out clipped. + ## 0.1.6 - **Slideshow mode**: giving kittyview more than one file now opens an interactive slideshow on the alternate screen -- Right/Space/n and Left/Backspace/p to navigate, Home/End for the ends, q/Esc/Ctrl-C to quit. Images are fitted to the window and centred, with a status line naming the file and position. On the Unicode-placeholder path, navigation never flashes a blank screen: an `a=T,U=1` transmission is invisible until placeholder cells reference it, so the next image's data streams out while the previous slide still shows, and the visible switch is a small delete-erase-grid burst. Every draw uses the same protocol commands as single-image display -- the transmit-then-place split (`a=t`/`a=p`) is deliberately avoided, having been found rendering blank in the wild where `a=T` works. The first draw orders the alternate-screen switch around its transmission per target: directly (and under Zellij) the switch comes first, because kitty-model terminals keep a separate image store per screen buffer and an image transmitted on the main screen does not exist on the alternate one; through tmux/screen passthrough the transmission comes first, because switching the pane's screen schedules a redraw during which tmux silently drops passthrough -- while the outer terminal, whose store holds the image, never switches screens at all. And because tmux drops passthrough around *any* pending redraw -- while `q=2` means nothing ever reports the loss -- every draw under a multiplexer is verified with the protocol's own reply channel (a silent-on-success placement probe chased by a DA barrier) and retried when the data did not arrive; losses are reported in a diagnostics line on exit. Under a multiplexer, slide changes rebuild by way of the pane's main screen (a brief flash), which field testing proved necessary independently of transmission loss: Ghostty through 1.3.1 renders placeholder images delivered as in-place pane updates blank -- with the data confirmed present in the terminal via the reply channel -- while a full repaint renders them correctly. The `r` key forces that rebuild by hand. Placeholder cells are bound to an explicit placement ID through their underline colour, so they resolve against exactly the slideshow's placement -- Ghostty through 1.3.1 otherwise picks among an image's virtual placements in hash order, and any stray placement could capture the cells. Each slide's data is deleted from the terminal's image store when it is replaced, so a long slideshow does not accumulate hundreds of megabytes in the terminal. Restoring the terminal is layered: one cleanup path for quits and errors, a panic hook that restores the screen before the panic message prints, and fatal signals are caught, cleaned up after, and re-raised so the exit status still reports them. Ctrl-Z suspends and resumes properly. Unix only for now: no native Windows terminal displays kitty graphics from a local process, so on Windows the slideshow refuses with an explanation instead. diff --git a/src/slideshow.rs b/src/slideshow.rs index b7c119f..e6a4bed 100644 --- a/src/slideshow.rs +++ b/src/slideshow.rs @@ -16,6 +16,14 @@ //! terminals delete image data on a clear-screen, including data that was //! just transmitted and not yet revealed. //! +//! Under tmux every draw ends by asking for a client repaint, because +//! Ghostty through 1.3.1 renders placeholder cells delivered as an in-place +//! pane update blank while a full repaint out of tmux's own grid renders +//! them correctly -- which is why switching panes completes an image that +//! came out clipped. `refresh-client` is that same repaint without the +//! pane switch, and re-sends nothing: the image is already in the +//! terminal's store and the cells are already in tmux's grid. +//! //! Restoring the terminal is layered. A normal exit and an error both walk //! the same cleanup; a panic is caught by a hook that restores the terminal //! before the message prints, so it lands readable on the main screen; and @@ -49,7 +57,9 @@ pub enum Key { Last, Quit, Suspend, - /// Redraw the current slide from scratch (the `r` key). + /// Redraw the current slide from scratch (the `r` key): the heavy + /// rebuild through the pane's main screen, for when the repaint every + /// draw already ends with was not enough. Redraw, /// Anything unrecognised; the show goes on. Other, @@ -521,6 +531,7 @@ mod unix { use super::*; use crate::terminal::{self, tty}; use std::path::PathBuf; + use std::process::{Command, Stdio}; use std::sync::Once; use std::sync::atomic::{AtomicBool, AtomicI32, Ordering}; @@ -649,9 +660,51 @@ mod unix { /// Pause after leaving the alternate screen, so the multiplexer's /// redraw settles before the data goes out. const LEAVE_SETTLE: Duration = Duration::from_millis(250); + /// Pause after asking tmux to repaint, so the redraw is finished before + /// the next slide's transmission goes out through passthrough. + const REPAINT_SETTLE: Duration = Duration::from_millis(200); /// Draw attempts per slide under a multiplexer. const MAX_ATTEMPTS: u32 = 3; + /// Whether a tmux client repaint can stand in for the alternate-screen + /// cycle on this stack. + /// + /// `refresh-client` talks to the server named by `$TMUX` -- the + /// innermost tmux we are inside -- and repaints that client, which is + /// the whole job when tmux is the only layer between us and the + /// terminal. Nested inside another multiplexer the repaint's own + /// output arrives at the outer layer as an ordinary in-place pane + /// update, which is the very thing that renders blank, so those stacks + /// keep the cycle. So does screen, which has no equivalent command + /// and was never the stack this was field-tested on. + pub(super) fn can_repaint(mux_stack: &[Mux]) -> bool { + matches!(mux_stack, [Mux::Tmux(_)]) && std::env::var_os("TMUX").is_some() + } + + /// Ask tmux to repaint the client, the way switching panes does. + /// + /// Nothing is re-sent: the image data is already in the terminal's + /// store, and the placeholder cells are ordinary text in tmux's grid. + /// They survive the repaint because their image ID rides a 256-colour + /// SGR, which a multiplexer relays verbatim (see + /// [`crate::placeholder::IdSpace::MuxSafe`]). + /// + /// Failure is ignored. A repaint that does not happen costs a slide + /// that may render blank, which is what the `r` key is for; there is + /// nothing better to do about it mid-slideshow, and the alternate + /// screen is no place for an error message. + fn repaint(mux_stack: &[Mux]) { + if !can_repaint(mux_stack) { + return; + } + let _ = Command::new("tmux") + .arg("refresh-client") + .stdout(Stdio::null()) + .stderr(Stdio::null()) + .status(); + std::thread::sleep(REPAINT_SETTLE); + } + /// The state a draw reads and advances: where we are in the list, what /// is decoded, what is on screen, and whether the next draw still owes /// the alternate-screen entry -- plus the tallies for the diagnostics @@ -664,7 +717,8 @@ mod unix { /// The next draw must rebuild from the main screen (the `r` key). force_cycle: bool, /// Whether the opening draw has happened; every draw after it - /// rebuilds from the main screen when under a multiplexer. + /// rebuilds from the main screen when under a multiplexer a + /// repaint cannot reach. first_draw_done: bool, draws: u32, verified_ok: u32, @@ -678,15 +732,22 @@ mod unix { /// verifying under a multiplexer that the image data survived the trip /// and retrying when it did not. /// - /// Under a multiplexer, every draw after the first rebuilds from the - /// pane's main screen -- leave the alternate screen, let the redraw - /// settle, transmit, re-enter -- at the cost of a brief flash of the - /// underlying pane. Field-tested on Ghostty 1.3.1 + tmux: it is the - /// one draw shape that reliably ends in a rendered image there, where - /// in-place draws end blank even when the protocol's own arrival - /// check reports the data present. Each draw is still verified over - /// the reply channel and retried on a reported loss, and the `r` key - /// forces a rebuild by hand. + /// Every draw ends with a repaint, because Ghostty through 1.3.1 + /// renders placeholder cells delivered as an in-place pane update + /// blank -- even when the protocol's own arrival check reports the + /// data present -- while a full repaint out of tmux's own grid renders + /// them correctly. Under plain tmux that repaint is `refresh-client`, + /// which is what switching panes does and costs nothing visible. + /// Where a repaint cannot reach (screen, or tmux nested in another + /// multiplexer) the draw falls back to rebuilding from the pane's main + /// screen -- leave the alternate screen, let the redraw settle, + /// transmit, re-enter -- at the cost of a brief flash. The rebuild is + /// also the last-attempt fallback when transmissions are being lost, + /// and the `r` key forces one by hand. + /// + /// The repaint comes after the arrival check, never before: tmux drops + /// passthrough while a redraw is pending, and the question would be + /// eaten along with it. /// /// When `state.pending_enter` is set, the draw carries the /// alternate-screen entry in its prelude (and clears the flag once @@ -704,12 +765,17 @@ mod unix { } else { MAX_ATTEMPTS }; + // Whether a draw was left standing, as opposed to the attempts + // running out with the transmission still reported lost. + let mut settled = false; for attempt in 0..attempts { if attempt > 0 { std::thread::sleep(RETRY_PAUSE); } let cycle = !renderer.mux_stack.is_empty() - && (state.first_draw_done || state.force_cycle || attempt + 1 == MAX_ATTEMPTS); + && (state.force_cycle + || attempt + 1 == MAX_ATTEMPTS + || (state.first_draw_done && !can_repaint(renderer.mux_stack))); if cycle { if attempt + 1 == MAX_ATTEMPTS { state.fallback_draws += 1; @@ -758,12 +824,12 @@ mod unix { // Nothing to verify without a multiplexer, without an image, // or for animations (whose arrival has no cheap check). let Some(image_id) = drawn else { - state.force_cycle = false; - return Ok(()); + settled = true; + break; }; if renderer.mux_stack.is_empty() || animated { - state.force_cycle = false; - return Ok(()); + settled = true; + break; } // The answer window doubles as input: a key pressed during it // is discarded with the reply -- worth it under a multiplexer. @@ -772,19 +838,23 @@ mod unix { match session.ask(&request, VERIFY_TIMEOUT) { None => { state.verify_unanswered += 1; - state.force_cycle = false; - return Ok(()); + settled = true; + break; } Some(reply) if verify_reply_says_arrived(Some(&reply)) => { state.verified_ok += 1; - state.force_cycle = false; - return Ok(()); + settled = true; + break; } Some(_) => state.lost_transmissions += 1, } } - state.unrecovered += 1; + if !settled { + state.unrecovered += 1; + } state.force_cycle = false; + // Whatever draw is standing gets the repaint that makes it render. + repaint(renderer.mux_stack); Ok(()) } @@ -1294,6 +1364,30 @@ mod tests { ); } + #[cfg(unix)] + #[test] + fn only_a_lone_tmux_layer_can_be_repainted() { + use crate::slideshow::unix::can_repaint; + // `tmux refresh-client` repaints the client of the server named by + // $TMUX. That is the whole path to the terminal only when tmux is + // the single layer; anything outside it receives the repaint as an + // in-place pane update, which is what renders blank in the first + // place. These stay false whether or not we are inside tmux. + assert!(!can_repaint(&[]), "no multiplexer, nothing to repaint"); + assert!( + !can_repaint(&[Mux::Screen(None)]), + "screen has no equivalent" + ); + assert!( + !can_repaint(&[Mux::Tmux(None), Mux::Tmux(None)]), + "the outer tmux would see an in-place update" + ); + assert!( + !can_repaint(&[Mux::Tmux(None), Mux::Screen(None)]), + "a repaint cannot reach past an outer layer" + ); + } + #[test] fn direct_terminals_enter_the_screen_before_transmitting() { // Kitty-model terminals keep a separate image store per screen diff --git a/test/slideshow-test.sh b/test/slideshow-test.sh index fc4071d..1c7abca 100755 --- a/test/slideshow-test.sh +++ b/test/slideshow-test.sh @@ -92,8 +92,11 @@ ask_yn "Type something at the prompt: no stray characters, no raw mode leftovers if [ -n "${TMUX:-}" ]; then echo - echo "(Running inside tmux: a brief flash of the pane between slides is" - echo " expected, and a diagnostics line should have printed on exit.)" + echo "(Running inside tmux: slides are repainted with 'tmux refresh-client'," + echo " so there should be NO flash of the underlying pane between slides." + echo " A diagnostics line should have printed on exit.)" + ask_yn "Did every slide render fully -- no clipped or partial images?" || true + ask_yn "Did slides change without flashing the pane underneath?" || true ask_yn "Did the exit diagnostics report 0 'never arrived'?" || true fi From 30632aaa95f6651cf5a2b36473d875b0e32c1cfc Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:26:35 +0000 Subject: [PATCH 3/5] fix: settle before the repaint on draws that skip verification The repaint added in the previous commit runs after the attempt loop, on whatever draw is left standing. Two paths reach it without having waited for the multiplexer: an animated slide, whose arrival has no cheap check, and the message slide shown for a file that will not load. Both carry passthrough. An animation sends its frames and the `a=a` loop start -- the largest payload any draw produces -- and a message slide sends the delete of the image it replaces. `write_bytes` returns once the bytes reach the pty, not once tmux has parsed them, so `refresh-client` fired immediately after could schedule a redraw while that data is still in flight, and tmux drops passthrough while a redraw is pending. The symptom would be an animation stuck on a static frame, or an error message with the previous slide's image still underneath it. The verification path already pays this wait, and its reply proves the drain outright rather than assuming it. The two paths that skip verification now wait the same interval, and only when a repaint will actually follow. Reported by CodeRabbit on #40, which caught the animated path; the message-slide path is the same defect one branch up. Co-Authored-By: Claude Opus 5 (1M context) --- src/slideshow.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/src/slideshow.rs b/src/slideshow.rs index e6a4bed..d0dc253 100644 --- a/src/slideshow.rs +++ b/src/slideshow.rs @@ -821,13 +821,29 @@ mod unix { // now is what a panic must delete. session.arm_emergency_restore(restore_sequence(renderer.mux_stack, state.current_id)); + // The repaint after the loop must not land while this draw is + // still in flight: tmux drops passthrough while a redraw is + // pending, and every draw shape carries some -- an animation + // its frames and loop start, a message slide the delete of the + // image it replaces. The verification below pays that wait + // already, and its reply proves the drain outright; the two + // paths that skip verification have nothing, so they wait here + // instead, and only when a repaint will actually follow. + let settle_for_repaint = || { + if can_repaint(renderer.mux_stack) { + std::thread::sleep(VERIFY_SETTLE); + } + }; + // Nothing to verify without a multiplexer, without an image, // or for animations (whose arrival has no cheap check). let Some(image_id) = drawn else { + settle_for_repaint(); settled = true; break; }; if renderer.mux_stack.is_empty() || animated { + settle_for_repaint(); settled = true; break; } From a9e1cf79f7cb81b374ff028291ba8215bfc60495 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:26:35 +0000 Subject: [PATCH 4/5] test: skip the no-flash check where the repaint does not run The tmux questions were gated on $TMUX alone, which is set inside a nested tmux too. There kittyview cannot use `refresh-client` -- the outer layer would receive the repaint as one more in-place update -- so it falls back to the alternate-screen rebuild, and a flash between slides is correct behaviour rather than a failure. The honest answer then incremented FAIL and failed the script. The inner tmux reports its client's TERM, which names whatever sits outside it, so a `tmux*` or `screen*` value identifies the nested case. The no-flash question is now asked only where the repaint actually runs; elsewhere the script says a flash is expected and moves on. The rendering and diagnostics questions are unchanged, since those hold on every stack. Reported by CodeRabbit on #40. Co-Authored-By: Claude Opus 5 (1M context) --- test/slideshow-test.sh | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/test/slideshow-test.sh b/test/slideshow-test.sh index 1c7abca..28853d0 100755 --- a/test/slideshow-test.sh +++ b/test/slideshow-test.sh @@ -91,12 +91,30 @@ ask_yn "After quitting: is this terminal exactly as it was (prompt, scrollback, ask_yn "Type something at the prompt: no stray characters, no raw mode leftovers?" || true if [ -n "${TMUX:-}" ]; then + # kittyview repaints with `tmux refresh-client` only when tmux is the + # single layer between it and the terminal. Nested inside another + # multiplexer it falls back to the alternate-screen rebuild, where a + # flash between slides is expected rather than a failure -- so the + # no-flash question is asked only where the repaint actually runs. The + # inner tmux reports its client's TERM, which names that outer layer. + outer_term=$(tmux display-message -p '#{client_termname}' 2>/dev/null || echo) + case "$outer_term" in + tmux*|screen*) repaintable=no ;; + *) repaintable=yes ;; + esac + echo - echo "(Running inside tmux: slides are repainted with 'tmux refresh-client'," - echo " so there should be NO flash of the underlying pane between slides." - echo " A diagnostics line should have printed on exit.)" + echo "(Running inside tmux: a diagnostics line should have printed on exit.)" ask_yn "Did every slide render fully -- no clipped or partial images?" || true - ask_yn "Did slides change without flashing the pane underneath?" || true + if [ "$repaintable" = yes ]; then + echo "(Slides are repainted with 'tmux refresh-client', so there should be" + echo " NO flash of the underlying pane between slides.)" + ask_yn "Did slides change without flashing the pane underneath?" || true + else + echo "(Nested multiplexer -- outer TERM is '$outer_term'. kittyview falls" + echo " back to the alternate-screen rebuild here, so a brief flash between" + echo " slides is expected; skipping the no-flash check.)" + fi ask_yn "Did the exit diagnostics report 0 'never arrived'?" || true fi From d99609be9365c60ce6a88b1ee79ddcce858022f9 Mon Sep 17 00:00:00 2001 From: msample <4896732+msample@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:27:06 +0000 Subject: [PATCH 5/5] docs: note that unverified draws also wait before the repaint The upcoming entry described the repaint as ordered against the arrival check alone, which reads as though that check were the only thing keeping a redraw off a draw still in flight. Animations and the message slide skip it and wait on their own. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 59f5226..9b26827 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## upcoming -- **Slideshow images render fully under tmux, without the flash**: Ghostty through 1.3.1 renders placeholder images delivered as an in-place pane update blank or clipped -- with the data confirmed present in the terminal via the reply channel -- while a full repaint out of tmux's own grid renders them correctly. That is why switching tmux panes completes an image that came out partial. Every draw under a lone tmux layer now ends with `tmux refresh-client`: the same client repaint a pane switch triggers, re-sending nothing (the image is already in the terminal's store, the placeholder cells already in tmux's grid) and costing nothing visible. It replaces the alternate-screen rebuild 0.1.6 used for the same purpose, so slide changes no longer flash the pane underneath, nor pay the 250ms settle that rebuild needed. The repaint is issued after the arrival check, never before, since tmux drops passthrough while a redraw is pending and would eat the question with it. Where a repaint cannot reach -- screen, which has no equivalent command, and tmux nested in another multiplexer, whose outer layer would receive the repaint as one more in-place update -- slide changes still rebuild by way of the pane's main screen; that rebuild remains the last-attempt fallback when transmissions are being lost, and what the `r` key forces by hand. +- **Slideshow images render fully under tmux, without the flash**: Ghostty through 1.3.1 renders placeholder images delivered as an in-place pane update blank or clipped -- with the data confirmed present in the terminal via the reply channel -- while a full repaint out of tmux's own grid renders them correctly. That is why switching tmux panes completes an image that came out partial. Every draw under a lone tmux layer now ends with `tmux refresh-client`: the same client repaint a pane switch triggers, re-sending nothing (the image is already in the terminal's store, the placeholder cells already in tmux's grid) and costing nothing visible. It replaces the alternate-screen rebuild 0.1.6 used for the same purpose, so slide changes no longer flash the pane underneath, nor pay the 250ms settle that rebuild needed. The repaint is issued after the arrival check, never before, since tmux drops passthrough while a redraw is pending and would eat the question with it; the draws that skip that check -- animations, and the message slide shown for a file that will not load -- wait the same interval before the repaint instead, since they carry passthrough of their own. Where a repaint cannot reach -- screen, which has no equivalent command, and tmux nested in another multiplexer, whose outer layer would receive the repaint as one more in-place update -- slide changes still rebuild by way of the pane's main screen; that rebuild remains the last-attempt fallback when transmissions are being lost, and what the `r` key forces by hand. - `examples/placeholder_probe` gained a second group of variants (`manual`, `refresh`, `nudge`, `rewrite`, `cycle-refresh`) that bisect the *repair* rather than the draw: given a slide that rendered wrong, which nudge completes it. On Ghostty 1.3.1 + tmux only the two that force a full client repaint do -- unrelated terminal traffic does not, and re-sending the placeholder cells in place does not -- which is what settled the fix above. - `test/slideshow-test.sh` now checks for the absence of the inter-slide flash it previously told the tester to expect, and asks directly whether any slide came out clipped.