Picker::from_query_stdio (and therefore, all examples) fail in Microsoft Windows

[mcclure]

Using release v4.2.0, I tried running the ratatui-image example apps, plus an app of my own design, on my Windows machine. I tested three ways: In the basic, ancient CMD.EXE "Command Prompt" box; in CMD.EXE in Windows Terminal; and "inside WSL1" in Windows Terminal (a WSL app can invoke a Windows exe; the Windows app runs in a little bubble of Windowsness, and STDOUT gets relayed back to the WSL terminal via a mostly-perfect, but not perfect, vtXXX translation layer).

In all cases, the test apps failed hard. I got combinations of failing with NoFontSize panics, failing with Timeout(Timeout) panics, printing a sequence of garbage characters before printing one of the above panics. However by removing calls to Picker::from_query_stdio, I was able to make ratatui-image render.

Examples

For my tests, I ran on Windows 10 22H2/19045.5247. I ran with Windows Terminal version: 1.21.3231.0. When in WSL, I am using "WSL1"; inside my WSL1 I have Ubuntu 20.04.6 LTS, and its packages are up to date. (So I have not proven for a fact any of this reproduces in WSL2, or with Windows 11, but as far as I know terminal handling is not a difference between WSL1 and WSL2.)

"Test 0": Establishing reality

To ensure I am not wasting your time, I check to ensure ratatui works on this system at all. For this I check out https://github.com/mcclure/tui-textarea , branch "ami", commit 58b93f5960b2, and test with cargo.exe run --example vim (followed by doing some vim stuff. a 0 4 7 [esc] [ctrl-P] :q! [return] is a good test). This is a clone of vim implemented in Rust+Ratatui. You do not need to run this test.

CMD.EXE: Works as expected.
CMD.EXE in Windows Terminal: Works as expected.
Bash in WSL1 in Windows Terminal: Works as expected.

Test 1: ratatui-image demo example

I clone the ratatui image and check out tag v4.2.0. I run cargo.exe run --example demo --features="crossterm".

CMD.EXE: Screen clears. A line of garbage (GI=something, various garbage, AAAA) appears in the upper left. Screen clears again, followed by a crash with:

thread 'main' panicked at examples\demo\main.rs:82:53:
called `Result::unwrap()` on an `Err` value: Timeout(Timeout)

CMD.EXE in Windows Terminal: Immediate crash with:

thread 'main' panicked at examples\demo\main.rs:82:53:
called `Result::unwrap()` on an `Err` value: NoFontSize

Bash in WSL in Windows Terminal: Apparently same as CMD.EXE. Screen clears. A line of garbage (Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA) appears in the upper left. Screen clears again, followed by a crash with:

thread 'main' panicked at examples\demo\main.rs:82:53:
called `Result::unwrap()` on an `Err` value: Timeout(Timeout)

