@agentshouse/app-bridge 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -2,18 +2,67 @@
 
 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 three families:
+port's one listener. It carries eight 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.
+  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** - sync state, credential state, release availability and observed
-  failure.
+- **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 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. It surfaces
 the dedicated Runtime port the worker transfers over the bridge as a plain
@@ -30,6 +79,7 @@ const md = connectMdRuntime(await bridge.runtime);
 
 bridge.onAddress((address) => render(address));
 bridge.onStatus((status) => showSync(status.sync));
+bridge.setTab({ title: 'Atlas (3)' });
 
 open('/rooms/atlas');
 function open(address) {
@@ -63,6 +113,17 @@ host.open('/rooms/atlas');
 ```
 
 The host plays the shell and the worker: it delivers the address the App starts
-at, records every push and replace and answers each with the address the shell
-would then show, records an admitted ceremony, refuses one that is not a
-same-origin absolute path, publishes a status, and attaches a Runtime port.
+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, 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`, and attaches a Runtime port.

package/client/src/bridge.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+type HouseInstallation = 'accepted' | 'dismissed' | 'manual';
+type HouseNotifications = 'on' | 'off' | 'blocked' | 'unavailable';
+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>;
+    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 | 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;
+export {};

package/client/src/bridge.js

@@ -0,0 +1,261 @@
+export class HouseCeremonyRefused extends Error {
+    path;
+    constructor(path) {
+        super('house_ceremony_refused');
+        this.name = 'HouseCeremonyRefused';
+        this.path = path;
+    }
+}
+export class HouseNavigationRefused extends Error {
+    address;
+    constructor(address) {
+        super('house_navigation_refused');
+        this.name = 'HouseNavigationRefused';
+        this.address = address;
+    }
+}
+function answered(pending, answer, value) {
+    if (typeof answer.id !== 'number')
+        return;
+    const asked = pending.get(answer.id);
+    if (asked === undefined)
+        return;
+    pending.delete(answer.id);
+    if (answer.refused === true)
+        asked.reject(new HouseCeremonyRefused(null));
+    else if (answer.refusal !== undefined)
+        asked.reject(new DOMException(answer.refusal.message, answer.refusal.name));
+    else
+        asked.resolve(value);
+}
+function settled() {
+    let settle = null;
+    const promise = new Promise((resolve, reject) => {
+        settle = { resolve, reject };
+    });
+    return { promise, settle: settle };
+}
+function heldBridge() {
+    const held = globalThis.houseBridge;
+    if (held === undefined)
+        throw new Error('house_bridge_absent');
+    return held;
+}
+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 addressListeners = new Set();
+    const statusListeners = new Set();
+    let outbox = [];
+    let held = null;
+    let address = null;
+    let status = null;
+    function send(message) {
+        if (held === null)
+            outbox?.push(message);
+        else
+            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);
+            return;
+        }
+        if (data.house === 'status') {
+            status = data.status;
+            for (const listener of statusListeners)
+                listener(status);
+            return;
+        }
+        if (data.house === 'address') {
+            address = String(data.address);
+            if (data.navigated === true)
+                navigations.shift()?.settle.resolve(address);
+            for (const listener of addressListeners)
+                listener(address);
+            return;
+        }
+        if (data.house === 'navigate-refused') {
+            const refused = data.address;
+            const named = typeof refused === 'string' ? refused : null;
+            const index = named === null ? 0 : navigations.findIndex((one) => one.address === named);
+            const [pending] = navigations.splice(index < 0 ? 0 : index, 1);
+            pending?.settle.reject(new HouseNavigationRefused(named));
+            return;
+        }
+        if (data.house === 'attachment') {
+            const answer = data;
+            if (typeof answer.id !== 'number')
+                return;
+            const pending = attachments.get(answer.id);
+            if (pending === undefined)
+                return;
+            attachments.delete(answer.id);
+            pending.resolve(answer.image ?? null);
+            return;
+        }
+        if (data.house === 'install') {
+            const answer = data;
+            answered(installations, answer, answer.outcome);
+            return;
+        }
+        if (data.house === 'notifications') {
+            const answer = data;
+            answered(notifications, answer, answer.state);
+            return;
+        }
+        if (data.house === 'badge') {
+            answered(badges, data, undefined);
+            return;
+        }
+        if (data.house === 'source') {
+            const answer = data;
+            if (typeof answer.id !== 'number')
+                return;
+            const pending = sources.get(answer.id);
+            if (pending === undefined)
+                return;
+            sources.delete(answer.id);
+            pending.resolve(answer.answer ?? null);
+            return;
+        }
+        if (data.house === 'screenshot') {
+            const answer = data;
+            if (typeof answer.id !== 'number')
+                return;
+            const pending = screenshots.get(answer.id);
+            if (pending === undefined)
+                return;
+            screenshots.delete(answer.id);
+            pending.resolve(answer.image ?? null);
+            return;
+        }
+        if (data.house === 'ceremony-refused') {
+            const refused = data.path;
+            const named = typeof refused === 'string' ? refused : null;
+            const index = named === null ? 0 : ceremonies.findIndex((one) => one.path === named);
+            const [pending] = ceremonies.splice(index < 0 ? 0 : index, 1);
+            pending?.settle.reject(new HouseCeremonyRefused(named));
+        }
+    }
+    void source.then((port) => {
+        held = port;
+        port.addEventListener('message', receive);
+        port.start();
+        const waiting = outbox ?? [];
+        outbox = null;
+        for (const message of waiting)
+            port.postMessage(message);
+    });
+    function readSource(house, app, release) {
+        const pending = settled();
+        const id = ++nextSource;
+        sources.set(id, pending.settle);
+        send({ house, id, app, release });
+        return pending.promise;
+    }
+    function navigate(mode, asked) {
+        const pending = settled();
+        navigations.push({ address: asked, settle: pending.settle });
+        send({ house: 'navigate', mode, address: asked });
+        return pending.promise;
+    }
+    return {
+        runtime: runtime.promise,
+        address() {
+            return address;
+        },
+        onAddress(listener) {
+            addressListeners.add(listener);
+            return () => {
+                addressListeners.delete(listener);
+            };
+        },
+        push(asked) {
+            return navigate('push', asked);
+        },
+        replace(asked) {
+            return navigate('replace', asked);
+        },
+        ceremony(path) {
+            const pending = settled();
+            ceremonies.push({ path, settle: pending.settle });
+            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 });
+        },
+        readAttachment(room, attachment) {
+            const pending = settled();
+            const id = ++nextAttachment;
+            attachments.set(id, pending.settle);
+            send({ house: 'attachment-read', id, room, attachment });
+            return pending.promise;
+        },
+        sourceTop(app, release) {
+            return readSource('source-top', app, release);
+        },
+        sourceDownload(app, release) {
+            return readSource('source-download', app, release);
+        },
+        readScreenshot(app) {
+            const pending = settled();
+            const id = ++nextScreenshot;
+            screenshots.set(id, pending.settle);
+            send({ house: 'screenshot-read', id, app });
+            return pending.promise;
+        },
+        status() {
+            return status;
+        },
+        onStatus(listener) {
+            statusListeners.add(listener);
+            return () => {
+                statusListeners.delete(listener);
+            };
+        },
+        gaConsent(choice) {
+            send({ house: 'ga/consent', choice });
+        },
+    };
+}

