# ScopeDOPE iOS — Session Handoff

**Last updated:** 2026-06-14 · **Read this first when resuming.**

---

## TL;DR

Building the **ScopeDOPE iPhone app** from the company documentation + the existing Android
codebase. We are in **Phase 0–1**. The ballistics engine has been vendored into `iOS/` and
made iOS-ready; the built-in ammo data has been vendored. Nothing has been compiled yet
(no Mac available). Next concrete steps are listed below.

---

## The hard constraint (do not violate)

The iOS build is a **new, fully self-contained project under `C:\ClaudeCode\ScopeDope\iOS\`**.
- **Do not modify** any file outside `iOS/`.
- **Do not build-depend on** `ScopeDOPE/scopedope-android-main/` or
  `ScopeDOPE/scopedope-shared-main/` — they are **read-only references only**.
- Anything needed is **vendored** (copied into `iOS/` and maintained independently).
  No external reliances.

## Locked decisions

- **Engine:** XCFramework built from the Kotlin Multiplatform `:ballistics` engine (NOT a
  from-scratch Swift re-implementation) — guarantees < 0.01 mil parity with Android.
- **UI/stack:** Swift + SwiftUI, MVVM, iOS 16 min, **portrait-only + dark-only**, bundle id
  `com.coldboreballisticsllc.scopedope`. GRDB (ammo), Codable (`.dope`), CoreBluetooth,
  CoreLocation, Sentry Cocoa (opt-in/OFF).
- **Environment:** macOS + Xcode is being acquired. Until then, only Windows-side prep
  (Kotlin edits, model/`.dope` design) is possible — no iOS binary can be produced.

---

## What's DONE

### Phase 0 — engine (vendored + iOS-ready)
`iOS/engine/` is a standalone KMP project (own Gradle wrapper, settings, version catalog):
- Vendored the 4 `commonMain` engine files + `MultiZoneBcTest.kt` (independent copies).
- **Fix 1:** replaced all 7 `java.lang.Math.toRadians(...)` calls with a multiplatform
  `toRadians(deg)` helper (`kotlin.math.PI`) so `commonMain` compiles for Kotlin/Native.
- **Fix 2:** `engine/ballistics/build.gradle.kts` adds `iosArm64/iosX64/iosSimulatorArm64`
  packaged as the `ScopeDopeBallistics` XCFramework; dropped `androidTarget()`/Android SDK;
  kept `jvm()` for headless tests.
- Originals in `scopedope-shared-main` confirmed untouched.

### Phase 1 — built-in ammo data (vendored)
`iOS/assets/ammo/` (SHA-256-verified copies): `databases/ammo_builtin.db` (read-only,
130 loads / 28 calibers), `ammo_builtin.csv` (source of truth), `build-ammo-db.py`,
`schema/BuiltinAmmoDatabase_v4.json` (Room v4 schema to mirror in GRDB), + README.

---

## What's NEXT (in order)

1. **[needs Mac/JDK] Verify the engine builds:** `cd iOS/engine && ./gradlew :ballistics:jvmTest`
   (runs on any OS with a JDK — this is the first green checkpoint and can be done before the
   Mac if a JDK + the Kotlin toolchain are installed).
2. **[needs macOS] Build the XCFramework:**
   `./gradlew :ballistics:assembleScopeDopeBallisticsXCFramework` → lands in
   `engine/ballistics/build/XCFrameworks/`. Then an iOS smoke test: 3 known cases vs. JVM (< 0.01 mil).
3. **Vendor the `.dope` schema** into `iOS/` (from the `dope-format` repo, if/when obtained;
   the Android `DopeSessionSerializer.kt` is a usable reference until then) — needed before
   the `.dope` Codable layer.
4. **Phase 1 Swift work (Windows-authorable):** design Swift domain structs (mirror
   `Models.kt`), the `.dope` Codable types (v3), and the `UserDefaults` prefs wrapper
   (SPEC Appendix D). Plan the `ammo_user.db` (writable, same schema + `is_user_defined=1`,
   migrations mandatory, no destructive fallback).
5. Then Phases 2→8 per `ScopeDOPE_iOS_BUILD_PLAN.md`.

---

## Key reference locations (read-only)

- **SPEC (authoritative requirements):** `ScopeDOPE/04_-_Highly_Confidential/SPEC/ScopeDOPE/`
  — `SPEC.md`, `SPEC_data_engine.md`, `SPEC_features.md`, `SPEC_nonfunc_appendices.md`.
- **Engine white paper (math):** `ScopeDOPE/04_-_Highly_Confidential/Engine_Documentation/SCOPEDOPE_BALLISTICS_ENGINE_TECHNICAL_WHITE_PAPER.md`.
- **UI design tokens:** `CBB_Corporate/03_-_Confidential/Style_Guides/UI_DESIGN_STYLE_GUIDE.md`.
- **Android app (parity reference):** `ScopeDOPE/scopedope-android-main/` — engine API
  contract in `app/.../domain/usecase/CalculateDopeUseCase.kt`; models in
  `domain/model/Models.kt`; BLE drivers in `data/sensor/*`, `data/printer/niimbot/*`;
  renderers in `label/renderer/*`; `.dope` in `data/session/DopeSessionSerializer.kt`.
- **Original engine source:** `ScopeDOPE/scopedope-shared-main/ballistics/` + validation
  corpus (39 JSONs) in `ballistics-test-data/test_cases/`.

## Still missing / external

- **macOS + Xcode** (hard prerequisite for any iOS binary).
- **`dope-format` repo** (the `.dope` v3 JSON Schema) — not yet on disk.
- Apple Developer account (TestFlight); BLE hardware (Niimbot/sensors) for later device tests.
- Fonts IBM Plex Mono + Inter (open source, bundle when doing UI).

---

## Companion docs in this folder

- `README.md` — folder overview + how to build the engine.
- `ScopeDOPE_iOS_BUILD_PLAN.md` — the full phased plan (Phases 0–8, critical path).
- `assets/ammo/README.md` — ammo data provenance + schema + iOS usage.

> Persistent cross-session memory also exists (project + engine-blockers notes); this file is
> the human-readable, in-repo source of truth for where we left off.
