# 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.