@terreno/mcp 57.9.0 → 57.10.1

package/src/docs/versioned/next/reference/blocks.md

@@ -0,0 +1,178 @@
+# UI blocks
+
+`@terreno/blocks` checks the YAML (or JSON) document an agent uses when a chat reply is
+components instead of prose. Ask schemas are in [Agent UI Asks](agent-ui-asks.md). Validate a
+file locally with [the blocks how-to](../how-to/agent-ui-blocks.md).
+
+## Document
+
+A reply is one mapping. Keys, when present, are in this order: `v`, `datasets`, `blocks`.
+
+```yaml
+v: 1
+blocks:
+  - type: text
+    markdown: I could not find any signups for that range.
+```
+
+`parseBlocks` strips one surrounding ` ```yaml ` fence, parses YAML 1.2 core schema or JSON,
+and rejects anchors, aliases, and explicit tags (`YAML_FEATURE_DISALLOWED`). A value that is
+not a mapping with `v` is `NOT_A_DOCUMENT`. Callers display that reply with
+`wrapAsTextDocument`, which builds `{v: 1, blocks: [{type: text, markdown}]}`.
+
+## Datasets
+
+A dataset name matches `^[a-z][a-z0-9_]{0,63}$`. A document has at most 8 datasets.
+
+| Source | Fields | Rule |
+| --- | --- | --- |
+| inline | `columns`: `{name, type}` where `type` is `string`, `number`, or `date`; `rows`: arrays | At most 500 rows and 12 columns. Each row has one value per column. `source: inline` is optional. |
+| ref | `source: ref`, `id`, optional `grain` (`hour`, `day`, `week`, `month`), optional `limit` | `limit` above 1,000 is `TOO_MANY_POINTS`. Set `grain` to a coarser bucket. Column checks run when `knownDatasets` is passed. |
+
+## Charts and tables
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `chart` | `kind`: `line`, `bar`, `area`, `donut`, and either `data` + `x` + `y` or `points` (`{label, value}`) | `id`, `title`, `legend`, `emptyText`, `height`: `sm`, `md`, `lg` |
+| `table` | `data` (dataset name) | `id`, `columns` (names), `title` |
+
+`x` is a string or date column. `y` is a number column. A table lists at most 12 columns.
+
+## HTML
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `html` | `html` (at most 100,000 bytes) | `id`, `title`, `height`: `sm`, `md`, `lg` |
+
+`validateBlocks` returns `HTML_DISABLED` unless `options.allowHtml` is true. A host turns that on with `uiBlocks.html`. The server sanitizes the HTML before it is stored. The client renders it only when `allowHtml` is set.
+
+## Callout, image, and details
+
+| Block | Required | Optional |
+| --- | --- | --- |
+| `callout` | `text` | `id`, `status`: `info`, `warning`, `alert` |
+| `image` | `alt`, `src` | `id` |
+| `details` | `title`, `text` | `id` |
+
+`src` is a `data:image` URL, a `file:` ref (`file:` plus an id), or an `https` URL. `https` is allowed only when the hostname is in `validateBlocks` `imageHosts` (the server option is `uiBlocks.imageHosts`). Anything else is `IMAGE_HOST_NOT_ALLOWED`. An empty list rejects every `https` image. A ref dataset `id` uses 1–80 letters, digits, underscores, or hyphens. A block or action-element `id` stays lowercase and starts with a letter. `limit` of `0` is `INVALID_TYPE` (an integer of at least 1), not `TOO_SHORT`.
+
+Warnings do not block rendering:
+
+| Code | When |
+| --- | --- |
+| `BAR_TOO_MANY_CATEGORIES` | A bar chart would draw more than 60 categories. |
+| `DONUT_TOO_MANY_SLICES` | A donut chart would draw more than 8 slices. |
+| `LINE_SINGLE_POINT` | A line chart has one point. |
+
+## Blocks
+
+| Block | Required | Optional | Renders as |
+| --- | --- | --- | --- |
+| `heading` | `text` (1–200) | `size`: `sm`, `md`, `lg`, `xl`, `2xl`; `id` | `Heading` |
+| `text` | `markdown` (1–4,000) | `id` | `MarkdownView` |
+| `metric` | `label` (1–80), `value` (1–80) | `delta` (1–40), `trend`: `up`, `down`, `flat`, `helper` (1–120), `id` | `Card` |
+| `badge` | `text` (1–80) | `status`: `info`, `error`, `warning`, `success`, `neutral`, `active`; `id` | `Badge` |
+| `divider` | — | `id` | `SectionDivider` |
+| `context` | `text` (1–280) | `id` | `Text` |
+| `columns` | `children`: 2–4 blocks | `id` | `Box` row |
+| `card` | `children`: at least 1 block | `title` (1–120), `id` | `Card` |
+
+`columns` and `card` sit at the top level. Their children are leaf blocks. A layout block
+inside another layout block is `DEPTH_EXCEEDED`. Every block counts toward the 50-block
+cap, including the `card` or `columns` block itself, so a card cannot hold 50 children.
+
+`id` matches `^[a-z][a-z0-9_]{0,63}$`.
+
+## Actions
+
+An `actions` block requires `id` and `elements` (1–25). An element is a `button` or a
+`segmented` control.
+
+| Element | Required | Optional |
+| --- | --- | --- |
+| `button` | `id`, `text` (1–80), `action` | `variant`: `primary`, `secondary`, `outline`, `ghost`, `destructive`; `iconName` |
+| `segmented` | `id`, `target` (a chart or table `id`), `options` (2–8 of `{label, data}`) | — |
+
+`action.kind` is `reply` (`text`), `open` (`url` or `route`, exactly one), `select`
+(`target` plus `data`), or `callback` (`name` plus optional `payload`). A `select` target
+that is not a chart or table `id` is `SELECT_TARGET_INVALID`. When `validateBlocks` is
+called with `hostActions`, a callback `name` outside that list is `UNKNOWN_HOST_ACTION`.
+Omitting `hostActions` skips that check.
+
+## Partial parsing
+
+`parseBlocksPartial(text)` never throws. A document that `validateBlocks` accepts returns
+`{datasets, blocks, pending: false}`. A cut reply returns only the top-level blocks whose
+next `- ` already arrived, drops the unfinished tail, and sets `pending: true`. `datasets`
+is present only after the `blocks:` key has started and the prefix parses.
+
+## CLI
+
+`terreno-blocks validate <file | ->` prints each problem as `path  CODE  message — fix` and
+exits 1. A valid document exits 0. Warnings are printed and still exit 0.
+
+Unknown fields fail with `UNKNOWN_KEY`. `v` must be `1` (`UNSUPPORTED_VERSION`).
+
+## Limits
+
+| Limit | Value |
+| --- | --- |
+| Blocks in one document, including nested blocks | 50 |
+| Nesting | 2 (`blocks` → `columns` or `card` → leaf) |
+| `columns` children | 2–4 |
+| Elements in one `actions` block | 25 |
+| Text in one `text` block | 4,000 characters |
+| Document version | 1 |
+
+## Errors
+
+`validateBlocks` returns `{ok: true, doc, warnings}` or `{ok: false, errors, warnings}`.
+Each error is `{path, code, message, fix}`, sorted by path. `warnings` lists chart
+heuristics and does not fail `ok`.
+
+| Code | Meaning |
+| --- | --- |
+| `COLUMN_NOT_FOUND` | A chart or table names a column the dataset does not have. |
+| `COLUMN_TYPE_MISMATCH` | A column value, or a chart axis, does not match the column type. |
+| `DATASET_NOT_FOUND` | A chart or table names a dataset the document does not define. |
+| `DATASET_TOO_LARGE` | A dataset has more than 500 rows or 12 columns. |
+| `DEPTH_EXCEEDED` | A `columns` or `card` block is nested inside another layout block. |
+| `DUPLICATE_ID` | A block id, an action-element id, or a column name is used more than once. |
+| `HTML_DISABLED` | An html block is present and this host has not turned HTML on. |
+| `HTML_TOO_LARGE` | An html block is larger than 100,000 bytes. |
+| `IMAGE_HOST_NOT_ALLOWED` | An image URL is not a `data:image` URL, a `file:` ref, or an `https` URL on an allowed host. |
+| `INVALID_ENUM` | A value is not one of the allowed values. |
+| `INVALID_FORMAT` | A string does not match its required format. |
+| `INVALID_TYPE` | A value has the wrong type, including a numeric field below its minimum. |
+| `KEY_ORDER` | Top-level keys are not in the order `v`, `datasets`, `blocks`. |
+| `MISSING_REQUIRED` | A required field is missing. |
+| `NOT_A_DOCUMENT` | The reply is not one YAML or JSON mapping with a `v` field. |
+| `SELECT_TARGET_INVALID` | A select action names a block that is not a chart or table. |
+| `ROW_ARITY_MISMATCH` | A dataset row does not have one value per column. |
+| `TABLE_TOO_WIDE` | A table lists more than 12 columns. |
+| `TOO_FEW` | A list has fewer items than allowed. |
+| `TOO_LONG` | A string is longer than allowed. |
+| `TOO_MANY` | A list has more items than allowed. |
+| `TOO_MANY_BLOCKS` | The document has more than 50 blocks. |
+| `TOO_MANY_POINTS` | A ref dataset `limit` is above 1,000. |
+| `TOO_SHORT` | A string is empty or only whitespace. |
+| `UNKNOWN_HOST_ACTION` | A callback names a host action that is not registered. |
+| `UNKNOWN_KEY` | An object has a field that its schema does not define. |
+| `UNSUPPORTED_VERSION` | `v` is not 1. |
+| `YAML_FEATURE_DISALLOWED` | The document uses a YAML anchor, alias, or explicit tag. |
+
+## Exports
+
+| Export | Role |
+| --- | --- |
+| `parseBlocks(text)` | Fence strip, YAML or JSON parse |
+| `parseBlocksPartial(text)` | Completed top-level blocks while a reply is still streaming |
+| `validateBlocks(doc, options?)` | Structure, then dataset, chart, table, action, and html lint. `options.knownDatasets` checks `ref` columns. `options.hostActions` checks callback names. `options.allowHtml` allows `html` blocks. |
+| `wrapAsTextDocument(text)` | Display fallback for a non-document |
+| `blocksSchema` | Zod schema |
+| `blocksJsonSchema` | JSON Schema for the same structure |
+| `blocksPromptSection({hostActions, allowHtml})` | System-prompt section. Limits come from `BLOCK_LIMITS`. `allowHtml` adds the `html` block. |
+| `BLOCK_LIMITS` | The numbers in the table above |
+| `BLOCK_ERROR_CODES` | The codes in the table above |
+| `BLOCK_WARNING_CODES` | `BAR_TOO_MANY_CATEGORIES`, `DONUT_TOO_MANY_SLICES`, `LINE_SINGLE_POINT` |
+| `HTML_HEIGHTS`, `CALLOUT_STATUSES` | Allowed `html` heights and `callout` statuses. `HtmlBlock`, `CalloutBlock`, `ImageBlock`, and `DetailsBlock` are type exports. |

package/src/docs/versioned/next/reference/environment-variables.md

@@ -23,6 +23,7 @@ Comprehensive guide to environment variables used across Terreno packages and ex
 | `TERRENO_TEST_MONGODB_URI` | `@terreno/test` | ❌ | auto | Yes | tooling |
 | `TERRENO_TEST_USE_MEMORY_MONGO` | `@terreno/test` | ❌ | — | No | tooling |
 | `TERRENO_TEST_USE_REPLSET` | `@terreno/test` | ❌ | — | No | tooling |
+| `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | `@terreno/test` | ❌ | `60000` | No | tooling |
 | `TERRENO_TEST_USE_FIXTURE_CACHE` | `@terreno/test` | ❌ | — | No | tooling |
 | `TERRENO_TEST_CACHE_DIR` | `@terreno/test` | ❌ | — | No | tooling |
 | `BUN_TEST_DISABLE_DB` | test harness | ❌ | — | No | tooling |

