### KeybindHelper Initialization Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/KeybindHelper.md

Example of how to initialize KeybindHelper with a coordinator instance.

```swift
let keybindHelper = KeybindHelper(previewCoordinator: coordinator)
```

--------------------------------

### Show Onboarding Window

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Displays the first-time setup (onboarding) window on a specified screen.

```swift
private func showOnboardingWindow(on screen: NSScreen)
```

--------------------------------

### Configuration.md Feature Categories Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Lists example feature categories used for organizing configuration settings.

```text
- Preview Window Configuration
- Window Capture and Cache
- Dock Preview Settings
- Window Switcher Configuration
- Window Filtering and Sorting
- Widgets
- UI and Appearance
- Developer and Debug
```

--------------------------------

### DockObserver Initialization Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/DockObserver.md

Demonstrates how to create an instance of DockObserver with a SharedPreviewWindowCoordinator.

```swift
let coordinator = SharedPreviewWindowCoordinator()
let observer = DockObserver(previewCoordinator: coordinator)
```

--------------------------------

### Code Example Guidelines (Swift)

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Specifies conventions for writing code examples in Swift, emphasizing clarity and practical usage.

```swift
// Shows actual usage
// Uses real method names and types
// Includes error handling where relevant
// Swift syntax highlighting
```

--------------------------------

### Project File Organization Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Illustrates the directory structure and key markdown files within the project for documentation.

```text
output/
├── README.md                    # Start here - overview and how to use
├── INDEX.md                     # Quick links and common tasks
├── STRUCTURE.md                 # This file
├── configuration.md             # All 238+ configuration keys
├── types.md                     # Type definitions and enums
└── api-reference/               # Detailed API documentation
    ├── WindowUtil.md            # Window management (40+ methods)
    ├── WindowInfo.md            # Window data structure
    ├── WindowSeeder.md          # Cold-start initialization
    ├── SharedPreviewWindowCoordinator.md  # Preview management
    ├── DockObserver.md          # Dock interaction monitoring
    ├── KeybindHelper.md         # Keyboard event handling
    ├── AppDelegate.md           # App lifecycle
    ├── UpdaterState.md          # Update management
    └── MediaRemoteService.md    # Media control
```

--------------------------------

### Example Usage of Show Preview

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Illustrates how to fetch active windows for an application and then display a preview using the showPreview method.

```swift
let windows = try await WindowUtil.getActiveWindows(of: app)
coordinator.showPreview(for: app, at: dockItemPosition, with: windows)
```

--------------------------------

### Example Usage of Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Demonstrates how to create and initialize a SharedPreviewWindowCoordinator. The instance is automatically set as active upon creation.

```swift
let coordinator = SharedPreviewWindowCoordinator()
// Coordinator is now active and ready to display previews
```

--------------------------------

### KeybindHelper Configuration Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/KeybindHelper.md

Demonstrates how KeybindHelper respects global settings for keybind configurations, such as the cycle key and vim motions.

```swift
// In settings
@Default(.cmdTabCycleKey) var cycleKey = UInt16(kVK_ANSI_A)
@Default(.enableVimMotions) var vimMotions = false

// KeybindHelper automatically respects these
```

--------------------------------

### play

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/MediaRemoteService.md

Starts media playback.

```APIDOC
## play

Starts playback.

### Method

`func play()`
```

--------------------------------

### Switch to Beta Update Channel

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Example of how to change the update channel to 'beta' to receive pre-release versions.

```swift
updaterState.updateChannel = .beta
```

--------------------------------

### Types.md Type Categories Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Lists example type categories used for organizing type definitions.

```text
- Core Window Types
- Application Types
- Preview Types
- Media Types
- Update Types
- Configuration Enums
```

--------------------------------

### UpdaterState Basic Setup

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Initializes an UpdaterState instance and assigns the Sparkle updater. This is a fundamental step for using the UpdaterState class.

```swift
let updaterState = UpdaterState()
updaterState.updater = sparkleUpdater
```

--------------------------------

### Setup Menu Bar

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Creates and displays the application's menu bar icon and status menu. This is called when the menu bar icon feature is enabled.

```swift
func setupMenuBar()
```

--------------------------------

### API Reference File Structure Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Defines the standard layout for individual API reference markdown files.

```text
# ClassName

Brief overview

Source: path/to/Source.swift

## Overview
  - What the class does
  - Key responsibilities
  - Main use cases

## Class Definition
  - Exact Swift declaration

## Static/Instance Properties
  - Property name and type
  - Description

## Types (nested)
  - Enums, structs, etc.

## Methods (by category)
  - Static methods
  - Instance methods
  - Initializers

## Examples
  - Typical usage patterns
```

--------------------------------

### Manually Check for Updates

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Example of how to call the `checkForUpdates` method to manually initiate an update check.

```swift
updaterState.checkForUpdates()
```

--------------------------------

### SPUUpdaterDelegate: updaterDidFinishSetup

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Delegate method called after the Sparkle updater has finished its setup process. No specific action is required within this method.

