@agentshouse/app-bridge 0.1.0-c357a960443ec → 0.1.0-c415579fa0c3a

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton (trof3039)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,18 +7,17 @@ installation, notifications, status, Site image reads, App release code,
 external calls, App messages and App and Site screenshot reads.
 [docs/families.md](docs/families.md) describes each and the test host.
 
-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
-message port, which the App hands to the MD Runtime client entry.
+The package carries no credential handling and no Runtime family. House builds
+the MD Runtime client into the page beside the bridge, and `bridge.runtime`
+resolves to that client, so the App imports and constructs none.
 
 ## Use
 
 ```js
 import { connectHouseBridge } from '@agentshouse/app-bridge';
-import { connectMdRuntime } from '@agentshouse/mdruntime/client';
 
 const bridge = connectHouseBridge();
-const md = connectMdRuntime(await bridge.runtime);
+const md = await bridge.runtime;
 
 bridge.onAddress((address) => render(address));
 bridge.onStatus((status) => showSync(status.sync));
@@ -38,9 +37,8 @@ async function manageSecurity(securityPath) {
 }
 ```
 
-`bridge.runtime` resolves with a structural `HouseMessagePort`. A consumer whose
-Runtime client entry asks for the DOM `MessagePort` type passes it through
-directly at run time and casts at the type level.
+`bridge.runtime` resolves to the `MdRuntimeClient` of
+`@agentshouse/mdruntime/client`, whose README describes its members.
 
 ## Test without a House
 
@@ -49,7 +47,7 @@ import { connectHouseBridge } from '@agentshouse/app-bridge';
 import { createHouseBridgeTestHost } from '@agentshouse/app-bridge/test-host';
 
 const host = createHouseBridgeTestHost({ address: '/rooms/atlas' });
-const bridge = connectHouseBridge(host.port);
+const bridge = connectHouseBridge(host);
 
 bridge.push('/rooms/atlas/members');
 host.open('/rooms/atlas');

package/dist/client/src/bridge.d.ts

