BrailleEssentials break cursor untether

[fcnjd]

@josephsl sorry for pinging you directly here, but I consider this issue as more important than the others I created, as it basically forces me daily to switch between activating and deactivating the addon.
When working in the console with constantly changing output, it is often necesary to untether NVDA cursor from system, to be able to read text while the current process is working. With Braille Essentials enabled, this breaks, and no matter if toggle to nvda cursor happens automatically by terminal detection, or manually with nvda+ctrl+t, it isn't working.
Steps to reproduce:

1. Open Bash and paste the following code:

#!/bin/bash

i=0

while true; do
  echo "Count: $i"
  ((i++))
  sleep 1
done

2. execute it and press NVDA+6 to untether cursor from system
3. Try to scroll up with the Braille display and wait a second - you'll be down again

I'd be happy to see this fixed soon. And an additional idea regarding this: As an extra to automatically switch to NVDA cursor when in terminal, which already is present, it could be an idea to automatically untether cursor when a button on the Braille display to scroll up/down is pressed, and re-tether if something on the keyboard is pressed. Then the display never shifts unexpectedly, but also reduces the affort of changing settings.

[josephsl]

Hi,

Let's focus on "untether" issue for now.

Which NVDA version is this? I'm using NVDA 2025.3.3 (portable), 2026.1.1 (portable), and alpha releases (installed) to test this scenario.

Thanks.

[fcnjd]

Hi,
thank you for your quick reply. Now I'm on 2026.1.1, but it already occured on 2026.1 before I made that minor update. If I do a restart with addons disabled, problem doesn't occur and cursor untethers as it should.

[fcnjd]

Just checked on another machine where I also have that problem: It's both a BrailleExtender and BrailleEssentials issue, deactivating one and activating the other doesn't help, disabling both fixes the problem.

[josephsl]

Hi,

June 2026 update: I am about to release Braille Essentials 26.07 (I don't think the issue is resolved though).

Thanks.

[fcnjd]

Hi, good you write, reminds me of the fact I wanted to report another finding to further narrow the issue down. When the option to auto switch to review mode for terminal is turned off, the issue isn't present - only with that option being enabled, maybe that helps to track it.
Thanks.

[josephsl]

Hi,

Yep, that narrows the issue (looks like I need to compare code paths). @dbernaca, any thoughts?

[josephsl]

Hi,

Technical: braille terminal module defines a private cursor synchronization routine that attempts to synchronize terminal caret with review cursor position (for braille, if I understand the routine correctly). However, its logic is incomplete: it assumes that "caret moves review cursor" (or its cousin, "focus moves navigator object") will not be a factor in its operation. I have edited this routine to do nothing if "caret moves review cursor" is disabled as the issue describes.

If things go well, I will include it in Braille Essentials 26.0-7 and perhaps propose a PR for Braille Extender.

Thanks.

[josephsl]

Hi,

Now July 2026 update: based on recent comment, I think I figured out a possible solution. Please try the attached try build (26.06.4000) and see if it fixes the issue.

Technical: in the patched "handle caret move" method, only handle caret changes if "caret moves review cursor" is enabled.

Thanks.

[josephsl]

Update: attaching .nvda-addon file is not supported, so here is a temporary try build download link:

https://github.com/josephsl/brailleEssentials/releases/download/26.05.4/brailleEssentials-26.06.4000.nvda-addon

[josephsl]

Hi,

As you test the try build, can you tell us which terminal app/emulator (Windows Terminal, Mintty, something else) you are using?

Thanks.

[fcnjd]

Hi,
thank you for your explanation, and the attached fix. I tried the above testing code I sent initially, and can confirm that the cursor again untethers properly. I'm using Git Bash on Windows11 as a terminal - but at least in CMD (or maybe let it be WSL) I went to properties and changed default away from Windows terminal back to classical conhost, I felt this is much more responsive than the terminal app. Not 100% sure, but I believe that already affects what's getting active when Git Bash is used.

[fcnjd]

... or maybe not. Had to find out, after another NVDA restart after the one required by addon install, it stopt working again. I'm sorry for that, right now cannot tell what opened the error path again. But what I can tell: It's the same terminal session I previously also used in the successful test, it is still open.

[josephsl]

Hi,

I see. This issue is complicated by a related patch in Braille Essentials/Extener where NVDA will forcefully set braille tether mode to review cursor when focusig on terminal windows. If nothing else works, you could disable "autmatically switch to review mode in termal" setting from the add-on settings, create a manually activated NVDA configuration profile, and switch o it whenever you need to work with terminal output with braille+caret moves review cursor off.

Thanks.

[fcnjd]

Hi,
the config is a good idea. Anyway, I came across something that could be related: Auto switch to review doesn't work when NVDA cursor is untethered, even in the trial update. Can be reproduced: NVDA cursor is set to follow caret. I open a git bash, dot 8 blinks. Then I press NVDA+6 (laptop layout) to untether the cursor, and then a down arrow press to recreate Braille cursor changes that to dots 78, indicating that NVDA cursor isn't used anymore. Switching it again with NVDA+6 so cursors are tethered again, another down arrow press brings back dot 7. Also, I had the impression (but that's not yet proven), that if I have the option to say current line while scrolling off (which I usually have), cursor untether works again. But haven't yet got it working often enough to say it very sure. Anyway, thought I'd mention that with the auto review cursor in case it somehow helps.
Thanks.

[josephsl]

Hi,

Reproducible with Windows Terminal (I am using WSL/Ubuntu).

Technical: when automatic review mode activation is on, only braille handler is told to tether to review only. When down arrow is pressed, cursor jumps becuase it could be seen as focus movement. Pressing Control+NVDA+T to switch braille cursor tethering to review mode solves the problem.

This points to looking at gain focus event in Braille Essentials/Extender's braille terminal patching code. This should be tested thoroughly in case editing gain focus handler breaks other apps.

Thanks.