@agentshouse/app-bridge 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,68 @@
+# @agentshouse/app-bridge
+
+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 three 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.
+- **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** - sync state, credential state, release availability and observed
+  failure.
+
+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.
+
+## Use
+
+```js
+import { connectHouseBridge } from '@agentshouse/app-bridge';
+import { connectMdRuntime } from '@agentshouse/mdruntime/client';
+
+const bridge = connectHouseBridge();
+const md = connectMdRuntime(await bridge.runtime);
+
+bridge.onAddress((address) => render(address));
+bridge.onStatus((status) => showSync(status.sync));
+
+open('/rooms/atlas');
+function open(address) {
+  bridge.push(address);
+}
+
+async function manageSecurity(securityPath) {
+  try {
+    await bridge.ceremony(securityPath);
+  } catch (refusal) {
+    report(refusal);
+  }
+}
+```
+
+`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.
+
+## Test without a House
+
+```js
+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);
+
+bridge.push('/rooms/atlas/members');
+host.open('/rooms/atlas');
+```
+
+The host plays the shell and the worker: it delivers the address the App starts
+at, records every push and replace and answers each with the address the shell
+would then show, records an admitted ceremony, refuses one that is not a
+same-origin absolute path, publishes a status, and attaches a Runtime port.

package/bridge.d.ts

@@ -0,0 +1,20 @@
+import type { HouseBridgePort, HouseMessagePort, HouseStatus } from './wire.js';
+export declare class HouseCeremonyRefused extends Error {
+    readonly path: string | null;
+    constructor(path: string | null);
+}
+export declare class HouseNavigationRefused extends Error {
+    readonly address: string | null;
+    constructor(address: string | null);
+}
+export interface HouseBridge {
+    readonly runtime: Promise<HouseMessagePort>;
+    address(): string | null;
+    onAddress(listener: (address: string) => void): () => void;
+    push(address: string): Promise<string>;
+    replace(address: string): Promise<string>;
+    ceremony(path: string): Promise<never>;
+    status(): HouseStatus | null;
+    onStatus(listener: (status: HouseStatus) => void): () => void;
+}
+export declare function connectHouseBridge(source?: Promise<HouseBridgePort>): HouseBridge;

package/bridge.js

@@ -0,0 +1,134 @@
+export class HouseCeremonyRefused extends Error {
+    path;
+    constructor(path) {
+        super('house_ceremony_refused');
+        this.name = 'HouseCeremonyRefused';
+        this.path = path;
+    }
+}
+export class HouseNavigationRefused extends Error {
+    address;
+    constructor(address) {
+        super('house_navigation_refused');
+        this.name = 'HouseNavigationRefused';
+        this.address = address;
+    }
+}
+function settled() {
+    let settle = null;
+    const promise = new Promise((resolve, reject) => {
+        settle = { resolve, reject };
+    });
+    return { promise, settle: settle };
+}
+function heldBridge() {
+    const held = globalThis.houseBridge;
+    if (held === undefined)
+        throw new Error('house_bridge_absent');
+    return held;
+}
+export function connectHouseBridge(source = heldBridge()) {
+    const runtime = settled();
+    const ceremonies = [];
+    const navigations = [];
+    const addressListeners = new Set();
+    const statusListeners = new Set();
+    let outbox = [];
+    let held = null;
+    let address = null;
+    let status = null;
+    function send(message) {
+        if (held === null)
+            outbox?.push(message);
+        else
+            held.postMessage(message);
+    }
+    function receive(event) {
+        const data = event.data;
+        if (data === null || typeof data !== 'object')
+            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)
+                listener(status);
+            return;
+        }
+        if (data.house === 'address') {
+            address = String(data.address);
+            if (data.navigated === true)
+                navigations.shift()?.settle.resolve(address);
+            for (const listener of addressListeners)
+                listener(address);
+            return;
+        }
+        if (data.house === 'navigate-refused') {
+            const refused = data.address;
+            const named = typeof refused === 'string' ? refused : null;
+            const index = named === null ? 0 : navigations.findIndex((one) => one.address === named);
+            const [pending] = navigations.splice(index < 0 ? 0 : index, 1);
+            pending?.settle.reject(new HouseNavigationRefused(named));
+            return;
+        }
+        if (data.house === 'ceremony-refused') {
+            const refused = data.path;
+            const named = typeof refused === 'string' ? refused : null;
+            const index = named === null ? 0 : ceremonies.findIndex((one) => one.path === named);
+            const [pending] = ceremonies.splice(index < 0 ? 0 : index, 1);
+            pending?.settle.reject(new HouseCeremonyRefused(named));
+        }
+    }
+    void source.then((port) => {
+        held = port;
+        port.addEventListener('message', receive);
+        port.start();
+        const waiting = outbox ?? [];
+        outbox = null;
+        for (const message of waiting)
+            port.postMessage(message);
+    });
+    function navigate(mode, asked) {
+        const pending = settled();
+        navigations.push({ address: asked, settle: pending.settle });
+        send({ house: 'navigate', mode, address: asked });
+        return pending.promise;
+    }
+    return {
+        runtime: runtime.promise,
+        address() {
+            return address;
+        },
+        onAddress(listener) {
+            addressListeners.add(listener);
+            return () => {
+                addressListeners.delete(listener);
+            };
+        },
+        push(asked) {
+            return navigate('push', asked);
+        },
+        replace(asked) {
+            return navigate('replace', asked);
+        },
+        ceremony(path) {
+            const pending = settled();
+            ceremonies.push({ path, settle: pending.settle });
+            send({ house: 'ceremony', path });
+            return pending.promise;
+        },
+        status() {
+            return status;
+        },
+        onStatus(listener) {
+            statusListeners.add(listener);
+            return () => {
+                statusListeners.delete(listener);
+            };
+        },
+    };
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, type HouseBridge, } from './bridge.js';
+export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
+export type { HouseBridgeEvent, HouseBridgePort, HouseCredentialState, HouseMessagePort, HouseNavigationMode, HouseStatus, HouseSyncState, } from './wire.js';

package/index.js

@@ -0,0 +1,2 @@
+export { connectHouseBridge, HouseCeremonyRefused, HouseNavigationRefused, } from './bridge.js';
+export { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@agentshouse/app-bridge",
+  "version": "0.1.0-alpha.1",
+  "description": "Renderer-side client of the agents.house App bridge: navigation, ceremonies and status, with an in-page test host.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./test-host": {
+      "types": "./test-host.d.ts",
+      "default": "./test-host.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md"
+  ]
+}

package/test-host.d.ts

@@ -0,0 +1,19 @@
+import type { HouseBridgePort, HouseMessagePort, HouseNavigationMode, HouseStatus } from './wire.js';
+export interface HouseBridgeNavigation {
+    readonly mode: HouseNavigationMode;
+    readonly address: string;
+}
+export interface HouseBridgeTestHost {
+    readonly port: Promise<HouseBridgePort>;
+    readonly navigations: readonly HouseBridgeNavigation[];
+    readonly ceremonies: readonly string[];
+    address(): string;
+    open(address: string): void;
+    publish(status: HouseStatus): void;
+    attachRuntime(runtime: HouseMessagePort): void;
+}
+export interface HouseBridgeTestHostOptions {
+    readonly address?: string;
+    readonly status?: HouseStatus;
+}
+export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

package/test-host.js

@@ -0,0 +1,106 @@
+import { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
+const HOST_ORIGIN = 'https://house.invalid';
+function sameOriginPath(value) {
+    if (typeof value !== 'string')
+        return null;
+    if (value.charAt(0) !== '/' || value.slice(0, 2) === '//')
+        return null;
+    if (value.length > HOUSE_ADDRESS_MAX_CHARS)
+        return null;
+    const target = new URL(value, HOST_ORIGIN);
+    return target.origin === HOST_ORIGIN ? `${target.pathname}${target.search}${target.hash}` : null;
+}
+export function createHouseBridgeTestHost(options = {}) {
+    const navigations = [];
+    const ceremonies = [];
+    const listeners = new Set();
+    const queued = [];
+    let started = false;
+    let address = sameOriginPath(options.address ?? '/') ?? '/';
+    function deliver(data, ports = []) {
+        const event = { data, ports };
+        if (!started) {
+            queued.push(event);
+            return;
+        }
+        queueMicrotask(() => {
+            for (const listener of listeners)
+                listener(event);
+        });
+    }
+    function arrive(target, navigated) {
+        address = target;
+        deliver({ house: 'address', address, navigated });
+    }
+    function navigate(mode, asked) {
+        const target = sameOriginPath(asked);
+        if (target === null) {
+            deliver({
+                house: 'navigate-refused',
+                address: typeof asked === 'string' ? asked : null,
+            });
+            return;
+        }
+        navigations.push({ mode: mode === 'replace' ? 'replace' : 'push', address: target });
+        arrive(target, true);
+    }
+    function ceremony(path) {
+        const target = sameOriginPath(path);
+        if (target === null) {
+            deliver({ house: 'ceremony-refused', path: typeof path === 'string' ? path : null });
+            return;
+        }
+        ceremonies.push(target);
+    }
+    function receive(message) {
+        const data = message;
+        if (data === null || typeof data !== 'object')
+            return;
+        if (data.house === 'navigate') {
+            navigate(data.mode, data.address);
+        }
+        else if (data.house === 'ceremony') {
+            ceremony(data.path);
+        }
+    }
+    const port = {
+        postMessage(message) {
+            receive(message);
+        },
+        addEventListener(_type, listener) {
+            listeners.add(listener);
+        },
+        start() {
+            started = true;
+            const held = queued.splice(0);
+            queueMicrotask(() => {
+                for (const event of held) {
+                    for (const listener of listeners)
+                        listener(event);
+                }
+            });
+        },
+    };
+    if (options.status !== undefined)
+        deliver({ house: 'status', status: options.status });
+    deliver({ house: 'address', address, navigated: false });
+    return {
+        port: Promise.resolve(port),
+        navigations,
+        ceremonies,
+        address() {
+            return address;
+        },
+        open(asked) {
+            const target = sameOriginPath(asked);
+            if (target !== null)
+                arrive(target, false);
+        },
+        publish(status) {
+            deliver({ house: 'status', status });
+        },
+        attachRuntime(runtime) {
+            deliver({ house: 'runtime' }, [runtime]);
+        },
+    };
+}

package/wire.d.ts

@@ -0,0 +1,30 @@
+export interface HouseBridgeEvent {
+    readonly data: unknown;
+    readonly ports: readonly HouseMessagePort[];
+}
+export interface HouseMessagePort {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: HouseBridgeEvent) => void): void;
+    start(): void;
+}
+export type HouseBridgePort = HouseMessagePort;
+export interface HouseSyncState {
+    readonly state: string;
+    readonly providerUnreachable: boolean;
+}
+export interface HouseCredentialState {
+    readonly state: 'none' | 'held' | 'rejected';
+    readonly expires_at: number | null;
+}
+export interface HouseStatus {
+    readonly runtime: string;
+    readonly credential: HouseCredentialState;
+    readonly sync: HouseSyncState | null;
+    readonly refusal: {
+        readonly reason: string;
+    } | null;
+    readonly loss: string | null;
+    readonly release: unknown;
+}
+export type HouseNavigationMode = 'push' | 'replace';
+export declare const HOUSE_ADDRESS_MAX_CHARS = 1000;

package/wire.js

@@ -0,0 +1 @@
+export const HOUSE_ADDRESS_MAX_CHARS = 1000;