# Panama Control Center design

## Summary

Panama will expand the existing top-right Quick Settings popover into a complete
Control Center. Wi-Fi, Bluetooth, Focus, Caffeine, Night Light, audio, account,
settings, and power remain in place. Home Assistant favorites and lightweight
iPhone continuity join that same surface instead of creating separate windows
or permanent bar widgets.

The approved visual direction is **A · Continuity Card**, integrated into the
Control Center. The panel keeps Panama's Prism glass and Tokyo Night Moon
language, grows to 430 logical pixels, and begins two pixels below the bar. Home
is a first-class control section; KDE Connect is deliberately smaller because
the paired iPhone exposes only a useful subset of KDE Connect.

## Goals

- Make the top-right popover feel like a complete desktop Control Center rather
  than a small collection of connectivity toggles.
- Toggle the existing Home Assistant favorites without opening a browser.
- Preserve the user's seven enabled Home Assistant lights and use Home
  Assistant friendly names and live states.
- Show the paired iPhone's real reachability and expose Send File, Send
  Clipboard, and Ring actions.
- Represent phone transfers in Ongoing while active and as quiet recent
  exchanges after completion.
- Keep credentials, Home Assistant responses, clipboard contents, and local
  file paths out of Git and shell logs.
- Leave BlueBubbles as the messaging implementation rather than manufacturing
  an inferior KDE Connect messaging surface.

## Non-goals

- Panama will not add SMS or iMessage controls. BlueBubbles already owns that
  experience.
- Panama will not show an iPhone battery percentage until the device reports a
  real value. The current KDE Connect battery interface returns `-1`.
- Panama will not expose remote input, device locking, remote commands, or phone
  notifications when the paired iPhone does not advertise those capabilities.
- Panama will not become a full Home Assistant dashboard or entity editor.
- Panama will not store a Home Assistant token in tracked files, QML, fixtures,
  process arguments, or logs.
- The first release does not pair or unpair KDE Connect devices inside Panama.
  KDE Connect's own pairing UI remains the safe handoff.

## Verified system state

KDE Connect currently reports one paired iPhone.
Its live D-Bus object exposes clipboard, find-my-phone, ping, share, and battery
plugins. The battery plugin has no value, and the remote-input object exposes no
callable control methods. Panama must derive action visibility from advertised
capabilities rather than from generic KDE Connect marketing claims.

The existing GNOME Home Assistant extension points to the user's Home Assistant
instance and has seven enabled light entities: all lights, kitchen lights, two
individual lights, bedroom, living room, and hall. It stores the long-lived
access token in Secret Service under `token_string=user_token`; it does not keep
the token in dconf.

## Interaction model

Clicking the existing right-side status cluster or pressing `Super+S` opens the
same Control Center. No new global shortcut is added.

The resting panel is ordered by frequency and scope:

1. Wi-Fi, Bluetooth, Caffeine, and Night Light toggle grid.
2. Focus and audio controls.
3. Home favorites.
4. Phone continuity.
5. User, Panama Settings, and power footer.

The panel starts two logical pixels beneath the bar instead of using the current
double bar-gap offset. It stays right-aligned and retains outside-click and
Escape dismissal. Its content scrolls when an expanded device list exceeds the
usable monitor height; the layer-shell window itself never extends beyond the
work area.

Only one detail section is expanded at a time. Wi-Fi, Bluetooth, sink, source,
Home, and Phone all participate in the existing `expandedSection` state so the
panel remains predictable.

## Home section

The resting Home card shows the first four enabled favorites in their saved
order. Each tile contains a domain-appropriate glyph, a friendly name, and a
plain state such as `On`, `Off`, or `Unavailable`. Enabled lights use a quiet
amber light treatment; Panama blue remains reserved for desktop selection and
focus.

Clicking a toggleable tile calls Home Assistant and temporarily disables only
that tile. The state is refreshed from Home Assistant after the request rather
than being permanently changed optimistically. Success is reflected visually
without a toast or Signal Glass event. A failure restores the last known state
and displays a concise inline error inside the Home section.

The trailing `N accessories` action expands a full list of configured
favorites inside the Control Center. No unconfigured Home Assistant entity is
shown. An `Open Home Assistant` action launches the configured base URL.

If Home Assistant is unreachable, Panama retains the last good states for the
current shell session, marks them stale, and offers Retry. If no URL or token is
available, the section becomes one setup row rather than disappearing or
breaking the rest of Control Center.

## Phone section

The Phone card follows approved mock A at a smaller scale:

- device silhouette, friendly name, and `Nearby on Wi-Fi` or `Not nearby`;
- Send File, Send Clipboard, and Ring as compact icon actions;
- one recent transfer row only when a real exchange occurred in the current
  shell session; and
- a Device Settings handoff to Panama Settings connectivity controls.

The bar adds a small phone glyph only while at least one paired phone is
reachable. It is status, not a second click target; the existing status cluster
continues to open Control Center.

Send File opens a graphical file chooser. Confirming a file starts a KDE
Connect share process. Canceling the chooser has no side effect and produces no
event. The action accepts regular local files only; URLs and directories are
not inferred from arbitrary text.

Send Clipboard tells KDE Connect to send the current clipboard through its own
clipboard plugin. Panama never reads, stores, previews, or logs clipboard text
for this action. Ring invokes find-my-phone only when that plugin is advertised.

Phone actions are disabled while the device is unreachable. Connection and
disconnection remain ambient Status Events under the existing global curation
policy. A completed transfer may appear as a quiet recent row and an important
Signal Glass event; canceling or failing a transfer produces a concise warning.
Ring and clipboard success do not produce global events.

## Architecture

### KDE Connect service

