@agentshouse/app-bridge 0.1.0-cac36ee240fcd → 0.1.0-cbcf384385682

package/README.md

@@ -1,22 +1,25 @@
 # @agentshouse/app-bridge
 
-The renderer-side client of the agents.house App bridge. An App served by House
-receives one message port before its own scripts run; this package is that
-port's one listener. It carries eleven families: navigation, ceremonies,
-installation, notifications, status, Site image reads, App release code,
-external calls, App messages and App and Site screenshot reads.
+The types of the agents.house App bridge, an accessor and an in-page test host.
+House builds the bridge object in every App it serves and hands it to the page
+before the App's own scripts run; `houseBridge()` returns that object, so an App
+carries no bridge code of its own. It carries eleven families: navigation,
+ceremonies, installation, notifications, status, Site image reads, App release
+code, external calls, App messages and App and Site screenshot reads.
 [docs/families.md](docs/families.md) describes each and the test host.
 
-The package carries no credential handling and no Runtime family. House builds
+The bridge carries no credential handling and no Runtime family. House builds
 the MD Runtime client into the page beside the bridge, and `bridge.runtime`
 resolves to that client, so the App imports and constructs none.
 
+House's `find_command` "App" is the guide to building an App or a Site.
+
 ## Use
 
 ```js
-import { connectHouseBridge } from '@agentshouse/app-bridge';
+import { houseBridge } from '@agentshouse/app-bridge';
 
-const bridge = connectHouseBridge();
+const bridge = houseBridge();
 const md = await bridge.runtime;
 
 bridge.onAddress((address) => render(address));
@@ -32,22 +35,24 @@ async function manageSecurity(securityPath) {
   try {
     await bridge.ceremony(securityPath);
   } catch (refusal) {
-    report(refusal);
+    if (refusal.name === 'HouseCeremonyRefused') report(refusal.path);
   }
 }
 ```
 
 `bridge.runtime` resolves to the `MdRuntimeClient` of
