# domkeq/macos-window-previews architecture

> Architecture diagram of the GitHub repository domkeq/macos-window-previews, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/domkeq/macos-window-previews
- Repository: https://github.com/domkeq/macos-window-previews

## Overview

WindowBar is a native macOS taskbar and Dock-hover companion. The user enables it from the menu-bar app, sees running-app icons, activates apps, and can inspect an app’s windows in a popover; selecting a window attempts focused activation. Dock hover uses Accessibility to identify a standard Dock item and show its window popover. Accessibility window listing/focusing and Screen Recording thumbnails are permission-gated, with thumbnail capture also controlled by a preference. Relationships follow the shown excerpts and SOURCE INDEX references; unsampled implementations are represented only where README or index evidence supports them.

Main entry points: [`Sources/WindowBar/Taskbar/TaskbarModel.swift`](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarModel.swift) (Taskbar model), [`Sources/WindowBar/DockIntegration/DockHoverController.swift`](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/DockIntegration/DockHoverController.swift) (Dock hover controller), [`Sources/WindowBar/AppHost/StatusItemController.swift`](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/StatusItemController.swift) (Menu-bar controls), [`Sources/WindowBar/AppHost/AppDelegate.swift`](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/AppDelegate.swift) (Lifecycle assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["App host"]
  node_entry["App entry<br/>[main.swift]"]
  node_lifecycle["Lifecycle assembly<br/>[AppDelegate.swift]"]
  node_status["Menu-bar controls"]
end

subgraph group_taskbar["Taskbar UI"]
  node_model["Taskbar model<br/>[TaskbarModel.swift]"]
  node_panel["Floating panel"]
  node_taskbarview["App icon strip"]
  node_item["App icon item"]
  node_popover["Window popover"]
  node_windowlist["Window cards"]
  node_previewcard["Preview card"]
end

subgraph group_dock["Dock companion"]
  node_dockcontroller["Dock hover controller"]
  node_dockresolver["Dock item resolver"]
  node_hoverstate["Hover state machine"]
end

subgraph group_windows["Window services"]
  node_apps["Running apps"]
  node_composite["Window repository"]
  node_axwindows["Accessibility listing"]
  node_cgwindows["Core Graphics listing"]
  node_activator["Window activation"]
  node_matcher["Window identity matcher"]
  node_thumbnail["Thumbnail provider"]
end

subgraph group_settings["Permissions and settings"]
  node_permissions["OS permission monitor"]
  node_preferences[("Preview preference")]
  node_featuregate["Permission feature gate"]
  node_logger["Diagnostics logger"]
end

node_user(("User"))

node_user -->|"configures"| node_status
node_entry -->|"launches"| node_lifecycle
node_lifecycle -->|"creates"| node_status
node_lifecycle -->|"creates"| node_model
node_lifecycle -->|"creates"| node_panel
node_lifecycle -->|"creates"| node_dockcontroller
node_status -->|"reloads"| node_model
node_status -->|"requests access"| node_permissions
node_status -->|"toggles"| node_preferences
node_status -->|"checks eligibility"| node_featuregate
node_panel -->|"hosts"| node_taskbarview
node_taskbarview -->|"observes and acts"| node_model
node_taskbarview -->|"renders"| node_item
node_taskbarview -->|"presents"| node_popover
node_popover -->|"requests previews"| node_model
node_popover -->|"presents"| node_windowlist
node_windowlist -->|"renders"| node_previewcard
node_windowlist -->|"loads thumbnails"| node_model
node_model -->|"discovers"| node_apps
node_model -->|"lists windows"| node_composite
node_model -->|"activates window"| node_activator
node_model -->|"gets thumbnails"| node_thumbnail
node_model -->|"reads status"| node_permissions
node_model -->|"logs failures"| node_logger
node_dockcontroller -->|"checks trust"| node_permissions
node_dockcontroller -->|"resolves pointer"| node_dockresolver
node_dockcontroller -->|"dispatches events"| node_hoverstate
node_dockcontroller -->|"gets apps and windows"| node_model
node_dockcontroller -->|"shows overlay"| node_popover
node_dockcontroller -->|"logs activity"| node_logger
node_dockresolver -->|"matches candidates"| node_apps
node_composite -->|"combines listings"| node_axwindows
node_composite -->|"combines listings"| node_cgwindows
node_composite -->|"matches identities"| node_matcher
node_activator -->|"checks trust"| node_permissions
node_activator -->|"matches target"| node_matcher
node_thumbnail -->|"checks capture access"| node_permissions
node_thumbnail -->|"checks preview toggle"| node_preferences

click node_entry "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/main.swift"
click node_lifecycle "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/AppDelegate.swift"
click node_status "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/StatusItemController.swift"
click node_model "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarModel.swift"
click node_panel "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarWindowController.swift"
click node_taskbarview "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarViewController.swift"
click node_item "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarAppItemView.swift"
click node_popover "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowListPopoverPresenter.swift"
click node_windowlist "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowListViewController.swift"
click node_previewcard "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowPreviewCardView.swift"
click node_dockcontroller "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/DockIntegration/DockHoverController.swift"
click node_dockresolver "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/DockIntegration/DockItemResolver.swift"
click node_hoverstate "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/DockHoverStateMachine.swift"
click node_apps "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/NSWorkspaceRunningApplicationProvider.swift"
click node_composite "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CompositeWindowRepository.swift"
click node_axwindows "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/AccessibilityWindowRepository.swift"
click node_cgwindows "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CoreGraphicsWindowRepository.swift"
click node_activator "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/AccessibilityWindowActivator.swift"
click node_matcher "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/WindowIdentityMatcher.swift"
click node_thumbnail "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CoreGraphicsWindowPreviewProvider.swift"
click node_permissions "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Permissions/SystemPermissionMonitor.swift"
click node_preferences "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Preferences/WindowBarPreferences.swift"
click node_featuregate "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/PermissionFeatureResolver.swift"
click node_logger "https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Diagnostics/WindowBarLogger.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_lifecycle,node_status,node_user toneBlue
class node_model,node_panel,node_taskbarview,node_item,node_popover,node_windowlist,node_previewcard toneAmber
class node_dockcontroller,node_dockresolver,node_hoverstate toneMint
class node_apps,node_composite,node_axwindows,node_cgwindows,node_activator,node_matcher,node_thumbnail toneRose
class node_permissions,node_preferences,node_featuregate,node_logger toneIndigo
```

## Components

### App host

- [App entry](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/main.swift): `Sources/WindowBar/main.swift`
- [Lifecycle assembly](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/AppDelegate.swift): `Sources/WindowBar/AppHost/AppDelegate.swift`
- [Menu-bar controls](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/AppHost/StatusItemController.swift): `Sources/WindowBar/AppHost/StatusItemController.swift`

### Taskbar UI

- [Taskbar model](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarModel.swift): `Sources/WindowBar/Taskbar/TaskbarModel.swift`
- [Floating panel](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarWindowController.swift): `Sources/WindowBar/Taskbar/TaskbarWindowController.swift`
- [App icon strip](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarViewController.swift): `Sources/WindowBar/Taskbar/TaskbarViewController.swift`
- [App icon item](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/TaskbarAppItemView.swift): `Sources/WindowBar/Taskbar/TaskbarAppItemView.swift`
- [Window popover](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowListPopoverPresenter.swift): `Sources/WindowBar/Taskbar/WindowListPopoverPresenter.swift`
- [Window cards](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowListViewController.swift): `Sources/WindowBar/Taskbar/WindowListViewController.swift`
- [Preview card](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Taskbar/WindowPreviewCardView.swift): `Sources/WindowBar/Taskbar/WindowPreviewCardView.swift`

### Dock companion

- [Dock hover controller](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/DockIntegration/DockHoverController.swift): `Sources/WindowBar/DockIntegration/DockHoverController.swift`
- [Dock item resolver](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/DockIntegration/DockItemResolver.swift): `Sources/WindowBar/DockIntegration/DockItemResolver.swift`
- [Hover state machine](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/DockHoverStateMachine.swift): `Sources/WindowBarCore/DockHoverStateMachine.swift`

### Window services

- [Running apps](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/NSWorkspaceRunningApplicationProvider.swift): `Sources/WindowBar/Windowing/NSWorkspaceRunningApplicationProvider.swift`
- [Window repository](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CompositeWindowRepository.swift): `Sources/WindowBar/Windowing/CompositeWindowRepository.swift`
- [Accessibility listing](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/AccessibilityWindowRepository.swift): `Sources/WindowBar/Windowing/AccessibilityWindowRepository.swift`
- [Core Graphics listing](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CoreGraphicsWindowRepository.swift): `Sources/WindowBar/Windowing/CoreGraphicsWindowRepository.swift`
- [Window activation](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/AccessibilityWindowActivator.swift): `Sources/WindowBar/Windowing/AccessibilityWindowActivator.swift`
- [Window identity matcher](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/WindowIdentityMatcher.swift): `Sources/WindowBarCore/WindowIdentityMatcher.swift`
- [Thumbnail provider](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Windowing/CoreGraphicsWindowPreviewProvider.swift): `Sources/WindowBar/Windowing/CoreGraphicsWindowPreviewProvider.swift`

### Permissions and settings

- [OS permission monitor](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Permissions/SystemPermissionMonitor.swift): `Sources/WindowBar/Permissions/SystemPermissionMonitor.swift`
- [Preview preference](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Preferences/WindowBarPreferences.swift): `Sources/WindowBar/Preferences/WindowBarPreferences.swift`
- [Permission feature gate](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBarCore/PermissionFeatureResolver.swift): `Sources/WindowBarCore/PermissionFeatureResolver.swift`
- [Diagnostics logger](https://github.com/domkeq/macos-window-previews/blob/main/Sources/WindowBar/Diagnostics/WindowBarLogger.swift): `Sources/WindowBar/Diagnostics/WindowBarLogger.swift`

### Other components

- **User**

## Connections

- User → Menu-bar controls: configures (evidence: `Sources/WindowBar/AppHost/StatusItemController.swift`)
- App entry → Lifecycle assembly: launches (evidence: `Sources/WindowBar/main.swift`)
- Lifecycle assembly → Menu-bar controls: creates (evidence: `Sources/WindowBar/AppHost/AppDelegate.swift`)
- Lifecycle assembly → Taskbar model: creates (evidence: `Sources/WindowBar/AppHost/AppDelegate.swift`)
- Lifecycle assembly → Floating panel: creates (evidence: `Sources/WindowBar/AppHost/AppDelegate.swift`)
- Lifecycle assembly → Dock hover controller: creates (evidence: `Sources/WindowBar/AppHost/AppDelegate.swift`)
- Menu-bar controls → Taskbar model: reloads (evidence: `Sources/WindowBar/AppHost/StatusItemController.swift`)
- Menu-bar controls → OS permission monitor: requests access (evidence: `Sources/WindowBar/AppHost/StatusItemController.swift`)
- Menu-bar controls → Preview preference: toggles (evidence: `Sources/WindowBar/AppHost/StatusItemController.swift`)
- Menu-bar controls → Permission feature gate: checks eligibility (evidence: `Sources/WindowBar/AppHost/StatusItemController.swift`)
- Floating panel → App icon strip: hosts (evidence: `Sources/WindowBar/Taskbar/TaskbarWindowController.swift`)
- App icon strip → Taskbar model: observes and acts (evidence: `Sources/WindowBar/Taskbar/TaskbarViewController.swift`)
- App icon strip → App icon item: renders (evidence: `Sources/WindowBar/Taskbar/TaskbarViewController.swift`)
- App icon strip → Window popover: presents (evidence: `Sources/WindowBar/Taskbar/TaskbarViewController.swift`)
- Window popover → Taskbar model: requests previews (evidence: `Sources/WindowBar/Taskbar/WindowListPopoverPresenter.swift`)
- Window popover → Window cards: presents (evidence: `Sources/WindowBar/Taskbar/WindowListPopoverPresenter.swift`)
- Window cards → Preview card: renders (evidence: `Sources/WindowBar/Taskbar/WindowListViewController.swift`)
- Window cards → Taskbar model: loads thumbnails (evidence: `Sources/WindowBar/Taskbar/WindowListViewController.swift`)
- Taskbar model → Running apps: discovers (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Taskbar model → Window repository: lists windows (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Taskbar model → Window activation: activates window (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Taskbar model → Thumbnail provider: gets thumbnails (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Taskbar model → OS permission monitor: reads status (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Taskbar model → Diagnostics logger: logs failures (evidence: `Sources/WindowBar/Taskbar/TaskbarModel.swift`)
- Dock hover controller → OS permission monitor: checks trust (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock hover controller → Dock item resolver: resolves pointer (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock hover controller → Hover state machine: dispatches events (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock hover controller → Taskbar model: gets apps and windows (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock hover controller → Window popover: shows overlay (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock hover controller → Diagnostics logger: logs activity (evidence: `Sources/WindowBar/DockIntegration/DockHoverController.swift`)
- Dock item resolver → Running apps: matches candidates (evidence: `Sources/WindowBar/DockIntegration/DockItemResolver.swift`)
- Window repository → Accessibility listing: combines listings (evidence: `Sources/WindowBar/Windowing/CompositeWindowRepository.swift`)
- Window repository → Core Graphics listing: combines listings (evidence: `Sources/WindowBar/Windowing/CompositeWindowRepository.swift`)
- Window repository → Window identity matcher: matches identities (evidence: `Sources/WindowBar/Windowing/CompositeWindowRepository.swift`)
- Window activation → OS permission monitor: checks trust (evidence: `Sources/WindowBar/Windowing/AccessibilityWindowActivator.swift`)
- Window activation → Window identity matcher: matches target (evidence: `Sources/WindowBar/Windowing/AccessibilityWindowActivator.swift`)
- Thumbnail provider → OS permission monitor: checks capture access (evidence: `Sources/WindowBar/Windowing/CoreGraphicsWindowPreviewProvider.swift`)
- Thumbnail provider → Preview preference: checks preview toggle (evidence: `Sources/WindowBar/Windowing/CoreGraphicsWindowPreviewProvider.swift`)
