Panama/docs/superpowers/plans/2026-08-17-contextual-signal-glass.md

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

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

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.