```swift
func updaterDidFinishSetup(_ updater: SPUUpdater)
```

--------------------------------

### Get Current Application Version

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Demonstrates how to access the current application version managed by UpdaterState.

```swift
print("Current: (updaterState.currentVersion)")
```

--------------------------------

### Get DockDoor Help via osascript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Fetches the built-in help information for DockDoor using `osascript`. This command is useful for understanding available commands and their syntax.

```osascript
osascript -e 'tell application "DockDoor" to get help'
```

--------------------------------

### Non-Example Code Guidelines (Swift)

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/STRUCTURE.md

Defines conventions for code snippets that are not full examples, focusing on type information.

```swift
// Shows type information
// Parameter and return types explicit
```

--------------------------------

### activate

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/MediaRemoteService.md

Starts listening to media remote events and tracking playback state. This method must be called before media controls will function.

```APIDOC
## activate

Starts listening to media remote events and tracking playback state. Must be called before media controls will work.

### Method

`func activate()`

**Example:**
```swift
MediaRemoteService.shared.activate()
```
```

--------------------------------

### Karabiner-Elements Configuration for DockDoor Switcher

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Example configuration for Karabiner-Elements to trigger the DockDoor Window Switcher using a custom key combination (Option+Tab). This bypasses potential issues with direct key simulation.

```json
{
    "type": "basic",
    "from": { "key_code": "tab", "modifiers": { "mandatory": ["option"] } },
    "to": [
        { "shell_command": "osascript -e 'tell application \"DockDoor\" to show switcher'" }
    ]
}
```

--------------------------------

### Toggle Automatic Checks Example

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Demonstrates how to call the `toggleAutomaticChecks` method to switch the automatic update checking setting.

```swift
updaterState.toggleAutomaticChecks()
```

--------------------------------

### Get DockDoor Help with AppleScript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Retrieve a list of available commands for DockDoor using AppleScript. This is useful for discovering supported actions.

```applescript
tell application "DockDoor" to get help
```

--------------------------------

### getAllWindowsOfAllApps

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Retrieves all cached windows across all running applications. This is useful for getting a comprehensive list of visible windows.

```APIDOC
## getAllWindowsOfAllApps

### Description
Returns all cached windows across all running applications.

### Method
static func

### Returns
`[WindowInfo]` — Array of all cached windows

### Example
```swift
let allWindows = WindowUtil.getAllWindowsOfAllApps()
print("Total windows: \(allWindows.count)")
```
```

--------------------------------

### Get All Windows Across All Applications

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/INDEX.md

Retrieves a comprehensive list of all currently open windows across all running applications on the system. This is useful for a complete system overview.

```swift
// Get all windows across all apps
let allWindows = WindowUtil.getAllWindowsOfAllApps()
```

--------------------------------

### Get Active Window Info

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Retrieves information about the frontmost window, including its properties and a cached preview image. This command is useful for scripting and automation.

```osascript
osascript -e 'tell application "DockDoor" to get active window'
```

--------------------------------

### Get Cached Windows Immediately

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/INDEX.md

Retrieves a list of windows that are currently stored in the cache for a given process identifier. This provides immediate access to previously discovered window information.

```swift
// Get cached windows immediately
let cachedWindows = WindowUtil.readCachedWindows(for: pid)
```

--------------------------------

### Get Active Windows for an Application

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/INDEX.md

Fetches the currently active windows associated with a specific running application. Requires the application's process identifier.

```swift
// Get active windows for an application
let app = NSRunningApplication(processIdentifier: pid)!
let windows = try await WindowUtil.getActiveWindows(of: app)
```

--------------------------------

### UpdaterState Manual Update Check

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Provides an example of manually triggering an update check via an IBAction and responding to status changes using .onReceive in SwiftUI. This is useful for user-initiated checks.

```swift
@IBAction func checkForUpdatesClicked(_ sender: NSButton) {
    updaterState.checkForUpdates()
}

// In UI, respond to updateStatus changes
.onReceive(updaterState.$updateStatus) { status in
    switch status {
    case .available:
        // Show update prompt
        break
    case .error(let message):
        // Show error alert
        break
    default:
        break
    }
}
```

--------------------------------

### Get All Windows as JSON via osascript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Retrieves all windows managed by DockDoor in JSON format using `osascript`. This is useful for parsing window data in scripts.

```osascript
osascript -e 'tell application "DockDoor" to list windows'
```

--------------------------------

### Get Active Windows for an Application

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Fetches active windows for a given application using screen capture and accessibility APIs. Use `WindowFetchContext` to control sorting and filtering. The `ignoreSingleWindowFilter` parameter can be used to include an optimization for single-window applications.

```swift
static func getActiveWindows(
    of app: NSRunningApplication,
    context: WindowFetchContext = .dockPreview,
    ignoreSingleWindowFilter: Bool = false
) async throws -> [WindowInfo]
```

