Clipboard Service Functionalities in Vorssaint Utils

The Vorssaint Utils Clipboard service provides comprehensive history tracking, quick-access UI panels, configurable auto-clear triggers, and privacy-first content filtering through two core components: ClipboardHistoryService and ClipboardAutoClearService.

The Clipboard service in the vorssaint/vorssaint-utils repository delivers a production-ready macOS clipboard management solution. It captures system pasteboard changes asynchronously while providing granular privacy controls and automatic sanitization capabilities.

History Capture and Content Detection

The ClipboardHistoryService polls the system pasteboard via readPasteboard to detect new content. It normalizes captured data through type-specific promotion methods: promote for plain text, promoteImage for image data, and promoteFiles for file references. Each captured item becomes a ClipboardHistoryEntry stored in the in-memory entries array.

Sensitive Content Filtering

Before storing any text, the service validates content against ClipboardHistorySensitiveText.isConcealed and looksSensitive to prevent recording passwords or secrets. The ClipboardHistoryEditing.storableText validator ensures edited entries remain within size limits and do not contain sensitive patterns unless the user explicitly disables the filter.

Quick Access Panel and Batch Operations

The service renders a floating quick-access panel through [ClipboardQuickPanelView.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/MenuPanel/ClipboardQuickPanelView.swift). Users interact with filteredEntries for live search, toggleQuickPreview to resize the panel, and batch selection methods including toggleQuickBatchSelection and selectAllQuickEntries. The panel supports preview sidebars via [ClipboardEntryPreviewSidebar.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/MenuPanel/ClipboardEntryPreviewSidebar.swift) and text rendering through [ClipboardTextPreview.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/MenuPanel/ClipboardTextPreview.swift).

Copy and Paste Implementation

copy(_:) and copy(_:completion:) write single entries to the pasteboard asynchronously using GeneralPasteboardAccess.shared.async to avoid blocking the main thread. For quick-panel interactions, copyQuickEntry(_:) and copyQuickEntries(_:) handle single or batch paste operations. All methods utilize plannedWrite to compose the correct pasteboard representation, supporting plain text, PNG/TIFF images, file URLs, and rich-text formats.

Content Organization and History Management

togglePin keeps important entries at the top of the history, while move allows repositioning items within their pinned or recent groups. The service maintains order integrity through normalizeEntryOrder and enforces storage limits via trimToLimit, which respects the user-defined DefaultsKey.clipboardHistoryLimit. For text corrections, updateText(_:to:) validates input through ClipboardHistoryEditing.storableText while preserving the entry's pinned state.

Automatic Pasteboard Clearing

The ClipboardAutoClearService monitors the system pasteboard through a tick timer that tracks change counts. It delegates clearance decisions to ClipboardAutoClearSupport.decide, which evaluates four independent triggers: a configurable delay after the last copy, computer sleep, display sleep, and screen lock. System event observers (sleepObserver, displaySleepObserver, screenLockObserver) fire immediate clearing when these events occur.

Global Shortcut Integration

registerHotkey creates a system-wide Carbon hot-key using RegisterEventHotKey that routes key presses to toggleHistoryWindow. The shortcut can be suspended during shortcut editing to prevent conflicts. This allows users to summon the history panel from any application context.

Data Persistence and Storage

History serialization occurs through save, persist, and load methods, which write to ClipboardHistory.json in the application's private container. The service coalesces writes to minimize disk I/O and uses flushBeforeTermination to ensure data survives crashes. Legacy data fallback to UserDefaults is supported for migration scenarios.

Configuration and Settings

User preferences are exposed through [ClipboardSettings.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/ClipboardSettings.swift), enabling toggles for history recording and limit configuration. Application-specific exclusions are managed via [ClipboardIgnoredAppsList.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/ClipboardIgnoredAppsList.swift), which prevents the service from polling the pasteboard when specific apps are frontmost.

Practical Implementation Examples

import Vorssaint

// Enable history tracking
UserDefaults.standard.set(true, forKey: DefaultsKey.clipboardHistoryEnabled)
ClipboardHistoryService.shared.syncWithPreferences()

// Copy text with completion handling
let entry = ClipboardHistoryEntry(text: "Secure workflow integration")
ClipboardHistoryService.shared.copy(entry) { success in
    print("Pasteboard updated: \(success)")
}

// Pin an entry to prevent automatic trimming
if let entry = ClipboardHistoryService.shared.entries.first {
    ClipboardHistoryService.shared.togglePin(entry)
}

// Configure auto-clear after 30 seconds of inactivity
UserDefaults.standard.set(true, forKey: DefaultsKey.clipboardAutoClearOnDelay)
UserDefaults.standard.set(30, forKey: DefaultsKey.clipboardAutoClearDelay)
ClipboardAutoClearService.shared.syncWithPreferences()

Summary

• Asynchronous Capture: The ClipboardHistoryService polls the pasteboard via readPasteboard and promotes diverse content types without blocking the main thread.
• Privacy Controls: Built-in isConcealed and looksSensitive checks prevent recording secrets, while ClipboardAutoClearService sanitizes the pasteboard based on time or system events.
• Flexible UI: SwiftUI-based quick panels support live search, batch selection, and preview rendering with toggleQuickPreview.
• Persistence: History serializes to ClipboardHistory.json using coalesced write operations and crash-safe flushBeforeTermination.
• System Integration: Carbon hot-keys provide global access, while ClipboardSettings.swift and ClipboardIgnoredAppsList.swift offer granular preference control.

Frequently Asked Questions

How does the Clipboard service detect and handle sensitive content?

The service inspects all text through ClipboardHistorySensitiveText.isConcealed and looksSensitive methods before creating entries. These checks identify password patterns and concealed pasteboard types, preventing storage unless the user disables the security filter in preferences. The updateText method additionally validates edited content against ClipboardHistoryEditing.storableText to maintain these security boundaries.

What triggers the automatic clipboard clearing functionality?

ClipboardAutoClearService evaluates four independent conditions through ClipboardAutoClearSupport.decide: a user-configurable delay after the last copy operation, computer sleep events, display sleep events, and screen lock activation. The service monitors system notifications via sleepObserver, displaySleepObserver, and screenLockObserver to trigger immediate clearing when these state changes occur.

How is clipboard history persisted across application restarts?

The service maintains durability through save, persist, and load operations that serialize the entries array to a JSON file at ClipboardHistory.json within the app's private container. The flushBeforeTermination method ensures data is written before the app closes, while coalesced writes optimize performance during normal operation. Legacy data stored in UserDefaults is automatically migrated to the file-based system.

Can I exclude specific applications from clipboard monitoring?

Yes. The [ClipboardIgnoredAppsList.swift](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/ClipboardIgnoredAppsList.swift) interface allows users to specify bundle identifiers or application names that the ClipboardHistoryService will ignore during its polling cycle. When an ignored application becomes active, the service suspends readPasteboard operations to prevent capturing sensitive data from password managers or banking applications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}