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

package/README.md

@@ -2,7 +2,7 @@
 
 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 eight families:
+port's one listener. It carries nine 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
@@ -58,11 +58,22 @@ port's one listener. It carries eight families:
   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 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 package carries no credential handling and no Runtime family. It surfaces
 the dedicated Runtime port the worker transfers over the bridge as a plain
@@ -124,6 +135,8 @@ records in `consents` each
 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
+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`, and attaches a Runtime port.
+without push does, settles every `setBadge`, delivers each App message
+`message({ from, body })` plays, and attaches a Runtime port.

package/client/src/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseSourceDownload, HouseSourceRefusal, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+import type { HouseAppMessage, 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);
@@ -30,8 +30,10 @@ export interface HouseBridge {
     sourceTop(app: string, release?: string): Promise<HouseSourceTop | HouseSourceRefusal | null>;
     sourceDownload(app: string, release?: string): Promise<HouseSourceDownload | HouseSourceRefusal | 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?: Promise<HouseBridgePort>): HouseBridge;

package/client/src/bridge.js

@@ -59,6 +59,7 @@ export function connectHouseBridge(source = heldBridge()) {
     let nextScreenshot = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
+    const messageListeners = new Set();
     let outbox = [];
     let held = null;
     let address = null;
@@ -85,6 +86,12 @@ export function connectHouseBridge(source = heldBridge()) {
                 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)
@@ -172,6 +179,13 @@ 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);
+        send({ house, id, ...asked });
+        return pending.promise;
+    }
     function navigate(mode, asked) {
         const pending = settled();
         navigations.push({ address: asked, settle: pending.settle });
@@ -239,11 +253,10 @@ export function connectHouseBridge(source = heldBridge()) {
             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;
+            return screenshot('screenshot-read', { app });
+        },
+        readSiteScreenshot(site) {
+            return screenshot('site-screenshot-read', { site });
         },
         status() {
             return status;
@@ -254,6 +267,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/client/src/index.d.ts

@@ -1,3 +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';
+export type { HouseAppMessage, HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseGa, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceFile, HouseSourceRefusal, HouseSourceTop, HouseStatus, HouseSyncState, } from './wire.js';

package/client/src/test-host.d.ts

@@ -1,5 +1,5 @@
 import type { HouseImageCopy } from './bridge.js';
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+import type { HouseAppMessage, HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
@@ -13,6 +13,7 @@ export interface HouseBridgeTestHost {
     address(): string;
     open(address: string): void;
     publish(status: HouseStatus): void;
+    message(message: HouseAppMessage): void;
     attachRuntime(runtime: HouseMessagePort): void;
 }
 export interface HouseBridgeTestHostOptions {
@@ -26,5 +27,6 @@ export interface HouseBridgeTestHostOptions {
         readonly download: HouseSourceDownload;
     }[];
     readonly screenshots?: Readonly<Record<string, Blob>>;
+    readonly siteScreenshots?: Readonly<Record<string, Blob>>;
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

package/client/src/test-host.js

@@ -123,6 +123,11 @@ export function createHouseBridgeTestHost(options = {}) {
             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) {
@@ -158,6 +163,9 @@ export function createHouseBridgeTestHost(options = {}) {
             arrive(appAddressOf('/', asked), false);
         },
         publish,
+        message(message) {
+            deliver({ house: 'app-message', from: message.from, body: message.body });
+        },
         attachRuntime(runtime) {
             deliver({ house: 'runtime' }, [runtime]);
         },

package/client/src/wire.d.ts

@@ -65,5 +65,9 @@ export interface HouseSourceRefusal {
     };
 }
 export type HouseTab = TabChange;
+export interface HouseAppMessage {
+    readonly from: string;
+    readonly body: unknown;
+}
 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.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.",
+  "version": "0.1.0-alpha.12",
+  "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": "UNLICENSED",
   "type": "module",
   "sideEffects": false,