```swift
let app = NSRunningApplication(processIdentifier: pid)!
let windows = try await WindowUtil.getActiveWindows(of: app, context: .dockPreview)
for window in windows {
    print("Window: \(window.windowName ?? "Unknown")")
}
```

--------------------------------

### Handle First-Time Launch

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Manages the initial launch of the application, including showing the onboarding window and potentially a cinematic intro.

```swift
private func handleFirstTimeLaunch()
```

--------------------------------

### Get Focused Window for Frontmost App

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Gets the focused window of the currently active application. Returns nil if no focused window is found.

```swift
static func getFocusedWindowForFrontmostApp() -> WindowInfo?
```

```swift
if let focusedWindow = WindowUtil.getFocusedWindowForFrontmostApp() {
    print("Focused: \(focusedWindow.windowName ?? "Unknown")")
}
```

--------------------------------

### Initialize and Access AppDelegate

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Shows how to create an instance of AppDelegate, set it as the application's delegate, and access it from anywhere within the application.

```swift
let appDelegate = AppDelegate()
NSApplication.shared.delegate = appDelegate

// Access from anywhere
let delegate = NSApplication.shared.delegate as? AppDelegate
delegate?.openSettingsWindow(nil)
```

--------------------------------

### Show App Preview via osascript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Demonstrates how to show a preview for a specific application using the `osascript` command in the terminal. The app name should be enclosed in quotes.

```osascript
osascript -e 'tell application "DockDoor" to show preview "Finder"'
```

--------------------------------

### Show Preview Method

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Displays a preview for a given application, specifying its screen position and the windows to include.

```swift
func showPreview(for app: NSRunningApplication, at position: CGPoint, with windows: [WindowInfo])
```

--------------------------------

### getFocusedWindowForFrontmostApp

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Gets the focused window of the frontmost (active) application. Returns nil if no focused window is found.

```APIDOC
## getFocusedWindowForFrontmostApp

### Description
Gets the focused window of the frontmost (active) application.

### Method
static func

### Returns
`WindowInfo?` — The focused window, or nil if not found

### Example
```swift
if let focusedWindow = WindowUtil.getFocusedWindowForFrontmostApp() {
    print("Focused: \(focusedWindow.windowName ?? \"Unknown\")")
}
```
```

--------------------------------

### Initialize and Use DockObserver

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/DockObserver.md

Demonstrates how to initialize a DockObserver with a SharedPreviewWindowCoordinator and how to reset it. The observer becomes active upon initialization, triggering previews on hover and actions on scroll.

```swift
// Initialize observer
let coordinator = SharedPreviewWindowCoordinator()
let dockObserver = DockObserver(previewCoordinator: coordinator)

// Observer is now active and monitoring dock interactions
// When user hovers over dock items, previews appear
// When user scrolls on dock, configured actions trigger

// On app wake or accessibility restoration
dockObserver.reset()
```

--------------------------------

### Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Initializes the UpdaterState, loading necessary data and preferences.

```APIDOC
### init

```swift
override init()
```

Initializes UpdaterState:
1. Loads current version from app bundle
2. Restores previously saved update channel preference
3. Calls parent init

**Saved preferences:**
- Update channel is saved to UserDefaults under key "updateChannel"
```

--------------------------------

### Show Previews

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/INDEX.md

Initiates the display of a preview for an application. This requires an active window coordinator and a list of the application's active windows.

```swift
let coordinator = SharedPreviewWindowCoordinator()
let windows = try await WindowUtil.getActiveWindows(of: app)
coordinator.showPreview(for: app, at: dockIconPosition, with: windows)
```

--------------------------------

### Show Full Preview Method

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Displays a full-screen preview of a specific window, usually triggered by user interaction.

```swift
func showFullPreview(for window: WindowInfo, at position: CGPoint)
```

--------------------------------

### showPreview

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Displays a preview for a given application, specifying its position and the windows to be shown. This is a key method for initiating the preview display.

```APIDOC
## showPreview

### Description
Displays a preview for an application with the given windows.

### Signature
```swift
func showPreview(for app: NSRunningApplication, at position: CGPoint, with windows: [WindowInfo])
```

### Parameters
#### Path Parameters
- **app** (`NSRunningApplication`) - The application to preview.
- **position** (`CGPoint`) - The screen position for the preview.
- **windows** (`[WindowInfo]`) - A list of windows to display in the preview.

### Example
```swift
let windows = try await WindowUtil.getActiveWindows(of: app)
coordinator.showPreview(for: app, at: dockItemPosition, with: windows)
```
```

--------------------------------

### Preview Commands

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Commands to manage dock-style app previews and the window switcher.

