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

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 (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 (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 (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

// 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 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 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.

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