What Is the DockPreview Service? A Deep Dive into Live Dock Previews on macOS

The DockPreview service is a macOS utility that transforms static Dock icons into interactive live-preview panels, enabling users to view window thumbnails, execute middle-click actions, and manage applications without switching workspaces.

The DockPreview service acts as the rendering engine behind Vorssaint's enhanced Dock experience in the vorssaint-utils repository. By bridging macOS Accessibility and Screen Recording APIs, this Swift-based service captures live window contents and generates contextual preview cards that appear when hovering over Dock items. Its architecture demonstrates how system-level permissions can be harmonized with fluid user interface interactions to create a productivity-focused workflow.

Core Responsibilities of the DockPreview Service

Live Window Capture and Thumbnail Generation

At its foundation, the DockPreview service reads real-time window metadata through the Accessibility API. When a user initiates a hover or middle-click gesture, the service queries the target application for its visible windows and generates thumbnail representations using Screen Recording capabilities.

This process requires two critical macOS permissions:

• Accessibility permission to enumerate windows belonging to specific applications
• Screen Recording permission to capture pixel data for live thumbnails

The service isolates these privileged operations within DockPreviewSupport.swift, ensuring that window enumeration and image capture occur only when explicitly authorized.

Dynamic Panel Geometry and Positioning

The DockPreview service calculates precise layout metrics to ensure preview panels appear correctly relative to the Dock's orientation. Whether the Dock rests at the bottom, left, or right edge of the screen, the service computes panel dimensions, hover corridors, and positioning offsets.

Key geometric calculations include:

• Panel sizing based on window count and screen constraints
• Hover corridors that maintain the preview session while the cursor travels from the Dock icon to the panel
• Orientation-aware anchoring that adjusts positioning for bottom, left, or right Dock configurations

These calculations respect user preferences for tile size, magnification settings, and auto-hide behavior stored in the DockPreview preferences.

Interaction Handling and Session Management

Beyond passive display, the DockPreview service manages complex interaction states. It interprets middle-click events to trigger specific actions, handles drag-to-reposition gestures for moving windows between spaces, and distinguishes between closing individual windows versus quitting entire applications.

The service maintains session state through the DockPreviewPanelView.swift component, which renders the SwiftUI interface and processes gesture recognizers. Session lifecycle management ensures that preview panels dismiss appropriately when the user clicks elsewhere or moves the cursor outside the interaction zone.

Permission-Aware Availability Checks

Before rendering any UI, the DockPreview service validates its operational readiness through the availability API. This system checks for required permissions and validates Dock accessibility, returning specific blocked reasons when prerequisites are missing.

The service recognizes three primary failure states:

• missingAccessibility when AXIsProcessTrusted returns false
• missingScreenRecording when screen capture authorization is denied
• dockUnavailable when the Dock process cannot be accessed

Architecture and Key Source Files

The DockPreview service spans multiple layers of the vorssaint-utils codebase, from low-level geometry utilities to high-level SwiftUI presentations.

DockPreviewSupport.swift contains the core business logic, including the availability check, panel frame calculations, and interaction handlers. This file implements the mathematical models for hover corridors and orientation-aware positioning.

DockPreviewPanelView.swift provides the visual layer, rendering thumbnail grids and action buttons using SwiftUI. This view coordinates with the support layer to update content dynamically as window states change.

DockClickSupport.swift operates as a complementary service that handles standard Dock clicks, ensuring that single-click minimize actions and middle-click preview triggers operate without conflict. These services share state to prevent race conditions during rapid user interactions.

Documentation for permission requirements resides in PERMISSIONS.md, while troubleshooting guidance for failed previews appears in TROUBLESHOOTING.md.

Working with the DockPreview Support API

Checking Service Availability

Before presenting a preview panel, verify that the service can operate using the availability checker:

let enabled = true // User preference toggle
let hasAccessibility = AXIsProcessTrusted()
let hasScreenRecording = ScreenRecorder.isAuthorized()

let preferences = DockPreviewPreferences.sanitized(
    orientation: nil,
    autohide: nil,
    tileSize: nil,
    magnification: nil,
    magnifiedTileSize: nil
)

