From c4733e0624dd3cfa56df1a5d159b0036d90ae7f2 Mon Sep 17 00:00:00 2001 From: Gabriel Brown Date: Tue, 18 Aug 2026 18:43:37 -0400 Subject: [PATCH] Plan Panama roadmap completion --- .../plans/2026-08-18-roadmap-completion.md | 176 ++++++++++++++++++ .../2026-08-18-roadmap-completion-design.md | 127 +++++++++++++ 2 files changed, 303 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-18-roadmap-completion.md create mode 100644 docs/superpowers/specs/2026-08-18-roadmap-completion-design.md diff --git a/docs/superpowers/plans/2026-08-18-roadmap-completion.md b/docs/superpowers/plans/2026-08-18-roadmap-completion.md new file mode 100644 index 0000000..b9124ff --- /dev/null +++ b/docs/superpowers/plans/2026-08-18-roadmap-completion.md @@ -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 ` 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. + diff --git a/docs/superpowers/specs/2026-08-18-roadmap-completion-design.md b/docs/superpowers/specs/2026-08-18-roadmap-completion-design.md new file mode 100644 index 0000000..b83514c --- /dev/null +++ b/docs/superpowers/specs/2026-08-18-roadmap-completion-design.md @@ -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. +