@symbiote-native/web-browser 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @symbiote-native/web-browser
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-web-browser`](https://github.com/expo/expo/tree/main/packages/expo-web-browser) — an in-app
+browser (`SFSafariViewController` on iOS, Chrome Custom Tabs on Android) plus the OAuth
+auth-session flow — usable from **every** adapter, React, Vue, and Angular, not just React. Built
+the same way as [`@symbiote-native/secure-store`](../secure-store): an `expo-modules-core`-based
+wrapper (see the `symbiote-expo-native-module` project skill for the full mechanism — why
+`expo-modules-core` is depended on directly and never the `expo` meta-package, why the upstream JS
+is hand-ported into `core/` rather than imported, and how autolinking picks up the native module).
+
+## Install
+
+```bash
+npm install @symbiote-native/web-browser
+```
+
+`expo-web-browser` and `expo-modules-core` come along as regular, pinned dependencies — never
+install either yourself, and never add the `expo` meta-package to this project (it bundles its own
+Metro/Babel pipeline that conflicts with this project's own).
+
+### Required one-time step: native autolinking wiring
+
+Unlike a plain RN native module, `expo-web-browser`'s native code is discovered by
+`expo-modules-autolinking` — this needs wiring into the native host app **once**, covering this
+package and every other `expo-modules-core` package with zero further changes:
+
+| Platform | Touches |
+|---|---|
+| iOS | `ios/Podfile` — add `use_expo_modules!` |
+| iOS | `AppDelegate.swift` — Expo's runtime-bootstrap hook |
+| Android | `settings.gradle` / `app/build.gradle` — resolve and include the Expo Gradle projects |
+| Android | `MainApplication.kt` — Expo's bootstrap hook, plus a native-module name map |
+
+Full mechanics live in the `symbiote-expo-native-module` skill. The per-package half of that table
+— the Gradle dependency and the module map entry — is generated by
+[`@symbiote-native/expo-modules-link`](../expo-modules-link) from this package's `native-link.json`
+on every install. No `Info.plist` usage description is needed, and the `<queries>` entry Android
+needs to see the Custom Tabs service ships inside `expo-web-browser`'s own manifest and merges into
+your app automatically.
+
+## Shape
+
+```
+src/core/                 the whole API: open/dismiss, the auth session, and the Custom Tabs
+                          service functions. native-module.ts resolves ExpoWebBrowser through
+                          expo-modules-core's requireNativeModule.
+src/react/                @symbiote-native/web-browser/react
+src/vue/                  @symbiote-native/web-browser/vue
+src/angular/              @symbiote-native/web-browser/angular
+```
+
+All three adapter entries are plain re-exports of `core/`. Every export is a stateless free
+function; the one piece of live state — the Android auth-session polyfill's redirect subscription —
+belongs to a single in-flight promise inside the core and never surfaces as something a caller
+subscribes to or tears down. So there is nothing for a hook, composable, or service to wrap, the
+same reason [`@symbiote-native/secure-store`](../secure-store) re-exports rather than wraps. Import
+from `@symbiote-native/web-browser` directly if you don't care which adapter you're on; the
+per-adapter subpaths exist so every wrapper package has the same import surface.
+
+## Use it
+
+```ts
+import * as WebBrowser from '@symbiote-native/web-browser';
+
+await WebBrowser.openBrowserAsync('https://example.com');
+```
+
+The in-app browser keeps the user inside the app, unlike `Linking.openURL`, which hands them off to
+the system browser. iOS resolves once the browser closes (`{ type: 'cancel' }`, or
+`{ type: 'dismiss' }` if you closed it yourself with `dismissBrowser()`); Android resolves with
+`{ type: 'opened' }` as soon as the Custom Tab launches and never reports the close.
+
+A login flow that redirects back into the app:
+
+```ts
+const result = await WebBrowser.openAuthSessionAsync(
+  'https://auth.example.com/authorize?…&redirect_uri=myapp://callback',
+  'myapp://callback',
+);
+
+if (result.type === 'success') {
+  const code = new URL(result.url).searchParams.get('code');
+}
+```
+
+iOS uses `ASWebAuthenticationSession`, so the system asks the user whether the app may authenticate
+with that url, and the redirect URI registered with the authorization server has to use the app's
+own scheme (`myapp://`, not `https://`). Android has no equivalent, so it is polyfilled with a
+Custom Tab racing `Linking` against `AppState` — adding your own `Linking` listener for the same
+redirect is unnecessary on both, and on iOS can have side effects.
+
+Warming the Custom Tabs service up before you need it, on Android:
+
+```ts
+const { servicePackage } = await WebBrowser.warmUpAsync();
+await WebBrowser.mayInitWithUrlAsync('https://example.com', servicePackage);
+// …later
+await WebBrowser.coolDownAsync(servicePackage);
+```
+
+## API
+
+| Export | Signature | Notes |
+|---|---|---|
+| `openBrowserAsync` | `(url, options?) => Promise<IWebBrowserResult>` | Opens the in-app browser. |
+| `dismissBrowser` | `() => Promise<IWebBrowserDismissResult>` | iOS only — throws elsewhere, since a Custom Tab cannot be closed programmatically. |
+| `openAuthSessionAsync` | `(url, redirectUrl?, options?) => Promise<IWebBrowserAuthSessionResult>` | Resolves `{ type: 'success', url }` on the redirect. |
+| `dismissAuthSession` | `() => void` | iOS only, for the same reason as `dismissBrowser`. |
+| `warmUpAsync` | `(browserPackage?) => Promise<IWebBrowserWarmUpResult>` | Android. Resolves `{}` elsewhere. |
+| `mayInitWithUrlAsync` | `(url, browserPackage?) => Promise<IWebBrowserMayInitWithUrlResult>` | Android. Resolves `{}` elsewhere. |
+| `coolDownAsync` | `(browserPackage?) => Promise<IWebBrowserCoolDownResult>` | Android. Resolves `{}` elsewhere. |
+| `getCustomTabsSupportingBrowsersAsync` | `() => Promise<IWebBrowserCustomTabsResults>` | Android. Throws on iOS — see the note below. |
+| `WebBrowserResultType` | `enum` | `CANCEL`, `DISMISS`, `OPENED`, `LOCKED`. |
+| `WebBrowserPresentationStyle` | `enum` | iOS modal presentation styles for `options.presentationStyle`. |
+
+`IWebBrowserOpenOptions`: `toolbarColor`, `enableBarCollapsing`; Android's `browserPackage`,
+`secondaryToolbarColor`, `showTitle`, `enableDefaultShareMenuItem`, `showInRecents`, `createTask`,
+`useProxyActivity`; iOS's `controlsColor`, `dismissButtonStyle`, `readerMode`, `presentationStyle`.
+`IAuthSessionOpenOptions` adds iOS's `preferEphemeralSession` and `preferUniversalLinks`.
+
+## Not ported
+
+- **The `experimentalLauncherActivity` config plugin.** Upstream's
+  `plugin/src/withWebBrowserAndroid.ts` exists only for that opt-in flag: it writes a
+  `BrowserLauncherActivity.kt` into the consuming app and registers it as the launcher activity in
+  the app's `AndroidManifest.xml`, as a workaround for a specific redirect edge case. It is opt-in
+  upstream and unnecessary for `openBrowserAsync`, `openAuthSessionAsync`, or anything else on this
+  page, so this package does not reproduce it. An app that genuinely wants that workaround adds the
+  activity by hand.
+- **`maybeCompleteAuthSession`.** Genuinely web-only: it closes the `window.open` popup the web
+  implementation of `openAuthSessionAsync` created. On a native platform upstream's own version can
+  only ever return `{ type: 'failed', message: 'Not supported on this platform' }`, so it is left
+  out rather than shipped as a function that can never succeed.
+- **The web-only open options** `windowName` and `windowFeatures`, for the same reason —
+  SymbioteNative has no web target, so nothing could read them.
+
+## Notes
+
+- **`getCustomTabsSupportingBrowsersAsync` throws on iOS rather than resolving empty.** iOS's
+  native module registers its no-op stub as `getCustomTabsSupportingBrowsers`, without the `Async`
+  suffix, so the availability check fires before the "not Android, return an empty result" branch
+  is reached. Upstream behaves identically; the guard order is kept deliberately so this package
+  and `expo-web-browser` cannot drift. Branch on `Platform.OS === 'android'` yourself if you call
+  it cross-platform.
+- **Colors are marshalled before the native call.** `toolbarColor`, `secondaryToolbarColor` and
+  `controlsColor` go through `processColor`, so any React Native color format works.
+- **Only one auth session at a time.** Starting a second one while the first is open rejects.
+
+## Test it
+
+```bash
+pnpm vitest run packages/web-browser
+```
+
+The core tests fake the native module in place of `requireNativeModule`'s runtime resolution —
+`ExpoWebBrowser` only exists on a device — and drive fake `AppState`/`Linking` event sources so the
+Android auth-session polyfill's race is exercised headlessly. The browser itself, the iOS
+`ASWebAuthenticationSession` consent prompt, and real deep-link delivery can only be verified on a
+device or simulator.

