@agentshouse/app-bridge 0.1.0-c415579fa0c3a → 0.1.0-c58a055eeaa71

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,7 +35,7 @@ async function manageSecurity(securityPath) {
   try {
     await bridge.ceremony(securityPath);
   } catch (refusal) {
-    report(refusal);
+    if (refusal.name === 'HouseCeremonyRefused') report(refusal.path);
   }
 }
 ```
@@ -43,11 +46,11 @@ async function manageSecurity(securityPath) {
 ## 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/index.d.ts

@@ -0,0 +1,139 @@
+import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
+type Open<Value extends string> = Value | (string & {});
+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 HouseImageCopy {
+    readonly attachment: string;
+    readonly copy: string;
+    readonly name: string;
+    readonly media_type: string;
+}
+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<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;
+    analyticsConsent(choice: HouseAnalyticsChoice): void;
+}
+export interface HouseHeld {
+    readonly houseBridge: HouseBridge;
+}
+export declare const houseBridge: () => HouseBridge;
+export {};

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, HouseImageCopy, 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;

package/dist/test-host.js

@@ -0,0 +1,165 @@
+const HOST_ORIGIN = 'https://house.invalid';
+const ADDRESS_MAX_CHARS = 1000;
+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,
+    });
+}
+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) {
+        const target = sameOriginPath(asked);
+        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) {
+            addressListeners.add(listener);
+            return () => {
+                addressListeners.delete(listener);
+            };
+        },
+        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);
+        },
+        readAttachment(room, attachment) {
+            const image = options.images?.find((entry) => entry.room === room && entry.attachment === attachment);
+            return Promise.resolve(image === undefined
+                ? null
+                : {
+                    attachment: image.attachment,
+                    copy: image.copy,
+                    name: image.name,
+                    media_type: image.media_type,
+                });
+        },
+        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) {
+            statusListeners.add(listener);
+            return () => {
+                statusListeners.delete(listener);
+            };
+        },
+        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,30 +18,30 @@
   `'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,
-  `preferences`: the `room_ref` and Path of the App's own preferences document,
+  `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 observed failure, `ga`:
+  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.
+  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
@@ -53,14 +53,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
@@ -69,7 +69,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)`
@@ -84,23 +84,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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-c415579fa0c3a",
-  "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.",
+  "version": "0.1.0-c58a055eeaa71",
+  "description": "Types of the agents.house App bridge House hands every App: 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 accessor and an in-page test host.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -10,16 +10,16 @@
   },
   "exports": {
     ".": {
-      "types": "./dist/client/src/index.d.ts",
-      "default": "./dist/client/src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./test-host": {
-      "types": "./dist/client/src/test-host.d.ts",
-      "default": "./dist/client/src/test-host.js"
+      "types": "./dist/test-host.d.ts",
+      "default": "./dist/test-host.js"
     }
   },
   "dependencies": {
-    "@agentshouse/mdruntime": "0.1.0-c6e4c19c13638"
+    "@agentshouse/mdruntime": "0.1.0-c967d1ca66fee"
   },
   "files": [
     "dist",

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

@@ -1,38 +0,0 @@
-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;