Group inline links and list items into browse lines

docs/testing/browser-visual-lines.md

@@ -0,0 +1,58 @@
+# Browse visual lines
+
+Cthulhu previously made every link and list item a line boundary, even when
+several appeared on the same rendered row. The local Orca reference
+`src/orca/scripts/web/script_utilities.py:_get_line_contents_at_offset` uses
+geometry plus block ancestry. Its `ax_utilities.py:get_nearest_block_ancestor`
+treats links and non-grid list items as inline for this purpose.
+
+Cthulhu now lets ordinary links inherit their block and list items inherit
+their list. Native text rectangles still determine whether fragments share
+a line. Headings, paragraphs, lists, table cells, non-span sections, hard
+newlines, code and editable controls retain their boundaries. Grid list
+items stay independent using the captured AT-SPI display attribute. Explicitly
+named atomic links and other whole controls retain their existing stops.
+This is a focused improvement, not full parity with Orca's layout policy.
+
+The move owns temporary assembled lines; the retained cursor, activation and
+braille routing still use actual objects and native offsets. Say All retains
+fragments and their privacy ancestry. Speech coalesces plain spans but keeps
+inline link roles, visited states and role sounds, plus heading announcements.
+
+## Automated checks
+
+- Review, AT-SPI, presentation and application package tests.
+- `CTHULHU_NATIVE_BROWSER_TESTS=fragments,lists,namedlinks,linkedheadings,document,selection python3 tests/native_browser.py`
+- `python3 tests/native_firefox.py`
+
+The fragments fixture covers adjacent links, text around a link, a horizontal
+list, vertical list items, separate headings, reverse navigation, wrapped
+spans, code, Say All and native braille routing. Firefox's existing baseline
+covers browser navigation and tabs; the new horizontal fixture is tested in
+Brave. Tests use private Xvfb/D-Bus sessions without replacing the live reader.
+
+## Live acceptance
+
+1. Quit the current reader with Cthulhu+Q.
+2. Press Ctrl+Escape, then Shift+G. These are separate key presses. The second
+   rebuilds and launches Cthulhu through `~/devel/cthulhu-go.sh`.
+3. Open `file:///home/angus/devel/cthulhu/tests/browser-fragments.html` in the
+   browser. In browse mode, press Ctrl+Home, then 3 to reach “Line grouping”.
+4. Press Down once: hear First link, Second link and trailing text together,
+   with link announcements according to the configured speech/sound settings.
+   Down again reads East and West together. Up returns to the full link row.
+5. Continue Down: North and South remain separate, followed by Separate
+   heading and Final paragraph as separate lines. The browser must stay in
+   browse mode and keyboard focus must not jump into an unrelated control.
+6. Use K/Shift+K to select individual links and Enter to activate one. Each
+   link still targets Split heading. Check Home/End and Left/Right within a
+   combined row, then Down to leave that whole row.
+7. With braille, confirm the row contains both links; route to characters in
+   each link and check the caret and subsequent activation target. Run Say
+   All and listen for missing/repeated content and retained link roles.
+8. Repeat on the original page in Brave and Firefox. Report exact speech,
+   braille content, focused control and keys whose behavior differs. Inspect
+   `~/devel/cthulhu-go.log` if anything is unexpected.
+
+Physical keyboard, audible speech and physical braille acceptance remain
+pending. Human review and live testing are required before submission.