Add `services/KdeConnect.qml` as the shell-facing state owner. It exposes the
paired devices, preferred phone, reachability, advertised actions, current
transfer, and recent exchange. It supervises small allow-listed helper
commands; UI components never assemble shell command strings.

Add `scripts/panama-kdeconnect` with a JSON contract:

- `status` reports paired devices, reachability, type, and supported actions;
- `send-file DEVICE FILE` validates a regular file and shares it;
- `send-clipboard DEVICE` invokes the KDE Connect clipboard plugin; and
- `ring DEVICE` invokes find-my-phone.

The helper uses `kdeconnect-cli` and the session D-Bus service. It emits no
certificate fingerprints, IP addresses, clipboard contents, or file contents.
Status refreshes when Control Center opens and on a low-frequency fallback
timer. The existing `DeviceEvents.qml` reads this service instead of launching
its own independent KDE Connect probe.

Transfer state is contributed to `Ongoing.qml`. A running share shows filename,
device name, and a Cancel action when the child process can still be stopped.
No fake percentage is shown because KDE Connect's public CLI does not provide
reliable byte progress for this device.

### Home Assistant bridge

Add `scripts/panama-home-assistant`, a small local bridge with four commands:

- `probe` reports configuration and API availability without entity details;
- `snapshot` returns only configured favorites and normalized state;
- `toggle ENTITY_ID` calls the Home Assistant service for an allow-listed
  configured entity; and
- `open` launches the configured Home Assistant URL.

Configuration resolution is intentionally layered:

1. `PANAMA_HOME_ASSISTANT_URL`, `PANAMA_HOME_ASSISTANT_TOKEN`, and optional
   `PANAMA_HOME_ASSISTANT_ENTITIES` from the gitignored `config/bash/env`;
2. the existing GNOME extension's `hass-url` and enabled-entity dconf values;
3. the existing Secret Service item with `token_string=user_token`.

This preserves the current working setup without copying a token. Explicit
Panama environment variables can replace the compatibility fallbacks later.
The bridge sends the token only in the Home Assistant Authorization header and
redacts request failures before returning them to QML.

Add `services/HomeAssistant.qml` to own normalized entities, loading and stale
state, per-entity busy state, and inline errors. It refreshes when Control
Center opens, after a toggle, and at a bounded interval while the panel is
visible. It does not continuously poll while the panel is closed.

### Control Center components

Keep `QuickSettings.qml` as the only layer-shell window and
`QuickSettingsPanel.qml` as composition. Add focused presentation components
under `modules/quicksettings/`:

- `ControlSectionHeader.qml` for consistent quiet labels and trailing actions;
- `HomeControls.qml` and `HomeTile.qml`;
- `PhoneControls.qml`; and
- `RecentExchange.qml`.

The panel width becomes a named Control Center geometry token rather than
changing the shared popover width used by unrelated surfaces. Existing Wi-Fi,
Bluetooth, audio, Focus, Caffeine, Night Light, footer, keyboard focus, and
outside-click behavior remain intact.

## Security and privacy

- The existing Secret Service token remains the preferred compatibility
  source; no migration requires printing or copying it.
- Environment configuration is allowed only in the already gitignored
  `config/bash/env` file.
- Helpers never echo tokens, Authorization headers, clipboard text, entity
  response bodies, IP addresses, or full local file paths to logs.
- Home Assistant commands accept only entity IDs present in the configured
  favorites snapshot.
- KDE Connect device IDs and file paths are passed as separate process
  arguments, never interpolated into a shell command.
- A user click is required for every Home toggle, phone ring, clipboard send,
  file chooser, and file transfer.

## Failure behavior

- KDE Connect absent: Phone shows `KDE Connect unavailable` with a Settings
  handoff; Control Center remains usable.
- Paired phone offline: identity remains visible, actions disable, and no
  repeated disconnect toast is emitted.
- File chooser canceled: no error and no history entry.
- Transfer failed: Ongoing clears, recent history does not claim success, and a
  concise warning is shown.
- Home Assistant unavailable: last good state remains visibly stale and Retry
  is offered.
- Invalid or expired token: Home shows `Authentication required` without
  exposing the response body.
- One malformed entity is omitted without suppressing healthy favorites.

## Testing and verification

Focused automated coverage will prove:

1. KDE Connect status normalization and capability filtering through synthetic
   command fixtures.
2. File validation, allow-listed device actions, canceled chooser behavior, and
   transfer lifecycle without sending a real file.
3. Home Assistant configuration precedence, response normalization,
   allow-listed toggles, authentication redaction, stale-state retention, and
   malformed-entity isolation against a local fake API.
4. Control Center structure, exclusive detail expansion, Home/Phone empty and
   failure states, Ongoing contribution, status glyph visibility, and the
   two-pixel top attachment through contract tests.
5. Fresh Quickshell construction with no QML errors or warnings and valid
   Hyprland configuration.
6. A live read-only smoke test that reports only the paired/reachable phone
   count, supported-action names, Home Assistant availability, and configured
   entity count.
7. Visual captures of resting, expanded Home, phone offline, transfer active,
   and Home Assistant failure states.

A real Ring, clipboard send, Home light toggle, or file transfer is not part of
automated verification because each changes an external device. Those final
checks require an explicit user action from the finished Control Center.

## Documentation updates

- Update `config/dot/hypr/DESKTOP-PARITY.md` to mark Home Assistant favorites
  and KDE Connect phone integration live.
- Document Control Center behavior, credential resolution, and iOS limitations
  in `config/dot/hypr/README.md`.
- Keep BlueBubbles listed as the messaging application and KDE Connect as the
  continuity/file-transfer layer.
