Skip to content

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.

Fix file copy list to support multiple items and promote copied items to top and fix drag preview going behind panel

Deepender259f1a6e0b5b20
diff --git a/FEATURES.md b/FEATURES.md
new file mode 100644
index 0000000..d9c539a
--- /dev/null
+++ b/FEATURES.md
@@ -0,0 +1,271 @@
+# 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 `startDrag` pipeline, 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).
+
+```mermaid
+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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/shared/ipc.ts))
+To prevent drift between processes, all communication occurs over three statically typed maps:
+1. **`InvokeMap`** (Request/Response): Asynchronous operations where the renderer expects a result from Node.js (e.g., `state:load`, `item:delete`, `item:merge`, `settings:update`).
+2. **`EventMap`** (Main $\rightarrow$ Renderer): Real-time broadcast signals initiated by the background services (e.g., `state:items`, `window:cursor-edge`, `ui:toast`).
+3. **`SendMap`** (Fire-and-Forget): Time-critical, synchronous gestures. The primary use case is `item: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.
+
+```mermaid
+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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/src/hooks/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 the `DWELL_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 the `GRACE_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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/clipboard/ClipboardWatcher.ts) continuously monitors the system clipboard without relying on brittle OS polling hooks that degrade CPU performance.
+
+```mermaid
+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 `popLayout` engine, 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.
+
+```mermaid
+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`:
+1. The renderer calls `e.preventDefault()` on the native HTML5 drag event to prevent the browser from rendering an empty drag image.
+2. It synchronously dispatches `item:start-drag` to Node.js.
+3. 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`).
+4. 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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/src/components/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:
+```json
+{
+ "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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/store/settings.ts) & [ItemStore.ts](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/store/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 explicit `if (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. |
diff --git a/README.md b/README.md
index 7fd4d86..ebab9f4 100644
--- a/README.md
+++ b/README.md
@@ -1,57 +1,287 @@
# Edge-Drop
-A clipboard manager that lives hidden on the **left edge** of your screen and expands on hover.
+An engineering-grade, zero-click, hover-activated desktop clipboard shelf and native OS file transfer hub built with **Electron**, **React**, **TypeScript**, and **Framer Motion**.
-## Features
+---
-- **Edge panel** — invisible, click-through window anchored to the left edge; hovers into view when your cursor enters the hot zone
-- **Clipboard history** — captures text, rich HTML, images, and file paths automatically
-- **Drag in / drag out** — drop multiple images or files into the shelf; drag items out into any other app (Photoshop, Explorer, Word…)
-- **Search, pin, delete, clear** — all the essentials of a high-end clipboard manager
-- **Deep-black macOS-inspired UI** — layered gradients, accent glow, inner light edge, smooth spring animations
-- **Settings** — accent color, hot-zone position/height, history limit, incognito mode, reduce motion, launch at login
-- **System tray** — show/hide, incognito toggle, quit
+## Overview
-## Getting Started
+Traditional clipboard managers disrupt workflow by requiring repetitive keyboard shortcuts (`Win+V`, `Cmd+Shift+V`) or manual navigation to system tray menus. **Edge-Drop** eliminates cognitive friction by acting as a transparent, frameless, always-on-top desktop accessory anchored to the leftmost pixel edge of your monitor.
-```bash
-npm install
-npm run dev # Launch with HMR
-npm run build # Production build
-npm run typecheck # Verify types
+When your cursor approaches the left boundary of your screen, Edge-Drop dynamically reveals itself with synchronized elastic spring physics. You can drag images, file stacks, rich text snippets, and HTML bundles out of the shelf and drop them natively into professional desktop software—such as **Adobe Photoshop**, **Microsoft Word**, **Slack**, or **Windows Explorer**—without ever leaving your active application.
+
+---
+
+## Architectural & Data Flow Diagrams
+
+### 1. High-Level System Architecture
+Edge-Drop maintains strict separation between Node.js system-level integrations (Main Process) and the React visual presentation layer (Renderer Process), communicating over a type-safe IPC bridge.
+
+```mermaid
+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
+```
+
+---
+
+### 2. The Invisible Edge-Trigger & Hysteresis State Machine
+To remain 100% click-through when hidden while preventing visual oscillation (flickering open/closed) when the user's cursor hovers near the shelf boundary, Edge-Drop implements a dead-band hysteresis algorithm in `useEdgeHover.ts`.
+
+```mermaid
+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
+ }
```
-## How It Works
+* **Trigger Zone (`x <= 3px`)**: A 3-pixel strip on the left screen edge starts a 120ms dwell timer.
+* **Dead Band (`255px < x <= 290px`)**: Cursor micro-tremors within this buffer are ignored.
+* **Grace Margin (`x > 290px`)**: Moving 20px outside the visual shelf starts a 250ms grace timer before collapsing.
+
+---
+
+### 3. Clipboard Capture & Deduplication Pipeline
+The background service `ClipboardWatcher.ts` continuously monitors the OS clipboard, computing content hashes to deduplicate entries and elevate reused items to the top of the stack.
+
+```mermaid
+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
+```
+
+---
+
+### 4. OS-Level OLE Native Drag & Drop Protocol
+Standard web drag events cannot pass file handles to external desktop software. Edge-Drop intercepts HTML5 drags and bridges them to Electron's native OS drag API.
+
+```mermaid
+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
+```
-| Mechanism | Detail |
+---
+
+## Exhaustive Feature Specifications
+
+### 1. Zero-Click Edge Hover & Hysteresis
+* **Frameless & Transparent**: Runs as a frameless `BrowserWindow` anchored at `x=0`. When hidden, `win.setIgnoreMouseEvents(true, { forward: true })` allows underlying desktop apps to receive all mouse clicks and gestures without obstruction.
+* **16ms Cursor Polling**: Uses `screen.getCursorScreenPoint()` in the Main process to overcome Windows transparent window DOM event limitations, ensuring 100% reliable edge detection.
+* **Configurable Hot Zones**: Users can customize the vertical height of the trigger band (25%, 40%, 60%) and the height of the visual blade (40% to 100% of screen height).
+
+### 2. Synchronized Elastic Overshoot Bounce
+* **Physical Spring Reveal**: When the panel opens, the outer `.blade-container` wrapper scales outward by **+5%** (`scale: [0.92, 1.05, 0.98, 1]`) before snapping back to rest.
+* **Reverse Curve Connection Flares**: Two custom SVG top and bottom connection arcs (`.flare-top` and `.flare-bottom`) sit inside the container wrapper. When the shelf bounces, the connection curves scale and stretch in perfect synchronization with the clipboard body, creating a seamless visual attachment to the monitor bezel.
+
+### 3. Multi-Format Clipboard Engine
+* **Format Agnostic**: Captures plain text, URLs, rich HTML, RTF, raw image bitmaps, and multi-file selections.
+* **Smart Deduplication**: When an existing item is copied again, Edge-Drop elevates it to position 0, updates its timestamp, and increments its badge multiplier (`hitCount` badge), preventing duplicate clutter.
+* **Incognito Mode**: A single click suspends background polling, allowing users to handle sensitive passwords or financial data without logging to history.
+
+### 4. Fluid Collections & Stack Bundling
+* **Automatic Grouping**: Multi-file drag-ins or multi-image copies are automatically grouped into expandable 3D card stacks (`bundle-stack-large`) with cascading rotation and depth offsets.
+* **Sub-Item Drag & Split**: Click any bundle to smoothly expand its internal contents. Drag individual files directly out of an expanded bundle into external software, or click the split icon to detach a sub-item into an independent top-level shelf card.
+* **Interactive Drag Merging**: Drag any item card over another item on the shelf to instantly merge them into a unified collection bundle.
+
+### 5. High-Legibility Minimalist UI/UX
+* **Deep-Black macOS Aesthetics**: Built with deep black backgrounds (`#000000`), frosted glass blurs (`backdrop-filter: blur(20px)`), and minimalist hairlines (`rgba(255, 255, 255, 0.08)`).
+* **Scroll Gradient Masks**: Fixed top and bottom 18px linear gradient overlays smoothly fade scrolling items into black, eliminating sharp border clipping.
+* **Monochrome Styling**: Pinned items and multipliers feature clean, monochrome badges (`#ffffff` text on dark pill backgrounds) for maximum legibility and visual elegance.
+* **Pill Selector Settings**: Clean, instant-toggle pill buttons replace clumsy sliders for configuring history capacity (100–1000 items), auto-delete timers (1h to 7 days), and hot-zone dimensions.
+
+---
+
+## Technical Stack & Security Architecture
+
+| Technology | Role & Justification |
|---|---|
-| **Edge hide/expand** | Transparent, frameless, always-on-top `BrowserWindow` at x=0. `setIgnoreMouseEvents(true, { forward: true })` makes it click-through but still dispatches pointer events. Renderer detects cursor in the hot band (leftmost 12px × middle 40% of screen) and toggles interactivity via IPC. |
-| **Clipboard capture** | Polls every 600ms, computes a per-format signature for change detection, deduplicates, caps at the configured limit (default 500). |
-| **Drag out** | Main writes item content to a temp file (image→PNG, text→.txt, files→original paths) and calls `webContents.startDrag({ file, icon })` — Electron's supported native OLE drag path. |
-| **Drag in** | HTML5 `onDrop` + `webUtils.getPathForFile` (Electron ≥24) to resolve OS file objects back to absolute paths, bulk-added to the store. |
-| **Persistence** | JSON index in `userData/items.json`, image files in `userData/images/`. Settings in `userData/settings.json`. |
+| **Electron 31+** | Cross-platform desktop runtime providing access to OS OLE drag pipelines and native Win32 clipboard APIs. |
+| **electron-vite** | Ultra-fast build tooling separating Main, Preload, and Renderer processes with Vite HMR. |
+| **React 18 + TypeScript** | Strongly typed component hierarchy and reactive UI rendering. |
+| **Framer Motion** | Physics-based spring animations, layout transitions (`popLayout`), and gesture animations. |
+| **Zustand** | Lightweight, selector-optimized state management with zero cascading re-renders during drag gestures. |
-## Stack
+### Enterprise Hardening Standards
+* **`nodeIntegration: false` & `contextIsolation: true`**: Preload scripts execute in a isolated context. The React renderer cannot access Node.js or OS primitives directly.
+* **Typed IPC Contracts (`shared/ipc.ts`)**: All IPC channels (`InvokeMap`, `EventMap`, `SendMap`) are statically typed; neither process can emit or receive malformed payloads.
+* **Atomic JSON Persistence**: Disk operations write to temporary files before renaming over destination files, guaranteeing zero data corruption during system crashes.
+* **Dev-Safe Startup Registration**: Startup registry modifications (`app.setLoginItemSettings`) are strictly gated by `app.isPackaged` checks, preventing local development binaries from polluting Windows Registry startup keys.
-- **Electron** + **electron-vite** (main + preload + renderer HMR)
-- **React** + **TypeScript** + **Framer Motion** + **Zustand**
-- **Security**: contextIsolation on, nodeIntegration off, typed preload bridge, single-instance lock
+---
-## Project Structure
+## Project Structure & Responsibility Matrix
```
Edge-Drop/
-├─ shared/ types, IPC contracts, bridge type
-├─ electron/
-│ ├─ main/ window, tray, IPC handlers, config, drag-out, entry
-│ ├─ preload/ contextBridge API
-│ ├─ clipboard/ ClipboardWatcher, format readers
-│ └─ store/ ItemStore, settings, paths
-├─ src/ React renderer
-│ ├─ components/ Panel, ItemList, ClipboardItem, SearchBar, Header, Settings, Icons, EmptyState
-│ ├─ hooks/ useEdgeHover, useDragOut, useFilteredItems
-│ ├─ store/ Zustand appStore
-│ ├─ lib/ edge bridge client, theme, format helpers
-│ └─ styles/ tokens, global, panel, item, settings
-└─ resources/ app icon
+├─ shared/ # Statically typed IPC contracts & domain models
+│ ├─ types.ts # ClipboardItem, Bundle, Settings, and DragRequest DTOs
+│ └─ ipc.ts # InvokeMap, EventMap, and SendMap channel definitions
+├─ electron/ # Node.js backend & OS integrations
+│ ├─ main/ # Application lifecycle, window management & OLE drag handlers
+│ │ ├─ index.ts # Single-instance lock, IPC handler registration & startup
+│ │ ├─ window.ts # Frameless window creation, ignoreMouseEvents & cursor polling
+│ │ ├─ tray.ts # System tray icon & context menus
+│ │ └─ dragOut.ts # OLE native startDrag execution & temp file resolution
+│ ├─ preload/ # Sandbox bridge exposing window.edge API
+│ │ └─ index.ts # contextBridge exposure of typed IPC wrapper methods
+│ ├─ clipboard/ # Background clipboard monitoring services
+│ │ ├─ ClipboardWatcher.ts # 600ms polling loop & format detection
+│ │ └─ formatReaders.ts # Win32 HDROP, RTF, HTML, and bitmap extraction
+│ └─ store/ # Disk persistence & state synchronization
+│ ├─ ItemStore.ts # Atomic JSON history persistence & deduplication logic
+│ ├─ settings.ts # User configuration management & startup registration
+│ └─ paths.ts # AppData directory resolution & temp folder management
+├─ src/ # React renderer process (UI & Motion)
+│ ├─ components/ # Modular visual components
+│ │ ├─ Panel.tsx # Outer blade wrapper, AnimatePresence & connection flares
+│ │ ├─ ItemList.tsx # Virtualized scrolling list & drag-over auto-scroll
+│ │ ├─ ClipboardItem.tsx # Card tile, AnimatePresence expansion & subitem actions
+│ │ ├─ SearchBar.tsx # Instant filtering & clear actions
+│ │ ├─ Settings.tsx # Pill selectors, toggles & gradient masks
+│ │ └─ Icons.tsx # Optimized SVG icon library
+│ ├─ hooks/ # Custom reactive hooks
+│ │ ├─ useEdgeHover.ts # Dual-threshold hysteresis state machine (3px / 255px / 290px)
+│ │ └─ useDragOut.ts # Native OLE drag trigger formatting
+│ ├─ store/ # Zustand appStore & selector definitions
+│ ├─ lib/ # Theme tokens & format display utilities
+│ └─ styles/ # Modular CSS architecture
+│ ├─ tokens.css # Design system colors, radii, shadows & z-indices
+│ ├─ panel.css # Blade wrapper, reverse curves & badges
+│ └─ settings.css # Pill button styling & gradient overlays
+└─ resources/ # Application icons & branding assets
```
+
+---
+
+## Getting Started & Development
+
+### Prerequisites
+* **Node.js**: v18.0.0 or higher
+* **OS**: Windows 10/11 (Primary target for OLE drag and transparent window polling) or macOS 12+
+
+### Installation & Running Locally
+
+1. **Clone the repository & install dependencies**:
+ ```bash
+ git clone https://github.com/your-username/Edge-Drop.git
+ cd Edge-Drop
+ npm install
+ ```
+
+2. **Start the development server with HMR**:
+ ```bash
+ npm run dev
+ ```
+ *Launches the Electron main process and starts the Vite renderer server with Hot Module Replacement.*
+
+3. **Type-checking & Linting**:
+ ```bash
+ npm run typecheck
+ npm run lint
+ ```
+
+### Building & Packaging for Production
+
+To create a standalone production executable (`.exe` installer or unpackaged binary):
+
+```bash
+# Build TypeScript and bundle production assets to /out and /dist
+npm run build
+
+# Package the Windows application using electron-builder
+npm run package
+```
+> [!NOTE]
+> If packaging fails on Windows with an `EBUSY: resource busy or locked` error, ensure that any running instances of Edge-Drop are completely closed before rebuilding (`taskkill /F /IM electron.exe /T`).
+
+---
+
+## Additional Documentation
+
+For an even deeper technical dive into the individual subsystems, see **[FEATURES.md](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/FEATURES.md)** in the repository root, which contains comprehensive breakdowns of the dead-band hysteresis math, OLE temporary file management, and fluid bundle memory layouts.
diff --git a/drag_debug.txt b/drag_debug.txt
index d67df81..31130d5 100644
--- a/drag_debug.txt
+++ b/drag_debug.txt
@@ -1323,3 +1323,89 @@
[2026-07-05T15:41:55.693Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
[2026-07-05T15:41:55.694Z] createFileStackDragIcon calling Resvg for count=1
[2026-07-05T15:41:55.858Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:04.318Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:30:04.775Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:04.777Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:30:04.928Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:04.929Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:30:05.066Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:19.116Z] startDragOut called for kind=files
+[2026-07-07T12:30:19.117Z] staged: file=C:\Users\yadav\Downloads\RESUME_ARCHITECT_MASTER.md, files=["C:\\Users\\yadav\\Downloads\\RESUME_ARCHITECT_MASTER.md"]
+[2026-07-07T12:30:19.117Z] dragIcon called for kind=files
+[2026-07-07T12:30:19.117Z] files check: count=1, paths=["C:\\Users\\yadav\\Downloads\\RESUME_ARCHITECT_MASTER.md"]
+[2026-07-07T12:30:19.118Z] createFileStackDragIcon returning cached for stack|dark|text|1
+[2026-07-07T12:30:19.118Z] dragIcon result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:19.118Z] calling sender.startDrag with item.file=C:\Users\yadav\Downloads\RESUME_ARCHITECT_MASTER.md, item.files=["C:\\Users\\yadav\\Downloads\\RESUME_ARCHITECT_MASTER.md"]
+[2026-07-07T12:30:31.499Z] startDragOut called for kind=files
+[2026-07-07T12:30:31.500Z] staged: file=C:\Users\yadav\Downloads\V0Bn101.svg, files=["C:\\Users\\yadav\\Downloads\\V0Bn101.svg"]
+[2026-07-07T12:30:31.501Z] dragIcon called for kind=files
+[2026-07-07T12:30:31.502Z] files check: count=1, paths=["C:\\Users\\yadav\\Downloads\\V0Bn101.svg"]
+[2026-07-07T12:30:31.502Z] createFileStackDragIcon returning cached for stack|dark|image|1
+[2026-07-07T12:30:31.503Z] dragIcon result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:30:31.503Z] calling sender.startDrag with item.file=C:\Users\yadav\Downloads\V0Bn101.svg, item.files=["C:\\Users\\yadav\\Downloads\\V0Bn101.svg"]
+[2026-07-07T12:35:04.849Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:35:05.156Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:35:05.156Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:35:05.302Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:35:05.303Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:35:05.433Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:41:45.873Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:41:46.034Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:41:46.034Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:41:46.204Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:41:46.205Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:41:46.354Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:42:31.510Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:42:31.674Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:42:31.675Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:42:31.818Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:42:31.819Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:42:31.968Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:43:13.882Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:43:14.054Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:43:14.055Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:43:14.194Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:43:14.195Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:43:14.360Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:46:37.986Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:46:38.524Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:46:38.525Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:46:38.747Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:46:38.748Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:46:38.970Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:50:42.230Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:50:42.589Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:50:42.590Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:50:42.729Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T12:50:42.730Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T12:50:42.866Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T13:06:19.716Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T13:06:20.043Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T13:06:20.044Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T13:06:20.181Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T13:06:20.181Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T13:06:20.319Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:01:17.587Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:01:17.971Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:01:17.972Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:01:18.125Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:01:18.125Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:01:18.262Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:49:01.795Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:49:02.148Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:49:02.148Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:49:02.290Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T14:49:02.291Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T14:49:02.427Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:40:31.417Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:40:32.872Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:40:32.873Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:40:33.187Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:40:33.188Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:40:33.468Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:46:05.889Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:46:06.259Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:46:06.260Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:46:06.414Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
+[2026-07-07T19:46:06.415Z] createFileStackDragIcon calling Resvg for count=1
+[2026-07-07T19:46:06.574Z] createFileStackDragIcon resvg result: isEmpty=false, size={"width":96,"height":96}
diff --git a/electron.vite.config.1783428191594.mjs b/electron.vite.config.1783428191594.mjs
new file mode 100644
index 0000000..8f884ee
--- /dev/null
+++ b/electron.vite.config.1783428191594.mjs
@@ -0,0 +1,46 @@
+// electron.vite.config.ts
+import { resolve } from "node:path";
+import { defineConfig, externalizeDepsPlugin } from "electron-vite";
+import react from "@vitejs/plugin-react";
+var __electron_vite_injected_dirname = "C:\\Users\\yadav\\OneDrive\\Desktop\\projects\\Edge-Drop";
+var electron_vite_config_default = defineConfig({
+ main: {
+ plugins: [externalizeDepsPlugin()],
+ build: {
+ rollupOptions: {
+ input: { index: resolve(__electron_vite_injected_dirname, "electron/main/index.ts") }
+ }
+ }
+ },
+ preload: {
+ plugins: [externalizeDepsPlugin()],
+ build: {
+ rollupOptions: {
+ input: { index: resolve(__electron_vite_injected_dirname, "electron/preload/index.ts") },
+ output: {
+ format: "cjs",
+ entryFileNames: "[name].cjs"
+ }
+ }
+ }
+ },
+ renderer: {
+ // Root must be project root because index.html lives there.
+ root: ".",
+ resolve: {
+ alias: {
+ "@renderer": resolve(__electron_vite_injected_dirname, "src"),
+ "@shared": resolve(__electron_vite_injected_dirname, "shared")
+ }
+ },
+ build: {
+ rollupOptions: {
+ input: { index: resolve(__electron_vite_injected_dirname, "index.html") }
+ }
+ },
+ plugins: [react()]
+ }
+});
+export {
+ electron_vite_config_default as default
+};
diff --git a/electron/clipboard/formats.ts b/electron/clipboard/formats.ts
index 95321a0..40ea041 100644
--- a/electron/clipboard/formats.ts
+++ b/electron/clipboard/formats.ts
@@ -7,6 +7,8 @@
* variants out of raw Windows formats (copied files arrive as FileNameW).
*/
import { clipboard } from 'electron'
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
import type { ItemData } from '../../shared/types'
/** Windows clipboard format name for a copied-file list. */
@@ -17,8 +19,39 @@ function readFileList(): string[] | null {
try {
const buf = clipboard.readBuffer(CF_FILE_LIST)
if (!buf || buf.length < 4) return null
- // FileNameW is a null-terminated UTF-16LE wide string. Multiple files are
- // separated by NUL chars; the whole blob ends with a double NUL.
+
+ if (process.platform === 'win32') {
+ try {
+ // Retrieve the full list of files from the system clipboard using PowerShell
+ // to bypass Electron's built-in single file limit.
+ const stdout = execSync(
+ 'powershell.exe -NoProfile -NonInteractive -Command "Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::GetFileDropList()"',
+ { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }
+ )
+ const paths = stdout
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .filter((line) => line.length > 0 && existsSync(line))
+ if (paths.length > 0) return paths
+ } catch (err) {
+ console.error('[formats] Failed to read file drop list via PowerShell:', err)
+ }
+ }
+
+ // Fallback: parse the FileNameW buffer directly (only gets the first file on Windows)
+ const wide = buf.toString('utf16le')
+ const parts = wide.split('\u0000').map((s) => s.trim()).filter(Boolean)
+ return parts.length ? parts : null
+ } catch {
+ return null
+ }
+}
+
+/** Fast, non-blocking check of FileNameW contents for clipboard signatures. */
+function readFileListFast(): string[] | null {
+ try {
+ const buf = clipboard.readBuffer(CF_FILE_LIST)
+ if (!buf || buf.length < 4) return null
const wide = buf.toString('utf16le')
const parts = wide.split('\u0000').map((s) => s.trim()).filter(Boolean)
return parts.length ? parts : null
@@ -234,7 +267,8 @@ export function clipboardSignature(): string {
const fmtKey = formats.slice().sort().join('\x1f')
// If files are on the clipboard, their paths are the most stable fingerprint.
- const files = readFileList()
+ // Use fast, non-blocking read to avoid spawning a child process during polling.
+ const files = readFileListFast()
if (files && files.length) {
return `files:${files.join('\n')}`
}
diff --git a/electron/main/ipc.ts b/electron/main/ipc.ts
index eaac67c..94a7dc9 100644
--- a/electron/main/ipc.ts
+++ b/electron/main/ipc.ts
@@ -101,6 +101,10 @@ export function registerIpc(): void {
writeItemToClipboard(item.data)
console.log('[IPC] item:copy wrote to clipboard, kind=', item.data.kind)
+ // Promote the copied item to the top of the history stack
+ getStore().add(item.data, loadSettings().historyLimit)
+ pushState.items()
+
// Unpause after a short delay to allow OS clipboard event to settle.
// Respect the current incognito state when unpausing.
setTimeout(() => {
@@ -142,6 +146,13 @@ export function registerIpc(): void {
if (!wrote) return false
+ // Promote the parent item to the top of the history stack
+ const parentItem = getStore().get(req.id)
+ if (parentItem) {
+ getStore().add(parentItem.data, loadSettings().historyLimit)
+ pushState.items()
+ }
+
const watcher = getWatcher()
watcher.setPaused(true)
setTimeout(() => {
@@ -163,6 +174,10 @@ export function registerIpc(): void {
writeItemToClipboard(item.data)
console.log('[IPC] item:paste wrote to clipboard, kind=', item.data.kind)
+ // Promote the pasted item to the top of the history stack
+ getStore().add(item.data, loadSettings().historyLimit)
+ pushState.items()
+
// Close panel via toggle so focus returns to the user's active input/text box
pushState.togglePanel()
@@ -211,6 +226,13 @@ export function registerIpc(): void {
if (!wrote) return false
+ // Promote the parent item to the top of the history stack
+ const parentItem = getStore().get(req.id)
+ if (parentItem) {
+ getStore().add(parentItem.data, loadSettings().historyLimit)
+ pushState.items()
+ }
+
pushState.togglePanel()
setTimeout(() => {
diff --git a/electron/main/window.ts b/electron/main/window.ts
index 376aa28..d2af024 100644
--- a/electron/main/window.ts
+++ b/electron/main/window.ts
@@ -61,14 +61,14 @@ export function setInteractive(value: boolean): void {
if (value) {
// Panel is open: disable click-through so user can interact.
mainWindow.setIgnoreMouseEvents(false)
- mainWindow.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow.setAlwaysOnTop(true, 'floating')
} else {
// Panel is closed: full click-through, no forwarding needed.
// Cursor edge detection is done by the main-process poll (startCursorPoll)
// via screen.getCursorScreenPoint() + IPC, so forward:true is not required
// and omitting it ensures Windows passes ALL mouse clicks to apps beneath.
mainWindow.setIgnoreMouseEvents(true, { forward: false })
- mainWindow.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow.setAlwaysOnTop(true, 'floating')
}
}
@@ -191,7 +191,7 @@ export function createWindow(): BrowserWindow {
// Respect OS-level always-on-top reordering.
mainWindow.on('focus', () => {
- mainWindow?.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow?.setAlwaysOnTop(true, 'floating')
})
// Open external links in the default browser.
@@ -210,7 +210,7 @@ export function createWindow(): BrowserWindow {
mainWindow.once('ready-to-show', () => {
if (!mainWindow) return
mainWindow.show()
- mainWindow.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow.setAlwaysOnTop(true, 'floating')
})
mainWindow.webContents.on('console-message', (_event, _level, message, line, sourceId) => {
@@ -233,7 +233,7 @@ export function createWindow(): BrowserWindow {
heartbeatTimer = setInterval(() => {
if (runtime.quitting) return
if (mainWindow && !mainWindow.isDestroyed() && mainWindow.isVisible()) {
- mainWindow.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow.setAlwaysOnTop(true, 'floating')
}
if (detectorWindow && !detectorWindow.isDestroyed() && detectorWindow.isVisible()) {
detectorWindow.setAlwaysOnTop(true, 'normal')
@@ -255,7 +255,7 @@ export function setVisible(visible: boolean): void {
if (!mainWindow) return
if (visible) {
mainWindow.showInactive()
- mainWindow.setAlwaysOnTop(true, 'screen-saver')
+ mainWindow.setAlwaysOnTop(true, 'floating')
} else {
mainWindow.hide()
}
diff --git a/features_and_architecture.md b/features_and_architecture.md
new file mode 100644
index 0000000..d9c539a
--- /dev/null
+++ b/features_and_architecture.md
@@ -0,0 +1,271 @@
+# 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 `startDrag` pipeline, 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).
+
+```mermaid
+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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/shared/ipc.ts))
+To prevent drift between processes, all communication occurs over three statically typed maps:
+1. **`InvokeMap`** (Request/Response): Asynchronous operations where the renderer expects a result from Node.js (e.g., `state:load`, `item:delete`, `item:merge`, `settings:update`).
+2. **`EventMap`** (Main $\rightarrow$ Renderer): Real-time broadcast signals initiated by the background services (e.g., `state:items`, `window:cursor-edge`, `ui:toast`).
+3. **`SendMap`** (Fire-and-Forget): Time-critical, synchronous gestures. The primary use case is `item: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.
+
+```mermaid
+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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/src/hooks/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 the `DWELL_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 the `GRACE_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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/clipboard/ClipboardWatcher.ts) continuously monitors the system clipboard without relying on brittle OS polling hooks that degrade CPU performance.
+
+```mermaid
+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 `popLayout` engine, 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.
+
+```mermaid
+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`:
+1. The renderer calls `e.preventDefault()` on the native HTML5 drag event to prevent the browser from rendering an empty drag image.
+2. It synchronously dispatches `item:start-drag` to Node.js.
+3. 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`).
+4. 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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/src/components/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:
+```json
+{
+ "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](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/store/settings.ts) & [ItemStore.ts](file:///c:/Users/yadav/OneDrive/Desktop/projects/Edge-Drop/electron/store/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 explicit `if (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. |