@abide/abide 0.114.1 → 0.116.0

package/docs/abide.md

@@ -38,6 +38,7 @@ at its address with `.md` on the end, and the links below point at those files.
 - `Selection` — `reference/types/Selection.md`
 - `busy` — `reference/busy.md`
 - `ready` — `reference/ready.md`
+- `synced` — `reference/synced.md`
 - `refresh` — `reference/refresh.md`
 - `invalidate` — `reference/invalidate.md`
 - `refuse` — `reference/refuse.md`
@@ -71,10 +72,12 @@ at its address with `.md` on the end, and the links below point at those files.
 - Generated surfaces — `reference/generated-surfaces.md`
 - `assistant` — `reference/assistant.md`
 - `AssistantMessage` — `reference/types/AssistantMessage.md`
+- `AssistantContent` — `reference/types/AssistantContent.md`
 - `AssistantEvent` — `reference/types/AssistantEvent.md`
 - `AssistantOptions` — `reference/types/AssistantOptions.md`
 - `Provider` — `reference/types/Provider.md`
 - `Toolbox` — `reference/types/Toolbox.md`
+- `ToolAnswer` — `reference/types/ToolAnswer.md`
 - `ToolDefinition` — `reference/types/ToolDefinition.md`
 - `claudeApi` — `reference/claudeApi.md`
 - `ClaudeApiConfig` — `reference/types/ClaudeApiConfig.md`
@@ -87,6 +90,8 @@ at its address with `.md` on the end, and the links below point at those files.
 - `route` — `reference/route.md`
 - `Params` — `reference/types/Params.md`
 - `online` — `reference/online.md`
+- `outbox` — `reference/outbox.md`
+- `QueuedCall` — `reference/types/QueuedCall.md`
 - `reachable` — `reference/reachable.md`
 - `trace` — `reference/trace.md`
 - `server` — `reference/server.md`
