libreoffice support started, still broken. Some updates to how wine-access gets called.

LIBREOFFICE_SUPPORT.md

@@ -0,0 +1,150 @@
+# LibreOffice integration
+
+Current Orca is the primary behavioral reference for LibreOffice. Python
+Cthulhu remains available on the `legacy` branch for historical comparisons:
+`git show legacy:src/cthulhu/scripts/apps/soffice/script.py`.
+Do not switch the active Go checkout to inspect that reference.
+
+## Architecture
+
+Application handling runs after screen-lock and foreground validation, before
+generic focus and text filtering. `internal/app/application_behavior.go`
+routes copied accessibility events by verified provider process identity.
+The LibreOffice handler lives in `internal/app/libreoffice.go`.
+It can normalize an event, request focus adoption, or suppress presentation.
+The reader retains window ownership, input policy, pending-output cancellation,
+review, and speech/Braille delivery. Ordinary applications keep their existing
+event path. Steam's existing integration remains in place.
+
+`internal/atspi/libreoffice_native.go` captures bounded Calc metadata on the
+native owner thread. It does not enumerate a sheet. The controller and
+presentation code never retain native objects or perform provider queries.
+`internal/presentation/libreoffice.go` owns the corresponding speech
+formatting; LibreOffice Braille formatting stays beside its controller.
+
+The first implementation has no independent mutable application state:
+logical focus belongs to the existing event loop. Future selections and
+dynamic headers must be keyed by application bus, document, and sheet identity.
+Retire them on document/sheet destruction or application exit. Focus loss
+must cancel pending output while preserving document header choices; shutdown
+and screen lock must retire pending operations. Add command routing when the
+first real Office command requires it, using the existing input machinery.
+Application code must not bypass security/foreground gates or manage its own
+speech connection, key grabs, or background event loop.
+
+Keep generic table operations and genuinely shared fixes in their existing
+subsystems. Keep verified LibreOffice exceptions in the dedicated files.
+Adding later Office features should extend these boundaries, without
+reorganizing unrelated reader code or building a speculative plugin framework.
+
+## First slice
+
+- Calc active-cell events establish logical focus, including after editing
+  and when the sheet changes.
+- Cell contents and addresses are separate. Normal speech gives the value,
+  then the address; an empty value gives “blank.” Only-displayed-text mode
+  omits the address and the synthetic blank label.
+- Recorded Braille preserves value spacing followed by the address. A cell
+  component is not an editable text route.
+- F2 resolves a temporary editor's focused paragraph when available.
+  If the paragraph appears later, its first owned text/caret event establishes
+  editor focus before generic filtering.
+- Post-editing sheet focus is adopted silently. Spreadsheet capacity and
+  cell/container state chatter are omitted as in Orca.
+- Ancestor focus claims are suppressed when captured ancestry identifies the
+  existing focused spreadsheet object.
+- Non-editor caret events do not displace a focused cell. Selection events do
+  not promote the first selected cell of a range into logical focus.
+
+References inspected: Orca commit `cd58a88ed` (2026-10-14),
+`scripts/apps/soffice/script.py`, `script_utilities.py`,
+`speech_generator.py`, `braille_generator.py`, and shared
+`speech_generator.py` / `ax_utilities_table.py`.
+
+## Next slices
+
+1. Formula presence and an on-demand formula command, using current Orca's
+   `where_am_i_presenter.py:present_cell_formula` and cell attributes.
+2. Selected/unselected ranges, rows, columns, and Select All. Represent ranges
+   compactly; do not expand every selected cell as Orca's current comparison
+   does. Test very large and disjoint selections.
+3. Dynamic row/column headers, sheet-scoped state, preferences and bindings.
+   Inspect current Orca's shared table navigator rather than copying only
+   the soffice directory. Spreadsheet full-row reading also needs a bounded,
+   explicitly defined extent; the generic setting is not full Calc support.
+4. Writer paragraph navigation, selection, Say All, spell-check presentation,
+   and Braille panning. Compare each actual workflow with current Orca.
+
+Merged cells, overflow announcements, large-sheet responsiveness, other
+LibreOffice backends, and independent-workbook acceptance remain separate
+checks. This first slice does not establish complete Office support.
+
+## Verification
+
+```sh
+GOCACHE=/tmp/cthulhu-go-cache go test -race ./internal/atspi ./internal/app ./internal/presentation -count=1
+/usr/bin/python3 tests/native_libreoffice.py
+python3 tests/native_atspi.py --table-only
+python3 tests/native_x11.py
+```
+
+The Calc harness launches installed LibreOffice with a disposable profile,
+document, virtual X11 display, and private session/accessibility buses.
+It exercises the production native adapter and event loop; recorded speech
+and Braille are asserted for cell movement and blanks, F2 typing, Escape
+cancellation, Enter commit, caret movement inside an existing numeric cell,
+and switching between two sheets.
+No active reader is replaced and no normal Office profile is changed.
+
+These automated checks do not establish audible speech, physical input, or
+physical Braille. Before submission, review the diff and test a rebuilt binary:
+
+1. In a disposable Calc workbook, populate text, numbers, formulas and blanks.
+   Arrow between them and listen for the value followed by its address.
+2. Press F2, edit, cancel with Escape, then edit and commit with Enter. Check
+   character/word navigation in an existing cell editor and continued arrows.
+3. Switch sheets and switch between two workbooks. Return from menus, dialogs,
+   the formula bar, and another application; check logical focus recovery.
+4. Check the cell value/address, spacing, editor cursor and return to cell
+   display on physical Braille. Text routing applies inside the editor.
+5. Repeat ordinary GTK table movement/multiselection, browser typing and table
+   reading, and Steam navigation. Check lock/unlock and stale/background events.
+
+Human review and testing remain required by `CONTRIBUTING.md`. Passing this
+fixture alone is not sufficient for submission or live accessibility acceptance.
+
+Initial verification against LibreOffice 26.2.6.3 passed the Calc harness,
+affected-package race tests, vet/build, GTK table/multiselection checks, and
+Xorg input checks. Browser tab and table checks also passed. Browser editing
+failed on an extra title announcement both here and on untouched commit
+`8e76d23`. Browser modes initially failed to focus a heading after reload,
+then passed on the baseline and on a rerun here; the cause of that first
+failure was not established. Physical acceptance remains pending.
+
+## Calc startup focus diagnosis
+
+A normal-profile startup under i3 can leave Calc accepting arrow keys while
+omitting active-cell accessibility events. In the observed case, cell events
+were followed by focus claims from the floating Form Design and Form Controls
+toolbars; subsequent arrows produced formula-bar text updates but no new cell
+events. A separate AT-SPI observer reproduced the missing events without
+Cthulhu. The affected workbook worked with a fresh profile, and a generic
+workbook reproduced the failure with a disposable copy of the normal profile.
+This establishes a profile-dependent LibreOffice focus/event problem; the
+precise profile setting responsible has not been isolated.
+
+Press **Ctrl+F6** to return focus to the document, then retry the arrows.
+This directly restored active-cell events in the isolated reproduction.
+LibreOffice documents this shortcut in its
+[Calc accessibility keyboard guide](https://help.libreoffice.org/latest/en-GB/text/scalc/guide/keyboard.html).
+Automatic focus stealing would interfere with intentional toolbar use and
+is not part of the reader's handling.
+
+The native Calc test focuses its window once and uses ordinary key sequences
+afterward. It also checks F6 followed by Ctrl+F6 and resumed cell speech/Braille.
+Its fresh-profile virtual display does not cover this normal-profile startup
+failure. The same production test also passed under private i3 with the copied
+normal profile after Ctrl+F6 recovery, asserting recorded cell speech and
+Braille along with editing and sheet switching. Verify startup and recovery
+under the actual window manager, plus audible speech and physical Braille,
+separately.