# 🎯 Quick Reference Card

**Keep this open while developing LangOver**

---

## 🏃 Quick Start (First Time)

```bash
1. Add package: File → Add Package Dependencies
   URL: https://github.com/sindresorhus/KeyboardShortcuts

2. Set deployment: Project → General → macOS 13.0

3. Add capabilities: Project → Signing & Capabilities
   → App Sandbox (✓ Accessibility)
   → Hardened Runtime

4. Set as menu bar app: Project → Info
   → Application is agent (UIElement) = YES

5. Delete old app file: LangToLangApp.swift

6. Build: Cmd+R
```

---

## ⌨️ Xcode Keyboard Shortcuts

| Action | Shortcut |
|--------|----------|
| Build | ⌘B |
| Run | ⌘R |
| Stop | ⌘. |
| Clean Build Folder | ⌘⇧K |
| Show/Hide Console | ⌘⇧Y |
| Show/Hide Navigator | ⌘0 |
| Show/Hide Inspector | ⌘⌥0 |
| Find in File | ⌘F |
| Find in Project | ⌘⇧F |
| Quick Open | ⌘⇧O |

---

## 📂 File Quick Reference

| File | What It Does | When to Edit |
|------|--------------|--------------|
| **LangOverApp.swift** | App entry point | Rarely |
| **AppDelegate.swift** | Menu bar, hotkey setup | Add menu items |
| **Settings.swift** | Save/load preferences | Add new settings |
| **LayoutConverter.swift** | Text conversion logic | **Add languages** |
| **KeyboardDetector.swift** | Find keyboards | Modify detection |
| **AccessibilityService.swift** | Read/write text | Fix text issues |
| **HotkeyService.swift** | Handle hotkey press | Change behavior |
| **FirstLaunchView.swift** | Initial setup UI | Change first-run |
| **PreferencesView.swift** | Settings window | Add preferences |

---

## 🔧 Common Tasks

### Add a New Keyboard Layout

**File:** `LayoutConverter.swift`

```swift
// 1. Add detection function
private static func isRussian(_ text: String) -> Bool {
    let russianRange = "\u{0400}"..."\u{04FF}"
    let russianChars = text.filter { char in
        russianRange.contains(String(char))
    }
    return Double(russianChars.count) / Double(text.count) > 0.5
}

// 2. Add conversion functions
private static func convertEnglishToRussian(_ text: String) -> String {
    let mapping: [Character: Character] = [
        "q": "й", "w": "ц", "e": "у", "r": "к", "t": "е",
        "a": "ф", "s": "ы", "d": "в", "f": "а", "g": "п",
        // ... add all mappings
    ]
    return String(text.map { mapping[$0] ?? $0 })
}

// 3. Update main convert() function
static func convert(text: String, between layouts: [String]) -> String? {
    if isEnglish(text) {
        // Check which language to convert to
        if layouts.contains("Russian") {
            return convertEnglishToRussian(text)
        } else if layouts.contains("Hebrew") {
            return convertEnglishToHebrew(text)
        }
    } else if isRussian(text) {
        return convertRussianToEnglish(text)
    } else if isHebrew(text) {
        return convertHebrewToEnglish(text)
    }
    return nil
}
```

---

### Change the Menu Bar Icon

**File:** `AppDelegate.swift` (line ~58)

```swift
// Find this line:
let image = NSImage(systemSymbolName: "textformat.abc", ...)

// Replace with any SF Symbol:
let image = NSImage(systemSymbolName: "keyboard", ...)
// or
let image = NSImage(systemSymbolName: "globe", ...)
// or
let image = NSImage(systemSymbolName: "character.textbox", ...)
```

**Find SF Symbols:** Open "SF Symbols" app (free from Apple)

---

### Change the Default Hotkey

**File:** `Settings.swift` (line ~61)

```swift
// Find this line:
static let toggleConversion = Self("toggleConversion", 
    default: .init(.space, modifiers: [.control, .shift]))

// Change key:
default: .init(.keyL, modifiers: [.control, .shift])  // Ctrl+Shift+L

// Change modifiers:
default: .init(.space, modifiers: [.command, .shift])  // Cmd+Shift+Space
default: .init(.space, modifiers: [.option, .shift])   // Opt+Shift+Space
```

