@agentshouse/app-bridge 0.1.0-alpha.8 → 0.1.0-c07e1058c2cee

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton (trof3039)
+
+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

@@ -2,61 +2,24 @@
 
 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 six families:
+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.
+[docs/families.md](docs/families.md) describes each and the test host.
 
-- **Navigation** - the part of the shell's URL below the App's path, with its
-  query and fragment. The shell delivers it when the App starts and whenever the
-  User navigates; the App asks the shell to push or replace it. The App also
-  sets its tab's title and icon with `setTab({ title, icon })`, either or both:
-  a title of at most 200 characters and an icon given as a base64 `data:` URL
-  of an SVG, PNG, GIF or WebP image of at most 1,048,576 characters. The shell
-  shows them over the App's display name, or a Site's title, and its tab icon
-  until the next load, and ignores a request outside those bounds.
-- **Ceremony** - the App asks the shell to leave for one of House's own
-  purpose-bound authenticated pages. The shell navigates only to a same-origin
-  absolute path, carries its current address as the return target, and the page
-  returns there when it completes. An App names an address House gave it in a
-  reading and composes none.
-- **Status** - the App reference the Runtime port is attached under, sync
-  state, credential state, release availability and observed failure, `ga`:
-  whether the page measures and the visitor's stored analytics choice, and
-  `service_mode`: `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
-  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
-  copy exists. The original bytes never cross this bridge at a Site.
-- **App release code** - `sourceTop(app, release)` answers the top level of
-  the latest successful release of an App the User may use: its folders, its
-  files with their sizes and its root README's text, or `null` for none;
-  `sourceDownload(app, release)` answers every file of that release with its
-  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
-  App with no release; a read House does not answer, or one that outlived
-  the browser's signed-in User, is `null`.
-- **App screenshot read** - given an App reference, `readScreenshot(app)`
-  answers the image this browser captured of that App's screen the first time
-  it ran its current release, as a PNG `Blob` at most 1200 pixels wide, or
-  `null` when this browser holds none. The image stays in the browser; a Site
-  holds none.
+The package 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.
 
-The package carries no credential handling and no Runtime family. It surfaces
-the dedicated Runtime port the worker transfers over the bridge as a plain
-message port, which the App hands to the MD Runtime client entry.
+House's `find_command` "App" is the guide to building an App or a Site.
 
 ## Use
 
 ```js
 import { connectHouseBridge } from '@agentshouse/app-bridge';
-import { connectMdRuntime } from '@agentshouse/mdruntime/client';
 
 const bridge = connectHouseBridge();
-const md = connectMdRuntime(await bridge.runtime);
+const md = await bridge.runtime;
 
 bridge.onAddress((address) => render(address));
 bridge.onStatus((status) => showSync(status.sync));
@@ -76,9 +39,8 @@ async function manageSecurity(securityPath) {
 }
 ```
 
-`bridge.runtime` resolves with a structural `HouseMessagePort`. A consumer whose
-Runtime client entry asks for the DOM `MessagePort` type passes it through
-directly at run time and casts at the type level.
+`bridge.runtime` resolves to the `MdRuntimeClient` of
+`@agentshouse/mdruntime/client`, whose README describes its members.
 
 ## Test without a House
 
@@ -87,22 +49,8 @@ import { connectHouseBridge } from '@agentshouse/app-bridge';
 import { createHouseBridgeTestHost } from '@agentshouse/app-bridge/test-host';
 
 const host = createHouseBridgeTestHost({ address: '/rooms/atlas' });
-const bridge = connectHouseBridge(host.port);
+const bridge = connectHouseBridge(host);
 
 bridge.push('/rooms/atlas/members');
 host.open('/rooms/atlas');
 ```
-
-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 `readScreenshot` from the `screenshots` it was given by App
-reference, and attaches a Runtime port.

package/dist/client/src/bridge.d.ts

