Plan Panama roadmap completion

2026-08-20 21:58:25 -04:00
parent e1faaf7a76
commit c4733e0624
2 changed files with 303 additions and 0 deletions
@@ -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.
+