# Android native layer

This directory is a Flet Flutter service extension. The Python `NativeBridge` control
sends small versioned commands over the extension; Kotlin owns the actual Android
lifecycle.

The native layer is deliberately split from the Flet Activity:

```text
Python/Flet -> FletService -> MethodChannel -> Kotlin bridge
                                      -> VpnRuntimeService (VpnService)
                                      -> ProxyRuntimeService (foreground service)
                                      -> FreeTurn/libbox adapters
```

`VpnRuntimeService` calls `VpnService.prepare()` through the bridge and starts foreground
immediately. The pinned libbox core asks `PlatformInterface.openTun()` to establish the
TUN from its effective config; this prevents a fake Connected state with an unowned
black-hole interface. Runtime state is persisted in `SharedPreferences`.

## Native artifacts

Put reviewable, pinned artifacts in `libs/` locally:

- `libbox.aar` from `Leadaxe/sing-box-lx`, version pinned in `libbox.version`.
- `freeturn.aar` may be kept for review, but is not packaged with libbox yet because
  their independently generated gomobile runtimes use conflicting global classes.

The files are git-ignored. Record version, commit and SHA-256 in
`THIRD_PARTY_NOTICES.md` before distributing an APK. `scripts/fetch-engine-artifacts.sh`
downloads the pinned libbox release and verifies its upstream `SHA256SUMS`.

`scripts/build-android.sh` extracts libbox's `classes.jar` and `jni/*` into
the packaged Flutter plugin. This is required because Gradle does not allow a direct
local `.aar` dependency while producing the plugin AAR. A missing artifact does not
make a smoke APK pretend to work: the corresponding adapter returns `UNSUPPORTED`.

The native milestone still needs physical-device testing for VPN consent, foreground
service timing, packet forwarding, hotspot interface discovery, VLESS and AmneziaWG.