package/src/docs/versioned/next/reference/mcp-server.md

@@ -391,6 +391,23 @@ Validate a Mongoose schema against Terreno conventions.
 - Recommendations for fixes
 - Severity levels (error, warning, info)
 
+### terreno_validate_ui_blocks
+
+Check one whole-reply YAML or JSON document. The text is the same report `terreno-blocks validate` prints: each problem is `path  CODE  message — fix`. A valid document with no warnings returns an empty string.
+
+**Parameters:**
+
+``````typescript
+{
+  document: string; // Required — the YAML or JSON document
+}
+``````
+
+**Returns:**
+
+- The CLI report, including a trailing newline when there is at least one line
+- An empty string when the document is valid and has no warnings
+
 ### terreno_bootstrap_ai_rules
 
 Scaffold AI coding assistant rules (AGENTS.md, Cursor/Windsurf rules, Copilot instructions, rulesync config).

package/src/docs/versioned/next/reference/test.md

@@ -79,10 +79,14 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 |----------|--------|
 | `TERRENO_TEST_USE_MEMORY_MONGO` | When `"true"`, `registerSimpleMongoPreload` starts `mongodb-memory-server` if `TERRENO_TEST_MONGODB_URI` is unset. |
 | `TERRENO_TEST_MONGODB_URI` | External MongoDB URI. Takes priority over in-memory server in `startMongoServer` and `registerSimpleMongoPreload`. |
