# Continue the Telepin Mac build

The user requested the Windows map/GPS movement app on an **Apple Silicon Mac** and will open this project in Codex there. This port was prepared on Windows; no compiled Mac DMG or verified Mac runtime exists yet. Preserve the Windows 0.3.0 release and existing user changes.

## Completed work

- Version 0.5.0. Windows packaging remains in `desktop/package.json`; `desktop/electron-builder.mac.cjs` is a separate Apple Silicon configuration.
- USB/Wi-Fi chooser and explicit **Set up Wi-Fi** on trusted USB. Wireless sessions use a dedicated encrypted tunnel and a peer key saved during USB setup; no silent USB fallback. Wi-Fi requires iOS 17.4+ and Python 3.13 with native TLS-PSK. The Mac environment is `.venv-mac-build-arm64-py313` so an older 3.12 environment is preserved.
- Mac engine paths, native traffic lights, application/Edit/Window/Help menus, Finder help, and protected Quit/reset behavior.
- Same movement UI with Mac setup copy and native titlebar spacing.
- Bounded POSIX process-group cleanup, including an orphaned setup worker, before reconnecting or exiting.
- Native architecture validation in `build_engine.py`. The Python runtime already supports Darwin USB discovery and the iOS 17.4+ userspace tunnel.
- `Build Mac.command` runs `scripts/build_mac.py`: tests, native arm64 engine, real Electron bridge checks, icon, DMG/ZIP packaging, signature/startup checks, and verification receipts after success.
- Source archive preserves executable command permissions and LF endings; excludes environments, dependencies, build output, and private device data.

## Finish on the Mac

1. Read `MAC-APP.md`. Confirm native Apple Silicon Python 3.13, Node.js 24+, Xcode Command Line Tools, and macOS 14+. Resolve missing local prerequisites; do not reuse Windows binaries or Rosetta environments.
2. Run `bash "Build Mac.command"` from this folder. Default output is ad-hoc signed, not Developer ID signed/notarized. Do not enable signing/notarization or upload to Apple without user instruction and existing credentials.
3. Fix actual native build/startup failures in this source tree. Run proportionate checks and the native build. Preserve movement serialization and reset/recovery handling.
4. Inspect the DMG and app. Test Finder installation, native window controls/menus, map interaction, GPX dialogs, saved routes, close, and Quit. Verify it starts without the development Python environment. Automated smoke checks do not contact an iPhone.
5. With the user's connected/trusted iPhone in Developer Mode, verify a user-selected location and short route in Maps, then verify Restore real GPS. Set up Wi-Fi over USB, disconnect, physically unplug the cable, and connect over Wi-Fi. Check pairing, discovery, location, route, idle connection-loss reporting, and restoration. Test wireless interruption followed by **Reconnect & restore** over both Wi-Fi and USB. Confirm movement never resumes automatically. Record the actual phone model/iOS and outcomes. A successful command or map animation does not prove phone behavior. If the phone rejects the peer-verification exchange, investigate it against actual device behavior; do not bypass the saved peer identity check.
6. Write a native verification report in `releases/mac-arm64`, verify hashes, and deliver the DMG and source companion. Until native checks pass, describe this as a Mac port/build handoff, not a tested installer.

## Existing checks

Windows-side checks cover Python/build logic, both Electron platform branches, POSIX lifecycle mocks, platform renderer fixtures, movement regressions at 1000×700, and real Windows Electron integration. They do not prove Mach-O packaging, native signing/window behavior, or physical iOS 26.7 compatibility.

Version 0.5.0 passed 125 Python tests and 112 desktop tests on 2026-10-06, plus platform/Wi-Fi/movement renderer fixtures, real Windows Electron integration and packaged startup checks. See [WIFI-VERIFICATION.md](WIFI-VERIFICATION.md) for the verification receipt and pending physical checks. These tests do not establish physical iPhone compatibility.

```text
.venv313\Scripts\python.exe -B -m unittest discover -s tests -v
cd desktop
npm test
npm run test:desktop
```

With a local Vite server, `node src/__tests__/platform.smoke.cjs` checks platform fixtures; `TELEPIN_FIXTURE_PLATFORM=darwin node src/__tests__/movement.smoke.cjs` checks Mac-mode movement. These block external map requests. The native build's real Electron integration does not require Chrome.

[PyInstaller requires platform-native builds](https://pyinstaller.org/en/stable/operating-mode.html). The Mac interface uses [Electron's native titlebar API](https://www.electronjs.org/docs/latest/tutorial/custom-title-bar).