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

package/README.md

@@ -2,11 +2,16 @@
 
 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 five 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
@@ -24,6 +29,16 @@ 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`.
 
 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
@@ -40,6 +55,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) {
@@ -81,4 +97,6 @@ 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, and attaches a Runtime port.
+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.

package/client/src/bridge.d.ts

@@ -1,4 +1,4 @@
-import type { HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseStatus } 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);
@@ -20,7 +20,10 @@ export interface HouseBridge {
     push(address: string): Promise<string>;
     replace(address: string): Promise<string>;
     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>;
     status(): HouseStatus | null;
     onStatus(listener: (status: HouseStatus) => void): () => void;
     gaConsent(choice: HouseGaChoice): void;

package/client/src/bridge.js

@@ -33,6 +33,8 @@ export function connectHouseBridge(source = heldBridge()) {
     const navigations = [];
     const attachments = new Map();
     let nextAttachment = 0;
+    const sources = new Map();
+    let nextSource = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
     let outbox = [];
@@ -88,6 +90,17 @@ 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 === 'ceremony-refused') {
             const refused = data.path;
             const named = typeof refused === 'string' ? refused : null;
@@ -105,6 +118,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 });
@@ -134,6 +154,9 @@ export function connectHouseBridge(source = heldBridge()) {
             send({ house: 'ceremony', path });
             return pending.promise;
         },
+        setTab(tab) {
+            send({ house: 'tab', title: tab.title, icon: tab.icon });
+        },
         readAttachment(room, attachment) {
             const pending = settled();
             const id = ++nextAttachment;
@@ -141,6 +164,12 @@ 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);
+        },
         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 } 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;
@@ -9,6 +9,7 @@ export interface HouseBridgeTestHost {
     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;
@@ -20,5 +21,9 @@ export interface HouseBridgeTestHostOptions {
     readonly images?: readonly (HouseImageCopy & {
         readonly room: string;
     })[];
+    readonly sources?: readonly {
+        readonly top: HouseSourceTop;
+        readonly download: HouseSourceDownload;
+    }[];
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

package/client/src/test-host.js

@@ -1,4 +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) {
@@ -15,6 +16,7 @@ export function createHouseBridgeTestHost(options = {}) {
     const navigations = [];
     const ceremonies = [];
     const consents = [];
+    const tabs = [];
     const listeners = new Set();
     const queued = [];
     let started = false;
@@ -77,9 +79,20 @@ export function createHouseBridgeTestHost(options = {}) {
         else if (data.house === 'ceremony') {
             ceremony(data.path);
         }
+        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);
@@ -123,6 +136,7 @@ export function createHouseBridgeTestHost(options = {}) {
         navigations,
         ceremonies,
         consents,
+        tabs,
         address() {
             return address;
         },

package/client/src/wire.d.ts

@@ -1,3 +1,4 @@
+import type { TabChange } from '../../src/apps/tab.js';
 export interface HouseBridgeEvent {
     readonly data: unknown;
     readonly ports: readonly HouseMessagePort[];
@@ -35,4 +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.5",
-  "description": "Renderer-side client of the agents.house App bridge: navigation, ceremonies, status and Site image reads, with an in-page test host.",
+  "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.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -23,6 +23,8 @@
     "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/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 }),
+    };
+}