package/build/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/web-browser/angular: the Angular entry over the framework-agnostic core.
+// Nothing here holds per-instance state or hands back a subscription, so there is no lifecycle for
+// an injectable service to own — see the React entry for the full reasoning.
+export * from '../core';

package/build/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getCustomTabsSupportingBrowsersAsync, warmUpAsync, mayInitWithUrlAsync, coolDownAsync, openBrowserAsync, dismissBrowser, openAuthSessionAsync, dismissAuthSession, } from './web-browser';
+export { WebBrowserResultType, WebBrowserPresentationStyle } from './types';
+export type { IAuthSessionOpenOptions, IRedirectEvent, IServiceActionResult, IWebBrowserAuthSessionResult, IWebBrowserCoolDownResult, IWebBrowserCustomTabsResults, IWebBrowserDismissResult, IWebBrowserMayInitWithUrlResult, IWebBrowserOpenOptions, IWebBrowserRedirectResult, IWebBrowserResult, IWebBrowserWarmUpResult, } from './types';

package/build/core/index.js

@@ -0,0 +1,2 @@
+export { getCustomTabsSupportingBrowsersAsync, warmUpAsync, mayInitWithUrlAsync, coolDownAsync, openBrowserAsync, dismissBrowser, openAuthSessionAsync, dismissAuthSession, } from './web-browser';
+export { WebBrowserResultType, WebBrowserPresentationStyle } from './types';

