storm/cthulhu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add settings and preferences policy to Orca 50 spec

Browse Source
This commit is contained in:
Hunter Jozwiak
2026-04-10 20:07:39 -04:00
parent 013c81d19b
commit fb573c83d1
1 changed files with 45 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/superpowers/specs/2026-04-10-orca-50-event-system-rebase-design.md
View File

@@ -63,6 +63,26 @@ Command and presentation ownership should move to Orca 50's managers:
- Add required presenter modules such as `braille_presenter.py`.
- Port existing presenter modules as needed to the Orca 50 manager API.
Settings and preferences should move to Orca 50's manager model while keeping
Cthulhu's TOML persistence:
- Keep `user-settings.toml` and `app-settings/*.toml` as Cthulhu's only persisted settings store.
- Do not use dconf/GSettings persistence and do not require installed Cthulhu GSettings schemas.
- Implement `gsettings_registry.py` as a Cthulhu TOML-backed registry facade with the Orca 50 API shape.
- Preserve Orca 50 registry APIs needed by managers and preferences grids: `layered_lookup`, `set_runtime_value`, `clear_runtime_values`, `set_active_profile`, `set_active_app`, `get_keybindings`, `get_pronunciations`, `save_schema`, and registration decorators.
- Migrate TOML data to Orca 50 schema/key labels instead of carrying old Cthulhu keys as the permanent internal model.
- Use Orca 50 `migration_key` metadata where possible.
- Add Cthulhu-specific migration aliases where upstream Orca cannot know the old name. For example, migrate old `cthulhuModifierKeys` into the new per-layout modifier-key settings, based on the saved keyboard layout.
- Keep legacy aliases as read/import fallbacks for old TOML files, not as the post-migration write format.
Preferences UI should move to the Orca 50 grid model:
- Add `preferences_grid_base.py` and use Orca 50's manager/presenter-owned preferences grids.
- Use Orca 50's newer `guilabels.py` user-facing labels, translated only for Cthulhu branding where appropriate.
- Do not retrofit the old Glade-backed `cthulhu-setup.ui` dialog to the new settings model as the final approach.
- Port Cthulhu-only preference pages into the grid model rather than silently losing them. OCR settings are explicitly in scope for the first pass.
- Inventory plugin and AI preference pages in the implementation plan. Either port them in the same pass or explicitly stage them with a temporary access plan; do not leave them stranded without an intentional decision.
The script layer should be ported to the Orca 50 API:
- `script.py`
@@ -115,12 +135,15 @@ If new Python modules are added under `src/cthulhu/`, update `src/cthulhu/meson.
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.
2. Add the TOML-backed `gsettings_registry.py` facade, migration helpers, and preferences-grid base.
3. Add TOML migration from old Cthulhu keys to Orca 50 schema/key labels.
4. Port `script.py` and `script_manager.py` to the Orca 50 script API.
5. Port `input_event.py`, `input_event_manager.py`, `ax_device_manager.py`, and modifier management.
6. Add `command_manager.py` and move default-script command/keybinding setup.
7. Add `presentation_manager.py` and required presenters.
8. Port preferences UI to the Orca 50 grid model, including OCR settings.
9. Replace `event_manager.py` last.
10. Remove or rewrite obsolete Cthulhu event tests after the replacement semantics are in place.
## Testing Strategy
@@ -145,6 +168,14 @@ Remove or rewrite tests that assert behavior intentionally discarded by this reb
Add Cthulhu-specific smoke coverage only for renamed package/branding and install details, such as AT-SPI device naming and Meson integration.
Add settings and preferences coverage:
- Migration tests for old TOML to new TOML schema/key labels.
- Registry tests proving layered lookup, runtime overrides, profile/app context, and save paths hit TOML rather than dconf.
- Tests for Cthulhu-specific aliases such as `cthulhuModifierKeys`.
- Preferences-grid smoke coverage for migrated Cthulhu-only pages, including OCR.
- Regression coverage that OCR settings remain reachable and persist after saving.
Verification order after implementation:
1. Run targeted Python tests for the manager slice.
@@ -157,6 +188,9 @@ Verification order after implementation:
- 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 use dconf/GSettings as Cthulhu's persisted settings store.
- Do not preserve old Cthulhu TOML key labels as the final write format.
- Do not keep the old Glade-backed preferences dialog as the final UI for migrated Orca 50 settings.
- Do not edit `~/.local/.../cthulhu` directly.
- Do not require sudo or system-level changes.
@@ -166,4 +200,8 @@ The largest risk is the size of the import closure. Orca 50's event path is a ma
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.
The third risk is settings migration. Keeping TOML as the store while adopting Orca 50's settings API reduces dependence on dconf, but it requires a deliberate registry facade and one-time TOML migration. The facade must not become a broad compatibility layer that permanently hides old names.
The fourth risk is preferences UI scope. Orca 50's preferences are manager/presenter-owned grids, while current Cthulhu still has a large Glade-backed dialog. Cthulhu-only pages such as OCR must be ported or explicitly staged to avoid losing access to settings.
The fifth 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.