@agentshouse/app-bridge 0.1.0-alpha.7 → 0.1.0-alpha.9

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 five families:
+port's one listener. It carries six 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
@@ -17,6 +17,14 @@ port's one listener. It carries five families:
   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.
 - **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
@@ -39,6 +47,11 @@ port's one listener. It carries five 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 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
@@ -99,4 +112,6 @@ 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`, and attaches a Runtime port.
+`null`, answers `readScreenshot` from the `screenshots` it was given by App
+reference, answers every `install()` `'manual'`, as a browser with no install
+prompt does, and attaches a Runtime port.

package/client/src/bridge.d.ts

@@ -13,6 +13,7 @@ export interface HouseImageCopy {
     readonly name: string;
     readonly media_type: string;
 }
+type HouseInstallation = 'accepted' | 'dismissed' | 'manual';
 export interface HouseBridge {
     readonly runtime: Promise<HouseMessagePort>;
     address(): string | null;
@@ -20,12 +21,15 @@ export interface HouseBridge {
     push(address: string): Promise<string>;
     replace(address: string): Promise<string>;
     ceremony(path: string): Promise<never>;
+    install(): Promise<HouseInstallation>;
     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

@@ -35,6 +35,10 @@ export function connectHouseBridge(source = heldBridge()) {
     let nextAttachment = 0;
     const sources = new Map();
     let nextSource = 0;
+    const installations = new Map();
+    let nextInstallation = 0;
+    const screenshots = new Map();
+    let nextScreenshot = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
     let outbox = [];
@@ -90,6 +94,20 @@ export function connectHouseBridge(source = heldBridge()) {
             pending.resolve(answer.image ?? null);
             return;
         }
+        if (data.house === 'install') {
+            const answer = data;
+            if (typeof answer.id !== 'number')
+                return;
+            const pending = installations.get(answer.id);
+            if (pending === undefined)
+                return;
+            installations.delete(answer.id);
+            if (answer.outcome !== undefined)
+                pending.resolve(answer.outcome);
+            else
+                pending.reject(new DOMException(answer.refusal?.message, answer.refusal?.name));
+            return;
+        }
         if (data.house === 'source') {
             const answer = data;
             if (typeof answer.id !== 'number')
@@ -101,6 +119,17 @@ export function connectHouseBridge(source = heldBridge()) {
             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;
@@ -154,6 +183,13 @@ 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;
+        },
         setTab(tab) {
             send({ house: 'tab', title: tab.title, icon: tab.icon });
         },
@@ -170,6 +206,13 @@ export function connectHouseBridge(source = heldBridge()) {
         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;
         },

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

@@ -25,5 +25,6 @@ export interface HouseBridgeTestHostOptions {
         readonly top: HouseSourceTop;
         readonly download: HouseSourceDownload;
     }[];
+    readonly screenshots?: Readonly<Record<string, Blob>>;
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

package/client/src/test-host.js

@@ -79,6 +79,9 @@ 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 === 'tab') {
             const change = tabChange(data);
             if (change !== null)
@@ -109,6 +112,11 @@ export function createHouseBridgeTestHost(options = {}) {
                     },
             });
         }
+        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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-alpha.7",
-  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, status, Site image reads and App release code, with an in-page test host.",
+  "version": "0.1.0-alpha.9",
+  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, installation, status, Site image reads, App release code and App screenshot reads, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,