Clipboard Manager Implementation Summary

Overview

A clipboard manager applet for the COSMIC desktop environment, built with Rust using the libcosmic framework and iced GUI toolkit. It monitors the system clipboard using wl-clipboard-rs, stores history in SQLite, and provides a searchable interface with a two-panel Raycast-style UI.

Architecture

Core Components

1. Main Application (src/main.rs)

• Entry point that initializes logging, localization, and configuration
• Runs the COSMIC applet with SQLite backend
• Handles version flag (-V, --version)

2. Application State (src/app.rs)

• Main application logic using cosmic::Application trait
• Manages popup windows (main clipboard view and quick settings)
• Handles navigation, clipboard events, and user interactions
• Key structures:
  • AppState<Db>: Main application state with database, config, and UI state
  • ClipboardState: Tracks connection status or errors
  • PopupKind: Differentiates between main popup and quick settings

3. Database Layer (src/db/)

• SQLite Backend (sqlite_db.rs): Persistent storage with:
  • Entry table for clipboard items
  • Favorite marking support
  • Automatic cleanup based on entry limits and lifetime
  • Full-text search capabilities
  • MIME type storage for each entry

4. Clipboard Integration (src/clipboard.rs, src/clipboard_watcher.rs)

• Uses Wayland's zwlr_data_control_v1 protocol
• Monitors clipboard changes in real-time
• Filters X11 MIME types to prevent crashes with apps like Sublime Text
• Persistence via wl-clipboard-rs: spawns background thread to serve data
• Private mode support (disables monitoring when enabled)

5. UI Layer (src/view.rs)

• Maccy-like Interface: Minimalist list view, optimized for rapid keyboard navigation.
• Rich Content Support:
  • Captures Text (default).
  • Optional support for Images and Binary data.
  • Thumbnails: Automatically generates and displays previews for copied images.
• Quick Settings Panel: Toggle private mode, unique session, clear entries
• Search Bar: Real-time filtering with pagination controls

6. Navigation (src/navigation.rs)

• Keyboard event handling:
  • Arrow keys: Navigate list (Up/Down in vertical, Left/Right in horizontal)
  • Enter: Copy focused entry and close popup
  • Delete: Remove focused entry (works even when search input is focused)
  • Escape: Close popup
• Event subscription system using iced::Subscription

7. Configuration (src/config.rs)

• Cosmic config integration with auto-reload
• Settings:
  • private_mode: Disable clipboard monitoring
  • maximum_entries_lifetime: Days to keep entries (default: 30)
  • maximum_entries_number: Max total entries (default: 500)
  • maximum_entries_by_page: Entries per page (default: 10)
  • user_session: Clear on logout
  • preferred_mime_types: Regex patterns for MIME type priority

8. Messages (src/message.rs)

• Event-driven architecture with message types:
  • AppMsg: Main application messages
  • ConfigMsg: Configuration changes
  • DbMessage: Database operations
  • Clipboard events, navigation events, user actions

Key Features

1. Clipboard Monitoring

• Real-time clipboard change detection
• Multi-MIME type support (text, images, file URIs)
• X11 MIME filter to prevent app crashes
• Automatic deduplication on insert

2. Search & Navigation

• Full-text search across entries
• Keyboard navigation with arrow keys
• Pagination (10 items per page by default)
• Auto-scrolling to focused item

3. Entry Management

• Favorite marking (★)
• Delete individual entries
• Clear all entries
• Copy on click or Enter key
• Automatic cleanup based on age/count limits

4. Clipboard Persistence

• Uses wl-clipboard-rs to serve data in background
• Prevents data loss when source app closes
• Spawns daemon thread that exits when clipboard is overtaken

5. UI Design

• Raycast-inspired two-panel layout
• 800px wide popup (700-900px limits)
• Compact list preview (30 chars) + full content panel
• Responsive to theme changes
• No Icons and Completely Keyboard driven

6. Privacy & Sessions

• Private mode: Disables monitoring
• Unique session: Auto-clear on app exit
• No persistent clipboard when session ends

Technical Details

Dependencies

• libcosmic: COSMIC desktop framework with applet support
• iced: Cross-platform GUI framework
• sqlx: Async SQLite operations
• wl-clipboard-rs: Wayland clipboard interaction
• tokio: Async runtime

Wayland Protocol Requirements

• Requires zwlr_data_control_manager_v1 protocol
• On COSMIC, must be enabled via:

  echo 'export COSMIC_DATA_CONTROL_ENABLED=1' | sudo tee /etc/profile.d/data_control_cosmic.sh > /dev/null

Build & Run

# Build
just build-release

# Run (for testing)
just run

# Install
just install  # or equivalent make install

Performance Considerations

1. Entry Limits: Default 500 entries, configurable
2. Page Size: 10 items per page reduces rendering load
3. Lazy Loading: Only render visible page range
4. Image Caching: Uses iced image handles
5. Database Indexing: Timestamp and favorite columns indexed

Security & Privacy

1. Protocol Security: zwlr_data_control_v1 allows privileged clipboard access
2. Private Mode: Completely disables monitoring
3. Unique Session: No persistence between logins
4. No Network: All data stored locally in SQLite

Future Considerations

• Syntax highlighting for code snippets
• Advanced filtering (by type, date, favorites)
• Export/import clipboard history
• Clipboard sharing across devices (if network feature added)
• Plugin system for custom content handlers
• Global keyboard shortcut when COSMIC supports it