# Contextual Signal Glass 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:** Build a curated event broker, quiet shared Signal Glass host, and persistent privacy/activity indicators.

**Architecture:** Producers publish structured events to one bounded broker. A single per-screen host renders transient events ahead of existing focus controls, while persistent privacy state renders independently in the bar.

**Tech Stack:** Quickshell QML, QtQuick, Quickshell PipeWire/Bluetooth/Io APIs, Hyprland, Bash contract tests

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

## Global Constraints

- Initial discovery must not emit user-visible events.
- DND suppresses ambient events but never persistent privacy state.
- No idle visual animation or unbounded queue/process loop.
- Existing Focus behavior and tests must remain compatible.

---

### Task 1: Status event broker

**Files:**
- Create: `config/dot/quickshell/services/StatusEvents.qml`
- Modify: `config/dot/quickshell/shell.qml`
- Test: `tests/quickshell/status-events-contract`

**Interfaces:**
- Produces: `publish(event: var)`, `dismiss(): void`, `invoke(): void`, `activeEvent`, `active`, and IPC diagnostics.

- [ ] Write an IPC contract that publishes ambient and critical fixtures, verifies replacement and DND filtering, and dismisses cleanly.
- [ ] Run the contract and verify it fails because the IPC target is absent.
- [ ] Implement broker normalization, priority, four-entry queue, stable-key replacement, expiry, and action routing.
- [ ] Wire a diagnostics-only IPC target and run the contract to green.

### Task 2: Shared Signal Glass host

**Files:**
- Create: `config/dot/quickshell/modules/signals/SignalGlass.qml`
- Create: `config/dot/quickshell/modules/signals/EventCard.qml`
- Create: `config/dot/quickshell/modules/signals/FocusCard.qml`
- Create: `config/dot/quickshell/modules/signals/qmldir`
- Modify: `config/dot/quickshell/shell.qml`
- Retire: `config/dot/quickshell/modules/focus/FocusCapsule.qml`

**Interfaces:**
- Consumes: `StatusEvents.activeEvent`, `FocusSession.active`, and `FocusSession.capsuleVisible`.
- Produces: one `qs-signal-glass` layer surface per monitor.

- [ ] Add a static source contract proving only one Signal Glass host is instantiated.
- [ ] Extract the existing focus presentation without changing its actions.
- [ ] Implement the compact event presentation and event-first/focus-second arbitration.
- [ ] Verify focus contracts and QML construction.

### Task 3: Event producers and persistent activity

**Files:**
- Create: `config/dot/quickshell/services/PrivacyState.qml`
- Create: `config/dot/quickshell/services/DeviceEvents.qml`
- Modify: `config/dot/quickshell/services/Capture.qml`
- Modify: `config/dot/quickshell/services/NightLight.qml`
- Modify: `config/dot/quickshell/services/FocusSession.qml`
- Test: `tests/quickshell/activity-state-contract`

**Interfaces:**
- Produces: `PrivacyState.microphoneActive`, `cameraActive`, `screenSharingActive`, `recordingActive`, `activeKinds`, and transition events.

- [ ] Write contracts for capture events and independent persistent-state reporting.
- [ ] Instrument Panama-owned capture, Night Light, and focus completion transitions.
- [ ] Add initialized transition monitoring for output, Bluetooth, KDE Connect, and privacy activity.
- [ ] Run the contracts and verify missing optional integrations fail quietly.

### Task 4: Bar indicator and detail panel

**Files:**
- Create: `config/dot/quickshell/modules/bar/ActivityIndicator.qml`
- Create: `config/dot/quickshell/modules/bar/ActivityPanel.qml`
- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
- Modify: `config/dot/quickshell/services/ShellState.qml`

**Interfaces:**
- Consumes: `PrivacyState` booleans and `Capture.stopRecording()`.

- [ ] Add the indicator beside Focus with semantic icon/color selection.
- [ ] Add a compact details popover and safe Stop action for Panama recording.
- [ ] Verify overlay exclusivity, click targets, and all active-state combinations.

### Task 5: System verification

- [ ] Run all Quickshell contract tests.
- [ ] Run QML/runtime diagnostics and inspect logs for warnings.
- [ ] Capture ambient, privacy, recording, and focus-restoration states.
- [ ] Restart the live Quickshell instance and repeat the smoke contract.