(for example see: https://github.com/mcclure/tui-textarea , branch "orb-demo", commit 7e7341ba)

Test 1.1: What about termwiz?

If I try to run the examples without a --features line, it says one of "crossterm", "termion", or "termwiz" must be chosen. Could crossterm be the problem?

Termion (the crate itself) doesn't run on Windows at all, so ignore that.
I test with cargo.exe run --example demo --features="termion".

Results in all three environments: exact same as Test 1 except the error output lacks linebreaks

Test 2: async

In the repo from test 1, I run cargo.exe run --example async --features="crossterm".

CMD.EXE: Crashes with "Gi=31,s=1,v=1,a=q,t=d,f=24;AAAAError: Timeout(Timeout)"
CMD.EXE in Windows terminal: Crashes with "Error: NoFontSize"
Bash in WSL1 in WIndows Terminal: Crashes with "Gi=31,s=1,v=1,a=q,t=d,f=24;AAAAError: Timeout(Timeout)"

Seems to be the same as Test 1.

Test 3: Custom program

I check out https://github.com/mcclure/tui-textarea , branch "orb-demo", commit 7e7341ba. I test with cargo.exe run --example vim. This is a tiny crossterm app I wrote, it's supposed to display a color gradient.

CMD.EXE: Crashes with

Gi=31,s=1,v=1,a=q,t=d,f=24;AAAAthread 'main' panicked at examples\vim.rs:289:45:
called `Result::unwrap()` on an `Err` value: Timeout(Timeout)

The relevant line is Picker::from_query_stdio().unwrap();

CMD.EXE in Windows Terminal: Crashes with

thread 'main' panicked at examples\vim.rs:289:45:
called `Result::unwrap()` on an `Err` value: NoFontSize

Bash in WSL1 in Windows Terminal: Crashes with

Gi=31,s=1,v=1,a=q,t=d,f=24;AAAAthread 'main' panicked at examples\vim.rs:289:45:
called `Result::unwrap()` on an `Err` value: Timeout(Timeout)

All three of these are crashing on the line let picker = Picker::from_query_stdio().unwrap();.

Test 4: Custom program without Picker::from_query_stdio()

The problem appears to be Picker::from_query_stdio. I notice the ratatui-image README contains an example of booting up with Picker::from_fontsize instead, although it recommends not to use it. Still in the https://github.com/mcclure/tui-textarea repo, I modify the test app to catch Timeout and NoFontSize errors and assume fontsize 8,12 in that case. I save this as 7ef6507942e7. Running this with cargo.exe run --example vim:

CMD.EXE: Runs and displays at quarter-block size. For some reason, input is locked out and I cannot quit, although the version of this program without ratatui-image ("test 0" above) did not have this problem. I do not know if this is caused by ratatui-image or my own code.
CMD.EXE in Windows Terminal: Runs and displays at quarter-block size (image below). Input works and I can quit by typing :quit or pressing q.
Bash in WSL1 in Windows Terminal: Identical to CMD.EXE (including being locked up).

In CMD.EXE in Windows Terminal, the program looks and runs exactly the same as it does in Debian 12.8 on my laptop, so for purposes of this bug this is a success.

Analysis

There appear to be two paths in Windows, a "Good" path you get by using CMD.EXE directly in Windows Terminal and a "Mediocre" path you get by any other means. Both paths fail with Picker::from_query_stdio, but with different errors.

There might be a second bug that causes apps using ratatui-image to lock up in the Windows "bad path" when running with from_fontsize, but I cannot prove this yet. If I find there is a bug, I will file it separately.

"Expected behavior"

Main expectation:

• At minimum, I would expect that if from_query_stdio() fails on any major platform (even "mediocre path" Windows) then the documentation should reflect that:
  • The function documentation should warn that failure is expected on some platforms;
  • The examples ("async", "demo") should detect that they are on a bad platform and correct for this, so crate users know what proper usage is;
  • And the README, in the "quick start" program, the comment "Should use Picker::from_query_stdio() to get the font size and protocol" should be changed to "Should try Picker::from_query_stdio() first to get the font size and protocol" (the current text implies that from_query_studio is preferred in all cases).

Minor expectations:

• In the "good path": Windows is a common platform, and judging from past issues you seem to have put some effort into supporting Windows Terminal, so I would expect Windows Terminal to be fully featured: I would expect Picker::from_query_stdio() to work in Windows Terminal. If Windows terminal does not offer the capabilities you need to make this work, I would recommend filing a github issue on Windows Terminal, as in my experience that team is very receptive to developer asks.
• The "mediocre path": If it turns out that you inherently cannot detect font size on some Windows hosts, such as original CMD.EXE, I would expect that in this path you should fail with NoFontSize rather than Timeout. "Oops, I'm on Windows" is a definitely detectable situation. I think "Timeout" should indicate only an actual timeout and not a systematic platform issue.

[j4james]

CMD.EXE: Screen clears. A line of garbage (GI=something, various garbage, AAAA) appears in the upper left.

I'm assuming this is on Windows 10. If you're using the old conhost terminal, that's going to be years out of date, and it didn't originally support APC sequences, so the content of the sequence will just be echoed to the screen. In this case you're seeing the APC query that detects kitty graphics.

As for the later Timeout error, I think that's probably waiting for the DSR-OS response, which was also not supported on the old conhost terminal.

CMD.EXE in Windows Terminal: Immediate crash with: NoFontSize

This will be because you're using Windows Terminal 1.21, and support for querying the font size was only added in version 1.22.

Bash in WSL in Windows Terminal: Apparently same as CMD.EXE.

This is a bit weird, unless you're running a Windows executable from within a WSL shell. Are you trying to run an .exe file, or an actual Linux build of the app? Because if it's the former, you're effectively just using the old version of conhost, and then the output from that gets forwarded to Windows Terminal. From a VT point of view, the app isn't really being run in Windows Terminal.

In summary, I think most of these problems (at least from test 1) should eventually be resolved with a newer version of Windows and/or Windows Terminal. There likely will still be other terminals that are similarly affected though.

[mcclure]

This will be because you're using Windows Terminal 1.21, and support for querying the font size was only added in version 1.22.

When I ask Windows Terminal to check for updates it says there are none, and the most recent release listed at Windows Terminal is v1.21.3231.0 . Am I missing something, or do you mean I need to wait for the next stable release?

In summary, I think most of these problems (at least from test 1) should eventually be resolved with a newer version of Windows and/or Windows Terminal

I believe this and as a user this is enough, but as a developer I would like to be able to integrate ratatui-image into my app without consequences such as my program crashing. I expect to be able to run ratatui-image in a way where if it doesn't like the environment it degrades to halfblocks. To use ratatui-image this way, I must do things that are currently not documented, so I think at minimum the documentation should be amended.

This is a bit weird, unless you're running a Windows executable from within a WSL shell. Are you trying to run an .exe file, or an actual Linux build of the app?

I am trying to run a Windows executable from within a WSL shell. I do this because I don't know how to use CMD.COM but I do know how to use Bash. So I install WSL, I get a nice bash environment, I get git and hg and all these things, and then when I want to build an application I run cmake.exe or cargo.exe and now I am building and running real windows executables with full windows compatibility. I recognize it is a little odd, but it works, and there is no reason it shouldn't work, or at least, I'd expect it not to crash. If I get a slightly degraded terminal experience because I executed the binary in a weird way that's acceptable, but not a crash.

[j4james]

do you mean I need to wait for the next stable release?

Yeah. Version 1.22 is in preview at the moment. Version 1.21 is the current stable release. Note that you can install both at the same time if you want to try out the preview.

I believe this and as a user this is enough, but as a developer I would like to be able to integrate ratatui-image into my app without consequences such as my program crashing.

Sorry, I didn't mean to imply that your issue wasn't valid. My response was partly intended as an FYI for the ratatui-image maintainers, so they know why these errors are occurring on Windows Terminal. Hopefully that's of some help in deciding how best to address the problem.

I recognize it is a little odd, but it works, and there is no reason it shouldn't work,

If it works for you, that's great. I just wanted you to be aware that you're effectively running a 5 year old version of the terminal with loads of bugs, and it's likely never going to be updated (unless you update Windows itself). If you just want a bash-like environment from which you can run Windows apps, you may be better off with git bash.

[benjajaja]

My takeaway from this is that "Timeout: " should really be something more specific like "No response from terminal", and then maybe try to convert Timeout error into NoFont which perhaps conceptually is what matters.