```APIDOC
## Preview Commands

### Description
Manage dock-style previews for applications and trigger the Window Switcher.

### Commands
- `show preview "App"` - Show dock-style preview for an app
- `show preview "id" by "bundle"` - Look up app by bundle ID
- `show preview "123" by "pid"` - Look up app by process ID
- `hide preview` - Hide the current preview window
- `show switcher` - Open the Window Switcher

### Optional Parameters
- `at "x,y"` - Position the preview at specific coordinates
- `dock frame "x,y,w,h"` - Position relative to a dock icon rect
- `with delay true` - Use the configured hover delay
```

--------------------------------

### Create WindowInfo for Windowless App

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Use this static method to create a WindowInfo entry for an application that currently has no visible windows.

```swift
static func windowlessEntry(for app: NSRunningApplication) -> WindowInfo
```

```swift
let windowlessEntry = WindowInfo.windowlessEntry(for: app)
```

--------------------------------

### Read and Write Configuration Values in Code

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/configuration.md

Demonstrates how to read and write configuration values using the Defaults API. This is useful for dynamically adjusting settings within your application's logic.

```swift
import Defaults

// Read a value
let previewWidth = Defaults[.previewWidth]

// Write a value
Defaults[.previewWidth] = 400

// Observe changes
Defaults.publisher(.previewWidth)
    .sink {
        newWidth in
        print("Width changed to: \(newWidth)")
    }
```

--------------------------------

### Get All Windows for an App

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/README.md

Retrieves all active windows associated with a specific running application. This function is part of the WindowUtil API for window discovery.

```swift
let app = NSRunningApplication(processIdentifier: pid)!
let windows = try await WindowUtil.getActiveWindows(of: app)
```

--------------------------------

### KeybindHelper Usage Pattern

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/KeybindHelper.md

Illustrates a typical usage pattern for KeybindHelper, including initialization, monitoring, and resetting.

```swift
let coordinator = SharedPreviewWindowCoordinator()
let keybindHelper = KeybindHelper(previewCoordinator: coordinator)

// Keybind helper now monitors keyboard
// When user presses configured keys, switcher shows/hides
// When user navigates, KeybindHelper updates selection
// When user presses action key, window action executes

// On system wake
keybindHelper.reset()
```

--------------------------------

### currentVersion Property

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

A published property holding the current application version, typically read from the app bundle. Used for displaying the installed version.

```swift
@Published var currentVersion: String
```

--------------------------------

### Run Window Seeding Process

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowSeeder.md

Executes the window seeding process asynchronously. This method discovers all windows from running applications and initializes the live Accessibility tracking system. It returns immediately, running in the background.

```swift
func run()
```

```swift
let seeder = WindowSeeder()
seeder.run()
// Windows are now cached and being tracked
```

--------------------------------

### Seeking to a Specific Time

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/MediaRemoteService.md

Control playback position by seeking to a desired time in seconds. Examples show seeking to 45 seconds and 1 minute.

```swift
// Seek to 45 seconds
MediaRemoteService.shared.seek(to: 45.0)

// Seek to 1 minute
MediaRemoteService.shared.seek(to: 60.0)
```

--------------------------------

### WindowInfo Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Initializes a new WindowInfo instance with detailed parameters, including window properties, application information, accessibility elements, and state flags. Optional parameters allow for flexible initialization.

```swift
init(
    windowProvider: WindowPropertiesProviding,
    app: NSRunningApplication,
    ownerApp: NSRunningApplication? = nil,
    image: CGImage?,
    axElement: AXUIElement,
    appAxElement: AXUIElement,
    closeButton: AXUIElement?,
    lastAccessedTime: Date,
    creationTime: Date? = nil,
    imageCapturedTime: Date? = nil,
    spaceID: Int? = nil,
    screenIdentifier: String? = nil,
    isMinimized: Bool,
    isHidden: Bool
)
```

--------------------------------

### Show Preview Window

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/README.md

Initiates a preview window for an application. Requires an instance of SharedPreviewWindowCoordinator.

```swift
let coordinator = SharedPreviewWindowCoordinator()
coordinator.showPreview(for: app, at: position, with: windows)
```

--------------------------------

### DockObserver Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/DockObserver.md

Initializes a new DockObserver instance. This is the primary way to create an observer, requiring a coordinator for managing preview windows.

```APIDOC
## init

Initializes a DockObserver with a preview coordinator.

### Parameters
#### Path Parameters
- `previewCoordinator` (SharedPreviewWindowCoordinator) - Required - Coordinator for managing previews

### Request Example
```swift
let coordinator = SharedPreviewWindowCoordinator()
let observer = DockObserver(previewCoordinator: coordinator)
```
```

--------------------------------

### WindowSeeder Initialization

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowSeeder.md

Creates a new WindowSeeder instance. This instance is then ready to run the window seeding process.

```APIDOC
## init

### Description
Creates a new WindowSeeder instance. Ready to run the seeding process.

### Signature
```swift
init()
```
```

--------------------------------

### bringToFront

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Brings the window to the front of the window stack and makes it the active, focused window.

```APIDOC
## bringToFront

### Description
Brings the window to the front and focuses it.

### Method
`bringToFront()`

### Example
```swift
window.bringToFront()
```
```

