@agentshouse/app-bridge 0.1.0-ca559eade7c19 → 0.1.0-ca6bf24eae119

package/docs/families.md

@@ -13,8 +13,7 @@
   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 one only for `/bind/<app_ref>`, where the User binds
-  its Rooms and connects its account slots, with `?slot=<name>` to open at one
-  slot.
+  its Rooms, with `?slot=<name>` to open at one slot.
 - **Installation** - `install()` offers the page as a Home-screen app. Where the
   browser has an install prompt ready the shell shows it and the call resolves
   `'accepted'` or `'dismissed'` with the User's choice, spending that prompt;
@@ -47,17 +46,21 @@
   The App reports the visitor's choice with `analyticsConsent('accept')` or
   `analyticsConsent('decline')`; the shell hands it to House's analytics loader, and
   the choice never reaches House.
-- **Handoff** - when House hands its runtime over to a newer build, the App keeps
-  running, its `runtime` client and observations included: a call it makes
-  meanwhile waits for the newer runtime, however long that takes, and is
-  answered once, by it; each observation goes on with the newer runtime's
-  values; and the status and the address arrive again. A runtime that ended
-  before answering has its reads answered by the next one; since it may have
-  applied any other call, an act on House is answered the outcome
-  `transport-uncertainty`, and every other call, a Save or a draft write among
-  them, fails with the retryable code `transport-uncertainty`.
-- **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
+- **Releases and builds** - an open App keeps the release it loaded: a newer
+  release, or a newer House build, takes effect at the App's next load, offline
+  too once the browser stored it. When one tab loads a newer House build, the
+  other House tabs reload into it; Room Drafts, chat drafts and unsent changes
+  survive the reload.
+- **A runtime that ends** - when the browser ends House's runtime under an open
+  App, the App keeps running, its `runtime` client and observations included:
+  each observation goes on with the next runtime's values, and the status and
+  the address arrive again. A runtime that ended before answering has its reads
+  answered by the next one; since it may have applied any other call, an act on
+  House is answered the outcome `transport-uncertainty`, and every other call,
+  a Save or a draft write among them, fails with the retryable code
+  `transport-uncertainty`.
+- **Site image read** - given a Published Room and the Path of one of its
+  binary entries, 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
@@ -69,22 +72,21 @@
   refusal is House's `{ error: { code, retryable } }`, `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`.
-- **External calls** - `callExternal({ url, method, headers, body, slot, room_ref })`
+- **External calls** - `callExternal({ url, method, headers, body, room_ref })`
   has House's server send an HTTPS request to one of the release's declared
   external origins and resolves with the service's `status`, `headers` and its
   body as `body` text or `body_base64`, or a refusal as House's
   `{ error: { code, retryable } }`, or `null` when House does not answer. House fills in the
-  App and its running release; naming an account slot and one of the App's
-  bound Rooms places the key of the account that Room connects to the slot,
-  when the User holds one of the account's roles there, which the App never
-  sees, and naming neither sends no key. A Site's call names no slot, and the House panel names an
-  `account` instead. `body_base64` replaces `body` for bytes.
+  App and its running release. A `room_ref` names a Room the signed-in User binds to the App
+  in a `write` slot, and House adds that Room's Service key for the URL's origin, which App
+  code never sees; a call naming no Room carries no key, and a Site's call names no Room.
+  `body_base64` replaces `body` for bytes.
 - **App messages** - `messages(listener)` hands the listener each message
   another holder of this App sends to this User's running copies, as `from`,
   the sender's User id, and `body`, the JSON value they sent, until the
   function it returns is called. App code sends one through the Runtime's
   `call('message.send', { to, body })` with the recipient's User id and
-  a body of at most 32 KiB of JSON; House fills in the App and relays it only
+  a body of at most 32 kB of JSON; House fills in the App and relays it only
   to copies running now, storing nothing. The panel sends none.
 - **App screenshot read** - given an App reference, `readScreenshot(app)`
   answers the image this browser captured of that App's screen the first time
@@ -96,30 +98,29 @@
   after its latest release, as a JPEG `Blob`, or `null` when House holds none
   or does not answer. A Site's own renderer reads none.
 
