# writronic/macursor architecture

> Architecture diagram of the GitHub repository writronic/macursor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/writronic/macursor
- Repository: https://github.com/writronic/macursor

## Overview

MaCursor is a macOS cursor customization app: users import or convert themes, edit them, and apply a theme to system cursors; the optional helper keeps behavior active in the background. Separate capabilities include per-app automation, menu-bar controls, capture and markup, translation, gestures, trails, focus-on-hover, and Finder context actions. The graph combines sampled calls and SOURCE INDEX references with README-documented capabilities; several feature implementations were not sampled, so their internal wiring is intentionally omitted.

Main entry points: [`CursorEngine/MACCursorActions.swift`](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorActions.swift) (Cursor Actions), [`CursorEngineHelper/HelperRuntime.swift`](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/HelperRuntime.swift) (Helper Runtime), [`MaCursor/SwiftUI/Services/CursorService.swift`](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/CursorService.swift) (Cursor Service), [`CursorEngine/MACCursorCapture.swift`](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorCapture.swift) (Cursor Capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_theme["Themes and Editing"]
  node_theme_library["Theme Library"]
  node_library_controller["Library Controller"]
  node_theme_editor["Theme Editor"]
  node_theme_conversion["Theme Conversion"]
  node_windows_import["Windows Import"]
  node_slot_import["Image Import"]
end

subgraph group_runtime["Cursor Runtime"]
  node_cursor_service["Cursor Service"]
  node_cursor_actions["Cursor Actions"]
  node_cursor_definitions["Cursor Definitions"]
  node_preferences[("Preferences")]
  node_auto_switch["Theme Automation"]
end

subgraph group_helper["Background Helper"]
  node_helper_manager["Helper Manager"]
  node_helper_runtime["Helper Runtime"]
  node_menu_controller["Menu Bar Controller"]
  node_menu_panel["Menu Bar Panel"]
  node_menu_service["Menu Bar Service"]
end

subgraph group_features["Cursor Features"]
  node_capture["Cursor Capture"]
  node_capture_editor["Capture Editor"]
  node_translator["Cursor Translator"]
  node_gestures["Cursor Gestures"]
  node_trails["Cursor Trails"]
  node_focus["Focus on Hover"]
end

subgraph group_finder["Finder Actions"]
  node_finder_sync["Finder Extension"]
  node_finder_actions["Finder Actions"]
end

node_user(("User"))

node_user -->|"imports themes"| node_theme_library
node_user -->|"edits themes"| node_theme_editor
node_user -->|"converts themes"| node_theme_conversion
node_theme_conversion -.->|"imports Windows"| node_windows_import
node_theme_editor -->|"imports images"| node_slot_import
node_theme_library -->|"uses controller"| node_library_controller
node_library_controller -->|"applies theme"| node_cursor_service
node_cursor_service -->|"applies theme"| node_cursor_actions
node_cursor_service -->|"validates identifiers"| node_cursor_definitions
node_cursor_actions -->|"uses definitions"| node_cursor_definitions
node_user -->|"configures switching"| node_auto_switch
node_auto_switch -.->|"applies themes"| node_cursor_actions
node_preferences -->|"configures behavior"| node_cursor_actions
node_user -->|"installs helper"| node_helper_manager
node_helper_manager -->|"registers helper"| node_helper_runtime
node_helper_runtime -->|"controls cursors"| node_cursor_actions
node_helper_runtime -->|"dispatches capture"| node_capture
node_helper_runtime -->|"controls panel"| node_menu_controller
node_menu_controller -->|"hosts view"| node_menu_panel
node_menu_panel -->|"uses service"| node_menu_service
node_menu_service -->|"controls cursors"| node_cursor_actions
node_user -->|"captures screen"| node_capture
node_capture -.->|"opens editor"| node_capture_editor
node_user -->|"translates screen text"| node_translator
node_user -->|"configures gestures"| node_gestures
node_user -->|"configures trails"| node_trails
node_user -->|"enables hover focus"| node_focus
node_user -->|"uses Finder menu"| node_finder_sync
node_finder_sync -->|"dispatches actions"| node_finder_actions

click node_theme_library "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Models/CursorLibrary.swift"
click node_library_controller "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/LibraryController.swift"
click node_theme_editor "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/ViewModels/CursorThemeEditorViewModel.swift"
click node_theme_conversion "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/ThemeConversion.swift"
click node_windows_import "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/WindowsCursorImporter.swift"
click node_slot_import "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/SlotImageImporter.swift"
click node_cursor_service "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/CursorService.swift"
click node_cursor_actions "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorActions.swift"
click node_cursor_definitions "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorDefinitions.swift"
click node_preferences "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Models/MACPreferences.swift"
click node_auto_switch "https://github.com/writronic/macursor/blob/main/CursorEngine/MACAutoSwitch.swift"
click node_helper_manager "https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/HelperToolManager.swift"
click node_helper_runtime "https://github.com/writronic/macursor/blob/main/CursorEngineHelper/HelperRuntime.swift"
click node_menu_controller "https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarController.swift"
click node_menu_panel "https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarPanelView.swift"
click node_menu_service "https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarService.swift"
click node_capture "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorCapture.swift"
click node_capture_editor "https://github.com/writronic/macursor/blob/main/CursorEngineHelper/HelperScreenshotEditor.swift"
click node_translator "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorTranslator.swift"
click node_gestures "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorGestures.swift"
click node_trails "https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorTrails.swift"
click node_focus "https://github.com/writronic/macursor/blob/main/CursorEngine/MACFocusFollowsMouse.swift"
click node_finder_sync "https://github.com/writronic/macursor/blob/main/MaCursorFinder/MACFinderSync.swift"
click node_finder_actions "https://github.com/writronic/macursor/blob/main/MaCursorFinder/RightClickMenuActions.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_theme_library,node_library_controller,node_theme_editor,node_theme_conversion,node_windows_import,node_slot_import,node_user toneBlue
class node_cursor_service,node_cursor_actions,node_cursor_definitions,node_preferences,node_auto_switch toneAmber
class node_helper_manager,node_helper_runtime,node_menu_controller,node_menu_panel,node_menu_service toneMint
class node_capture,node_capture_editor,node_translator,node_gestures,node_trails,node_focus toneRose
class node_finder_sync,node_finder_actions toneIndigo
```

## Components

### Themes and Editing

- [Theme Library](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Models/CursorLibrary.swift): `MaCursor/SwiftUI/Models/CursorLibrary.swift`
- [Library Controller](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/LibraryController.swift): `MaCursor/SwiftUI/Services/LibraryController.swift`
- [Theme Editor](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/ViewModels/CursorThemeEditorViewModel.swift): `MaCursor/SwiftUI/ViewModels/CursorThemeEditorViewModel.swift`
- [Theme Conversion](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/ThemeConversion.swift): `MaCursor/SwiftUI/Services/ThemeConversion.swift`
- [Windows Import](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/WindowsCursorImporter.swift): `MaCursor/SwiftUI/Services/WindowsCursorImporter.swift`
- [Image Import](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/SlotImageImporter.swift): `MaCursor/SwiftUI/Services/SlotImageImporter.swift`

### Cursor Runtime

- [Cursor Service](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/CursorService.swift): `MaCursor/SwiftUI/Services/CursorService.swift`
- [Cursor Actions](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorActions.swift): `CursorEngine/MACCursorActions.swift`
- [Cursor Definitions](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorDefinitions.swift): `CursorEngine/MACCursorDefinitions.swift`
- [Preferences](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Models/MACPreferences.swift): `MaCursor/SwiftUI/Models/MACPreferences.swift`
- [Theme Automation](https://github.com/writronic/macursor/blob/main/CursorEngine/MACAutoSwitch.swift): `CursorEngine/MACAutoSwitch.swift`

### Background Helper

- [Helper Manager](https://github.com/writronic/macursor/blob/main/MaCursor/SwiftUI/Services/HelperToolManager.swift): `MaCursor/SwiftUI/Services/HelperToolManager.swift`
- [Helper Runtime](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/HelperRuntime.swift): `CursorEngineHelper/HelperRuntime.swift`
- [Menu Bar Controller](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarController.swift): `CursorEngineHelper/MenuBarController.swift`
- [Menu Bar Panel](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarPanelView.swift): `CursorEngineHelper/MenuBarPanelView.swift`
- [Menu Bar Service](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/MenuBarService.swift): `CursorEngineHelper/MenuBarService.swift`

### Cursor Features

- [Cursor Capture](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorCapture.swift): `CursorEngine/MACCursorCapture.swift`
- [Capture Editor](https://github.com/writronic/macursor/blob/main/CursorEngineHelper/HelperScreenshotEditor.swift): `CursorEngineHelper/HelperScreenshotEditor.swift`
- [Cursor Translator](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorTranslator.swift): `CursorEngine/MACCursorTranslator.swift`
- [Cursor Gestures](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorGestures.swift): `CursorEngine/MACCursorGestures.swift`
- [Cursor Trails](https://github.com/writronic/macursor/blob/main/CursorEngine/MACCursorTrails.swift): `CursorEngine/MACCursorTrails.swift`
- [Focus on Hover](https://github.com/writronic/macursor/blob/main/CursorEngine/MACFocusFollowsMouse.swift): `CursorEngine/MACFocusFollowsMouse.swift`

### Finder Actions

- [Finder Extension](https://github.com/writronic/macursor/blob/main/MaCursorFinder/MACFinderSync.swift): `MaCursorFinder/MACFinderSync.swift`
- [Finder Actions](https://github.com/writronic/macursor/blob/main/MaCursorFinder/RightClickMenuActions.swift): `MaCursorFinder/RightClickMenuActions.swift`

### Other components

- **User**

## Connections

- User → Theme Library: imports themes (evidence: `README.md`)
- User → Theme Editor: edits themes (evidence: `README.md`)
- User → Theme Conversion: converts themes (evidence: `README.md`)
- Theme Conversion → Windows Import: imports Windows
- Theme Editor → Image Import: imports images (evidence: `MaCursor/SwiftUI/ViewModels/CursorThemeEditorViewModel.swift`)
- Theme Library → Library Controller: uses controller (evidence: `MaCursor/SwiftUI/Models/CursorLibrary.swift`)
- Library Controller → Cursor Service: applies theme (evidence: `MaCursor/SwiftUI/Services/LibraryController.swift`)
- Cursor Service → Cursor Actions: applies theme (evidence: `MaCursor/SwiftUI/Services/CursorService.swift`)
- Cursor Service → Cursor Definitions: validates identifiers (evidence: `MaCursor/SwiftUI/Services/CursorService.swift`)
- Cursor Actions → Cursor Definitions: uses definitions (evidence: `CursorEngine/MACCursorActions.swift`)
- User → Theme Automation: configures switching (evidence: `README.md`)
- Theme Automation → Cursor Actions: applies themes
- Preferences → Cursor Actions: configures behavior (evidence: `CursorEngine/MACCursorActions.swift`)
- User → Helper Manager: installs helper (evidence: `README.md`)
- Helper Manager → Helper Runtime: registers helper (evidence: `MaCursor/SwiftUI/Services/HelperToolManager.swift`)
- Helper Runtime → Cursor Actions: controls cursors (evidence: `CursorEngineHelper/HelperRuntime.swift`)
- Helper Runtime → Cursor Capture: dispatches capture (evidence: `CursorEngineHelper/HelperRuntime.swift`)
- Helper Runtime → Menu Bar Controller: controls panel (evidence: `CursorEngineHelper/HelperRuntime.swift`)
- Menu Bar Controller → Menu Bar Panel: hosts view (evidence: `CursorEngineHelper/MenuBarController.swift`)
- Menu Bar Panel → Menu Bar Service: uses service (evidence: `CursorEngineHelper/MenuBarPanelView.swift`)
- Menu Bar Service → Cursor Actions: controls cursors (evidence: `CursorEngineHelper/MenuBarService.swift`)
- User → Cursor Capture: captures screen (evidence: `README.md`)
- Cursor Capture → Capture Editor: opens editor
- User → Cursor Translator: translates screen text (evidence: `README.md`)
- User → Cursor Gestures: configures gestures (evidence: `README.md`)
- User → Cursor Trails: configures trails (evidence: `README.md`)
- User → Focus on Hover: enables hover focus (evidence: `README.md`)
- User → Finder Extension: uses Finder menu (evidence: `README.md`)
- Finder Extension → Finder Actions: dispatches actions (evidence: `MaCursorFinder/MACFinderSync.swift`)