# How the Dock Preview Service in Vorssaint-Utils Captures Window Previews

> Discover how the Dock preview service in vorssaint-utils captures window previews using a dual-engine pipeline with CGSHWCaptureWindowList and ScreenCaptureKit, plus LRU caching.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-11

---

**The Dock preview service in vorssaint-utils captures window previews through a dual-engine pipeline that first attempts fast Window-Server capture via `CGSHWCaptureWindowList`, then falls back to ScreenCaptureKit for hidden or Stage Manager windows, caching results in a 64 MiB LRU buffer.**

The Dock preview feature in vorssaint-utils provides live thumbnails when hovering over Dock icons, implemented through a sophisticated capture pipeline that balances performance and system compatibility. This macOS utility leverages both private Window-Server APIs and public ScreenCaptureKit frameworks to deliver real-time window previews without requiring constant screen-recording permissions. Understanding how the Dock preview service captures window previews reveals a carefully engineered fallback system designed to handle everything from minimized windows to Stage Manager parked applications.

## Architecture Overview

The implementation spans three coordinated components that manage the capture lifecycle, image processing, and UI presentation.

### DockPreviewService (The Orchestrator)

Located in [`Sources/Vorssaint/Services/DockPreview/DockPreviewService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/DockPreview/DockPreviewService.swift) (lines 26-28, 84-89, 274-288), this observable singleton monitors mouse events through `handleMouseMoved` and `dockHit(at:)` to detect Dock icon hovers. When a hover timer expires, it initiates a preview session via `beginSession(_:)`, requesting thumbnails from the provider and managing the floating preview panel's lifecycle.

### WindowPreviewProvider (The Capture Engine)

Found in [`Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift) (lines 41-53, 107-115, 141-149), this class implements the dual-capture strategy. It maintains a time-based LRU cache (max 48 entries or 64 MiB) and exposes `refreshPreviews(for:)` to batch-capture window images, detecting Stage Manager strips through `SwitcherSupport.alphaGrid` and rectifying them via `rectifiedStripCapture` (lines 258-320).

### DockPreviewSupport (Geometry and Timing)

Defined in [`Sources/Vorssaint/Services/DockPreview/DockPreviewSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/DockPreview/DockPreviewSupport.swift) (lines 69-72, 103-106), this helper supplies critical UI parameters including `previewableWindows(for:)` filtering, hover delays, and panel sizing calculations through `panelSize` and `panelFrame` (lines 887-904).

## The Dual-Capture Pipeline

The service implements a prioritized capture strategy that maximizes image quality while maintaining broad compatibility across macOS versions and window states.

### Primary Capture: Window-Server API

The provider first attempts `captureViaWindowServer(_:)` (lines 241-254), calling the private `CGSHWCaptureWindowList` function. This returns a `CGImage` directly from the window server without screen-recording permissions, capturing minimized and off-screen windows instantly. However, this symbol is non-public and may fail for Stage Manager parked windows or become unavailable in future macOS releases.

### Fallback Capture: ScreenCaptureKit

When Window-Server capture returns nil, the provider falls back to the public ScreenCaptureKit framework (lines 151-168). It constructs an `SCShareableContent` filter for the specific window ID and invokes `SCScreenshotManager.captureImage`. This method requires explicit Screen Recording permission but reliably captures windows that the private API cannot, including those hidden in Stage Manager strips.

### Stage Manager Rectification

Stage Manager captures appear as perspective-transformed strips. The provider detects these using an alpha-grid test (`SwitcherSupport.alphaGrid`), then applies `CIPerspectiveCorrection` through `rectifiedStripCapture` (lines 258-320) to generate upright thumbnails suitable for the preview grid.

## Caching and Memory Management

To prevent redundant captures, `WindowPreviewProvider` maintains an in-memory cache with automatic pruning. The cache stores down-scaled bitmap copies (`bitmapCopy`, lines 327-345) and tracks access times via `lastTouched`. A system memory-pressure source triggers cache clearance (lines 554-576), ensuring the 64 MiB limit never risks app stability.

## Implementation Examples

```swift
// Initiate a preview session for a specific Dock item
DockPreviewService.shared.preview(someSwitcherItem)

// Retrieve a cached thumbnail synchronously
if let image = WindowPreviewProvider.shared.cachedPreview(for: windowID) {
    // Display in NSImageView
}

// Force refresh for all windows belonging to a process
let items = WindowEnumerator.listWindows(for: pid, maximumCount: 12)
WindowPreviewProvider.shared.refreshPreviews(for: items) { windowID, cgImage in
    // Update UI card with cgImage
}

```

## Summary

- The Dock preview service uses a dual-capture strategy prioritizing private Window-Server APIs over public ScreenCaptureKit.
- `WindowPreviewProvider` in [`Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift) handles all image acquisition and Stage Manager rectification.
- An LRU cache (48 entries/64 MiB) prevents redundant captures while responding to memory pressure events.
- `DockPreviewService` orchestrates mouse detection and panel presentation via `handleMouseMoved` and `beginSession`.
- Stage Manager windows require perspective correction via `CIPerspectiveCorrection` to appear as upright thumbnails.

## Frequently Asked Questions

### Why does the Dock preview service use two different capture methods?

The service prioritizes `CGSHWCaptureWindowList` for its speed and lack of permission requirements, but falls back to ScreenCaptureKit when windows are hidden, minimized in Stage Manager, or when the private symbol is unavailable. This hybrid approach ensures compatibility across macOS versions while minimizing user permission prompts.

### How does the service handle Stage Manager windows that appear as tilted strips?

When `SwitcherSupport.alphaGrid` detects a transformed capture, the provider invokes `rectifiedStripCapture` (lines 258-320) to apply a `CIPerspectiveCorrection` Core Image filter. This geometric transformation converts the angled Stage Manager thumbnail into a standard upright preview suitable for the Dock panel grid.

### What prevents the preview cache from consuming excessive memory?

The implementation enforces a 64 MiB or 48-entry limit using an LRU eviction policy. Additionally, the service registers with memory-pressure notifications to immediately clear the cache when macOS signals memory constraints, ensuring the utility remains lightweight even during intensive multitasking.

### Where is the hover detection logic implemented?

Mouse tracking occurs in [`DockPreviewService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/DockPreviewService.swift) through `handleMouseMoved` (lines 511-558), which performs hit-testing via `dockHit(at:)` to determine when the cursor enters a Dock icon. Upon confirmation, it schedules the hover timer before calling `beginSession(_:)` to initiate the capture pipeline.