Gabriel Brown
e1faaf7a76
Phase 6, the last of the fresh-install spec. 159 scripts lose their .sh: 110 contracts, 47 Vicinae commands, 2 compositor contracts. A shebang and the executable bit already select the interpreter. The extension only ever added something that had to stay in sync, and the rename proved the point twice over in the space of an hour. The spec's stated risk was Vicinae's script discovery. One script was renamed and reloaded on its own before the other 46 followed; it came back as scripts:panama.capture and all 47 resolve. What the probe turned up instead is that the extension was never only a filename: Vicinae's command IDs embed it, so every ID changed. Nothing in this repository refers to them, so nothing breaks. The only trace is Vicinae's metadata.json, whose visited map had two Panama entries that are now orphaned -- two commands lost their usage ranking and will earn it back. Worth knowing before anyone renames these again on a machine that has a keybind pointing at one. Rewriting the references by exact filename missed two things it structurally could not see: a name built from a variable, settings-$page.sh, and a glob, -name '*.sh'. Both were in the contract that counts the generated commands, which promptly reported 47 expected and 0 found. The mechanical part of a rename is the part that looks finished. The three subcommands. panama doctor fronts a health check that already existed and already ran at the end of every install but could not be reached from a terminal. panama upgrade re-runs the installer from anywhere. panama test runs the suite, which had no entry point at all -- 121 files that were the main safety net in this repository and were invisible in it. Writing that runner found three tests nothing was running. calendar_agenda_bridge_test, home_assistant_bridge_test and kdeconnect_bridge_test are unittest suites without the executable bit, so no contract invoked them and the first draft of the runner skipped them silently. All three pass, and have passed unobserved for weeks. The runner collects *_test.py as well now, because a runner with a blind spot is worse than no runner for the same reason a dependency checker with one is: it reports PASS. Six worktrees pruned. Each was re-checked rather than trusted to the spec's list, and two needed it: panama-commands is not on feat/panama-commands but on feat/gnome-tweaks-parity, and fix/panama-displays-review reads [ahead 3] -- ahead of its remote, not of main, with every commit patch-equivalent to landed work. roadmap-completion stays; it has five commits that are genuinely unlanded. The branches are left alone: pruning a worktree costs nothing, deleting a branch is a decision. 121 contracts pass. Claude-Session: https://claude.ai/code/session_01NvgBuSWB5sE43yWmg21ozj
106 lines
5.3 KiB
Markdown
106 lines
5.3 KiB
Markdown
# Screen Intelligence 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 polished local OCR and code recognition to Panama's existing capture experience.
|
|
|
|
**Architecture:** Capture keeps ownership of geometry and delegates Read captures to a focused `ScreenIntelligence` singleton. A deterministic helper emits JSON from local Tesseract and ZBar, while a transient Quickshell result surface owns presentation and explicit follow-up actions.
|
|
|
|
**Tech Stack:** Quickshell 0.3.0, Qt 6 QML, Hyprland 0.56 Lua configuration, Bash, Tesseract 5, ZBar, grim, wl-clipboard
|
|
|
|
**Spec:** `docs/superpowers/specs/2026-08-17-screen-intelligence-design.md`
|
|
|
|
## Global Constraints
|
|
|
|
- Recognition is local until Search, Translate, or Open is explicitly selected.
|
|
- Reuse the existing Screen, Window, and Selection picker.
|
|
- Use Tokyo Night Moon and Prism tokens; no component-local colors.
|
|
- Do not add idle animation or polling.
|
|
- Temporary screen captures must be removed when dismissed or replaced.
|
|
- Missing recognition packages must degrade into clear guidance, not shell errors.
|
|
|
|
---
|
|
|
|
### Task 1: Recognition boundary
|
|
|
|
**Files:**
|
|
- Create: `config/dot/quickshell/scripts/screen-intelligence`
|
|
- Create: `tests/quickshell/screen-intelligence-helper-contract`
|
|
- Modify: `setup/packages/hyprland-packages`
|
|
|
|
**Interfaces:**
|
|
- Produces: `screen-intelligence probe` and `screen-intelligence analyze-file IMAGE`, each emitting one JSON object.
|
|
- Consumes: `tesseract`, `zbarimg`, and `jq`.
|
|
|
|
- [x] Write a contract that generates a high-contrast `PANAMA SCREEN INTELLIGENCE` fixture and expects that literal text from `analyze-file`.
|
|
- [x] Run it and verify it fails because the helper does not exist.
|
|
- [x] Implement strict argument validation, readiness probing, OCR, code recognition, JSON encoding, and user-safe errors.
|
|
- [x] Add `tesseract`, `tesseract-langpack-eng`, and `zbar` to the Hyprland package set.
|
|
- [x] Run the helper contract to green with the real engine.
|
|
|
|
### Task 2: Recognition state and actions
|
|
|
|
**Files:**
|
|
- Create: `config/dot/quickshell/services/ScreenIntelligence.qml`
|
|
- Test: `tests/quickshell/screen-intelligence-contract`
|
|
|
|
**Interfaces:**
|
|
- Produces: readiness properties, `phase`, `text`, detected-code data, `analyzeRegion`, `analyzeFile`, copy/search/translate/open actions, and `close`.
|
|
- Consumes: the Task 1 helper, `grim`, `wl-copy`, `xdg-open`, and `Quickshell.cachePath`.
|
|
|
|
- [x] Write a live IPC contract that expects the target, readiness JSON, fixture analysis, and cleanup.
|
|
- [x] Run it and verify the IPC target is missing.
|
|
- [x] Implement bounded process state, JSON parsing, explicit network actions, and temporary-file cleanup.
|
|
- [x] Wire a typed diagnostics and command IPC target in `shell.qml`.
|
|
- [x] Run the live contract to green.
|
|
|
|
### Task 3: Capture integration and result sheet
|
|
|
|
**Files:**
|
|
- Modify: `config/dot/quickshell/services/Capture.qml`
|
|
- Modify: `config/dot/quickshell/modules/capture/CaptureBar.qml`
|
|
- Create: `config/dot/quickshell/modules/capture/IntelligenceResult.qml`
|
|
- Modify: `config/dot/quickshell/shell.qml`
|
|
|
|
**Interfaces:**
|
|
- Produces: Screenshot, Record, and Read action selection plus the transient result overlay.
|
|
- Consumes: Task 2's `analyzeRegion` and state/action API.
|
|
|
|
- [x] Extend the live contract to open Selection + Read mode and inspect the exposed mode state.
|
|
- [x] Run it and verify the Read state is absent.
|
|
- [x] Add mutually exclusive action selection and defer recognition until the picker unmaps.
|
|
- [x] Build processing, success, empty, code, and unavailable result states with keyboard dismissal.
|
|
- [x] Restart Quickshell and inspect fresh logs for construction errors or warnings.
|
|
|
|
### Task 4: Settings, shortcut, launcher, and documentation
|
|
|
|
**Files:**
|
|
- Create: `config/dot/quickshell/modules/settings/ScreenIntelligencePage.qml`
|
|
- Modify: `config/dot/quickshell/modules/settings/SettingsSidebar.qml`
|
|
- Modify: `config/dot/quickshell/modules/settings/SettingsShell.qml`
|
|
- Modify: `config/dot/quickshell/modules/settings/qmldir`
|
|
- Modify: `config/dot/quickshell/services/ShellState.qml`
|
|
- Modify: `config/dot/hypr/keybinds.lua`
|
|
- Modify: `config/dot/hypr/rules.lua`
|
|
- Create: `config/local/share/applications/panama-screen-intelligence.desktop`
|
|
- Modify: `config/dot/hypr/README.md`
|
|
- Modify: `README.md`
|
|
- Modify: `tests/quickshell/settings-pages-contract`
|
|
|
|
**Interfaces:**
|
|
- Produces: Settings destination `screen-intelligence`, `Super+Shift+S`, and a searchable desktop entry.
|
|
|
|
- [x] Extend Settings and keybinding contracts with the new page and shortcut.
|
|
- [x] Run them and verify the route and bind fail.
|
|
- [x] Build the readiness/privacy page and add it to Settings navigation.
|
|
- [x] Add the keybinding, overlay privacy rule, desktop entry, and documentation.
|
|
- [x] Link and validate the desktop entry, reload Hyprland, and run contracts to green.
|
|
|
|
### Task 5: Full-system verification
|
|
|
|
- [x] Run the helper and live Screen Intelligence contracts.
|
|
- [x] Run every Quickshell contract and `Hyprland --verify-config`.
|
|
- [x] Restart the live shell and inspect fresh logs.
|
|
- [ ] Exercise a real screen-region OCR capture and confirm Copy reaches clipboard history.
|
|
- [ ] Review the complete diff, commit the Panama snapshot, and push `main` to `origin`.
|