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.

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 for compiled integrations.

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.

Authentication and credentials#

oro: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 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. 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 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 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 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 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 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 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 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 and runtime reliability references. Linux native integration explains session hosting, provider selection, cancellation, notification privacy, and cold activation.

Android window presentation and sharing#

ApplicationWindow 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 and Android native state.

Continue#

• Native execution and push
• Declarative workflows
• Historical migration
• Runtime 0.2 releases