testing-speaktype-desktop

name	testing-speaktype-desktop
description	How to end-to-end test the SpeakType Windows desktop app (Electron, desktop/ dir) — launch flags, Doubao login workaround, synthetic hotkeys, store locations, known traps.

Testing SpeakType Windows desktop (Electron)

Round 247 learnings (packaged v0.16.0)

• Sherpa worker model-switch bug (may persist): switching local models mid-session (parakeet→sensevoice, whisper→sensevoice) makes the sherpa worker eval fail with SyntaxError: Identifier 'gc' has already been declared; every retry fails until the app process is fully restarted. A COLD start with the model already selected initializes fine. Preflight before any sensevoice-dependent test: check %APPDATA%\SpeakType\logs\main.log for sherpa worker started (...) with NO following sherpa worker error; if the error appears, restart the app rather than clicking Retry.
• MoveWindow trap: the SpeakType main window is often maximized; MoveWindow silently no-ops on a maximized window (returns True). Click the restore button first, then resize (see C:\Users\Administrator\tts\resize.ps1, targets Get-Process SpeakType MainWindowHandle).
• Theme flip helper that works non-interactively: C:\Users\Administrator\tts\theme.ps1 -v 0|1 (sets both Personalize values + broadcasts ImmersiveColorSet).
• When AI polish is enabled with the mock server, ALL dictation output becomes the MOCK-REWRITE: prompt echo — disable AI polish before testing plain dictation/whisper switching, or results look garbled.
• Persona app-rule verification: History items show time · <persona name> · duration · Local offline; the rule persona also appears inside the mock-rewrite prompt echo (style instructions section), which is independent corroboration.
• This VM may lack the historical C:\Users\Administrator\tts assets; verify rkey.ps1/hf246.wav/sample.wav exist before recording, and note in the report if they had to be re-synthesized.

Timing-sensitive fake-mic WAVs (pause/paragraph tests)

• sample.wav contains ~0.64s leading and ~2.21s trailing INTERNAL silence around the speech. When concatenating it with fixed silence gaps to test pause-duration logic (e.g. hands-free paragraph breaks measured last-voice→first-voice), those internal silences inflate the intended gap by ~2.85s and can flip the verdict. Trim the PCM to first/last sample with |peak|≥1000 before concatenating (see C:\Users\Administrator\tts\r354\gen354.mjs).
• Also note the fake mic LOOPS the WAV: add a long tail silence and exit hands-free during the tail, or the loop restart appears as another long-gap sentence.

Network-blocking tests (download failure simulation) — CRITICAL traps

• NEVER enable Windows Firewall on this box (netsh advfirewall set allprofiles state on): it severs the Devin control channel instantly; recovery needed a VM reboot. The firewall is intentionally OFF, so program-scoped firewall block rules are silently ineffective too.

• hosts-file blocking may silently stop working (entries present, ANSI encoding fine, flushdns/Dnscache OK, but ping still resolves real IPs). Always verify with ping <domain> that blocking is effective BEFORE relying on it — a "blocked" download that succeeds means the block never applied.

• Null routes (route add <ip> mask 255.255.255.255 <bogus-gw>) do NOT block here (virtual NAT proxy-ARPs everything). Proxy env vars (HTTPS_PROXY) are ignored by Node/undici fetch in the Electron main process.

• Working method: IPsec static policy (independent of firewall profiles): netsh ipsec static add policy name=P; add filterlist name=F; add filter filterlist=F srcaddr=me dstaddr=<ip-or-net> [dstmask=...] protocol=TCP mirrored=yes; add filteraction name=A action=block; add rule name=R policy=P filterlist=F filteraction=A; set policy name=P assign=y. Block 143.204.0.0/16 (huggingface CF), hf-mirror IP, github.com IP, 185.199.108.0/22 (GH release CDN). Verify with node fetch (UND_ERR_CONNECT_TIMEOUT ≈10s per source). Cleanup: set policy assign=n; delete policy/filterlist/filteraction.