package/client/src/index.d.ts

@@ -0,0 +1,3 @@
+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/{test-host.d.ts → client/src/test-host.d.ts}

@@ -1,4 +1,5 @@
-import type { HouseBridgePort, HouseMessagePort, HouseNavigationMode, HouseStatus } from './wire.js';
+import type { HouseImageCopy } from './bridge.js';
+import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
@@ -7,6 +8,8 @@ export interface HouseBridgeTestHost {
     readonly port: Promise<HouseBridgePort>;
     readonly navigations: readonly HouseBridgeNavigation[];
     readonly ceremonies: readonly string[];
+    readonly consents: readonly HouseGaChoice[];
+    readonly tabs: readonly HouseTab[];
     address(): string;
     open(address: string): void;
     publish(status: HouseStatus): void;
@@ -15,5 +18,13 @@ export interface HouseBridgeTestHost {
 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;
+    }[];
+    readonly screenshots?: Readonly<Record<string, Blob>>;
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

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

@@ -1,3 +1,5 @@
+import { appAddressOf } from '../../src/apps/remainder.js';
+import { tabChange } from '../../src/apps/tab.js';
 import { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
 const HOST_ORIGIN = 'https://house.invalid';
 function sameOriginPath(value) {
@@ -13,10 +15,13 @@ function sameOriginPath(value) {
 export function createHouseBridgeTestHost(options = {}) {
     const navigations = [];
     const ceremonies = [];
+    const consents = [];
+    const tabs = [];
     const listeners = new Set();
     const queued = [];
     let started = false;
-    let address = sameOriginPath(options.address ?? '/') ?? '/';
+    let address = appAddressOf('/', options.address ?? '/');
+    let status = options.status ?? null;
     function deliver(data, ports = []) {
         const event = { data, ports };
         if (!started) {
@@ -52,6 +57,18 @@ export function createHouseBridgeTestHost(options = {}) {
         }
         ceremonies.push(target);
     }
+    function publish(next) {
+        status = next;
+        deliver({ house: 'status', status });
+    }
+    function consent(choice) {
+        if (status === null || !status.ga.measures)
+            return;
+        if (choice !== 'accept' && choice !== 'decline')
+            return;
+        consents.push(choice);
+        publish({ ...status, ga: { measures: true, choice } });
+    }
     function receive(message) {
         const data = message;
         if (data === null || typeof data !== 'object')
@@ -62,6 +79,50 @@ 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)
+                tabs.push(change);
+        }
+        else if (data.house === 'ga/consent') {
+            consent(data.choice);
+        }
+        else if (data.house === 'source-top' || data.house === 'source-download') {
+            const asked = data;
+            const source = options.sources?.find((entry) => entry.top.app_ref === asked.app);
+            const answer = source === undefined ? null : data.house === 'source-top' ? source.top : source.download;
+            deliver({ house: 'source', id: asked.id, answer });
+        }
+        else if (data.house === 'attachment-read') {
+            const asked = data;
+            const image = options.images?.find((entry) => entry.room === asked.room && entry.attachment === asked.attachment);
+            deliver({
+                house: 'attachment',
+                id: asked.id,
+                image: image === undefined
+                    ? null
+                    : {
+                        attachment: image.attachment,
+                        copy: image.copy,
+                        name: image.name,
+                        media_type: image.media_type,
+                    },
+            });
+        }
+        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 });
+        }
     }
     const port = {
         postMessage(message) {
@@ -81,24 +142,22 @@ export function createHouseBridgeTestHost(options = {}) {
             });
         },
     };
