128 lines
6.3 KiB
Markdown
128 lines
6.3 KiB
Markdown
# 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.
|
|
|