ping-openmls-sdk-react-native-macos 0.2.0

package/README.md

@@ -0,0 +1,64 @@
+# `ping-openmls-sdk-react-native-macos`
+
+> **Status:** stage 1 of [docs/RN_NATIVE_BINDINGS.md](../../docs/RN_NATIVE_BINDINGS.md) —
+> Rust build pipeline only. The Pod, Swift bridge, and JS API land in stages 2–4.
+
+Real MLS for React Native macOS apps. Wraps the same Rust core (`core/ping-core` →
+`core/ping-ffi`) that iOS, Android, and Web use, packaged as a TurboModule for RN-macOS.
+
+## Build the native artefact
+
+```bash
+# From repo root, on macOS:
+./scripts/build-macos.sh
+```
+
+The script:
+
+1. Adds Rust targets `aarch64-apple-darwin` and `x86_64-apple-darwin` if missing.
+2. Cross-compiles `ping-openmls-sdk-ffi` for both targets at `MACOSX_DEPLOYMENT_TARGET=10.15`.
+3. `lipo`s the two `.a`s into a universal static archive at
+   `bindings/react-native-macos/Frameworks/libping_ffi.a`. CocoaPods links this directly
+   into the host app's binary at build time — no runtime dylib loading, no rpath setup.
+4. Runs `uniffi-bindgen` (Swift target) to produce `Generated.swift`, `pingFFI.h`, and
+   `module.modulemap` in `ios/`.
+
+All output is gitignored — re-run the script after pulling new commits to the Rust core.
+
+## Layout
+
+| Path | Source / Generated | Purpose |
+|---|---|---|
+| `Frameworks/libping_ffi.a` | generated by `build-macos.sh` | Universal arm64+x86_64 static lib (linked into host app) |
+| `ios/Generated.swift` | generated by `uniffi-bindgen` | Swift type wrappers around the C ABI |
+| `ios/pingFFI.h` | generated | C header |
+| `ios/module.modulemap` | generated | Clang module map for Swift import |
+| `ios/PingNativeModule.swift` | hand-written (stage 2+) | RN TurboModule entry point |
+| `ios/PingStorageBridge.swift` | hand-written (stage 3) | Storage callback marshalling |
+| `ios/PingTransportBridge.swift` | hand-written (stage 3) | Transport callback marshalling |
+| `src/index.ts` | hand-written (stage 4) | JS API mirror of `ping-openmls-sdk` |
+| `src/NativePing.ts` | hand-written (stage 4) | TurboModule TS spec for codegen |
+| `package.json` | hand-written (stage 2) | npm metadata |
+| `ping-openmls-sdk-react-native-macos.podspec` | hand-written (stage 2) | Pod descriptor for autolinking |
+
+## Architecture
+
+Despite the `ios/` directory name, this Pod targets **macOS** (RN-macOS uses the same
+CocoaPods conventions). The dylib in `Frameworks/` is the actual universal macOS binary;
+`ios/` holds the Swift sources that load it.
+
+See [docs/RN_NATIVE_BINDINGS.md](../../docs/RN_NATIVE_BINDINGS.md) for the full bridge
+architecture, including the Storage/Transport callback marshalling pattern.
+
+## Non-breaking guarantees
+
+This package and its build script (`scripts/build-macos.sh`) are entirely additive. They
+do not touch:
+
+- `bindings/swift/` (iOS xcframework)
+- `bindings/kotlin/` (Android AAR)
+- `sdk/js/` (web SDK)
+- `core/ping-ffi/src/ping.udl` (the canonical FFI surface)
+- Any existing build script or CI job
+
+Rebuilding iOS, Android, or the WASM bundle is unaffected by this package.