**Available keys:** `.space`, `.keyA` through `.keyZ`, `.f1` through `.f12`

---

### Add a New Setting

**File:** `Settings.swift`

```swift
// 1. Add UserDefaults key
private enum Keys {
    // ... existing keys
    static let myNewSetting = "myNewSetting"
}

// 2. Add published property
@Published var myNewSetting: Bool {
    didSet { defaults.set(myNewSetting, forKey: Keys.myNewSetting) }
}

// 3. Load in init()
self.myNewSetting = defaults.bool(forKey: Keys.myNewSetting)
```

**File:** `PreferencesView.swift`

```swift
// 4. Add UI in preferences
Toggle("My New Setting", isOn: $settings.myNewSetting)
```

---

### Add a Menu Item

**File:** `AppDelegate.swift` → `updateMenu()` function

```swift
// Add after existing items:
let myNewItem = NSMenuItem(
    title: "My New Feature", 
    action: #selector(myNewAction), 
    keyEquivalent: ""
)
myNewItem.target = self
menu.addItem(myNewItem)

// Then add the action:
@objc private func myNewAction() {
    print("Menu item clicked!")
    // Do something...
}
```

---

### Debug: Print to Console

```swift
// Anywhere in the code:
print("🔍 Debug: \(someVariable)")

// With colors (view in Xcode console):
print("✅ Success!")  // Green checkmark
print("❌ Error!")    // Red X
print("⚠️ Warning!")  // Yellow warning
print("🔍 Debug!")    // Magnifying glass
```

---

## 🐛 Debugging Checklist

**Hotkey not working?**
1. [ ] Accessibility permission granted?
2. [ ] App enabled? (menu shows "Disable")
3. [ ] No other app using same hotkey?

**Text not converting?**
1. [ ] Text is English or Hebrew?
2. [ ] Text is actually selected?
3. [ ] Try in TextEdit first (some apps block this)

**Build errors?**
1. [ ] KeyboardShortcuts package added?
2. [ ] Deployment target = macOS 13.0?
3. [ ] Clean build folder (⌘⇧K)?

**App not in menu bar?**
1. [ ] LSUIElement = YES in Info?
2. [ ] Check Console for crash logs
3. [ ] Look carefully (icon might be small)

---

## 📍 Important Line Numbers

**LayoutConverter.swift**
- Line 10: `convert()` - Main conversion function
- Line 37: `convertEnglishToHebrew()` - English→Hebrew
- Line 62: `convertHebrewToEnglish()` - Hebrew→English

**AppDelegate.swift**
- Line 26: `applicationDidFinishLaunching()` - App startup
- Line 42: `setupMenuBar()` - Menu bar configuration
- Line 58: Menu bar icon
- Line 68: `updateMenu()` - Menu items

**Settings.swift**
- Line 18: UserDefaults keys
- Line 25: Published properties (all settings)
- Line 61: Hotkey definition

**HotkeyService.swift**
- Line 25: `handleHotkeyPress()` - What happens when hotkey pressed

**AccessibilityService.swift**
- Line 16: `hasAccessibilityPermission()` - Check permission
- Line 27: `getSelectedText()` - Get selected text
- Line 38: `replaceSelectedText()` - Replace text

---

## 🧪 Testing Commands

**Reset all settings:**
```bash
defaults delete com.yourname.LangOver
```

**Check saved settings:**
```bash
defaults read com.yourname.LangOver
```

**Reset first launch:**
```bash
defaults delete com.yourname.LangOver hasCompletedFirstLaunch
```

**View Accessibility permissions:**
```bash
sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
"SELECT client, auth_value FROM access WHERE service='kTCCServiceAccessibility';"
```

---

## 📦 Package Management

**Add package:**
```
File → Add Package Dependencies → Paste URL → Add Package
```

**Update package:**
```
File → Packages → Update to Latest Package Versions
```

