# Document — Anothen/.claude/paste-cache/cd046ab1cd6978cd.txt
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)
Trigger: Ctrl+Shift+Alt+P reliably fires without collision or silent suppression.
Display: Overlay appears correctly and proportionally across all connected monitors, irrespective of mismatched DPI.
Capture: The resulting .png precisely encompasses the drawn region (pixel-perfect matching the visual boundaries).
Persistence: Exactly one file is used and overwritten (C:\Users\Praxillax\Documents\apps\SnapText\_latest_snap.png). No history, no archives, no OneDrive.
Clipboard: The absolute path is successfully placed in the Windows clipboard.
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):
desktopCapturer is confirmed. The memory spike is brief and acceptable; it provides exact DPI-awareness without subprocess lag.
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)