gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0d894afe3e91c3077bb617edc67f8945b1c9dbc1
Panama/docs/superpowers/plans/2026-08-17-focus-glass-continuum.md
T
Gabriel Brown d96863b687 Convert British spellings to American across the repo 
colour -> color, behaviour -> behavior, centre -> center, favourite ->
favorite, and about twenty other pairs, applied consistently across
comments, docs, error/UI copy, and a handful of QML identifiers that
used the British spelling as their actual name: SystemSettings'
serialiseValue/serialiseTable/normaliseGradient, Displays'
normaliseModes, Wallpaper's normalisePolicy, SettingsBackup's
serialiseHomeState, DateTime's ntpSynchronised property, Clipboard's
_normalise helper, and ShortcutCapture's cancelled signal (with its
onCancelled handler in ShortcutsPage.qml). Every call site and the two
tests that assert on the literal source text (settings-ownership and
settings-backup-live contracts) were updated in lockstep.

Left untouched: config/dot/espanso/match/packages/misspell-en/ is a
vendored third-party autocorrect dictionary -- its entries are typo
corrections, not our prose, and rewriting them would fight the
package's own purpose (and any future re-sync from upstream).

The already-American `favorites` property (Home page pinned
accessories) was never actually misspelled -- only nearby comments and
error strings said "favourites" -- so no data migration was needed
there.

Claude-Session: https://claude.ai/code/session_01E6TJUAh41HaP25MVHWkhRZ
2026-08-19 08:07:55 -04:00

6.6 KiB
Raw Blame History

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)

  • Add focusDurationMinutes: 45 to Settings.qml.

  • Create a singleton with a wall-clock deadline and paused remaining duration.

  • Persist state atomically to Quickshell.stateDir + "/focus-session.json" with FileView and JsonAdapter.

  • Record and restore the pre-session DND and Caffeine values.

  • Resolve expiry on every one-second timer tick and immediately after state restoration.

  • 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

  • Build the compact indicator as a transparent-bar-native pill showing a focus glyph and tabular remaining time.

  • Build the capsule with a Prism glass surface, primary workspace target, explicit close control, and Pause/Resume, Workspace, and End actions.

  • Make the primary row activate the stored workspace and dismiss only the capsule.

  • Instantiate one capsule and add one indicator to the right-side bar row.

  • Add a focused Hyprland layer rule enabling blur, suppressing compositor animation, and excluding the capsule from screen sharing.

  • 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

  • Add a full-width Quick Settings row that starts the default session while idle and shows the capsule while active.

  • Register typed IPC functions start(), reveal(), pause(), workspace(), overview(), and end().

  • Bind SUPER+SHIFT+F to qs ipc call focus reveal, where reveal() starts a default session if none exists.

  • 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

  • Add requested-overview-workspace state without coupling ShellState to the focus service.

  • Replace the centered equal-card row with a top filmstrip and a large selected-workspace preview.

  • Keep the trailing dynamic-workspace card and one-shot thumbnail capture behavior.

  • Add wheel navigation over the strip and keep the overview mapped while switching workspaces.

  • Add a keyboard-focused search field and filtered cross-workspace window results.

  • Mark the focus-session workspace subtly in both filmstrip and preview.

  • 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

  • Run Hyprland --verify-config and reload the Lua configuration.

  • Reload the live Quickshell instance and inspect qs log for QML errors and warnings.

  • Exercise a short live focus session through start, pause, resume, dismiss, reopen, workspace overview, and end.

  • Capture screenshots of capsule open, indicator-only, Continuum default, and Continuum search states.

  • Update Panama's feature documentation and keybinding table with the verified behavior.

  • Inspect the exact Panama diff and ensure unrelated pre-existing changes remain untouched.

Reference in New Issue View Git Blame Copy Permalink