@@ -0,0 +1,38 @@
+import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
+import type { HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseBridgePort, HouseGaChoice, HouseImageCopy, HouseInstallation, HouseNotifications, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+export type { HouseImageCopy } from './wire.js';
+export declare class HouseCeremonyRefused extends Error {
+    readonly path: string | null;
+    constructor(path: string | null);
+}
+export declare class HouseNavigationRefused extends Error {
+    readonly address: string | null;
+    constructor(address: string | null);
+}
+export interface HouseBridgeSource {
+    readonly port: Promise<HouseBridgePort>;
+    readonly runtime: Promise<MdRuntimeClient>;
+}
+export interface HouseBridge {
+    readonly runtime: Promise<MdRuntimeClient>;
+    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;
+    readAttachment(room: string, attachment: string): Promise<HouseImageCopy | null>;
+    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;
+    gaConsent(choice: HouseGaChoice): void;
+}
+export declare function connectHouseBridge(source?: HouseBridgeSource): HouseBridge;

package/{client → dist/client}/src/bridge.js

@@ -14,6 +14,46 @@ export class HouseNavigationRefused extends Error {
         this.address = address;
     }
 }
+function pendingAnswer(pending, answer) {
+    const asked = pending.get(answer.id);
+    if (asked === undefined)
+        return null;
+    pending.delete(answer.id);
+    if (answer.refused === true) {
+        asked.reject(new HouseCeremonyRefused(null));
+        return null;
+    }
+    if (answer.refusal !== undefined) {
+        asked.reject(new DOMException(answer.refusal.message, answer.refusal.name));
+        return null;
+    }
+    return asked;
+}
+const FRAME_HOUSES = [
+    'runtime',
+    'status',
+    'screenshot',
+    'address',
+    'ceremony-refused',
+    'navigate-refused',
+    'attachment',
+    'source',
+    'external-call',
+    'install',
+    'notifications',
+    'badge',
+    'app-message',
+];
+function frameMessage(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    const message = value;
+    if (typeof message.house !== 'string')
+        return null;
+    if (!FRAME_HOUSES.includes(message.house))
+        return null;
+    return value;
+}
 function settled() {
     let settle = null;
     const promise = new Promise((resolve, reject) => {
@@ -22,23 +62,31 @@ function settled() {
     return { promise, settle: settle };
 }
 function heldBridge() {
-    const held = globalThis.houseBridge;
-    if (held === undefined)
+    const held = globalThis;
+    if (held.houseBridge === undefined || held.houseRuntime === undefined)
         throw new Error('house_bridge_absent');
-    return held;
+    return { port: held.houseBridge, runtime: held.houseRuntime };
 }
 export function connectHouseBridge(source = heldBridge()) {
-    const runtime = settled();
     const ceremonies = [];
     const navigations = [];
     const attachments = new Map();
     let nextAttachment = 0;
     const sources = new Map();
     let nextSource = 0;
+    const installations = new Map();
+    let nextInstallation = 0;
+    const notifications = new Map();
+    let nextNotifications = 0;
+    const badges = new Map();
+    let nextBadge = 0;
     const screenshots = new Map();
     let nextScreenshot = 0;
+    const externals = new Map();
+    let nextExternal = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
+    const messageListeners = new Set();
     let outbox = [];
     let held = null;
     let address = null;
@@ -50,21 +98,21 @@ export function connectHouseBridge(source = heldBridge()) {
             held.postMessage(message);
     }
     function receive(event) {
-        const data = event.data;
-        if (data === null || typeof data !== 'object')
-            return;
-        if (data.house === 'runtime') {
-            const [port] = event.ports;
-            if (port !== undefined)
-                runtime.settle.resolve(port);
+        const data = frameMessage(event.data);
+        if (data === null)
             return;
-        }
         if (data.house === 'status') {
             status = data.status;
             for (const listener of statusListeners)
                 listener(status);
             return;
         }
+        if (data.house === 'app-message') {
+            const { from, body } = data;
+            for (const listener of messageListeners)
+                listener({ from, body });
+            return;
+        }
         if (data.house === 'address') {
             address = String(data.address);
             if (data.navigated === true)
@@ -82,36 +130,59 @@ export function connectHouseBridge(source = heldBridge()) {
             return;
         }
         if (data.house === 'attachment') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = attachments.get(answer.id);
+            const pending = attachments.get(data.id);
             if (pending === undefined)
                 return;
-            attachments.delete(answer.id);
-            pending.resolve(answer.image ?? null);
+            attachments.delete(data.id);
+            pending.resolve(data.image ?? null);
+            return;
+        }
+        if (data.house === 'install') {
+            const pending = pendingAnswer(installations, data);
+            if (pending !== null && 'outcome' in data)
+                pending.resolve(data.outcome);
+            return;
+        }
+        if (data.house === 'notifications') {
+            const pending = pendingAnswer(notifications, data);
+            if (pending !== null && 'state' in data)
+                pending.resolve(data.state);
+            return;
+        }
+        if (data.house === 'badge') {
+            pendingAnswer(badges, data)?.resolve();
             return;
         }
         if (data.house === 'source') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
+                return;
+            const pending = sources.get(data.id);
+            if (pending === undefined)
+                return;
+            sources.delete(data.id);
+            pending.resolve(data.answer ?? null);
+            return;
+        }
+        if (data.house === 'external-call') {
+            if (typeof data.id !== 'number')
                 return;
-            const pending = sources.get(answer.id);
+            const pending = externals.get(data.id);
             if (pending === undefined)
                 return;
-            sources.delete(answer.id);
-            pending.resolve(answer.answer ?? null);
+            externals.delete(data.id);
+            pending.resolve(data.answer ?? null);
             return;
         }
         if (data.house === 'screenshot') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = screenshots.get(answer.id);
+            const pending = screenshots.get(data.id);
             if (pending === undefined)
                 return;
-            screenshots.delete(answer.id);
-            pending.resolve(answer.image ?? null);
+            screenshots.delete(data.id);
+            pending.resolve(data.image ?? null);
             return;
         }
         if (data.house === 'ceremony-refused') {
@@ -122,7 +193,7 @@ export function connectHouseBridge(source = heldBridge()) {
             pending?.settle.reject(new HouseCeremonyRefused(named));
         }
     }
-    void source.then((port) => {
+    void source.port.then((port) => {
         held = port;
         port.addEventListener('message', receive);
         port.start();
@@ -138,6 +209,16 @@ export function connectHouseBridge(source = heldBridge()) {
         send({ house, id, app, release });
         return pending.promise;
     }
+    function screenshot(house, asked) {
+        const pending = settled();
+        const id = ++nextScreenshot;
+        screenshots.set(id, pending.settle);
+        if (house === 'screenshot-read' && 'app' in asked)
+            send({ house, id, app: asked.app });
+        if (house === 'site-screenshot-read' && 'site' in asked)
+            send({ house, id, site: asked.site });
+        return pending.promise;
+    }
     function navigate(mode, asked) {
         const pending = settled();
         navigations.push({ address: asked, settle: pending.settle });
@@ -145,7 +226,7 @@ export function connectHouseBridge(source = heldBridge()) {
         return pending.promise;
     }
     return {
-        runtime: runtime.promise,
+        runtime: source.runtime,
         address() {
             return address;
         },
@@ -167,6 +248,27 @@ export function connectHouseBridge(source = heldBridge()) {
             send({ house: 'ceremony', path });
             return pending.promise;
         },
+        install() {
+            const pending = settled();
+            const id = ++nextInstallation;
+            installations.set(id, pending.settle);
+            send({ house: 'install', id });
+            return pending.promise;
+        },
+        notifications(on) {
+            const pending = settled();
+            const id = ++nextNotifications;
+            notifications.set(id, pending.settle);
+            send({ house: 'notifications', id, on });
+            return pending.promise;
+        },
+        setBadge(unread) {
+            const pending = settled();
+            const id = ++nextBadge;
+            badges.set(id, pending.settle);
+            send({ house: 'badge', id, unread });
+            return pending.promise;
+        },
         setTab(tab) {
             send({ house: 'tab', title: tab.title, icon: tab.icon });
         },
@@ -183,13 +285,19 @@ export function connectHouseBridge(source = heldBridge()) {
         sourceDownload(app, release) {
             return readSource('source-download', app, release);
         },
-        readScreenshot(app) {
+        callExternal(request) {
             const pending = settled();
-            const id = ++nextScreenshot;
-            screenshots.set(id, pending.settle);
-            send({ house: 'screenshot-read', id, app });
+            const id = ++nextExternal;
+            externals.set(id, pending.settle);
+            send({ house: 'external-call', id, request });
             return pending.promise;
         },
+        readScreenshot(app) {
+            return screenshot('screenshot-read', { app });
+        },
+        readSiteScreenshot(site) {
+            return screenshot('site-screenshot-read', { site });
+        },
         status() {
             return status;
         },
@@ -199,6 +307,12 @@ export function connectHouseBridge(source = heldBridge()) {
                 statusListeners.delete(listener);
             };
         },
+        messages(listener) {
+            messageListeners.add(listener);
+            return () => {
+                messageListeners.delete(listener);
+            };
+        },
         gaConsent(choice) {
             send({ house: 'ga/consent', choice });
         },

package/dist/client/src/index.d.ts

@@ -0,0 +1,3 @@
+export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, type HouseBridgeSource, type HouseImageCopy, } from './bridge.js';
+export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
+export type { HouseAppMessage, HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseExternalAnswer, HouseExternalRequest, HouseGa, HouseGaChoice, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceFile, HouseSourceTop, HouseStatus, HouseSyncState, } from './wire.js';

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

@@ -1,19 +1,21 @@
-import type { HouseImageCopy } from './bridge.js';
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+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';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
 }
-export interface HouseBridgeTestHost {
-    readonly port: Promise<HouseBridgePort>;
+export interface HouseBridgeTestHost extends HouseBridgeSource {
     readonly navigations: readonly HouseBridgeNavigation[];
     readonly ceremonies: readonly string[];
     readonly consents: readonly HouseGaChoice[];
     readonly tabs: readonly HouseTab[];
+    readonly externalCalls: readonly HouseExternalRequest[];
     address(): string;
     open(address: string): void;
     publish(status: HouseStatus): void;
-    attachRuntime(runtime: HouseMessagePort): void;
+    message(message: HouseAppMessage): void;
+    attachRuntime(runtime: MdRuntimeClient): void;
 }
 export interface HouseBridgeTestHostOptions {
     readonly address?: string;
@@ -26,5 +28,7 @@ export interface HouseBridgeTestHostOptions {
         readonly download: HouseSourceDownload;
     }[];
     readonly screenshots?: Readonly<Record<string, Blob>>;
+    readonly siteScreenshots?: Readonly<Record<string, Blob>>;
+    readonly external?: (request: HouseExternalRequest) => HouseExternalAnswer | HouseRefusal | null | Promise<HouseExternalAnswer | HouseRefusal | null>;
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

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

@@ -17,13 +17,18 @@ export function createHouseBridgeTestHost(options = {}) {
     const ceremonies = [];
     const consents = [];
     const tabs = [];
+    const externalCalls = [];
     const listeners = new Set();
     const queued = [];
     let started = false;
     let address = appAddressOf('/', options.address ?? '/');
     let status = options.status ?? null;
-    function deliver(data, ports = []) {
-        const event = { data, ports };
+    let attached = () => { };
+    const runtime = new Promise((resolve) => {
+        attached = resolve;
+    });
+    function deliver(data) {
+        const event = { data };
         if (!started) {
             queued.push(event);
             return;
@@ -79,6 +84,15 @@ export function createHouseBridgeTestHost(options = {}) {
         else if (data.house === 'ceremony') {
             ceremony(data.path);
         }
+        else if (data.house === 'install') {
+            deliver({ house: 'install', id: data.id, outcome: 'manual' });
+        }
+        else if (data.house === 'notifications') {
+            deliver({ house: 'notifications', id: data.id, state: 'unavailable' });
+        }
+        else if (data.house === 'badge') {
+            deliver({ house: 'badge', id: data.id });
+        }
         else if (data.house === 'tab') {
             const change = tabChange(data);
             if (change !== null)
@@ -109,11 +123,21 @@ export function createHouseBridgeTestHost(options = {}) {
                     },
             });
         }
+        else if (data.house === 'external-call') {
+            const asked = data;
+            externalCalls.push(asked.request);
+            void Promise.resolve(options.external?.(asked.request) ?? null).then((answer) => deliver({ house: 'external-call', id: asked.id, answer }));
+        }
         else if (data.house === 'screenshot-read') {
             const asked = data;
             const held = typeof asked.app === 'string' ? options.screenshots?.[asked.app] : undefined;
             deliver({ house: 'screenshot', id: asked.id, image: held ?? null });
         }
+        else if (data.house === 'site-screenshot-read') {
+            const asked = data;
+            const held = typeof asked.site === 'string' ? options.siteScreenshots?.[asked.site] : undefined;
+            deliver({ house: 'screenshot', id: asked.id, image: held ?? null });
+        }
     }
     const port = {
         postMessage(message) {
@@ -138,10 +162,12 @@ export function createHouseBridgeTestHost(options = {}) {
     deliver({ house: 'address', address, navigated: false });
     return {
         port: Promise.resolve(port),
+        runtime,
         navigations,
         ceremonies,
         consents,
         tabs,
+        externalCalls,
         address() {
             return address;
         },
@@ -149,8 +175,11 @@ export function createHouseBridgeTestHost(options = {}) {
             arrive(appAddressOf('/', asked), false);
         },
         publish,
-        attachRuntime(runtime) {
-            deliver({ house: 'runtime' }, [runtime]);
+        message(message) {
+            deliver({ house: 'app-message', from: message.from, body: message.body });
+        },
+        attachRuntime(client) {
+            attached(client);
         },
     };
 }

package/dist/client/src/wire.d.ts

@@ -0,0 +1,215 @@
+import type { TabChange } from '../../src/apps/tab.js';
+export interface HouseBridgeEvent {
+    readonly data: unknown;
+}
+export interface HouseBridgePort {
+    postMessage(message: HouseFrameRequest): void;
+    addEventListener(type: 'message', listener: (event: HouseBridgeEvent) => void): void;
+    start(): void;
+}
+export interface HouseSyncState {
+    readonly state: string;
+    readonly providerUnreachable: boolean;
+}
+export interface HouseCredentialState {
+    readonly state: 'none' | 'held' | 'rejected';
+    readonly expires_at: number | null;
+}
+export type HouseGaChoice = 'accept' | 'decline';
+export interface HouseGa {
+    readonly measures: boolean;
+    readonly choice: HouseGaChoice | null;
+}
+export interface HouseStatus {
+    readonly app: string | null;
+    readonly preferences: {
+        readonly room_ref: string;
+        readonly path: string;
+    } | null;
+    readonly runtime: string;
+    readonly credential: HouseCredentialState;
+    readonly sync: HouseSyncState | null;
+    readonly refusal: {
+        readonly reason: string;
+    } | null;
+    readonly loss: string | null;
+    readonly ga: HouseGa;
+    readonly service_mode: 'open' | 'write-halted' | null;
+    readonly offline: boolean;
+}
+export type HouseNavigationMode = 'push' | 'replace';
+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 type HouseTab = TabChange;
+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;
+    };
+}
+export interface HouseAppMessage {
+    readonly from: string;
+    readonly body: unknown;
+}
+export type HouseInstallation = 'accepted' | 'dismissed' | 'manual';
+export type HouseNotifications = 'on' | 'off' | 'blocked' | 'unavailable';
+export interface HouseImageCopy {
+    readonly attachment: string;
+    readonly copy: string;
+    readonly name: string;
+    readonly media_type: string;
+}
+export interface HouseFrameRefusal {
+    readonly name: string;
+    readonly message: string;
+}
+export type HouseFrameRequest = {
+    readonly house: 'navigate';
+    readonly mode: HouseNavigationMode;
+    readonly address: string;
+} | ({
+    readonly house: 'tab';
+} & HouseTab) | {
+    readonly house: 'ceremony';
+    readonly path: string;
+} | {
+    readonly house: 'install';
+    readonly id: number;
+} | {
+    readonly house: 'notifications';
+    readonly id: number;
+    readonly on?: boolean;
+} | {
+    readonly house: 'badge';
+    readonly id: number;
+    readonly unread: readonly string[];
+} | {
+    readonly house: 'attachment-read';
+    readonly id: number;
+    readonly room: string;
+    readonly attachment: string;
+} | {
+    readonly house: 'source-top' | 'source-download';
+    readonly id: number;
+    readonly app: string;
+    readonly release?: string;
+} | {
+    readonly house: 'external-call';
+    readonly id: number;
+    readonly request: HouseExternalRequest;
+} | {
+    readonly house: 'screenshot-read';
+    readonly id: number;
+    readonly app: string;
+} | {
+    readonly house: 'site-screenshot-read';
+    readonly id: number;
+    readonly site: string;
+} | {
+    readonly house: 'ga/consent';
+    readonly choice: HouseGaChoice;
+};
+export type HouseInstallAnswer = {
+    readonly outcome: HouseInstallation;
+} | {
+    readonly refusal: HouseFrameRefusal;
+};
+export type HouseNotificationAnswer = {
+    readonly refused: true;
+} | {
+    readonly refusal: HouseFrameRefusal;
+} | {
+    readonly state: HouseNotifications;
+};
+export type HouseBadgeAnswer = {
+    readonly refused: true;
+} | {
+    readonly refusal: HouseFrameRefusal;
+} | {
+    readonly refused?: never;
+    readonly refusal?: never;
+};
+export type HouseFrameMessage = {
+    readonly house: 'runtime';
+} | {
+    readonly house: 'status';
+    readonly status: HouseStatus;
+} | {
+    readonly house: 'screenshot';
+    readonly id: number;
+    readonly image: Blob | null;
+} | {
+    readonly house: 'address';
+    readonly address: string;
+    readonly navigated: boolean;
+} | {
+    readonly house: 'ceremony-refused';
+    readonly path: string | null;
+} | {
+    readonly house: 'navigate-refused';
+    readonly address: string | null;
+} | {
+    readonly house: 'attachment';
+    readonly id: number;
+    readonly image: HouseImageCopy | null;
+} | {
+    readonly house: 'source';
+    readonly id: number;
+    readonly answer: HouseSourceTop | HouseSourceDownload | HouseRefusal | null;
+} | {
+    readonly house: 'external-call';
+    readonly id: number;
+    readonly answer: HouseExternalAnswer | HouseRefusal | null;
+} | ({
+    readonly house: 'install';
+    readonly id: number;
+} & HouseInstallAnswer) | ({
+    readonly house: 'notifications';
+    readonly id: number;
+} & HouseNotificationAnswer) | ({
+    readonly house: 'badge';
+    readonly id: number;
+} & HouseBadgeAnswer) | {
+    readonly house: 'app-message';
+    readonly from: string;
+    readonly body: unknown;
+};
+export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;
+export {};

package/{src → dist/src}/apps/remainder.js

@@ -12,5 +12,5 @@ export function appAddressOf(root, address) {
 export function shellAddressOf(root, appAddress) {
     const { path, rest } = split(appAddress);
     const below = path === '/' ? '' : path;
-    return `${root === '/' ? '' : root}${below}${rest}` || '/';
+    return `${`${root === '/' ? '' : root}${below}` || '/'}${rest}`;
 }

package/docs/families.md

@@ -0,0 +1,106 @@
+# The App bridge's families
+
+- **Navigation** - the part of the shell's URL below the App's path, with its
+  query and fragment. The shell delivers it when the App starts and whenever the
+  User navigates; the App asks the shell to push or replace it. The App also
+  sets its tab's title and icon with `setTab({ title, icon })`, either or both:
+  a title of at most 200 characters and an icon given as a base64 `data:` URL
+  of an SVG, PNG, GIF or WebP image of at most 1,048,576 characters. The shell
+  shows them over the App's display name, or a Site's title, and its tab icon
+  until the next load, and ignores a request outside those bounds.
+- **Ceremony** - the App asks the shell to leave for one of House's own
+  purpose-bound authenticated pages. The shell navigates only to a same-origin
+  absolute path, carries its current address as the return target, and the page
+  returns there when it completes. An App names an address House gave it in a
+  reading and composes none.
+- **Installation** - `install()` offers the page as a Home-screen app. Where the
+  browser has an install prompt ready the shell shows it and the call resolves
+  `'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
+  `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
+  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
+  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,
+  `preferences`: the `room_ref` and Path of the App's own preferences document,
+  or `null` until the runtime holds that Room, sync
+  state, credential state and observed failure, `ga`:
+  whether the page measures and the visitor's stored analytics choice, and
+  `service_mode`: `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
+  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
+  copy exists. The original bytes never cross this bridge at a Site.
+- **App release code** - `sourceTop(app, release)` answers the top level of
+  the latest successful release of an App the User may use: its folders, its
+  files with their sizes and its root README's text, or `null` for none;
+  `sourceDownload(app, release)` answers every file of that release with its
+  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
+  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
+  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
+  `account` instead. `body_base64` replaces `body` for bytes.
+- **App messages** - `messages(listener)` hands the listener each message
+  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
+  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)`
+  answers the image this browser captured of that App's screen the first time
+  it ran its current release, as a PNG `Blob` at most 1200 pixels wide, or
+  `null` when this browser holds none. The image stays in the browser; a Site
+  holds none.
+- **Site screenshot read** - given one of the User's Site identifiers,
+  `readSiteScreenshot(site)` answers the image House captured of that Site
+  after its latest release, as a JPEG `Blob`, or `null` when House holds none
+  or does not answer. A Site's own renderer reads none.
+
+## 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.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-alpha.8",
-  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, status, Site image reads, App release code and App screenshot reads, with an in-page test host.",
-  "license": "UNLICENSED",
+  "version": "0.1.0-c07e1058c2cee",
+  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, installation, notifications and the icon badge, status, Site image reads, App release code, App and Site screenshot reads, and App messages, with an in-page test host.",
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -10,21 +10,21 @@
   },
   "exports": {
     ".": {
-      "types": "./client/src/index.d.ts",
-      "default": "./client/src/index.js"
+      "types": "./dist/client/src/index.d.ts",
+      "default": "./dist/client/src/index.js"
     },
     "./test-host": {
-      "types": "./client/src/test-host.d.ts",
-      "default": "./client/src/test-host.js"
+      "types": "./dist/client/src/test-host.d.ts",
+      "default": "./dist/client/src/test-host.js"
     }
   },
+  "dependencies": {
+    "@agentshouse/mdruntime": "0.1.0-c7274d650bd05"
+  },
   "files": [
-    "client/src/*.js",
-    "client/src/*.d.ts",
-    "src/apps/remainder.js",
-    "src/apps/remainder.d.ts",
-    "src/apps/tab.js",
-    "src/apps/tab.d.ts",
-    "README.md"
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
   ]
 }

package/client/src/bridge.d.ts

@@ -1,32 +0,0 @@
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseSourceDownload, HouseSourceRefusal, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
-export declare class HouseCeremonyRefused extends Error {
-    readonly path: string | null;
-    constructor(path: string | null);
-}
-export declare class HouseNavigationRefused extends Error {
-    readonly address: string | null;
-    constructor(address: string | null);
-}
-export interface HouseImageCopy {
-    readonly attachment: string;
-    readonly copy: string;
-    readonly name: string;
-    readonly media_type: string;
-}
-export interface HouseBridge {
-    readonly runtime: Promise<HouseMessagePort>;
-    address(): string | null;
-    onAddress(listener: (address: string) => void): () => void;
-    push(address: string): Promise<string>;
-    replace(address: string): Promise<string>;
-    ceremony(path: string): Promise<never>;
-    setTab(tab: HouseTab): void;
-    readAttachment(room: string, attachment: string): Promise<HouseImageCopy | null>;
-    sourceTop(app: string, release?: string): Promise<HouseSourceTop | HouseSourceRefusal | null>;
-    sourceDownload(app: string, release?: string): Promise<HouseSourceDownload | HouseSourceRefusal | null>;
-    readScreenshot(app: string): Promise<Blob | null>;
-    status(): HouseStatus | null;
-    onStatus(listener: (status: HouseStatus) => void): () => void;
-    gaConsent(choice: HouseGaChoice): void;
-}
-export declare function connectHouseBridge(source?: Promise<HouseBridgePort>): HouseBridge;

package/client/src/index.d.ts

@@ -1,3 +0,0 @@
-export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, type HouseImageCopy, } from './bridge.js';
-export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
-export type { HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseGa, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceFile, HouseSourceRefusal, HouseSourceTop, HouseStatus, HouseSyncState, } from './wire.js';

package/client/src/wire.d.ts

@@ -1,69 +0,0 @@
-import type { TabChange } from '../../src/apps/tab.js';
-export interface HouseBridgeEvent {
-    readonly data: unknown;
-    readonly ports: readonly HouseMessagePort[];
-}
-export interface HouseMessagePort {
-    postMessage(message: unknown): void;
-    addEventListener(type: 'message', listener: (event: HouseBridgeEvent) => void): void;
-    start(): void;
-}
-export type HouseBridgePort = HouseMessagePort;
-export interface HouseSyncState {
-    readonly state: string;
-    readonly providerUnreachable: boolean;
-}
-export interface HouseCredentialState {
-    readonly state: 'none' | 'held' | 'rejected';
-    readonly expires_at: number | null;
-}
-export type HouseGaChoice = 'accept' | 'decline';
-export interface HouseGa {
-    readonly measures: boolean;
-    readonly choice: HouseGaChoice | null;
-}
-export interface HouseStatus {
-    readonly app: string;
-    readonly runtime: string;
-    readonly credential: HouseCredentialState;
-    readonly sync: HouseSyncState | null;
-    readonly refusal: {
-        readonly reason: string;
-    } | null;
-    readonly loss: string | null;
-    readonly release: unknown;
-    readonly ga: HouseGa;
-    readonly service_mode: 'open' | 'write-halted' | null;
-}
-export type HouseNavigationMode = 'push' | 'replace';
-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 HouseSourceRefusal {
-    readonly error: {
-        readonly code: string;
-    };
-}
-export type HouseTab = TabChange;
-export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;
-export {};