# Platform APIs and thread restrictions

> Native modules are BTS-only, main-thread element ops are MTS-only; guard with mts / bts.

Source: https://haskell-miso.org/docs/native/platform-apis/

Mirroring Lynx ("not all APIs exist on both threads"), miso's native APIs are split by thread, and calling one from the wrong thread fails at runtime — the type system does not catch it, so guard with `mts` / `bts` when code may run on either thread. Neither module is re-exported from `Miso.Native`; import it directly.

## Native modules (BTS-only)

`Miso.Native.Module` wraps Lynx's global [NativeModules](https://lynxjs.org/guide/use-native-modules.html) (platform capabilities: storage, clipboard, device info, …). `callNativeModule` invokes a void-returning method and `callNativeModuleWith` a callback method whose result is decoded via `FromJSON`. `NativeModules` exists **only on the BTS**:

```haskell
callNativeModule "NativeLocalStorageModule" "setStorageItem"
  [ String "key", String "value" ]
```

`update` runs on the BTS by default, so this just works there; from a main-thread handler, hop to the BTS first with `runOnBG`. On the MTS the module is `undefined` and the call logs a console error.

## Main-thread element ops (MTS-only)

The imperative helpers in `Miso.Native.MainThread` (`setStyleProperty` etc.) and the element PAPI they call exist **only on the MTS**; on the BTS they no-op. Drive them from a `*Main` handler or via `runOnMain`.

| API | BTS | MTS |
| --- | --- | --- |
| `update` (default handlers, effects) | ✓ | via `runOnMain` |
| `Miso.Native.Module` (NativeModules) | ✓ | ✗ (undefined) |
| `Miso.Native.MainThread` (element ops, `eachFrame`) | ✗ (no-op) | ✓ |
| `MainThreadRef` | — | ✓ |
| `Sub` | ✓ (guard with `bts`) | ✓ (guard with `mts`) |