--------------------------------

### Coordinator Lifecycle

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Illustrates the lifecycle of the SharedPreviewWindowCoordinator, from initialization to deinitialization, including key methods for showing, updating, and hiding the preview.

```plaintext
init() 
  → activeInstance = self
  
showPreview()
  → Creates/updates preview panel
  → Displays windows/content
  → Shows with animation
  
updatePreview()
  → Updates displayed content
  
hidePreview()
  → Fades out with animation
  → Clears currentlyDisplayedPID
  
deinit
  → activeInstance = nil
  → Cleanup resources
```

--------------------------------

### showFullPreview

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Displays a full-screen preview of a single, specified window. This is often triggered by user interactions like clicking on a specific window in a list.

```APIDOC
## showFullPreview

### Description
Shows a full-screen preview of a single window, typically triggered by specific interactions.

### Signature
```swift
func showFullPreview(for window: WindowInfo, at position: CGPoint)
```

### Parameters
#### Path Parameters
- **window** (`WindowInfo`) - The specific window to display in full preview.
- **position** (`CGPoint`) - The desired screen position for the full preview.

### Example
```swift
coordinator.showFullPreview(for: selectedWindowInfo, at: screenCenter)
```
```

--------------------------------

### Perform Window Actions

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/INDEX.md

Demonstrates how to perform actions like closing a window and handling the results. The `perform` method returns a status indicating the outcome of the action.

```swift
let result = WindowAction.close.perform(on: window)

switch result {
case .dismissed:
    print("Preview dismissed")
case .windowRemoved:
    print("Window closed")
case .appWindowsRemoved(let pid):
    print("App \(pid) quit")
case .windowUpdated(let updated):
    print("Window updated: \(updated)")
case .noChange:
    print("No change")
}
```

--------------------------------

### Show App Preview with Position

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Displays a dock-style preview for a specified app at given coordinates. Ensure the app name is correctly quoted.

```applescript
tell application "DockDoor" to show preview "Safari" at "500,400"
```

--------------------------------

### KeybindHelper Initialization

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/KeybindHelper.md

Initializes the KeybindHelper with a SharedPreviewWindowCoordinator to manage preview windows and handle key events for the window switcher.

```APIDOC
## KeybindHelper Initialization

### Description
Initializes the keybind helper with a preview coordinator.

### Method Signature
```swift
init(previewCoordinator: SharedPreviewWindowCoordinator)
```

### Parameters
#### Path Parameters
- **previewCoordinator** (SharedPreviewWindowCoordinator) - Required - Coordinator for preview windows

### Request Example
```swift
let coordinator = SharedPreviewWindowCoordinator()
let keybindHelper = KeybindHelper(previewCoordinator: coordinator)
```
```

--------------------------------

### Bring Window to Front

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Brings the specified window to the front of the window stack and gives it focus.

```swift
func bringToFront()
```

```swift
window.bringToFront()
```

--------------------------------

### Monitor Configuration Changes

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/README.md

Listens for changes to a default configuration value, such as preview width. Uses Combine for reactive updates.

```swift
@Default(.previewWidth) var width = 300

Defaults.publisher(.previewWidth).sink {
    newWidth in
    print("Width: \(newWidth)")
}
```

--------------------------------

### AppDelegate Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Initializes the AppDelegate, setting up the updater and its state. This is called during application startup.

```swift
override init()
```

--------------------------------

### WindowSeeder.run()

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowSeeder.md

Executes the window seeding process asynchronously. This method discovers all windows from running applications, caches their information, and initializes the live Accessibility (AX) element tracking system.

```APIDOC
## run

### Description
Executes the window seeding process asynchronously. Discovers all windows from running applications and initializes the live tracker.

### Behavior
1. Gets list of all running applications
2. For each application, discovers its windows
3. Caches window information
4. Activates live AX tracking for future window changes
5. Returns immediately (runs in background)

### Signature
```swift
func run()
```

### Example
```swift
let seeder = WindowSeeder()
seeder.run()
// Windows are now cached and being tracked
```
```

--------------------------------

### Open Settings Window

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Programmatically opens the application's settings window. This method activates the application and brings the settings window to the foreground.

```swift
@objc func openSettingsWindow(_ sender: Any?)
```

```swift
appDelegate.openSettingsWindow(nil)
```

--------------------------------

### Application Did Finish Launching

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Called after the application has finished launching. This method orchestrates all initialization tasks for the application.

```swift
func applicationDidFinishLaunching(_ aNotification: Notification)
```

--------------------------------

### Access Configuration in SwiftUI

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/configuration.md

Shows how to bind SwiftUI views to configuration values using the @Default property wrapper. This allows for reactive updates in your UI when settings change.

```swift
@Default(.previewWidth) var previewWidth

var body: some View {
    Text("Width: \(previewWidth)")
        .onReceive(Defaults.publisher(.previewWidth)) {
            newWidth in
            previewWidth = newWidth
        }
}
```

