# Native platform services

Check backend support before showing a native action. An import succeeding does not mean the operation is implemented, enabled, permitted, or supported by the device.

```js
import platform from 'oro:platform'
import foreground from 'oro:foreground'

const backend = await platform.getSupport('foreground')
if (backend.implementation === 'implemented') {
  const support = await foreground.getSupport()
  console.log(support.available, support.canStart, support.registeredKinds)
} else {
  console.log(backend.platform, backend.reason)
}
```

`getCapabilities()` and `getSupport(feature)` read the compiled inventory without prompting or accessing saved values. Descriptors distinguish `implemented`, `missing`, and `restricted`; `requiresRuntimeCheck` points to the feature's own probe. Unknown feature names reject. Older binaries without the support route still reject: use a matched CLI/API/native SDK installation.

## Choose a backend deliberately

For custom registered native extensions, `platform.request(extension, action, payload, { signal })` sends an extension operation through the native bridge. The extension defines its action/payload contract; this does not dynamically supply a missing backend. Requests remain owned by the originating document and can discard late results after cancellation. See the [native service binding reference](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/NATIVE_SERVICE_BINDINGS.md) for compiled integrations.

| Service | Android | Linux | macOS, iOS/iPadOS, Windows |
| --- | --- | --- | --- |
| Authentication-bound keys | Keystore and system prompt | TPM2 / hardware PKCS#11 with explicit provider-PIN policy | New backend missing |
| Explicit password selection | Credential Manager | Secret Service chooser | New backend missing |
| Finite foreground work | Data-sync service | Native executor; optional session host | New backend missing |
| Continuous foreground work | Opt-in special-use service | Native executor; optional session host | Missing; iOS unbounded background execution is restricted |
| Deferred native work | JobScheduler | Durable native scheduler; optional session host | New backend missing |
| UnifiedPush | Native connector | D-Bus connector; optional cold session host | New backend missing |
| Launcher publication | Shortcuts | Desktop actions and receipts; no pin flow | New backend missing |
| Declarative workflows and historical migration | Bundled Android executors | High-level executors missing | High-level executors missing |
| New channel/group notification submission | Android channels/groups | Freedesktop transport and app policies; no Android grouping | New submission backend missing; existing notification APIs remain separate |

Unavailable support probes preserve a reason. Operational calls reject with `ENOSYS`; permission, busy, storage, protocol, and cancellation errors remain distinct. This table describes the newer interfaces, not all existing window, notification, secure-storage, or extension APIs. See the [full native inventory](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/NATIVE_PLATFORM_PARITY.md).

## Authentication and credentials

[`oro:authentication`](/runtime/docs/javascript/authentication/) binds encryption and signing to a native cryptographic authentication operation. Query `getStatus({ policy: 'biometric-or-device' })` before offering the action. Linux biometric-only mode is restricted; Secret Service storage alone does not provide authentication-bound hardware keys. Seal/open failures after enrollment changes or missing keys need explicit recovery. Do not replace retained ciphertext automatically.

`createSigningKey` and `signChallenge` operate on a fresh authority/account-bound server challenge. The application still verifies server authority, enrolls/revokes keys, and reconciles sessions. A successful local prompt is not server authentication.

[`oro:credentials`](/runtime/docs/javascript/credentials/) is an explicit user password-provider action. Check `getStatus()` and invoke `selectPassword()` from the user's sign-in action. It is separate from automatic autofill and from [`oro:secure-storage`](/runtime/docs/javascript/secure-storage/). Do not log returned passwords. New request options carry an `AbortSignal`; cancellation belongs to the originating document.

## Android and Linux interface integration

- **Launcher destinations:** use [`oro:launcher`](/runtime/docs/javascript/launcher/) with `[launcher] enabled = true`. Resolve receipt identities after restoring sign-in. Publication and pin submission do not authorize a target or confirm user pinning.
- **Document providers:** [`oro:document-access`](/runtime/docs/javascript/document-access/) lists, persists, releases, and inspects Android picker-granted URIs. It cannot grant arbitrary access. Directory reads return bounded pages; handle `truncated` and `nextOffset`.
- **Network paths:** [`oro:network-status`](/runtime/docs/javascript/network-status/) observes Android/Linux OS status. Subscribe before taking the initial snapshot. Validated connectivity is not a probe of your application server; Linux does not invent unavailable transport details.
- **Haptics:** [`oro:haptics`](/runtime/docs/javascript/haptics/) requests Android selection/confirmation/rejection feedback only with the app's explicit saved opt-in. System feedback settings remain authoritative. Other platforms reject enabled requests with `ENOSYS`.
- **Back handling:** [`oro:window/back`](/runtime/docs/javascript/window/) installs a bounded handler on Android or Linux GTK/WebKit. Return whether the app handled Back; respect the deadline and dispose the handler with the view.
- **Insets and gestures:** [`oro:window/appearance`](/runtime/docs/javascript/window/) observes native insets and Back gestures and sets bounded Android edge-exclusion regions. Android's acceptance of a requested rectangle is not independently confirmed. Preserve system navigation and let native text scaling operate without applying the OS scale twice.
- **Notifications:** [`oro:notification`](/runtime/docs/javascript/notification/) adds channel/group inspection, submission and response handling. Permission, channel policy, submission, display, and human attention are separate results. Native notification identifiers correlate workflow/push events; cancellation alone does not release workflow deduplication state.

