From 013c81d19b828757fc7933dc04c11ec45bbfae05 Mon Sep 17 00:00:00 2001 From: Hunter Jozwiak Date: Fri, 10 Apr 2026 19:29:49 -0400 Subject: [PATCH] Add Orca 50 event system rebase spec --- ...4-10-orca-50-event-system-rebase-design.md | 169 ++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-10-orca-50-event-system-rebase-design.md diff --git a/docs/superpowers/specs/2026-04-10-orca-50-event-system-rebase-design.md b/docs/superpowers/specs/2026-04-10-orca-50-event-system-rebase-design.md new file mode 100644 index 0000000..df85505 --- /dev/null +++ b/docs/superpowers/specs/2026-04-10-orca-50-event-system-rebase-design.md @@ -0,0 +1,169 @@ +# Orca 50 Event System Rebase Design + +Date: 2026-04-10 +Status: Design approved in conversation; implementation plan pending review + +## Source Of Truth + +Rebase Cthulhu's event system wholesale onto the official GNOME Orca 50.0.9 event system. + +- Upstream source: https://download.gnome.org/sources/orca/50/orca-50.0.9.tar.xz +- Upstream release date from the GNOME source index: 2026-03-18 +- Verified SHA-256: `0c5dd0eb971e4694e3bd60ac9de76db587cc311ba802fda7380eaf1dce6a09cb` +- The official tarball is authoritative. A local `/tmp/orca50` copy differed from the tarball in `input_event_manager.py`; use the official tarball behavior there. + +Package and branding names should be translated from Orca to Cthulhu where appropriate. Behavioral compatibility with the old Cthulhu event system is not a goal. + +## Approved Scope + +Use the full Orca 50 manager slice, not a narrow event-manager-only port. + +The initial replacement slice includes: + +- `event_manager.py` +- `input_event_manager.py` +- `input_event.py` +- `ax_device_manager.py` +- `cthulhu_modifier_manager.py` rebased to Orca 50's modifier-manager API +- `systemd.py` +- `command_manager.py` +- `presentation_manager.py` +- `braille_presenter.py` + +Pull the required import closure from Orca 50 rather than building compatibility shims around old Cthulhu APIs. Expected support modules include presenter, navigator, settings, and split AX utility helpers needed by the manager slice. + +## Architecture + +The Orca 50 manager slice cannot be made reliable under the old Cthulhu `Script` API. Port the surrounding script layer as part of the rebase. + +Event handling should move to Orca 50's model: + +- Use `PriorityQueue` with priority/counter/event entries. +- Use Orca 50's priority calculation, obsolete-event detection, pause queueing, and direct listener dispatch. +- Replace the old queue and async/sync special cases. +- Replace old `_ignore` behavior with Orca 50's split ignore checks. +- Drop compositor-event shaping from the event path. + +Input handling should move to Orca 50's device/input model: + +- Add `ax_device_manager.py`. +- Rebase `input_event_manager.py` to the upstream API and signal handling. +- Rebase `input_event.py` around Orca 50's command, focus, modifier, presentation, and script manager interactions. +- Preserve only necessary Cthulhu branding such as the AT-SPI device name, expected to remain `org.stormux.Cthulhu`. + +Modifier handling should move to Orca 50's modifier manager behavior: + +- Translate names/logging/package references from Orca to Cthulhu. +- Do not preserve old Cthulhu modifier-manager behavior unless needed for a Cthulhu-specific branding or install detail. + +Command and presentation ownership should move to Orca 50's managers: + +- Add `command_manager.py` and move command/keybinding ownership to it. +- Add `presentation_manager.py`. +- Add required presenter modules such as `braille_presenter.py`. +- Port existing presenter modules as needed to the Orca 50 manager API. + +The script layer should be ported to the Orca 50 API: + +- `script.py` +- `script_manager.py` +- `scripts/default.py` + +Expected API changes include `get_listeners`, `register_event_listeners`, `event_cache`, `present_if_inactive`, `_on_*` listener methods, and `set_up_commands`. Old camelCase APIs should not remain as public compatibility surfaces in the final state. Temporary aliases are acceptable only inside the implementation plan if they keep the tree testable between steps. + +## Import Closure + +Do not stop at the first import error. Pull the manager-slice closure intentionally. + +Likely missing modules from Orca 50 include: + +- `gsettings_registry.py` +- `gsettings_migrator.py` +- `preferences_grid_base.py` +- `ax_device_manager.py` +- `systemd.py` +- `braille_monitor.py` +- `caret_navigator.py` +- `chat_presenter.py` +- `clipboard.py` +- `debugging_tools_manager.py` +- `document_presenter.py` +- `live_region_presenter.py` +- `profile_manager.py` +- `pronunciation_dictionary_manager.py` +- `say_all_presenter.py` +- `sound_presenter.py` +- `speech_manager.py` +- `speech_presenter.py` +- `speech_monitor.py` +- `spellcheck_presenter.py` +- `structural_navigator.py` +- `table_navigator.py` +- `text_attribute_manager.py` +- `ax_action.py` +- `ax_utilities_action.py` +- `ax_utilities_component.py` +- `ax_utilities_object.py` +- `ax_utilities_selection.py` +- `ax_utilities_table.py` +- `ax_utilities_text.py` + +If new Python modules are added under `src/cthulhu/`, update `src/cthulhu/meson.build` so installation does not diverge from repo tests. + +## Migration Order + +Implement in this order to keep failures local: + +1. Add helper modules and update Meson install lists. +2. Port `script.py` and `script_manager.py` to the Orca 50 script API. +3. Port `input_event.py`, `input_event_manager.py`, `ax_device_manager.py`, and modifier management. +4. Add `command_manager.py` and move default-script command/keybinding setup. +5. Add `presentation_manager.py` and required presenters. +6. Replace `event_manager.py` last. +7. Remove or rewrite obsolete Cthulhu event tests after the replacement semantics are in place. + +## Testing Strategy + +Use Orca 50.0.9 tests as the behavioral baseline where practical: + +- `event_manager` +- `input_event_manager` +- `input_event` +- `command_manager` +- `presentation_manager` +- `script_manager` +- `orca_modifier_manager` +- presenter modules + +Remove or rewrite tests that assert behavior intentionally discarded by this rebase: + +- compositor relevance gates +- compositor event shaping +- Steam churn filters +- self-hosted focus prioritization +- old async/sync queue behavior + +Add Cthulhu-specific smoke coverage only for renamed package/branding and install details, such as AT-SPI device naming and Meson integration. + +Verification order after implementation: + +1. Run targeted Python tests for the manager slice. +2. Run `./test-local.sh`. +3. Run `./build-local.sh` to refresh the local install for runtime testing when the repo test state is coherent enough. + +## Explicit Non-Goals + +- Do not preserve old Cthulhu event-manager behavior. +- Do not keep compositor-state integration in the event path. +- Do not keep old camelCase script/event APIs as final public compatibility surfaces. +- Do not build an adapter layer around the old event queue. +- Do not edit `~/.local/.../cthulhu` directly. +- Do not require sudo or system-level changes. + +## Risk Notes + +The largest risk is the size of the import closure. Orca 50's event path is a manager slice, not a single-file replacement. + +The second risk is partial API translation. Mixing the Orca 50 managers with the old Cthulhu `Script` surface would create fragile compatibility behavior, so the script layer is part of the rebase. + +The third risk is deliberate behavioral churn. Since the requested direction is "Preserve nothing," old Cthulhu event-specific behavior is not a regression target unless basic screen-reader operation is broken.