@agentshouse/app-bridge 0.1.0-c8d8dc6285bbd → 0.1.0-c8d97d63f2350

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/families.md CHANGED
@@ -13,8 +13,7 @@
13
13
  absolute path, carries its current address as the return target, and the page
14
14
  returns there when it completes. An App names an address House gave it in a
15
15
  reading and composes one only for `/bind/<app_ref>`, where the User binds
16
- its Rooms and connects its account slots, with `?slot=<name>` to open at one
17
- slot.
16
+ its Rooms, with `?slot=<name>` to open at one slot.
18
17
  - **Installation** - `install()` offers the page as a Home-screen app. Where the
19
18
  browser has an install prompt ready the shell shows it and the call resolves
20
19
  `'accepted'` or `'dismissed'` with the User's choice, spending that prompt;
@@ -47,15 +46,19 @@
47
46
  The App reports the visitor's choice with `analyticsConsent('accept')` or
48
47
  `analyticsConsent('decline')`; the shell hands it to House's analytics loader, and
49
48
  the choice never reaches House.
50
- - **Handoff** - when House hands its runtime over to a newer build, the App keeps
51
- running, its `runtime` client and observations included: a call it makes
52
- meanwhile waits for the newer runtime, however long that takes, and is
53
- answered once, by it; each observation goes on with the newer runtime's
54
- values; and the status and the address arrive again. A runtime that ended
55
- before answering has its reads answered by the next one; since it may have
56
- applied any other call, an act on House is answered the outcome
57
- `transport-uncertainty`, and every other call, a Save or a draft write among
58
- them, fails with the retryable code `transport-uncertainty`.
49
+ - **Releases and builds** - an open App keeps the release it loaded: a newer
50
+ release, or a newer House build, takes effect at the App's next load, offline
51
+ too once the browser stored it. When one tab loads a newer House build, the
52
+ other House tabs reload into it; Room Drafts, chat drafts and unsent changes
53
+ survive the reload.
54
+ - **A runtime that ends** - when the browser ends House's runtime under an open
55
+ App, the App keeps running, its `runtime` client and observations included:
56
+ each observation goes on with the next runtime's values, and the status and
57
+ the address arrive again. A runtime that ended before answering has its reads
58
+ answered by the next one; since it may have applied any other call, an act on
59
+ House is answered the outcome `transport-uncertainty`, and every other call,
60
+ a Save or a draft write among them, fails with the retryable code
61
+ `transport-uncertainty`.
59
62
  - **Site image read** - given a Published Room and the Path of one of its
60
63
  binary entries, it answers the web copy's path and metadata, or `null` when no
61
64
  copy exists. The original bytes never cross this bridge at a Site.
@@ -69,21 +72,20 @@
69
72
  refusal is House's `{ error: { code, retryable } }`, `app_release_not_found` for an
70
73
  App with no release; a read House does not answer, or one that outlived
71
74
  the browser's signed-in User, is `null`.
72
- - **External calls** - `callExternal({ url, method, headers, body, slot, room_ref })`
75
+ - **External calls** - `callExternal({ url, method, headers, body, room_ref })`
73
76
  has House's server send an HTTPS request to one of the release's declared
74
77
  external origins and resolves with the service's `status`, `headers` and its
75
78
  body as `body` text or `body_base64`, or a refusal as House's
76
79
  `{ error: { code, retryable } }`, or `null` when House does not answer. House fills in the
77
- App and its running release; naming an account slot and one of the App's
78
- bound Rooms places the key of the account that Room connects to the slot,
79
- when the User holds one of the account's roles there, which the App never
80
- sees, and naming neither sends no key. A Site's call names no slot, and the House panel names an
81
- `account` instead. `body_base64` replaces `body` for bytes.
80
+ App and its running release. A `room_ref` names a Room the signed-in User binds to the App
81
+ in a `write` slot, and House adds that Room's Service key for the URL's origin, which App
82
+ code never sees; a call naming no Room carries no key, and a Site's call names no Room.
83
+ `body_base64` replaces `body` for bytes.
82
84
  - **App messages** - `messages(listener)` hands the listener each message