let availability = DockPreviewSupport.availability(
    enabled: enabled,
    hasAccessibility: hasAccessibility,
    hasScreenRecording: hasScreenRecording,
    preferences: preferences
)

guard availability.canRun else {
    if let reason = availability.blockedReason {
        print("Preview blocked: \(reason.rawValue)")
    }
    return
}

Calculating Panel Geometry

Compute the preview panel's position relative to a Dock icon using the geometry helpers:

let iconRect = CGRect(x: 200, y: 0, width: 64, height: 64)
let screenFrame = NSScreen.main!.visibleFrame

let panelSize = DockPreviewSupport.panelSize(
    itemCount: 3,
    screenVisibleFrame: screenFrame,
    isPinned: false
)

let panelRect = DockPreviewSupport.panelFrame(
    anchor: iconRect,
    panelSize: panelSize,
    screenVisibleFrame: screenFrame,
    orientation: .bottom
)

Executing Window Actions

Handle close actions with the appropriate quit behavior based on user preferences:

let shouldQuitApp = false // Preference: close window vs quit application
let action = DockPreviewSupport.closeAction(quitAppOnClose: shouldQuitApp)

DockPreviewSupport.performCloseAction(
    quitAppOnClose: shouldQuitApp,
    requestQuit: { 
        // Return true if app quit succeeds
        NSRunningApplication(processIdentifier: pid)?.terminate() 
        return true 
    },
    closeWindow: {
        // Execute window close via Accessibility API
        AXUIElementPerformAction(windowElement, kAXPressAction)
    }
)

Handling Permissions and Error States

The DockPreview service implements graceful degradation when macOS permissions are absent. When availability.blockedReason returns .missingScreenRecording, the application should direct users to System Settings to enable screen capture for the Vorssaint process.

For Accessibility permission failures, the service typically triggers the standard macOS permission prompt. The TROUBLESHOOTING.md document outlines specific steps for resetting the Accessibility database if permission states become desynchronized.

The service also detects when the Dock process is unreachable, which occurs during macOS updates or if the Dock crashes. In these instances, the dockUnavailable reason triggers a retry mechanism that attempts to re-establish connection when the Dock process respawns.

Summary

• The DockPreview service generates live window thumbnails by integrating macOS Accessibility and Screen Recording APIs.
• Core geometry calculations in DockPreviewSupport.swift handle panel positioning across all Dock orientations (bottom, left, right).
• The service requires explicit user permissions and provides detailed blocked reasons (missingAccessibility, missingScreenRecording, dockUnavailable) when unavailable.
• Interactive features include middle-click actions, drag-to-reposition, and contextual close versus quit behaviors.
• Architecture separates concerns between geometric calculations (DockPreviewSupport), visual rendering (DockPreviewPanelView), and click handling (DockClickSupport).

Frequently Asked Questions

What permissions does the DockPreview service require?

The service requires two macOS permissions: Accessibility to enumerate application windows and Screen Recording to capture thumbnail images. These permissions are checked via AXIsProcessTrusted() and ScreenRecorder.isAuthorized() before the service initializes any preview panels. According to PERMISSIONS.md, users must explicitly grant these in System Settings under Privacy & Security.

How does the service position preview panels relative to the Dock?

The service calculates positioning using DockPreviewSupport.panelFrame, which accepts the Dock icon's anchor rectangle, desired panel size, screen visible frame, and orientation enum (.bottom, .left, or .right). The algorithm accounts for the hover corridor—a transitional zone that keeps the preview visible while the cursor moves from the Dock icon to the panel—preventing accidental dismissal during normal usage.

What happens when required permissions are missing?

When permissions are absent, DockPreviewSupport.availability returns canRun: false with a specific blockedReason enum case. The service distinguishes between missingAccessibility and missingScreenRecording, allowing the UI to present targeted instructions. If the Dock process is unreachable, it returns dockUnavailable, typically triggering a background retry until the connection restores.

Can the DockPreview service handle different Dock configurations?

Yes, the service adapts to user-specific Dock configurations including auto-hide behavior, tile size, magnification settings, and orientation. The DockPreviewPreferences.sanitized method normalizes these preferences, ensuring that panel calculations respect the actual Dock geometry whether positioned at the screen's bottom, left, or right edge.

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