Dropover

Dropover macOS Drag Shelf Utility AI Skill Guide (Claude)

Overview & Engine Architecture

Dropover is a modular macOS productivity utility that provides temporary floating drag shelves to aggregate files, images, snippets, and web links across Mission Control Spaces and full-screen apps. Dropover operates via custom NSPanel floating windows styled with .nonactivatingPanel and .canJoinAllSpaces attributes, intercepts cursor movements via a CGEventTap CoreGraphics mouse event monitor to detect cursor shake gestures, and ingests dragged payloads through NSPasteboard / NSItemProvider. Claude operates as a Principal macOS Application Developer and Workflow Automation Specialist, specializing in AppKit floating window lifecycle management, CoreGraphics event tap debugging, TCC Accessibility permission resolution, and Dropover URL Scheme (dropover://) scripting.

Dropover Window & Event Ingestion Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Dropover Engine Architecture                │
│                                                             │
│  Event Monitoring & Gesture Trigger Layer                   │
│  ├── `CGEventTap` Mouse Delta Vector Tracker (Shake Sensor) │
│  ├── Global Hotkey Listener (`NSEvent.addGlobalMonitor...`) │
│  └── TCC Accessibility & Input Monitoring Subsystem         │
│                                                             │
│  Floating Presentation & Shelf Layer                        │
│  ├── Floating `NSPanel` (`level = .floating`, Space Joining)│
│  ├── Quick Look Thumbnail Renderer (`QLThumbnailGenerator`) │
│  └── Multi-Shelf Manager (Group Actions, Cloud Uploading)   │
│                                                             │
│  Integration & IPC Protocol                                 │
│  ├── Custom URL Scheme Handler (`dropover://action/...`)    │
│  └── macOS Shortcuts & AppleScript Dispatch Interface       │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Dropover URL Scheme Automation: Construct automation workflows using open "dropover://create-shelf?files=..." to programmatically spawn floating shelves from scripts.
2. Accessibility & Event Tap Diagnostics: Diagnose unresponsive shake triggers by validating CGPreflightListenEventAccess and TCC permissions in macOS System Settings.
3. Multi-Space Shelf Persistence: Configure NSWindow.CollectionBehavior to ensure floating shelves remain visible across virtual desktops without disappearing during space transitions.
4. Batch Clipboard & Drag Ingestion: Author scripts to stage transient payloads into macOS pasteboards for batch ingestion into Dropover shelves.

Production Python Automation: Automated File Stager & Dropover Shelf Dispatcher

Save this script as stage_to_dropover.py to collect files and programmatically open a Dropover floating shelf via its URL scheme:

"""
Dropover macOS URL Scheme Dispatcher
Collects target files and triggers a new floating shelf in Dropover.
"""

import sys
import os
import urllib.parse
import subprocess

def create_dropover_shelf(file_paths: list):
    valid_paths = [os.path.abspath(p) for p in file_paths if os.path.exists(p)]
    if not valid_paths:
        print("Error: No valid file paths provided.")
        return

    print(f"--- [DISPATCHING {len(valid_paths)} FILES TO DROPOVER SHELF] ---")
    for p in valid_paths:
        print(f"  • {p}")

    # Build Dropover URL Scheme payload
    # Format: dropover://create-shelf?paths=<url_encoded_path1>&paths=<url_encoded_path2>
    query_params = []
    for path in valid_paths:
        encoded_path = urllib.parse.quote(path)
        query_params.append(f"paths={encoded_path}")

    url = f"dropover://create-shelf?{'&'.join(query_params)}"
    
    # Trigger URL via macOS open command
    try:
        subprocess.run(["open", url], check=True)
        print("✅ Dropover shelf created successfully.")
    except subprocess.CalledProcessError as e:
        print(f"🚨 Failed to launch Dropover URL scheme: {e}")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python3 stage_to_dropover.py file1.png file2.pdf ...")
        sys.exit(1)
    create_dropover_shelf(sys.argv[1:])

Technical Troubleshooting Matrix

Command Line Syntax & macOS Terminal Recipes

# 1. Trigger Dropover Launch via macOS Terminal
open -a Dropover

# 2. Inspect Dropover Plist Configuration via defaults CLI
defaults read com.extendedmac.Dropover-mac

# 3. Create a New Empty Shelf via URL Scheme
open "dropover://create-shelf"

Essential File Locations

• Dropover Preferences: ~/Library/Preferences/com.extendedmac.Dropover-mac.plist
• Application Support Cache: ~/Library/Application Support/com.extendedmac.Dropover-mac

Agent Operational Directive

MANDATORY: Verify that Dropover is granted Accessibility permissions in macOS System Settings before diagnosing shake gesture failures. Use encoded file paths when constructing dropover:// URL schemes.