116 lines
6.6 KiB
Markdown
116 lines
6.6 KiB
Markdown
# 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.
|