# @uidu/app-bridge reference

URL: https://developers.uidu.org/docs/reference/app-bridge

> Every export of @uidu/app-bridge, generated from the source.

The browser half of a custom app that runs inside uidu. In React, prefer `<UiduAppProvider>` from `@uidu/react`, which wraps it. Guide: [Custom app](https://developers.uidu.org/docs/paths/custom-app.md).

## Functions

| Export                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                   | Demo |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| [`connect`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/bridge.ts)<br />`connect(options: ConnectOptions = {}): Promise<AppBridge>`                          | Ask the uidu page framing this app for a session, and resolve once it has one. Rejects with an `AppBridgeError` when the app isn't framed by a trusted uidu page, or the host refuses or doesn't answer — so an app can fall back (to local storage, a login screen…).                        | —    |
| [`detectParentOrigin`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/origins.ts)<br />`detectParentOrigin(win: Window): string \| null`                        | The origin of the page that framed this one, when the browser says: `location.ancestorOrigins` (Chromium, Safari) first, since it can't be suppressed by a referrer policy; `document.referrer` otherwise (Firefox). uidu frames apps with `strict-origin-when-cross-origin`, which sends it. | —    |
| [`isTrustedOrigin`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/origins.ts)<br />`isTrustedOrigin(origin: string, patterns: ReadonlyArray<string>): boolean` | Whether `origin` matches any of `patterns`, each an exact origin or a `https://*.example.org` wildcard (see `matchesOrigin`).                                                                                                                                                                 | —    |
| [`matchesOrigin`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/origins.ts)<br />`matchesOrigin(origin: string, pattern: string): boolean`                     | `pattern` is an exact origin (`https://me.uidu.local:8443`) or a wildcard one (`https://*.uidu.org`), where `*` stands for one or more subdomain labels — never for the bare domain, the scheme or the port.                                                                                  | —    |
| [`parseHostMessage`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/protocol.ts)<br />`parseHostMessage(data: unknown): HostMessage \| null`                    | Narrow an inbound `event.data` to a host message, or null. Checks only the shape — whether the sender is trusted is the caller's job.                                                                                                                                                         | —    |

## Classes

| Export                                                                                             | Description                                                                                                                               | Demo |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| [`AppBridgeError`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/bridge.ts) | Why the bridge failed or gave up, by `code` (`NOT_EMBEDDED`, `UNTRUSTED_HOST`, `TIMEOUT`, `HOST_ERROR`, …); `connect()` rejects with one. | —    |

## Constants

| Export                                                                                                    | Description                                                                                                                                                                                                    | Demo                                                                                                            |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`DEFAULT_HOST_ORIGINS`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/origins.ts) | Which pages an app lets hand it a session.                                                                                                                                                                     | [`app/custom-app/page.tsx`](https://github.com/uidu-org/api.js/blob/main/apps/demo/src/app/custom-app/page.tsx) |
| [`PROTOCOL_VERSION`](https://github.com/uidu-org/api.js/blob/main/packages/app-bridge/src/protocol.ts)    | The wire format between a custom app and the uidu page that frames it — protocol v1, as served by `CustomAppFrame.tsx` in the uidu repo (docs/superpowers/specs/2026-09-23-custom-space-apps/SPEC.md, step 2). | —                                                                                                               |

## Types

`AppBridge`, `AppBridgeErrorCode`, `AppContext`, `AppMessage`, `ConnectOptions`, `ContextMessage`, `ErrorMessage`, `HostMessage`, `Named`, `ReadyMessage`, `RefreshMessage`