# Focus Glass and Continuum Overview Design

## Outcome

Panama gains a polished focus-session surface and a GNOME-like workspace overview. The focus surface uses the selected Signal Glass visual language, keeps Command Deck's useful controls, and treats its associated Hyprland workspace as a first-class destination. The overview uses the selected Continuum layout: a workspace filmstrip above a large, spatially familiar active-workspace preview.

## Focus session behavior

- A focus session starts with Panama's configurable default duration of 45 minutes and binds to the currently focused positive-numbered Hyprland workspace.
- Starting a session enables Do Not Disturb and Caffeine. Panama remembers their prior values and restores them when the session ends.
- The session uses a wall-clock deadline rather than decrementing persistent state every second. It therefore survives a Quickshell reload without losing time.
- Pause stores the exact remaining duration. Resume creates a new deadline from that stored duration.
- The session completes automatically at zero and posts a normal desktop notification through the existing Panama notification server.
- End deliberately terminates the session and restores the prior DND and Caffeine values.
- Only one focus session exists at a time. Starting again replaces the old session with a fresh session on the current workspace.

## Signal Glass surface

- The main capsule is a top-centered blurred glass surface below the bar, carrying Panama's Prism edge, Tokyo Night Moon palette, and event-driven open/close motion.
- Its primary row shows the focus icon, workspace label, remaining time, and whether DND and Caffeine are being held.
- Clicking the primary row activates the bound workspace and dismisses the capsule without ending the session.
- The action row contains Pause or Resume, Workspace, and End.
- Workspace opens the Continuum overview with the session's bound workspace selected.
- A labeled close button hides the capsule while the session continues.
- While a session exists, a compact bar indicator remains visible. Clicking it reopens the capsule, so dismissal never makes the running session undiscoverable.
- No focus UI animates while idle. The only periodic update is the once-per-second remaining-time text while a session is running and not paused.

## Discoverability and controls

- Quick Settings includes a full-width Focus row. When idle it starts a 45-minute session on the current workspace. When active it shows the remaining time and opens the capsule.
- `SUPER+SHIFT+F` performs the same start-or-show action.
- A `focus` Quickshell IPC target exposes `start`, `reveal`, `pause`, `workspace`, `overview`, and `end` for launcher integration and diagnostics.

## Continuum overview

- The overview keeps the existing full-screen dimmed and blurred layer, Escape behavior, outside-click dismissal, one-shot window captures, and dynamic-workspace support.
- A horizontally scrollable workspace filmstrip occupies the top of the surface. It contains every positive-numbered workspace plus the trailing new-workspace affordance.
- The focused or requested workspace is rendered as a large preview below the filmstrip. Clicking one of its windows activates that window and closes the overview.
- Selecting a workspace in the filmstrip activates it while keeping the overview open, matching GNOME's spatial workflow. Scrolling over the filmstrip moves left or right through workspaces.
- Opening from the focus capsule initially selects the session workspace and marks it with a subtle focus-session badge.
- A search field filters windows across all positive workspaces by title or application id. Selecting a result activates its workspace and window, then closes the overview.
- The overview IPC target can open directly into a search query, enabling deterministic diagnostics and future launcher actions without synthesizing keyboard input.

## State and boundaries

- `services/FocusSession.qml` owns session timing, persistence, DND and Caffeine coordination, and workspace activation. Visual modules only call its public functions and render its properties.
- `services/ShellState.qml` remains the owner of mutually exclusive overlays and gains only the requested overview workspace id.
- `modules/focus/` owns the capsule and bar indicator.
- `modules/overview/` owns the Continuum presentation and window search.
- Persistent state is stored atomically through Quickshell `FileView` and `JsonAdapter` under `Quickshell.stateDir`; no daemon or new package is required.

## Failure handling

- If the persisted workspace no longer exists, direct activation falls back to Hyprland's workspace dispatcher using the stored positive id.
- A malformed or absent state file falls back to an inactive session with no user-visible error.
- If the shell reloads after the deadline, the session is completed during restoration and its managed DND and Caffeine state is released.
- Search and workspace lists tolerate transient null Hyprland objects while IPC state refreshes.

## Verification

- Validate the focus state machine with a standalone Quickshell harness using a very short session.
- Validate every QML component constructs without warnings against Quickshell 0.3.0.
- Exercise start, pause, resume, dismiss, reopen, workspace activation, overview targeting, automatic completion, and manual end through live IPC.
- Reload the daily-driver shell and inspect its logs for QML errors.
- Capture the capsule, compact indicator, Continuum overview, and search state for visual review.