83
85
  another holder of this App sends to this User's running copies, as `from`,
84
86
  the sender's User id, and `body`, the JSON value they sent, until the
85
87
  function it returns is called. App code sends one through the Runtime's
86
- `call('message.send', { to, body })` with the recipient's User id and
88
+ `call('apps/messages/send', { to, body })` with the recipient's User id and
87
89
  a body of at most 32 kB of JSON; House fills in the App and relays it only
88
90
  to copies running now, storing nothing. The panel sends none.
89
91
  - **App screenshot read** - given an App reference, `readScreenshot(app)`
@@ -111,30 +113,14 @@
111
113
  declares them. A Site and the House panel have none: their call rejects with
112
114
  an error named and coded `NotSupportedError`, with `retryable` false.
113
115
 
114
- - **Cooperation** - `cooperate({ checkpoint, persist, capture, restore,
115
- ready, settle })` lets House activate a newer release of the App while it
116
- runs, keeping the User's task; the function it returns withdraws it.
117
- Register it in the entry script, before the first draw, or House treats the
118
- page as not cooperating and the newer release waits for the App's next
119
- open. When a newer release is stored, House calls `checkpoint()`, which
120
- resolves at the App's next safe checkpoint and may never resolve, then
121
- `persist()`, which makes authored work durable, then `capture()`, which
122
- answers the meaningful task the App owns, such as the selected record,
123
- filters, cursor, selection and scroll position, as JSON of at most 65,536
124
- characters; House keeps the address itself. In the newer release House
125
- calls `restore(task)` once its document has drawn, so the scroll position
126
- and focus it sets hold, or `restore(null)` when it opens the release without
127
- a task, then `ready()`, the App's own check that its local data and
128
- capabilities work, and finally `settle('committed')` once the release is
129
- active or `settle('abandoned')` when House returns to the release before
130
- it, restoring the same task there. A release House opens already active is
131
- settled `'committed'` at once, after `restore(task)` when House hands it a
132
- task, and a cooperation registered after House settled is settled at its
133
- registration. Until `settle('committed')` House fails the release's outside
134
- calls at once, as offline, those of the workers it starts included, and
135
- refuses its Saves, write acts and external calls with the retryable code
136
- `house_trial_withheld`, so a start-up effect is not repeated; run start-up
137
- effects after `settle('committed')`.
116
+ - **First place** - `cooperate({ placed })` tells House when the page has
117
+ drawn the place it opened on; the function it returns withdraws it. Register
118
+ it in the entry script, before the first draw. `placed()` resolves once the
119
+ page has drawn that place with what it shows: House keeps its
120
+ first-preparation surface over a page registered by its first draw until
121
+ then, and lifts it at the first draw of a page that registered none, so the
122
+ User goes from the surface to a drawn place in one change. House asks the
123
+ page for nothing else.
138
124
 
139
125
  ## The test host
140
126
 
@@ -160,7 +146,5 @@ as a browser without push does, settles every `setBadge`, records in `chats`
160
146
  each Chat `chat.mount` places, with its `element`, the `options` it was last
161
147
  given and whether it is still `mounted`, drawing nothing, delivers each App
162
148
  message `message({ from, body })` plays, and hands `bridge.runtime` the MD
163
- Runtime client `attachRuntime(client)` gives it. `checkpoint()` runs the
164
- registered cooperation's checkpoint, persist and capture and answers the task,
165
- `restore(task)` runs its restore and answers its readiness check, and
166
- `settle(activation)` hands it the outcome.
149
+ Runtime client `attachRuntime(client)` gives it. It takes a `cooperate` and
150
+ never calls `placed()`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agentshouse/app-bridge",
3
- "version": "0.1.0-c8d8dc6285bbd",
3
+ "version": "0.1.0-c8d97d63f2350",
4
4
  "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.",
5
5
  "license": "MIT",
6
6
  "type": "module",