# Vorssaint App Switcher Window Thumbnail Capture Mechanism Explained

> Discover how Vorssaint app switcher captures window thumbnails using ScreenCaptureKit. Learn about caching and fallback mechanisms for seamless app switching.

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

---

**The Vorssaint app switcher captures window thumbnails using ScreenCaptureKit’s `SCWindow.captureThumbnail(maxEdge:)` method, caches them in a 160 MiB LRU-backed `NSCache`, and renders them through `SwitcherGridCard` with automatic fallback to application icons when capture fails.**

The `vorssaint/vorssaint-utils` repository implements a high-performance window preview pipeline that balances visual fidelity with memory constraints. The Vorssaint app switcher window thumbnail capture mechanism relies on three coordinated components—window enumeration, image caching, and reactive UI rendering—to deliver fluid previews without blocking the main thread.

## How WindowEnumerator Discovers Windows

The pipeline begins in [`Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowEnumerator.swift), where the `WindowEnumerator` class queries macOS ScreenCaptureKit to list every `SCWindow` object visible to the current user session. It filters out system‑level windows that cannot be previewed (such as menu bars and hidden daemons) and constructs an array of `WindowItem` structs. Each `WindowItem` carries a persistent identifier (`window.id.uuidString`) required later for cache lookups, along with metadata such as window title and owning application.

## Thumbnail Capture and Caching Strategy

Once windows are enumerated, [`Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/WindowPreviewProvider.swift) orchestrates the actual capture and storage logic.

### ScreenCaptureKit Integration

The provider invokes `SCWindow.captureThumbnail(maxEdge: 512)` for each visible window. The `maxEdge` parameter defaults to **512 points** (1024 pixels on Retina displays), ensuring thumbnails remain crisp while minimizing memory footprint. The raw `CGImage` returned by ScreenCaptureKit is immediately wrapped in an `NSImage` and passed to the caching layer.

### LRU Cache Implementation

`WindowPreviewProvider` maintains an **in‑memory NSCache** configured with a `totalCostLimit` of **160 MiB**. The cache uses the window’s UUID string as its key and calculates each entry’s cost as `bytesPerRow × height`, preventing unbounded growth. When the cache exceeds its budget, the least‑recently‑used thumbnail is evicted automatically. This design guarantees that the switcher never holds stale images for inactive windows while keeping the most recently viewed windows instantly accessible.

## Rendering the Thumbnail Grid

[`Sources/Vorssaint/UI/Switcher/SwitcherView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Switcher/SwitcherView.swift) consumes the cached images via `SwitcherGridCard`. Each card draws the thumbnail at dimensions defined in [`Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Switcher/SwitcherSupport.swift) (`thumbnailWidth` and `thumbnailHeight`), applying rounded corners and padding. If `WindowPreviewProvider` reports a missing or failed capture, the card falls back to the application’s icon (`fallbackIconSize`) so the grid never shows empty placeholders. The view updates reactively when the provider’s `onUpdate` closure fires, triggering a SwiftUI diff and re‑render only for changed windows.

## Practical Code Examples

### 1. Requesting a Thumbnail Manually

You can replicate the provider’s capture logic for custom UI components:

```swift
import ScreenCaptureKit
import AppKit

func captureWindowThumbnail(window: SCWindow) async -> NSImage? {
    // Capture at 512pt (1024px @2x) resolution
    guard let cgImage = await window.captureThumbnail(maxEdge: 512) else {
        return nil
    }
    return NSImage(cgImage: cgImage, size: .zero)
}

```

*This mirrors the internal call made by `WindowPreviewProvider.refreshThumbnails()`.*

### 2. Observing Thumbnail Updates in SwiftUI

Integrate the provider into a view to receive automatic updates:

```swift
struct WindowGrid: View {
    @StateObject private var provider = WindowPreviewProvider()

    var body: some View {
        LazyVGrid(columns: [GridItem(.adaptive(minimum: 200))]) {
            ForEach(provider.items) { item in
                SwitcherGridCard(item: item)
            }
        }
        .onAppear { provider.startUpdating() }
    }
}

```

*`startUpdating()` begins the enumeration‑to‑capture cycle described above.*

### 3. Accessing the Cache Directly

For advanced use cases, you can query the cache without triggering a new capture:

```swift
let cacheKey = window.id.uuidString
if let cachedImage = WindowPreviewProvider.thumbnailCache.object(forKey: cacheKey) {
    // Use the cached NSImage immediately
    imageView.image = cachedImage
}

```

*The cache key matches the window’s persistent identifier assigned during enumeration.*

## Summary

- **WindowEnumeration**: [`WindowEnumerator.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowEnumerator.swift) uses ScreenCaptureKit to list valid `SCWindow` objects and expose them as `WindowItem` structs.
- **Capture & Cache**: [`WindowPreviewProvider.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/WindowPreviewProvider.swift) calls `captureThumbnail(maxEdge: 512)`, wraps the result in an `NSImage`, and stores it in a 160 MiB `NSCache` keyed by window UUID.
- **UI Rendering**: [`SwitcherView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SwitcherView.swift) and `SwitcherGridCard` display cached thumbnails at sizes defined in [`SwitcherSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SwitcherSupport.swift), falling back to application icons when capture fails.
- **Memory Safety**: The LRU cache evicts least‑recently‑used items automatically, ensuring the switcher remains responsive even with dozens of open windows.

## Frequently Asked Questions

### What API does Vorssaint use to capture window thumbnails?

Vorssaint uses **ScreenCaptureKit’s** `SCWindow.captureThumbnail(maxEdge:)` method, available on macOS 12.3 and later. This API provides hardware‑accelerated captures without requiring window server injection.

### How does the switcher prevent excessive memory usage?

The mechanism enforces a hard **160 MiB limit** via `NSCache.totalCostLimit`. Each thumbnail’s cost is calculated as `bytesPerRow × height`, and the cache automatically evicts the oldest entries when this threshold is exceeded.

### What happens when a window cannot be captured?

If `captureThumbnail(maxEdge:)` returns `nil`—for example, due to security restrictions or minimized windows—the `SwitcherGridCard` falls back to the owning application’s icon. The UI remains populated; users see the icon instead of a blank space.

### Why is the thumbnail size fixed at 512 points?

The **512‑point edge** (1024 pixels on Retina) provides sufficient resolution for high‑DPI displays while keeping the uncompressed image under 2 MiB per thumbnail. This size balances visual clarity with the 160 MiB cache budget, allowing roughly 80 high‑resolution previews simultaneously.