-`@agentshouse/mdruntime/client`, whose README describes its members.
+`@agentshouse/mdruntime/client`, whose README describes its members. Its
+`call(name, input)` reaches House: `HouseCalls` names each Call an App makes
+and the input it takes, such as `call('member.list', { room_ref })`.
 
 ## Test without a House
 
 ```js
-import { connectHouseBridge } from '@agentshouse/app-bridge';
+import { houseBridge } from '@agentshouse/app-bridge';
 import { createHouseBridgeTestHost } from '@agentshouse/app-bridge/test-host';
 
 const host = createHouseBridgeTestHost({ address: '/rooms/atlas' });
-const bridge = connectHouseBridge(host);
+const bridge = houseBridge();
 
 bridge.push('/rooms/atlas/members');
 host.open('/rooms/atlas');

package/dist/calls.d.ts

@@ -0,0 +1,117 @@
+export interface HouseCalls {
+    readonly 'access.read': {
+        readonly room_ref: string;
+    };
+    readonly 'conversation.answer': {
+        readonly answer: {
+            readonly interaction_id: string;
+            readonly response: unknown;
+        };
+        readonly conversation: string;
+        readonly operation_id?: string;
+    };
+    readonly 'conversation.create': {
+        readonly agent_id: string;
+        readonly operation_id?: string;
+    };
+    readonly 'conversation.delete': {
+        readonly conversation: string;
+        readonly operation_id?: string;
+    };
+    readonly 'conversation.history': {
+        readonly conversations: readonly {
+            readonly after?: string;
+            readonly conversation: string;
+        }[];
+    };
+    readonly 'conversation.interrupt': {
+        readonly conversation: string;
+        readonly operation_id?: string;
+    };
+    readonly 'conversation.kill': {
+        readonly conversation: string;
+        readonly operation_id?: string;
+    };
+    readonly 'conversation.markDone': {
+        readonly conversation_id?: string;
+        readonly result?: string;
+        readonly operation_id: string;
+    };
+    readonly 'conversation.rename': {
+        readonly conversation_id: string;
+        readonly operation_id: string;
+        readonly name: string;
+    };
+    readonly 'conversation.send': {
+        readonly conversation: string;
+        readonly files?: readonly {
+            readonly blob: Blob;
+            readonly byteLength: number;
+            readonly contentHash: string;
+            readonly height?: number;
+            readonly mediaType: string;
+            readonly name: string;
+            readonly width?: number;
+        }[];
+        readonly operation_id?: string;
+        readonly text?: string;
+    };
+    readonly 'conversation.setOption': {
+        readonly conversation_id: string;
+        readonly operation_id: string;
+        readonly option: string;
+        readonly value: string | boolean;
+    };
+    readonly 'feature.list': Readonly<Record<string, never>>;
+    readonly 'holder.list': Readonly<Record<string, never>>;
+    readonly 'holder.ring': {
+        readonly to: string;
+    };
+    readonly 'member.list': {
+        readonly room_ref: string;
+        readonly history?: boolean;
+        readonly limit?: number;
+        readonly cursor?: string;
+    };
+    readonly 'message.send': {
+        readonly to: string;
+        readonly body: unknown;
+    };
+    readonly 'processing.read': {
+        readonly room_ref: string;
+        readonly path: string;
+    };
+    readonly 'record.list': {
+        readonly room_ref: string;
+        readonly record?: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+        readonly order?: 'asc' | 'desc';
+    };
+    readonly 'relay.read': Readonly<Record<string, never>>;
+    readonly 'routine.list': {
+        readonly room_ref: string;
+    };
+    readonly 'routineAccess.list': {
+        readonly room_ref: string;
+    };
+    readonly 'routineAllowance.list': {
+        readonly room_ref: string;
+        readonly access: string;
+    };
+    readonly 'routineRequest.list': {
+        readonly room_ref: string;
+    };
+    readonly 'storage.read': {
+        readonly room_ref?: string;
+    };
+    readonly submit: {
+        readonly content: string;
+    };
+    readonly 'trigger.list': {
+        readonly room_ref: string;
+    };
+    readonly 'triggerOccurrence.list': {
+        readonly room_ref: string;
+    };
+}

package/dist/calls.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
+import type { HouseCalls } from './calls.js';
+export type { HouseCalls } from './calls.js';
+type Open<Value extends string> = Value | (string & {});
+export type HouseCallInput<Name extends string> = Name extends keyof HouseCalls ? HouseCalls[Name] : unknown;
+export interface HouseRuntime extends Omit<MdRuntimeClient, 'call'> {
+    call<Name extends Open<keyof HouseCalls>>(name: Name, input: HouseCallInput<Name>): ReturnType<MdRuntimeClient['call']>;
+}
+export interface HouseSyncState {
+    readonly state: string;
+    readonly providerUnreachable: boolean;
+}
+export interface HouseCredentialState {
+    readonly state: Open<'none' | 'held' | 'rejected'>;
+    readonly expiresAt: number | null;
+}
+export type HouseAnalyticsChoice = 'accept' | 'decline';
+export interface HouseAnalytics {
+    readonly measures: boolean;
+    readonly choice: Open<HouseAnalyticsChoice> | null;
+}
+export interface HouseStatus {
+    readonly app: string | null;
+    readonly preferences: {
+        readonly roomRef: string;
+        readonly path: string;
+    } | null;
+    readonly runtime: string;
+    readonly credential: HouseCredentialState;
+    readonly sync: HouseSyncState | null;
+    readonly refusal: {
+        readonly code: string;
+        readonly retryable: boolean;
+    } | null;
+    readonly loss: string | null;
+    readonly analytics: HouseAnalytics;
+    readonly serviceMode: Open<'open' | 'write-halted'> | null;
+    readonly offline: boolean;
+}
+export type HouseNavigationMode = 'push' | 'replace';
+export interface HouseTab {
+    readonly title?: string;
+    readonly icon?: string;
+}
+interface HouseRelease {
+    readonly app_ref: string;
+    readonly release: string;
+}
+export interface HouseSourceTop extends HouseRelease {
+    readonly folders: readonly string[];
+    readonly files: readonly {
+        readonly name: string;
+        readonly size: number;
+    }[];
+    readonly readme: string | null;
+}
+export type HouseSourceFile = {
+    readonly path: string;
+    readonly size: number;
+} & ({
+    readonly text: string;
+} | {
+    readonly base64: string;
+});
+export interface HouseSourceDownload extends HouseRelease {
+    readonly files: readonly HouseSourceFile[];
+}
+export interface HouseExternalRequest {
+    readonly url: string;
+    readonly method?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly body_base64?: string;
+    readonly account?: string;
+    readonly slot?: string;
+}
+export type HouseExternalAnswer = {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string | readonly string[]>>;
+} & ({
+    readonly body: string;
+} | {
+    readonly body_base64: string;
+});
+export interface HouseRefusal {
+    readonly error: {
+        readonly code: string;
+        readonly retryable: boolean;
+    };
+}
+export interface HouseAppMessage {
+    readonly from: string;
+    readonly body: unknown;
+}
+export type HouseInstallation = Open<'accepted' | 'dismissed' | 'manual'>;
+export type HouseNotifications = Open<'on' | 'off' | 'blocked' | 'unavailable'>;
+export interface HouseCeremonyRefused extends Error {
+    readonly name: 'HouseCeremonyRefused';
+    readonly code: Open<'house_ceremony_refused'>;
+    readonly retryable: boolean;
+    readonly path: string | null;
+}
+export interface HouseNavigationRefused extends Error {
+    readonly name: 'HouseNavigationRefused';
+    readonly code: Open<'house_navigation_refused'>;
+    readonly retryable: boolean;
+    readonly address: string | null;
+}
+export interface HouseBrowserRefused extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+}
+export interface HouseBridge {
+    readonly runtime: Promise<HouseRuntime>;
+    address(): string | null;
+    onAddress(listener: (address: string) => void): () => void;
+    push(address: string): Promise<string>;
+    replace(address: string): Promise<string>;
+    ceremony(path: string): Promise<never>;
+    install(): Promise<HouseInstallation>;
+    notifications(on?: boolean): Promise<HouseNotifications>;
+    setBadge(unread: readonly string[]): Promise<void>;
+    setTab(tab: HouseTab): void;
+    sourceTop(app: string, release?: string): Promise<HouseSourceTop | HouseRefusal | null>;
+    sourceDownload(app: string, release?: string): Promise<HouseSourceDownload | HouseRefusal | null>;
+    callExternal(request: HouseExternalRequest): Promise<HouseExternalAnswer | HouseRefusal | null>;
+    readScreenshot(app: string): Promise<Blob | null>;
+    readSiteScreenshot(site: string): Promise<Blob | null>;
+    status(): HouseStatus | null;
+    onStatus(listener: (status: HouseStatus) => void): () => void;
+    messages(listener: (message: HouseAppMessage) => void): () => void;
+    analyticsConsent(choice: HouseAnalyticsChoice): void;
+}
+export interface HouseHeld {
+    readonly houseBridge: HouseBridge;
+}
+export declare const houseBridge: () => HouseBridge;

package/dist/index.js

@@ -0,0 +1 @@
+export const houseBridge = () => globalThis.houseBridge;

package/dist/{client/src/test-host.d.ts → test-host.d.ts}

@@ -1,14 +1,13 @@
 import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
-import type { HouseBridgeSource, HouseImageCopy } from './bridge.js';
-import type { HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseGaChoice, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+import type { HouseAnalyticsChoice, HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './index.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
 }
-export interface HouseBridgeTestHost extends HouseBridgeSource {
+export interface HouseBridgeTestHost {
     readonly navigations: readonly HouseBridgeNavigation[];
     readonly ceremonies: readonly string[];
-    readonly consents: readonly HouseGaChoice[];
+    readonly consents: readonly HouseAnalyticsChoice[];
     readonly tabs: readonly HouseTab[];
     readonly externalCalls: readonly HouseExternalRequest[];
     address(): string;
@@ -20,9 +19,6 @@ export interface HouseBridgeTestHost extends HouseBridgeSource {
 export interface HouseBridgeTestHostOptions {
     readonly address?: string;
     readonly status?: HouseStatus;
-    readonly images?: readonly (HouseImageCopy & {
-        readonly room: string;
-    })[];
     readonly sources?: readonly {
         readonly top: HouseSourceTop;
         readonly download: HouseSourceDownload;

package/dist/test-host.js

@@ -0,0 +1,173 @@
+const HOST_ORIGIN = 'https://house.invalid';
+const ADDRESS_MAX_CHARS = 64 * 1024;
+function sameOriginPath(value) {
+    if (typeof value !== 'string')
+        return null;
+    if (value.charAt(0) !== '/' || value.slice(0, 2) === '//')
+        return null;
+    if (value.length > ADDRESS_MAX_CHARS)
+        return null;
+    const target = new URL(value, HOST_ORIGIN);
+    return target.origin === HOST_ORIGIN ? `${target.pathname}${target.search}${target.hash}` : null;
+}
+function appAddress(address) {
+    return address.startsWith('/') ? address : `/${address}`;
+}
+function ceremonyRefused(path) {
+    return Object.assign(new Error('house_ceremony_refused'), {
+        name: 'HouseCeremonyRefused',
+        code: 'house_ceremony_refused',
+        retryable: false,
+        path,
+    });
+}
+function navigationRefused(address) {
+    return Object.assign(new Error('house_navigation_refused'), {
+        name: 'HouseNavigationRefused',
+        code: 'house_navigation_refused',
+        retryable: false,
+        address,
+    });
+}
+function followHeld(listeners, listener, held) {
+    let following = true;
+    queueMicrotask(() => {
+        if (!following)
+            return;
+        listeners.add(listener);
+        const value = held();
+        if (value !== null)
+            listener(value);
+    });
+    return () => {
+        following = false;
+        listeners.delete(listener);
+    };
+}
+export function createHouseBridgeTestHost(options = {}) {
+    const navigations = [];
+    const ceremonies = [];
+    const consents = [];
+    const tabs = [];
+    const externalCalls = [];
+    const addressListeners = new Set();
+    const statusListeners = new Set();
+    const messageListeners = new Set();
+    let current = appAddress(options.address ?? '/');
+    let published = options.status ?? null;
+    let shown = null;
+    let seen = null;
+    let attached = () => { };
+    const runtime = new Promise((resolve) => {
+        attached = resolve;
+    });
+    function arrive(target) {
+        current = target;
+        queueMicrotask(() => {
+            shown = target;
+            for (const listener of addressListeners)
+                listener(target);
+        });
+    }
+    function publish(next) {
+        published = next;
+        queueMicrotask(() => {
+            seen = next;
+            for (const listener of statusListeners)
+                listener(next);
+        });
+    }
+    function navigate(mode, asked) {
+        let path = asked;
+        if (/^https?:\/\//i.test(asked)) {
+            try {
+                const target = new URL(asked);
+                path = target.origin === HOST_ORIGIN ? target.pathname + target.search + target.hash : '';
+            }
+            catch {
+                path = '';
+            }
+        }
+        const target = sameOriginPath(path);
+        if (target === null)
+            return Promise.reject(navigationRefused(asked));
+        navigations.push({ mode, address: target });
+        arrive(target);
+        return new Promise((resolve) => {
+            queueMicrotask(() => resolve(target));
+        });
+    }
+    const bridge = {
+        runtime,
+        address: () => shown,
+        onAddress(listener) {
+            return followHeld(addressListeners, listener, () => shown);
+        },
+        push: (asked) => navigate('push', asked),
+        replace: (asked) => navigate('replace', asked),
+        ceremony(path) {
+            const target = sameOriginPath(path);
+            if (target === null)
+                return Promise.reject(ceremonyRefused(path));
+            ceremonies.push(target);
+            return new Promise(() => { });
+        },
+        install: () => Promise.resolve('manual'),
+        notifications: () => Promise.resolve('unavailable'),
+        setBadge: () => Promise.resolve(),
+        setTab(tab) {
+            tabs.push(tab);
+        },
+        sourceTop: (app) => Promise.resolve(options.sources?.find((entry) => entry.top.app_ref === app)?.top ?? null),
+        sourceDownload: (app) => Promise.resolve(options.sources?.find((entry) => entry.top.app_ref === app)?.download ?? null),
+        callExternal(request) {
+            externalCalls.push(request);
+            return Promise.resolve(options.external?.(request) ?? null);
+        },
+        readScreenshot: (app) => Promise.resolve(options.screenshots?.[app] ?? null),
+        readSiteScreenshot: (site) => Promise.resolve(options.siteScreenshots?.[site] ?? null),
+        status: () => seen,
+        onStatus(listener) {
+            return followHeld(statusListeners, listener, () => seen);
+        },
+        messages(listener) {
+            messageListeners.add(listener);
+            return () => {
+                messageListeners.delete(listener);
+            };
+        },
+        analyticsConsent(choice) {
+            if (published === null || !published.analytics.measures)
+                return;
+            if (choice !== 'accept' && choice !== 'decline')
+                return;
+            consents.push(choice);
+            publish({ ...published, analytics: { measures: true, choice } });
+        },
+    };
+    Object.defineProperty(globalThis, 'houseBridge', { value: bridge, configurable: true });
+    if (published !== null)
+        publish(published);
+    arrive(current);
+    return {
+        navigations,
+        ceremonies,
+        consents,
+        tabs,
+        externalCalls,
+        address: () => current,
+        open(asked) {
+            arrive(appAddress(asked));
+        },
+        publish,
+        message({ from, body }) {
+            queueMicrotask(() => {
+                for (const listener of messageListeners)
+                    listener({ from, body });
+            });
+        },
+        attachRuntime(client) {
+            attached(client);
+        },
+    };
+}

package/docs/families.md

@@ -18,28 +18,32 @@
   `'accepted'` or `'dismissed'` with the User's choice, spending that prompt;
   otherwise, as on every iPhone and iPad, it resolves `'manual'` and the App
   shows its own instructions. A prompt the browser refuses to show, as for a
-  call made without a click, rejects with the browser's own `DOMException`
-  and stays ready. Call it from a click. The standard
+  call made without a click, rejects with an error named and coded by the
+  browser's own error name, with `retryable` false, and stays ready. Call it from a click. The standard
   `display-mode: standalone` media query tells the App it runs installed.
 - **Notifications** - House's own panel alone; an App's or a Site's call
-  rejects with `HouseCeremonyRefused`. `notifications()` answers this browser
+  rejects with an error named `HouseCeremonyRefused`, carrying `code` and `retryable`. `notifications()` answers this browser
   storage's push state: `'on'`, `'off'`, `'blocked'` where the browser refuses
   notifications, or `'unavailable'` where it has no push, as on an iPhone or
   iPad outside a Home-screen app. `notifications(true)` asks the browser's
   permission and subscribes, `notifications(false)` unsubscribes, and each
-  answers the state it leaves; a failure of the browser's push service rejects
-  with the browser's own `DOMException`. Call `notifications(true)` from a
+  answers the state it leaves; a failure of the browser's push service, and
+  of `setBadge`, rejects the same way. Call `notifications(true)` from a
   click. `setBadge(unread)` takes the identifiers of the Human Notifications
   unread in this storage and sets the icon's badge to their number, or clears
   it at none, where the browser shows one.
-- **Status** - the App reference the runtime client is attached under, sync
-  state, credential state and observed failure, `ga`:
+- **Status** - the App reference the runtime client is attached under,
+  `preferences`: the `roomRef` and Path of the App's own preferences document,
+  or `null` until the runtime holds that Room, sync
+  state, credential state and its `expiresAt`, observed failure, `analytics`:
   whether the page measures and the visitor's stored analytics choice, and
-  `service_mode`: `open`, `write-halted` while House refuses writes, so the
+  `serviceMode`: `open`, `write-halted` while House refuses writes, so the
   App can stop retrying them, or `null` while the runtime holds no House
-  connection.
-  The App reports the visitor's choice with `gaConsent('accept')` or
-  `gaConsent('decline')`; the shell hands it to House's analytics loader, and
+  connection. Every status field is camelCase. `onStatus(listener)` and
+  `onAddress(listener)` hand a listener the status and the address the bridge
+  already holds, then each change.
+  The App reports the visitor's choice with `analyticsConsent('accept')` or
+  `analyticsConsent('decline')`; the shell hands it to House's analytics loader, and
   the choice never reaches House.
 - **Site image read** - given a Published Room and an original attachment
   reference, it answers the web copy's path and metadata, or `null` when no
@@ -51,14 +55,14 @@
   path, its size and its `text`, or its bytes as `base64`. The browser keeps
   each answer per App and release: a read naming a release it holds answers
   without asking House, and keeping a newer release drops the earlier one. A
-  refusal is House's `{ error: { code } }`, `app_release_not_found` for an
+  refusal is House's `{ error: { code, retryable } }`, `app_release_not_found` for an
   App with no release; a read House does not answer, or one that outlived
   the browser's signed-in User, is `null`.
 - **External calls** - `callExternal({ url, method, headers, body, slot })`
   has House's server send an HTTPS request to one of the release's declared
   external origins and resolves with the service's `status`, `headers` and its
   body as `body` text or `body_base64`, or a refusal as House's
-  `{ error: { code } }`, or `null` when House does not answer. House fills in the
+  `{ error: { code, retryable } }`, or `null` when House does not answer. House fills in the
   App and its running release; naming an account slot places the key of the
   account the User connected to it, which the App never sees, and naming none
   sends no key. A Site's call names no slot, and the House panel names an
@@ -67,7 +71,7 @@
   another holder of this App sends to this User's running copies, as `from`,
   the sender's User id, and `body`, the JSON value they sent, until the
   function it returns is called. App code sends one through the Runtime's
-  `call('apps/messages/send', { to, body })` with the recipient's User id and
+  `call('message.send', { to, body })` with the recipient's User id and
   a body of at most 32 KiB of JSON; House fills in the App and relays it only
   to copies running now, storing nothing. The panel sends none.
 - **App screenshot read** - given an App reference, `readScreenshot(app)`
@@ -82,23 +86,24 @@
 
 ## The test host
 
-The host plays the shell and the worker: it delivers the address the App starts
-at and each address `open` plays as Back or Forward through the shell's own
-slice below the App's path, admitting nothing, so it delivers `//notes` exactly
-as a browser at `/apps/<app>//notes` does. It records every push and replace
-and answers each with the address the shell would then show, records an
-admitted ceremony, refuses a push, replace or ceremony that is not a
-same-origin absolute path, publishes a status, its `service_mode` included,
-records in `consents` each
-`gaConsent` it takes while that status measures and publishes the status the
-choice leaves, records in `tabs` each `setTab` the shell would take and ignores
-any other, answers a release code read from the `sources` it was given, or
-`null`, answers each `callExternal` from the `external` function it was given, or
-`null`, and records the request in `externalCalls`, answers `readScreenshot`
-from the `screenshots` it was given by App
-reference and `readSiteScreenshot` from the `siteScreenshots` it was given by
-Site identifier, answers every `install()` `'manual'`, as a browser with no install
-prompt does, answers every `notifications()` `'unavailable'`, as a browser
-without push does, settles every `setBadge`, delivers each App message
-`message({ from, body })` plays, and hands `bridge.runtime` the MD Runtime
-client `attachRuntime(client)` gives it.
+`createHouseBridgeTestHost(options)` plays House in one page: it installs a
+bridge object that `houseBridge()` returns, until the next host replaces it.
+It delivers the address the App starts at and each address `open` plays as
+Back or Forward, admitting nothing, so it delivers `//notes` exactly as a
+browser at `/apps/<app>//notes` does. It records every push and replace and
+answers each with the address the shell would then show, records an admitted
+ceremony, and refuses a push, replace or ceremony that is not a same-origin
+absolute path of at most 1,000 characters with an error named
+`HouseNavigationRefused` or `HouseCeremonyRefused`. It publishes a status,
+its `serviceMode` included, records in `consents` each `analyticsConsent` it
+takes while that status measures and publishes the status the choice leaves,
+records in `tabs` each `setTab`, answers a release code read from the
+`sources` it was given, or `null`, answers each `callExternal` from the
+`external` function it was given, or `null`, and records the request in
+`externalCalls`, answers `readScreenshot` from the `screenshots` it was given
+by App reference and `readSiteScreenshot` from the `siteScreenshots` it was
+given by Site identifier, answers every `install()` `'manual'`, as a browser
+with no install prompt does, answers every `notifications()` `'unavailable'`,
+as a browser without push does, settles every `setBadge`, delivers each App
+message `message({ from, body })` plays, and hands `bridge.runtime` the MD
+Runtime client `attachRuntime(client)` gives it.