package/build/core/native-module.d.ts

@@ -0,0 +1,12 @@
+import type { IProcessedOpenOptions, IWebBrowserAuthSessionResult, IWebBrowserCoolDownResult, IWebBrowserCustomTabsResults, IWebBrowserDismissResult, IWebBrowserMayInitWithUrlResult, IWebBrowserResult, IWebBrowserWarmUpResult } from './types';
+export type INativeWebBrowserModule = {
+    openBrowserAsync?(url: string, options: IProcessedOpenOptions): Promise<IWebBrowserResult>;
+    dismissBrowser?(): Promise<IWebBrowserDismissResult>;
+    openAuthSessionAsync?(url: string, redirectUrl: string | null | undefined, options: IProcessedOpenOptions): Promise<IWebBrowserAuthSessionResult>;
+    dismissAuthSession?(): void;
+    warmUpAsync?(browserPackage?: string): Promise<IWebBrowserWarmUpResult>;
+    coolDownAsync?(browserPackage?: string): Promise<IWebBrowserCoolDownResult>;
+    mayInitWithUrlAsync?(url: string, browserPackage?: string): Promise<IWebBrowserMayInitWithUrlResult>;
+    getCustomTabsSupportingBrowsersAsync?(): Promise<IWebBrowserCustomTabsResults>;
+};
+export declare const expoWebBrowser: INativeWebBrowserModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_WEB_BROWSER_MODULE_NAME = 'ExpoWebBrowser';
+export const expoWebBrowser = requireNativeModule(EXPO_WEB_BROWSER_MODULE_NAME);

