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

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,6 +58,13 @@ 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
@@ -126,4 +133,5 @@ 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.
+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);
@@ -32,6 +32,7 @@ export interface HouseBridge {
     readScreenshot(app: 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)
@@ -254,6 +261,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 {

package/client/src/test-host.js

@@ -158,6 +158,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.11",
+  "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, and App messages, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,