# Panama Cohesion Design

## Purpose

Panama has grown from a Hyprland config into a desktop: 15 Lua/conf files, 130 QML
files, 18 services, a 12-page settings application, and 29 contract tests. Each
feature was built well on its own. What is missing is the seam between them.

This document audits the current state and defines the architecture that turns
the pieces into one product, with a single goal:

> **A user should never need a text editor to change how their desktop behaves.**

That goal is not currently met, and the reason is structural rather than a matter
of missing pages.

---

## Part 1 — Audit

### Finding 1 (critical, live bug): every Hyprland write from Settings is a no-op

`services/SystemSettings.qml` applies display policy with `hyprctl keyword`:

```qml
autoHdrWrite.exec(["hyprctl", "keyword", "render:cm_auto_hdr", enabled ? "1" : "0"]);
```

On a Lua-configured Hyprland, `hyprctl keyword` does not work:

```
$ hyprctl getoption decoration:rounding -j     →  "int": 18
$ hyprctl keyword decoration:rounding 4
keyword can't work with non-legacy parsers. Use eval.
$ echo $?                                       →  0
$ hyprctl getoption decoration:rounding -j     →  "int": 18
```

It prints the refusal to **stdout** and exits **0**. `SystemSettings` branches on
`exitCode === 0`, so all three writers take the success path: they persist the
requested value to `panama-settings.json`, clear `lastError`, and the UI redraws
as if the change took effect. Nothing reached the compositor.

Game-aware HDR, VRR policy, and direct scanout have therefore never worked from
Settings, and the app confidently reports that they did. `applyPersistedDisplayPolicy()`
replays the same three no-ops one second after every shell start.

The correct mechanism on this build is `hyprctl eval`, which is verified working:

```
$ hyprctl eval 'hl.config({ decoration = { rounding = 4 } })'   →  ok
$ hyprctl getoption decoration:rounding -j                      →  "int": 4
```

`eval` is also strictly more capable than `keyword` — it can set *any* config
value, including gradients, animation curves, and nested tables. It executes
arbitrary Lua, so the existing "never interpolate UI text into a command" rule
must extend to it: values are validated and serialized numerically, never
concatenated from user input.

### Finding 2: three disconnected sources of truth for the same three values

| Value | `looks.lua` | `DesktopPreferences.qml` | Applied by |
| --- | --- | --- | --- |
| `render:cm_auto_hdr` | `1` | `autoHdr: true` | `hyprctl keyword` (no-op) |
| `misc:vrr` | `3` | `vrrPolicy: 3` | `hyprctl keyword` (no-op) |
| `render:direct_scanout` | `2` | `directScanoutPolicy: 2` | `hyprctl keyword` (no-op) |

They agree today only because they were typed to agree. Editing the Lua does not
change what Settings displays; changing Settings does not touch the Lua. The Lua
side reads no shared state whatsoever — there is no bridge in either direction.

### Finding 3: the preference store costs four hand-edits per knob

Every key in `config/DesktopPreferences.qml` is written out four times: a
`property alias`, a `JsonAdapter` property, a `Connections` handler, and a line
in `resetDesktopDefaults()`. Seventeen keys produce 68 lines of pure bookkeeping.

The failure modes are silent. Omit the `Connections` handler and the setting
stops persisting with no error. Omit the reset line and "Restore defaults"
quietly skips it. This cost is the direct reason the settings app stalled at 16
user-facing knobs.

### Finding 4: ~40 comparable values are hardcoded one file away

`config/Settings.qml` still hardcodes, as `readonly`: weather latitude/longitude,
location label, temperature unit and refresh interval; the vitals poll interval
and the GPU sysfs path; the night-light schedule (`17.0`–`10.0`); all four
notification timing and history limits; the 16-entry dock pin list; the
screenshot and recording directories; and the `wf-recorder` argument string.

Every one of these is exactly the kind of thing the settings app exists for. None
is reachable from it.

### Finding 5: appearance is not adjustable at all

`Theme.qml` defines ~50 tokens, all `readonly`, none mutable. The Appearance
page's "Theme" card is two dead text rows:

```qml
SettingRow { label: "Color palette"; detail: "Tokyo Night Moon"; value: "Prism" }
SettingRow { label: "Interface type"; detail: "Adwaita Sans"; value: "System" }
```

Meanwhile `looks.lua` hardcodes gaps, border size, rounding, blur, shadow, glow,
and fourteen animation curves. The page named "Appearance" adjusts a clock format
and three vitals toggles.

### Finding 6: Shortcuts is a hand-typed copy of 19 of 113 real binds

`keybinds.lua` makes 95 `hl.bind` calls producing **113** live binds. The page
hardcodes an array of **19**. It cannot show the other 94, cannot change any, and
drifts the moment a bind is edited.

The compositor already exposes the real list, and it is 74% self-describing:

```
$ hyprctl binds -j  →  113 binds, 84 carrying a human description
    modmask 64  key T  description "Terminal"
```