package/build/core/types.d.ts

@@ -0,0 +1,193 @@
+import type { ProcessedColorValue } from 'react-native';
+/** Payload of the deep-link event the Android auth-session polyfill listens for. */
+export type IRedirectEvent = {
+    url: string;
+};
+/**
+ * Options for [`openBrowserAsync`](#openbrowserasync).
+ *
+ * Upstream's two `@platform web` fields (`windowName`, `windowFeatures`) are not part of this
+ * type — SymbioteNative has no web target, so they could never be read.
+ */
+export type IWebBrowserOpenOptions = {
+    /** Color of the toolbar. Accepts any React Native color format. */
+    toolbarColor?: string;
+    /**
+     * Package name of the browser that should handle the Custom Tab. Pick one from
+     * `getCustomTabsSupportingBrowsersAsync`.
+     * @platform android
+     */
+    browserPackage?: string;
+    /** Whether the toolbar hides as the user scrolls the page. */
+    enableBarCollapsing?: boolean;
+    /**
+     * Color of the secondary toolbar. Accepts any React Native color format.
+     * @platform android
+     */
+    secondaryToolbarColor?: string;
+    /**
+     * Whether the toolbar shows the website's title.
+     * @platform android
+     */
+    showTitle?: boolean;
+    /**
+     * Whether a default share item is added to the browser's menu.
+     * @platform android
+     */
+    enableDefaultShareMenuItem?: boolean;
+    /**
+     * Whether the browsed website appears as its own entry in the recents/multitasking view.
+     * Requires `createTask` to stay `true`.
+     * @default false
+     * @platform android
+     */
+    showInRecents?: boolean;
+    /**
+     * Whether the browser opens in its own task rather than the app's.
+     * @default true
+     * @platform android
+     */
+    createTask?: boolean;
+    /**
+     * Whether to launch the browser through a transparent proxy activity with a different task
+     * affinity, which keeps the browser alive while the app is backgrounded. Only read when
+     * `createTask` is `true`, and forces `showInRecents` on. Set `false` for the legacy direct
+     * launch.
+     * @default true
+     * @platform android
+     */
+    useProxyActivity?: boolean;
+    /**
+     * Tint color for the controls in `SFSafariViewController`. Accepts any React Native color
+     * format.
+     * @platform ios
+     */
+    controlsColor?: string;
+    /**
+     * Style of the dismiss button.
+     * @platform ios
+     */
+    dismissButtonStyle?: 'done' | 'close' | 'cancel';
+    /**
+     * Whether Safari should enter Reader mode when the page supports it.
+     * @platform ios
+     */
+    readerMode?: boolean;
+    /**
+     * [Presentation style](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621355-modalpresentationstyle)
+     * of the browser window.
+     * @default WebBrowserPresentationStyle.OVER_FULL_SCREEN
+     * @platform ios
+     */
+    presentationStyle?: WebBrowserPresentationStyle;
+};
+/**
+ * Options for [`openAuthSessionAsync`](#openauthsessionasync). Android has no native auth-session
+ * API, so there the inherited `IWebBrowserOpenOptions` fields are passed to the Custom Tab the
+ * polyfill opens; on iOS `ASWebAuthenticationSession` ignores them and reads only the two fields
+ * below.
+ */
+export type IAuthSessionOpenOptions = IWebBrowserOpenOptions & {
+    /**
+     * Ask the browser for a private authentication session, so it shares no cookies or browsing
+     * data with the user's normal session. Whether the request is honored is up to the user's
+     * default browser.
+     * @default false
+     * @platform ios
+     */
+    preferEphemeralSession?: boolean;
+    /**
+     * Use HTTPS universal-link callbacks instead of custom-URL-scheme callbacks. Needs the
+     * Associated Domains entitlement configured for the redirect URL's host, and iOS 17.4+. Left
+     * `false`, the legacy `callbackURLScheme` API is used, which needs no entitlement.
+     * @default false
+     * @platform ios
+     */
+    preferUniversalLinks?: boolean;
+};
+/**
+ * The open options after the three color fields have been run through `processColor`. This is the
+ * shape the native module actually receives — a color reaches native as a platform integer, never
+ * as the CSS string the caller wrote.
+ */
+export type IProcessedOpenOptions = Omit<IAuthSessionOpenOptions, 'toolbarColor' | 'secondaryToolbarColor' | 'controlsColor'> & {
+    toolbarColor?: ProcessedColorValue | null;
+    secondaryToolbarColor?: ProcessedColorValue | null;
+    controlsColor?: ProcessedColorValue | null;
+};
+export type IWebBrowserCustomTabsResults = {
+    /**
+     * The browser the user picked as their device default, or `undefined` when there is none — which
+     * usually means the user will be prompted to choose.
+     */
+    defaultBrowserPackage?: string;
+    /**
+     * The browser `CustomTabsClient` prefers for Custom Tabs. Favors the user's default as long as
+     * it appears in both `browserPackages` and `servicePackages`; only such browsers fully support
+     * Custom Tabs. `undefined` when no installed browser qualifies.
+     */
+    preferredBrowserPackage?: string;
+    /**
+     * Every package `PackageManager` recognizes as able to handle Custom Tabs. Empty when the device
+     * has no supporting browser.
+     */
+    browserPackages: string[];
+    /**
+     * Every package `PackageManager` recognizes as able to handle the Custom Tabs *Service* — the
+     * one `warmUpAsync`, `mayInitWithUrlAsync` and `coolDownAsync` talk to.
+     */
+    servicePackages: string[];
+};
+/** How a browser session ended. */
+export declare enum WebBrowserResultType {
+    /** The user dismissed the browser themselves. @platform ios */
+    CANCEL = "cancel",
+    /** The browser was closed by a `dismissBrowser` call. @platform ios */
+    DISMISS = "dismiss",
+    /** The browser was launched. Android resolves here without waiting for it to close. @platform android */
+    OPENED = "opened",
+    /** Another browser session is already in progress. */
+    LOCKED = "locked"
+}
+/**
+ * A browser presentation style, mapped directly onto
+ * [`UIModalPresentationStyle`](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621355-modalpresentationstyle).
+ *
+ * @platform ios
+ */
+export declare enum WebBrowserPresentationStyle {
+    /** The browser covers the screen. */
+    FULL_SCREEN = "fullScreen",
+    /** The browser partially covers the underlying content. */
+    PAGE_SHEET = "pageSheet",
+    /** The browser is centered on the screen. */
+    FORM_SHEET = "formSheet",
+    /** The browser is displayed over the app's content. */
+    CURRENT_CONTEXT = "currentContext",
+    /** The browser view covers the screen. */
+    OVER_FULL_SCREEN = "overFullScreen",
+    /** The browser is displayed over the app's content. */
+    OVER_CURRENT_CONTEXT = "overCurrentContext",
+    /** The browser is displayed in a popover view. */
+    POPOVER = "popover",
+    /** The system picks the style. Older iOS versions fall back to `FULL_SCREEN`. */
+    AUTOMATIC = "automatic"
+}
+export type IWebBrowserResult = {
+    type: WebBrowserResultType;
+};
+/** What `dismissBrowser` resolves with once the presented browser has been torn down. */
+export type IWebBrowserDismissResult = {
+    type: WebBrowserResultType.DISMISS;
+};
+export type IWebBrowserRedirectResult = {
+    type: 'success';
+    url: string;
+};
+export type IServiceActionResult = {
+    servicePackage?: string;
+};
+export type IWebBrowserAuthSessionResult = IWebBrowserRedirectResult | IWebBrowserResult;
+export type IWebBrowserMayInitWithUrlResult = IServiceActionResult;
+export type IWebBrowserWarmUpResult = IServiceActionResult;
+export type IWebBrowserCoolDownResult = IServiceActionResult;