For Android integration and managed-window/lifecycle details, use the pinned [native integration](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/ANDROID_NATIVE_INTEGRATION.md) and [runtime reliability](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/ANDROID_RUNTIME_RELIABILITY.md) references. Linux [native integration](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/LINUX_NATIVE_INTEGRATION.md) explains session hosting, provider selection, cancellation, notification privacy, and cold activation.

## Android window presentation and sharing

[`ApplicationWindow`](/runtime/docs/javascript/window/) adds explicit startup and presentation controls:

- `markReady()` acknowledges a usable mounted screen with its required styles. Apps configured with `[webview] require_ready = true` keep native startup recovery armed until this acknowledgement. Only the current window acknowledges its own readiness; this does not establish application authorization.
- `markPresented()` reveals a verified bundled Android startup screen after a native visual-state fence. It does not acknowledge readiness or stop the 30-second native watchdog. Keep application controls inert until the usable screen calls `markReady()`; failed startup restores native recovery and Reload.
- `setSystemAppearance({ theme, color, insets })` selects Android 11+ system-bar icon contrast, an opaque `#rrggbb` surface, and explicit `native` or `web` inset ownership. Remove competing app-owned native inset listeners before adopting it to avoid double padding.
- `setFullscreen(true)` first requires explicit inset ownership. Android's Exit fullscreen control, Back, suspension, hiding, and renderer destruction can exit presentation; observe `windowfullscreenchange`. Native fullscreen is separate from browser DOM fullscreen and does not capture the pointer or hide the keyboard. `getFullscreenState()` reads the native state.
- `setContentProtection(true)` requests Android `FLAG_SECURE` while the window is visible. It protects the native Activity's ordinary screenshots/recents, not clipboard, exported files, external displays, or already-exported secrets. Coordinate other native flag owners.

The appearance/fullscreen APIs require Android 11+; content protection and Android-specific startup presentation are not universal cross-platform window capabilities. Unsupported operations reject with `ENOSYS`. Android creation/show/hide/close can reject `ENOTREADY` while Activity state is saved or unavailable; retry the intended action after resume rather than assuming a window was attached.

Android `window.share({ files })` supports up to 16 files and 8 MiB total. New recipient opens expire after 24 hours, but a recipient can retain a copy. Resolution means a share target was selected, not delivery or consumption. Keep sharing tied to an explicit user action and use the ordinary text/URL share path where file sharing is unavailable.

## Native records and coordination

Trusted C++20 integrations use `RecordStore` and `RecordCoordinator` with the secure-storage service's native key provider. Run blocking record/key-store calls off UI/event-loop callbacks and drain workers before stopping the runtime. This is not a public JavaScript record API.

The shared v2 format provides encrypted records, authenticated scope/revision metadata, compare-and-swap updates, and durable operation state. Preserve `ESTALE`, `EBUSY`, `EBADMSG`, `EKEYREVOKED`, and `EACCES` failures. Interrupted execution becomes `unknown`; inspect durable state and reconcile with the remote authority instead of replaying a mutation. A local receipt does not prove server authorization or transfer completion.

Android Kotlin v1 retains its own format and namespace. C++ v2 being compiled on Android, Apple platforms, Linux, or Windows does not automatically migrate v1 records or qualify each OS key service. The high-level Android workflow/migration executors remain Android-only. See [record formats and limits](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/NATIVE_PLATFORM_PARITY.md#native-encrypted-records-and-operation-coordination) and [Android native state](https://github.com/oro-computer/runtime/blob/v0.2.1/docs/ANDROID_NATIVE_STATE.md).

## Continue

- [Native execution and push](/runtime/docs/guides/native-execution-and-push/)
- [Declarative workflows](/runtime/docs/guides/declarative-workflows/)
- [Historical migration](/runtime/docs/guides/historical-migration/)
- [Runtime 0.2 releases](/runtime/docs/guides/releases-0-2/)