# 🚀 Quick Setup Checklist

Follow these steps in order to get LangOver running:

## ✅ Pre-Flight Checks

- [ ] **macOS 13.0+** (Check: Apple menu → About This Mac)
- [ ] **Xcode 15.0+** installed from the Mac App Store
- [ ] Project open in Xcode

---

## 📦 Step 1: Add Package Dependency (5 minutes)

- [ ] In Xcode: **File → Add Package Dependencies...**
- [ ] Paste URL: `https://github.com/sindresorhus/KeyboardShortcuts`
- [ ] Click **"Add Package"** twice
- [ ] Wait for package to download (watch the progress in Xcode's top-right)

---

## ⚙️ Step 2: Project Settings (10 minutes)

### General Tab
- [ ] Click the **blue project icon** at the top of the file list
- [ ] In **General** tab:
  - [ ] Change **"Display Name"** to: `LangOver`
  - [ ] Set **"Minimum Deployment"** to: `macOS 13.0`

### Signing & Capabilities Tab
- [ ] Switch to **"Signing & Capabilities"** tab
- [ ] Click **"+ Capability"** button
- [ ] Add: **"App Sandbox"**
- [ ] In App Sandbox section, check: ✓ **Accessibility**
- [ ] Click **"+ Capability"** again
- [ ] Add: **"Hardened Runtime"**

### Info Tab
- [ ] Switch to **"Info"** tab
- [ ] Click the **"+"** next to "Custom macOS Application Target Properties"
- [ ] Add new property:
  - **Key**: Type `Application is agent` (it will auto-complete to "Application is agent (UIElement)")
  - **Type**: Boolean
  - **Value**: YES (toggle it on)

---

## 🗑️ Step 3: Clean Up Old Files (2 minutes)

- [ ] In the file list, find **"LangToLangApp.swift"** (the one with `@main`)
- [ ] Right-click it → **"Delete"** → **"Move to Trash"**
- [ ] Verify that **"LangOverApp.swift"** is now in the file list (this is our new main file)

---

## 🏗️ Step 4: Verify File Structure (3 minutes)

Make sure all these files appear in your project (on the left side):

**Core Files:**
- [ ] `LangOverApp.swift` ← Main entry point
- [ ] `AppDelegate.swift` ← Menu bar manager
- [ ] `ContentView.swift` ← Updated view

**Models:**
- [ ] `Settings.swift`
- [ ] `KeyboardLayout.swift`

**Services:**
- [ ] `KeyboardDetector.swift`
- [ ] `LayoutConverter.swift`
- [ ] `AccessibilityService.swift`
- [ ] `HotkeyService.swift`

**Views:**
- [ ] `FirstLaunchView.swift`
- [ ] `PreferencesView.swift`

**Configuration:**
- [ ] `Info.plist`

**Documentation:**
- [ ] `README.md`
- [ ] `KEYBOARD_MAPPING.md`
- [ ] `SETUP_CHECKLIST.md` (this file!)

---

## 🔍 Step 5: Check Target Membership (5 minutes)

Sometimes Xcode doesn't automatically add files to the build target. Let's verify:

1. [ ] Select **any Swift file** in the file list (e.g., `Settings.swift`)
2. [ ] Open the **File Inspector** (right sidebar, first tab - looks like a document icon)
   - If you don't see it: **View → Inspectors → File Inspector**
3. [ ] Under **"Target Membership"**, make sure your app target is **checked** ✓
4. [ ] Repeat for a few other files to verify

**If any file is NOT checked:**
- [ ] Check the box next to your app target name
- [ ] Repeat for all Swift files

---

## ▶️ Step 6: Build and Run (5 minutes)

- [ ] Select **"My Mac"** as the run destination (top-left, next to ▶️ button)
- [ ] Click the **▶️ Play button** (or press Cmd+R)
- [ ] Wait for the build to complete

**If you see build errors:**
- [ ] Read the error message carefully
- [ ] Common issues:
  - **"Cannot find 'KeyboardShortcuts' in scope"** → Go back to Step 1
  - **"Multiple commands produce 'LangOverApp.swift'"** → Make sure you deleted the old app file in Step 3
  - **"No such module 'SwiftUI'"** → Check your deployment target is macOS 13.0+

---

## 🎉 Step 7: First Run Experience (5 minutes)

If the build succeeds, you'll see:

1. **First Launch Dialog**
   - [ ] Dialog appears showing detected keyboards
   - [ ] All keyboards are pre-checked
   - [ ] Click **"Continue"**

2. **Accessibility Permission Alert**
   - [ ] Alert appears asking for permission
   - [ ] Click **"Open System Settings"**
   - [ ] In System Settings → Privacy & Security → Accessibility:
     - [ ] Find **"LangOver"** in the list
     - [ ] Toggle it **ON** (you may need to click the lock icon first)
   - [ ] Close System Settings

3. **Menu Bar Icon**
   - [ ] Look at the **top-right corner** of your Mac screen
   - [ ] You should see a small "abc" icon (or similar)
   - [ ] Click it to see the menu

---

## 🧪 Step 8: Test the App (10 minutes)

### Test 1: Basic Conversion
1. [ ] Open **TextEdit** or **Notes**
2. [ ] Type some English text: `akuo`
3. [ ] Select the text you just typed
4. [ ] Press **Ctrl+Shift+Space**
5. [ ] The text should change to: `שלום` (Hebrew)

### Test 2: Reverse Conversion
1. [ ] Select the Hebrew text: `שלום`
2. [ ] Press **Ctrl+Shift+Space** again
3. [ ] It should convert back to: `akuo`

### Test 3: Cursor-to-Line-Break
1. [ ] Type new text: `hello world`
2. [ ] Place cursor at the end (after "world")
3. [ ] **Don't select anything**
4. [ ] Press **Ctrl+Shift+Space**
5. [ ] All text should convert

### Test 4: Menu Bar Controls
1. [ ] Click the **LangOver menu bar icon**
2. [ ] Click **"Disable"**
3. [ ] Try pressing Ctrl+Shift+Space → Nothing should happen
4. [ ] Click the icon again → Click **"Enable"**
5. [ ] Try the hotkey again → Should work

### Test 5: Preferences
1. [ ] Click menu bar icon → **"Preferences"**
2. [ ] Preferences window opens
3. [ ] Try unchecking a keyboard (leave at least 2 checked)
4. [ ] Try changing the hotkey:
   - [ ] Click the hotkey recorder
   - [ ] Press a new combination (e.g., Cmd+Shift+L)
   - [ ] Close preferences
   - [ ] Test the new hotkey

---

## ✅ Final Verification

- [ ] App appears in menu bar ✓
- [ ] Hotkey converts selected text ✓
- [ ] Hotkey converts from cursor to line break ✓
- [ ] Preferences window opens and saves changes ✓
- [ ] Enable/Disable toggle works ✓
- [ ] App requests Accessibility permission ✓

---

## 🐛 Troubleshooting

### "App doesn't appear in menu bar"
- [ ] Check that `LSUIElement` is set to YES in Info.plist (or "Application is agent" in Info tab)
- [ ] Look carefully at the top-right corner (it might be small)
- [ ] Try restarting the app

### "Build fails with 'Cannot find KeyboardShortcuts'"
- [ ] File → Add Package Dependencies → Add KeyboardShortcuts package
- [ ] Clean build folder: Product → Clean Build Folder
- [ ] Rebuild: Cmd+B

### "Hotkey doesn't work"
- [ ] Open System Settings → Privacy & Security → Accessibility
- [ ] Make sure LangOver is in the list and enabled
- [ ] Click the menu bar icon - make sure it says "Disable" (meaning it's enabled)

### "Can't see any files in Xcode"
- [ ] Make sure you opened the `.xcodeproj` file, not just a folder
- [ ] Try View → Navigators → Project (Cmd+1)

### "App crashes on launch"
- [ ] Check the Console in Xcode (View → Debug Area → Show Debug Area)
- [ ] Look for red error messages
- [ ] Most common: Missing KeyboardShortcuts package

---

## 🎊 Success!

If all tests pass, congratulations! You now have a fully functional keyboard layout converter app!

### What's Next?

- [ ] **Read README.md** for customization options
- [ ] **Read KEYBOARD_MAPPING.md** to understand how conversion works
- [ ] **Add support for more languages** (Russian, Arabic, etc.)
- [ ] **Customize the menu bar icon** (see README.md)
- [ ] **Share the app** with friends (see README.md for distribution instructions)

---

## 📞 Need Help?

If something doesn't work:

1. Check the **Console** in Xcode (View → Debug Area)
2. Look for error messages (red text)
3. Google the error message
4. Make sure all steps above are checked off

---

**Estimated Total Time: ~45 minutes**

Good luck! 🚀
