Skip to content

docs: refresh CLAUDE.md Tesseract and testing sections #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
melonamin merged 2 commits into from
Sep 27, 2026
Merged

docs: refresh CLAUDE.md Tesseract and testing sections #99

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1b83b9f
docs: refresh CLAUDE.md Tesseract and testing sections
melonamin Sep 26, 2026
f36a97b
docs: correct dependency list, Swift versions, and TRexLLM tests
melonamin Sep 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 16 additions & 23 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ TRex is a macOS menu bar application that performs OCR (Optical Character Recogn
xcodebuild -scheme TRex -configuration Release build

# Build the CLI tool
xcodebuild -scheme "TRex CMD" -configuration Release build
xcodebuild -scheme "TRex CLI" -configuration Release build

# Clean build
xcodebuild -scheme TRex clean
Expand Down Expand Up @@ -56,17 +56,24 @@ The codebase follows a modular architecture:

When modifying TRex:

1. **Swift Version**: Use Swift 5.x syntax (project uses swift-tools-version 5.9, aim for Swift Concurrency best practices)
1. **Swift Version**: Use Swift 5.x syntax (packages use swift-tools-version 6.1; the app targets build in Swift 5 language mode; aim for Swift Concurrency best practices)
2. **UI Framework**: All UI should be built with SwiftUI
3. **Minimum OS**: Ensure compatibility with macOS 14.0+ (Sonoma). Apple Intelligence features require macOS 15.1+
4. **Dependencies**: Managed via Swift Package Manager (KeyboardShortcuts, LaunchAtLogin, AnyLanguageModel)
4. **Dependencies**: Managed via Swift Package Manager — KeyboardShortcuts, Sparkle, swift-argument-parser (app/CLI), AnyLanguageModel (TRexLLM), TesseractSwift (TRexCore). LaunchAtLogin is vendored source (`TRex/LaunchAtLogin.swift`), not a package
5. **Text Recognition**: Vision framework calls should handle multiple recognition levels
6. **Error Handling**: OCR operations should gracefully handle failures and provide user feedback via notifications
7. **Concurrency**: All code must be Swift 6 concurrency-safe (Sendable protocol, actor isolation)

## Testing

The project currently has no test suite. When implementing tests, use XCTest framework following standard Swift testing patterns.
Both packages have XCTest suites: `Packages/TRexCore/Tests/TRexCoreTests/` covers OCR routing, table detection, capture history, automation, timeouts, and bug regressions; `Packages/TRexLLM/Tests/TRexLLMTests/` covers providers, configuration, errors, and image preprocessing (some integration tests make real network calls). Run them with:

```bash
swift test --package-path Packages/TRexCore
swift test --package-path Packages/TRexLLM
```

Follow the existing test patterns when adding coverage. Note: `swift test` may rewrite `Package.resolved` as a side effect — revert that churn rather than committing it. The app targets (`TRex/`, `TRex CMD/`) have no test targets.

## Distribution

Expand All @@ -87,33 +94,19 @@ The app registers and handles these URL schemes:

## Tesseract OCR Integration

TRex now includes optional Tesseract OCR support for additional languages:
TRex includes Tesseract OCR support for languages beyond Vision's built-in set, via the [TesseractSwift](https://github.com/amebalabs/TesseractSwift) Swift package (a TRexCore dependency — no separate build step):

### Building Tesseract
```bash
# Build libraries (requires cmake, already done)
./Scripts/build-tesseract.sh

# Download core language files
./Scripts/download-tessdata.sh
```
- Language data (`.traineddata`) is downloaded on demand by `LanguageDownloader` into `~/Library/Application Support/TRex/tessdata/`
- `LanguageCodeMapper` translates BCP-47 codes (e.g. `en-US`) to Tesseract codes (e.g. `eng`)
- Recognition runs through the actor-based `TesseractEngineCoordinator` for Swift 6 concurrency safety

### OCR Architecture
- **OCREngine protocol** - Abstraction for OCR engines (Sendable for Swift 6)
- **VisionOCREngine** - Apple Vision framework (default, 14 languages)
- **TesseractOCREngine** - Tesseract OCR (100+ languages, currently stubbed)
- **TesseractOCREngine** - Tesseract OCR (100+ languages via TesseractSwift)
- **LLMOCREngine** - LLM-based vision OCR (supports all languages via GPT-4o, Claude, etc.)
- **OCRManager** - Intelligent routing between engines (thread-safe singleton)

### App Store Preparation
Before submitting to App Store, run:
```bash
# In Xcode build phase or manually
./Scripts/app-store-prepare.sh
```

Note: Tesseract integration is currently using a stub implementation. To enable full functionality, build the libraries using the provided scripts.

## LLM Integration

TRex supports LLM-powered OCR and text post-processing using AnyLanguageModel as a unified API:
Expand Down
Loading