--------------------------------

### Update Preview Method

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Updates the content of the currently visible preview window with a new list of windows.

```swift
func updatePreview(with windows: [WindowInfo])
```

--------------------------------

### List All Running Apps

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Retrieves a JSON list of all currently running applications and their associated window counts. This command is helpful for system monitoring scripts.

```osascript
osascript -e 'tell application "DockDoor" to list apps'
```

--------------------------------

### List Windows for Specific App

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Returns a JSON array of all windows belonging to a specified application. This is useful for scripting and parsing window data.

```osascript
osascript -e 'tell application "DockDoor" to list windows "Safari"'
```

--------------------------------

### WindowSeeder Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowSeeder.md

Creates a new WindowSeeder instance. This initializer prepares the seeder to run the seeding process.

```swift
init()
```

--------------------------------

### Window Actions

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Commands to manipulate window state, including focus, size, and position.

```APIDOC
## Window Actions

### Description
Perform actions on windows identified by a window ID or the string "active".

### Commands
- `focus window "id"` - Bring window to front
- `minimize window "id"` - Minimize / unminimize
- `close window "id"` - Close the window
- `maximize window "id"` - Fill the screen
- `hide window "id"` - Hide / unhide the app
- `toggle fullscreen "id"` - Toggle fullscreen mode
- `center window "id"` - Center on screen
- `position window "id" to "position"` - Snap to screen region (left, right, top, bottom, etc.)
```

--------------------------------

### fillBottomHalf

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the bottom half of the screen.

```APIDOC
## fillBottomHalf

### Description
Fills the window to occupy the bottom half of the screen.

### Method
`fillBottomHalf()`
```

--------------------------------

### Instance Methods

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/UpdaterState.md

Methods for directly interacting with the update process, such as initiating checks or toggling automatic updates.

```APIDOC
### checkForUpdates

```swift
func checkForUpdates()
```

Triggers a manual check for updates. Sets status to `.checking` and delegates to Sparkle updater.

**Example:**
```swift
updaterState.checkForUpdates()
```

### toggleAutomaticChecks

```swift
func toggleAutomaticChecks()
```

Toggles automatic background update checking on/off and updates the published property.

**Example:**
```swift
updaterState.toggleAutomaticChecks()
```
```

--------------------------------

### Restart Application

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Restarts the application by launching a new instance and then quitting the current one.

```swift
func restartApp()
```

--------------------------------

### WindowSeeder Class Definition

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowSeeder.md

Defines the WindowSeeder class, which handles one-time cold-start initialization of the window discovery system.

```swift
final class WindowSeeder
```

--------------------------------

### fillTopHalf

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the top half of the screen.

```APIDOC
## fillTopHalf

### Description
Fills the window to occupy the top half of the screen.

### Method
`fillTopHalf()`
```

--------------------------------

### Querying Windows & Apps

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Commands that return JSON data for application and window status.

```APIDOC
## Querying Windows & Apps

### Description
Retrieve information about running applications and windows in JSON format.

### Commands
- `list apps` - All running apps with window counts
- `list windows` - All windows across all apps
- `list windows "AppName"` - Windows for a specific app
- `get active window` - Info about the frontmost window
- `get window "id"` - Window info with cached preview image (base64)
- `get windows` - All windows with preview images
```

--------------------------------

### windowlessEntry

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Creates a WindowInfo entry for an application that does not have any visible windows. This is useful for representing background applications or services.

```APIDOC
## windowlessEntry

### Description
Creates a WindowInfo entry for an application without windows.

### Method
static `windowlessEntry`

### Parameters
#### Path Parameters
- **app** (`NSRunningApplication`) - Required - The application for which to create the WindowInfo.

### Returns
`WindowInfo` — A window entry representing the windowless app.

### Example
```swift
let windowlessEntry = WindowInfo.windowlessEntry(for: app)
```
```

--------------------------------

### Reconcile Image Preview Permission

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Ensures the image preview setting aligns with the current screen recording permission status. It re-enables previews if permission is granted after being denied.

```swift
private func reconcileImagePreviewWithPermission()
```

--------------------------------

### Show Window Switcher with AppleScript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Use this command to open the DockDoor Window Switcher via AppleScript. Ensure DockDoor is running.

```applescript
tell application "DockDoor" to show switcher
```

--------------------------------

### fillBottomRightQuarter

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the bottom-right quarter of the screen.

```APIDOC
## fillBottomRightQuarter

### Description
Fills the window to occupy the bottom-right quarter of the screen.

### Method
`fillBottomRightQuarter()`
```

--------------------------------

### SharedPreviewWindowCoordinator Initialization

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Initializes a new SharedPreviewWindowCoordinator. This method sets up the coordinator as the active instance and configures the panel for floating, borderless previews.

