@abide/abide 0.114.1 → 0.115.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`
@@ -87,6 +88,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`
@@ -4889,7 +4892,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 +4900,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 +4943,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
@@ -6422,7 +6528,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 +6578,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` |
@@ -6533,6 +6648,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 +6841,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 +6864,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 +6887,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 +6895,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 +7149,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 +7175,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 +7366,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 +7382,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 +7666,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) |
@@ -8020,6 +8171,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`
@@ -8821,7 +9011,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 +9043,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) |
 | `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.115.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',

package/src/server/OFFLINE_STALE.ts

@@ -0,0 +1,10 @@
+// 21.22, 21.23 — HOW LONG A COPY KEPT ON THE DEVICE STAYS SERVABLE once stale, where `ABIDE_OFFLINE`
+// registers its worker: a week, while the network answers or fails to — as long as Safari keeps an
+// unvisited site's storage.
+//
+// NO `max-age` BESIDE IT on a page or a `GET`: a copy reads `max-age` as its own life (18.14), and
+// a followed copy stale from the moment it landed would reload on every read. With no lifetime and
+// no `Last-Modified`, a cache holds the answer stale at once, which is all the two windows need.
+
+export const OFFLINE_STALE =
+    'stale-while-revalidate=604800, stale-if-error=604800'

package/src/server/answerRequest.ts

@@ -26,6 +26,8 @@ import { ERROR_META } from '#shared/ERROR_META.ts'
 import { escapeAttribute } from '#shared/escapeText.ts'
 import { type Failed, isFailed } from '#shared/Failed.ts'
 import { HandlerRoute } from '#shared/HandlerRoute.ts'
+import { KEEP_HEADER } from '#shared/KEEP_HEADER.ts'
+import { KEEP_OPENED } from '#shared/KEEP_OPENED.ts'
 import { health } from '#shared/health.ts'
 import { appName } from '#shared/log.ts'
 import { compose } from '#shared/Middleware.ts'
@@ -59,6 +61,7 @@ import { callerOrMint } from './callerOf.ts'
 import { settingOn } from './config.ts'
 import { compressAnswer } from './compressAnswer.ts'
 import { DOCUMENT_HEADERS } from './DOCUMENT_HEADERS.ts'
+import { OFFLINE_STALE } from './OFFLINE_STALE.ts'
 import { noteCallInRender } from './deferredBuilds.ts'
 import { answerMcp, openApi } from './generatedSurfaces.ts'
 import { type AppRung, failureOf, rungsOver } from './hooks.ts'
@@ -84,7 +87,7 @@ import {
     within,
     writtenStatus,
 } from './requestScope.ts'
-import { seedFor } from './seedBuffer.ts'
+import { callsOnly, seedFor } from './seedBuffer.ts'
 
 // One row of the server's table the compiler writes (`SERVER_TABLE`). The loader is a dynamic import
 // so a page's markup is off the boot path until an address asks for it, which is the same reason
@@ -159,6 +162,8 @@ export type AppSources = {
     errors: RankedError[]
     /** The document the error pages are painted into. */
     errorDocument: string
+    /** 21.22, 21.23 — whether a page registers the worker `ABIDE_OFFLINE` turns on (45.1). */
+    offline: boolean
     /** Every handler, keyed by its method and address (`handlerKey`), to what answers it. 16.2. */
     handlers: Map<string, Mounted>
     /**
@@ -186,11 +191,11 @@ export async function answerRequest(
     const method = request.method === 'HEAD' ? 'GET' : request.method
 
     // 25.1, 25.3, 26.17 — the principal and the account of the app are handlers abide mounts,
-    // answered as the app's are.
+    // answered as the app's are — 21.4, save that neither is the app's to keep on the device.
     const own = OWN_HANDLERS.get(asked)
     if (own !== undefined)
         return own.method === method
-            ? answerRpc(own, {}, url, request, app)
+            ? answerRpc(own, {}, url, request, app, false)
             : methodRefused(app, asked, [own.method])
     // 20.5, 20.9, 36.7 — a surface of abide's own, or a 404 where it answers nothing.
     const surface = SURFACES.get(asked)
@@ -229,7 +234,7 @@ export async function answerRequest(
     const file = app.published.get(decodedOrKept(asked))
     if (file !== undefined)
         return readsOnly(request)
-            ? publicResponse(request, file)
+            ? publicResponse(request, file, app.offline)
             : methodRefused(app, asked, READS)
 
     // 15.16 — an address that will not percent-decode names nothing, and is the caller's fault.
@@ -312,7 +317,8 @@ async function answerMatched(
     const url = new URL(request.url)
     const asked = url.pathname
     const params = (currentRequestScope() as RequestScope).params as Params
-    if ('handler' in found) return answerRpc(found, params, url, request, app)
+    if ('handler' in found)
+        return answerRpc(found, params, url, request, app, app.offline)
     const page = found
 
     // 30.16 — THE CLIENT ROUTER ASKING, not a reader loading the page. `middleware` has already run
@@ -333,6 +339,7 @@ async function answerMatched(
     // that stored the identity answer for a reader who sent no `accept-encoding` must not hand it
     // to one who did, nor the reverse.
     const headers = new Headers(DOCUMENT_HEADERS)
+    if (app.offline) headers.set('cache-control', `private, ${OFFLINE_STALE}`)
     // THE HEADERS A `GET` WOULD CARRY, and no render for a body nobody is sent — nor a caller
     // minted for a request that never becomes a page.
     if (request.method === 'HEAD')
@@ -350,9 +357,21 @@ async function answerMatched(
     // 11.32 — the page renders in a scope of its own, so what its values hold is this request's —
     // and 41.13, every call it makes is left for the browser's own call to be answered from.
     // 41.29 — BUT NOT A PAGE A SCRIPT FETCHED, which nothing hydrates: its entries would answer the
-    // next call this caller makes with what the render saw, a sign-in since included.
-    const hydrated = request.headers.get('sec-fetch-dest') !== 'empty'
-    beginRender({ seed: hydrated ? seedFor(caller) : SEEDS_NOTHING, calls: [] })
+    // next call this caller makes with what the render saw, a sign-in since included — save the one
+    // the worker fetched for the navigation it answers, which is the page that hydrates (45.23).
+    const keep = request.headers.get(KEEP_HEADER)
+    const hydrated =
+        keep === KEEP_OPENED ||
+        request.headers.get('sec-fetch-dest') !== 'empty'
+    // 41.30 — SAVE ONE THE WORKER KEEPS, whose early calls are what a later open of it starts.
+    beginRender({
+        seed: hydrated
+            ? seedFor(caller)
+            : keep !== null
+              ? callsOnly()
+              : SEEDS_NOTHING,
+        calls: [],
+    })
     // 41.1, 35.2 — THE DOCUMENT IS THE BUILT PAGE, read whole before there is a `Response` to commit a
     // status to: a refusal the page read, or a throw, is answered by the nearest error page at its own
     // status rather than as a 200 the stream then abandons.
@@ -561,6 +580,7 @@ export async function appSources(parts: SourceParts): Promise<AppSources> {
         },
         published,
         explained: parts.explained,
+        offline: client.offline,
         ...mounted,
     }
     for (const row of sources.routes) {
@@ -738,14 +758,23 @@ function laneFailure(
  * authored, and the content-type off the extension, which is what `Bun.file` already derives
  * rather than a table kept here.
  */
-function publicResponse(request: Request, file: PublicFile): Response {
+function publicResponse(
+    request: Request,
+    file: PublicFile,
+    offline: boolean,
+): Response {
     return answerBlobTagged(
         Bun.file(file.path, { type: file.type }),
         file.etag,
         request,
         // 21.12. Revalidated every time and cached in between, which is what an unhashed name
         // earns — the etag is what makes that one conditional request rather than one transfer.
-        new Headers({ 'cache-control': 'public, max-age=0, must-revalidate' }),
+        // 21.23 — and served stale where the device keeps it, while that request is made.
+        new Headers({
+            'cache-control': offline
+                ? `public, max-age=0, ${OFFLINE_STALE}`
+                : 'public, max-age=0, must-revalidate',
+        }),
         200,
     )
 }

package/src/server/answerRpc.ts

@@ -29,6 +29,7 @@ import {
 import { followAsEvents } from './answerSocket.ts'
 import { answerValue, namesEtag, sseHeaders } from './answerValue.ts'
 import { argsFor } from './argsFor.ts'
+import { OFFLINE_STALE } from './OFFLINE_STALE.ts'
 import { callerOf } from './callerOf.ts'
 import {
     argsDocumentOf,
@@ -233,6 +234,8 @@ export async function answerRpc(
     request: Request,
     // 16.38 — what paints a refusal for a request that came as a navigation.
     pages: ErrorPages,
+    // 21.22 — whether the device keeps what is answered.
+    offline: boolean,
 ): Promise<Response> {
     const pathname = url.pathname
     const origin = request.headers.get('origin')
@@ -300,6 +303,7 @@ export async function answerRpc(
         args,
         key,
         entry,
+        offline,
     )
     // A `Response` the handler built is its own — but the origin answer below is laid over it, so it
     // varies on `Origin` too (21.7), which `handlerHeaders` never reached.
@@ -350,6 +354,7 @@ async function answerOutcome(
     args: unknown,
     key: string | undefined,
     entry: unknown,
+    offline: boolean,
 ): Promise<Response> {
     const handler = found.handler
     if (!outcome.settled) return answered(failureOf(outcome.error))
@@ -380,13 +385,28 @@ async function answerOutcome(
         headers.set(VERSION_HEADER, etag)
         RPC_SERVER.served?.(handler, serving, key as string)
     }
-    // 21.8, 21.9, 21.11 — WHAT IS LEFT OF THE LIFE OF THE PRODUCTION ANSWERED, in place of `no-store`
-    // and nothing else. A `ttl` of Infinity is bounded by `invalidate` alone (11.35), which no cache
-    // downstream hears, so it keeps `no-store`.
-    if (Number.isFinite(deadline))
+    // 21.22 — A `GET` THE DEVICE KEEPS, where the worker is there to keep it: a value, not a
+    // refusal (16.40) nor a stream with no end to keep (16.32) — a generator's, or the lines a
+    // `jsonl` or an `sse` fixed.
+    const framing = currentRequestScope()?.framing
+    const kept =
+        offline &&
+        found.method === 'GET' &&
+        !isFailed(value) &&
+        !streams(value) &&
+        framing !== 'jsonl' &&
+        framing !== 'sse' &&
+        writtenStatus() < 300
+    // 21.8, 21.9, 21.11 — WHAT IS LEFT OF THE LIFE OF THE PRODUCTION ANSWERED, in place of
+    // `no-store` or ahead of 21.22's directives, and nothing else. 21.17 — a `ttl` of Infinity is
+    // bounded by `invalidate` alone (11.35), which no cache downstream hears, so it keeps the default.
+    const life = Number.isFinite(deadline)
+        ? `, max-age=${Math.max(0, Math.floor((deadline - Date.now()) / 1000))}`
+        : ''
+    if (life !== '' || kept)
         headers.set(
             'cache-control',
-            `private, max-age=${Math.max(0, Math.floor((deadline - Date.now()) / 1000))}`,
+            `private${life}${kept ? `, ${OFFLINE_STALE}` : ''}`,
         )
     // 18.19 — A READER HOLDING THIS VERSION IS TOLD SO, and sent no body.
     if (