cthulhu/docs/atspi-document-selection-handoff.md

AT-SPI Document Selection Branch Handoff

Branch: atspi-document-selection

Implemented

• Added document-wide AT-SPI selection normalization in src/cthulhu/ax_document_selection.py.
• Reworked text-selection handling in src/cthulhu/script_utilities.py to use the shared adapter where possible and fall back cleanly where not.
• Updated primary callers in the default and web scripts so copy/cut, selection announcements, and selected-text queries use the shared selection path.
• Added keyboard-driven clipboard announcement fallback in src/cthulhu/scripts/default.py, including Wayland-specific policy changes.
• Fixed build-local.sh so rebuilding refreshes modified installed modules under ~/.local.

Verified

• python3 -m pytest -q tests/test_document_selection_regressions.py
• python3 -m pytest -q tests/test_default_script_clipboard_regressions.py
• python3 -m pytest -q tests/test_web_input_regressions.py
• HOME=/tmp/cthulhu-test-home python3 -m pytest -q tests
• ./build-local.sh

Latest full-suite result before handoff: 95 passed, 1 warning.

Still Open

• Browser link-text selection is still not reliable in Chromium/Edge and in web-backed content like Steam.
• The current branch includes extra diagnostics around clipboard and selection paths because they were useful during manual debugging.
• The newest attempted web fix is in src/cthulhu/scripts/web/script.py, but the manual repro still fails:
  • selecting link text with Shift+Left / Shift+Right
  • hearing no selection announcement
  • then having copy behavior depend on fallback logic instead of real selection state

Useful Files For Follow-Up

• src/cthulhu/ax_document_selection.py
• src/cthulhu/script_utilities.py
• src/cthulhu/scripts/default.py
• src/cthulhu/scripts/web/script.py
• src/cthulhu/scripts/web/script_utilities.py
• tests/test_document_selection_regressions.py
• tests/test_default_script_clipboard_regressions.py
• tests/test_web_input_regressions.py