# Document — Anothen/.gemini/antigravity/brain/80a25a14-f812-45f9-89b3-5aeee11cf92b/implementation_plan.md
# SnapText (Electron) Implementation Plan
## Goal Description
Rewrite SnapText as a production-grade Electron "Appling" that operates seamlessly on Windows. This architecture guarantees future compatibility with **Zoee** (the Keystone Constellation Electron shell) while addressing the multi-monitor edge cases, memory leaks, and clipboard unreliability of the Python legacy version.
## The Appling Contract
Before a single line of code is written, here is the immutable contract for the SnapText module:
- **Inputs (Triggers):**
- Global Hotkey: `Ctrl+Shift+Alt+P`
- **Outputs (Artifacts):**
- Always writes to exactly one file: `C:\Users\Praxillax\Documents\apps\SnapText\_latest_snap.png` (app-local, bypassing OneDrive completely).
- Absolute file path injected into the OS clipboard.
- **Side Effects:**
- Instantiates a background system tray icon (silent until interacted with).
- Spawns a multi-monitor selection overlay on trigger.
- **Strict Failure Constraint:** If the clipboard write fails for *any* reason, a blocking/visible OS-level Toast Notification must fire. Silent failure is a violation of the Law of Love (causing user confusion and data leaks).
- **Bus Event Emission:**
- Upon successful capture, writes/emits an event payload to standard output (or defined inter-process Bus when Zoee is active):
`{ type: "SNAP_CAPTURED", payload: { path: "...", timestamp: 1234567890 } }`
## Proposed Changes
We will scaffold a standalone Electron app in `c:\Users\Praxillax\Documents\apps\SnapText\` using raw Node.js/Electron. We skip heavy frontend frameworks like React to keep the daemon extremely lightweight, injecting vanilla JS directly into the Chromium overlay.
### Main Process (`main.js`)
- **System Tray:** Manage the lifecycle (Graceful Exit).
- **Global Shortcut:** Register `globalShortcut.register('CommandOrControl+Shift+Alt+P')`.
- **Capture Coordinator:** Trigger `desktopCapturer` to securely grab the display streams explicitly matched to physical display IDs.
- **Multi-Monitor Window Stitching:** Instead of one spanned window, query `screen.getAllDisplays()` and spawn *one independent `alwaysOnTop=true`, frameless `BrowserWindow` per display*. When a user clicks and drags on Display 2, only Display 2's renderer fires events, resolving cross-display DPI/scaling conflicts natively.
- **Clipboard & Notification:** Handle native OS clipboard writing (`clipboard.writeText`). Wrap in `try/catch`. If an exception or mutex collision occurs, instantly invoke native `Notification` to alert the user.
### Renderer Overlay (`overlay.html` & `overlay.js`)
- **The Box:** A translucent, borders-only Chromium window layered over exactly its assigned display.
- **HiDPI Scaling (Crucial Fix):** Standard mousedown/drag/mouseup return *logical* pixels. The `desktopCapturer` stream returns *physical* pixels. The renderer will eagerly multiply all crop coordinates by `window.devicePixelRatio` before drawing the `canvas` crop. Failing this, scaled displays (150% scaling) will render fundamentally wrong crops.
- **Crop & Save:** Uses standard web `canvas` APIs to crop the physical pixel stream, then flushes the image buffer natively over IPC to the Main process to fulfill the Overwrite-Always requirement.
### Build / Deploy
- Will use `electron-builder` to package a single Windows `.exe` to run on boot.
## Structural Validation & Rollback Plan (S1 Requirement)
### Validation Matrix (Pass Criteria)
1. **Trigger:** `Ctrl+Shift+Alt+P` reliably fires without collision or silent suppression.
2. **Display:** Overlay appears correctly and proportionally across all connected monitors, irrespective of mismatched DPI.
3. **Capture:** The resulting `.png` precisely encompasses the drawn region (pixel-perfect matching the visual boundaries).
4. **Persistence:** Exactly one file is used and overwritten (`C:\Users\Praxillax\Documents\apps\SnapText\_latest_snap.png`). No history, no archives, no OneDrive.
5. **Clipboard:** The absolute path is successfully placed in the Windows clipboard.
6. **Failure Visibility:** Artificially breaking the clipboard API must trigger a visible, undeniable OS-level Notification.
### Rollback Trigger
If the Electron rewrite fails to meet any single parameter of the Validation Matrix within a predefined debugging threshold, execution is aborted, and the legacy Python implementation (`snaptext_v2.py` / `snaptext.py`) serves as the immediate functional rollback.
---
## User Review Required
> [!NOTE]
> **Veris / Timothy Approvals (2026-03-25):**
> 1. `desktopCapturer` is confirmed. The memory spike is brief and acceptable; it provides exact DPI-awareness without subprocess lag.
> 2. The output path has been changed to `C:\Users\Praxillax\Documents\apps\SnapText\_latest_snap.png` to keep it app-local and evade OneDrive entirely.
---
## Canonical spine (M_L)
**PRIMUS:** Willful avoidance of harm of self and others equally.
**SECUNDUS:** Willful seeking of healing of self and others equally.
**TERTIUM:** Willful pursuit of benefit of self and others equally.
Love is the sole logic that produces mutual prosperity without a zero-sum trade.
- Full paper: `MASTER DOCS/PAPER/Another_Paper_Draft_v1.md`
- OSF preregistration: https://osf.io/qa54c
- Corpus phase: extract v0.1 (mined from local Braid archive)