```APIDOC
## init

### Description
Creates and initializes a new preview window coordinator. Sets itself as the active instance. Configures the panel with appropriate styling for floating previews (non-activating, borderless, transparent).

### Signature
```swift
init()
```

### Example
```swift
let coordinator = SharedPreviewWindowCoordinator()
// Coordinator is now active and ready to display previews
```
```

--------------------------------

### Fill Window to Quarter Screen

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy a specific quarter of the screen.

```swift
func fillTopLeftQuarter()
```

```swift
func fillTopRightQuarter()
```

```swift
func fillBottomLeftQuarter()
```

```swift
func fillBottomRightQuarter()
```

--------------------------------

### Save Window Order from Cache

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Saves the current order of windows, as stored in the cache, to persistent storage.

```swift
static func saveWindowOrderFromCache()
```

--------------------------------

### fillBottomLeftQuarter

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the bottom-left quarter of the screen.

```APIDOC
## fillBottomLeftQuarter

### Description
Fills the window to occupy the bottom-left quarter of the screen.

### Method
`fillBottomLeftQuarter()`
```

--------------------------------

### Capture Window Image using Window ID and PID

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Captures a window's image using its ID and the process ID of its application. This overload also manages caching and can force a refresh.

```swift
static func captureWindowImage(
    windowID: CGWindowID,
    pid: pid_t,
    windowTitle: String? = nil,
    forceRefresh: Bool = false
) async throws -> CGImage
```

```swift
do {
    let image = try await WindowUtil.captureWindowImage(windowID: windowID, pid: pid)
    displayImage(image)
} catch {
    print("Capture failed: \(error)")
}
```

--------------------------------

### WindowPropertiesProviding Protocol

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/types.md

Defines the essential properties required for any object that provides window information. This protocol is implemented by concrete window sources like SCWindow.

```swift
protocol WindowPropertiesProviding {
    var windowID: CGWindowID { get }
    var frame: CGRect { get }
    var title: String? { get }
    var owningApplicationBundleIdentifier: String? { get }
    var owningApplicationProcessID: pid_t? { get }
    var isOnScreen: Bool { get }
    var windowLayer: Int { get }
}
```

--------------------------------

### KeybindHelper Initializer

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/KeybindHelper.md

Initializes the KeybindHelper with a SharedPreviewWindowCoordinator instance.

```swift
init(previewCoordinator: SharedPreviewWindowCoordinator)
```

--------------------------------

### fillLeftHalf

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the left half of the screen.

```APIDOC
## fillLeftHalf

### Description
Fills the window to occupy the left half of the screen.

### Method
`fillLeftHalf()`
```

--------------------------------

### Window Size Property

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Represents the current dimensions of the preview window, dynamically updated based on user preferences.

```swift
var windowSize: CGSize
```

--------------------------------

### Fetch Shareable Content with Timeout

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Asynchronously fetches shareable content, with built-in protection against timeouts. Specify whether to include only on-screen windows.

```swift
static func getShareableContent(onScreenWindowsOnly: Bool) async -> SCShareableContent?
```

--------------------------------

### Focus Search Window Method

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/SharedPreviewWindowCoordinator.md

Brings the focus to the search window, which is part of the window switcher functionality.

```swift
func focusSearchWindow()
```

--------------------------------

### Handle Application Reopen

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/AppDelegate.md

Called when the user clicks the application's dock icon while it is already running. It is used to bring the settings window to the front.

```swift
func applicationShouldHandleReopen(_ sender: NSApplication, hasVisibleWindows flag: Bool) -> Bool
```

--------------------------------

### captureWindowImage (SCWindow)

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Captures an image of the specified window using ScreenCaptureKit. Allows forcing a refresh even if the image is cached.

```APIDOC
## captureWindowImage

### Description
Captures an image of the specified window using ScreenCaptureKit.

### Method
static func captureWindowImage(window: SCWindow, forceRefresh: Bool = false) async throws -> CGImage

### Parameters
#### Path Parameters
There are no path parameters for this method.

#### Query Parameters
There are no query parameters for this method.

#### Request Body
There is no request body for this method.

### Parameters
- **window** (`SCWindow`) - Required - The window to capture
- **forceRefresh** (`Bool`) - Optional - Force re-capture even if cached (Default: false)

### Returns
`CGImage` — The captured window image

### Throws
Errors from screen capture process
```

--------------------------------

### captureAndCacheWindowInfo

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Captures and caches the image for a given window, updating the cache with the new image. Can be forced to refresh.

```APIDOC
## captureAndCacheWindowInfo

### Description
Captures and caches window image, updating the cache with the new image.

### Method
static func captureAndCacheWindowInfo(window: WindowInfo, forceRefresh: Bool = false) async

### Parameters
- **window** (`WindowInfo`) - Required - The window to capture
- **forceRefresh** (`Bool`) - Optional - Force re-capture regardless of cache (Default: false)
```

--------------------------------

### DockObserver Active Instance Property

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/DockObserver.md

Provides a weak static reference to the currently active DockObserver instance.

```swift
weak static var activeInstance: DockObserver?
```

