@abide/abide 0.115.0 → 0.116.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @abide/abide
 
+## 0.116.0
+
+### Minor Changes
+
+- c1c3924: `bind:files` — a file input's files as an array, one or many: a pick writes them, and an array written to it (one dropped, or `[]` to clear) is what the input holds. A `bind:` an element has no property for, such as `bind:file` or `bind:vlaue`, is now a build error where it compiled to an attribute that bound nothing. RULEBOOK 32.73, 32.74
+- 48cfc3e: tools answer images — a handler whose answer is a png, jpeg, gif or webp body reaches a model as the image: `/__abide/mcp` carries it as an `image` content item (so Claude Code, through a bridge, sees it), and a `Toolbox` call answers a `ToolAnswer` of `content` — the same pieces, text or image — which `claudeApi` shows the model as the call's result. Any other image type, an svg, is answered as its text. Breaking for a hand-written `Provider`: a `ToolAnswer` is `{ content, failed }` where it was `{ text, failed }`. RULEBOOK 20.21, 44.35
+- 48cfc3e: multimodal transcripts — an `AssistantMessage`'s `content` is its words or its pieces in order, each `AssistantContent` text or an image as base64 with its type. `assistant` refuses an image a model can't take or one outside a user turn, and hands a `Provider` every turn as its pieces, words alone as one text piece. `claudeApi` shows each image to the model as an image block in its place, and `claudeCode` sends the one message Claude Code is sent as Messages API blocks, each image in its place. RULEBOOK 44.5, 44.36, 44.37, 44.38, 44.39
+
+### Patch Changes
+
+- 0a78343: a page reached inside the app reloads offline — the router tells the offline worker each address a navigation reaches, and the worker keeps its page where no saved copy would stand in ([`a3975be`](https://github.com/briancray/abide/commit/a3975be224584df096fe799c6291c0dfcd80cf84))
+
 ## 0.115.0
 
 ### Minor Changes

package/docs/REGISTRY.md

@@ -321,25 +321,27 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | 19.21, 19.22, 20.5, 20.7, 20.8, 20.9, 20.10, 20.12, 20.13, 20.14, 20.16, 20.17, 20.19, 20.20, 36.7, 16.78 |
+| `/__abide/mcp` | `POST` | The streamable-http MCP endpoint. | 19.21, 19.22, 20.5, 20.7, 20.8, 20.9, 20.10, 20.12, 20.13, 20.14, 20.16, 20.17, 20.19, 20.20, 20.21, 20.22, 36.7, 16.78 |
 
 # Assistant
 
 | 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, 44.2, 44.3, 44.4, 44.21 |
-| `AssistantMessage` | `{ role: 'user' \| 'assistant'; content: string }` | One turn of the transcript a caller sends. | 44.3, 44.4 |
+| `assistant` | `(messages: AssistantMessage[], provider: Provider, options?: AssistantOptions) => AsyncGenerator<AssistantEvent>` | A conversation with a model, as the events it produces. | 44.1, 44.2, 44.3, 44.4, 44.21, 44.36, 44.37, 44.39 |
+| `AssistantMessage` | `{ role: 'user' \| 'assistant'; content: string \| AssistantContent[] }` | One turn of the transcript a caller sends: its words, or its pieces in order. | 44.3, 44.4 |
+| `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, 44.35, 44.36, 44.37, 44.38, 44.39 |
 | `AssistantEvent` | `{ type: 'text'; text: string } \| { type: 'tool'; id: string; name: string } \| { type: 'input'; id: string; input: unknown } \| { type: 'result'; id: string; text: string; failed: boolean } \| { type: 'done'; stop: string; usage: { input: number; output: number } }` | What a conversation produces: text, a tool call as it starts, its input once written, its result, and the end. | 44.2, 44.11, 44.28 |
 | `AssistantOptions` | `{ mcp?: boolean; maxTurns?: number }` | What `assistant` takes beside a provider. | 44.6, 44.8, 44.11 |
-| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | 44.2, 44.28 |
-| `Toolbox` | `{ list: ToolDefinition[]; call(name: string, input: unknown): Promise<{ text: string; failed: boolean }> }` | The app's MCP tools, called as the asker. | 44.6, 44.7 |
+| `Provider` | `{ run(messages: (AssistantMessage & { content: AssistantContent[] })[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | 44.2, 44.28, 44.39 |
+| `Toolbox` | `{ list: ToolDefinition[]; call(name: string, input: unknown): Promise<ToolAnswer> }` | The app's MCP tools, called as the asker. | 44.6, 44.7, 44.35 |
+| `ToolAnswer` | `{ content: AssistantContent[]; failed: boolean }` | What a tool call answered: its pieces, and whether it failed. | 20.21, 20.22, 44.35 |
 | `ToolDefinition` | `{ name: string; description: string; inputSchema: unknown; annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean }; outputSchema: unknown }` | A tool as the app's MCP surface lists it. | 20.14, 20.16, 20.19, 44.6 |
 
 ## `claudeApi`
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `claudeApi` | `(config: ClaudeApiConfig) => Provider` | The Claude Messages API as a provider. | 44.9, 44.10, 44.12, 44.21 |
+| `claudeApi` | `(config: ClaudeApiConfig) => Provider` | The Claude Messages API as a provider. | 44.9, 44.10, 44.12, 44.21, 44.35, 44.38 |
 | `ClaudeApiConfig` | `{ apiKey: string; baseURL?: string; model: string; max_tokens: number; system?: string \| unknown[]; tools?: unknown[]; [field: string]: unknown }` | A Messages API request body, less `messages` and `stream`, with the client's key and origin. | 44.9, 44.10 |
 
 ## `claudeCode`
@@ -519,7 +521,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `navigate` | `(url?: URL \| string, options?: { replace?: boolean, keepScroll?: boolean }) => Promise<void>` | Navigates. | 30.7, 30.9, 30.10, 30.11, 30.12, 30.13, 30.14, 30.15, 30.16, 30.17, 30.18, 30.20, 30.21, 30.22, 30.23, 30.24, 30.25, 30.27, 30.29, 30.30, 30.31, 30.32, 45.12 |
+| `navigate` | `(url?: URL \| string, options?: { replace?: boolean, keepScroll?: boolean }) => Promise<void>` | Navigates. | 30.7, 30.9, 30.10, 30.11, 30.12, 30.13, 30.14, 30.15, 30.16, 30.17, 30.18, 30.20, 30.21, 30.22, 30.23, 30.24, 30.25, 30.27, 30.29, 30.30, 30.31, 30.32, 45.12, 45.24 |
 
 # `.abide` files
 
@@ -551,11 +553,12 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `name={expr}` | A reactive attribute or property. | 32.3, 32.20, 32.23, 32.37, 32.70, 32.71 |
 | `on<event>={fn}` | A native listener on an element, and an ordinary prop on a component. | 32.4 |
 | `name="…{expr}…"` | An interpolated quoted value. | 32.3, 32.71 |
-| `bind:value` | Two-way bind on an element. | 5.16, 32.5, 32.58, 32.59, 32.60, 32.61, 32.62, 32.72 |
+| `bind:value` | Two-way bind on an element. | 5.16, 32.5, 32.58, 32.59, 32.60, 32.61, 32.62, 32.72, 32.74 |
 | `bind:prop={state}` | Hands a component prop the caller's `Reactive`, or a `{get, set}` pair, to write through. | 32.6, 33.6, 33.8, 14.18 |
-| `bind:checked` | A boolean bind on an input. | 32.7, 32.72 |
-| `bind:open` | The same, on a `<details>`. | 32.7, 32.72 |
-| `bind:group` | Radio or checkbox membership. | 32.8, 32.72 |
+| `bind:checked` | A boolean bind on an input. | 32.7, 32.72, 32.74 |
+| `bind:open` | The same, on a `<details>`. | 32.7, 32.72, 32.74 |
+| `bind:group` | Radio or checkbox membership. | 32.8, 32.72, 32.74 |
+| `bind:files` | A file input's files, as a list. | 32.73, 32.72, 32.74 |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | 32.5, 32.6 |
 | `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | 32.9, 32.38, 32.66, 32.68, 32.69 |
 | `class:name={cond}` | Toggles a class. | 32.10, 32.71 |
@@ -656,7 +659,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `ABIDE_MAX_REQUEST_BODY_SIZE` | `number` | The default ceiling on a mutation's body. | 16.13, 16.54, 16.55, 16.78 |
 | `ABIDE_MAX_SOCKET_MESSAGE_SIZE` | `number` | The ceiling on a frame received over the socket mux, in bytes. | 18.28 |
 | `ABIDE_MAX_SOCKET_SUBSCRIPTIONS` | `number` | How many values one connection to the socket mux may follow. | 18.31, 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, 45.2, 45.3, 45.4, 45.5, 45.6, 45.7, 45.8, 45.9, 45.10, 45.11, 45.12, 45.13, 45.14, 45.15, 45.16, 45.17, 45.18, 45.19, 45.20, 45.21, 45.22, 45.23 |
+| `ABIDE_OFFLINE` | `boolean` | Whether the app keeps its pages and its bundle on the device, for when the network is gone. | 45.1, 45.2, 45.3, 45.4, 45.5, 45.6, 45.7, 45.8, 45.9, 45.10, 45.11, 45.12, 45.13, 45.14, 45.15, 45.16, 45.17, 45.18, 45.19, 45.20, 45.21, 45.22, 45.23, 45.24 |
 | `ABIDE_STOP_TIMEOUT` | `number` | How long `App.stop` drains, in ms. | 42.17, 42.18 |
 | `ABIDE_MAX_STREAM_BUFFER_SIZE` | `number` | The cap on a stream transcript held in memory. | 36.18 |
 | `ABIDE_MAX_LOG_BUFFER_COUNT` | `number` | How many lines `log.records` is trimmed back to. | 28.1 |

package/docs/RULEBOOK.md

@@ -1385,6 +1385,13 @@ whatever its handler's args schema declares there.
 20.20 A handler `/__abide/mcp` would list whose args schema can never be an object MUST refuse the
 app at boot, naming the handler.
 
+20.21 A `tools/call` that `/__abide/mcp` answers for a call answered with an image body of a type
+44.36 names MUST carry that body as one `image` content item, base64 with its type, in place of its
+text, and MUST carry no `structuredContent`.
+
+20.22 A call to a tool declaring an `outputSchema` that is answered with an `image/*` body MUST be
+refused, its text naming the tool and the image's type, and MUST be logged per 20.18 as a 500.
+
 # 21. Generated headers
 
 21.1 Every response MUST carry `x-content-type-options: nosniff`.
@@ -2072,6 +2079,13 @@ declarations first, then each directive's in the tag's order.
 attribute a `bind:name` names, `checked` beside `bind:group`, an `<option selected>` inside a
 `<select bind:value>`, or text inside a `<textarea bind:value>`.
 
+32.73 `bind:files` MUST hold a list of the input's files, with or without `multiple`, MUST write the
+files picked back on change, and MUST hand the input a list written to it; the server MUST write
+nothing for it.
+
+32.74 A `bind:` on an element naming none of `value`, `checked`, `open`, `group`, `files` and
+`element` MUST be a build error.
+
 # 33. Props
 
 33.1 `props` MUST be callable from a `<script>` block only, and calling it from a `<script module>`
@@ -3160,7 +3174,7 @@ of its own.
 each one.
 
 44.5 `claudeCode` MUST send a transcript to Claude Code as one message, its earlier turns folded
-above the last.
+above the last and each `AssistantContent` image in its place.
 
 44.6 With `mcp`, the `Toolbox` `assistant` hands a `Provider` MUST list the tools `/__abide/mcp`
 lists, and MUST call each as a request through the app answering the request.
@@ -3251,6 +3265,23 @@ that browser carrying any other.
 `principal.clear` made at its browser since it opened signs in, at the caller 26.9 rotates it to,
 and the command it yields MUST pair that one.
 
+44.35 A `Toolbox` call MUST hand as its `ToolAnswer`'s `content` the pieces `/__abide/mcp` carries
+for the same call, `claudeApi` MUST show the model those pieces as the call's result, and the
+`result` `AssistantEvent` MUST carry their words and none of their images.
+
+44.36 `assistant` MUST refuse 400, before any `Provider` is reached, a transcript holding an
+`AssistantContent` image whose `mimeType` is none of `image/png`, `image/jpeg`, `image/gif` and
+`image/webp`.
+
+44.37 `assistant` MUST refuse 400, before any `Provider` is reached, a transcript holding an
+`AssistantContent` image in a turn that is not the user's.
+
+44.38 `claudeApi` MUST send each `AssistantContent` image to the model as an image block, base64 with
+its type, in its place in its turn.
+
+44.39 `assistant` MUST hand a `Provider` each turn as its `AssistantContent` pieces, a turn's string
+as one text piece.
+
 # 45. Offline
 
 45.1 Where `ABIDE_OFFLINE` is on, a page `abide build` built MUST register the worker
@@ -3322,6 +3353,10 @@ and that copy is stale by no more than its `stale-if-error`.
 45.23 The worker `ABIDE_OFFLINE` turns on MUST ask for a page it saves with an `abide-keep` header,
 naming `open` where its answer is the one a navigation opens.
 
+45.24 The worker `ABIDE_OFFLINE` turns on MUST save the page of an address a `navigate` reached,
+where it saved no copy of that address 45.19 would answer with, and MUST NOT save one of another
+origin.
+
 # 46. Outbox
 
 46.1 `outbox` MUST answer, oldest first, every call queued in it that was neither delivered nor

package/docs/abide.md

@@ -72,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`
@@ -594,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 |
 
@@ -5404,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 } }
     },
@@ -5458,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. |
 
@@ -5595,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?' }],
+            },
+        ],
     })
 })
 ```
@@ -6627,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` |
@@ -7833,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
 
@@ -7851,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
 
@@ -7869,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
 
@@ -7923,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
 
@@ -7941,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
 
@@ -7977,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
 
@@ -8789,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
 
@@ -8829,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) |
@@ -9043,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), [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_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.115.0",
+    "version": "0.116.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/src/compiler/classifyTemplate.ts

@@ -84,10 +84,10 @@ export type ClassifiedAttribute = {
     // 32.11 — a spread's attributes, less the ones the element names itself, kept written by a
     // binding of its own.
     | { kind: 'spread'; explicit: string[] }
-    // 32.5, 32.7, 32.8 — the property and the value, kept in step both ways. `reflects` is the
-    // attribute the property's value stands at in the tag, and `undefined` where it is not an
+    // 32.5, 32.7, 32.8, 32.73 — the property and the value, kept in step both ways. `reflects` is
+    // the attribute the property's value stands at in the tag, and `undefined` where it is not an
     // attribute: a `<textarea>`'s value is its text and a `<select>`'s is its options' `selected`,
-    // which the markup writes inside the tag (32.61).
+    // which the markup writes inside the tag (32.61), and a file input's files are no markup at all.
     | {
           kind: 'bound'
           bind: ValueBind
@@ -135,7 +135,7 @@ export function classifyAttributes(
         readsAnItem(holder: object): boolean
     },
 ): ClassifiedAttribute[] {
-    refuseTwoOwners(node)
+    refuseBinds(node)
     const groups = mergeGroupsOf(node)
     const sharing: ReturnType<typeof sharingOf>[] = []
     for (const group of groups) sharing.push(sharingOf(group, lowering))
@@ -210,7 +210,8 @@ export function classifyAttributes(
                 kind: 'bound',
                 bind,
                 reflects:
-                    bind === 'value' && node.lowerTag !== 'input'
+                    bind === 'files' ||
+                    (bind === 'value' && node.lowerTag !== 'input')
                         ? undefined
                         : bind === 'group'
                           ? 'checked'
@@ -354,15 +355,22 @@ function heldClasses(groups: MergeGroup[]): string[] {
 }
 
 /**
+ * 32.74 — A `bind:` AN ELEMENT HAS NO PROPERTY FOR IS REFUSED: `bind:vlaue` would otherwise be an
+ * attribute of that name, binding nothing and saying nothing.
+ *
  * 32.72 — WHAT A `bind:` WRITES IS THE BIND'S ALONE: `checked` beside `bind:checked` or
  * `bind:group`, `value` beside `bind:value`, any `bind:name` beside `name` — and an
  * `<option selected>` inside a `<select bind:value>`, and a `<textarea bind:value>`'s text. Two
  * owners of one value render whichever the browser keeps and move with whichever wrote last.
  */
-function refuseTwoOwners(node: ElementNode): void {
+function refuseBinds(node: ElementNode): void {
     for (const attribute of node.attributes) {
         const lower = attribute.lowerName
         if (!lower.startsWith('bind:') || lower === 'bind:element') continue
+        if (valueBindOf(lower) === undefined)
+            throw new Error(
+                `abide: <${node.tag}> has ${attribute.name}, which binds nothing — an element binds ${VALUE_BINDS.join(', ')} or element. RULEBOOK 32.74.`,
+            )
         const owned =
             lower === 'bind:group' ? 'checked' : lower.slice('bind:'.length)
         const beside = attributeOf(node, owned)
@@ -468,18 +476,17 @@ function isElementBind(lowerName: string): boolean {
 /**
  * The binds that keep a property and a value in step.
  *
- * 32.5, 32.7, 32.8 — both emitters ask: the server writes the value into the tag and the client
- * binds the property.
+ * 32.5, 32.7, 32.8, 32.73 — both emitters ask: the server writes the value into the tag, where it
+ * has one, and the client binds the property.
  */
-type ValueBind = 'value' | 'checked' | 'open' | 'group'
+const VALUE_BINDS = ['value', 'checked', 'open', 'group', 'files'] as const
+type ValueBind = (typeof VALUE_BINDS)[number]
 
 /** The value bind a folded attribute name is, or `undefined` for any other attribute. */
 function valueBindOf(lowerName: string): ValueBind | undefined {
-    if (lowerName === 'bind:value') return 'value'
-    if (lowerName === 'bind:checked') return 'checked'
-    if (lowerName === 'bind:open') return 'open'
-    if (lowerName === 'bind:group') return 'group'
-    return undefined
+    if (!lowerName.startsWith('bind:')) return undefined
+    const bind = lowerName.slice('bind:'.length) as ValueBind
+    return VALUE_BINDS.includes(bind) ? bind : undefined
 }
 
 /**

package/src/compiler/emitClient.ts

@@ -769,7 +769,7 @@ function elementUnits(
             handlers.push(
                 `${element}.addEventListener(${JSON.stringify(one.event)}, ${lowering.listener(one.attribute)})`,
             )
-        // 32.5, 32.7, 32.8 — THE PROPERTY AND THE VALUE, IN STEP BOTH WAYS: a watch on this
+        // 32.5, 32.7, 32.8, 32.73 — THE PROPERTY AND THE VALUE, IN STEP BOTH WAYS: a watch on this
         // region's scope writes the property, and a listener writes it back.
         // 32.8 — a group compares against the input's own value, read where the value is.
         else if (one.kind === 'bound' && one.bind === 'group')
@@ -782,6 +782,10 @@ function elementUnits(
                           : JSON.stringify(one.own.value)
                 }), ${SCOPE})`,
             )
+        else if (one.kind === 'bound' && one.bind === 'files')
+            binds.push(
+                `${lowering.use('bindFiles')}(${element}, ${lowering.reference(one.attribute)}, ${SCOPE})`,
+            )
         else if (one.kind === 'bound')
             binds.push(
                 `${lowering.use('bindProperty')}(${element}, ${JSON.stringify(one.bind)}, ${lowering.reference(one.attribute)}, ${SCOPE})`,

package/src/server/BRIDGE_VERSION.ts

@@ -1,3 +1,3 @@
 // The `abide-bridge` release a pairing command names, so a visitor's `bunx` runs the relay this
 // server speaks. `packages/abide/tests/claudeCode.test.ts` holds it to the bridge package's own.
-export const BRIDGE_VERSION = '0.3.3'
+export const BRIDGE_VERSION = '0.3.4'

package/src/server/IMAGE_TYPES.ts

@@ -0,0 +1,10 @@
+/**
+ * The image types a model is shown (44.36). A leaf, because `assistant` refuses a transcript image of
+ * any other and `/__abide/mcp` answers one of any other as its text (20.21).
+ */
+export const IMAGE_TYPES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'image/webp',
+])

package/src/server/answerWorker.ts

@@ -17,6 +17,7 @@ import {
     OFFLINE_SAVED,
 } from '#shared/OFFLINE_CACHES.ts'
 import { PRINCIPAL_HEADER } from '#shared/PRINCIPAL_HEADER.ts'
+import { REACHED_MESSAGE } from '#shared/REACHED_MESSAGE.ts'
 import type { Manifest } from './manifestOf.ts'
 
 // What `framingOf` reads as a framed stream (16.32), and a binary's bytes (16.34), which may be one —
@@ -38,7 +39,7 @@ async function dropOurs(keeping) {
 }
 `
 
-// 45.3 through 45.8, 45.13, and 45.17 through 45.21.
+// 45.3 through 45.8, 45.13, 45.17 through 45.21, and 45.24.
 const SAVING = `
 self.addEventListener('install', (event) => {
     event.waitUntil(
@@ -60,26 +61,23 @@ self.addEventListener('activate', (event) => {
             await self.registration.navigationPreload?.disable()
             await self.clients.claim()
             for (const client of await self.clients.matchAll({ type: 'window' }))
-                await fetch(pageRequest(client.url, undefined, '1')).then(
-                    (response) =>
-                        kept(response)
-                            ? keep(new Request(client.url), response)
-                            : response.body?.cancel(),
-                    () => {},
-                )
+                await keepPage(client.url)
         })(),
     )
 })
 
 self.addEventListener('message', (event) => {
-    if (event.data === 'rotated') event.waitUntil(caches.delete(SAVED))
+    if (event.data === 'rotated') event.waitUntil(dropSaved())
+    const reached = event.data?.[REACHED]
+    if (typeof reached === 'string' && reached.startsWith(\`\${self.location.origin}/\`))
+        event.waitUntil(keepReached(reached))
 })
 
 self.addEventListener('fetch', (event) => {
     const request = event.request
     if (request.mode === 'navigate') {
         if (request.method === 'GET') event.respondWith(answer(event, true))
-        else event.waitUntil(caches.delete(SAVED))
+        else event.waitUntil(dropSaved())
         return
     }
     if (request.method !== 'GET') return
@@ -132,8 +130,7 @@ async function answer(event, page) {
     try {
         return await fromNetwork(event, page, page)
     } catch {
-        if (life !== undefined && life.age < life.fresh + life.error)
-            return marked(saved)
+        if (life !== undefined && standsIn(life)) return marked(saved)
         return page ? offline() : Response.error()
     }
 }
@@ -169,18 +166,49 @@ async function fromNetwork(event, page, opened) {
     const asked = page
         ? pageRequest(request.url, request.headers, opened ? OPENED : '1')
         : new Request(request, { cache: 'no-cache' })
+    const since = drops
     const response = await fetch(asked)
     // A copy nothing reads is a tee holding every chunk, so one is cloned only to be saved.
     const copy = kept(response) ? response.clone() : undefined
-    const rotated = response.headers.has(PRINCIPAL)
-    event.waitUntil(
-        (rotated ? caches.delete(SAVED) : Promise.resolve()).then(() =>
-            copy === undefined ? undefined : keep(request, copy),
-        ),
-    )
+    event.waitUntil(keep(request, copy, since, response.headers.has(PRINCIPAL)))
     return response
 }
 
+// 45.13, 45.24 — A PAGE NO NAVIGATION ASKED FOR, kept as a page behind the one opened is: an open
+// window's as the worker activates, and an address the router reached.
+function keepPage(url) {
+    const since = drops
+    return fetch(pageRequest(url, undefined, '1')).then((response) => {
+        // Nothing reads this answer, so one 45.3 or 45.4 turns away is let go here.
+        const copy = kept(response) ? response : undefined
+        if (copy === undefined) response.body?.cancel()
+        return keep(new Request(url), copy, since, response.headers.has(PRINCIPAL))
+    }, () => {})
+}
+
+// The addresses being kept, so one reached twice before its copy lands is asked for once.
+const reaching = new Set()
+
+// 45.24 — AN ADDRESS THE ROUTER REACHED, whose page no navigation asked for, so none is saved unless
+// this asks — and only where no copy saved would stand in offline: one that would is refreshed by the
+// page's own next load, and asking on every step renders each page twice. A page kept holds no seed
+// (RULEBOOK 41.29), so what a reload paints stale is markup its calls then answer over.
+async function keepReached(url) {
+    if (reaching.has(url)) return
+    reaching.add(url)
+    try {
+        const saved = await caches.match(url, { cacheName: SAVED, ignoreVary: true })
+        if (saved === undefined || !standsIn(lifeOf(saved))) await keepPage(url)
+    } finally {
+        reaching.delete(url)
+    }
+}
+
+// 45.19 — whether a copy kept still stands in where the network gives nothing.
+function standsIn(life) {
+    return life.age < life.fresh + life.error
+}
+
 // How old a kept copy is and how long each of its windows runs, in seconds; a copy with no date is
 // as old as it can be.
 function lifeOf(response) {
@@ -219,9 +247,27 @@ function kept(response) {
     return !STREAMED.some((streamed) => type.startsWith(streamed))
 }
 
-async function keep(request, response) {
+// 45.7 — EVERY PAGE SAVED DROPPED, and with them every copy asked for before the drop: one asked under
+// the cookies of then would land after it holding the caller signed out since. The drop an answer's
+// own abide-principal makes is the exception, since that answer is the new caller's.
+let drops = 0
+
+function dropSaved() {
+    drops += 1
+    return caches.delete(SAVED)
+}
+
+// Saves a copy 45.3 and 45.4 let through where no drop has come since its request was asked — after
+// the drop its own answer makes where that answer rotated the principal — and cancels one where one has.
+async function keep(request, copy, since, rotated) {
+    if (rotated) {
+        await dropSaved()
+        since = drops
+    }
+    if (copy === undefined) return
+    if (since !== drops) return copy.body?.cancel()
     const cache = await caches.open(SAVED)
-    await cache.put(request, response)
+    await cache.put(request, copy)
 }
 
 function offline() {
@@ -277,6 +323,7 @@ const KEPT = ${JSON.stringify(KEPT_HEADER)}
 const KEEP = ${JSON.stringify(KEEP_HEADER)}
 const OPENED = ${JSON.stringify(KEEP_OPENED)}
 const NAVIGATION = ${JSON.stringify(NAVIGATION_HEADER)}
+const REACHED = ${JSON.stringify(REACHED_MESSAGE)}
 // 45.4 — the types a stream 16.32 frames, which has no end to save.
 const STREAMED = ${JSON.stringify(STREAMED_TYPES)}
 const OFFLINE = ${JSON.stringify(OFFLINE)}

package/src/server/assistant.ts

@@ -12,11 +12,20 @@
 
 import { namedLogger } from '#shared/log.ts'
 import { refuse } from '#shared/refuse.ts'
+import { IMAGE_TYPES } from './IMAGE_TYPES.ts'
 import { type McpReply, McpSurface } from './generatedSurfaces.ts'
 import { request, within } from './requestScope.ts'
 
-/** One turn of the transcript a caller sends. */
-export type AssistantMessage = { role: 'user' | 'assistant'; content: string }
+/** A piece of a turn: words, or an image as base64 with its type. */
+export type AssistantContent =
+    | { type: 'text'; text: string }
+    | { type: 'image'; data: string; mimeType: string }
+
+/** One turn of the transcript a caller sends: its words, or its pieces in order. */
+export type AssistantMessage = {
+    role: 'user' | 'assistant'
+    content: string | AssistantContent[]
+}
 
 /** What a conversation yields, the same from every provider. */
 export type AssistantEvent =
@@ -43,19 +52,19 @@ export type ToolDefinition = {
     outputSchema: unknown
 }
 
+/** What a tool call answered: its pieces, and whether it failed. 20.21, 44.35. */
+export type ToolAnswer = { content: AssistantContent[]; failed: boolean }
+
 /** The app's MCP tools, called as the asker. */
 export type Toolbox = {
     list: ToolDefinition[]
-    call(
-        name: string,
-        input: unknown,
-    ): Promise<{ text: string; failed: boolean }>
+    call(name: string, input: unknown): Promise<ToolAnswer>
 }
 
 /** What runs a conversation: a model's API, or something that runs its own loop. */
 export type Provider = {
     run(
-        messages: AssistantMessage[],
+        messages: (AssistantMessage & { content: AssistantContent[] })[],
         tools: Toolbox,
         limits: { maxTurns: number; signal: AbortSignal },
     ): AsyncGenerator<AssistantEvent>
@@ -81,11 +90,38 @@ export async function* assistant(
             400,
             'The transcript has to end on a user turn for the assistant to answer it. RULEBOOK 44.3.',
         )
+    // Every turn as its pieces, so a provider reads one shape: words alone are one text piece.
+    const turns: Parameters<Provider['run']>[0] = []
+    for (const message of messages) {
+        if (typeof message.content === 'string') {
+            turns.push({
+                role: message.role,
+                content: [{ type: 'text', text: message.content }],
+            })
+            continue
+        }
+        turns.push({ role: message.role, content: message.content })
+        for (const piece of message.content) {
+            if (piece?.type !== 'image') continue
+            // 44.37 — an image is the asker's to show, never a turn the model answered.
+            if (message.role !== 'user')
+                throw refuse(
+                    400,
+                    'An image can only stand in a user turn of the transcript. RULEBOOK 44.37.',
+                )
+            // 44.36.
+            if (!IMAGE_TYPES.has(piece.mimeType))
+                throw refuse(
+                    400,
+                    `An image in the transcript is ${piece.mimeType}, and a model is shown only ${[...IMAGE_TYPES].join(', ')}. RULEBOOK 44.36.`,
+                )
+        }
+    }
     const tools = toolboxOver(
         options.mcp === true ? appSurface() : NO_SURFACE,
         askerOf(request()),
     )
-    const events = provider.run(messages, tools, {
+    const events = provider.run(turns, tools, {
         maxTurns: options.maxTurns ?? MAX_TURNS,
         signal: request().signal,
     })
@@ -181,10 +217,15 @@ function toolboxOver(surface: McpSurface, asker: Request): Toolbox {
                 return await surface.call(name, input, asker)
             } catch (thrown) {
                 return {
-                    text:
-                        thrown instanceof Error
-                            ? thrown.message
-                            : String(thrown),
+                    content: [
+                        {
+                            type: 'text',
+                            text:
+                                thrown instanceof Error
+                                    ? thrown.message
+                                    : String(thrown),
+                        },
+                    ],
                     failed: true,
                 }
             }
@@ -199,3 +240,31 @@ function toolboxOver(surface: McpSurface, asker: Request): Toolbox {
     )
     return tools
 }
+
+/**
+ * Pieces as Messages API blocks, in order: text as text, an image as base64 with its type. A text of
+ * whitespace alone is left out, as the API refuses one. 44.38.
+ */
+export function blocksOf(content: AssistantContent[]): unknown[] {
+    const blocks: unknown[] = []
+    for (const piece of content)
+        if (piece.type === 'image')
+            blocks.push({
+                type: 'image',
+                source: {
+                    type: 'base64',
+                    media_type: piece.mimeType,
+                    data: piece.data,
+                },
+            })
+        else if (/\S/.test(piece.text))
+            blocks.push({ type: 'text', text: piece.text })
+    return blocks
+}
+
+/** The words of `content`, its images left out. */
+export function textOf(content: AssistantContent[]): string {
+    let text = ''
+    for (const piece of content) if (piece.type === 'text') text += piece.text
+    return text
+}

package/src/server/claudeApi.ts

@@ -8,7 +8,7 @@
 
 import { framedStream } from '#shared/framing.ts'
 import { refuse } from '#shared/refuse.ts'
-import type { AssistantEvent, Provider } from './assistant.ts'
+import { blocksOf, type Provider, textOf } from './assistant.ts'
 
 /** A Messages API request body, less what abide writes, with the client's key and origin. */
 export type ClaudeApiConfig = {
@@ -80,8 +80,12 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                     input_schema: tool.inputSchema,
                 })
             const history: { role: string; content: unknown }[] = []
+            // 44.38 — each image in its place in its turn.
             for (const message of messages)
-                history.push({ role: message.role, content: message.content })
+                history.push({
+                    role: message.role,
+                    content: blocksOf(message.content),
+                })
             const usage = { input: 0, output: 0 }
             for (let turn = 1; ; turn++) {
                 const answered = await fetch(
@@ -189,28 +193,29 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                     }
                     return
                 }
-                const results = await Promise.all(
-                    called.map(
-                        async (
-                            block,
-                        ): Promise<AssistantEvent & { type: 'result' }> => ({
-                            type: 'result',
-                            id: block.id as string,
-                            ...(await tools.call(
-                                block.name as string,
-                                block.input,
-                            )),
-                        }),
-                    ),
+                const answers = await Promise.all(
+                    called.map(async (block) => ({
+                        id: block.id as string,
+                        ...(await tools.call(
+                            block.name as string,
+                            block.input,
+                        )),
+                    })),
                 )
                 const content: unknown[] = []
-                for (const result of results) {
-                    yield result
+                for (const answer of answers) {
+                    // 44.35 — the event carries the answer's words; an image goes to the model alone.
+                    yield {
+                        type: 'result',
+                        id: answer.id,
+                        text: textOf(answer.content),
+                        failed: answer.failed,
+                    }
                     content.push({
                         type: 'tool_result',
-                        tool_use_id: result.id,
-                        content: result.text,
-                        is_error: result.failed,
+                        tool_use_id: answer.id,
+                        content: blocksOf(answer.content),
+                        is_error: answer.failed,
                     })
                 }
                 // 44.12 — every result of one turn in one message.

package/src/server/claudeCode.ts

@@ -11,8 +11,10 @@
 import { mounted } from '#shared/mount.ts'
 import { refuse } from '#shared/refuse.ts'
 import {
+    type AssistantContent,
     type AssistantEvent,
     type AssistantMessage,
+    blocksOf,
     forwardOf,
     type Provider,
 } from './assistant.ts'
@@ -65,7 +67,7 @@ function claudeCodeProvider(config: ClaudeCodeConfig = {}): Provider {
             bridge.frames.push({
                 type: 'turn',
                 id: turn.id,
-                prompt: foldedPrompt(messages),
+                prompt: foldedContent(messages),
                 config,
                 maxTurns,
             })
@@ -105,16 +107,34 @@ function claudeCodeProvider(config: ClaudeCodeConfig = {}): Provider {
     }
 }
 
-/** The transcript as the one message Claude Code is sent: earlier turns folded above the last. 44.5. */
-function foldedPrompt(messages: AssistantMessage[]): string {
-    const last = (messages.at(-1) as AssistantMessage).content
-    if (messages.length === 1) return last
-    let earlier = ''
-    for (let index = 0; index < messages.length - 1; index++) {
-        const message = messages[index] as AssistantMessage
-        earlier += `<${message.role}>\n${message.content}\n</${message.role}>\n`
+/**
+ * The transcript as the one message Claude Code is sent, as Messages API blocks: earlier turns folded
+ * above the last, and each image in its place. 44.5.
+ */
+function foldedContent(
+    messages: (AssistantMessage & { content: AssistantContent[] })[],
+): unknown[] {
+    const pieces: AssistantContent[] = []
+    let words = messages.length > 1 ? '<conversation>\n' : ''
+    const last = messages.length - 1
+    for (let index = 0; index <= last; index++) {
+        const message = messages[index] as (typeof messages)[number]
+        if (index < last) words += `<${message.role}>\n`
+        for (let at = 0; at < message.content.length; at++) {
+            const piece = message.content[at] as AssistantContent
+            if (at > 0) words += '\n'
+            if (piece.type === 'text') {
+                words += piece.text
+                continue
+            }
+            pieces.push({ type: 'text', text: words }, piece)
+            words = ''
+        }
+        if (index < last) words += `\n</${message.role}>\n`
+        if (index === last - 1) words += '</conversation>\n\n'
     }
-    return `<conversation>\n${earlier}</conversation>\n\n${last}`
+    pieces.push({ type: 'text', text: words })
+    return blocksOf(pieces)
 }
 
 /** The browser asking, which a pairing is to. 44.13. */

package/src/server/generatedSurfaces.ts

@@ -14,6 +14,7 @@
 // schema (19.9) as `argsDocument`.
 
 import { isFailed } from '#shared/Failed.ts'
+import { essenceOf } from '#shared/framing.ts'
 import { namedLogger } from '#shared/log.ts'
 import { mounted } from '#shared/mount.ts'
 import { type Reactive, reactive } from '#shared/reactive/index.ts'
@@ -21,9 +22,10 @@ import { parseRoutePattern } from '#shared/routePattern.ts'
 import { argsInURL, rpcRequest } from '#shared/rpcRequest.ts'
 import { answered } from './answerFailure.ts'
 import { bodyWithin, type Mounted } from './answerRpc.ts'
-import type { ToolDefinition } from './assistant.ts'
+import type { ToolAnswer, ToolDefinition } from './assistant.ts'
 import { appIdentity } from './config.ts'
 import { crossingOrigin, crossingRefusal } from './crossingOrigin.ts'
+import { IMAGE_TYPES } from './IMAGE_TYPES.ts'
 import { MCP_PROTOCOL_VERSION } from './MCP_PROTOCOL_VERSION.ts'
 import { type Listed, surfaceOf } from './surfaceOf.ts'
 
@@ -307,16 +309,12 @@ export class McpSurface {
     }
 
     /** What calling the tool `name` as `asker` answered, a refusal or a missing tool a failed one. */
-    call(
-        name: string,
-        args: unknown,
-        asker: Request,
-    ): Promise<{ text: string; failed: boolean }> {
+    call(name: string, args: unknown, asker: Request): Promise<ToolAnswer> {
         const tool = this.#tool(name)
         if (tool === undefined) {
             logCall(String(name), 404, undefined)
             return Promise.resolve({
-                text: `No tool named ${name}.`,
+                content: [{ type: 'text', text: `No tool named ${name}.` }],
                 failed: true,
             })
         }
@@ -331,7 +329,7 @@ export class McpSurface {
         one: Published,
         args: Record<string, unknown> | undefined,
         asker: Request,
-    ): Promise<{ text: string; failed: boolean }> {
+    ): Promise<ToolAnswer> {
         // 28.7 — a closed namespace does not pay for the line it would have written.
         const started = MCP_LOG.enabled() ? performance.now() : undefined
         let answer: Response
@@ -345,10 +343,41 @@ export class McpSurface {
             }
             answer = answered(thrown)
         }
+        const mimeType = essenceOf(answer.headers.get('content-type'))
+        if (answer.status < 400 && mimeType.startsWith('image/')) {
+            // 20.22 — a tool that promised a value and answered a picture has no structured content
+            // to carry: its handler's type is wrong, and the call says so where it happened.
+            if (structured(one)) {
+                await answer.body?.cancel()
+                logCall(one.name, 500, started)
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${one.name} declares a result schema but answered an image, ${mimeType}.`,
+                        },
+                    ],
+                    failed: true,
+                }
+            }
+            // 20.21 — AN IMAGE A MODEL IS SHOWN IS THE IMAGE, handed on as one rather than its bytes
+            // read as text, so a model looks at what a handler drew. Any other (an svg) is its text.
+            if (IMAGE_TYPES.has(mimeType)) {
+                const data = (await answer.bytes()).toBase64()
+                logCall(one.name, answer.status, started)
+                return {
+                    content: [{ type: 'image', data, mimeType }],
+                    failed: false,
+                }
+            }
+        }
         // The body is the call's too: a handler that streams has only begun when its head arrives.
         const text = await answer.text()
         logCall(one.name, answer.status, started)
-        return { text, failed: answer.status >= 400 }
+        return {
+            content: [{ type: 'text', text }],
+            failed: answer.status >= 400,
+        }
     }
 
     /** One MCP request, made as `asker`, as JSON-RPC's `result` or `error`. */
@@ -379,20 +408,25 @@ export class McpSurface {
                         `No tool named ${String(params?.name)}.`,
                     )
                 }
-                const { text, failed } = await this.#called(
+                const { content, failed } = await this.#called(
                     tool,
                     params?.arguments as Record<string, unknown> | undefined,
                     asker,
                 )
+                const [piece] = content
                 return {
                     result: {
-                        content: [{ type: 'text', text }],
+                        // 20.21 — an AssistantContent piece is already an MCP content item.
+                        content,
                         // 20.16 — the same value as structured content, where the tool declares
-                        // its shape; a refusal is not that value.
+                        // its shape; a refusal is not that value. A tool declaring one answers no
+                        // image (20.22), so its one piece is its text.
                         structuredContent:
-                            failed || !structured(tool)
+                            failed ||
+                            !structured(tool) ||
+                            piece?.type !== 'text'
                                 ? undefined
-                                : JSON.parse(text),
+                                : JSON.parse(piece.text),
                         isError: failed,
                     },
                 }

package/src/server/index.ts

@@ -27,11 +27,13 @@ export {
 } from '#shared/rpc.ts'
 // 45 — a conversation with a model, piped through a handler, and the two providers abide ships.
 export {
+    type AssistantContent,
     type AssistantEvent,
     type AssistantMessage,
     type AssistantOptions,
     assistant,
     type Provider,
+    type ToolAnswer,
     type Toolbox,
     type ToolDefinition,
 } from './assistant.ts'

package/src/shared/REACHED_MESSAGE.ts

@@ -0,0 +1,7 @@
+/**
+ * The key of the message the router posts the offline worker, naming the address a navigation
+ * reached, which the worker then keeps (45.24).
+ *
+ * A leaf, because the server writes it into the worker's script and the router posts it.
+ */
+export const REACHED_MESSAGE = 'reached'

package/src/shared/framing.ts

@@ -33,11 +33,19 @@ export function framingOf(type: string | null | undefined): Framed | null {
 export function carriesBytes(type: string | null | undefined): boolean {
     if (type === null || type === undefined || type === '') return false
     if (framingOf(type) !== null) return false
-    const semicolon = type.indexOf(';')
-    const essence = semicolon === -1 ? type : type.slice(0, semicolon)
+    const essence = essenceOf(type)
     return essence !== 'application/json' && !essence.endsWith('+json')
 }
 
+/** A content type less its parameters, folded to lower case, as a type is compared; `''` for none. */
+export function essenceOf(type: string | null | undefined): string {
+    if (type === null || type === undefined) return ''
+    const semicolon = type.indexOf(';')
+    return (semicolon === -1 ? type : type.slice(0, semicolon))
+        .trim()
+        .toLowerCase()
+}
+
 /** One frame: an sse event's name — `message` where it named none — `id` and `data`, or a jsonl line. */
 export type Frame = { name: string; id: string | undefined; data: string }
 

package/src/ui/Router.ts

@@ -5,6 +5,7 @@ import { firstMatch, type Params, partsOf } from '#shared/matchRoute.ts'
 import { unmounted } from '#shared/mount.ts'
 import { NAVIGATION_HEADER } from '#shared/NAVIGATION_HEADER.ts'
 import { OFFLINE_SAVED } from '#shared/OFFLINE_CACHES.ts'
+import { REACHED_MESSAGE } from '#shared/REACHED_MESSAGE.ts'
 import type { ShareScope } from '#shared/reactive/share.ts'
 import { arrive, route } from '#shared/route.ts'
 import { rankRoutes, type Segment } from '#shared/routePattern.ts'
@@ -400,14 +401,18 @@ export class Router {
      */
     private writeAddress(target: URL, replace: boolean, left: Scroll): void {
         const full = `${target.pathname}${target.search}${target.hash}`
-        if (replace) {
-            history.replaceState(entryAt(this.index, null), '', full)
-            return
+        // A step to a fragment, or to the address standing, reaches no page the worker lacks.
+        const moved =
+            target.pathname !== location.pathname ||
+            target.search !== location.search
+        if (replace) history.replaceState(entryAt(this.index, null), '', full)
+        else {
+            this.remember(left)
+            this.index += 1
+            this.scrolls.length = this.index
+            history.pushState(entryAt(this.index, null), '', full)
         }
-        this.remember(left)
-        this.index += 1
-        this.scrolls.length = this.index
-        history.pushState(entryAt(this.index, null), '', full)
+        if (moved) reached(target)
     }
 
     /**
@@ -720,6 +725,22 @@ async function savedOffline(target: URL): Promise<boolean> {
     return saved !== undefined
 }
 
+/**
+ * Tells the service worker an address a navigation reached, for it to keep (45.24).
+ *
+ * POSTED AS THE ADDRESS IS WRITTEN, rather than heard from 30.15's ask: a step within the standing
+ * route asks nothing, the ask's redirect lands elsewhere than it asked, and a superseded one writes
+ * no address.
+ */
+function reached(at: URL): void {
+    const controller = navigator.serviceWorker?.controller
+    if (controller == null) return
+    // A page is kept by its address, which a fragment is no part of.
+    const address = new URL(at)
+    address.hash = ''
+    controller.postMessage({ [REACHED_MESSAGE]: address.href })
+}
+
 /**
  * Asks the server's `middleware` about an address; `undefined` where the fetch failed.
  *

package/src/ui/bindFiles.ts

@@ -0,0 +1,42 @@
+import { boundValue, writeBound } from '#shared/boundValue.ts'
+import type { Scope } from './Scope.ts'
+
+/**
+ * Keeps a file input's files in step with a `bind:files` value, both ways.
+ *
+ * 32.73 — A FILE INPUT'S FILES ARE A LIST, with or without `multiple`, and no markup: the server has
+ * none to write. A `FileList` cannot be built, so a list written in is handed over through a
+ * `DataTransfer`, and an empty one clears the input through `value`, the one write it takes.
+ */
+export function bindFiles(
+    element: Element,
+    operand: unknown,
+    scope: Scope,
+): void {
+    const bound = element as HTMLInputElement
+    scope.watch(() => {
+        const files = (boundValue(operand) ?? []) as readonly File[]
+        if (holdsFiles(bound.files, files)) return
+        if (files.length === 0) {
+            bound.value = ''
+            return
+        }
+        const transfer = new DataTransfer()
+        for (const file of files) transfer.items.add(file)
+        bound.files = transfer.files
+    })
+    bound.addEventListener('change', () => {
+        const picked: File[] = []
+        for (const file of bound.files ?? []) picked.push(file)
+        writeBound(operand, picked)
+    })
+}
+
+/** Whether an input already holds `files`, the same files in the same order. */
+function holdsFiles(held: FileList | null, files: readonly File[]): boolean {
+    const count = held?.length ?? 0
+    if (count !== files.length) return false
+    for (let index = 0; index < count; index++)
+        if ((held as FileList)[index] !== files[index]) return false
+    return true
+}

package/src/ui/index.ts

@@ -40,6 +40,7 @@ export {
     textHere,
 } from './adoptWalk.ts'
 export { bindElement } from './bindElement.ts'
+export { bindFiles } from './bindFiles.ts'
 export { bindGroup } from './bindGroup.ts'
 export { bindProperty } from './bindProperty.ts'
 export { bindSpread } from './bindSpread.ts'