# mHub Browser API
When a web page is opened inside an mHub-compatible browser, the browser
exposes the **mHub Browser API**. `window.mhub` is simply the namespace it
lives in, the way `navigator` is for the web platform. It lets a page do
things a normal browser cannot:
1. **`mhub.fetch`**: fetch any URL without CORS, with request headers the
browser would never let a page set.
2. **`mhub.storage`**: key/value storage that follows the *site*, not the
domain it was written on.
3. **`mhub.openStream`**: play media that needs mandatory request headers.
4. **`mhub.setLinks`**: add entries ("addon links") to the browser home screen.
5. **`mhub.setBackHandler`**: own the back press while the page runs its own
navigation.
6. **`mhub.setSearch`**: receive searches the user types into the host's own
search UI, so your search page needs no input field.
7. **`mhub.device`** / **`mhub.capabilities`**: read what the page can't
detect on its own.
8. **Mirrors**: one small file on each of your domains, and your site
survives a dead one. No API call involved; see
[Mirrors](#mirrors-survive-a-dead-domain).
Everything here is **progressive enhancement**: outside an mHub-compatible
browser the API simply doesn't exist, so guard every use with feature detection.
A page that ignores the API keeps working as a plain website.
## The core guarantee
If `window.mhub` exists, **every member documented in the Core API below MUST
exist and work**. A conforming host has no partial surface and no members that
silently do nothing. What legitimately varies between hosts are the *optional
powers* (a loopback stream proxy, the mirror system, the task protocol, the
signed identity), and each of those is announced in
[`mhub.capabilities`](#windowmhubcapabilities). Check `window.mhub` to know the
API is there; check a capability to know an optional power is there. So
`if (window.mhub)` is the whole check. Probing a core member
(`window.mhub?.fetch`) says the opposite of this guarantee, and once a page
does it for one member it does it for all of them.
The API is the same on **every platform** the host apps run on: mobile, TV,
desktop, web. A platform difference is always expressed through
`capabilities` (or `device`), never through a missing member.
The API is only present when the app has the page-API feature enabled, and only
in the **top document**, never inside embedded (third-party) iframes.
---
## Readiness: the boot script
`window.mhub` is injected **synchronously at document start**, before your
first script, so normally the whole API is simply there:
```js
if (window.mhub) {
const res = await window.mhub.fetch("https://example.com/api");
}
```
Two things make raw feature-detection awkward: on some hosts the API attaches
a few milliseconds late, and a page often wants to *tell the user* when it is
not running in an mHub browser at all. The **boot script** handles both; load
it as the first script in ``:
```html
```
It gives the page three things:
1. **The queuing stub, installed synchronously.** `mhub.fetch`,
`mhub.setLinks`, `mhub.setSearch` and `mhub.setBackHandler` are callable
from the very first line; on a late-attaching host the calls queue and
replay in order. (`mhub.storage`, `mhub.openStream`, `mhub.capabilities`
and `mhub.device` cannot be queued meaningfully; while the stub is active
they are `undefined`/`null`, so touch them after `mhub.ready`.)
2. **Detection.** `mhub.ready` is a `Promise`: `true` once a real
host has attached, `false` when this is a plain browser (decided shortly
after the document is complete). After it settles, `mhub.hosted` carries
the same answer synchronously. On `false`, queued `fetch` calls **reject**
(`"mhub: no host attached"`) instead of hanging forever.
3. **A warning banner** when there is no host, only with the `data-require`
attribute (override the text with `data-message`). Leave it off and handle
`mhub.ready === false` yourself; a page built as progressive enhancement
needs neither.
```js
const hosted = await mhub.ready;
if (!hosted) showDownloadHint(); // or data-require does it for you
```
With the boot script loaded, `window.mhub` is **always** there, because the
stub puts it there in a plain browser too. `if (window.mhub)` then detects
nothing and `mhub.ready` is the only honest answer. Without the boot script it
is the other way round: the namespace exists only where a host injected it,
and testing it is the whole detection.
`mhub.ready` and `mhub.hosted` are provided by the **boot script, not by
hosts**; never feature-detect the host through them.
Self-hosting or inlining the script is fine and recommended for
availability-critical pages; it has no server-side coupling. Pages that cannot
load it can still hand-roll the stub (see the script source; the stub shape
is the compatibility contract and stays stable).
---
## Events
Live host-state changes arrive through a single **`mhubupdate`** event on
`window`, discriminated by `detail.kind`:
```js
addEventListener("mhubupdate", (e) => {
switch (e.detail.kind) {
case "device": applyLayout(e.detail.device); break;
case "permission": onPermission(e.detail.granted); break;
case "identity": refetchUserState(); break;
}
});
```
| `detail.kind` | Fired when | `detail` |
|---|---|---|
| `device` | on load (device known) | `{ device: { isTV, platform } }` |
| `permission` | on load, and when a permission changes | `{ name: "fetch", state: "allow"/"deny"/"ask", granted }` |
| `identity` | when the signed identity / entitlement changes (only on hosts with the `"sign"` capability, never elsewhere) | `{}` (a trigger only) |
- **`permission`** reports the effective per-site decision, so a page can show a
"grant access" affordance instead of a dead button. `granted` is
`state === "allow"`; `ask` means the next `mhub.fetch` will prompt. `name`
identifies which permission it is, today only `"fetch"` (CORS-free web
access, also covering proxied `openStream`); branch on it so your code keeps
working if more permissions are added later.
- **`identity`** carries no data on purpose: the signed identity is never exposed
to page JavaScript. Read it as *"your entitlement may have changed, re-fetch
your own endpoint"*; the browser attaches the fresh signature to that request.
A second event, **`mhubback`**, is not a state change but a command: the host
handing the back press to the page. It is documented with
[`mhub.setBackHandler`](#windowmhubsetbackhandlerdepth).
---
## `window.mhub.capabilities`
A **synchronous** array of strings naming the optional host powers. Core
members are never listed; they are always present (see the core guarantee).
```js
if (window.mhub?.capabilities.includes("streamProxy")) {
// openStream can inject mandatory headers here
}
```
| Capability | Meaning |
|---|---|
| `"streamProxy"` | `openStream` can proxy streams with mandatory request headers |
| `"mirrors"` | the host runs the [mirror system](#mirrors-survive-a-dead-domain): site-file discovery, page-load failover, `fetch` failover, adaptive order |
| `"tasks"` | `fetch` transparently resolves MediaHubMX fetch tasks (a client-side request with the user's own IP) |
| `"sign"` | `fetch` attaches the signed client identity to confirmed site endpoints |
| `"search"` | the host surfaces a site-search entry point (e.g. the address bar) and delivers queries to [`setSearch`](#windowmhubsetsearchconfig) |
| `"cast"` | *planned, never announced yet*; see [Casting](#planned-casting) |
Unknown strings may appear as the API grows; ignore what you don't know.
The list is **fixed per document load**: a capability never appears or
disappears while your page is running.
---
## `window.mhub.fetch(url, options?)`
A CORS-free, `fetch`-compatible request that runs on the native side.
```js
const res = await window.mhub.fetch("https://example.com/data.json");
const data = await res.json();
```
### Parameters
| Argument | Type | Notes |
| --------- | ------------------- | -------------------------------------------------- |
| `url` | `string` | Resolved relative to the current page. |
| `options` | `object` (optional) | A subset of `fetch`'s `RequestInit`, see below. |
Supported `options`:
- `method`: e.g. `"GET"`, `"POST"`.
- `headers`: a plain object or a `Headers` instance. Because the request is
built **natively**, this includes headers a browser reserves for itself
(`Referer`, `Origin`, `User-Agent`, …); set them like any other.
- `body`: **string only** (JSON, form-encoded, …). Blobs/FormData are not
transferred.
- `redirect`: best-effort. `"follow"` (the default) works everywhere; hosts
built on a native fetch may not honor `"manual"`/`"error"` and follow anyway.
Credentials are always omitted; the host never attaches its own cookies.
### Return value
A Promise resolving to a **`Response`-compatible** object. On mobile it is a real
`Response` (so `arrayBuffer()` and `blob()` also work); on desktop it is a
lightweight object with the common members. For portability, rely on:
- `status` (number), `ok` (boolean), `url` (string), `headers`
- `text()` → `Promise`
- `json()` → `Promise`
Binary responses are transferred transparently (base64 under the hood) and
reconstructed for you.
The promise **rejects** on network failure, on denied permission, and on
timeout: a request that neither answers nor fails is aborted by the host
(currently after 20 s), so a hanging upstream can never leave your page waiting
forever.
### What it does beyond a plain fetch
- **No CORS.** The request runs natively, so cross-origin responses are readable
regardless of the target's CORS headers.
- **Forbidden headers.** A browser silently strips `Referer`, `Origin`,
`User-Agent` and friends from page-initiated requests; here they go through.
Many stream and API endpoints are unusable without exactly this.
- With the **`"mirrors"`** capability, requests to the site's own endpoints fail
over to the next mirror on a network error, a timeout or an HTTP status
`>= 500`; see [Mirrors](#mirrors-survive-a-dead-domain).
- With the **`"tasks"`** capability, MediaHubMX fetch tasks in the response
are resolved transparently; see the [binding](#mediahubmx-binding).
- With the **`"sign"`** capability, requests to the site's own confirmed
endpoints carry the signed client identity; see the
[binding](#mediahubmx-binding).
### Permission
The **first** `mhub.fetch` for a given site shows a one-time dialog
("Allow web access?") naming the host the page is served from, with a
*Remember for this site* option.
- **Allow** + remember → persisted; no further prompts.
- **Allow** without remember → granted for the session.
- **Block** → the call rejects; a red indicator appears in the address bar and
tapping it re-opens the dialog. A block is session-only and never persisted.
Several `mhub.fetch` calls made before the user answers share the one dialog and
are all resolved by the single decision. The same permission covers proxied
[`openStream`](#windowmhubopenstreamurl-headers-cors) calls; it does **not**
gate `mhub.storage`.
---
## `window.mhub.storage`
Key/value storage that follows your **site**, not the domain it was written on.
All methods return promises; values are strings, so you decide the format.
```js
await window.mhub.storage.set("watchlist", JSON.stringify(items));
const raw = await window.mhub.storage.get("watchlist"); // string | null
await window.mhub.storage.remove("watchlist");
const keys = await window.mhub.storage.keys(); // string[]
```
Storage needs **no permission** and never prompts: nothing leaves the device,
exactly like `localStorage`.
### Why not `localStorage`
Browsers partition `localStorage` per origin. A site reachable under several
mirror domains therefore gets a separate, empty store on each one, and that
hits exactly when a mirror is used, i.e. when the usual domain is unreachable.
The host is the only side that knows which domains are the same site, so it is
the only side that can bridge this.
### Scope
The site part of the key comes from the **host**, derived from the same verified
identity that governs permission and the signature (see *Site identity*). You
cannot choose it, and no other site can name it to reach your data. Inside your
own scope the keys are yours; namespace them per addon if one origin serves
several (`"ted/watchlist"`, `"nasa/watchlist"`).
A site that has not published a site file still gets storage, keyed by its
origin: same isolation, it just cannot span mirrors, because as far as the host
knows there are none.
### Limits
Per site: **512 KB** in total, **256 KB** per value, **200** keys. `set` rejects
when a limit is hit rather than dropping data silently, so you can react.
The store lives on the device; several tabs of the same site share it, writes
are last-write-wins. There is no cross-device sync; it follows the site's
*identity*, not the user.
### Availability
Outside a host `window.mhub` doesn't exist at all, so fall back to
`localStorage`; the data then simply stays on the current domain:
```js
const store = window.mhub?.storage;
const raw = store
? await store.get("watchlist")
: localStorage.getItem("watchlist");
```
---
## `window.mhub.openStream({url, headers?, cors?})`
**The one way to start playback of an external stream.** Media that needs
mandatory request headers (a `Referer`, a token) cannot be played by handing
the URL to a `