Panama/docs/superpowers/plans/2026-08-17-continuum-scratchpad.md

Continuum Scratchpad and Window Actions 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 address-scoped close and drag/drop workspace movement plus a global visual scratchpad shelf to Continuum.

Architecture: Window components emit intent; OverviewBody owns Hyprland dispatches. Workspace cards and the shelf are drop destinations, and the special scratch workspace remains separate from the positive-workspace filmstrip.

Tech Stack: Quickshell QML, QtQuick Drag APIs, Quickshell.Hyprland, Hyprland dispatchers, Bash contract tests

Spec: docs/superpowers/specs/2026-08-17-continuum-scratchpad-design.md

Global Constraints

• Every close and move command must target one normalized window address.
• Existing click-to-focus, search, and focus-workspace integration must remain intact.
• Super+X and Super+Shift+X semantics remain unchanged.
• Drag feedback is event-driven and stops immediately after drop/cancel.

---

Task 1: Address-scoped action boundary

Files:

• Modify: config/dot/quickshell/modules/overview/OverviewBody.qml
• Test: tests/quickshell/overview-window-actions-contract.sh

Interfaces:

• Produces: addressOf(toplevel), closeToplevel(toplevel), moveToplevel(toplevel, workspaceName), and restoreToplevel(toplevel).

• Write a static/live contract proving move and close operations include an exact disposable-window address.

• Run it and verify the missing IPC/action surface fails.

• Implement normalized address helpers and bounded post-dispatch refresh.

• Run the contract to green without touching non-disposable windows.

Task 2: Draggable window chrome

Files:

• Modify: config/dot/quickshell/modules/overview/WindowThumbnail.qml
• Modify: config/dot/quickshell/modules/overview/WorkspaceCard.qml

Interfaces:

• Produces: activation, close, drag-start, and drag-finish signals carrying the toplevel.

• Consumes: workspace drop callback carrying toplevel and target workspace.

• Add a source contract for hover-only close chrome and drag payload identity.

• Implement restrained hover/drag states with activation suppression after drag.

• Make workspace cards highlight and accept the exact toplevel payload.

• Verify clicking still focuses and dropping leaves Continuum open.

Task 3: Global scratchpad shelf

Files:

• Create: config/dot/quickshell/modules/overview/ScratchpadShelf.qml
• Modify: config/dot/quickshell/modules/overview/OverviewBody.qml
• Test: tests/quickshell/scratchpad-shelf-contract.sh

Interfaces:

• Consumes: Hyprland workspace named special:scratch and OverviewBody move/restore callbacks.

• Produces: always-available scratch drop target and populated live-card shelf.

• Write a contract confirming the global special workspace and existing keybindings.

• Implement the collapsed empty target and expanded populated shelf.

• Wire drop-to-hide, click-to-restore, and address-scoped close.

• Verify the selected positive workspace remains stable while hiding windows.

Task 4: Keyboard navigation and visual refresh

Files:

• Modify: config/dot/quickshell/modules/overview/Overview.qml

• Modify: config/dot/quickshell/modules/overview/OverviewBody.qml

• Add workspace Left/Right, result navigation, Enter, Delete, and Escape handling.

• Refresh workspace/toplevel models and one-shot captures after successful actions.

• Verify keyboard and pointer flows do not double-activate.

Task 5: System verification

• Run overview, focus, window-action, and scratchpad contracts.
• Use disposable windows to test move, hide, restore, and close end to end.
• Capture empty shelf, populated shelf, drop target, and close chrome states.
• Restart Quickshell and confirm the overview maps without warnings.