Plan Panama roadmap completion
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,176 @@
|
|||||||
|
# Panama Roadmap Completion Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** Close every audited correctness gap and finish the approved Phase 3–5 Panama roadmap.
|
||||||
|
|
||||||
|
**Architecture:** Preserve Settings, `DesktopPreferences`, and `Theme.qml` as the existing ownership spine. Add narrowly scoped event observers, adapters, and generated artifacts around those boundaries; contextual shell surfaces only route into Settings. Each task is independently committed and contract-tested before final integration.
|
||||||
|
|
||||||
|
**Tech Stack:** Quickshell/QML, JavaScript, Bash, Python 3, Hyprland Lua, systemd user units, `jq`.
|
||||||
|
|
||||||
|
**Spec:** `docs/superpowers/specs/2026-08-18-roadmap-completion-design.md`
|
||||||
|
|
||||||
|
## Global Constraints
|
||||||
|
|
||||||
|
- Preserve the current Prism/Tokyo Night design language and existing component library.
|
||||||
|
- Do not introduce continuously repainting effects or polling loops.
|
||||||
|
- Do not expose or modify `config/bash/env`.
|
||||||
|
- Write a failing contract before each production change and record the red/green commands.
|
||||||
|
- Keep interactive QML harnesses and Quickshell restarts for the final integration gate.
|
||||||
|
- Generated and user-owned files must be written atomically.
|
||||||
|
- No production configuration is activated until the reviewed branch is merged.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Task 1: Close Phase 1 and Phase 2 safety gaps
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/README.md`
|
||||||
|
- Modify: `config/dot/hypr/looks.lua`
|
||||||
|
- Modify: `config/dot/quickshell/services/Displays.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/DisplaysPage.qml`
|
||||||
|
- Modify: `config/dot/quickshell/scripts/panama-lock`
|
||||||
|
- Modify: `config/dot/quickshell/services/Wallpaper.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/WallpaperControls.qml`
|
||||||
|
- Test: `tests/quickshell/settings-ownership-contract.sh`
|
||||||
|
- Test: `tests/quickshell/display-transaction-contract.sh`
|
||||||
|
- Test: `tests/quickshell/lock-screen-helper-contract.sh`
|
||||||
|
- Test: `tests/quickshell/wallpaper-service-contract.sh`
|
||||||
|
- Test: `tests/quickshell/wallpaper-settings-contract.sh`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: `Displays.primaryFirstMonitors`, event-driven topology refresh, and a lock helper that never emits an unreadable image.
|
||||||
|
- Consumes: current `Theme.accent`, `Theme.accentSecondary`, display transaction rollback, and wallpaper preference schema.
|
||||||
|
|
||||||
|
- [ ] Add failing ownership assertions that active borders derive from `Theme.accent` and `Theme.accentSecondary`, while inactive borders derive only from scheme roles; verify the current contract fails for the stale prohibition.
|
||||||
|
- [ ] Update the ownership implementation comments and documentation, then run `bash tests/quickshell/settings-ownership-contract.sh` and verify PASS.
|
||||||
|
- [ ] Add a failing display fixture that changes the harness screen model without calling the display service’s public `refresh()` and expects topology reconciliation plus rollback of a pending transaction.
|
||||||
|
- [ ] Add an event-driven screen-model observer and primary-first derived monitor list; run `bash tests/quickshell/display-transaction-contract.sh` and `bash tests/quickshell/display-layout-contract.sh`.
|
||||||
|
- [ ] Add failing lock fixtures for missing global and per-monitor wallpapers, requiring readable shipped-image fallback and screenshot fallback when no image exists.
|
||||||
|
- [ ] Tighten `panama-lock` path validation and bounded warnings; run `bash tests/quickshell/lock-screen-helper-contract.sh`.
|
||||||
|
- [ ] Add failing wallpaper contracts for primary-first output order, selection preservation, and a HOME path containing a single quote.
|
||||||
|
- [ ] Replace inline `bash -lc` path interpolation with an argument-safe helper and update controls to preserve selection; run both wallpaper contracts.
|
||||||
|
- [ ] Run the Task 1 contract set and commit with message `Close desktop safety gaps`.
|
||||||
|
|
||||||
|
### Task 2: Complete contextual configuration and reliable overview capture
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `config/dot/quickshell/modules/dock/Dock.qml`
|
||||||
|
- Modify: relevant dock context-menu component if already split
|
||||||
|
- Modify: `config/dot/quickshell/modules/notifications/NotificationCard.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/osd/Osd.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/overview/WindowThumbnail.qml`
|
||||||
|
- Modify: `config/dot/quickshell/services/ShellState.qml`
|
||||||
|
- Test: `tests/quickshell/settings-jump-contract.sh`
|
||||||
|
- Create or modify: `tests/quickshell/overview-thumbnail-contract.sh`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: one route per configurable surface into the existing owning Settings page.
|
||||||
|
- Consumes: `ShellState.openSettings(page)` and the existing app-icon thumbnail fallback.
|
||||||
|
|
||||||
|
- [ ] Extend the settings-jump contract so it fails until dock, notifications, and OSD each expose a contextual Settings route without replacing their primary action.
|
||||||
|
- [ ] Add the three restrained contextual actions using existing menu/button styles and Settings routes.
|
||||||
|
- [ ] Add a failing static/isolated contract proving capture does not start before recording readiness, is bounded, and retains the icon fallback.
|
||||||
|
- [ ] Gate capture on recording readiness or the appropriate Quickshell frame-ready signal, remove warning-producing blind retries, and keep capture event-driven.
|
||||||
|
- [ ] Run both contracts and commit with message `Complete contextual desktop controls`.
|
||||||
|
|
||||||
|
### Task 3: Complete advanced accents and named themes
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `config/dot/quickshell/config/PreferenceSchema.qml`
|
||||||
|
- Modify: `config/dot/quickshell/config/Theme.qml`
|
||||||
|
- Create: `config/dot/quickshell/services/ThemeProfiles.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/AccentPicker.qml`
|
||||||
|
- Create: `config/dot/quickshell/modules/settings/AccentEditor.qml`
|
||||||
|
- Create: `config/dot/quickshell/modules/settings/ThemeProfilePicker.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/AppearancePage.qml`
|
||||||
|
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
|
||||||
|
- Modify: `config/dot/quickshell/services/SettingsSearch.qml`
|
||||||
|
- Test: create `tests/quickshell/theme-profiles-contract.sh`
|
||||||
|
- Test: create `tests/quickshell/accent-controls-contract.sh`
|
||||||
|
- Test: modify `tests/quickshell/control-center-contract.sh`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: profile records `{id,name,scheme,accent,secondary,shipped}` and reactive `Theme` colour roles.
|
||||||
|
- Consumes: `DesktopPreferences`, `SystemSettings.commitPreference`, `hyprpicker`, and current Prism Settings components.
|
||||||
|
|
||||||
|
- [ ] Write failing pure-model fixtures for three shipped profiles, custom profile creation, bounded unique names, shipped-profile immutability, and HSV/hex conversion.
|
||||||
|
- [ ] Implement `ThemeProfiles` with Moon, Moon Rose, and Day plus saved custom profiles, then verify model tests.
|
||||||
|
- [ ] Write failing UI contracts for labelled HSV controls, curated swatches, keyboard focus, screen picking, profile save/switch/delete, and search routing.
|
||||||
|
- [ ] Build the profile picker and advanced editor from existing `SettingRow`, `ValueSlider`, `SettingsButton`, and focus tokens; do not add ambient animation.
|
||||||
|
- [ ] Update `Theme.qml` and `ColorScheme` so custom pairs reactively reach shell roles and Hyprland borders.
|
||||||
|
- [ ] Extend the Control Center contract to cover power profiles, night light, and colour scheme controls added after its original contract.
|
||||||
|
- [ ] Run theme, accent, ownership, settings-search, and Control Center contracts; commit with message `Complete the Panama theme system`.
|
||||||
|
|
||||||
|
### Task 4: Propagate the accent to external applications
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `config/dot/quickshell/scripts/panama-theme-apps`
|
||||||
|
- Modify: `config/dot/quickshell/services/ColorScheme.qml`
|
||||||
|
- Modify: tracked kitty/tmux/Vicinae/Wofi/Neovim include points as required
|
||||||
|
- Create: generated-file templates or helpers under the owning application directories
|
||||||
|
- Test: create `tests/quickshell/theme-apps-accent-contract.sh`
|
||||||
|
- Test: modify `tests/quickshell/gtk-theme-contract.sh` if its invocation contract changes
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: `panama-theme-apps dark|light [#RRGGBB #RRGGBB]` with per-adapter JSON status.
|
||||||
|
- Consumes: the selected profile’s validated primary and secondary accents.
|
||||||
|
|
||||||
|
- [ ] Write a failing isolated fixture invoking the helper with dark/light and custom pairs, asserting atomic generated overrides for kitty, tmux, btop, Vicinae/Wofi, hyprlock, and Neovim plus backward-compatible two-state invocation.
|
||||||
|
- [ ] Implement validated optional accent arguments and independent adapters; never rewrite user-owned base files wholesale.
|
||||||
|
- [ ] Update each application’s tracked config to include its generated accent override after the base Tokyo Night theme.
|
||||||
|
- [ ] Pass the selected pair from `ColorScheme` and expose bounded adapter failures through its existing error state.
|
||||||
|
- [ ] Run the isolated helper contract, GTK contract, Bash syntax, and a fixture-only idempotence check; commit with message `Propagate accents across desktop applications`.
|
||||||
|
|
||||||
|
### Task 5: Finish onboarding, recovery automation, and generated docs
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify: `config/dot/quickshell/config/PreferenceSchema.qml`
|
||||||
|
- Create: `config/dot/quickshell/modules/settings/WelcomePage.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
|
||||||
|
- Modify: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
|
||||||
|
- Modify: `config/dot/quickshell/services/SettingsSearch.qml`
|
||||||
|
- Modify: `config/dot/quickshell/services/SystemSettings.qml`
|
||||||
|
- Modify: display/theme/reset/restore call sites for pre-risk snapshots
|
||||||
|
- Modify: `setup/scripts/link-dotfiles`
|
||||||
|
- Create: user systemd snapshot service/timer files under the existing systemd config tree
|
||||||
|
- Create: `config/dot/quickshell/scripts/panama-generate-docs`
|
||||||
|
- Create: `docs/SETTINGS.md`
|
||||||
|
- Create: `docs/SHORTCUTS.md`
|
||||||
|
- Test: create `tests/quickshell/first-run-contract.sh`
|
||||||
|
- Test: modify `tests/quickshell/settings-backup-live-contract.sh`
|
||||||
|
- Test: create `tests/quickshell/generated-docs-contract.sh`
|
||||||
|
- Test: modify `tests/quickshell/keybind-rebind-contract.sh`
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Produces: fresh-install marker lifecycle, `snapshot --cause <cause>` retention, and deterministic generated Markdown.
|
||||||
|
- Consumes: existing Settings navigation, backup/restore helper, preference schema, and shipped keybind metadata.
|
||||||
|
|
||||||
|
- [ ] Write failing first-run fixtures proving only fresh installs get a marker, completion removes it atomically, existing settings are not interrupted, and Welcome remains searchable.
|
||||||
|
- [ ] Implement the Welcome page and marker lifecycle using existing card/row components.
|
||||||
|
- [ ] Add failing backup fixtures for daily retention and pre-risk snapshots before display layout, named theme, reset-all, and restore operations.
|
||||||
|
- [ ] Extend the backup helper/service with labelled atomic snapshots, fourteen-day retention, and a systemd user timer; wire the four risky call sites.
|
||||||
|
- [ ] Strengthen keybind contracts to explicitly cover both rebind and reset collisions.
|
||||||
|
- [ ] Write a failing drift contract for generated settings and shortcut documentation.
|
||||||
|
- [ ] Implement the deterministic generator, generate both Markdown files, and verify a second run produces no diff.
|
||||||
|
- [ ] Run first-run, backup, keybind, generated-docs, schema, and search contracts; commit with message `Finish onboarding and desktop recovery`.
|
||||||
|
|
||||||
|
### Task 6: Integrate, review, activate, and verify live readiness
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Modify only files required by review findings.
|
||||||
|
- Update roadmap/status documentation to mark exact delivered scope.
|
||||||
|
|
||||||
|
**Interfaces:**
|
||||||
|
- Consumes: all preceding task commits.
|
||||||
|
- Produces: reviewed `main`, pushed origin, one activated Quickshell session, and an evidence ledger.
|
||||||
|
|
||||||
|
- [ ] Run `git diff --check`, executable Bash syntax, Lua syntax, generated-doc drift, every non-interactive Quickshell contract, and Hyprland configuration validation.
|
||||||
|
- [ ] Dispatch a whole-branch code review against this plan and fix every Critical/Important finding with one reviewed fix wave.
|
||||||
|
- [ ] Merge the reviewed branch into `main` without rewriting shared history and push `origin/main`.
|
||||||
|
- [ ] Run the repository’s user-level setup/link step needed for new systemd units and autostarts; do not print environment secrets.
|
||||||
|
- [ ] Resolve live health where locally actionable: enable RustDesk and Nextcloud user autostart, install/link calendar integration if its declared dependency is already available, and leave hardware-only DDC as a documented warning.
|
||||||
|
- [ ] Restart Quickshell once, perform the interactive visual/runtime gate, inspect logs for QML errors and screencopy warnings, and run `panama-doctor --json`.
|
||||||
|
- [ ] Record exact passed commands, remaining environment-only observations, and final commit IDs.
|
||||||
|
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
# Panama Roadmap Completion Design
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Finish the approved five-phase Panama desktop roadmap without diluting the
|
||||||
|
existing Prism/Tokyo Night identity or introducing parallel sources of truth.
|
||||||
|
The result must be safe enough for the daily desktop, understandable to a
|
||||||
|
normal GNOME/macOS user, and configurable without editing shell files.
|
||||||
|
|
||||||
|
## Fixed product decisions
|
||||||
|
|
||||||
|
- The existing Prism glass visual language, spacing, typography, and motion
|
||||||
|
tokens remain authoritative. New surfaces reuse existing Settings widgets.
|
||||||
|
- Curated named accents remain the fast path. Advanced colour controls add HSV
|
||||||
|
and screen picking without replacing the curated choices.
|
||||||
|
- Settings remain the sole configuration application. Contextual affordances
|
||||||
|
route into an owning Settings page instead of duplicating controls.
|
||||||
|
- User-selected accent is a theme role. `ColorScheme` applies it to external
|
||||||
|
systems but must never substitute a scheme-owned hard-coded focused colour.
|
||||||
|
- Existing installations must not be surprised by an automatic welcome flow.
|
||||||
|
Only fresh installs receive the first-run marker; the welcome page remains
|
||||||
|
manually discoverable later.
|
||||||
|
- No continuously repainting animation or background polling is introduced.
|
||||||
|
Hardware/topology changes are event-driven; periodic snapshots use a user
|
||||||
|
systemd timer.
|
||||||
|
|
||||||
|
## 1. Correctness and safety closure
|
||||||
|
|
||||||
|
The ownership contract and documentation will be updated to reflect the actual
|
||||||
|
boundary: `Theme` owns the active accent values, while `ColorScheme` owns
|
||||||
|
applying those values to Hyprland alongside its scheme-relative inactive role.
|
||||||
|
|
||||||
|
Displays will observe the Quickshell screen model. A topology change refreshes
|
||||||
|
the full compositor layout. If a confirmation transaction is active, it enters
|
||||||
|
the existing safe rollback path using only currently connected outputs. The
|
||||||
|
production observer, rather than an explicit test-only refresh, is exercised by
|
||||||
|
the transaction contract.
|
||||||
|
|
||||||
|
The lock generator will accept wallpaper paths only when they are absolute,
|
||||||
|
regular, and readable. Missing global or per-output images fall back to the
|
||||||
|
shipped wallpaper when readable, then to screenshot mode. Generation remains
|
||||||
|
atomic and returns a bounded user-facing warning.
|
||||||
|
|
||||||
|
Wallpaper discovery will move shell quoting into a narrow helper that accepts
|
||||||
|
paths as arguments. Per-monitor choices list the selected primary output first
|
||||||
|
and preserve a valid selection across topology changes.
|
||||||
|
|
||||||
|
## 2. Contextual configuration and overview reliability
|
||||||
|
|
||||||
|
Every configurable shell surface gets an unobtrusive route to its owning page:
|
||||||
|
|
||||||
|
- Bar widgets keep their current secondary-click behavior.
|
||||||
|
- Dock context menus include a final “Dock settings” action without replacing
|
||||||
|
application actions.
|
||||||
|
- Notification cards expose “Notification settings” in their overflow menu.
|
||||||
|
- A secondary click on a visible OSD opens Accessibility/OSD settings and then
|
||||||
|
dismisses the OSD.
|
||||||
|
|
||||||
|
Overview thumbnails remain event-driven. Capture begins only after the overview
|
||||||
|
surface has a valid recording context. Retry logic must not knowingly call
|
||||||
|
`captureFrame()` while the context is unavailable, must stop after a bounded
|
||||||
|
deadline, and must leave the existing app-icon fallback without warning spam.
|
||||||
|
|
||||||
|
## 3. Complete theme system
|
||||||
|
|
||||||
|
Appearance presents three layers in one hierarchy:
|
||||||
|
|
||||||
|
1. Shipped named themes: Moon, Moon Rose, and Day.
|
||||||
|
2. Saved user themes, capturing colour scheme and accent pair.
|
||||||
|
3. Advanced accent editing: hue, saturation, and value controls plus
|
||||||
|
`hyprpicker` screen sampling.
|
||||||
|
|
||||||
|
The persisted model contains a stable profile identifier, display name, colour
|
||||||
|
scheme, primary accent, and secondary accent. Curated swatches map onto shipped
|
||||||
|
profiles. A custom edit switches to a custom profile without mutating a shipped
|
||||||
|
definition. Saved names are trimmed, bounded, and unique.
|
||||||
|
|
||||||
|
`Theme.qml` remains the in-shell source of truth. The selected pair flows to the
|
||||||
|
bar, dock, panels, notifications, OSD, focused Hyprland border, and lock preview.
|
||||||
|
All controls have keyboard focus, visible focus treatment, and text labels; hue
|
||||||
|
is never the only signal.
|
||||||
|
|
||||||
|
## 4. External accent propagation
|
||||||
|
|
||||||
|
`panama-theme-apps` will accept scheme plus an optional validated accent pair.
|
||||||
|
Omitted accents preserve backward compatibility. It atomically writes small
|
||||||
|
generated overrides rather than rewriting user-owned base configuration.
|
||||||
|
|
||||||
|
The current accent pair propagates to kitty, tmux, btop, Vicinae/Wofi, the
|
||||||
|
managed lock screen, and Panama's Neovim theme hook. Running kitty/tmux/Vicinae
|
||||||
|
instances are refreshed only through supported live interfaces; applications
|
||||||
|
without safe reload retain the generated value for their next launch.
|
||||||
|
|
||||||
|
Each adapter reports `written`, `applied`, `skipped`, or `failed`. One adapter
|
||||||
|
failure does not prevent other targets from updating, but the shell receives a
|
||||||
|
bounded summary and exposes failures in health diagnostics.
|
||||||
|
|
||||||
|
## 5. First run, recovery, and generated documentation
|
||||||
|
|
||||||
|
The installer creates a first-run marker only for a new Panama settings store.
|
||||||
|
On the first shell session, Settings opens a restrained Welcome page covering:
|
||||||
|
launcher, tiling/window movement, Control Center, notifications/clipboard, and
|
||||||
|
health. Completion removes the marker atomically. The page can always be opened
|
||||||
|
from Settings search.
|
||||||
|
|
||||||
|
Existing shortcut collision refusal remains the conflict-detection mechanism
|
||||||
|
and gains contract coverage for both rebind and reset collisions.
|
||||||
|
|
||||||
|
Settings snapshots run daily through a user systemd timer and before these
|
||||||
|
risky operations: applying a complete display layout, applying a named theme,
|
||||||
|
resetting all preferences, and restoring a snapshot. Automatic snapshots are
|
||||||
|
labelled by cause, atomic, and retained for fourteen daily generations plus the
|
||||||
|
most recent snapshot for each risky cause.
|
||||||
|
|
||||||
|
A deterministic generator produces `docs/SETTINGS.md` and
|
||||||
|
`docs/SHORTCUTS.md` from the preference schema and shipped keybind metadata.
|
||||||
|
A contract fails when committed documentation differs from generated output.
|
||||||
|
|
||||||
|
## 6. Verification and rollout
|
||||||
|
|
||||||
|
Work is built in an isolated worktree. Unit/contract tests run per task. No
|
||||||
|
interactive QML harness is opened on the daily desktop until the final gate.
|
||||||
|
The final gate includes every Quickshell contract, shell/Lua syntax, Hyprland
|
||||||
|
configuration validation, generated-document drift, a clean runtime log, and a
|
||||||
|
manual visual pass after merge. The branch is merged to `main`, pushed, and only
|
||||||
|
then activated by restarting Quickshell once.
|
||||||
|
|
||||||
Reference in New Issue
Block a user