# Focus Glass and Continuum Overview Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a persistent focus-session workflow with a Signal Glass control capsule and replace the current workspace-card overview with the GNOME-like Continuum filmstrip.

**Architecture:** A singleton `FocusSession` service owns all timing and side effects, while focused QML modules render the capsule, bar indicator, Quick Settings entry point, and overview. `ShellState` carries only overlay selection and the requested overview workspace, keeping focus state independent from window state.

**Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Quickshell Hyprland IPC, Quickshell Io `FileView`/`JsonAdapter`, Hyprland 0.56 Lua configuration

**Spec:** `docs/superpowers/specs/2026-08-17-focus-glass-continuum-design.md`

## Global Constraints

- Use the existing Tokyo Night Moon tokens and Prism edge; do not hardcode component colors.
- Use event-driven transitions only; no continuously repainting visual animations.
- Keep the current bar edge-to-edge and transparent.
- Preserve all existing overlay shortcuts and GNOME-derived workspace bindings.
- Add no package or background daemon.
- Persist only state transitions; do not write the remaining time every second.

---

### Task 1: Focus-session state machine

**Files:**
- Create: `config/dot/quickshell/services/FocusSession.qml`
- Modify: `config/dot/quickshell/config/Settings.qml`
- Test: temporary standalone Quickshell harness under `/tmp`

**Interfaces:**
- Consumes: `Notifs.doNotDisturb`, `Caffeine.enabled`, `Hyprland.focusedWorkspace`, `Hyprland.dispatch()`
- Produces: `active`, `paused`, `capsuleVisible`, `workspaceId`, `workspaceLabel`, `remainingSeconds`, `remainingText`, `start(minutes)`, `startDefault()`, `pauseOrResume()`, `dismiss()`, `reveal()`, `activateWorkspace()`, `end(completed)`

- [x] Add `focusDurationMinutes: 45` to `Settings.qml`.
- [x] Create a singleton with a wall-clock deadline and paused remaining duration.
- [x] Persist state atomically to `Quickshell.stateDir + "/focus-session.json"` with `FileView` and `JsonAdapter`.
- [x] Record and restore the pre-session DND and Caffeine values.
- [x] Resolve expiry on every one-second timer tick and immediately after state restoration.
- [x] Run executable contracts for active-to-ended state, pause stability, persisted restart restoration, and completion from an expired persisted deadline.

### Task 2: Signal Glass capsule and compact indicator

**Files:**
- Create: `config/dot/quickshell/modules/focus/FocusCapsule.qml`
- Create: `config/dot/quickshell/modules/focus/FocusIndicator.qml`
- Create: `config/dot/quickshell/modules/focus/FocusAction.qml`
- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
- Modify: `config/dot/quickshell/shell.qml`
- Modify: `config/dot/hypr/rules.lua`

**Interfaces:**
- Consumes: Task 1's `FocusSession` public properties and functions
- Produces: a `qs-focus-capsule` layer surface and a clickable bar indicator

- [x] Build the compact indicator as a transparent-bar-native pill showing a focus glyph and tabular remaining time.
- [x] Build the capsule with a Prism glass surface, primary workspace target, explicit close control, and Pause/Resume, Workspace, and End actions.
- [x] Make the primary row activate the stored workspace and dismiss only the capsule.
- [x] Instantiate one capsule and add one indicator to the right-side bar row.
- [x] Add a focused Hyprland layer rule enabling blur, suppressing compositor animation, and excluding the capsule from screen sharing.
- [x] Reload Quickshell and verify dismiss/reopen and workspace activation through live state.

### Task 3: Discoverable start paths and IPC

**Files:**
- Modify: `config/dot/quickshell/modules/quicksettings/QuickSettingsPanel.qml`
- Modify: `config/dot/quickshell/shell.qml`
- Modify: `config/dot/hypr/keybinds.lua`
- Modify: `config/dot/hypr/README.md`

**Interfaces:**
- Consumes: Task 1's service and Task 2's capsule visibility
- Produces: Quick Settings Focus row, `focus` IPC target, `SUPER+SHIFT+F` binding

- [x] Add a full-width Quick Settings row that starts the default session while idle and shows the capsule while active.
- [x] Register typed IPC functions `start()`, `reveal()`, `pause()`, `workspace()`, `overview()`, and `end()`.
- [x] Bind `SUPER+SHIFT+F` to `qs ipc call focus reveal`, where `reveal()` starts a default session if none exists.
- [x] Verify every function using `qs ipc call focus ...` and verify the Hyprland config.

### Task 4: Continuum workspace filmstrip

**Files:**
- Modify: `config/dot/quickshell/services/ShellState.qml`
- Modify: `config/dot/quickshell/modules/overview/Overview.qml`
- Modify: `config/dot/quickshell/modules/overview/OverviewBody.qml`
- Modify: `config/dot/quickshell/modules/overview/WorkspaceCard.qml`

**Interfaces:**
- Consumes: `FocusSession.workspaceId`, `ShellState.overviewWorkspaceId`, Hyprland workspace and toplevel models
- Produces: `ShellState.openOverview(workspaceId)`, filmstrip selection, large workspace preview, cross-workspace window search

- [x] Add requested-overview-workspace state without coupling `ShellState` to the focus service.
- [x] Replace the centred equal-card row with a top filmstrip and a large selected-workspace preview.
- [x] Keep the trailing dynamic-workspace card and one-shot thumbnail capture behavior.
- [x] Add wheel navigation over the strip and keep the overview mapped while switching workspaces.
- [x] Add a keyboard-focused search field and filtered cross-workspace window results.
- [x] Mark the focus-session workspace subtly in both filmstrip and preview.
- [x] Verify workspace selection, window activation, scrolling, new workspace creation, search, Escape, and background dismissal.

### Task 5: Integration and visual verification

**Files:**
- Modify: `config/dot/hypr/DESKTOP-PARITY.md`
- Modify: `README.md`

**Interfaces:**
- Consumes: all previous tasks
- Produces: documented, live daily-driver feature

- [x] Run `Hyprland --verify-config` and reload the Lua configuration.
- [x] Reload the live Quickshell instance and inspect `qs log` for QML errors and warnings.
- [x] Exercise a short live focus session through start, pause, resume, dismiss, reopen, workspace overview, and end.
- [x] Capture screenshots of capsule open, indicator-only, Continuum default, and Continuum search states.
- [x] Update Panama's feature documentation and keybinding table with the verified behavior.
- [x] Inspect the exact Panama diff and ensure unrelated pre-existing changes remain untouched.