• Simplest reliable block for packaged builds: patch app.asar — npx asar extract resources/app.asar tmp, string-replace the three source hosts in out/main/index.js (https://huggingface.co/, https://hf-mirror.com/, the GH models-v1 release base) with https://127.0.0.1:1/…, npx asar pack back (back up app.asar first). Fetch to 127.0.0.1:1 fails instantly (no 10s/source timeout like IPsec) and exercises the genuine network-error path; asar integrity is not enforced (app boots fine, verified 0.15.1/Electron 43). Restore the original asar afterwards.

• Re-confirmed 2026-08-17: HTTPS_PROXY=http://127.0.0.1:1 is ignored by Node fetch in Electron main (status 200 through "fake proxy"); hosts blocking remains dead on this box — always ping to verify before trusting any block.

• Partial-progress display: since #130 (d383cbe) any COMPLETE file on disk counts as progress, but since #261 (652f34e) percent <1% returns null — tokens.txt-only (no .part) shows plain again; a real .part with meta still shows . A resumed download's final file can be verified by sha256 == c71f0ce0… (the HF LFS oid in download.ts GH_ASSET_SHA256).

This is separate from the Chrome extension skill (testing-speaktype). Do NOT test the desktop app via the extension procedure.

Memory-soak diagnostics on the packaged build (round 276)

• The packaged SpeakType.exe accepts --inspect=9229: http://127.0.0.1:9229/json exposes the main-process Node inspector ws. Over that ws, Runtime.evaluate needs includeCommandLineAPI: true or require is undefined and every eval silently returns undefined.
• Reusable scripts in C:\Users\Administrator\tts\r366\: memsample.ps1 (per-role WS/PM csv every 60s, classifies main/renderer/gpu/network by CommandLine), heappoll.cjs (process.memoryUsage + v8.getHeapStatistics csv via inspector; needs node >=22 for global WebSocket — use C:\hostedtoolcache\node\24.0.1\x64\node.exe), snap.cjs (v8.writeHeapSnapshot to a file; the write itself bloats RSS/PM by ~60-70 MB, so take the final snapshot AFTER the last csv sample you intend to use, and exclude snapshot minutes from slope fits).
• TRAP: with an inspector client attached, tray Quit does NOT complete — main + gpu + utility processes linger until the debug client disconnects; kill the poller and the app exits cleanly within seconds. Don't misreport this as a quit hang.
• Slope methodology: least-squares over the csv, computed separately for first-30 and last-30 minutes; the first ~30 min contain allocator warm-up (~0.2 MB/min) that converges to ~0. Endpoint-to-endpoint deltas over short windows (like round 275's 37 min) overstate the slope.
• Baseline from this round (0.17.0 @ 6a0f1f0, sensevoice hands-free ~6 utterances/min): main heapUsed flat 16-18 MB, arrayBuffers 0, external oscillating 5-10 MB, PM plateau ≈495 MB, last-30-min PM slope ≈0.

Round 258 learnings (Silero hangover A/B methodology)

• Segment-count is the strongest single signal for Silero segmentation fixes on the 2.2s-gap fixture (silero256d.wav, 32 short sentences): broken hangover → ~12 heavily-merged segments; fixed → ~41; peak baseline → ~37 with all heads intact. Count segments from history.json before eyeballing text.
• Two runs in one app session can share one history.json: record the pre-run count N and slice history.slice(0, len-N) for the delta — avoids restarting the app between A and B when only the Enhanced VAD toggle changes (toggle applies live, no restart needed).
• Freshly launched SpeakType steals foreground focus; ALWAYS screenshot-verify Notepad focus after every app (re)launch before Ctrl+A/Delete/Alt+Q. A run started with SpeakType focused pastes nothing ("No text field in focus" toast) but still writes history — history-based counting stays valid, on-screen text does not.
• Residual Silero anomaly signature to look for even after fixes: pairs of 需要换行处理。 (head lost) followed by segments ending …我/我们 (that head glued to previous tail) — count them as pairs, not independent errors.

Round 257 learnings (ASR language + Silero model preflight)

• settings.language MUST be zh for Chinese fixture tests. The user's real config has language: "en"; with en, SenseVoice transcribes Chinese TTS as pinyin garbage ("H Huang Hang.", "Lin Qi.") and command words never match — this silently invalidates whole VAD/command runs. Preflight: node -e "...settings.language" and set zh in test userData before any Chinese run.
• Silero model preflight: fresh test userData needs %APPDATA%\SpeakType\vad\silero_vad.onnx (a copy lives at C:\Users\Administrator\silero_vad.onnx). The Enhanced VAD toggle turns green even when the model is missing and main.log logs NOTHING about silero — the only visible confirmation is the Settings hint text "Add-on ready — voice detection upgraded". Behavioral tell: with the model, 2.2s-gap fixtures produce merged 10-18s captures; without it, capture cuts at every gap like peak mode.
• rkey.ps1 maps only rctrl/etc — it does NOT know lalt/q; Alt+Q must be sent with the computer-use key action (works as a global hotkey regardless of focus).
• Alt+Q during an in-flight utterance still finalizes and pastes that utterance once (by design, like hold release); "no residual" means nothing further lands afterwards.
• Looping a short (<2s) command WAV with no silence gap never finalizes (continuous speech); command fixtures need ≥2.5s trailing silence inside the file.
• Clicking the Notepad taskbar icon sometimes raises SpeakType instead — always screenshot-verify focus before Ctrl+A/Delete (a stray Ctrl+A+Del into SpeakType is harmless but wastes a cycle).

Frameless-window drag region swallows clicks (general trap)

• The main window's top strip (~y<45 when maximized) is a -webkit-app-region: drag zone: clicks on any in-app button/link that scrolls up into that strip do nothing (or activate a background window if the click lands outside the app). Symptom: repeated clicks on a visibly rendered button with no effect. Fix: scroll the page so the target sits below y≈100, then click. (Same root cause as the History Show all/Show less note below.) Note: builds after PR #352 give <main> a mt-10 margin so content can no longer scroll under the strip — this trap only applies to pre-#352 builds.

Launch (dev and installed)

• Dev: cd desktop && npx electron out/main/index.js <flags> (build with npm run build first).
• Installed (NSIS): %LOCALAPPDATA%\Programs\SpeakType\SpeakType.exe <flags>.
• Required flags in this environment: --no-proxy-server --use-fake-device-for-media-stream --use-fake-ui-for-media-stream --use-file-for-fake-audio-capture=C:\Users\Administrator\tts\sample.wav plus --remote-debugging-port=9333 when you need CDP.
• WHY --no-proxy-server: Electron follows Windows system proxy (registry points at socks 127.0.0.1:1080 which is NOT listening here) → doubao.com fails with ERR_PROXY_CONNECTION_FAILED. Chrome on this box is launched without proxy so it works; Electron needs the explicit override.
• Fake mic works exactly like Chrome; the wav loops, sentence: 「帮我跟老板说那个方案需要再改一下明天上午之前给他答复」.

Crafting fake-mic WAVs (PR #44 lessons)

• System.Speech WAVs contain a LIST chunk after fmt — the data chunk is NOT at offset 44. Naively rewriting sizes at offsets 4/40 yields a file Chrome's fake capture plays as pure silence (dictation logs maxPeak=0 voicedMs=0). Parse chunks, extract the data PCM, and rebuild a canonical 44-byte-header wav (see C:\Users\Administrator\tts\makehf2.ps1).
• Continuous hands-free (Alt+Q) can be tested deterministically: fake-capture loops the file, so a wav of speech + ~4s trailing silence makes every loop one auto-finalized sentence (silence > vadSilenceMs=2000 triggers finalize, hands-free auto-restarts). A pure-silence wav drives the 6×10s no-voice rounds → auto-exit toast in ~62s.
• Verify toasts objectively with CDP polling of the toast.html target (C:\Users\Administrator\tts\toastpoll44.cjs, needs --remote-debugging-port).

Doubao login inside Electron (independent cookie jar)

• No doubao credentials on the box. Workaround: copy Chrome's doubao.com cookies into the Electron session via CDP (C:\Users\Administrator\tts\cookie_xfer.js: reads Chrome's cookies on port 29229/2513, writes via Electron's 9333 using Storage.setCookies). Reload the bridge window after injecting.
• Then the real activation flow works: home 去激活 → doubao window → click its built-in voice input once (fake mic) → WS hook captures api_app_key into the store (doubaoAppKeyCache).

Store / userData locations

• Dev: %APPDATA%\Electron\speaktype.json.
• Installed/packaged since 0.8.x: %APPDATA%\SpeakType\speaktype.json (older builds used %APPDATA%\SpeakType 语音输入法\ — the app auto-migrates from it on first launch, so when testing a "fresh config" you must rename both dirs away, otherwise the legacy config is migrated back in and the test is invalid: look for migrated legacy userData from … in main.log).
• Offline model lives in %APPDATA%\SpeakType\models\sensevoice-small\{model.int8.onnx (239MB), tokens.txt}; keep a copy outside the config dir so a fresh-config run can restore it instead of re-downloading. downloadLocalModel skips files that already exist, so copying them in before clicking 下载 makes the card finish instantly (still logs local model … downloaded).
• To simulate "not activated": quit app, set doubaoAppKeyCache to "", relaunch → hold RightCtrl shows Chinese toast 「还没拿到豆包语音入口…」. Back up the file first.

Offline (SenseVoice) live captions

• Offline live captions are approximated by re-decoding the buffered audio every ~1s (asr.ts PARTIAL_* consts): preview starts after 1s of audio and stops once the buffer exceeds 20s; the final result is still decoded on release. To prove it, zoom on the floating panel at ~8s and ~16s (text must grow) and again at ~25s (frozen/shorter than the final pasted text) during a >27s hold.
• Decoding is synchronous in the main process; during long re-decodes the whole UI (and CDP) can stall briefly. If the window stays white and all CDP targets time out, the main process is wedged — kill and relaunch (seen once on 0.8.3).

Auto-learn corrections (0.8.5 watchedit.ts)

• Trigger conditions: autoLearn && autoPaste && !failed && text contains Chinese (dictation.ts finalize). Watcher = hidden powershell.exe -NonInteractive child of SpeakType polling the UIA focused element every 700ms for 15s (deadline starts inside PS, so add ~2-3s startup slack).
• Notepad classic Edit works via the Name-property fallback (full text incl. Chinese; verified with a standalone probe replaying the same UIA script).
• To make a correction that actually learns: the changed segment after common-prefix/suffix trimming must be a 2-6 char pure-Chinese word on the "right" side. Replacing 方案→草案 does NOT learn (shared 案 → diff becomes 方→草, 1 char). Use replacements sharing no boundary chars (答复→回执). Make the edit within ~3-13s after paste (before 15s deadline, after PS's first sample).
• Learning evidence: main.log auto-learn: "X" -> "Y" (mojibake in console is normal — read speaktype.json as UTF-8/base64), settings.hotwords appended, history text replaced. Since 6eaa42a the renderer refreshes immediately after a learn (learnCorrection calls pushSettings); Dictionary/History should show the new state without touching settings.
• When counting watcher processes, exclude your own shell: filter Win32_Process powershell.exe by ParentProcessId ∈ SpeakType PIDs, and never put match-strings like 'FocusedElement' in your own command line (it self-matches).
• Cross-window false positive (found in 0.8.5 first cut): typing Chinese in ANOTHER focused control during the 15s window could be mislearned. Fixed in 6eaa42a — the observer binds to the baseline control's UIA RuntimeId; re-verified that typing in SpeakType's search box after paste no longer learns.
• Incremental learning (0.9.1, 6f03041): each ~1.5s edit pause settles a round (toast per word), baseline rolls, LCS splits one big edit into multiple words. Testing traps: (a) the observation window is only WATCH_SECONDS=20 from the last text change — it does NOT extend while the user is merely idle, so edits starting >~20s after paste are silently missed (found as a real gap vs the "25s still learns" claim); batch click+select+type into ONE computer-use call, tool round-trips of 3-4s easily blow the window; (b) word pairs must share NO boundary chars or prefix/suffix trimming shrinks the diff below the 2-char threshold (明天→后天 shares 天 → only 明→后 → not learned, by design); (c) the History page "Clear all" button next to the search box wipes ALL history with no confirm — don't click it to clear the search filter.

App-based persona rules

• Personas page → 「按应用自动切人设」→ 添加规则 → match text (matches process name OR window title, case-insensitive) + persona dropdown. The rule is evaluated at record start from the foreground window, and with no LLM configured it only shows up as the personaName on the history item (History list shows HH:MM · <persona> · <secs> · Local offline).
• Always run the counter-test (foreground = a non-matching window, e.g. the SpeakType window itself) — it must record the global persona instead, otherwise a hardcoded persona would look like a pass.

Synthetic hotkeys (uiohook sees SendInput)

• Use C:\Users\Administrator\tts\rkey.ps1 -Seq "down:rctrl,sleep:8000,up:rctrl" (scancode SendInput). Works for RightCtrl hold, Alt+Space, Alt+digits (d1..d9), Alt+Q (q key added for PR #16), f6, esc (added for 0.8.6 hotkey-capture tests). If a key is missing from the script's $map, the script silently no-ops — add the VK/scancode pair before concluding a hotkey is broken.
• Hotkey capture (0.8.6 「录一个键」): the 10s capture window is easily missed if you press the key via a fresh exec shell (PowerShell startup can exceed 10s) — the button silently reverts and it looks like capture is broken. Press within the window via the computer-use key action (F6/Escape work) or a pre-warmed shell. Middle mouse: computer-use middle_click on any blank area is seen by uiohook. Auto-repeat bug found in 509ba94 (holding the OLD hotkey during capture triggered a real dictation via key-repeat keydowns) was fixed in c025093 (captureSwallowKeycode swallows that key until its keyup) — re-verified: hold 1.8s captures cleanly with no finalize, and normal dictation works right after.
• Persona toast lasts 2.6s — screenshot immediately, or verify via store settings.personaId change.
• Home page stats/activation card do NOT live-refresh in all cases; stats refresh on app restart.

Known traps

• Alt+Space is the Windows system-menu key of the focused app (e.g. Notepad) — a paste issued while that menu modal is open is lost. Default toggle is Alt+Q since PR #15; if testing Alt+Space anyway, note AutoGLM (AutoGLM.exe, auto-running on this box) ALSO swallows it globally — kill it (taskkill /f /im AutoGLM.exe) first.
• Fixed in PR #15 (don't re-report): tray icon missing from the installed package; error panel not auto-hiding (now hides after 5s); home activation card not refreshing after key capture.
• Several stale orange tray icons from killed electron.exe dev runs linger in the tray overflow; hover to clear them.
• This VM has NO audio output device (Get-CimInstance Win32_SoundDevice empty, taskbar speaker shows red X) — the "mute other apps while recording" switch (VK_VOLUME_MUTE) has no observable effect here; mark it untested rather than inferring.
• System locale resolves to English, so with uiLanguage: "system" (fresh store) the app starts in English — useful baseline for i18n tests (since PR #16).
• Dev runs show the Electron version (e.g. 43.3.0) as the app version in sidebar/About (app.getVersion()); only the packaged app shows the real product version.
• Computer-use type action into the app sometimes drops shifted/capital letters (e.g. "SpeakType" → "peakype") — an input-injection artifact, not an app bug; verify chip text before reporting.
• Launching rkey.ps1 via Start-Process -WindowStyle Hidden can steal the foreground window: the release-Ctrl+V then pastes into the hidden PowerShell instead of the target (looks like "paste failed" while transcription/history are fine). Workaround: re-click the target window during the hold, or diagnose with C:\Users\Administrator\tts\fg_watch.ps1.
• Rewrite-selection (0.8.7): C:\Users\Administrator\tts\mock_chat.mjs is a local OpenAI-compatible chat-completions mock (http://127.0.0.1:8975/v1, logs each prompt, returns fixed "[REWRITTEN-BY-MOCK]" text) — use it for the rewrite E2E when no real LLM key works. secret:personal:DEEPSEEK_API_KEY was Insufficient Balance (HTTP 402) as of 2026-08-10; verify with the settings-page Test connection button before relying on it. The computer-use type action drops : in URLs (https// bug) — paste base URLs from clipboard instead. Rewrite toasts last ~2.6s: time the screenshot ~1s after F8 release (fail path) or during the hold (no-model/no-selection paths).
• C:\Users\Administrator\tts\mock_whisper.mjs now matches the exact path /v1/audio/transcriptions (404 otherwise) — usable for both the success path and the HTTP-404 error branch of the ASR test-connection button. It can also return arbitrary text from (useful for long/punctuation test cases).

Window-state (maximize/hidden) verification

• Judge maximized objectively with user32 IsZoomed(MainWindowHandle) + GetWindowRect (maximized rect = -8,-8,workarea+8 on this box), not by the title-bar glyph — at this scaled resolution the restore glyph is ambiguous in screenshots.
• --hidden only takes effect when settings.startMinimized=true (index.ts); hidden state is provable via Get-Process SpeakType all MainWindowHandle=0 plus a desktop screenshot.
• launchAtLogin writes HKCU Run value name SpeakType pointing at the launched exe with --hidden; clean up with reg delete HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v SpeakType /f after tests, or the packaged test build will autostart on the next VM boot.
• AutoGLM on this box can spontaneously pop a 智谱 login window into the foreground mid-test (not only swallow Alt+Space) — kill AutoGLM.exe before recording window-visibility tests.

Remote mic relay (relay/ Cloudflare Worker) local testing

• npx wrangler dev in relay/ needs Node >= 22 (VM default 20.19 fails). Prepend C:\hostedtoolcache\node\24.0.1\x64 to PATH first. Serves http://localhost:8787.

• The desktop app connects with wss:// only. Local wrangler has no TLS: run the TLS-terminating proxy C:\Users\Administrator\tts\wss_proxy.mjs (8443 -> 8787, reuses the app's self-signed cert) and launch Electron with NODE_TLS_REJECT_UNAUTHORIZED=0; point the relay URL setting at https://127.0.0.1:8443.

• C:\Users\Administrator\tts\relay_pipe_test.mjs objectively verifies Worker pass-through (binary fidelity, start/stop/status/peer, room-occupied close 1008) against ws://localhost:8787 without the desktop app.

• CDP Runtime.evaluate with top-level const fails on re-run — wrap injected snippets in an IIFE.

• Real phone mousedown on the Chrome phone page steals foreground; use CDP Input.dispatchMouseEvent for hold/release so pasted text lands in the target window.

• A real relay deployment exists at https://speaktype-relay.wookat520.workers.dev — use it directly for production-path relay tests (no local wrangler/TLS proxy needed). Do NOT pass --ignore-certificate-errors to the fake-phone Chrome when targeting workers.dev, so the real TLS chain is verified too.

• PWA /app pairing (0.9.0+): the fixed pair code == settings.remoteRelayRoom (12 hex chars, generated once when Internet relay is first enabled; shown under the QR in Settings→General→Audio→Phone as microphone). Phone page stores it in localStorage['speaktype-room']; refresh must skip the pairing UI and auto-reconnect. cdp_phone_hold090.js (variant of cdp_phone_hold.js) also matches /app targets — note after installing the PWA there are TWO /app CDP targets (tab + standalone window); the script grabs the first, so close the tab if you need the standalone one. beforeinstallprompt DOES fire in Chrome-for-Testing here — clicking 添加到主屏幕 opens the native Install dialog and the installed standalone window works end-to-end. Console/SW checks: C:\Users\Administrator\tts\cdp_pwa_check.js (port 9444) prints SW registration, 4 asset statuses and console errors.

• 0.9.2 (2324483) autolearn window: watcher now renews the deadline while the FOCUSED control's UIA runtime id equals the anchor id (watchedit.ts L54-58), WATCH_SECONDS=45 / MAX=300 - idle 25-40s after paste then editing DOES learn (verified). The old '20s from last text change' trap only applies to <=0.9.1. History 'Clear all' now needs an inline confirm (Clear all history? -> red Clear / Cancel); Cancel preserves entries - safe to click once, but the red Clear still wipes everything.

Fresh-user simulation trap (legacy userData migration)

• Deleting %APPDATA%\SpeakType\speaktype.json is NOT enough to simulate a brand-new user: src/main/migrate.ts copies the config back from any legacy dir matching SpeakType * that contains a speaktype.json (e.g. SpeakType ?????). Renaming with a suffix (SpeakType xxx-off) still matches the glob - move the legacy dir OUT of %APPDATA% entirely, and move it back (original name) during cleanup.
• Verify via main.log: expect "no legacy userData to migrate" instead of "migrated legacy userData from ...".
• To make the Home missing-model banner appear for the default model, also stash the model files out of %APPDATA%\SpeakType\models\<model> and restore afterwards.

Capturing loader-phase UI states (badge/spinner)

• SenseVoice offline transcription finishes in <1s, so the post-release loader is nearly impossible to screenshot. To hold the loader open, run a local OpenAI-compatible polish server that delays ~6s before responding (node http server on 127.0.0.1, returning {choices:[{message:{content:...}}]}), set polishBaseUrl/ApiKey/Model in speaktype.json, then screenshot during the "Polishing..." spinner. Restore polish settings afterwards.

Fake mic and audio service traps (round 30)

• The fake microphone is NOT a system device: launch SpeakType.exe with Chromium flags --use-fake-device-for-media-stream --use-fake-ui-for-media-stream --use-file-for-fake-audio-capture=C:\Users\Administrator\tts\sample.wav. Without these flags hotkeys appear dead: recording aborts instantly with a brief "Microphone unavailable / No microphone found" toast (bottom-center, ~2.6s, easy to miss).
• Windows Audio services (Audiosrv/AudioEndpointBuilder) may be DISABLED on this VM; the Chromium fake-capture flags work regardless. Re-enable with sc.exe config Audiosrv start= auto etc. only if real audio devices are needed.
• To debug the packaged main process, launch with --inspect=9229 and use Runtime.evaluate over the Node inspector WebSocket; require app modules via path.join(process.resourcesPath, 'app.asar', 'node_modules', ...).

Verifying text-transform paths (round 47, PR #101)

• To prove a localCleanup/polish text transform really fired, screenshot the live-caption capsule mid-hold: it shows the raw ASR partial BEFORE cleanup (e.g. costs$11), then compare with the final pasted text (costs $11). Same build, before/after distinguishable.
• Custom English fake-mic WAVs can be generated offline with SAPI TTS: SpFileStream + SpAudioFormat.Type=22 (16kHz mono) writes a wav directly usable as --use-file-for-fake-audio-capture source.
• When launched with fake-mic flags, the SpeakType main window steals foreground: before dictating into Notepad, click its taskbar icon and confirm focus via the Ln/Col status bar.
• Stats-accounting changes (round 48, PR #103): back up %APPDATA%\SpeakType\history.json, zero the stats block while the app is closed, then dictate a sentence whose word count differs wildly from its char count (e.g. 5 words / 28 chars) and cross-check history.json numbers against the Home UI. This box's SAPI has English voices only (David/Zira) — mixed CJK/Latin test sentences cannot be TTS-generated naturally.

Export dialogs and encoding traps (round 50, PR #106)

• Renderer Blob downloads (Dictionary/History export) open a native Save dialog in Electron: click Save in the GUI first, then verify the file byte-for-byte via shell. The file does not exist until Save is clicked.
• PowerShell 5 reads UTF-8-without-BOM files as ANSI by default and can corrupt Chinese text when writing back. Always use Get-Content -Raw -Encoding UTF8 / .NET UTF-8 APIs when touching speaktype.json or history.json, and back them up before any script edits.

Two-step confirm buttons and persona storage (round 51, PR #107)

• Two-step confirm buttons change label width on first click, which shifts the button center: leave >=0.3s between clicks and aim the second click at the widened label. Zero-interval synthetic double clicks may be swallowed.
• Personas/rules/current selection live in speaktype.json: top-level personas[] (custom ids like custom-), settings.personaId, settings.appPersonas. Cascade-cleanup assertions are most reliable via direct shell inspection of that file.

Prompt capture via local mock endpoint (round 52, PR #109)

• To assert exact polish/rewrite prompt content, run a local Node HTTP mock at 127.0.0.1:18099 that logs the POST JSON body and returns a fixed OpenAI-compatible completion, then point polishBaseUrl at it.
• Remember polishEnabled=true routes ordinary dictation through the mock too: disable polish when testing local-only hotword correction, or the fixed mock output overwrites the text you want to inspect.
• Use full local model ids (e.g. parakeet-tdt-0.6b-v3, not parakeet); a wrong id silently shows the download banner instead of erroring.

Remote mic (phone-as-mic) testing (round 54, PR #110)

• Open the pairing page in a browser launched with --no-proxy-server --ignore-certificate-errors plus the three fake-mic flags; the LAN page uses a self-signed cert and the box has a dead system proxy.
• LAN/relay mode switching works with the pairing page still connected (since PR #112 stopRemoteMic force-closes lingering connections); verify with netstat | findstr 43117 plus the remote mic listening/relaying via lines in main.log.
• Single-box "text lands in Notepad" checks race pasteText (Ctrl+V to the foreground window ~60ms after mouseup): use a SendInput script that Alt+Tabs within ~25ms of mouseup, or the text lands in the browser.
• computer-tool coordinates are 1024x768 scaled; the real display is 1280x720 — multiply x by 1.25 and y by 0.9375 when driving SendInput scripts from screenshots.

Terminal paste-target testing (round 55, PR #114/#115)

• Use a real cmd.exe window as the paste target (activeApp reports cmd.exe, which is in TERMINAL_APPS); clicking inside a cmd window enters "select" mark mode that swallows the paste — press Esc before dictating.
• SAPI-generated short-sentence wav files looped as fake mic input are sometimes misrecognized on the first loop (e.g. "Speak type" → "speight"); assert on the second loop's stable output or lengthen the hold.

Hotkey sampling, hidden startup, caption overlay (rounds 62-63)

• Hotkey loss-rate sampling is only valid when the target window has been ready >=3s before injecting (a keypress injected ~2s after Notepad launch can be swallowed by focus churn — environment flake, not a product bug; 20/20 clean under the steady-state rule).
• launchAtLogin assertion: reg query HKCU\Software\Microsoft\Windows\CurrentVersion\Run /v SpeakType (value includes --hidden). startMinimized only hides the main window when launched WITH --hidden; without it the window shows as usual.
• Repeated Stop-Process kills accumulate ghost tray icons; sweep the tray overflow with the mouse to clear ghosts before double-clicking the real icon to restore a hidden main window. Prefer tray Quit for cleanup.
• Caption-overlay visual checks (mask/line-height/scroll): zoom the region around [340,555,690,645] (bottom-center) and keep same-utterance zooms of the old build for before/after comparison. The "not overflowing → no mask" state must be captured ~3-4s after entering hands-free (partial still <= configured lines; overflows by ~15s). For 6-line captures avoid the #120 50s segmentation moment (caption restarts and shrinks) — sample at 30-45s or 25s+ into the second segment.
• Audio render endpoint: this box has no physical audio device, but a VB-CABLE virtual sound card is now installed (PR #217 round) so CoreAudio GetMute/SetMute work. If GetMute ever throws 0x80070490 again, reinstall: driver pack at C:\Users\Administrator\tts\vbcable\, run pnputil /add-driver vbMmeCable64_win10.inf /install then C:\Users\Administrator\tts\scream\Install\helpers\devcon-x64.exe install vbMmeCable64_win10.inf VBAudioVACWDM and Restart-Service audiosrv. (Scream 4.0 does NOT install — its .cat certificate is expired.)
• Mute probes: C:\Users\Administrator\tts\getmute.ps1 and setmute.ps1 <0|1>. Both were fixed in the PR #217 round: the old getmute.ps1 had 12 vtable filler methods (off-by-one — it actually called GetVolumeStepInfo and always returned True); the correct IAudioEndpointVolume layout is 11 fillers before SetMute(slot14)/GetMute(slot15). If you copy this pattern, verify with SetMute(1)/(0) → GetMute round-trips first. muted-by-recording crash-recovery flag lives at %APPDATA%\SpeakType\muted-by-recording.
• Probing mute DURING a hold-key recording: computer-tool hold_key blocks, so start a background PowerShell that sleeps ~3-4s then probes/kills (tts\pr217_probe.ps1, tts\pr217_kill.ps1), then immediately start the hold. keepFailedAudio pruning only fires when a finish-stage recognition failure persists audio — needs fault injection (temporarily corrupt a model file), not network blocking.

Model fault injection, hotkeys, migrations (rounds 64-66)

• To create a finish-stage recognition failure, corrupt a whisper ggml model (whisper-server is a separate process: exited(3) → failed entry lands + prune runs, main app survives). Since PR #125, corrupting a sherpa model (sensevoice/parakeet) no longer crashes the app — a wrong-size file is treated as not-downloaded (guard proof: process alive 30s+ AND no sherpa worker started in log; pre-#125 builds silently abort). For the parakeet channel inject joiner.int8.onnx (only 6MB, fastest to back up/restore).
• Before any model injection record Get-FileHash SHA256 and rename the original aside; restore and re-verify the hash afterwards. Pre-seeding failed-audio for prune tests: node-generated valid RIFF wavs + fs.utimesSync to control mtime (prune sorts by mtime; drives the 20-count/7-day/50MB rules precisely).
• The speech model status/download button lives in Settings→Speech (the AI model tab is polish settings). HF downloads go through a local proxy cache here — 234MB completes in seconds, so re-download tests can just wait for completion and compare SHA against the original.
• Hands-free hotkey tests always use Alt+Q: Alt+Space was removed from the product in PR #126 (Windows system-menu key; synthetic injection never triggered it either). Verifying read-time migrations needs three-way proof: UI shows the new value + the file on disk keeps the old value (node-read while the app runs) + the new value actually works (injection test).
• Persona hotkey injection uses rkey.ps1's d1/d2/d3 key names (down:alt,down:d2,...); persona switching writes settings.personaId, so restoring the backed-up config is enough for cleanup.
• Config-corruption recovery toast ("Settings rebuilt", with .bad backup) appears ~ready+1.5s and lasts 4s — screenshot ~2s after Start-Process. BOM-only corruption is repaired silently in place with zero data loss (no toast, no .bad). For window-bounds persistence compare GetWindowRect physical pixels, not the DIP values stored in speaktype.json (DPI differs).

Download progress/resume copy testing (round 68, PR #128)

• To exercise resume-copy/progress logic without a real interrupted download, fake a .part: write the first N bytes of the real file to dest.part plus dest.part.json containing {"url":"fake","total":<real total bytes>} — partialProgress only reads the .part size and meta.total (download.ts), so the UI shows N/total ("Resume download (43% done)"). Delete both and restore originals afterwards.
• "Fresh no-model" state: rename the whole model directory to .bakNNN (rename back after). Since PR #128, a corrupt single file (wrong size) makes the button show "Resume download (99% done)" instead of the full-download copy; the banner body text still says "One-time download (~660MB)".
• Missing vs corrupt are different modelPartialPercent branches — inject both separately (delete a whole file vs write a wrong-size file). Since PR #130 both show Resume with distinct percentages (delete 652MB encoder → 2%, corrupt 6MB joiner → 99%), a strong assertion pair. Download failure state: inject with icacls %APPDATA%\SpeakType\models /deny "Administrator:(OI)(CI)W" (cleanup /remove:d, verify no DENY left). The "Downloading x% + progress bar" window needs a big file (652MB encoder ≈ 40s; a 6MB file finishes too fast to capture).
• UI-language dropdown via synthetic clicks tends to miss (opens the adjacent Theme dropdown or misses the item). Standard method: click to open the menu → screenshot to confirm item coordinates → separate single call to click the target item → screenshot to confirm it took effect.

Polish/rewrite mock, history injection, toast capture (round 70)

• Test AI polish / F8 rewrite with a local OpenAI-compatible mock: C:\Users\Administrator\tts\mock-polish-8098.cjs (127.0.0.1:8098, fixed response + logs each request); set polishBaseUrl=http://127.0.0.1:8098/v1 in settings. F8 must be HELD ≥400ms (holdDelayMs=120 threshold — an instant tap does not trigger).
• Failed-entry Retry can be injected synthetically: set a history entry status="failed" + error + audioFile pointing at a real wav copied under failed-audio; Retry re-recognizes and normalizes the entry in place.
• 500-entry full-load: rewrite the history array in history.json directly (top-level shape {history,stats} — leave stats alone).
• rkey.ps1's key map lacks ctrl/a/letter keys (type:/ctrl+a throw NullArray) — use computer-native injection for text and Ctrl+A. Short-lived toasts (persona switch, rewriteNoModel) require screenshotting immediately after computer-native key injection; the rkey→screenshot pipeline is too slow.

Browser proxy, hosts blocking, soft-segment evidence (round 71)

• If the local browser can't reach the internet, the cause is usually the dead system proxy (socks 127.0.0.1:1080, nothing listening) — launch msedge --no-proxy-server; do NOT change the system proxy.
• Before relying on hosts-file blocking (e.g. simulating GitHub API rate-limit silence), verify with ping: this box's hosts ACL may lack NETWORK SERVICE/Users read access, making the DNS Client ignore hosts entirely. Fix temporarily with icacls hosts /grant "NT AUTHORITY\NETWORK SERVICE:R" "BUILTIN\Users:R" + Restart-Service Dnscache; afterwards /remove:g and delete the entries. Resolve-DnsName always bypasses hosts — verify with ping.
• Hands-free soft-segment (50s) evidence: main.log dictation finalize: durationMs=5xxxx (>50000 means the soft-segment path); a 60s session on the looping fake mic triggers it.

Remote-mic LAN sim, soak evidence, no-paste-target guard (round 72, PR #134)

• Remote-mic LAN pairing can be tested without a phone: open the pairing URL in msedge --no-proxy-server on this box. Token rotation (re-open the desktop pairing dialog) invalidates the old page: it must stop after exactly 8 reconnect attempts and show the rescan prompt; a wrong token gets HTTP 403.
• 20-min hands-free soak evidence: compare main.log dictation finalize count vs History new-entry count (must match; zero-loss proof). Memory sampling in a background loop: when cleaning up with Stop-Process filtered by command line, exclude your own PID — a naive filter matched the sampler itself and killed it.
• Memory sampler MUST NOT use Start-Job from a one-shot exec shell — the job dies when the parent shell exits and leaves no CSV. Use a detached hidden process instead: Start-Process powershell -WindowStyle Hidden -ArgumentList '-Command', $samplerLoopWritingToCsv. At minimum capture a manual first/last WorkingSet snapshot as fallback evidence.
• After cold start, Alt+Q within the first ~5-8s may be ignored (sherpa worker not ready yet) — re-send after waiting; not a product bug.
• Launching win-unpacked WITHOUT the four fake-mic flags shows "Microphone unavailable — No microphone found" and no finalize in logs; easily misread as broken hotkeys. Always pass the flags.
• Comparing history.json text in Windows PowerShell requires gc -Raw -Encoding UTF8 (default ANSI reads UTF-8 as mojibake, giving a false mismatch).
• polishEnabled=true routes ALL dictation through the polish endpoint — when a mock endpoint is attached, keep it off except for F8 cases. F8 rewrite only checks polishBaseUrl (dictation.ts startRewrite); the toggle does not affect it.
• Since PR #134 "no paste target" = foreground window class Progman/WorkerW (or no hwnd). To trigger: click empty desktop and dictate, expect the "saved to History" toast and no Ctrl+V. SpeakType's own windows (Chrome_WidgetWin_1) count as valid targets.

Clipboard restore race testing (round 73, PR #136)

• Test the pasteText 350ms clipboard-restore race with C:\Users\Administrator\tts\clip-race.ps1 (launch with -STA, hidden window): it tight-polls the clipboard, and after detecting the dictated text it MUST wait ~200ms before writing the simulated user copy — writing immediately can land before Ctrl+V and pollute the paste itself (a sentinel false failure). Only assert on runs whose log timestamps show the write happened before the restore point (write + 60 + 350ms).
• When killing the sentinel, filter with 'clip[-]race\.ps1' AND exclude $PID — a plain command-line filter matches the killer itself (same self-kill trap as round 72).
• Since PR #136 the restore is conditional (clipboard.readText() === text): user copy during the window survives; with no contention the old clipboard is restored; with an empty previous clipboard the dictated text stays.

Image clipboard restore testing (round 74, PR #138)

• Test image-clipboard restore with C:\Users\Administrator\tts\imgclip.ps1 (must run -STA): set = 64x64 green bitmap with a red corner block; verify = ContainsImage + size + two pixel probes. Assert on pixel values, not just ContainsImage=True — otherwise you can't distinguish "restored a different image".
• Sentinel polling logs may show rapid [] ↔ text flapping right after a write (WinForms GetText jitter); take the final value from a separate -STA verify process, not the polling log.
• Since PR #138: image previous is snapshotted only when text previous is empty; restore is three-branch — clipboard rewritten by others → give up; text previous → writeText; non-empty image → writeImage. File lists and other formats are still not preserved (declared boundary).
• history.json top-level shape is {history:[...],stats:...}; latest entry text is $h.history[0].text.

Enhanced punctuation (punct-ct) testing (round 75, PR #140)

• Model punctuation only runs with polishEnabled=false and enhancedPunct=true (polish.ts — AI polish skips the punct model entirely).
• Model lives at %APPDATA%\SpeakType\models\punct-ct\model.onnx (~281MB, downloaded via Settings→Speech; HF direct takes ~1 min).
• Log signature for model punctuation is punct worker started; rule-based fallback has no such line.
• Settings-page status updates live via the onPunctStatus push channel: the punctuate failure path pushes downloaded:false (#140) so external model deletion reverts the UI without restart; the success path does NOT push — verifying "back to ready" requires remounting the page (switch tabs).

File transcription page testing (round 77, PR #143/#144)

• Long Chinese test wavs: local TTS voices are English-only. Build them by PCM-concatenating C:\Users\Administrator\tts\sample.wav — read the bytes, take [byte[]]$data = $b[44..($b.Length-1)] (must cast to byte[], otherwise BinaryWriter writes a tiny corrupt file), repeat, and hand-write a 44-byte RIFF header.
• TXT/SRT export goes through queued system "Save As" dialogs: save each one fully before clicking the next — a queued dialog intercepts later clicks/typing and can overwrite your source wav. Right after transcription completes, the Cancel button's position becomes the SRT button; screenshot to confirm the progress row is still there before clicking.
• Warm sensevoice/parakeet transcribe ~70s audio in only 3-5s — cancel test cases need ≥5min audio to have a window.
• ggml-tiny-q5_1.bin is already downloaded on this box (models root); to exercise the "model missing" banner pick base-q5_1 or small-q5_1.
• Settings tab ids are general/voice/model/about: "voice" is Speech recognition (local dictation models), "model" is the AI polish model tab (#144 fixed the banner jump to use "voice").
• TXT vs copied-text comparison: Windows clipboard converts to CRLF; normalize line endings before asserting equality.
• Verifying completion-instant UI (e.g. the #146 settling window): do one warm-up run first to measure the exact transcribe duration (log started/done delta), then time the action as "press Enter → wait duration+0.1s → act immediately → screenshot now AND re-screenshot after 5s". Queued Save-As dialogs can pop several seconds late, so a "no dialog appeared" assertion must include the delayed re-screenshot.
• ffmpeg 8.1.2 (gyan essentials) is installed on this box and on PATH. Container-matrix fixtures are one-liners: mp3 -b:a 64k, m4a -c:a aac, ogg/webm -c:a libopus, mp4 -f lavfi color=black + -shortest -c:v libx264 -c:a aac. Multi-hour wavs generate in seconds with -stream_loop N -i src.wav -t <sec> -c copy (3h ≈ 330MB — delete after).
• Release acceptance (round 80): Setup is a per-user NSIS installer → %LOCALAPPDATA%\Programs\SpeakType, wizard buttons sit bottom-right (~601,543), and an overwrite install shows "Will reinstall/upgrade". On the finish page UNCHECK "Run SpeakType" before Finish, then launch manually with the fake-mic flags. Silent uninstall: "Uninstall SpeakType.exe" /S (user data in %APPDATA%\SpeakType survives uninstall). The update banner comes from main/index.ts fetching the GitHub latest release ~5s after startup (api.github.com direct) — an amber "New version vX is available" bar on About, hidden when versions match. Download release assets with direct and byte-compare against the GitHub API asset size.