--------------------------------

### getShareableContent

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Asynchronously fetches shareable content, with built-in protection against timeouts. Optionally filters for on-screen windows only.

```APIDOC
## getShareableContent

### Description
Fetches shareable content with timeout protection.

### Method
static func

### Parameters
#### Path Parameters
- **onScreenWindowsOnly** (Bool) - Required - Whether to include only on-screen windows

### Returns
`SCShareableContent?` — Shareable content or nil if timeout
```

--------------------------------

### positionWindow

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Positions and resizes the window to a specific screen position and dimensions defined by `WindowPositionRect`.

```APIDOC
## positionWindow

### Description
Positions the window to a specific screen position.

### Method
`positionWindow(rect: WindowPositionRect)`

### Parameters
#### Path Parameters
- **rect** (`WindowPositionRect`) - Required - Target position/size. Options include `.full`, `.leftHalf`, `.rightHalf`, `.topHalf`, `.bottomHalf`, `.topLeftQuarter`, `.topRightQuarter`, `.bottomLeftQuarter`, `.bottomRightQuarter`, and `.center`.

### Example
```swift
window.positionWindow(rect: .leftHalf)
```
```

--------------------------------

### Define Window Actions

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Represents various actions that can be performed on a window, such as closing, minimizing, or resizing. Each action has a localized name and icon.

```swift
enum WindowAction: String, Hashable, CaseIterable, Defaults.Serializable {
    case quit
    case close
    case minimize
    case toggleFullScreen
    case hide
    case openNewWindow
    case maximize
    case bringToCurrentSpace
    case fillLeftHalf
    case fillRightHalf
    case fillTopHalf
    case fillBottomHalf
    case fillTopLeftQuarter
    case fillTopRightQuarter
    case fillBottomLeftQuarter
    case fillBottomRightQuarter
    case center
    case none
}
```

--------------------------------

### Open Window Switcher via osascript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Executes the command to open the DockDoor Window Switcher from the terminal using `osascript`. This is a common method for scripting.

```osascript
osascript -e 'tell application "DockDoor" to show switcher'
```

--------------------------------

### fillRightHalf

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the right half of the screen.

```APIDOC
## fillRightHalf

### Description
Fills the window to occupy the right half of the screen.

### Method
`fillRightHalf()`
```

--------------------------------

### Window Equality Rules

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Defines the conditions under which two WindowInfo instances are considered equal. Equality is based on window ID, process identifier, and accessibility element.

```swift
lhs.id == rhs.id &&
lhs.app.processIdentifier == rhs.app.processIdentifier &&
lhs.axElement == rhs.axElement
```

--------------------------------

### Fill Window to Half Screen

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy exactly half of the screen, either left, right, top, or bottom.

```swift
func fillLeftHalf()
```

```swift
func fillRightHalf()
```

```swift
func fillTopHalf()
```

```swift
func fillBottomHalf()
```

--------------------------------

### getActiveWindows

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowUtil.md

Fetches all active windows for a given application. This method utilizes screen capture and accessibility APIs to gather window information.

```APIDOC
## getActiveWindows

### Description
Fetches all active windows for an application, using screen capture and accessibility APIs.

### Method
static `async`

### Signature
`static func getActiveWindows(of app: NSRunningApplication, context: WindowFetchContext = .dockPreview, ignoreSingleWindowFilter: Bool = false) async throws -> [WindowInfo]`

### Parameters
#### Path Parameters
* **app** (`NSRunningApplication`) - Required - The application to fetch windows for.
* **context** (`WindowFetchContext`) - Optional - Defaults to `.dockPreview`. Determines which settings to use when fetching windows. The context influences sorting order and filtering behavior.
* **ignoreSingleWindowFilter** (`Bool`) - Optional - Defaults to `false`. Whether to include the single-window app optimization.

### Response
#### Success Response
* **`[WindowInfo]`** - Array of window information for the application.

### Throws
Errors from screen capture or accessibility APIs.

### Example
```swift
let app = NSRunningApplication(processIdentifier: pid)!
let windows = try await WindowUtil.getActiveWindows(of: app, context: .dockPreview)
for window in windows {
    print("Window: \(window.windowName ?? \"Unknown\")")
}
```
```

--------------------------------

### fillTopLeftQuarter

Source: https://github.com/ejbills/dockdoor/blob/main/_autodocs/api-reference/WindowInfo.md

Resizes the window to occupy the top-left quarter of the screen.

```APIDOC
## fillTopLeftQuarter

### Description
Fills the window to occupy the top-left quarter of the screen.

### Method
`fillTopLeftQuarter()`
```

--------------------------------

### Snap Active Window to Right Half via osascript

Source: https://github.com/ejbills/dockdoor/blob/main/docs.html

Uses `osascript` to command DockDoor to snap the active window to the right half of the screen. This is a convenient way to manage window layout from the command line.

```osascript
osascript -e 'tell application "DockDoor" to position window "active" to "right"'
```