8000 openclip/docs/index.md at main · alahmadics/openclip · GitHub
[go: up one dir, main page]
Skip to content

index.md

Latest commit

 

History

History
84 lines (64 loc) · 5.55 KB

index.md

File metadata and controls

84 lines (64 loc) · 5.55 KB
Raw

OpenClip Technical Documentation

Welcome to the OpenClip technical documentation hub. OpenClip is a lightweight, high-performance macOS floating popup utility written in Swift (macOS 14.0+). It intercepts selected text across any application, presents contextual text manipulation actions (copy, cut, paste, definition lookups, web searches, custom scripts, and extensions), and executes platform side-effects seamlessly.

Quick Start Guide

Prerequisites

  • macOS 14.0 (Sonoma) or later
  • Xcode 15.0+ (for building from source)
  • xcodegen (brew install xcodegen)

Building & Running

  1. Clone the Repository:
git clone https://github.com/openclip/openclip.git
cd openclip
  1. Generate Xcode Project:

Note: Run xcodegen generate whenever adding or removing .swift files.

xcodegen generate
  1. Build the Application:
xcodebuild -project OpenClip.xcodeproj -scheme OpenClip -destination 'platform=macOS' build | tail -n 10
  1. Run Unit Tests:
xcodebuild -project OpenClip.xcodeproj -scheme OpenClipTests -destination 'platform=macOS' test | grep -E "Test Suite|passed|failed|SUCCEEDED"
  1. Grant Accessibility Permissions: OpenClip relies on macOS Accessibility APIs to detect text selections without modifying system clipboard contents during monitoring. Grant permission in System Settings > Privacy & Security > Accessibility.

Documentation Table of Contents

System Architecture

Developer Guide

Action Execution Runtimes

  • AppleScript Runtime — AppleScriptAction execution, variable injection, and output handling.
  • JavaScript Runtime — JavaScriptAction under JavaScriptCore, the openclip bridge, and option keys via SettingKey.
  • URL Templates Engine — Parameterized search links using URLTemplateAction and TextPlaceholderEngine.
  • Shell & Executable Scripts — Process execution, environment variables (OPENCLIP_TEXT, OPENCLIP_MATCHED, OPENCLIP_ACTION_ID), and JSON/text stdout parsing.

User Guide

The app follows the macOS system language. English is the source locale; Simplified Chinese is bundled in Sources/OpenClip/Resources/Localizable.xcstrings.

Core Architectural Principles

OpenClip enforces a strict single-responsibility architecture divided across Core Architectural Subsystems:

  1. Settings Subsystem — SettingsStore (Typed SettingKey access; a few legacy UserDefaults.standard sites remain in the App target).
  2. Action Presentation — ActionCustomizationManager (Surface-tailored icon and title resolution).
  3. Action Chrome Policy — ActionChrome (UI policy metadata without type checking).
  4. Action Factory — DefaultActionFactory (Action creation from manifests/snippets).
  5. Action Result Handler — ActionResultHandler (Platform side-effects, pasteboard, and key events).
  6. Action Coordinator & Composition — ActionCoordinator (Composition root; wires managers to the registry via onRegister/onUnregister callbacks).
0