-    if (options.status !== undefined)
-        deliver({ house: 'status', status: options.status });
+    if (status !== null)
+        deliver({ house: 'status', status });
     deliver({ house: 'address', address, navigated: false });
     return {
         port: Promise.resolve(port),
         navigations,
         ceremonies,
+        consents,
+        tabs,
         address() {
             return address;
         },
         open(asked) {
-            const target = sameOriginPath(asked);
-            if (target !== null)
-                arrive(target, false);
-        },
-        publish(status) {
-            deliver({ house: 'status', status });
+            arrive(appAddressOf('/', asked), false);
         },
+        publish,
         attachRuntime(runtime) {
             deliver({ house: 'runtime' }, [runtime]);
         },

package/client/src/wire.d.ts

@@ -0,0 +1,69 @@
+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 {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-alpha.1",
-  "description": "Renderer-side client of the agents.house App bridge: navigation, ceremonies and status, with an in-page test host.",
+  "version": "0.1.0-alpha.10",
+  "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 and App screenshot reads, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -10,17 +10,21 @@
   },
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+      "types": "./client/src/index.d.ts",
+      "default": "./client/src/index.js"
     },
     "./test-host": {
-      "types": "./test-host.d.ts",
-      "default": "./test-host.js"
+      "types": "./client/src/test-host.d.ts",
+      "default": "./client/src/test-host.js"
     }
   },
   "files": [
-    "*.js",
-    "*.d.ts",
+    "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"
   ]
 }

