Build the Panama Hyprland desktop

2026-08-17 10:32:55 -04:00
parent 67033f2a31
commit 5248883e4b
190 changed files with 18554 additions and 34 deletions
@@ -0,0 +1,70 @@
+# Screen Intelligence Design
+
+## Purpose
+
+Screen Intelligence makes text trapped in pixels feel like normal desktop content. It extends Panama's existing screenshot picker with a local **Read** action for a screen, window, or selection, then presents the result in a focused Prism glass sheet.
+
+The feature is deliberately local-first. Screen pixels are captured into Panama's cache and processed by Tesseract and ZBar on the workstation. Nothing is uploaded unless the user explicitly chooses Search, Translate, or Open.
+
+## Interaction model
+
+- `Super+Shift+S` opens the existing capture picker in Selection + Read mode.
+- `Print` keeps opening the complete picker, where Screenshot, Record, and Read are peers.
+- Screen, Window, and Selection continue to use one shared target-selection model.
+- Committing a Read capture dismisses the picker before taking the final image, then opens a result sheet while recognition runs.
+- `Escape` dismisses the result and deletes its temporary image.
+- The result provides selectable text and explicit Copy, Search, and Translate actions.
+- A detected URL, QR code, or barcode is shown separately. Web URLs can be opened; all detected values can be copied.
+- A searchable desktop entry opens Read mode without requiring the shortcut.
+
+## Architecture
+
+`services/Capture.qml` remains the owner of screen/window/selection geometry and frozen-frame behavior. It gains a third action state, `intelligenceMode`, and delegates committed Read geometry to `services/ScreenIntelligence.qml` only after the capture overlay has unmapped.
+
+`services/ScreenIntelligence.qml` owns recognition state, process lifecycle, result actions, and cleanup. Its public boundary is:
+
+- `refresh(): void`
+- `analyzeRegion(geometry: string, outputName: string): void`
+- `analyzeFile(path: string): void`
+- `copyText(): void`
+- `copyCode(): void`
+- `search(): void`
+- `translate(): void`
+- `openDetected(): void`
+- `close(): void`
+
+`scripts/screen-intelligence` is the deterministic machine boundary. `probe` reports engine availability. `analyze-file IMAGE` emits one JSON object containing OCR text, detected code data, and a user-safe error. It never evaluates UI-provided shell text.
+
+`modules/capture/IntelligenceResult.qml` is a transient overlay, not an application window. It renders a quiet processing state, the selectable result, detected-content card, actions, and actionable failure guidance.
+
+## Recognition behavior
+
+- OCR uses the installed English Tesseract language pack.
+- Tesseract's automatic page-segmentation mode handles both short snippets and larger document regions.
+- ZBar recognition is additive. A capture can return text, a code, or both.
+- Empty recognition is not treated as a crash; the sheet explains that no readable text or code was found.
+- Missing engines produce a precise install command and keep the rest of the shell healthy.
+- Temporary captures live under `Quickshell.cachePath(...)` and are removed when dismissed or replaced.
+
+## Visual language
+
+- The result is a centered Prism glass sheet over a lightly dimmed desktop.
+- Tokyo Night Moon tokens are the only colors.
+- Processing uses a static status treatment; there is no spinner, pulse, shimmer, or idle animation.
+- OCR text is readable interface typography in a selectable editor, not a terminal-like dump.
+- The primary action is Copy. Network-leaving actions are visually secondary and clearly labelled.
+
+## Settings and discoverability
+
+Panama Settings gains a real **Screen Intelligence** page. It shows engine readiness, the `Super+Shift+S` shortcut, the local-processing privacy boundary, and the exact package requirement if recognition is unavailable. The page contains no fake toggles.
+
+The shortcut reference, Hyprland README, root README, desktop package list, and desktop entry remain in sync.
+
+## Verification
+
+- A generated image fixture must be recognized as literal text by the helper.
+- The live IPC contract must expose readiness, open Read mode, and route the Settings page.
+- The capture picker must construct with Screenshot, Record, and Read actions without QML warnings.
+- The result sheet must construct for processing, success, empty, and unavailable states.
+- Hyprland must register `Super+Shift+S` as Screen Intelligence and pass config verification.
+- The complete Quickshell contract suite must remain green.