cthulhu/PROGRESS_BARS.md

Progress reporting

Progress bars use the configured Off, Beep, Speak, or Both output mode and percentage thresholds. Background reporting is optional. Updates do not take focus or replace Braille for an unrelated object.

Native HTML <progress> and ARIA progressbar controls use their AT-SPI progress role and value events. Steam's shader dialog instead exposes changing static text such as Processing Vulkan shaders (37%). The Steam webscript recognizes that English status under the verified steamwebhelper process and passes its percentage to the shared progress handler. Other text, containing sections, and ordinary browser processes do not use this exception. Translated Steam shader messages and other custom text-only progress widgets are not covered by this recognition.

Automated checks

GOCACHE=/tmp/cthulhu-go-cache go test ./internal/app ./internal/webscripts ./internal/presentation ./internal/sound -count=1
python3 tests/native_progress.py
CTHULHU_NATIVE_BROWSER_TESTS=progress python3 tests/native_browser.py

The isolated GTK test checks foreground, background, and hidden progress. The isolated browser test drives real HTML and ARIA controls in a Chromium-family browser and verifies the resulting tone requests. Unit tests cover Steam text recognition, output modes, duplicate suppression, percentage thresholds, security, stale events, background settings, and unrelated Braille ownership. These checks do not establish audible output from the running reader.

Live review before submission

Rebuild and restart the reader, then launch a Steam game that needs shader processing. With Beep selected and Steam in the foreground, confirm that pitch rises as the percentage increases without navigating onto the status text. With Speak or Both selected, verify the configured speech threshold. With Off selected, verify that automatic progress output stops.

Switch to another application during processing: reporting should follow the background-progress setting without moving focus or replacing that application's Braille. Check ordinary Steam navigation and notifications afterward. Open tests/browser-progress.html in a browser and activate Update progress to check native and ARIA bars. Physical keyboard, listening, and Braille checks remain separate acceptance gates.