**Remove package:**
```
Project → Package Dependencies → Select package → "-" button
```

---

## 🎨 SF Symbols (Icon Names)

**Text-related:**
- `textformat.abc`
- `keyboard`
- `character.textbox`
- `text.bubble`

**General:**
- `globe`
- `globe.americas`
- `flag`
- `doc.text`

**Actions:**
- `arrow.2.squarepath`
- `arrow.triangle.2.circlepath`
- `repeat`

**Open SF Symbols app to browse hundreds more**

---

## 🔍 Xcode Tips

**Find all uses of a variable:**
- Right-click variable → Find → Find Selected Symbol in Workspace

**Jump to definition:**
- Cmd+Click on any function/variable

**Show documentation:**
- Option+Click on any function

**Fold/unfold code:**
- Cmd+Option+Left/Right arrow

**Comment/uncomment:**
- Cmd+/ (works on single line or selection)

**Duplicate line:**
- Cmd+D

**Move line up/down:**
- Cmd+Option+[ or ]

---

## 📝 Common Errors & Fixes

| Error | Fix |
|-------|-----|
| Cannot find 'KeyboardShortcuts' | Add package |
| Type 'SMAppService' has no member | Set deployment to macOS 13+ |
| Missing Info.plist | Check Build Settings → Info.plist File path |
| App not in menu bar | Set LSUIElement = YES |
| Hotkey doesn't work | Grant Accessibility permission |

---

## 🚀 Build & Deploy

**Build for testing:**
```
Product → Build (⌘B)
Product → Run (⌘R)
```

**Build for release:**
```
Product → Archive
Distribute App → Copy App
```

**Create DMG:**
```bash
# Install create-dmg via Homebrew:
brew install create-dmg

# Create DMG:
create-dmg \
  --volname "LangOver" \
  --window-pos 200 120 \
  --window-size 800 400 \
  --icon-size 100 \
  --app-drop-link 600 185 \
  "LangOver.dmg" \
  "LangOver.app"
```

---

## 📚 Learning Resources

**Apple Official:**
- SwiftUI: developer.apple.com/tutorials/swiftui
- AppKit: developer.apple.com/documentation/appkit
- Accessibility: developer.apple.com/accessibility

**Third-Party:**
- Hacking with Swift: hackingwithswift.com
- Swift by Sundell: swiftbysundell.com
- NSHipster: nshipster.com

**Community:**
- Swift Forums: forums.swift.org
- Stack Overflow: stackoverflow.com/questions/tagged/swift

---

## ✅ Pre-Release Checklist

Before distributing:

- [ ] App works on fresh Mac (no Xcode)
- [ ] First launch dialog appears
- [ ] Accessibility permission requested
- [ ] Hotkey converts text
- [ ] Preferences save and persist
- [ ] "Start at Login" works
- [ ] Menu bar icon visible
- [ ] All menu items functional
- [ ] No crashes or hangs
- [ ] Console shows no errors

---

## 🎯 Feature Ideas (Future)

**Easy:**
- [ ] Different menu bar icon when disabled
- [ ] Sound on successful conversion
- [ ] Show conversion history
- [ ] Export/import settings

**Medium:**
- [ ] Support 3+ keyboards (pick from list)
- [ ] Statistics (conversions per day)
- [ ] Undo last conversion
- [ ] Whitelist/blacklist apps

**Hard:**
- [ ] Auto-convert as you type (no hotkey)
- [ ] ML-based language detection
- [ ] iCloud settings sync
- [ ] iOS companion app

---

## 🆘 Emergency Fixes

**App won't launch:**
```bash
# Reset everything:
defaults delete com.yourname.LangOver
rm -rf ~/Library/Caches/com.yourname.LangOver
```

**Xcode is broken:**
```bash
# Delete derived data:
rm -rf ~/Library/Developer/Xcode/DerivedData/*
```

**Nuclear option:**
```bash
# Clean build folder: ⌘⇧K
# Quit Xcode
# Delete derived data (above)
# Restart Xcode
# Rebuild
```

---

**Print this page for quick reference!** 📄