+| `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` | Per-mongod start timeout for in-memory servers started by `startMongoServer`. Default `60000` (mongodb-memory-server's own default is 10s). Startup is tried twice. |
 | `BUN_TEST_DISABLE_DB` | When `"true"`, `registerBackendPreload` skips all Mongo `beforeAll`/`afterAll` hooks (no DB startup). |
 
 `startMongoServer` also publishes the resolved URI to `TERRENO_TEST_MONGO_URI` and honors `TERRENO_TEST_USE_REPLSET=true` for replica-set memory servers.
 
+If `registerBackendPreload` cannot start Mongo, every later test fails at once with
+`MongoDB test server failed to start` instead of waiting on mongoose command buffering.
+
 ## Exported helpers
 
 | Export | Description |
@@ -92,6 +96,7 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 | `setTerrenoTestEnv` | Apply and validate auth test env vars. |
 | `startMongoServer` / `stopMongoServer` | Start or stop shared in-memory Mongo and connect mongoose. |
 | `getMongoServerUri` | Resolved URI after `startMongoServer`. |
+| `resolveMongoLaunchTimeoutMs` | In-memory mongod launch timeout from `TERRENO_TEST_MONGO_LAUNCH_TIMEOUT_MS` (integer ≥ 1000), default 60000. |
 | `getBaseServer` | Build an Express app for supertest from route registrars. |
 | `authAsUser` | Login helper returning auth headers for supertest. |
 | `createMongoTestCache` | Fixture-cache controller for fast `@terreno/api` tests. |
@@ -112,8 +117,12 @@ Defaults: `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, `SESSION_SECRE
 Package CI uses `scripts/check-coverage.ts` (`bun run test:coverage`, default 95%
 functions and lines) as the live gate. Bun 1.4.2+ may exit 1 on bunfig
 `coverageThreshold` before isolated LCOV merges; the script continues when tests
-reported `0 fail` and then enforces 95% on the merged report. Dedicated CircleCI
-jobs (`api-ci`, `ai-ci`,
+reported `0 fail` and then enforces 95% on the merged report. The blocks
+coverage pass sets `--max-concurrency=1`, because Bun's default 20-way run
+exits 0 on a 2-vCPU worker before it prints the `All files` row. When that
+row is still missing after one retry, the script uses `coverage/lcov.info`
+only if it lists every non-test source file under `src/`. Dedicated CircleCI
+jobs (`api-ci`, `ai-ci`, `blocks-ci`,
 `rtk-ci`, `ui-ci`, `syncdb-ci`, `comms-ci`, `mcp-server-ci`, `admin-spa-ci`) run
 that script. Published packages without a dedicated workflow
 (`admin-backend`, `admin-frontend`, `api-health`, `feature-flags`, `@terreno/test`)

package/src/docs/versioned/next/reference/ui.md

@@ -10,6 +10,7 @@ React Native UI component library (a large component library). Layout (Box, Page
 - Actions: `Button`, `IconButton`, `Link`
 - Feedback: `Spinner`, `Modal`, `Toast`
 - Notifications: `NotificationBell`, `NotificationInbox`, `NotificationPreferences`
+- AI chat: `GPTChat`, `AskCard` (agent asks in the transcript), `SimpleAskCard` (an ask's simple card for narrow layouts), `BlocksView` (a whole-reply YAML document)
 - Authentication: `SocialLoginButton`, `LoginScreen`, `SignUpScreen`
 - Theming: `TerrenoProvider`, `useTheme`, custom icon registry (`icons` prop)
 - **Type re-exports:** `StyleProp`, `ViewStyle` (re-exported from react-native to avoid version conflicts)
@@ -32,7 +33,7 @@ supported and is convenient when startup cost is not material:
 import {Box, DataTable, Icon} from "@terreno/ui";
 ```
 
-Heavy optional widgets (`GPTChat`, `EmojiSelector`, `MarkdownEditor`, consent flows, `ChartCard`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
+Heavy optional widgets (`GPTChat`, `AskCard`, `BlocksView`, `EmojiSelector`, `MarkdownEditor`, consent flows, `ChartCard`, `Scorecard`, `SparklineChart`, `LineChart`, `BarChart`, `AreaChart`, `DonutChart`, and related admin tools) are
 re-exported from the root entry through lazy boundaries. Importing them from `@terreno/ui` stays type-compatible, but
 their implementation modules load on first render instead of during the initial root import. `DashboardGrid` stays eager.
 `MarkdownView` and `DataTable` header info defer `react-native-markdown-display`;
@@ -250,6 +251,18 @@ Buttons automatically size to their content unless `fullWidth` is specified:
 
 Internally, Button sets `alignSelf: 'flex-start'` when `fullWidth={false}` to prevent stretching in column layouts.
 
+A label stays on one line by default, so a long label can make the button wider than its container.
+Set `wrapText` to keep the button inside its container instead: the label wraps onto centered lines
+and the button grows taller. A `size="sm"` button grows from its 28px height instead of clipping the
+second line. `SimpleAskCard` and `AskCard` set `wrapText` on their answer buttons, because their
+labels come from the agent.
+
+```tsx
+<Box direction="row" width={160}>
+  <Button onClick={handleSave} text="Save all changes now" wrapText />
+</Box>
+```
+
 ### TextField grow and maxHeight
 
 `grow` makes a multiline field expand with its content. Pair it with `maxHeight` (pixels) to cap the expansion; past the cap the content scrolls.
@@ -390,10 +403,321 @@ The attach control (`FilePickerButton`) opens an anchored dropdown with **Photo
 />
 ```
 
+Pass `uiBlocks` to render each assistant message through `BlocksView`. A streaming message
+shows each finished top-level block and a spinner for the block still arriving. `reply`
+calls `onSubmit` with the button text. `open` and `select` call `onBlockAction`. `callback`
+calls `onBlockCallback` and the button stays loading until that promise settles. Return
+`{replace: "block", blocks}` to swap that block, or `{text}` to place an assistant message
+immediately after the message that started the callback. A result that arrives after
+`currentHistoryId` changes is dropped. `hostActions` disables callback names the host did
+not list. `resolveDataset` loads `ref` datasets. `resolveImage` turns a `file:` image id
+into a URL.
+
+```tsx
+<GPTChat
+  currentMessages={messages}
+  histories={histories}
+  hostActions={["export_csv"]}
+  onBlockAction={handleBlockAction}
+  onBlockCallback={handleBlockCallback}
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+  uiBlocks
+/>
+```
+
 Operator steps: [Add a GPT chat mascot](../how-to/add-gpt-chat-mascot.md). Demo story: `GPTChat` → `Mascot`.
+Blocks playground: `BlocksPlayground`.
 The example AI screen demonstrates a consumer selecting one of four bundled mascot
 images once per mount.
 
+#### Asks
+
+`GPTChat` shows an [agent ask](agent-ui-asks.md) as an `AskCard` in the transcript. Set `ask` on
+the ask's `tool-call` message and pass `onAskSubmit`:
+
+```tsx
+<GPTChat
+  askErrors={askErrors}
+  currentMessages={currentMessages}
+  histories={histories}
+  onAskSubmit={handleAskSubmit}
+  onCreateHistory={onCreateHistory}
+  onDeleteHistory={onDeleteHistory}
+  onSelectHistory={onSelectHistory}
+  onSubmit={onSubmit}
+/>
+```
+
+| Prop or field | Type | Description |
+| --- | --- | --- |
+| `GPTChatMessage.ask` | `ChatAsk` | On a `tool-call` message: the ask (`kind`, `input`), its `toolCallId`, `status` (`pending`, `answered`, or `cancelled`), and optional `response` and `simple` card. The chat shows an `AskCard` instead of the tool call. |
+| `onAskSubmit` | `(submission: {toolCallId, response}) => void \| Promise<void>` | Called when the user answers a pending ask. `response` is the answer envelope. The pressed control shows a loading state until the promise settles. Without it, asks show but cannot be answered. |
+| `askErrors` | `Record<string, AskValidationError[]>` | Errors for the last answer to each ask, keyed by tool call id, such as the `fields` of a 400 `Invalid askResponse`. Shown inside the card. |
+| `resolveAskFiles` | `AskFilesResolver` | Turns the files picked for a `files` ask into the refs its answer sends. Defaults to `resolveAskFilesAsDataUrls`. Pass an uploader to send `{fileId}` refs; see [Accept uploads with or without GCS](../how-to/agent-ui-asks.md#accept-uploads-with-or-without-gcs). |
+
+- The ask's `tool-result` message stays in `currentMessages` but is not shown. Keep it: message
+  indexes must match the stored `prompts` rows that ratings use. When `ask.response` is unset, the
+  card reads the answer from that message.
+- A pending ask takes focus when it appears: DOM focus on the card, labelled with the ask's
+  `title`, on web; accessibility focus on the question, an accessibility header, on native.
+- Answered and cancelled asks collapse to a one-line summary.
+
+The example AI screen, `example-frontend/app/(tabs)/ai.tsx`, handles the stream events, saved
+rows, answers, and errors. Steps: [Add agent asks to a chat](../how-to/agent-ui-asks.md).
+
+### BlocksView
+
+`BlocksView` paints a whole-reply document from `@terreno/blocks`. Pass the assistant text
+as `document`. Leaf blocks in this slice are `heading`, `text`, `metric`, `badge`,
+`divider`, and `context`. `columns` is a row from the `md` breakpoint and a stack on `sm`.
+`card` groups children under an optional title. A `callout` draws `Banner` and is not dismissible. An `image` draws `Image` and requires `alt`; pass `imageHosts` to allow `https` hosts. A `details` block draws `Accordion`. A `chart` draws `LineChart`, `BarChart`,
+`AreaChart`, or `DonutChart` from an inline dataset or from `points`. The series is only
+`{label, value}` — a point color in the document is not passed through. A `table` draws
+`DataTable`. A `ref` dataset stays empty until `resolveDataset` returns its rows, and the
+chart shows `loading` while that promise is in flight. A rejected fetch clears that
+loading state. A segmented control highlights the option whose `data` matches the target
+chart or table. A `select` action switches a table the same way it switches a chart.
+An image `file:` ref is not passed to `Image` until `resolveImage` returns a URL; the
+alt text still shows.
+
+A string that is not a document becomes one `text` block. A document that fails
+`validateBlocks` shows a `Banner` with the first three errors and the raw text inside a
+collapsed `Accordion`.
+
+An `actions` block draws `Button` and `SegmentedControl`. `onAction` receives
+`{action, blockId, elementId}` for reply, open, select, and callback. A `select`
+action also stores the chosen dataset on the target chart for this view. Pass
+`hostActions` to disable callback buttons whose names are not in that list. Omit
+`hostActions` and every callback stays enabled. `pendingElementIds` shows those
+buttons as loading. `overrides` replaces a block by id.
+
+```tsx
+<BlocksView
+  document={reply}
+  hostActions={["export_csv"]}
+  onAction={handleAction}
+  testID="assistant-blocks"
+/>
+```
+
+Demo story: `BlocksView`.
+
+### HtmlFrame
+
+`HtmlFrame` paints one `html` block. On web it is an `<iframe sandbox="" referrerpolicy="no-referrer">` whose `srcdoc` starts with a Content-Security-Policy meta tag (`default-src 'none'`). On native it is a WebView with JavaScript off, and navigation after the first load is rejected. `BlocksView` renders that frame only when `allowHtml` is true and `streaming` is false. Otherwise the block is a card that says the preview is off or still arriving. `GPTChat` passes `allowHtml` through.
+
+```tsx
+<HtmlFrame height="md" html="<h1>Invoice</h1>" title="Invoice preview" />
+```
+
+### AskCard
+
+One agent ask in a chat transcript: controls while it is pending, a summary line after. `GPTChat`
+renders it for messages with `ask`. Render it directly in a custom transcript. A saved ask whose
+input no longer validates, or whose `accept` answer has no `content` object, shows the generic
+line ("You answered this question.") and no sent values.
+
+```tsx
+<AskCard ask={ask} errors={errors} onSubmit={handleAskSubmit} testID="plan-ask" />
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `ask` | `ChatAsk` | The ask. Pending asks are interactive. Answered and cancelled asks show a summary. |
+| `errors` | `AskValidationError[]` | Errors for the last answer, shown under the controls |
+| `onSubmit` | `AskSubmitHandler` | Called with `{toolCallId, response}`. Without it, the card cannot be answered: buttons and the select are disabled, and radio and checkbox options show as plain text. When the promise it returns rejects, the ask stays open and the card shows "Your answer could not be sent. Try again." until the next answer. |
+| `promptRef` | `React.Ref<Text>` (React Native) | Receives the question's native text, which is an accessibility header. `GPTChat` uses it to move screen reader focus to a pending ask on native. |
+| `resolveAskFiles` | `AskFilesResolver` | For a `files` ask: turns the picked files into refs on Submit. Defaults to data URLs. `GPTChat` passes its own `resolveAskFiles`. |
+| `testID` | string | Defaults to `ask-card`. `GPTChat` passes `gpt-ask-<toolCallId>`. |
+
+A saved ask whose input no longer passes `validateAskInput` shows "This question cannot be shown.
+Send a message to continue." while pending, and "You answered this question." once answered.
+
+`choice` controls:
+
+| Ask | Controls |
+| --- | --- |
+| The simple card has a button for every option (`handoff: false`), and every option label is at most 20 characters | The card's buttons as quick replies, then Skip unless `allowDecline` is `false`. A tap answers. |
+| Up to 8 options | `RadioField`, then Submit (`submitLabel`) and Skip |
+| More than 8 options | Searchable `SelectField`, then Submit and Skip |
+| `select: "many"` | `MultiselectField` with a hint such as "Choose 1 to 3.", then a `TextField` titled `otherLabel` (default "Other") when `allowOther` is `true`, then Submit and Skip |
+
+The selection starts on the ask's `default`. Submit is enabled only when `validateAskResponse`
+accepts the selection. For `select: "many"`, the answer lists the checked ids in option order and
+sends the Other text trimmed, leaving `other` out when the field is blank. When the checked
+options and the Other text add up to more than `maxSelected`, the checkboxes say so ("You chose
+4. Choose at most 3."). An Other text over 500 characters, or a server error at `content.other`,
+shows on the Other field. When `ask.simple` is absent, the card derives it with `toSimpleCard`. An
+ask whose input fails `validateAskInput` shows "This question cannot be shown. Send a message to
+continue." instead of controls.
+
+`confirm` controls: the simple card's two buttons in its order, the approve button (`confirmLabel`,
+default "Confirm") first and the deny button (`denyLabel`, default "Cancel") last. The approve
+button uses the `destructive` variant when the ask sets `destructive: true`, else `primary`; the
+deny button uses `ghost`. Skip follows only when `allowDecline` is `true`. A tap answers
+`{"confirmed": true}` or `{"confirmed": false}`. Without `onSubmit`, both buttons are disabled.
+
+`markdown` controls: a `MarkdownEditorField` (edit and preview, at most 320 pt tall) that starts
+on the ask's `initial` draft and shows `placeholder` while empty, then Submit (`submitLabel`) and
+Skip unless `allowDecline` is `false`. Under the editor a hint gives the length and the bounds,
+such as "1,240 / 2,000 characters. At least 20." Submit is enabled only when
+`validateAskResponse` accepts the text, and it sends `{markdown, changed}` with `changed` true
+when the text differs from `initial`. Text over `maxLength`, or a server error at
+`content.markdown`, shows on the editor. Without `onSubmit`, the editor and both buttons are
+disabled. An answered markdown ask shows the sent text under its summary; text over 280
+characters shows a preview cut at a word, with Show all and Show less.
+
+`form` controls: one field per entry in `fields`, in order, titled with the field's `label`
+("(required)" appended for required fields) and its `helperText`, then Submit (`submitLabel`) and
+Skip unless `allowDecline` is `false`. Each field uses the `@terreno/ui` control for its type:
+
+| Field `type` | Control | Sends |
+| --- | --- | --- |
+| `text`, `email`, `url` | `TextField` (`text`, `email`, `url`) | The trimmed text |
+| `phone` | `TextField` (`phoneNumber`) | E.164, such as `+14155552671`, when the number parses (as a US number without a country code); else the trimmed text |
+| `number` | `TextField` | A number when the text is plain decimal notation; else the text, so validation says why |
+| `textarea` | `TextArea` | The trimmed text |
+| `date` | `DateTimeField` (`date`) | `YYYY-MM-DD` |
+| `time` | `DateTimeField` (`time`) with its time zone picker (the device's zone to start) | 24-hour `HH:mm` as shown; the zone is not sent |
+| `datetime` | `DateTimeField` (`datetime`) with a time zone picker | An ISO datetime with the chosen zone's offset, such as `2026-10-01T09:30:00-07:00` |
+| `boolean` | `BooleanField` | `true` or `false`, always |
+| `select` | `SelectField` | The option id |
+| `multiselect` | `MultiselectField` | The checked option ids |
+
+Fields start on their `default`. Blank fields are left out of `values`. Submit is enabled only
+when `validateAskResponse` accepts the values and no date, time, or datetime field holds an
+unfinished entry. `DateTimeField` reports that through `onEntryStatusChange`, such as
+"0 / 5 / 026": the field says "Enter a complete date, or clear it." until the user finishes it,
+and clearing every part leaves the field out. After the user edits a field, it says what is
+wrong in plain words, such as "Enter a number from 1 to 500." or "This field is required." A
+server error whose path is `content.values.<id>` (or an item under it) shows on that field until
+the user edits it; other errors show under the form. Without `onSubmit`, every field and both
+buttons are disabled. An answered form lists each sent field as its label and a readable value
+(Yes or No, option labels, "Oct 1, 2026", "9:30 AM", text shortened to one line of 80
+characters) under its summary.
+
+`files` controls: a hint built from the counts and types, such as "Up to 3 files: images, PDFs or
+text files.", then a "Choose files" `FilePickerButton` ("Add files" once some are picked), the
+picked files as an `AttachmentPreview` with a remove control on each, then Submit (`submitLabel`,
+default "Submit") and Skip unless `allowDecline` is `false`. The picker offers Photo Library only
+when `accept` has `image`, and its document picker offers only the accepted MIME types. It allows
+several files when `maxFiles` is more than 1 and is disabled once `maxFiles` files are picked.
+Submit is enabled only when `validateAskResponse` accepts the picked names, types, and sizes. On
+Submit, the card calls `resolveAskFiles` with the picked files and sends `{files: refs}`; Submit
+shows a spinner and Skip is disabled until the answer is sent. When the ask ends another way while
+the resolver runs, such as an answer from another tab, its refs are not sent. If the resolver throws, the ask
+stays open and the card shows "The files could not be sent. Try again, or pick them again." Server
+errors, such as `MIME_MISMATCH`, show under the picked files. Each file's type is
+`selectedFileMimeType(file)`, so a CSV a picker reports as `application/vnd.ms-excel` is sent as
+`text/csv`.
+
+| How the ask ended | Summary |
+| --- | --- |
+| `files` `accept` | You sent `<n>` files: `<filenames>`, or You sent 1 file: `<filename>` |
+| `form` `accept` | You sent the form (`<n>` fields) |
+| `markdown` `accept` | You approved the draft as is (`changed: false`), or You edited the draft (`<n>` characters) |
+| `confirm` `accept` | You confirmed: `<confirmLabel>`, or You declined: `<denyLabel>`, with the default labels when the ask sets none |
+| `choice` `accept` | You chose: `<option labels>`. With Other text, it adds "`<otherLabel>`: `<text>`" (the label defaults to "Other"), or shows only that when no option was checked. An empty `select: "many"` answer shows "You chose none of the options." |
+| `decline` | You skipped this question. |
+| `cancel` with `user_sent_message` | Not answered: you sent a message instead. |
+| `cancel` with `one_ask_at_a_time` | Not asked: the assistant asked another question first. |
+| Any other `cancel`, or status `cancelled` without a response | This question was cancelled. |
+| Status `answered` without a response | You answered this question. |
+
+| Element | testID |
+| --- | --- |
+| Card | `{testID}` |
+| Quick reply row | `{testID}-quick-replies` |
+| Quick reply or Skip button | `{testID}-button-<button id>`, such as `{testID}-button-option:team` or `{testID}-button-skip` |
+| Confirm button row | `{testID}-confirm-buttons` |
+| Confirm approve or deny button | `{testID}-button-approve`, `{testID}-button-deny` |
+| Radio options (up to 8) | `{testID}-radio` |
+| Select | `{testID}-select` |
+| Checkboxes (`select: "many"`) | `{testID}-multiselect` |
+| Other text field | `{testID}-other` |
+| Markdown editor, and its text input | `{testID}-editor`, `{testID}-editor-input` |
+| Sent markdown under an answered ask, and its Show all toggle | `{testID}-answer`, `{testID}-answer-toggle` |
+| Form field, and its wrapper | `{testID}-field-<field id>` (a `BooleanField` switch is `{testID}-field-<field id>.switch`), `{testID}-form-field-<field id>` |
+| Sent form values under an answered ask | `{testID}-answer` |
+| Files hint, picker, and picked files | `{testID}-hint`, `{testID}-picker`, `{testID}-selected` |
+| Files that could not be sent | `{testID}-resolve-error` |
+| Radio or checkbox options as plain text, without `onSubmit` | `{testID}-options` |
+| Submit | `{testID}-submit` |
+| Answer errors | `{testID}-errors` |
+| Summary | `{testID}-summary` |
+| Ask that cannot be shown | `{testID}-invalid` |
+| Answer that could not be sent | `{testID}-submit-error` |
+
+Types: `AskCardProps`, `ChatAsk`, `ChatAskState`, `ChatAskStatus`, `AskSubmission`,
+`AskSubmitHandler`, `AskFilesResolver`. Demo story: `AskCard`.
+
+File ref helpers:
+
+| Export | Description |
+| --- | --- |
+| `AskFilesResolver` | `(files: SelectedFile[]) => Promise<AskFileRef[]>`. Throw to keep the ask open. |
+| `resolveAskFilesAsDataUrls` | The default resolver: every file as a `{url}` data URL |
+| `selectedFileToDataUrlRef(file)` | One picked file as `{filename, mimeType, size, url}`. The data URL's media type is `selectedFileMimeType(file)`, and `size` is the decoded byte count. |
+| `selectedFileMimeType(file)` | The picked file's normalized type. When the picker reports none, `application/octet-stream`, or `application/vnd.ms-excel` (Windows reports CSV files so), the type comes from the extension: `.csv`, `.gif`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, `.txt`, `.webp`. Otherwise the reported type is kept. |
+| `normalizeMimeType(mimeType)` | Drops parameters and lowercases: `Text/CSV; charset=utf-8` becomes `text/csv` |
+
+`FilePickerButton` props used by the files card, also available to any caller:
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `documentTypes` | `string[]` | MIME types the document picker offers. Defaults to PDF, text, CSV, and JSON. An empty list hides Document. |
+| `includeImages` | boolean | Offer Photo Library. Defaults to `true`. When `false`, the button opens the document picker directly. |
+| `text` | string | Shows an outline button with this label instead of the paperclip icon |
+
+`SelectedFile.size` is the file's size in bytes when the picker reports it.
+
+### SimpleAskCard
+
+Any agent ask as its [simple card](agent-ui-asks.md#simple-cards): the title, the question, and up
+to three full-width buttons that each send an exact answer. Use it in narrow layouts, such as a
+watch-sized preview. It reads the card's `kind` only to word the handoff line.
+
+```tsx
+const [runTurn] = useGpthistoriesTurnMutation();
+
+<SimpleAskCard
+  card={pendingAsk.simple}
+  onPress={(button) =>
+    runTurn({
+      body: {buttonId: button.id, surface: "compact", toolCallId: pendingAsk.toolCallId},
+      id: historyId,
+    })
+  }
+  pendingButtonId={sendingButtonId}
+/>
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `card` | `SimpleCard` | `pendingAsk.simple` from the server, or `simple` on an `{ask}` event |
+| `onPress` | `(button: SimpleCardButton) => void \| Promise<void>` | Called with the pressed button. Send `{toolCallId: card.toolCallId, buttonId: button.id}` to the history's [`turn` action](agent-ui-asks.md#headless-endpoints), or send `button.response` as the answer. |
+| `pendingButtonId` | string? | The button whose answer is still sending. It shows a spinner, the other buttons are disabled, and presses are ignored. |
+| `testID` | string? | Defaults to `simple-ask-card` |
+
+- A card with `handoff: true` shows "Continue on your phone" under the question, because its
+  buttons cannot give every answer. A `markdown` card shows "Edit on your phone" instead, a
+  `form` card "Fill it in on your phone", and a `files` card "Upload on your phone".
+- Button styles map to `Button` variants the same way as `AskCard` quick replies: `primary` to
+  `primary`, `default` to `outline`, `destructive` to `destructive`, and `cancel` to `ghost`.
+
+| Element | testID |
+| --- | --- |
+| Card | `{testID}` |
+| Continue on your phone, or Edit on your phone | `{testID}-handoff` |
+| Button | `{testID}-button-<button id>`, such as `{testID}-button-option:team` |
+
+Types: `SimpleAskCardProps`, and `SimpleCard` and `SimpleCardButton` from `@terreno/blocks`. Demo
+story: `SimpleAskCard`. Its demo answers a plan card on a watch-sized 198×242 pt screen, and its
+"Every fixture" story draws every valid fixture's card at that size.
+
 ### SplitPage
 
 Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list, and