@agentshouse/app-bridge 0.1.0-alpha.6 → 0.1.0-alpha.8

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 four 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
@@ -29,6 +29,21 @@ port's one listener. It carries four families:
 - **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
@@ -88,4 +103,6 @@ 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, and attaches a Runtime port.
+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, and attaches a Runtime port.

package/client/src/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseStatus, HouseTab } from './wire.js';
+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);
@@ -22,6 +22,9 @@ export interface HouseBridge {
     ceremony(path: string): Promise<never>;
     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;

package/client/src/bridge.js

@@ -33,6 +33,10 @@ export function connectHouseBridge(source = heldBridge()) {
     const navigations = [];
     const attachments = new Map();
     let nextAttachment = 0;
+    const sources = new Map();
+    let nextSource = 0;
+    const screenshots = new Map();
+    let nextScreenshot = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
     let outbox = [];
@@ -88,6 +92,28 @@ export function connectHouseBridge(source = heldBridge()) {
             pending.resolve(answer.image ?? null);
             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;
@@ -105,6 +131,13 @@ export function connectHouseBridge(source = heldBridge()) {
         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 });
@@ -144,6 +177,19 @@ export function connectHouseBridge(source = heldBridge()) {
             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;
         },

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, HouseStatus, HouseSyncState, } from './wire.js';
+export type { 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, HouseStatus, HouseTab } from './wire.js';
+import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
@@ -21,5 +21,10 @@ export interface HouseBridgeTestHostOptions {
     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/client/src/test-host.js

@@ -87,6 +87,12 @@ export function createHouseBridgeTestHost(options = {}) {
         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);
@@ -103,6 +109,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/client/src/wire.d.ts

@@ -36,5 +36,34 @@ export interface HouseStatus {
     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.6",
-  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, status and Site image reads, with an in-page test host.",
+  "version": "0.1.0-alpha.8",
+  "description": "Renderer-side client of the agents.house App bridge: navigation, the tab title and icon, ceremonies, status, Site image reads, App release code and App screenshot reads, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,