Edge-Drop is a clipboard shelf on the edge of your screen. Hover to open it. Drag files and images into any app, click to copy text and links. Free and open-source for Windows.
Edge-Drop — Technical Features & Architecture Specification
This document provides an exhaustive, engineering-grade breakdown of the architecture, subsystems, data flows, and technical mechanisms that power Edge-Drop — a minimalist, always-accessible, hover-activated desktop clipboard shelf built with Electron, React, TypeScript, and Framer Motion.
1. Executive Summary & System Philosophy
Edge-Drop is designed around a single guiding user-experience principle: zero-friction, non-intrusive accessibility. Traditional clipboard managers require manual keyboard shortcuts (like Win+V) or system-tray clicking, breaking flow and visual concentration. Edge-Drop eliminates this friction by residing completely hidden as a 0-pixel interactive trigger zone along the leftmost screen edge. When approached by the cursor, it dynamically reveals itself through fluid spring physics, allowing instant drag-and-drop operations across desktop applications.
Architectural Highlights
- Zero-Latency State Rendering: Direct store reads (
useStore.getState()) combined with boolean Zustand selectors ensure that dragging and dropping items never triggers cascading React re-renders across long lists. - Hardened Sandbox Security: Operates with
contextIsolation: true,nodeIntegration: false, and a strongly typed, bidirectional TypeScript IPC bridge (contextBridge.exposeInMainWorld). - OS-Level OLE Native Dragging: Bypasses browser-only HTML5 drag limitations by generating temporary OS file handles and invoking Electron's native
startDragpipeline, allowing seamless drops into desktop software such as Adobe Photoshop, Microsoft Word, and Windows Explorer.
2. Core System Architecture & IPC Bridge
Edge-Drop enforces a strict decoupling between the system-level OS integrations (Main Process) and the presentation/animation layer (Renderer Process).
graph TD
subgraph OS ["Operating System and Hardware"]
WinClip["Win32 System Clipboard"]
WinFS["Local Filesystem and AppData"]
OLE["OS OLE Drag and Drop Pipeline"]
end
subgraph Main ["Electron Main Process (Node.js)"]
ClipWatch["ClipboardWatcher Service"]
Store["ItemStore and Settings Persistence"]
Tray["System Tray and Native Menu"]
WinMgr["BrowserWindow and Cursor Edge Poller"]
end
subgraph Bridge ["Typed Preload Bridge (ContextIsolation)"]
API["contextBridge: window.edge"]
end
subgraph Renderer ["React Renderer Process (UI and Motion)"]
Zustand["Zustand Store (appStore)"]
Hooks["useEdgeHover and useDragOut"]
UI["Panel, ItemList and Fluid Bundles"]
end
WinClip <-->|"Polls every 600ms"| ClipWatch
ClipWatch -->|"state:items IPC"| API
Store <-->|"JSON Atomic Read or Write"| WinFS
WinMgr <-->|"window:cursor-edge or window:set-interactive"| API
UI -->|"item:start-drag IPC"| API
API -->|"OLE Native Handle"| OLE
API <-->|"Typed Handlers and Events"| Zustand
Zustand <--> UI
The Typed IPC Contract (ipc.ts)
To prevent drift between processes, all communication occurs over three statically typed maps:
InvokeMap(Request/Response): Asynchronous operations where the renderer expects a result from Node.js (e.g.,state:load,item:delete,item:merge,settings:update).EventMap(Main $\rightarrow$ Renderer): Real-time broadcast signals initiated by the background services (e.g.,state:items,window:cursor-edge,ui:toast).SendMap(Fire-and-Forget): Time-critical, synchronous gestures. The primary use case isitem:start-drag, where the renderer must immediately yield execution to allow Node.js to claim the OS drag event loop without waiting for a round-trip Promise resolution.
3. The Invisible Edge-Trigger Architecture
Achieving a "click-through when hidden, interactive when visible" frameless window on modern operating systems without flickering requires a multi-layered hysteresis algorithm.
stateDiagram-v2
[*] --> Closed: Startup at x=0, Width=280px, Click-Through
state Closed {
[*] --> PollingEdge
PollingEdge --> TriggerZone: Cursor x <= 3px in hot zone
TriggerZone --> DwellTimer: Linger >= 120ms
DwellTimer --> Open: Timer expires
}
state Open {
[*] --> Interactive: Set interactive true
Interactive --> HysteresisCheck: 16ms Main Process Poll
HysteresisCheck --> Interactive: Cursor x <= 255px inside Blade
HysteresisCheck --> GraceTimer: Cursor x > 290px OR Left y-bounds
GraceTimer --> Interactive: Cursor returns before 250ms
GraceTimer --> Closed: Timer expires and setOpen false
}
1. Main-Process 16ms Screen Polling
Standard DOM pointerleave events are notoriously unreliable when applied to transparent Electron windows with dynamic shape-masking (setIgnoreMouseEvents). Instead, Edge-Drop runs a native background polling timer in the Main process using screen.getCursorScreenPoint(). Every 16ms, it evaluates the exact physical cursor coordinates and broadcasts window:cursor-edge to the renderer.
2. Dual-Threshold Dead-Band Hysteresis (useEdgeHover.ts)
To prevent rapid visual oscillation (flickering open and closed) when a user's hand hovers precariously at the exact outer boundary of the clipboard shelf (~270px), Edge-Drop implements a dead-band hysteresis algorithm:
TRIGGER_PX(3px): The leftmost strip of screen pixels that initiates theDWELL_MS(120ms) opening timer.KEEP_OPEN_PX(255px): If the cursor x-coordinate is $\le 255\text{px}$, the panel is guaranteed to be inside the visual blade; any pending close timers are immediately canceled.START_CLOSE_PX(290px): Only when the cursor moves beyond $290\text{px}$ ($20\text{px}$ outside the visual boundary of the shelf) does the system schedule theGRACE_MS(250ms) close timer.- The Dead Band ($255\text{px} < x \le 290\text{px}$): Cursor movement within this 35-pixel buffer is ignored, allowing smooth natural hand micro-tremors without accidentally triggering state transitions.
3. Dynamic Shape Masking (setIgnoreMouseEvents)
When the shelf is closed, the window must not block clicks meant for underlying desktop applications (like web browsers or IDEs). Edge-Drop invokes window:set-interactive(false) over IPC, which calls win.setIgnoreMouseEvents(true, { forward: true }). When the dwell timer triggers an open event, it immediately switches to win.setIgnoreMouseEvents(false), capturing all mouse clicks, scrolls, and drag gestures.
4. Multi-Format Clipboard Capture Engine
The background service ClipboardWatcher.ts continuously monitors the system clipboard without relying on brittle OS polling hooks that degrade CPU performance.
sequenceDiagram
participant OS as System Clipboard
participant CW as ClipboardWatcher Main
participant IS as ItemStore Disk
participant Renderer as React UI
loop Every 600ms
CW->>OS: Read available format types
alt Text or URL Format
CW->>OS: clipboard.readText
CW->>CW: Compute MD5 Hash Signature
else Image Format
CW->>OS: clipboard.readImage
CW->>CW: Extract raw buffer and PNG dimensions
else File Paths Format
CW->>OS: Read HDROP Buffer Windows or macOS
end
CW->>IS: Check if signature exists in Top 100 history
alt Duplicate Found
IS->>IS: Bump hitCount and update capturedAt timestamp
IS-->>Renderer: Broadcast updated list state:items
else New Content
IS->>IS: Prepend to history and enforce historyLimit cap
IS-->>Renderer: Broadcast new item list state:items
end
end
Signature Generation & Deduplication
Every captured clipboard entry is processed to generate a deterministic content signature:
- Text/Links: SHA-256 or MD5 hash of the normalized UTF-8 string.
- Images: Hash of the raw bitmap buffer combined with pixel dimensions (
width × height × bytes). - Files: Sorted array concatenation of absolute file system paths.
If a signature matches an existing item already present in the history store, Edge-Drop deduplicates the entry by elevating it back to the top of the shelf, updating its capturedAt timestamp, and incrementing its badge multiplier (hitCount), keeping the workspace clean.
5. Fluid Collections & Stack Bundling
To prevent mass file copying or multi-image screenshots from cluttering the shelf with dozens of individual cards, Edge-Drop introduces Fluid Bundles.
1. Automatic Collection Grouping (image-collection & files)
When a user drags multiple items simultaneously into the panel (or copies a multi-file selection from Explorer), the ItemStore groups them into a single parent entity:
- Collapsed Visual State: Displays an angled 3D card stack (
bundle-stack-large) showing up to 4 overlapping thumbnails with progressive rotation and scaling offsets (zIndex: 10 - idx,rotate: idx * 6 - 6). - Expanded Visual State: Clicking the bundle body smoothly expands the card via Framer Motion's
popLayoutengine, revealing an interactive sub-item list.
2. Granular Sub-Item Manipulation
Once a bundle is expanded, users can interact with individual internal elements without breaking the parent collection:
- Sub-Item Dragging: Dragging a single row out of an expanded bundle initiates a focused drag request (
{ id, imageId }or{ id, paths: [singlePath] }), transferring only that specific file to the target OS application. - Sub-Item Splitting / Ungrouping: Clicking the minus icon (
item:split) detaches the sub-item from the collection and promotes it into an independent, top-level item card on the shelf. - Interactive Drag-Over Merging: Dragging an external item card directly over an existing card on the shelf fires
window.edge.mergeItems(sourceId, targetId), automatically combining separate items into a unified collection stack.
6. OS-Level Native Drag-in & OLE Drag-out
Edge-Drop seamlessly bridges the web technology stack of Electron's renderer with low-level OS file transfer protocols.
sequenceDiagram
participant User
participant Renderer as React Card
participant Main as Electron Main
participant OS as OS and External App
Note over User,OS: Drag Out Flow via OLE Native Drag
User->>Renderer: DragStart on item tile
Renderer->>Renderer: e.preventDefault to Stop HTML5 Ghost
Renderer->>Main: IPC send item:start-drag with request
Main->>Main: Resolve data and write PNG or TXT to temp dir
Main->>OS: webContents.startDrag with absPath and thumb icon
OS->>User: OS renders native drag icon and handles drop anywhere
Note over User,OS: Drag In Flow via File Drop
User->>Renderer: DragOver panel edge
Renderer->>Renderer: setDragActive true to prevent autohide
User->>Renderer: Drop files onto ItemList
Renderer->>Main: webUtils.getPathForFile
Main->>Main: Validate filesystem paths and bulk create bundle
Main-->>Renderer: Broadcast updated items
Why Bypassing HTML5 Drag is Required
In a standard web browser, dragging an image out of a window only passes a URL or a Base64 string. Desktop software (like Adobe Illustrator, Slack, or File Explorer) expects actual filesystem paths via OS drag-and-drop protocols (CF_HDROP on Windows, NSFilenamesPboardType on macOS).
When a drag begins on a ClipboardItemCard:
- The renderer calls
e.preventDefault()on the native HTML5 drag event to prevent the browser from rendering an empty drag image. - It synchronously dispatches
item:start-dragto Node.js. - If the item is an in-memory image or text snippet, the Main process writes it to a clean temporary file (
C:\Users\<user>\AppData\Roaming\edge-drop\temp\item-<id>.png). - Node.js invokes
event.sender.startDrag({ file: absPath, icon: nativeImageThumb }), handing full control over to the Windows OLE Drag loop.
7. UI/UX & Motion Design System
The visual language of Edge-Drop is inspired by modern dark-mode aesthetics—deep black backgrounds (#000000), frosted glass backdrops (backdrop-filter: blur(20px)), subtle 1px hairlines (rgba(255, 255, 255, 0.08)), and high-contrast typography.
1. Synchronized Elastic Overshoot Bounce (Panel.tsx)
When the panel opens, it does not simply slide into place; it exhibits physical elasticity. In Panel.tsx, the outer wrapper (.blade-container) is animated with keyframes:
{
"scale": [0.92, 1.05, 0.98, 1],
"transition": { "duration": 0.55, "ease": [0.22, 1, 0.36, 1] }
}
By anchoring the transform origin to the left screen edge (originX: 0, originY: 0.5), the entire shelf—including its content and curved connection flares—scales outward by +5% before snapping back into its exact resting dimensions.
2. Synchronized Screen-Edge Connection Flares
To make the shelf appear physically extruded from the user's monitor bezel, two custom SVG reverse curves (.flare-top and .flare-bottom) sit at the top and bottom intersection points. Because these flares are positioned inside the scaling .blade-container wrapper rather than the inner clipped panel, they animate and stretch in perfect unison with the bounce animation.
3. Scroll Gradient Masks
Both the main clipboard history list (ItemList) and the settings configuration view (Settings) feature top and bottom 18px absolute linear gradient overlays (linear-gradient(to bottom, #000000, transparent)). As items scroll under the fixed Header or Footer, they smoothly fade into the deep black background rather than clipping sharply against border edges.
8. High-Legibility Settings & Persistence
The settings panel replaces traditional, clumsy UI sliders with clean Minimalist Pill Selectors (.setting-pills) and sleek custom toggle switches.
| Setting Option | Internal Key | Default | Description |
|---|---|---|---|
| Clear unpinned on restart | clearUnpinnedOnRestart |
false |
Automatically purges all non-pinned history upon device reboot. |
| Auto-delete timer | autoDeleteHours |
0 (Never) |
Purges copied items older than 1h, 6h, 24h, or 7 days (preserves Pinned items). |
| History capacity | historyLimit |
500 |
Limits unpinned storage depth (options: 100, 250, 500, 1000 items). |
| Edge trigger height | hotZoneHeight |
0.4 (40%) |
Adjusts the vertical hover detection band along the screen edge (25%, 40%, 60%). |
| Panel height | panelHeight |
0.65 (65%) |
Adjusts the visual height of the clipboard blade relative to screen resolution. |
| Incognito mode | incognito |
false |
Temporarily suspends clipboard polling; no new items are captured while active. |
| Launch at login | launchAtLogin |
false |
Registers Edge-Drop silently in the Windows Registry (CurrentVersion\Run). |
Atomic JSON Persistence (settings.ts & ItemStore.ts)
All user data is stored inside Electron's app.getPath('userData') directory (C:\Users\<user>\AppData\Roaming\edge-drop). To prevent data corruption during sudden system crashes or power loss, disk write operations utilize safe atomic file writing techniques (writing to a temporary file before renaming it over the destination target).
9. Hardened Security & Sandbox Isolation
Edge-Drop is built to strict enterprise desktop security standards:
nodeIntegration: false: The React renderer has zero access to Node.js APIs, file systems, or OS execution modules.contextIsolation: true: Preload scripts run in a separate JavaScript execution context, protecting the Main process from prototype pollution or cross-site scripting (XSS) injection attempts.- Windows Startup Dev-Mode Safety: All calls to
app.setLoginItemSettings()are wrapped in explicitif (app.isPackaged)safety guards. This guarantees that running local development servers (npm run dev) will never inject bare development binaries (electron.exe) into the Windows Registry startup keys.
10. Summary of Features Matrix
| Category | Feature Name | Capability Breakdown |
|---|---|---|
| Activation | Zero-Click Edge Hover | Hovers into view from 0px edge width; click-through when hidden. |
| Activation | Hysteresis Hiding | Dual-threshold dead band (255px / 290px) prevents boundary oscillation. |
| Capture | Multi-Format Support | Captures plain text, rich URLs, bitmaps/PNGs, and multi-file paths. |
| Capture | Smart Deduplication | Elevates existing items and increments hitCount badge on re-copy. |
| UI/UX | Elastic Overshoot Bounce | Entire panel and connection arcs scale +5% with spring physics on reveal. |
| UI/UX | Monochrome Aesthetics | Frosted deep black macOS-style panels with subtle white/silver badges. |
| UI/UX | Fluid Bundles | Groups multi-file/image copies into expandable 3D card stacks. |
| Manipulation | Granular Sub-Item Actions | Drag out, copy, or split individual files directly from inside a bundle. |
| Manipulation | Interactive Merging | Drag and drop shelf items onto one another to combine them into stacks. |
| OS Transfer | OLE Native Drag-Out | Direct OS file handle generation for dragging into Word, Explorer, etc. |
| OS Transfer | Protected Drag-In | Shelf stays locked open when dragging OS files over the target drop zone. |
| Configuration | Pill Selector Settings | Instant, slider-free configuration for capacity, hot zones, and timers. |
| System | Dev-Safe Login Startup | Safe Windows startup registration protected against dev-mode binaries. |