@@ -1,4 +1,6 @@
-import type { HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseBridgePort, HouseGaChoice, HouseMessagePort, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
+import type { HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseBridgePort, HouseGaChoice, HouseImageCopy, HouseInstallation, HouseNotifications, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+export type { HouseImageCopy } from './wire.js';
 export declare class HouseCeremonyRefused extends Error {
     readonly path: string | null;
     constructor(path: string | null);
@@ -7,16 +9,12 @@ export declare class HouseNavigationRefused extends Error {
     readonly address: string | null;
     constructor(address: string | null);
 }
-export interface HouseImageCopy {
-    readonly attachment: string;
-    readonly copy: string;
-    readonly name: string;
-    readonly media_type: string;
+export interface HouseBridgeSource {
+    readonly port: Promise<HouseBridgePort>;
+    readonly runtime: Promise<MdRuntimeClient>;
 }
-type HouseInstallation = 'accepted' | 'dismissed' | 'manual';
-type HouseNotifications = 'on' | 'off' | 'blocked' | 'unavailable';
 export interface HouseBridge {
-    readonly runtime: Promise<HouseMessagePort>;
+    readonly runtime: Promise<MdRuntimeClient>;
     address(): string | null;
     onAddress(listener: (address: string) => void): () => void;
     push(address: string): Promise<string>;
@@ -37,5 +35,4 @@ export interface HouseBridge {
     messages(listener: (message: HouseAppMessage) => void): () => void;
     gaConsent(choice: HouseGaChoice): void;
 }
-export declare function connectHouseBridge(source?: Promise<HouseBridgePort>): HouseBridge;
-export {};
+export declare function connectHouseBridge(source?: HouseBridgeSource): HouseBridge;

package/dist/client/src/bridge.js

@@ -14,19 +14,45 @@ export class HouseNavigationRefused extends Error {
         this.address = address;
     }
 }
-function answered(pending, answer, value) {
-    if (typeof answer.id !== 'number')
-        return;
+function pendingAnswer(pending, answer) {
     const asked = pending.get(answer.id);
     if (asked === undefined)
-        return;
+        return null;
     pending.delete(answer.id);
-    if (answer.refused === true)
+    if (answer.refused === true) {
         asked.reject(new HouseCeremonyRefused(null));
-    else if (answer.refusal !== undefined)
+        return null;
+    }
+    if (answer.refusal !== undefined) {
         asked.reject(new DOMException(answer.refusal.message, answer.refusal.name));
-    else
-        asked.resolve(value);
+        return null;
+    }
+    return asked;
+}
+const FRAME_HOUSES = [
+    'runtime',
+    'status',
+    'screenshot',
+    'address',
+    'ceremony-refused',
+    'navigate-refused',
+    'attachment',
+    'source',
+    'external-call',
+    'install',
+    'notifications',
+    'badge',
+    'app-message',
+];
+function frameMessage(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    const message = value;
+    if (typeof message.house !== 'string')
+        return null;
+    if (!FRAME_HOUSES.includes(message.house))
+        return null;
+    return value;
 }
 function settled() {
     let settle = null;
@@ -36,13 +62,12 @@ function settled() {
     return { promise, settle: settle };
 }
 function heldBridge() {
-    const held = globalThis.houseBridge;
-    if (held === undefined)
+    const held = globalThis;
+    if (held.houseBridge === undefined || held.houseRuntime === undefined)
         throw new Error('house_bridge_absent');
-    return held;
+    return { port: held.houseBridge, runtime: held.houseRuntime };
 }
 export function connectHouseBridge(source = heldBridge()) {
-    const runtime = settled();
     const ceremonies = [];
     const navigations = [];
     const attachments = new Map();
@@ -73,15 +98,9 @@ export function connectHouseBridge(source = heldBridge()) {
             held.postMessage(message);
     }
     function receive(event) {
-        const data = event.data;
-        if (data === null || typeof data !== 'object')
+        const data = frameMessage(event.data);
+        if (data === null)
             return;
-        if (data.house === 'runtime') {
-            const [port] = event.ports;
-            if (port !== undefined)
-                runtime.settle.resolve(port);
-            return;
-        }
         if (data.house === 'status') {
             status = data.status;
             for (const listener of statusListeners)
@@ -111,61 +130,59 @@ export function connectHouseBridge(source = heldBridge()) {
             return;
         }
         if (data.house === 'attachment') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = attachments.get(answer.id);
+            const pending = attachments.get(data.id);
             if (pending === undefined)
                 return;
-            attachments.delete(answer.id);
-            pending.resolve(answer.image ?? null);
+            attachments.delete(data.id);
+            pending.resolve(data.image ?? null);
             return;
         }
         if (data.house === 'install') {
-            const answer = data;
-            answered(installations, answer, answer.outcome);
+            const pending = pendingAnswer(installations, data);
+            if (pending !== null && 'outcome' in data)
+                pending.resolve(data.outcome);
             return;
         }
         if (data.house === 'notifications') {
-            const answer = data;
-            answered(notifications, answer, answer.state);
+            const pending = pendingAnswer(notifications, data);
+            if (pending !== null && 'state' in data)
+                pending.resolve(data.state);
             return;
         }
         if (data.house === 'badge') {
-            answered(badges, data, undefined);
+            pendingAnswer(badges, data)?.resolve();
             return;
         }
         if (data.house === 'source') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = sources.get(answer.id);
+            const pending = sources.get(data.id);
             if (pending === undefined)
                 return;
-            sources.delete(answer.id);
-            pending.resolve(answer.answer ?? null);
+            sources.delete(data.id);
+            pending.resolve(data.answer ?? null);
             return;
         }
         if (data.house === 'external-call') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = externals.get(answer.id);
+            const pending = externals.get(data.id);
             if (pending === undefined)
                 return;
-            externals.delete(answer.id);
-            pending.resolve(answer.answer ?? null);
+            externals.delete(data.id);
+            pending.resolve(data.answer ?? null);
             return;
         }
         if (data.house === 'screenshot') {
-            const answer = data;
-            if (typeof answer.id !== 'number')
+            if (typeof data.id !== 'number')
                 return;
-            const pending = screenshots.get(answer.id);
+            const pending = screenshots.get(data.id);
             if (pending === undefined)
                 return;
-            screenshots.delete(answer.id);
-            pending.resolve(answer.image ?? null);
+            screenshots.delete(data.id);
+            pending.resolve(data.image ?? null);
             return;
         }
         if (data.house === 'ceremony-refused') {
@@ -176,7 +193,7 @@ export function connectHouseBridge(source = heldBridge()) {
             pending?.settle.reject(new HouseCeremonyRefused(named));
         }
     }
-    void source.then((port) => {
+    void source.port.then((port) => {
         held = port;
         port.addEventListener('message', receive);
         port.start();
@@ -196,7 +213,10 @@ export function connectHouseBridge(source = heldBridge()) {
         const pending = settled();
         const id = ++nextScreenshot;
         screenshots.set(id, pending.settle);
-        send({ house, id, ...asked });
+        if (house === 'screenshot-read' && 'app' in asked)
+            send({ house, id, app: asked.app });
+        if (house === 'site-screenshot-read' && 'site' in asked)
+            send({ house, id, site: asked.site });
         return pending.promise;
     }
     function navigate(mode, asked) {
@@ -206,7 +226,7 @@ export function connectHouseBridge(source = heldBridge()) {
         return pending.promise;
     }
     return {
-        runtime: runtime.promise,
+        runtime: source.runtime,
         address() {
             return address;
         },

package/dist/client/src/index.d.ts

@@ -1,3 +1,3 @@
-export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, type HouseImageCopy, } from './bridge.js';
+export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, type HouseBridgeSource, type HouseImageCopy, } from './bridge.js';
 export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
-export type { HouseAppMessage, HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseExternalAnswer, HouseExternalRequest, HouseGa, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceFile, HouseSourceTop, HouseStatus, HouseSyncState, } from './wire.js';
+export type { HouseAppMessage, HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseExternalAnswer, HouseExternalRequest, HouseGa, HouseGaChoice, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceFile, HouseSourceTop, HouseStatus, HouseSyncState, } from './wire.js';

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

@@ -1,11 +1,11 @@
-import type { HouseImageCopy } from './bridge.js';
-import type { HouseAppMessage, HouseBridgePort, HouseExternalAnswer, HouseExternalRequest, HouseGaChoice, HouseMessagePort, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
+import type { MdRuntimeClient } from '@agentshouse/mdruntime/client';
+import type { HouseBridgeSource, HouseImageCopy } from './bridge.js';
+import type { HouseAppMessage, HouseExternalAnswer, HouseExternalRequest, HouseGaChoice, HouseNavigationMode, HouseRefusal, HouseSourceDownload, HouseSourceTop, HouseStatus, HouseTab } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
     readonly address: string;
 }
-export interface HouseBridgeTestHost {
-    readonly port: Promise<HouseBridgePort>;
+export interface HouseBridgeTestHost extends HouseBridgeSource {
     readonly navigations: readonly HouseBridgeNavigation[];
     readonly ceremonies: readonly string[];
     readonly consents: readonly HouseGaChoice[];
@@ -15,7 +15,7 @@ export interface HouseBridgeTestHost {
     open(address: string): void;
     publish(status: HouseStatus): void;
     message(message: HouseAppMessage): void;
-    attachRuntime(runtime: HouseMessagePort): void;
+    attachRuntime(runtime: MdRuntimeClient): void;
 }
 export interface HouseBridgeTestHostOptions {
     readonly address?: string;

package/dist/client/src/test-host.js

@@ -23,8 +23,12 @@ export function createHouseBridgeTestHost(options = {}) {
     let started = false;
     let address = appAddressOf('/', options.address ?? '/');
     let status = options.status ?? null;
-    function deliver(data, ports = []) {
-        const event = { data, ports };
+    let attached = () => { };
+    const runtime = new Promise((resolve) => {
+        attached = resolve;
+    });
+    function deliver(data) {
+        const event = { data };
         if (!started) {
             queued.push(event);
             return;
@@ -158,6 +162,7 @@ export function createHouseBridgeTestHost(options = {}) {
     deliver({ house: 'address', address, navigated: false });
     return {
         port: Promise.resolve(port),
+        runtime,
         navigations,
         ceremonies,
         consents,
@@ -173,8 +178,8 @@ export function createHouseBridgeTestHost(options = {}) {
         message(message) {
             deliver({ house: 'app-message', from: message.from, body: message.body });
         },
-        attachRuntime(runtime) {
-            deliver({ house: 'runtime' }, [runtime]);
+        attachRuntime(client) {
+            attached(client);
         },
     };
 }

package/dist/client/src/wire.d.ts

@@ -1,14 +1,12 @@
 import type { TabChange } from '../../src/apps/tab.js';
 export interface HouseBridgeEvent {
     readonly data: unknown;
-    readonly ports: readonly HouseMessagePort[];
 }
-export interface HouseMessagePort {
-    postMessage(message: unknown): void;
+export interface HouseBridgePort {
+    postMessage(message: HouseFrameRequest): void;
     addEventListener(type: 'message', listener: (event: HouseBridgeEvent) => void): void;
     start(): void;
 }
-export type HouseBridgePort = HouseMessagePort;
 export interface HouseSyncState {
     readonly state: string;
     readonly providerUnreachable: boolean;
@@ -23,7 +21,11 @@ export interface HouseGa {
     readonly choice: HouseGaChoice | null;
 }
 export interface HouseStatus {
-    readonly app: string;
+    readonly app: string | null;
+    readonly preferences: {
+        readonly room_ref: string;
+        readonly path: string;
+    } | null;
     readonly runtime: string;
     readonly credential: HouseCredentialState;
     readonly sync: HouseSyncState | null;
@@ -33,6 +35,7 @@ export interface HouseStatus {
     readonly loss: string | null;
     readonly ga: HouseGa;
     readonly service_mode: 'open' | 'write-halted' | null;
+    readonly offline: boolean;
 }
 export type HouseNavigationMode = 'push' | 'replace';
 interface HouseRelease {
@@ -85,5 +88,128 @@ export interface HouseAppMessage {
     readonly from: string;
     readonly body: unknown;
 }
+export type HouseInstallation = 'accepted' | 'dismissed' | 'manual';
+export type HouseNotifications = 'on' | 'off' | 'blocked' | 'unavailable';
+export interface HouseImageCopy {
+    readonly attachment: string;
+    readonly copy: string;
+    readonly name: string;
+    readonly media_type: string;
+}
+export interface HouseFrameRefusal {
+    readonly name: string;
+    readonly message: string;
+}
+export type HouseFrameRequest = {
+    readonly house: 'navigate';
+    readonly mode: HouseNavigationMode;
+    readonly address: string;
+} | ({
+    readonly house: 'tab';
+} & HouseTab) | {
+    readonly house: 'ceremony';
+    readonly path: string;
+} | {
+    readonly house: 'install';
+    readonly id: number;
+} | {
+    readonly house: 'notifications';
+    readonly id: number;
+    readonly on?: boolean;
+} | {
+    readonly house: 'badge';
+    readonly id: number;
+    readonly unread: readonly string[];
+} | {
+    readonly house: 'attachment-read';
+    readonly id: number;
+    readonly room: string;
+    readonly attachment: string;
+} | {
+    readonly house: 'source-top' | 'source-download';
+    readonly id: number;
+    readonly app: string;
+    readonly release?: string;
+} | {
+    readonly house: 'external-call';
+    readonly id: number;
+    readonly request: HouseExternalRequest;
+} | {
+    readonly house: 'screenshot-read';
+    readonly id: number;
+    readonly app: string;
+} | {
+    readonly house: 'site-screenshot-read';
+    readonly id: number;
+    readonly site: string;
+} | {
+    readonly house: 'ga/consent';
+    readonly choice: HouseGaChoice;
+};
+export type HouseInstallAnswer = {
+    readonly outcome: HouseInstallation;
+} | {
+    readonly refusal: HouseFrameRefusal;
+};
+export type HouseNotificationAnswer = {
+    readonly refused: true;
+} | {
+    readonly refusal: HouseFrameRefusal;
+} | {
+    readonly state: HouseNotifications;
+};
+export type HouseBadgeAnswer = {
+    readonly refused: true;
+} | {
+    readonly refusal: HouseFrameRefusal;
+} | {
+    readonly refused?: never;
+    readonly refusal?: never;
+};
+export type HouseFrameMessage = {
+    readonly house: 'runtime';
+} | {
+    readonly house: 'status';
+    readonly status: HouseStatus;
+} | {
+    readonly house: 'screenshot';
+    readonly id: number;
+    readonly image: Blob | null;
+} | {
+    readonly house: 'address';
+    readonly address: string;
+    readonly navigated: boolean;
+} | {
+    readonly house: 'ceremony-refused';
+    readonly path: string | null;
+} | {
+    readonly house: 'navigate-refused';
+    readonly address: string | null;
+} | {
+    readonly house: 'attachment';
+    readonly id: number;
+    readonly image: HouseImageCopy | null;
+} | {
+    readonly house: 'source';
+    readonly id: number;
+    readonly answer: HouseSourceTop | HouseSourceDownload | HouseRefusal | null;
+} | {
+    readonly house: 'external-call';
+    readonly id: number;
+    readonly answer: HouseExternalAnswer | HouseRefusal | null;
+} | ({
+    readonly house: 'install';
+    readonly id: number;
+} & HouseInstallAnswer) | ({
+    readonly house: 'notifications';
+    readonly id: number;
+} & HouseNotificationAnswer) | ({
+    readonly house: 'badge';
+    readonly id: number;
+} & HouseBadgeAnswer) | {
+    readonly house: 'app-message';
+    readonly from: string;
+    readonly body: unknown;
+};
 export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;
 export {};

package/dist/src/apps/remainder.js

@@ -12,5 +12,5 @@ export function appAddressOf(root, address) {
 export function shellAddressOf(root, appAddress) {
     const { path, rest } = split(appAddress);
     const below = path === '/' ? '' : path;
-    return `${root === '/' ? '' : root}${below}${rest}` || '/';
+    return `${`${root === '/' ? '' : root}${below}` || '/'}${rest}`;
 }

package/docs/families.md

@@ -32,7 +32,9 @@
   click. `setBadge(unread)` takes the identifiers of the Human Notifications
   unread in this storage and sets the icon's badge to their number, or clears
   it at none, where the browser shows one.
-- **Status** - the App reference the Runtime port is attached under, sync
+- **Status** - the App reference the runtime client is attached under,
+  `preferences`: the `room_ref` and Path of the App's own preferences document,
+  or `null` until the runtime holds that Room, sync
   state, credential state 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
@@ -100,4 +102,5 @@ reference and `readSiteScreenshot` from the `siteScreenshots` it was given by
 Site identifier, 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`, delivers each App message
-`message({ from, body })` plays, and attaches a Runtime port.
+`message({ from, body })` plays, and hands `bridge.runtime` the MD Runtime
+client `attachRuntime(client)` gives it.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-c357a960443ec",
+  "version": "0.1.0-c415579fa0c3a",
   "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, App and Site screenshot reads, and App messages, with an in-page test host.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "engines": {
@@ -18,9 +18,13 @@
       "default": "./dist/client/src/test-host.js"
     }
   },
+  "dependencies": {
+    "@agentshouse/mdruntime": "0.1.0-c6e4c19c13638"
+  },
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ]
 }