cthulhu/docs/testing/browser-lists.md

Browser element lists

In browse mode, hold Alt+Shift and press the key below. These shortcuts work in both desktop and laptop layouts and can be changed in Preferences under browser shortcuts.

Key	List
A	Clickables
B	Buttons
C	Combo boxes
E	Text entries
F	Form fields
G	Images
H	Headings
I	List items
K	Links
L	Lists
M	Landmarks
O	Large objects
P	Paragraphs
Q	Block quotes
R	Radio buttons
T	Tables
U	Unvisited links
V	Visited links
X	Check boxes
1–6	Headings at that level

Annotation, internal frame and math lists have no default shortcut, matching Orca. Assign them a browser shortcut in Preferences. Annotation lists include content insertions, content deletions and marks. Separators and live regions have no list command in Orca.

The list opens with the current item selected when it matches the filter. Use arrows, Home, End, Page Up and Page Down to select an item, or type the beginning of its name. Enter closes the list and moves the reading position to the selected item. It does not activate a link or press a button. Escape closes the list without moving. An empty list reports zero items and releases the keyboard. Speech presents rows and Braille shows the selection and count. The browser retains native keyboard focus while the list is open.

Lists use the same semantic filters as structural navigation, exclude hidden content, and stay within the current document, including embedded content. The native document capture limit also bounds lists. Core navigation lists can contain more than 256 items; external Tentacle forms retain their existing 256-item limit. List selections retain exact accessible references and page ownership, so removed targets, replaced documents and changed focus cannot select a different item. A changed page can require reopening the list.

Automated checks:

go test ./internal/input ./internal/review ./internal/interaction ./internal/app -count=1
CTHULHU_NATIVE_BROWSER_TESTS=lists,keys,document,modes,editing python3 tests/native_browser.py
python3 tests/native_internal_ui.py

The private browser list fixture checks 302 links, hidden-link exclusion, current-row restoration, selection, Escape, clickables, a heading level and an empty image list with actual X11 grabs and AT-SPI data. These checks inspect speech requests and synthetic input. They do not establish audible speech or physical keyboard/Braille behavior.

Before submission, review the diff and test the rebuilt reader on a real page:

1. Open links with Alt+Shift+K. Move with arrows, type a name, select with Enter, and confirm subsequent browse arrows start at that item. Press Enter again to verify that ordinary link activation still works.
2. Open clickables with Alt+Shift+A and headings with H and 1–6. Check spoken labels and Braille rows, then cancel and confirm the old reading position remains. Check lists with several hundred entries.
3. Open a list, change tabs or windows, and confirm capture is dismissed and typing works normally. Reload or remove a selected page item and confirm the old list cannot move to a different target.
4. Check ordinary H/Shift+H and K/Shift+K, browse arrows, Tab/Shift+Tab, editable-field typing, browser chrome, and the existing Cthulhu+Shift+A actions menu. Verify the new list keys pass through outside browse mode.

Human review and these live checks remain necessary under the project's AI-assisted contribution policy.

The full Go race suite, private browser lists, document navigation, editing, keyboard transitions and existing internal UI checks passed. The browser mode check missed a dynamic-text announcement during the combined run, then passed in isolation. The cause of that initial failure is unverified; its diagnostic log was retained at /tmp/cthulhu-browser-modes-2991369198.log.