# Clipboard Service Functionalities in Vorssaint Utils

> Explore the Vorssaint Utils Clipboard service's powerful history tracking, UI panels, auto-clear, and privacy filtering features. Enhance your workflow today.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: api-reference
- Published: 2026-09-08

---

**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](https://github.com/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Clipboard/ClipboardHistoryService.swift) 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/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/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/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Clipboard/ClipboardAutoClearService.swift) monitors the system pasteboard through a `tick` timer that tracks change counts. It delegates clearance decisions to [`ClipboardAutoClearSupport.decide`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Clipboard/ClipboardAutoClearSupport.swift), 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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/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/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

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardHistory.json) using coalesced write operations and crash-safe `flushBeforeTermination`.
- **System Integration**: Carbon hot-keys provide global access, while [`ClipboardSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/ClipboardSettings.swift) and [`ClipboardIgnoredAppsList.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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/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.