@agentshouse/app-bridge 0.1.0-alpha.1 → 0.1.0-alpha.3

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 three families:
+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
@@ -12,8 +12,11 @@ port's one listener. It carries three families:
   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.
+- **Status** - the App reference the Runtime port is attached under, sync
+  state, credential state, release availability and observed failure.
+- **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.
 
 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
@@ -63,6 +66,9 @@ 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
+at and each address `open` plays as Back or Forward through the shell's own
+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, and attaches a Runtime port.

package/{bridge.d.ts → client/src/bridge.d.ts}

@@ -7,6 +7,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 HouseBridge {
     readonly runtime: Promise<HouseMessagePort>;
     address(): string | null;
@@ -14,6 +20,7 @@ export interface HouseBridge {
     push(address: string): Promise<string>;
     replace(address: string): Promise<string>;
     ceremony(path: string): Promise<never>;
+    readAttachment(room: string, attachment: string): Promise<HouseImageCopy | null>;
     status(): HouseStatus | null;
     onStatus(listener: (status: HouseStatus) => void): () => void;
 }

package/{bridge.js → client/src/bridge.js}

@@ -31,6 +31,8 @@ export function connectHouseBridge(source = heldBridge()) {
     const runtime = settled();
     const ceremonies = [];
     const navigations = [];
+    const attachments = new Map();
+    let nextAttachment = 0;
     const addressListeners = new Set();
     const statusListeners = new Set();
     let outbox = [];
@@ -75,6 +77,17 @@ export function connectHouseBridge(source = heldBridge()) {
             pending?.settle.reject(new HouseNavigationRefused(named));
             return;
         }
+        if (data.house === 'attachment') {
+            const answer = data;
+            if (typeof answer.id !== 'number')
+                return;
+            const pending = attachments.get(answer.id);
+            if (pending === undefined)
+                return;
+            attachments.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;
@@ -121,6 +134,13 @@ export function connectHouseBridge(source = heldBridge()) {
             send({ house: 'ceremony', path });
             return pending.promise;
         },
+        readAttachment(room, attachment) {
+            const pending = settled();
+            const id = ++nextAttachment;
+            attachments.set(id, pending.settle);
+            send({ house: 'attachment-read', id, room, attachment });
+            return pending.promise;
+        },
         status() {
             return status;
         },

package/{index.d.ts → client/src/index.d.ts}

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

package/{test-host.d.ts → client/src/test-host.d.ts}

@@ -1,3 +1,4 @@
+import type { HouseImageCopy } from './bridge.js';
 import type { HouseBridgePort, HouseMessagePort, HouseNavigationMode, HouseStatus } from './wire.js';
 export interface HouseBridgeNavigation {
     readonly mode: HouseNavigationMode;
@@ -15,5 +16,8 @@ export interface HouseBridgeTestHost {
 export interface HouseBridgeTestHostOptions {
     readonly address?: string;
     readonly status?: HouseStatus;
+    readonly images?: readonly (HouseImageCopy & {
+        readonly room: string;
+    })[];
 }
 export declare function createHouseBridgeTestHost(options?: HouseBridgeTestHostOptions): HouseBridgeTestHost;

package/{test-host.js → client/src/test-host.js}

@@ -1,3 +1,4 @@
+import { appAddressOf } from '../../src/apps/remainder.js';
 import { HOUSE_ADDRESS_MAX_CHARS } from './wire.js';
 const HOST_ORIGIN = 'https://house.invalid';
 function sameOriginPath(value) {
@@ -16,7 +17,7 @@ export function createHouseBridgeTestHost(options = {}) {
     const listeners = new Set();
     const queued = [];
     let started = false;
-    let address = sameOriginPath(options.address ?? '/') ?? '/';
+    let address = appAddressOf('/', options.address ?? '/');
     function deliver(data, ports = []) {
         const event = { data, ports };
         if (!started) {
@@ -62,6 +63,22 @@ export function createHouseBridgeTestHost(options = {}) {
         else if (data.house === 'ceremony') {
             ceremony(data.path);
         }
+        else if (data.house === 'attachment-read') {
+            const asked = data;
+            const image = options.images?.find((entry) => entry.room === asked.room && entry.attachment === asked.attachment);
+            deliver({
+                house: 'attachment',
+                id: asked.id,
+                image: image === undefined
+                    ? null
+                    : {
+                        attachment: image.attachment,
+                        copy: image.copy,
+                        name: image.name,
+                        media_type: image.media_type,
+                    },
+            });
+        }
     }
     const port = {
         postMessage(message) {
@@ -92,9 +109,7 @@ export function createHouseBridgeTestHost(options = {}) {
             return address;
         },
         open(asked) {
-            const target = sameOriginPath(asked);
-            if (target !== null)
-                arrive(target, false);
+            arrive(appAddressOf('/', asked), false);
         },
         publish(status) {
             deliver({ house: 'status', status });

package/{wire.d.ts → client/src/wire.d.ts}

@@ -17,6 +17,7 @@ export interface HouseCredentialState {
     readonly expires_at: number | null;
 }
 export interface HouseStatus {
+    readonly app: string;
     readonly runtime: string;
     readonly credential: HouseCredentialState;
     readonly sync: HouseSyncState | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.0-alpha.3",
+  "description": "Renderer-side client of the agents.house App bridge: navigation, ceremonies, status and Site image reads, with an in-page test host.",
   "license": "UNLICENSED",
   "type": "module",
   "sideEffects": false,
@@ -10,17 +10,19 @@
   },
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+      "types": "./client/src/index.d.ts",
+      "default": "./client/src/index.js"
     },
     "./test-host": {
-      "types": "./test-host.d.ts",
-      "default": "./test-host.js"
+      "types": "./client/src/test-host.d.ts",
+      "default": "./client/src/test-host.js"
     }
   },
   "files": [
-    "*.js",
-    "*.d.ts",
+    "client/src/*.js",
+    "client/src/*.d.ts",
+    "src/apps/remainder.js",
+    "src/apps/remainder.d.ts",
     "README.md"
   ]
 }

package/src/apps/remainder.d.ts

@@ -0,0 +1,2 @@
+export declare function appAddressOf(root: string, address: string): string;
+export declare function shellAddressOf(root: string, appAddress: string): string;

package/src/apps/remainder.js

@@ -0,0 +1,16 @@
+function split(address) {
+    const mark = address.search(/[?#]/u);
+    return mark < 0
+        ? { path: address, rest: '' }
+        : { path: address.slice(0, mark), rest: address.slice(mark) };
+}
+export function appAddressOf(root, address) {
+    const { path, rest } = split(address);
+    const below = root === '/' ? path : path.slice(root.length);
+    return `${below.startsWith('/') ? below : `/${below}`}${rest}`;
+}
+export function shellAddressOf(root, appAddress) {
+    const { path, rest } = split(appAddress);
+    const below = path === '/' ? '' : path;
+    return `${root === '/' ? '' : root}${below}${rest}` || '/';
+}