# 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.