package/src/apps/remainder.d.ts

@@ -0,0 +1,2 @@
+export declare function appAddressOf(root: string, address: string): string;
+export declare function shellAddressOf(root: string, appAddress: string): string;

package/src/apps/remainder.js

@@ -0,0 +1,16 @@
+function split(address) {
+    const mark = address.search(/[?#]/u);
+    return mark < 0
+        ? { path: address, rest: '' }
+        : { path: address.slice(0, mark), rest: address.slice(mark) };
+}
+export function appAddressOf(root, address) {
+    const { path, rest } = split(address);
+    const below = root === '/' ? path : path.slice(root.length);
+    return `${below.startsWith('/') ? below : `/${below}`}${rest}`;
+}
+export function shellAddressOf(root, appAddress) {
+    const { path, rest } = split(appAddress);
+    const below = path === '/' ? '' : path;
+    return `${root === '/' ? '' : root}${below}${rest}` || '/';
+}

package/src/apps/tab.d.ts

@@ -0,0 +1,6 @@
+export declare const TAB_IMAGE: RegExp;
+export interface TabChange {
+    readonly title?: string;
+    readonly icon?: string;
+}
+export declare function tabChange(asked: unknown): TabChange | null;

package/src/apps/tab.js

@@ -0,0 +1,27 @@
+const TAB_TITLE_MAX_CHARS = 200;
+const TAB_ICON_MAX_CHARS = 1_048_576;
+function caseless(text) {
+    return text.replace(/[a-z]/gu, (letter) => `[${letter}${letter.toUpperCase()}]`);
+}
+export const TAB_IMAGE = new RegExp(`^${caseless('data:image/')}(?:svg\\+xml|${['png', 'gif', 'webp'].map(caseless).join('|')});${caseless('base64')},[A-Za-z0-9+/]+={0,2}$`, 'u');
+function admittedTitle(title) {
+    return typeof title === 'string' && title.length <= TAB_TITLE_MAX_CHARS;
+}
+function admittedIcon(icon) {
+    return typeof icon === 'string' && icon.length <= TAB_ICON_MAX_CHARS && TAB_IMAGE.test(icon);
+}
+export function tabChange(asked) {
+    if (asked === null || typeof asked !== 'object')
+        return null;
+    const { title, icon } = asked;
+    if (title === undefined && icon === undefined)
+        return null;
+    if (title !== undefined && !admittedTitle(title))
+        return null;
+    if (icon !== undefined && !admittedIcon(icon))
+        return null;
+    return {
+        ...(title === undefined ? {} : { title: title }),
+        ...(icon === undefined ? {} : { icon: icon }),
+    };
+}

package/bridge.d.ts

@@ -1,20 +0,0 @@
-import type { HouseBridgePort, HouseMessagePort, HouseStatus } 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 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>;
-    status(): HouseStatus | null;
-    onStatus(listener: (status: HouseStatus) => void): () => void;
-}
-export declare function connectHouseBridge(source?: Promise<HouseBridgePort>): HouseBridge;

package/bridge.js

@@ -1,134 +0,0 @@
-export class HouseCeremonyRefused extends Error {
-    path;
-    constructor(path) {
-        super('house_ceremony_refused');
-        this.name = 'HouseCeremonyRefused';
-        this.path = path;
-    }
-}
-export class HouseNavigationRefused extends Error {
-    address;
-    constructor(address) {
-        super('house_navigation_refused');
-        this.name = 'HouseNavigationRefused';
-        this.address = address;
-    }
-}
-function settled() {
-    let settle = null;
-    const promise = new Promise((resolve, reject) => {
-        settle = { resolve, reject };
-    });
-    return { promise, settle: settle };
-}
-function heldBridge() {
-    const held = globalThis.houseBridge;
-    if (held === undefined)
-        throw new Error('house_bridge_absent');
-    return held;
-}
-export function connectHouseBridge(source = heldBridge()) {
-    const runtime = settled();
-    const ceremonies = [];
-    const navigations = [];
-    const addressListeners = new Set();
-    const statusListeners = new Set();
-    let outbox = [];
-    let held = null;
-    let address = null;
-    let status = null;
-    function send(message) {
-        if (held === null)
-            outbox?.push(message);
-        else
-            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);
-            return;
-        }
-        if (data.house === 'status') {
-            status = data.status;
-            for (const listener of statusListeners)
-                listener(status);
-            return;
-        }
-        if (data.house === 'address') {
-            address = String(data.address);
-            if (data.navigated === true)
-                navigations.shift()?.settle.resolve(address);
-            for (const listener of addressListeners)
-                listener(address);
-            return;
-        }
-        if (data.house === 'navigate-refused') {
-            const refused = data.address;
-            const named = typeof refused === 'string' ? refused : null;
-            const index = named === null ? 0 : navigations.findIndex((one) => one.address === named);
-            const [pending] = navigations.splice(index < 0 ? 0 : index, 1);
-            pending?.settle.reject(new HouseNavigationRefused(named));
-            return;
-        }
-        if (data.house === 'ceremony-refused') {
-            const refused = data.path;
-            const named = typeof refused === 'string' ? refused : null;
-            const index = named === null ? 0 : ceremonies.findIndex((one) => one.path === named);
-            const [pending] = ceremonies.splice(index < 0 ? 0 : index, 1);
-            pending?.settle.reject(new HouseCeremonyRefused(named));
-        }
-    }
-    void source.then((port) => {
-        held = port;
-        port.addEventListener('message', receive);
-        port.start();
-        const waiting = outbox ?? [];
-        outbox = null;
-        for (const message of waiting)
-            port.postMessage(message);
-    });
-    function navigate(mode, asked) {
-        const pending = settled();
-        navigations.push({ address: asked, settle: pending.settle });
-        send({ house: 'navigate', mode, address: asked });
-        return pending.promise;
-    }
-    return {
-        runtime: runtime.promise,
-        address() {
-            return address;
-        },
-        onAddress(listener) {
-            addressListeners.add(listener);
-            return () => {
-                addressListeners.delete(listener);
-            };
-        },
-        push(asked) {
-            return navigate('push', asked);
-        },
-        replace(asked) {
-            return navigate('replace', asked);
-        },
-        ceremony(path) {
-            const pending = settled();
-            ceremonies.push({ path, settle: pending.settle });
-            send({ house: 'ceremony', path });
-            return pending.promise;
-        },
-        status() {
-            return status;
-        },
-        onStatus(listener) {
-            statusListeners.add(listener);
-            return () => {
-                statusListeners.delete(listener);
-            };
-        },
-    };
-}

package/index.d.ts

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

package/wire.d.ts

@@ -1,30 +0,0 @@
-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 interface HouseStatus {
-    readonly runtime: string;
-    readonly credential: HouseCredentialState;
-    readonly sync: HouseSyncState | null;
-    readonly refusal: {
-        readonly reason: string;
-    } | null;
-    readonly loss: string | null;
-    readonly release: unknown;
-}
-export type HouseNavigationMode = 'push' | 'replace';
-export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;