-- **Cooperation** - `cooperate({ checkpoint, persist, capture, restore,
-ready, settle })` lets House activate a newer release of the App while it
-  runs, keeping the User's task; the function it returns withdraws it.
-  Register it in the entry script, before the first draw, or House treats the
-  page as not cooperating and the newer release waits for the App's next
-  open. When a newer release is stored, House calls `checkpoint()`, which
-  resolves at the App's next safe checkpoint and may never resolve, then
-  `persist()`, which makes authored work durable, then `capture()`, which
-  answers the meaningful task the App owns, such as the selected record,
-  filters, cursor, selection and scroll position, as JSON of at most 65,536
-  characters; House keeps the address itself. In the newer release House
-  calls `restore(task)` once its document has drawn, so the scroll position
-  and focus it sets hold, or `restore(null)` when it opens the release without
-  a task, then `ready()`, the App's own check that its local data and
-  capabilities work, and finally `settle('committed')` once the release is
-  active or `settle('abandoned')` when House returns to the release before
-  it, restoring the same task there. A release House opens already active is
-  settled `'committed'` at once, after `restore(task)` when House hands it a
-  task, and a cooperation registered after House settled is settled at its
-  registration. Until `settle('committed')` House fails the release's outside
-  calls at once, as offline, those of the workers it starts included, and
-  refuses its Saves, write acts and external calls with the retryable code
-  `house_trial_withheld`, so a start-up effect is not repeated; run start-up
-  effects after `settle('committed')`.
+- **Chat** - `chat.mount(element, options)` places House's Chat, the one chat
+  in which the User's Agent conversations show, in `element` over the page's
+  `runtime` client, and resolves to a handle: `update(options)` replaces its
+  options and `unmount()` removes it. House serves the Chat with the page and
+  keeps it current, so the App installs and bundles nothing for it. The
+  options: `conversation` opens one, `null` for a new chat, `agent` is the
+  Agent a new chat goes to, `showChats` adds its conversation list, `width` is
+  `full`, the element, or `3/4`, `1/2` or `1/3` of the window docked at its
+  right edge, `onOpen` hears each conversation it opens as
+  `{ conversation, agent }`, and `onLink` takes a link without a scheme in
+  place of the browser. CSS custom properties named `--chat-*` on the element
+  or an ancestor set its look. It shows conversations only to a release that
+  declares them. A Site and the House panel have none: their call rejects with
+  an error named and coded `NotSupportedError`, with `retryable` false.
+
+- **First place** - `cooperate({ placed })` tells House when the page has
+  drawn the place it opened on; the function it returns withdraws it. Register
+  it in the entry script, before the first draw. `placed()` resolves once the
+  page has drawn that place with what it shows: House keeps its
+  first-preparation surface over a page registered by its first draw until
+  then, and lifts it at the first draw of a page that registered none, so the
+  User goes from the surface to a drawn place in one change. House asks the
+  page for nothing else.
 
 ## The test host
 
@@ -141,9 +142,9 @@ records in `tabs` each `setTab`, answers a release code read from the
 by App 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
+as a browser without push does, settles every `setBadge`, records in `chats`
+each Chat `chat.mount` places, with its `element`, the `options` it was last
+given and whether it is still `mounted`, drawing nothing, delivers each App
 message `message({ from, body })` plays, and hands `bridge.runtime` the MD
-Runtime client `attachRuntime(client)` gives it. `checkpoint()` runs the
-registered cooperation's checkpoint, persist and capture and answers the task,
-`restore(task)` runs its restore and answers its readiness check, and
-`settle(activation)` hands it the outcome.
+Runtime client `attachRuntime(client)` gives it. It takes a `cooperate` and
+never calls `placed()`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentshouse/app-bridge",
-  "version": "0.1.0-ca559eade7c19",
-  "description": "Types of the agents.house App bridge House hands every App: 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 accessor and an in-page test host.",
+  "version": "0.1.0-ca6bf24eae119",
+  "description": "Types of the agents.house App bridge House hands every App: 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, App messages and the Chat, with an accessor and an in-page test host.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -23,5 +23,10 @@
     "docs",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentshouse/core.git",
+    "directory": "client"
+  }
 }

package/dist/mdruntime/acquisition.d.ts

