# 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`** / **`mhub.openSearch`**: receive searches the user
types into the host's own search UI, so your search page needs no input
field, and open that UI from the page.
7. **`mhub.setImmersive`** / **`mhub.exit`**: run as an app, not a
document: hide the host's chrome for a player, and leave for the host's
home.
8. **The meta tag**: declare in the HTML what a host cannot see from the
outside — that this is an mhub page, and that a D-pad reaches everything
on it, so a TV can hand it the remote's keys instead of a pointer aid.
9. **`mhub.device`** / **`mhub.capabilities`**: read what the page can't
detect on its own.
10. **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 four things:
1. **The queuing stub, installed synchronously.** `mhub.fetch`,
`mhub.setLinks`, `mhub.setSearch`, `mhub.setBackHandler`,
`mhub.setImmersive`, `mhub.openSearch` and
`mhub.exit` 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.
3. **A browser fallback** when there is no host: `mhub.fetch` becomes the
browser's own `fetch` and the queued calls go through it (the other queued
calls had no one to reach and are dropped). It carries less, and says so:
see [below](#without-a-host-the-browser-fallback).
4. **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.
### Tell the host what you are: the meta tag
Two things a host cannot see from the outside, declared in the HTML so they
are known before any script runs — and, for a host that reads a page's HTML
ahead of a visit, before the page is even opened:
```html
```
- `app`: this document is an mhub page. On a TV the host clears its chrome
and treats the page as the app on screen; it never turns it away as a
plain website.
- `dpad`: the page is **fully operable with a D-pad**: the directional keys
move a visible focus to every interactive element, OK/Enter activates it,
nothing needs a pointer. A TV host then hands the remote's keys straight to
the page instead of putting a pointer aid (a virtual cursor driven by the
remote) in front of it. A page that declares only `dpad` is a website that
works with the remote: a TV host will not turn it away, but it is not an
mhub page.
Put it in ``, above your scripts. Tokens are separated by spaces or
commas; unknown tokens are ignored, so the list can grow. Per document, like
everything a page declares: the next document starts from nothing.
Without the tag a host still recognises an mhub page, by its use of the API:
the first `window.mhub` **call** tells it. That is the fallback for pages that
have not added the line, not a second way to declare it, and it arrives
whenever the page first calls, which on a TV can be too late. A mere read of
`window.mhub` does not count: a feature check by any script on any website
would otherwise pass a plain page off as an app. `dpad` has no fallback at
all; it lives in the HTML only.
### Without a host: the browser fallback
In a plain browser the page keeps calling `mhub.fetch`, and the boot script
answers with the browser's `fetch`: CORS applies, there is no proxy and no
signature, credentials are omitted, and a request is aborted after 20 s where
the browser can (`AbortController`). `mhub.storage`, `mhub.openStream`,
`mhub.capabilities` and `mhub.device` stay `undefined`/`null`; check
`mhub.hosted` before reaching for them.
What a browser cannot do is **refused with a `code`** instead of failing
obscurely, so the page can tell the user that an mhub-compatible app would
help (see [Errors](#errors-codes-and-what-to-tell-the-user)):
- `identity: "required"` is refused up front (`identity_required`); nothing is
sent.
- A header a browser reserves for itself (`Referer`, `Origin`, `Cookie`, ...)
is refused up front (`header_blocked`). `User-Agent` is dropped quietly, the
server sees the browser's own.
- A cross-origin request that died without a status is either CORS or the
network, and the browser words both the same. The fallback asks once more in
`no-cors` mode: an opaque answer means the server is reachable and the first
attempt was refused by CORS (`cors_blocked`); no answer means the network,
and the original error is rethrown without a code.
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).
---
## Errors: codes and what to tell the user
A rejected `mhub.fetch` carries a stable **`code`** on the error, so a page
can tell "a host would have helped" from an ordinary network failure without
matching message text. The `message` stays English and one line, for the
console; the `code` is what page code branches on. Whoever answers
`mhub.fetch` sets it: the host, or the boot script's
[browser fallback](#without-a-host-the-browser-fallback).
| `code` | Set by | When |
|---|---|---|
| `identity_required` | browser fallback | The request asked for `identity: "required"` and there is no host to sign it. Nothing was sent. |
| `header_blocked` | browser fallback | The request sets a header a browser refuses to send (`Referer`, `Origin`, `Cookie`, ...). Nothing was sent. |
| `cors_blocked` | browser fallback | The request went out and the browser refused to show the answer; the server is reachable. |
| `permission_denied` | host | The user blocked web access for this site; nothing was sent. |
The first three also carry **`hint`**, a URL that explains where an
mhub-compatible app comes from (`https://mhub.mx/browser`). Everything else a
rejection can be (network, timeout, an HTTP status the page treats as an
error) has no `code`; it is the ordinary failure it looks like.
`mhub.hosted === false` is a state, not an error: a feature that cannot start
without a host should stay quiet or sleep, and only a call that actually
fails should show a message.
### Wording
The user cannot fix any of the three "no host" causes, and the reason behind
them (a signature, a header) means nothing to them. So they share **one**
sentence, and only `permission_denied` gets its own; the codes stay distinct
for the console and for pages that know more than the request does. Say it in
the page's own language and tone; the boot script ships no translations.
| `code` | Recommended (EN) | (DE) |
|---|---|---|
| `identity_required`, `header_blocked`, `cors_blocked` | This needs an mhub-compatible app. | Dafür brauchst du eine mhub-kompatible App. |
| same, when the page still works without a host and only something is missing | Tip: this works in an mhub-compatible app. | Tipp: In einer mhub-kompatiblen App funktioniert das. |
| `permission_denied` | Web access for this site is blocked. Allow it in the address bar. | Der Webzugriff für diese Seite ist blockiert. Erlaube ihn in der Adresszeile. |
How to place it:
- **At the point of failure**, in the page's own style: the empty row, the
tile, the player's error state. Not a banner, not a dialog; the moment
carries the message. (`data-require` on the boot script is for pages that
are nothing without a host; those show the banner and stop.)
- **`hint` is a link behind the sentence**, not a button and not a second
line.
- **Once per sentence and session.** A screen that fans out ten requests
hits the same wall ten times; show it once and let the page's own fallback
(empty state, cached data) do the rest.
- Never guess the subject. The code does not know whether it was a stream, a
catalog or a settings read, so the sentence says "this"; a page that knows
may name it.
```js
try {
const res = await mhub.fetch(url, { identity: "required" });
} catch (err) {
if (err.code === "permission_denied") showBlocked();
else if (err.hint) showNeedsApp(err.hint); // identity_required, header_blocked, cors_blocked
else showFailed(err); // an ordinary network failure
}
```
---
## 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), and whenever `insets` change — every time the host's bar tucks away or returns, and on every immersive flip | `{ device: { isTV, platform, insets? } }` |
| `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 `"identity"` 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 |
| `"clientFetch"` | `fetch` transparently resolves the addon's client-fetch requests (a request made from the client, with the user's own IP) |
| `"identity"` | `fetch` attaches the signed client identity (`identity: true`, or by default 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.
- `identity`: whether the signed client identity rides along, **whatever
origin the request goes to**. `true` = attach it if this host can (a host
without the `"identity"` capability sends the request unsigned);
`"required"` = the request only makes sense signed, a host that cannot sign
rejects the promise instead of sending it; `false` = never. Left out, the
host signs requests to the site's own confirmed endpoints only. See the
[binding](#signed-identity-capability-identity).
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 **`"clientFetch"`** capability, client-fetch requests in the response
are resolved transparently; see the [binding](#mediahubmx-binding).
- With the **`"identity"`** capability, requests carry the signed client
identity: on request (`identity: true`) to any origin, by default to the
site's own confirmed endpoints; 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[]
const all = await window.mhub.storage.entries(); // { key: value }
const seen = await window.mhub.storage.entries("watched/");// only that prefix
const q = await window.mhub.storage.quota(); // see Limits
```
Storage needs **no permission** and never prompts: nothing leaves the device,
exactly like `localStorage`.
### `entries([prefix])`
Every value in one call, as an object, optionally narrowed to the keys that
start with `prefix`. Each `get` is a round trip; a page that keeps many small
keys — which is the shape that makes writes cheap, since only the value you
touch is written — would otherwise pay one per key at startup. Prefer this
over `keys()` whenever you want the values anyway, and name a prefix so you
read the one store you need rather than everything you have.
### 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 (`"arte/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
They differ per host, so ask rather than assume:
```js
const { total, used, perValue, keys, keysUsed } = await window.mhub.storage.quota();
```
All five are numbers; `used` counts keys and values together, the same way the
host counts them against `total`. Current hosts offer **20 MB** per site,
**512 KB** per value and **50 000** keys — room for a memory, not just a
watchlist. `perValue` counts characters, not bytes.
The **minimum** any host offers is **512 KB** in total, **256 KB** per value
and **200** keys. Older hosts, and hosts on a platform that cannot store more,
stay at that; `quota` is how you tell. On a host too old to know `quota` at
all, the call rejects — then assume the minimum.
`set` rejects when a limit is hit rather than dropping data silently, so you
can react. With many keys, prefer `entries(prefix)` over `keys()`: 50 000 keys
is a large array to hand across for nothing.
`entries` has a size limit of its own, separate from storage: its answer
crosses to your page in one piece, so a host refuses one that would be
several megabytes and tells you to narrow it with a prefix. Read a store at a
time, not the lot.
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 `