gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feat/panama-health
Panama/docs/superpowers/plans/2026-08-17-panama-settings.md
T

7.4 KiB
Raw Permalink Blame History

Panama Settings 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: Build the approved Luminous System Settings control center and map it to Super+I while preserving GNOME Settings as a launcher-accessible fallback.

Architecture: A persisted DesktopPreferences singleton owns user choices, SystemSettings owns allow-listed system reads and writes, and a normal tiled Settings window renders focused pages over those boundaries. Existing shell consumers continue through Settings.qml, while ShellState and typed IPC own window routing.

Tech Stack: Quickshell 0.3.0, Qt 6 QML, Quickshell Io and PipeWire, Hyprland 0.56 Lua configuration, systemd, Bash integration contracts

Spec: docs/superpowers/specs/2026-08-17-panama-settings-design.md

Global Constraints

  • Use Tokyo Night Moon tokens and the existing Prism edge; no component-local color literals.
  • Apply only allow-listed Hyprland numeric settings; never execute UI-provided shell text.
  • Do not expose full-time desktop HDR without tested automatic rollback.
  • Do not continuously poll or animate while idle.
  • Preserve GNOME Settings as an installed, searchable fallback.
  • Keep unrelated pre-existing Panama changes untouched.

Task 1: Persisted desktop preferences

Files:

  • Create: config/dot/quickshell/config/DesktopPreferences.qml
  • Modify: config/dot/quickshell/config/Settings.qml
  • Test: tests/quickshell/settings-preferences-contract.sh

Interfaces:

  • Produces: writable use24Hour, showSeconds, showWeekday, showCpu, showMemory, showGpu, dockAutohide, dockRevealDelayMs, dockHideDelayMs, focusDurationMinutes, autoHdr, vrrPolicy, directScanoutPolicy, and lastPage properties plus resetDesktopDefaults(): void.

  • Consumes: Quickshell.stateDir, FileView, and JsonAdapter.

  • Write a standalone Quickshell contract that changes clock, dock, and display-policy values in a disposable state directory, restarts the harness, and asserts the literal values survive.

  • Run the contract and verify it fails because DesktopPreferences does not exist.

  • Implement the JSON adapter and bind dynamic Settings.qml values to it.

  • Run the persistence contract and the existing focus/dock consumers to green.

Task 2: Allow-listed system boundary

Files:

  • Create: config/dot/quickshell/services/SystemSettings.qml
  • Test: tests/quickshell/settings-system-contract.sh

Interfaces:

  • Consumes: DesktopPreferences, NightLight, Notifs, Caffeine, hyprctl, systemctl, and pgrep.

  • Produces: monitor identity and geometry, display-policy setters, bounded refresh(): void, service status, openGnomePanel(panel: string): void, openApplication(id: string): void, and an inline lastError.

  • Write an IPC-backed contract that applies current policy values, refreshes the active monitor, and rejects an unsupported GNOME panel.

  • Run it and verify the settings-system diagnostics target is absent.

  • Implement fixed-command processes and strict numeric/panel allow lists.

  • Run the contract and confirm the live compositor returns to its original values.

Task 3: Luminous window and core pages

Files:

  • Create: config/dot/quickshell/modules/settings/SettingsWindow.qml
  • Create: config/dot/quickshell/modules/settings/SettingsShell.qml
  • Create: config/dot/quickshell/modules/settings/SettingsSidebar.qml
  • Create: config/dot/quickshell/modules/settings/SettingsCard.qml
  • Create: config/dot/quickshell/modules/settings/SettingRow.qml
  • Create: config/dot/quickshell/modules/settings/SettingsToggle.qml
  • Create: config/dot/quickshell/modules/settings/HomePage.qml
  • Create: config/dot/quickshell/modules/settings/AppearancePage.qml
  • Create: config/dot/quickshell/modules/settings/DisplaysPage.qml
  • Create: config/dot/quickshell/modules/settings/DesktopPage.qml
  • Create: config/dot/quickshell/modules/settings/qmldir
  • Test: tests/quickshell/settings-window-contract.sh

Interfaces:

  • Consumes: DesktopPreferences, SystemSettings, NightLight, and ShellState.settingsPage.

  • Produces: a tiled Panama Settings window with Home, Appearance, Displays, and Desktop pages.

  • Write a live contract that opens the window to each core page and verifies one Panama Settings toplevel remains mapped.

  • Run it and verify the settings IPC target is absent.

  • Implement the two-pane Luminous shell and reusable row/card controls.

  • Implement real preference, Night Light, HDR policy, VRR, direct-scanout, clock, vitals, and dock controls.

  • Run the page contract and inspect Quickshell logs for construction warnings.

Task 4: System pages and fallback handoffs

Files:

  • Create: config/dot/quickshell/modules/settings/SoundPage.qml
  • Create: config/dot/quickshell/modules/settings/NotificationsPage.qml
  • Create: config/dot/quickshell/modules/settings/ShortcutsPage.qml
  • Create: config/dot/quickshell/modules/settings/ServicesPage.qml
  • Create: config/dot/quickshell/modules/settings/AboutPage.qml
  • Modify: config/dot/quickshell/modules/settings/SettingsShell.qml
  • Test: tests/quickshell/settings-pages-contract.sh

Interfaces:

  • Consumes: existing PipeWire controls, Notifs, FocusSession, service status from Task 2, and fixed GNOME panel handoffs.

  • Produces: Sound, Notifications & Focus, Shortcuts, Startup & Services, and About destinations.

  • Extend the page contract with search routing, live DND/focus changes, audio construction, service refresh, and GNOME fallback command validation.

  • Run it and verify the new page names fail before implementation.

  • Build the five pages using the same row/card vocabulary and no inactive fake controls.

  • Run contracts and verify absent optional services render as unavailable.

Task 5: Shell, keybinding, launcher, and compositor integration

Files:

  • Modify: config/dot/quickshell/services/ShellState.qml
  • Modify: config/dot/quickshell/shell.qml
  • Modify: config/dot/hypr/keybinds.lua
  • Modify: config/dot/hypr/rules.lua
  • Create: config/local/share/applications/panama-settings.desktop
  • Modify: setup/scripts/link-dotfiles
  • Modify: README.md
  • Modify: config/dot/hypr/README.md

Interfaces:

  • Produces: ShellState.settingsOpen, settingsPage, typed settings and settings-system IPC targets, Super+I, and a searchable desktop entry.

  • Extend the live contract to open, close, toggle, and route directly to a named page.

  • Wire the Settings window and IPC handlers into the shell.

  • Replace the GNOME Settings Super+I command with Panama IPC while retaining the GNOME desktop entry.

  • Let the titled window participate in the active Hyprland tiling layout.

  • Link the Panama desktop entry into ~/.local/share/applications and refresh the launcher cache.

Task 6: Full-system verification

  • Run every Quickshell contract, Hyprland --verify-config, and desktop-file validation.
  • Reload Hyprland, restart Quickshell, and inspect fresh logs for errors or warnings.
  • Exercise Home, Displays, Desktop, Sound, Notifications, Services, shortcut search, and a GNOME handoff.
  • Capture Home, Displays, Desktop, and Services pages for visual review.
  • Inspect the exact Panama diff and confirm unrelated pre-existing changes were preserved.
Reference in New Issue View Git Blame Copy Permalink