docs: add Tolk NVDA presence compatibility design

docs/superpowers/specs/2026-04-10-tolk-nvda-presence-design.md

@@ -0,0 +1,195 @@
+# Tolk NVDA Presence Compatibility Design
+
+## Goal
+
+Allow applications running under Wine or Proton to use the official upstream `Tolk.dll` unchanged while routing Tolk speech through the existing Linux NVDA-to-Cthulhu path.
+
+The compatibility layer must satisfy only the checks that Tolk performs when selecting its NVDA driver. It must not require replacing `Tolk.dll`, patching Tolk, or using a Tolk-specific DLL override.
+
+## Confirmed Constraints
+
+- The shipped `Tolk.dll` must remain the official upstream binary.
+- The existing `wine2speechd` package already provides replacement `nvdaControllerClient32.dll` and `nvdaControllerClient64.dll` implementations for Linux.
+- The current blocker is Tolk detection, not the downstream speech transport.
+- Scope is limited to making Tolk believe NVDA is present; broader NVDA emulation is out of scope.
+
+## Current Tolk Behavior
+
+From `tolk/src/ScreenReaderDriverNVDA.cpp`, Tolk considers NVDA active only when both of the following succeed:
+
+1. `nvdaController_testIfRunning() == 0`
+2. `FindWindow(L"wxWindowClassNR", L"NVDA")` returns a window handle
+
+If either check fails, Tolk will not select the NVDA driver and speech output through Tolk will fail.
+
+## Recommended Approach
+
+Extend the existing Wine NVDA compatibility stack with a minimal NVDA presence helper. The solution has two parts:
+
+1. The existing custom NVDA controller DLLs continue handling `nvdaController_*` API calls and forwarding them into the Linux bridge.
+2. A lightweight Windows helper process running inside Wine creates the exact window Tolk expects for NVDA detection.
+
+This keeps the official `Tolk.dll` untouched and confines the compatibility contract to Tolk's actual checks.
+
+## Architecture
+
+### 1. NVDA controller DLLs
+
+The custom `nvdaControllerClient32.dll` and `nvdaControllerClient64.dll` remain the Wine-visible implementation that applications and Tolk load.
+
+Required behavior:
+
+- `nvdaController_speakText` forwards speech to the existing Linux bridge.
+- `nvdaController_brailleMessage` continues current behavior.
+- `nvdaController_cancelSpeech` continues current behavior.
+- `nvdaController_testIfRunning` returns success only when the Linux bridge is reachable and the compatibility environment is operational.
+
+`nvdaController_testIfRunning` must not return success solely because the DLL loaded. It is the main guard against false positive Tolk detection.
+
+### 2. NVDA presence helper
+
+A small Windows executable is added to the Wine-side compatibility package. Its only job is to create and maintain a top-level window with:
+
+- class name: `wxWindowClassNR`
+- window title: `NVDA`
+
+Required behavior:
+
+- starts quickly and remains idle
+- single-instance per Wine prefix or session
+- exits cleanly without user interaction
+- does not present visible UI unless Wine forces a window surface
+- can be launched independently or on demand by the controller DLL
+
+### 3. Startup coordination
+
+The presence helper must be running before Tolk calls `FindWindow`, or Tolk detection will fail.
+
+Acceptable coordination strategies:
+
+- preferred: launch the helper as part of the existing Wine accessibility startup path
+- acceptable: lazily launch the helper the first time the custom NVDA DLL is loaded, then wait briefly for the window to appear
+
+The preferred strategy is external startup rather than in-DLL process creation because it separates concerns and avoids loader-time side effects.
+
+## Detection Contract
+
+Tolk compatibility is considered successful only when all of the following are true:
+
+- official `Tolk.dll` loads normally
+- Tolk loads the custom NVDA controller DLL
+- `nvdaController_testIfRunning()` returns `0`
+- `FindWindow(L"wxWindowClassNR", L"NVDA")` succeeds
+- `Tolk_DetectScreenReader()` returns `NVDA`
+- `Tolk_Output()` delivers speech through the existing Linux bridge
+
+If the Linux bridge is unavailable, the compatibility layer must fail closed:
+
+- `nvdaController_testIfRunning()` returns failure
+- Tolk does not report NVDA as active
+
+The dummy NVDA window alone must never make Tolk think speech is available.
+
+## Packaging
+
+The compatibility feature belongs with the Wine NVDA compatibility stack, not in Tolk itself.
+
+Expected package contents:
+
+- `nvdaControllerClient32.dll`
+- `nvdaControllerClient64.dll`
+- `nvda-presence-helper.exe` or similarly named helper
+- startup integration so the helper is available in Wine and Proton environments where Tolk-based games run
+
+No `Tolk.dll` replacement or override is added.
+
+## Error Handling
+
+### Bridge unavailable
+
+- `nvdaController_testIfRunning` returns failure
+- speech-related entry points return the existing failure behavior
+- Tolk should not detect NVDA
+
+### Helper missing or failed to start
+
+- `FindWindow` fails
+- Tolk should not detect NVDA
+- logging should identify missing helper startup distinctly from bridge connectivity failures
+
+### Duplicate helper instances
+
+- duplicates must resolve harmlessly, preferably by allowing one owner and exiting the rest
+
+## Logging
+
+Add targeted logging in the compatibility layer only. Logging should make these states distinguishable:
+
+- controller DLL loaded
+- bridge connectivity check succeeded or failed
+- presence helper started
+- presence window created
+- Tolk compatibility ready
+
+No Tolk-side logging changes are needed because Tolk is not being modified.
+
+## Testing
+
+### Functional test
+
+Create or reuse a small Wine test application that:
+
+1. calls `Tolk_Load()`
+2. calls `Tolk_DetectScreenReader()`
+3. calls `Tolk_Output(L\"test\", false)`
+
+Expected result with bridge and helper active:
+
+- `Tolk_DetectScreenReader()` returns `NVDA`
+- speech reaches Cthulhu through the existing NVDA path
+
+### Negative tests
+
+1. Bridge down, helper up:
+   `Tolk_DetectScreenReader()` must not return `NVDA`
+2. Bridge up, helper down:
+   `Tolk_DetectScreenReader()` must not return `NVDA`
+3. Both down:
+   `Tolk_DetectScreenReader()` must not return `NVDA`
+
+### Regression check
+
+Verify that existing non-Tolk NVDA speech consumers continue using the current `wine2speechd` path without requiring Tolk-specific configuration.
+
+## Out of Scope
+
+- adding a plugin mechanism to Tolk
+- maintaining a Tolk fork
+- broader NVDA desktop emulation beyond what Tolk checks
+- compatibility with applications that perform additional NVDA-specific probing outside the current `wine2speechd` contract
+- anti-cheat or anti-tamper guarantees beyond avoiding Tolk replacement
+
+## Risks
+
+### Wine window behavior
+
+The helper must create a window that `FindWindow` can discover reliably under Wine and Proton. If Wine normalizes or alters class registration behavior, the helper may need adjustment.
+
+### Timing
+
+If a game calls Tolk very early, helper startup races could cause intermittent detection failure. This is why pre-starting the helper is preferred.
+
+### Split responsibility
+
+The controller DLL and helper must agree on readiness. If they drift apart, Tolk may see the window but still fail to speak. The fail-closed `testIfRunning` check is the protection against this.
+
+## Recommendation
+
+Implement the feature in the existing Wine NVDA compatibility stack, not in Tolk and not in Cthulhu core.
+
+The smallest correct implementation is:
+
+1. fix or confirm `nvdaController_testIfRunning()` behavior in the custom DLL
+2. add a minimal Wine helper that exposes the NVDA window Tolk checks for
+3. wire startup so the helper is available before Tolk detection occurs
+4. verify with a small Tolk test program under Wine