# Building and checking native Docs

The native editor uses SwiftUI with AppKit/UIKit text controls and a bounded
WASM interpreter for the shared Yjs-compatible CRDT. It does not load a web editor.

Requirements: Xcode 26, XcodeGen, Swift 6.2+, Node/npm, and Rust with the
`wasm32-unknown-unknown`, `aarch64-apple-darwin`, `x86_64-apple-darwin`,
`aarch64-apple-ios`, `aarch64-apple-ios-sim`, and `x86_64-apple-ios` targets.
The server gate additionally requires the Go version in `go.mod`.

Run the native gate from the repository root:

```sh
native/scripts/check-native.sh
```

It builds the CRDT WASM, runs Rust editor and bounded-host tests, checks native
and browser updates in both directions (including every list-rule reversal delta
and its authoritative snapshot), prepares the Apple XCFramework, and
runs Swift adapter/actor tests. `--core-only` runs the Rust and wire checks on
Linux. CI invokes this through `.amadan/ci.d/20-native`, alongside the existing
server/web gate. `--mutations` additionally proves representative faulty changes
are caught, restoring every changed source and saving logs under
`native/build/mutation-logs`. Do not run mutations concurrently with builds.

`CARGO` can select a non-default Cargo executable; put its matching Rust toolchain
on `PATH`. If that toolchain needs an explicit LLVM runtime lookup path, set
`DOCS_LLVM_LIBRARY_PATH`. No generated native framework is committed.

Build individual applications:

```sh
native/scripts/build-mac.sh
native/scripts/build-iphone.sh simulator
OFICINA_DEVELOPMENT_TEAM=YOUR_TEAM native/scripts/build-iphone.sh device
```

The suite's `build-native-apps.py` prepares the native framework and Xcode projects
once, then runs Docs and Sheets builds concurrently with separate platform logs
and a combined `results.json`. Its default targets are Mac and iOS Simulator;
`--platforms mac simulator device` also builds signed device applications when
`OFICINA_DEVELOPMENT_TEAM` is set. It does not install or publish applications.

Native UI tests use fresh local credentials and isolated databases. See
[REVIEW.md](REVIEW.md) for their runner, exact evidence, and untested behavior.
Performance measurements and their limits are in
[benchmarks/README.md](benchmarks/README.md).