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

package/README.md

@@ -6,15 +6,23 @@ port's one listener. It carries four 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
   returns there when it completes. An App names an address House gave it in a
   reading and composes none.
 - **Status** - the App reference the Runtime port is attached under, sync
-  state, credential state, release availability and observed failure, and
-  `ga`: whether the page measures and the visitor's stored analytics choice.
+  state, credential state, release availability and observed failure, `ga`:
+  whether the page measures and the visitor's stored analytics choice, and
+  `service_mode`: `open`, `write-halted` while House refuses writes, so the
+  App can stop retrying them, or `null` while the runtime holds no House
+  connection.
   The App reports the visitor's choice with `gaConsent('accept')` or
   `gaConsent('decline')`; the shell hands it to House's analytics loader, and
   the choice never reaches House.
@@ -37,6 +45,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) {
@@ -75,6 +84,8 @@ slice below the App's path, admitting nothing, so it delivers `//notes` exactly
 as a browser at `/apps/<app>//notes` does. It records every push and replace
 and answers each with the address the shell would then show, records an
 admitted ceremony, refuses a push, replace or ceremony that is not a
-same-origin absolute path, publishes a status, records in `consents` each
+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, 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, HouseStatus, HouseTab } from './wire.js';
 export declare class HouseCeremonyRefused extends Error {
     readonly path: string | null;
     constructor(path: string | null);
@@ -20,6 +20,7 @@ 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>;
     status(): HouseStatus | null;
     onStatus(listener: (status: HouseStatus) => void): () => void;

package/client/src/bridge.js

@@ -134,6 +134,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;

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, 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;

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,6 +79,11 @@ 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);
         }
@@ -123,6 +130,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[];
@@ -32,6 +33,8 @@ export interface HouseStatus {
     readonly loss: string | null;
     readonly release: unknown;
     readonly ga: HouseGa;
+    readonly service_mode: 'open' | 'write-halted' | null;
 }
 export type HouseNavigationMode = 'push' | 'replace';
+export type HouseTab = TabChange;
 export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-alpha.4",
-  "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.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.",
   "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 }),
+    };
+}