package/build/core/types.js

@@ -0,0 +1,37 @@
+/** How a browser session ended. */
+export var WebBrowserResultType;
+(function (WebBrowserResultType) {
+    /** The user dismissed the browser themselves. @platform ios */
+    WebBrowserResultType["CANCEL"] = "cancel";
+    /** The browser was closed by a `dismissBrowser` call. @platform ios */
+    WebBrowserResultType["DISMISS"] = "dismiss";
+    /** The browser was launched. Android resolves here without waiting for it to close. @platform android */
+    WebBrowserResultType["OPENED"] = "opened";
+    /** Another browser session is already in progress. */
+    WebBrowserResultType["LOCKED"] = "locked";
+})(WebBrowserResultType || (WebBrowserResultType = {}));
+/**
+ * A browser presentation style, mapped directly onto
+ * [`UIModalPresentationStyle`](https://developer.apple.com/documentation/uikit/uiviewcontroller/1621355-modalpresentationstyle).
+ *
+ * @platform ios
+ */
+export var WebBrowserPresentationStyle;
+(function (WebBrowserPresentationStyle) {
+    /** The browser covers the screen. */
+    WebBrowserPresentationStyle["FULL_SCREEN"] = "fullScreen";
+    /** The browser partially covers the underlying content. */
+    WebBrowserPresentationStyle["PAGE_SHEET"] = "pageSheet";
+    /** The browser is centered on the screen. */
+    WebBrowserPresentationStyle["FORM_SHEET"] = "formSheet";
+    /** The browser is displayed over the app's content. */
+    WebBrowserPresentationStyle["CURRENT_CONTEXT"] = "currentContext";
+    /** The browser view covers the screen. */
+    WebBrowserPresentationStyle["OVER_FULL_SCREEN"] = "overFullScreen";
+    /** The browser is displayed over the app's content. */
+    WebBrowserPresentationStyle["OVER_CURRENT_CONTEXT"] = "overCurrentContext";
+    /** The browser is displayed in a popover view. */
+    WebBrowserPresentationStyle["POPOVER"] = "popover";
+    /** The system picks the style. Older iOS versions fall back to `FULL_SCREEN`. */
+    WebBrowserPresentationStyle["AUTOMATIC"] = "automatic";
+})(WebBrowserPresentationStyle || (WebBrowserPresentationStyle = {}));