### Finding 7: "Restore defaults" is incomplete by construction

`resetDesktopDefaults()` resets `DesktopPreferences` only. Anything persisted
elsewhere survives an action that claims to restore Panama's defaults.

### Finding 8: page scaffolding is copy-pasted eleven times

Every page repeats the same `Flickable` → `Column` → `x: 34` → `y: 30` →
title/subtitle block. Every toggle repeats a four-property inline anchor
incantation:

```qml
SettingsToggle { anchors.right: parent.right; anchors.verticalCenter: parent.verticalCenter;
                 checked: DesktopPreferences.showCpu; onToggled: value => DesktopPreferences.showCpu = value }
```

Across eleven pages there are 56 rows but only ~15 toggles, 14 buttons, and 3
sliders — over half the rows are static text. Pages settled for read-only text
because a real control was expensive to add. That is a tooling problem wearing a
product problem's clothes.

### What is genuinely good and must be preserved

- The `SystemSettings` allow-list discipline — UI never builds a command string.
- The Prism design language and its restraint, documented in `Theme.qml`.
- Event-driven motion; nothing repaints while idle.
- The 29 contract tests and the spec → plan → implement workflow.
- Delegation of hardware, accounts, and printers to GNOME rather than
  half-reimplementing them.

---

## Part 2 — Target architecture

Four changes, in dependency order. Each is independently useful and independently
shippable.

### A. One schema, one store

Replace the hand-maintained preference object with a declarative schema —
one entry per setting carrying key, type, default, bounds or options, group,
label, and detail:

```qml
{ key: "dockHideDelayMs", type: "int", def: 250, min: 0, max: 2000, step: 25,
  group: "dock", label: "Hide delay",
  detail: "Prevents flicker when crossing icons" }
```

Persistence, change notification, validation, reset, and the settings UI all
derive from that one entry. Adding a knob becomes one line instead of four edits
plus a hand-built row, and reset becomes complete by construction rather than by
diligence.

The store moves from Quickshell's opaque per-shell state directory to
`~/.config/panama/settings.json`, so it is a stable path that the compositor can
also read, and one a user can back up, diff, or put in a dotfiles repo.

### B. Hyprland reads the same file

`config/dot/hypr/prefs.lua` gains a small dependency-free JSON reader and exposes
`prefs.get(key, fallback)`. `looks.lua`, `input.lua`, and `monitors.lua` read
through it, keeping their current literals as the fallback:

```lua
rounding = prefs.get("windowRounding", 18),
gaps_out = prefs.get("gapsOut", 10),
```

A missing, empty, or malformed file yields the shipped defaults. The read is
wrapped in `pcall` so a corrupt file can never take down the config.

This closes the loop:

- **Lua is the default.** It ships the curated values and works standalone.
- **The JSON is the truth.** Both sides read it.
- **Settings is the editor.** It writes the JSON *and* applies live via
  `hyprctl eval`, so changes take effect immediately and survive a reboot.

### C. Generic rows, then fill the pages

Add `SettingsPage` (the repeated scaffold), plus `ToggleRow`, `SliderRow`,
`ChoiceRow`, `ActionRow`, and `TextRow`. Rewrite the eleven pages on top of them,
promote the ~40 hardcoded `Settings.qml` values into real controls, and give
Appearance genuine content: accent pair, window rounding, gaps, border size,
blur, animation speed, bar height, font scale, and wallpaper.

Appearance customization stays inside the design language. The user picks how much
of it there is — spacing, softness, motion — not a free-form palette editor that
would let the Prism identity be dismantled by accident.

### D. Shortcuts from the compositor, then editable

Generate the Shortcuts page from `hyprctl binds -j` so it shows all 113 binds and
can never drift. Backfill descriptions for the 29 binds that lack one. Then allow
rebinding: overrides live in the same JSON, `keybinds.lua` applies them after the
defaults, and Settings applies them live with `hyprctl eval`.

---

## Constraints

- No UI-supplied string is ever interpolated into an `eval`, a shell command, or
  a config value. Numbers are range-checked; choices are matched against an
  allow-list; colors are validated as hex before serialization.
- A malformed or absent `settings.json` must degrade to shipped defaults, never
  to a broken compositor.
- `hyprctl keyword` is banned in this codebase. It exits 0 without acting.
- Every write path must be observably verified — read the value back rather than
  trusting an exit code. Finding 1 exists because an exit code was trusted.
- Tokyo Night Moon and Prism remain the only visual identity. Customization
  adjusts its parameters, it does not replace it.
- Motion stays event-driven. No idle repaint, at any setting.
- GNOME keeps ownership of hardware, accounts, printers, and users.

## Out of scope

- Arbitrary theme/palette import.
- A global menu (previously investigated; GTK apps expose `org.gtk.Actions` but
  not `org.gtk.Menus`, so coverage would be too inconsistent to ship).
- Replacing any GNOME-delegated panel.