@@ -1,13 +0,0 @@
-export type RuntimeDemand = {
-    readonly whole: boolean;
-    readonly rooms: readonly string[];
-    readonly handles: readonly string[];
-    readonly conversations: boolean;
-};
-export declare const WHOLE_DEMAND: RuntimeDemand;
-export declare function demanded(demand: RuntimeDemand, room: {
-    readonly locator: string;
-    readonly handle: string;
-}): boolean;
-export declare function wider(next: RuntimeDemand, current: RuntimeDemand): boolean;
-export declare function narrower(next: RuntimeDemand, current: RuntimeDemand): boolean;

package/dist/mdruntime/file.d.ts

@@ -1,19 +0,0 @@
-export type ChatDraftFile = {
-    name: string;
-    blob: Blob;
-};
-export type FileDeclaration = {
-    name: string;
-    mediaType: string;
-    byteLength: number;
-    contentHash: string;
-    width?: number;
-    height?: number;
-};
-export type Extent = {
-    width: number;
-    height: number;
-};
-export declare function extentOf(bytes: Uint8Array): Extent | null;
-export declare function hexDigest(digest: ArrayBuffer): string;
-export declare function declaredFile(file: ChatDraftFile): Promise<FileDeclaration>;

package/dist/mdruntime/rows.d.ts

@@ -1,37 +0,0 @@
-import { type Frontmatter } from '../mdmodel/index.js';
-import type { HeadChange } from './adapter.js';
-import type { BinaryFileRecord } from './binary.js';
-import { type Composition } from './collection.js';
-type Fields = Readonly<Record<string, unknown>>;
-export type DocumentRow = {
-    key: string;
-    kind: 'document';
-    room: string;
-    path: string;
-    type: string | null;
-    fields: Fields;
-    values: Fields;
-    reached: Readonly<Record<string, readonly unknown[]>>;
-    directories: readonly string[];
-    text: string | null;
-    change: HeadChange | null;
-    fileId: string | null;
-    binary: BinaryFileRecord | null;
-};
-export type ReferenceRow = {
-    key: string;
-    kind: 'reference';
-    room: string;
-    source: string;
-    target: string;
-    field: string;
-    forms: readonly string[];
-    path: string;
-    type: string;
-};
-export type Row = DocumentRow | ReferenceRow;
-export declare function documentKey(room: string, path: string): string;
-export declare function roomOfKey(key: string): string;
-export declare function markdownPath(path: string): boolean;
-export declare function rowsOf(room: string, path: string, document: Frontmatter | null, composition: Composition, change: HeadChange | null, fileId: string | null, binary: BinaryFileRecord | null): readonly Row[];
-export {};

package/dist/mdruntime/shared.d.ts

@@ -1,10 +0,0 @@
-export type Paths<V> = Readonly<Record<string, V>>;
-type Weigh<V> = (key: string, value: V) => number;
-export declare function shared<V>(map: Paths<V>): Paths<V>;
-export declare function patched<V>(base: Paths<V>, set: Iterable<readonly [string, V]>, removed?: Iterable<string>): Paths<V>;
-export declare function tally<V>(map: Paths<V>, weigh: Weigh<V>): number;
-export declare function sizeOf<V>(map: Paths<V>): number;
-export declare function differing<V>(left: Paths<V>, right: Paths<V>, same?: (left: V, right: V) => boolean): ReadonlySet<string>;
-export declare function drafted<V>(base: Paths<V>): Record<string, V>;
-export declare function settled<V>(draft: Record<string, V>): Paths<V>;
-export {};

package/dist/mdruntime/transfer.d.ts

@@ -1,9 +0,0 @@
-import type { Refusal } from '../mdmodel/index.js';
-export type Unconfirmed = {
-    kind: 'unconfirmed';
-};
-export type Refused = {
-    kind: 'refused';
-    refusal: Refusal;
-};
-export declare const unconfirmed: Unconfirmed;

package/dist/mdruntime/turn.d.ts

@@ -1,6 +0,0 @@
-export declare function yielded(): Promise<void>;
-export declare const ROW_WEIGHT = 256;
-export type Later<T> = T | Promise<T>;
-export declare function after<T, R>(value: Later<T>, next: (value: T) => R): Later<R>;
-export declare function inUnits<T>(items: Iterable<T>, each: (item: T) => number): Later<void>;
-export declare function inChunks<T>(items: readonly T[], weigh: (item: T) => number, each: (chunk: readonly T[]) => void): Promise<void>;