package/build/core/web-browser.d.ts

@@ -0,0 +1,83 @@
+import { type IAuthSessionOpenOptions, type IWebBrowserAuthSessionResult, type IWebBrowserCoolDownResult, type IWebBrowserCustomTabsResults, type IWebBrowserDismissResult, type IWebBrowserMayInitWithUrlResult, type IWebBrowserOpenOptions, type IWebBrowserResult, type IWebBrowserWarmUpResult } from './types';
+/**
+ * The packages that support Custom Tabs, the Custom Tabs service, and the user's chosen and
+ * preferred browser. Only as reliable as `PackageManager.getResolvingActivities` underneath — a
+ * browser can be missing from `browserPackages` once another one is set as default.
+ *
+ * @platform android
+ */
+export declare function getCustomTabsSupportingBrowsersAsync(): Promise<IWebBrowserCustomTabsResults>;
+/**
+ * Calls `warmUp` on the [`CustomTabsClient`](https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsClient#warmup(long))
+ * for the given package.
+ *
+ * @param browserPackage Browser to warm up. Defaults to the preferred one.
+ * @platform android
+ */
+export declare function warmUpAsync(browserPackage?: string): Promise<IWebBrowserWarmUpResult>;
+/**
+ * Starts a [`CustomTabsSession`](https://developer.android.com/reference/androidx/browser/customtabs/CustomTabsSession#mayLaunchUrl(android.net.Uri,android.os.Bundle,java.util.List%3Candroid.os.Bundle%3E))
+ * if needed and calls its `mayLaunchUrl`, so the browser can prefetch the page.
+ *
+ * @param url The page most likely to be opened first.
+ * @param browserPackage Browser to inform. Defaults to the preferred one.
+ * @platform android
+ */
+export declare function mayInitWithUrlAsync(url: string, browserPackage?: string): Promise<IWebBrowserMayInitWithUrlResult>;
+/**
+ * Drops every binding `warmUpAsync` and `mayInitWithUrlAsync` created. Call it once the bindings
+ * are no longer needed to avoid leaking them — though they are also released when the app is
+ * destroyed, which is often good enough.
+ *
+ * @param browserPackage Browser to cool down. Defaults to the preferred one.
+ * @returns The cooled service, or an empty object when there was no connection to dismiss.
+ * @platform android
+ */
+export declare function coolDownAsync(browserPackage?: string): Promise<IWebBrowserCoolDownResult>;
+/**
+ * Opens the url in a modal [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller)
+ * on iOS and a [Custom Tab](https://developer.chrome.com/docs/android/custom-tabs) on Android. The
+ * modal Safari does not share cookies with the system Safari — for a login flow that needs them,
+ * use `openAuthSessionAsync`.
+ *
+ * @returns Android resolves with `{ type: 'opened' }` as soon as the tab launches, without waiting
+ * for the user to close it. iOS resolves with `{ type: 'cancel' }` when the user dismissed the
+ * browser and `{ type: 'dismiss' }` when `dismissBrowser` closed it.
+ */
+export declare function openBrowserAsync(url: string, browserParams?: IWebBrowserOpenOptions): Promise<IWebBrowserResult>;
+/**
+ * Dismisses the presented browser. Throws where dismissing isn't available — Android's Custom Tabs
+ * offer no way to close a tab programmatically, so there the user has to press the tab's own close
+ * button.
+ *
+ * @platform ios
+ */
+export declare function dismissBrowser(): Promise<IWebBrowserDismissResult>;
+/**
+ * Opens a login page and resolves once the authentication provider redirects back to the app.
+ *
+ * On iOS this is `ASWebAuthenticationSession`, which asks the user whether the app may
+ * authenticate with the given url; the redirect URI registered with the authentication server has
+ * to use the app's own scheme (`demo://…`, not `https://…`). Adding a `Linking` listener of your
+ * own is unnecessary there and can have side effects.
+ *
+ * Android has no equivalent native API, so it is polyfilled: a Custom Tab plus `AppState` and
+ * `Linking`, racing "the deep link came back" against "the app returned to the foreground". Only
+ * one such session can be open at a time.
+ *
+ * @param url The login page to open.
+ * @param redirectUrl The url that deep-links back into the app. Without it the session can only
+ * end by the user closing the browser.
+ * @returns `{ type: 'success', url }` with the redirect url on a completed login,
+ * `{ type: 'cancel' }` when the user declined or closed the browser, and `{ type: 'dismiss' }` when
+ * `dismissBrowser` closed it.
+ */
+export declare function openAuthSessionAsync(url: string, redirectUrl?: string | null, options?: IAuthSessionOpenOptions): Promise<IWebBrowserAuthSessionResult>;
+/**
+ * Dismisses the current authentication session. Falls back to dismissing the plain browser where
+ * there is no native auth session, which on Android throws for the same reason `dismissBrowser`
+ * does.
+ *
+ * @platform ios
+ */
+export declare function dismissAuthSession(): void;