@@ -591,6 +596,7 @@ test('typing writes the value, and the value fills the field', async () => {
 | `bind:checked` | a checkbox, to a boolean |
 | `bind:open` | a `<details>`, to whether it is open |
 | `bind:group` | radios to one value, or checkboxes to an array of their `value`s |
+| `bind:files` | a file input, to an array of the files picked |
 | `bind:value={{get, set}}` | a field to a pair you write, where the value is computed |
 | `bind:prop={state}` | a component's prop, so the child's write reaches your value |
 
@@ -4889,7 +4895,7 @@ test('the health check carries the database beside the baseline', async () => {
 
 ## The browser going offline is a reactive value
 
-**`online` — the connection, read by name** — A contact edit made on a train is not saved. Take the browser offline in DevTools' Network panel and the banner says so.
+**`online` — the connection, read by name** — On a train the network comes and goes. Take the browser offline in DevTools' Network panel and the banner says so.
 
 ```abide src/ops/lib/OfflineBanner.abide
 <script>
@@ -4897,7 +4903,9 @@ import { online } from '@abide/abide'
 </script>
 
 {#if !online}
-    <p class="status">You are offline. Edits to contacts are not saved.</p>
+    <p class="status">
+        You are offline. Calls you log are sent once you are back.
+    </p>
 {/if}
 
 <ul class="fields">
@@ -4938,6 +4946,107 @@ watch(() => { if (online) refresh() })
 </script>
 ```
 
+## A call logged offline is sent when the network is back
+
+**`offline` — what a call settles to with no network** — A call logged on a train should not be lost in a tunnel. Take the browser offline in DevTools' Network panel, log a call, then go back online.
+
+```abide src/ops/lib/CallLog.abide
+<script>
+import { outbox, reactive } from '@abide/abide'
+import listCalls from '../listCalls.ts'
+import logCall from '../logCall.ts'
+
+const calls = listCalls()
+let note = reactive('')
+
+function log() {
+    const call = { id: crypto.randomUUID(), note }
+    note = ''
+    // With no network: shown at once, and sent from the outbox later.
+    logCall(call, {
+        offline: () => calls.patch((held) => held.push(call)),
+    })
+}
+</script>
+
+<div class="row">
+    <input bind:value={note} placeholder="What Grace said">
+    <button onclick={log}>Log call</button>
+</div>
+
+<ul class="fields stacked">
+    {#for call of calls.ready() ? calls : [] by call.id}
+        <li><span>call</span><strong>{call.note}</strong></li>
+    {/for}
+</ul>
+
+<ul class="tiles">
+    <li><span>waiting</span>
+        <strong>{outbox(logCall).length}</strong></li>
+    <li><span>saved</span>
+        <strong>{calls.synced() ? 'yes' : 'not yet'}</strong></li>
+</ul>
+```
+
+```ts src/ops/logCall.ts
+import { POST } from '@abide/abide/server'
+import { type Call, calls } from './lib/calls.ts'
+
+/** Logs a call once, however often it is sent: the browser picks its id. */
+export default POST(
+    ({ id, note }: Call) => {
+        calls.patch((held) => {
+            if (!held.some((call) => call.id === id)) held.push({ id, note })
+        })
+    },
+    { description: 'Logs a call against a contact.' },
+)
+```
+
+```ts src/ops/lib/CallLog.test.ts
+import { expect, test } from 'bun:test'
+import { flushSync } from '@abide/abide'
+import { mount } from '@abide/harness/abide'
+import { calls } from './calls.ts'
+import CallLog from './CallLog.abide'
+
+test('a call logged with the network is saved, and nothing waits', async () => {
+    using _log = await mount(CallLog({}))
+    const input = document.querySelector('input') as HTMLInputElement
+    input.value = 'Sent the quote'
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    document.querySelector('button')?.click()
+    await Bun.sleep(10)
+    flushSync()
+    expect(calls().map((call) => call.note)).toContain('Sent the quote')
+    const tiles = [...document.querySelectorAll('.tiles strong')]
+    expect(tiles.map((tile) => tile.textContent)).toEqual(['0', 'yes'])
+})
+
+test('a call sent twice under one id is logged once', async () => {
+    const { default: logCall } = await import('../logCall.ts')
+    const call = { id: 'again', note: 'Asked twice' }
+    await logCall(call)
+    await logCall(call)
+    expect(calls().filter((each) => each.id === 'again').length).toBe(1)
+})
+```
+
+A call given `offline` that gets no answer settles to what `offline` returns. A mutation then waits in the outbox, kept on the device through a reload, and is sent once the network answers: oldest first, one at a time, by one tab for all of them. Here `offline` also adds the call to the list, so it shows at once. `outbox` is asked of a selection as `busy` is, and answers a list: `outbox(logCall)` is the calls waiting for that handler.
+
+What is shown before the server has it says so: `synced()` is false on a value written in the browser rather than made by its producer, and on anything read from one. The list keeps its added call until the outbox is empty, then reads the server's again. A call is sent with the same `idempotency-key` every time, and `logCall` takes the browser's id, so a send whose answer was lost and is sent again logs the call once.
+
+| Name | What it does for the CRM |
+| --- | --- |
+| `outbox` · `rpc.outbox` | the calls waiting to be sent, and the ones the server refused, over a selection |
+| `QueuedCall` | one call in the outbox: its key, its address, its args, and how often it was sent |
+| `call.value` | what the call settled to: its stand-in, read as unsynced, until the server answers, and its refusal as `error()`, after a reload too |
+| `call.retry` | sends a refused call again |
+| `call.discard` | drops a call, sent or not |
+| `s.synced` | whether a value holds what its producer made |
+| `k.synced` · `rpc.synced` | the same, over a keyed value's or a handler's entries |
+| `synced` | the same, over a selection |
+
 ## Next
 
 - [Open it to machines](/guide/open-it-to-machines.md) — the CRM's handlers, described to other programs
@@ -5298,8 +5407,11 @@ const recorded: Provider = {
         const input = { name: 'Ada' }
         yield { type: 'tool', id: 'toolu_1', name }
         yield { type: 'input', id: 'toolu_1', input }
-        const answered = await tools.call(name, input)
-        yield { type: 'result', id: 'toolu_1', ...answered }
+        const { content, failed } = await tools.call(name, input)
+        // A search answers words, so its one piece is text.
+        const [words] = content
+        const text = words?.type === 'text' ? words.text : ''
+        yield { type: 'result', id: 'toolu_1', text, failed }
         yield { type: 'text', text: 'Ada Lovelace is at Analytical Engines.' }
         yield { type: 'done', stop: 'end_turn', usage: { input: 0, output: 0 } }
     },
@@ -5352,11 +5464,13 @@ test('the model calls the CRM search, through the app', async () => {
 
 | Name | What it does for the CRM |
 | --- | --- |
-| `AssistantMessage` | One turn of the transcript, `{ role, content }`. The last is the user's. |
+| `AssistantMessage` | One turn of the transcript, `{ role, content }`. The last is the user's. Its `content` is its words, or its pieces in order. |
+| `AssistantContent` | One piece of a turn: `text`, or an `image` as base64 with its type, so a rep can show the assistant a photo of a business card. PNG, JPEG, GIF and WebP, in the rep's own turns. |
 | `AssistantOptions` | `mcp` to offer the tools, and `maxTurns`, 10 by default, to cap the model's turns in one call. |
 | `AssistantEvent` | What the page reads: `text`, `tool` as a call starts, `input` once it is written, `result`, then `done` with the stop reason and token usage. The same events from every provider. |
-| `Provider` | What runs the conversation: one method, `run`. Write one for another model, or a recording for a test. |
+| `Provider` | What runs the conversation: one method, `run`, handed every turn as its pieces. Write one for another model, or a recording for a test. |
 | `Toolbox` | What a provider is handed: `list` of the tools, and `call` to run one as the asker. |
+| `ToolAnswer` | What `call` answers: its `content`, the same pieces as a turn — the tool's text, or the image a handler drew, which the model is shown as a picture — and whether it failed. |
 | `ToolDefinition` | One tool in `list`: its name, description and input schema. |
 | `abide:assistant` | The log namespace that writes one `debug` line per conversation once it ends: the stop reason, the transcript's length, the tool calls, the tokens and the time. |
 
@@ -5489,7 +5603,12 @@ test('the body is sent as written, with the transcript', async () => {
         max_tokens: 1024,
         system: 'Answer questions about contacts.',
         stream: true,
-        messages: [{ role: 'user', content: 'Which company is Ada at?' }],
+        messages: [
+            {
+                role: 'user',
+                content: [{ type: 'text', text: 'Which company is Ada at?' }],
+            },
+        ],
     })
 })
 ```
@@ -6422,7 +6541,15 @@ abide start
 ABIDE_OFFLINE=0 abide start
 ```
 
-Each page the CRM opens is kept on the device, with the answers its handlers gave, the public files it loaded and the bundle it runs, until `ABIDE_OFFLINE=0` turns that off where the CRM is served. With the network gone, a page opened before loads again with its data and works. One never opened says the device is offline, and a link to it leaves the page you are on standing.
+Each page the CRM opens is kept on the device, with the answers its handlers gave, the public files it loaded and the bundle it runs, until `ABIDE_OFFLINE=0` turns that off where the CRM is served. A kept page opens at once, however weak the signal, and the network is asked for the next copy behind it. With the network gone, a page opened in the last week loads again with its data and works. One never opened says the device is offline, and a link to it leaves the page you are on standing.
+
+| Name | What it does for the CRM |
+| --- | --- |
+| `cache-control: private, stale-while-revalidate=604800, stale-if-error=604800` | what a page and a handler's answer carry, so the device shows what it kept while it asks again |
+| `cache-control: public, max-age=0, stale-while-revalidate=604800, stale-if-error=604800` | the same, for a public file |
+| `clear-site-data: "cache"` | what a sign-in or a sign-out answers, so the browser forgets what it kept for the last person |
+
+What is kept is what those headers allow, and nothing else decides it. A handler that writes `cache-control: no-store` through `response` is never kept, and an answer with a `ttl` is shown from the device until its `max-age` runs out. A refresh always asks the network.
 
 With `src/public/icon.png` beside it, each page also links a manifest, so a phone can add the CRM to its home screen, which is what keeps what was saved there for good.
 
@@ -6464,6 +6591,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | [`Selection`](/reference/types/Selection.md) | `@abide/abide` |
 | [`busy`](/reference/busy.md) | `@abide/abide` |
 | [`ready`](/reference/ready.md) | `@abide/abide` |
+| [`synced`](/reference/synced.md) | `@abide/abide` |
 | [`refresh`](/reference/refresh.md) | `@abide/abide` |
 | [`invalidate`](/reference/invalidate.md) | `@abide/abide` |
 | [`refuse`](/reference/refuse.md) | `@abide/abide` |
@@ -6512,10 +6640,12 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | --- | --- |
 | [`assistant`](/reference/assistant.md) | `@abide/abide/server` |
 | [`AssistantMessage`](/reference/types/AssistantMessage.md) | `@abide/abide/server` |
+| [`AssistantContent`](/reference/types/AssistantContent.md) | `@abide/abide/server` |
 | [`AssistantEvent`](/reference/types/AssistantEvent.md) | `@abide/abide/server` |
 | [`AssistantOptions`](/reference/types/AssistantOptions.md) | `@abide/abide/server` |
 | [`Provider`](/reference/types/Provider.md) | `@abide/abide/server` |
 | [`Toolbox`](/reference/types/Toolbox.md) | `@abide/abide/server` |
+| [`ToolAnswer`](/reference/types/ToolAnswer.md) | `@abide/abide/server` |
 | [`ToolDefinition`](/reference/types/ToolDefinition.md) | `@abide/abide/server` |
 | [`claudeApi`](/reference/claudeApi.md) | `@abide/abide/server` |
 | [`ClaudeApiConfig`](/reference/types/ClaudeApiConfig.md) | `@abide/abide/server` |
@@ -6533,6 +6663,8 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | [`route`](/reference/route.md) | `@abide/abide` |
 | [`Params`](/reference/types/Params.md) | `@abide/abide` |
 | [`online`](/reference/online.md) | `@abide/abide` |
+| [`outbox`](/reference/outbox.md) | `@abide/abide` |
+| [`QueuedCall`](/reference/types/QueuedCall.md) | `@abide/abide` |
 | [`reachable`](/reference/reachable.md) | `@abide/abide/server` |
 | [`trace`](/reference/trace.md) | `@abide/abide/server` |
 | [`server`](/reference/server.md) | `@abide/abide/server` |
@@ -6724,6 +6856,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | `s.busy` | `() => boolean` | Work is in flight for this value. | [3.1](/rulebook#3.1), [3.2](/rulebook#3.2), [3.3](/rulebook#3.3), [3.4](/rulebook#3.4), [3.7](/rulebook#3.7), [3.9](/rulebook#3.9), [5.15](/rulebook#5.15), [7.5](/rulebook#7.5), [7.8](/rulebook#7.8), [11.19](/rulebook#11.19), [11.20](/rulebook#11.20), [11.21](/rulebook#11.21), [11.22](/rulebook#11.22), [11.50](/rulebook#11.50) |
 | `s.ready` | `() => boolean` | There is a value to serve. | [3.1](/rulebook#3.1), [3.2](/rulebook#3.2), [3.3](/rulebook#3.3), [3.5](/rulebook#3.5), [3.6](/rulebook#3.6), [3.8](/rulebook#3.8), [7.8](/rulebook#7.8), [11.20](/rulebook#11.20), [11.54](/rulebook#11.54), [11.58](/rulebook#11.58) |
 | `s.error` | `() => Failures \| undefined` | The standing refusal. | [3.1](/rulebook#3.1), [3.2](/rulebook#3.2), [3.3](/rulebook#3.3), [3.5](/rulebook#3.5), [4.10](/rulebook#4.10), [4.11](/rulebook#4.11), [4.12](/rulebook#4.12) |
+| `s.synced` | `() => boolean` | What is held is what the producer made. | [3.1](/rulebook#3.1), [3.2](/rulebook#3.2), [3.3](/rulebook#3.3), [3.10](/rulebook#3.10), [3.11](/rulebook#3.11), [3.12](/rulebook#3.12), [3.13](/rulebook#3.13) |
 | `s.isError` | `<Name extends Failures['name']>(error: unknown, name: Name) => error is Extract<Failures, { name: Name }>` | Whether a caught failure is the one named. | [3.1](/rulebook#3.1) |
 
 ## Triggers
@@ -6746,6 +6879,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 - [Talk to the server](/guide/talk-to-the-server.md)
 - [Keep it current](/guide/keep-it-current.md)
 - [Make it live](/guide/make-it-live.md)
+- [Run it](/guide/run-it.md)
 
 ---
 
@@ -6768,6 +6902,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 | --- | --- | --- | --- |
 | `k.busy` | `(pattern?: Partial<Args>) => boolean` | `busy` narrowed to matching entries. | [13.2](/rulebook#13.2), [13.3](/rulebook#13.3), [13.12](/rulebook#13.12) |
 | `k.ready` | `(pattern?: Partial<Args>) => boolean` | `ready` narrowed to matching entries. | [13.11](/rulebook#13.11), [13.12](/rulebook#13.12) |
+| `k.synced` | `(pattern?: Partial<Args>) => boolean` | `synced` narrowed to matching entries. | [13.12](/rulebook#13.12), [13.18](/rulebook#13.18) |
 | `k.invalidate` | `(pattern?: Partial<Args>) => void` | `invalidate` narrowed to matching entries. | [7.2](/rulebook#7.2), [7.3](/rulebook#7.3), [13.4](/rulebook#13.4), [13.12](/rulebook#13.12) |
 | `k.refresh` | `(pattern?: Partial<Args>) => void` | `refresh` narrowed to matching entries. | [7.4](/rulebook#7.4), [7.5](/rulebook#7.5), [13.4](/rulebook#13.4), [13.12](/rulebook#13.12) |
 
@@ -6775,6 +6910,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 
 - [Edit a contact](/guide/edit-a-contact.md)
 - [Keep it current](/guide/keep-it-current.md)
+- [Run it](/guide/run-it.md)
 
 ---
 
@@ -7028,7 +7164,7 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `busy` | `(selection?: Selection, pattern?: Partial<Args>) => boolean` | Whether any entry in the selection has work in flight. | [13.2](/rulebook#13.2), [13.3](/rulebook#13.3), [13.5](/rulebook#13.5), [13.12](/rulebook#13.12) |
+| `busy` | `(selection?: Selection, pattern?: Partial<Args>) => boolean` | Whether any entry in the selection has work in flight. | [13.2](/rulebook#13.2), [13.3](/rulebook#13.3), [13.5](/rulebook#13.5), [13.12](/rulebook#13.12), [46.11](/rulebook#46.11) |
 
 ## Taught in
 
@@ -7054,6 +7190,24 @@ Arrive here knowing which name you want. Each page is read off the registry: the
 
 ---
 
+<!-- reference/synced.md -->
+
+# `synced`
+
+`import { synced } from '@abide/abide'`
+
+## Selections — over many entries
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `synced` | `(selection?: Selection, pattern?: Partial<Args>) => boolean` | Whether every entry in the selection holds what its producer made. | [13.12](/rulebook#13.12), [13.18](/rulebook#13.18) |
+
+## Taught in
+
+- [Run it](/guide/run-it.md)
+
+---
+
 <!-- reference/refresh.md -->
 
 # `refresh`
@@ -7227,12 +7381,14 @@ Reactive primitives: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `Rpc` | `<Value, Args, Failures, Produced = Value>(args?: Args, options?: { signal?: AbortSignal }) => Reactive<Value, Value, Failures \| Failed<'HttpError', undefined>, Produced>` | A handler reached over http, or in process on a server. | [16.3](/rulebook#16.3), [16.4](/rulebook#16.4), [16.8](/rulebook#16.8), [16.11](/rulebook#16.11), [16.25](/rulebook#16.25), [16.26](/rulebook#16.26), [16.27](/rulebook#16.27), [16.28](/rulebook#16.28), [16.29](/rulebook#16.29), [16.33](/rulebook#16.33), [16.43](/rulebook#16.43), [16.48](/rulebook#16.48), [16.49](/rulebook#16.49), [16.62](/rulebook#16.62), [41.5](/rulebook#41.5), [41.7](/rulebook#41.7), [41.12](/rulebook#41.12), [41.21](/rulebook#41.21), [41.22](/rulebook#41.22), [41.25](/rulebook#41.25), [41.26](/rulebook#41.26), [41.27](/rulebook#41.27), [16.79](/rulebook#16.79) |
+| `Rpc` | `<Value, Args, Failures, Produced = Value>(args?: Args, options?: { signal?: AbortSignal; offline?: (args: Args) => Value }) => Reactive<Value, Value, Failures \| Failed<'HttpError', undefined>, Produced>` | A handler reached over http, or in process on a server. | [16.3](/rulebook#16.3), [16.4](/rulebook#16.4), [16.8](/rulebook#16.8), [16.11](/rulebook#16.11), [16.25](/rulebook#16.25), [16.26](/rulebook#16.26), [16.27](/rulebook#16.27), [16.28](/rulebook#16.28), [16.29](/rulebook#16.29), [16.33](/rulebook#16.33), [16.43](/rulebook#16.43), [16.48](/rulebook#16.48), [16.49](/rulebook#16.49), [16.62](/rulebook#16.62), [41.5](/rulebook#41.5), [41.7](/rulebook#41.7), [41.12](/rulebook#41.12), [41.21](/rulebook#41.21), [41.22](/rulebook#41.22), [41.25](/rulebook#41.25), [41.26](/rulebook#41.26), [41.27](/rulebook#41.27), [16.79](/rulebook#16.79), [16.80](/rulebook#16.80), [16.85](/rulebook#16.85) |
+| `offline` | `(args: Args) => Value` | What a call settles to where a browser could not get its answer. | [16.81](/rulebook#16.81), [16.82](/rulebook#16.82), [16.83](/rulebook#16.83), [16.84](/rulebook#16.84) |
 | `Value` | `unknown` | What the addressed `Reactive` holds. | [16.3](/rulebook#16.3), [16.30](/rulebook#16.30) |
 | `Produced` | `unknown` | What it yields, per the unit rule. | [1.2](/rulebook#1.2), [16.3](/rulebook#16.3) |
 | `Args` | `Record<string, JsonValue> \| undefined` | The arguments, in the body on a mutation and in the URL on a `GET` or `DELETE`. | [11.24](/rulebook#11.24), [16.18](/rulebook#16.18), [19.15](/rulebook#19.15) |
-| `rpc.busy` | `(pattern?: Partial<Args>) => boolean` | `busy` narrowed to the handler's matching entries. | [13.2](/rulebook#13.2), [13.3](/rulebook#13.3), [13.12](/rulebook#13.12) |
+| `rpc.busy` | `(pattern?: Partial<Args>) => boolean` | `busy` narrowed to the handler's matching entries. | [13.2](/rulebook#13.2), [13.3](/rulebook#13.3), [13.12](/rulebook#13.12), [46.11](/rulebook#46.11) |
 | `rpc.ready` | `(pattern?: Partial<Args>) => boolean` | `ready` narrowed to the handler's matching entries. | [13.11](/rulebook#13.11), [13.12](/rulebook#13.12) |
+| `rpc.synced` | `(pattern?: Partial<Args>) => boolean` | `synced` narrowed to the handler's matching entries. | [13.12](/rulebook#13.12), [13.18](/rulebook#13.18) |
 | `rpc.invalidate` | `(pattern?: Partial<Args>) => void` | `invalidate` narrowed to the handler's matching entries. | [7.2](/rulebook#7.2), [7.3](/rulebook#7.3), [13.4](/rulebook#13.4), [13.12](/rulebook#13.12) |
 | `rpc.refresh` | `(pattern?: Partial<Args>) => void` | `refresh` narrowed to the handler's matching entries. | [7.4](/rulebook#7.4), [7.5](/rulebook#7.5), [13.4](/rulebook#13.4), [13.12](/rulebook#13.12) |
 | `rpc.isError` | `<Name extends Failures['name']>(error: unknown, name: Name) => error is Extract<Failures, { name: Name }>` | Whether a caught failure is the one named. | [16.8](/rulebook#16.8) |
@@ -7241,11 +7397,18 @@ Reactive primitives: what is written in place rather than imported.
 | `rpc.url` | `(args?: Args) => string` | The address, resolved against the mount. | [16.9](/rulebook#16.9), [16.10](/rulebook#16.10), [30.28](/rulebook#30.28) |
 | `rpc.description` | `string \| undefined` | The human description. | [16.28](/rulebook#16.28) |
 
+## `outbox`
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `rpc.outbox` | `(pattern?: Partial<Args>) => QueuedCall[]` | `outbox` narrowed to the handler's calls. | [46.1](/rulebook#46.1), [13.12](/rulebook#13.12) |
+
 ## Taught in
 
 - [Talk to the server](/guide/talk-to-the-server.md)
 - [Keep it current](/guide/keep-it-current.md)
 - [Make it live](/guide/make-it-live.md)
+- [Run it](/guide/run-it.md)
 
 ---
 
@@ -7518,6 +7681,9 @@ Transports: what is written in place rather than imported.
 | `cache-control: no-store` | `/__abide/openapi.json`, `/__abide/mcp` | Refuses caching for an answer about the app's surfaces. | [21.4](/rulebook#21.4) |
 | `cache-control: public, max-age=31536000, immutable` | the built bundle | A chunk addressed by its own content hash. | [21.5](/rulebook#21.5) |
 | `cache-control: public, max-age=0, must-revalidate` | a file under a `public` directory | A file at an address the build never chose. | [21.12](/rulebook#21.12) |
+| `cache-control: private, stale-while-revalidate=604800, stale-if-error=604800` | a page, a `GET`'s answer, where `ABIDE_OFFLINE` registers its worker | The default that lets a copy kept on the device stand in for the network. | [21.22](/rulebook#21.22), [21.11](/rulebook#21.11), [21.17](/rulebook#21.17) |
+| `cache-control: public, max-age=0, stale-while-revalidate=604800, stale-if-error=604800` | a file under a `public` directory, where `ABIDE_OFFLINE` registers its worker | The same, for a file at an address the build never chose. | [21.23](/rulebook#21.23) |
+| `clear-site-data: "cache"` | an answer carrying `abide-principal`, where pages are kept offline | Drops what the browser's own cache kept for the caller signed in before. | [21.24](/rulebook#21.24) |
 | `etag` | a file under a `public` directory | The answered bytes, addressed by their content. | [21.13](/rulebook#21.13), [21.14](/rulebook#21.14) |
 | `referrer-policy: strict-origin-when-cross-origin` | a page | The browsers' own default, written down. | [21.6](/rulebook#21.6) |
 | `vary` | wherever an answer depends on a request header | Names the header the answer varied on. | [21.7](/rulebook#21.7) |
@@ -7682,7 +7848,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.9](/rulebook#20.9), [20.10](/rulebook#20.10), [20.12](/rulebook#20.12), [20.13](/rulebook#20.13), [20.14](/rulebook#20.14), [20.16](/rulebook#20.16), [20.17](/rulebook#20.17), [20.19](/rulebook#20.19), [20.20](/rulebook#20.20), [36.7](/rulebook#36.7), [16.78](/rulebook#16.78) |
+| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | [19.21](/rulebook#19.21), [19.22](/rulebook#19.22), [20.5](/rulebook#20.5), [20.7](/rulebook#20.7), [20.8](/rulebook#20.8), [20.9](/rulebook#20.9), [20.10](/rulebook#20.10), [20.12](/rulebook#20.12), [20.13](/rulebook#20.13), [20.14](/rulebook#20.14), [20.16](/rulebook#20.16), [20.17](/rulebook#20.17), [20.19](/rulebook#20.19), [20.20](/rulebook#20.20), [20.21](/rulebook#20.21), [20.22](/rulebook#20.22), [36.7](/rulebook#36.7), [16.78](/rulebook#16.78) |
 
 ## Taught in
 
@@ -7700,7 +7866,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `assistant` | `(messages: AssistantMessage[], provider: Provider, options?: AssistantOptions) => AsyncGenerator<AssistantEvent>` | A conversation with a model, as the events it produces. | [44.1](/rulebook#44.1), [44.2](/rulebook#44.2), [44.3](/rulebook#44.3), [44.4](/rulebook#44.4), [44.21](/rulebook#44.21) |
+| `assistant` | `(messages: AssistantMessage[], provider: Provider, options?: AssistantOptions) => AsyncGenerator<AssistantEvent>` | A conversation with a model, as the events it produces. | [44.1](/rulebook#44.1), [44.2](/rulebook#44.2), [44.3](/rulebook#44.3), [44.4](/rulebook#44.4), [44.21](/rulebook#44.21), [44.36](/rulebook#44.36), [44.37](/rulebook#44.37), [44.39](/rulebook#44.39) |
 
 ## Taught in
 
@@ -7718,7 +7884,25 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `AssistantMessage` | `{ role: 'user' \| 'assistant'; content: string }` | One turn of the transcript a caller sends. | [44.3](/rulebook#44.3), [44.4](/rulebook#44.4) |
+| `AssistantMessage` | `{ role: 'user' \| 'assistant'; content: string \| AssistantContent[] }` | One turn of the transcript a caller sends: its words, or its pieces in order. | [44.3](/rulebook#44.3), [44.4](/rulebook#44.4) |
+
+## Taught in
+
+- [Open it to machines](/guide/open-it-to-machines.md)
+
+---
+
+<!-- reference/types/AssistantContent.md -->
+
+# `AssistantContent`
+
+`import type { AssistantContent } from '@abide/abide/server'`
+
+## Assistant
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `AssistantContent` | `{ type: 'text'; text: string } \| { type: 'image'; data: string; mimeType: string }` | A piece of a turn: words, or an image as base64 with its type. | [44.5](/rulebook#44.5), [44.35](/rulebook#44.35), [44.36](/rulebook#44.36), [44.37](/rulebook#44.37), [44.38](/rulebook#44.38), [44.39](/rulebook#44.39) |
 
 ## Taught in
 
@@ -7772,7 +7956,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | [44.2](/rulebook#44.2), [44.28](/rulebook#44.28) |
+| `Provider` | `{ run(messages: (AssistantMessage & { content: AssistantContent[] })[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | [44.2](/rulebook#44.2), [44.28](/rulebook#44.28), [44.39](/rulebook#44.39) |
 
 ## Taught in
 
@@ -7790,7 +7974,25 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `Toolbox` | `{ list: ToolDefinition[]; call(name: string, input: unknown): Promise<{ text: string; failed: boolean }> }` | The app's MCP tools, called as the asker. | [44.6](/rulebook#44.6), [44.7](/rulebook#44.7) |
+| `Toolbox` | `{ list: ToolDefinition[]; call(name: string, input: unknown): Promise<ToolAnswer> }` | The app's MCP tools, called as the asker. | [44.6](/rulebook#44.6), [44.7](/rulebook#44.7), [44.35](/rulebook#44.35) |
+
+## Taught in
+
+- [Open it to machines](/guide/open-it-to-machines.md)
+
+---
+
+<!-- reference/types/ToolAnswer.md -->
+
+# `ToolAnswer`
+
+`import type { ToolAnswer } from '@abide/abide/server'`
+
+## Assistant
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `ToolAnswer` | `{ content: AssistantContent[]; failed: boolean }` | What a tool call answered: its pieces, and whether it failed. | [20.21](/rulebook#20.21), [20.22](/rulebook#20.22), [44.35](/rulebook#44.35) |
 
 ## Taught in
 
@@ -7826,7 +8028,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `claudeApi` | `(config: ClaudeApiConfig) => Provider` | The Claude Messages API as a provider. | [44.9](/rulebook#44.9), [44.10](/rulebook#44.10), [44.12](/rulebook#44.12), [44.21](/rulebook#44.21) |
+| `claudeApi` | `(config: ClaudeApiConfig) => Provider` | The Claude Messages API as a provider. | [44.9](/rulebook#44.9), [44.10](/rulebook#44.10), [44.12](/rulebook#44.12), [44.21](/rulebook#44.21), [44.35](/rulebook#44.35), [44.38](/rulebook#44.38) |
 
 ## Taught in
 
@@ -8020,6 +8222,45 @@ Generated surfaces: what is written in place rather than imported.
 
 ---
 
+<!-- reference/outbox.md -->
+
+# `outbox`
+
+`import { outbox } from '@abide/abide'`
+
+## `outbox`
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `outbox` | `<Chosen extends Selection>(selection?: Chosen, pattern?: Partial<Args>) => QueuedCall[]` | The calls a browser has queued and not delivered, the refused ones included. | [46.1](/rulebook#46.1), [46.2](/rulebook#46.2), [46.3](/rulebook#46.3), [46.4](/rulebook#46.4), [46.5](/rulebook#46.5), [46.6](/rulebook#46.6), [46.7](/rulebook#46.7), [46.8](/rulebook#46.8), [46.9](/rulebook#46.9), [46.10](/rulebook#46.10), [46.14](/rulebook#46.14), [46.15](/rulebook#46.15), [46.16](/rulebook#46.16), [46.17](/rulebook#46.17), [46.20](/rulebook#46.20), [18.35](/rulebook#18.35) |
+| `call.value` | `Reactive<Value, Value, Failed<string, unknown>>` | The value a queued call settled. | [46.5](/rulebook#46.5), [46.7](/rulebook#46.7), [46.18](/rulebook#46.18), [46.19](/rulebook#46.19) |
+| `call.retry` | `() => void` | Sends a queued call again. | [46.6](/rulebook#46.6), [46.12](/rulebook#46.12) |
+| `call.discard` | `() => void` | Drops a queued call. | [46.13](/rulebook#46.13) |
+
+## Taught in
+
+- [Run it](/guide/run-it.md)
+
+---
+
+<!-- reference/types/QueuedCall.md -->
+
+# `QueuedCall`
+
+`import type { QueuedCall } from '@abide/abide'`
+
+## `outbox`
+
+| Name | Signature | Meaning | Rules |
+| --- | --- | --- | --- |
+| `QueuedCall` | `{ id: string; method: 'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'; url: string; args: Record<string, JsonValue> \| undefined; queuedAt: number; attempts: number; value: Reactive<Value, Value, Failed<string, unknown>>; retry: () => void; discard: () => void }` | One call `outbox` holds. | [46.1](/rulebook#46.1), [46.10](/rulebook#46.10) |
+
+## Taught in
+
+- [Run it](/guide/run-it.md)
+
+---
+
 <!-- reference/reachable.md -->
 
 # `reachable`
@@ -8599,7 +8840,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `navigate` | `(url?: URL \| string, options?: { replace?: boolean, keepScroll?: boolean }) => Promise<void>` | Navigates. | [30.7](/rulebook#30.7), [30.9](/rulebook#30.9), [30.10](/rulebook#30.10), [30.11](/rulebook#30.11), [30.12](/rulebook#30.12), [30.13](/rulebook#30.13), [30.14](/rulebook#30.14), [30.15](/rulebook#30.15), [30.16](/rulebook#30.16), [30.17](/rulebook#30.17), [30.18](/rulebook#30.18), [30.20](/rulebook#30.20), [30.21](/rulebook#30.21), [30.22](/rulebook#30.22), [30.23](/rulebook#30.23), [30.24](/rulebook#30.24), [30.25](/rulebook#30.25), [30.27](/rulebook#30.27), [30.29](/rulebook#30.29), [30.30](/rulebook#30.30), [30.31](/rulebook#30.31), [30.32](/rulebook#30.32), [45.12](/rulebook#45.12) |
+| `navigate` | `(url?: URL \| string, options?: { replace?: boolean, keepScroll?: boolean }) => Promise<void>` | Navigates. | [30.7](/rulebook#30.7), [30.9](/rulebook#30.9), [30.10](/rulebook#30.10), [30.11](/rulebook#30.11), [30.12](/rulebook#30.12), [30.13](/rulebook#30.13), [30.14](/rulebook#30.14), [30.15](/rulebook#30.15), [30.16](/rulebook#30.16), [30.17](/rulebook#30.17), [30.18](/rulebook#30.18), [30.20](/rulebook#30.20), [30.21](/rulebook#30.21), [30.22](/rulebook#30.22), [30.23](/rulebook#30.23), [30.24](/rulebook#30.24), [30.25](/rulebook#30.25), [30.27](/rulebook#30.27), [30.29](/rulebook#30.29), [30.30](/rulebook#30.30), [30.31](/rulebook#30.31), [30.32](/rulebook#30.32), [45.12](/rulebook#45.12), [45.24](/rulebook#45.24) |
 
 ## Taught in
 
@@ -8639,11 +8880,12 @@ Generated surfaces: what is written in place rather than imported.
 | `name={expr}` | A reactive attribute or property. | [32.3](/rulebook#32.3), [32.20](/rulebook#32.20), [32.23](/rulebook#32.23), [32.37](/rulebook#32.37), [32.70](/rulebook#32.70), [32.71](/rulebook#32.71) |
 | `on<event>={fn}` | A native listener on an element, and an ordinary prop on a component. | [32.4](/rulebook#32.4) |
 | `name="…{expr}…"` | An interpolated quoted value. | [32.3](/rulebook#32.3), [32.71](/rulebook#32.71) |
-| `bind:value` | Two-way bind on an element. | [5.16](/rulebook#5.16), [32.5](/rulebook#32.5), [32.58](/rulebook#32.58), [32.59](/rulebook#32.59), [32.60](/rulebook#32.60), [32.61](/rulebook#32.61), [32.62](/rulebook#32.62), [32.72](/rulebook#32.72) |
+| `bind:value` | Two-way bind on an element. | [5.16](/rulebook#5.16), [32.5](/rulebook#32.5), [32.58](/rulebook#32.58), [32.59](/rulebook#32.59), [32.60](/rulebook#32.60), [32.61](/rulebook#32.61), [32.62](/rulebook#32.62), [32.72](/rulebook#32.72), [32.74](/rulebook#32.74) |
 | `bind:prop={state}` | Hands a component prop the caller's `Reactive`, or a `{get, set}` pair, to write through. | [32.6](/rulebook#32.6), [33.6](/rulebook#33.6), [33.8](/rulebook#33.8), [14.18](/rulebook#14.18) |
-| `bind:checked` | A boolean bind on an input. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72) |
-| `bind:open` | The same, on a `<details>`. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72) |
-| `bind:group` | Radio or checkbox membership. | [32.8](/rulebook#32.8), [32.72](/rulebook#32.72) |
+| `bind:checked` | A boolean bind on an input. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72), [32.74](/rulebook#32.74) |
+| `bind:open` | The same, on a `<details>`. | [32.7](/rulebook#32.7), [32.72](/rulebook#32.72), [32.74](/rulebook#32.74) |
+| `bind:group` | Radio or checkbox membership. | [32.8](/rulebook#32.8), [32.72](/rulebook#32.72), [32.74](/rulebook#32.74) |
+| `bind:files` | A file input's files, as a list. | [32.73](/rulebook#32.73), [32.72](/rulebook#32.72), [32.74](/rulebook#32.74) |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | [32.5](/rulebook#32.5), [32.6](/rulebook#32.6) |
 | `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | [32.9](/rulebook#32.9), [32.38](/rulebook#32.38), [32.66](/rulebook#32.66), [32.68](/rulebook#32.68), [32.69](/rulebook#32.69) |
 | `class:name={cond}` | Toggles a class. | [32.10](/rulebook#32.10), [32.71](/rulebook#32.71) |
@@ -8821,7 +9063,7 @@ Pages and routing: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `render` | `(component: Component) => Promise<Uint8Array>` | What produces a document. | [29.10](/rulebook#29.10), [35.4](/rulebook#35.4), [35.5](/rulebook#35.5), [35.6](/rulebook#35.6), [35.15](/rulebook#35.15), [35.16](/rulebook#35.16), [41.1](/rulebook#41.1), [41.2](/rulebook#41.2), [41.3](/rulebook#41.3), [41.4](/rulebook#41.4), [41.9](/rulebook#41.9), [41.13](/rulebook#41.13), [41.16](/rulebook#41.16), [41.17](/rulebook#41.17), [41.18](/rulebook#41.18), [41.19](/rulebook#41.19), [41.20](/rulebook#41.20), [41.28](/rulebook#41.28), [35.11](/rulebook#35.11), [41.29](/rulebook#41.29) |
+| `render` | `(component: Component) => Promise<Uint8Array>` | What produces a document. | [29.10](/rulebook#29.10), [35.4](/rulebook#35.4), [35.5](/rulebook#35.5), [35.6](/rulebook#35.6), [35.15](/rulebook#35.15), [35.16](/rulebook#35.16), [41.1](/rulebook#41.1), [41.2](/rulebook#41.2), [41.3](/rulebook#41.3), [41.4](/rulebook#41.4), [41.9](/rulebook#41.9), [41.13](/rulebook#41.13), [41.16](/rulebook#41.16), [41.17](/rulebook#41.17), [41.18](/rulebook#41.18), [41.19](/rulebook#41.19), [41.20](/rulebook#41.20), [41.28](/rulebook#41.28), [35.11](/rulebook#35.11), [41.29](/rulebook#41.29), [41.30](/rulebook#41.30) |
 
 ## Taught in
 
@@ -8853,7 +9095,7 @@ Configuration: what is written in place rather than imported.
 | `ABIDE_MAX_REQUEST_BODY_SIZE` | `number` | The default ceiling on a mutation's body. | [16.13](/rulebook#16.13), [16.54](/rulebook#16.54), [16.55](/rulebook#16.55), [16.78](/rulebook#16.78) |
 | `ABIDE_MAX_SOCKET_MESSAGE_SIZE` | `number` | The ceiling on a frame received over the socket mux, in bytes. | [18.28](/rulebook#18.28) |
 | `ABIDE_MAX_SOCKET_SUBSCRIPTIONS` | `number` | How many values one connection to the socket mux may follow. | [18.31](/rulebook#18.31), [18.32](/rulebook#18.32) |
-| `ABIDE_OFFLINE` | `boolean` | Whether the app keeps its pages and its bundle on the device, for when the network is gone. | [45.1](/rulebook#45.1), [45.2](/rulebook#45.2), [45.3](/rulebook#45.3), [45.4](/rulebook#45.4), [45.5](/rulebook#45.5), [45.6](/rulebook#45.6), [45.7](/rulebook#45.7), [45.8](/rulebook#45.8), [45.9](/rulebook#45.9), [45.10](/rulebook#45.10), [45.11](/rulebook#45.11), [45.12](/rulebook#45.12), [45.13](/rulebook#45.13), [45.14](/rulebook#45.14), [45.15](/rulebook#45.15), [45.16](/rulebook#45.16) |
+| `ABIDE_OFFLINE` | `boolean` | Whether the app keeps its pages and its bundle on the device, for when the network is gone. | [45.1](/rulebook#45.1), [45.2](/rulebook#45.2), [45.3](/rulebook#45.3), [45.4](/rulebook#45.4), [45.5](/rulebook#45.5), [45.6](/rulebook#45.6), [45.7](/rulebook#45.7), [45.8](/rulebook#45.8), [45.9](/rulebook#45.9), [45.10](/rulebook#45.10), [45.11](/rulebook#45.11), [45.12](/rulebook#45.12), [45.13](/rulebook#45.13), [45.14](/rulebook#45.14), [45.15](/rulebook#45.15), [45.16](/rulebook#45.16), [45.17](/rulebook#45.17), [45.18](/rulebook#45.18), [45.19](/rulebook#45.19), [45.20](/rulebook#45.20), [45.21](/rulebook#45.21), [45.22](/rulebook#45.22), [45.23](/rulebook#45.23), [45.24](/rulebook#45.24) |
 | `ABIDE_STOP_TIMEOUT` | `number` | How long `App.stop` drains, in ms. | [42.17](/rulebook#42.17), [42.18](/rulebook#42.18) |
 | `ABIDE_MAX_STREAM_BUFFER_SIZE` | `number` | The cap on a stream transcript held in memory. | [36.18](/rulebook#36.18) |
 | `ABIDE_MAX_LOG_BUFFER_COUNT` | `number` | How many lines `log.records` is trimmed back to. | [28.1](/rulebook#28.1) |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.114.1",
+    "version": "0.116.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",
@@ -57,7 +57,9 @@
     "sideEffects": [
         "./src/server/**",
         "./src/shared/WORK.ts",
-        "./src/shared/reactive/Reactive.ts"
+        "./src/shared/outbox.ts",
+        "./src/shared/reactive/Reactive.ts",
+        "./src/ui/outboxQueue.ts"
     ],
     "dependencies": {
         "typescript": "^7.0.2"

package/src/compiler/REACTIVE_MEMBERS.ts

@@ -28,6 +28,7 @@ export const REACTIVE_MEMBERS: ReadonlySet<string> = new Set([
     'ready',
     'refresh',
     'set',
+    'synced',
     'watch',
     // A `Reactive` is thenable (1.4), and `catch`/`finally` derive from `then` (1.5).
     'then',