From fb573c83d1b0d90b3a7971484a3a16145153a759 Mon Sep 17 00:00:00 2001 From: Hunter Jozwiak Date: Fri, 10 Apr 2026 20:07:39 -0400 Subject: [PATCH] Add settings and preferences policy to Orca 50 spec --- ...4-10-orca-50-event-system-rebase-design.md | 52 ++++++++++++++++--- 1 file changed, 45 insertions(+), 7 deletions(-) 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 index df85505..302d43e 100644 --- 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 @@ -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.