@terreno/mcp 57.12.0 → 57.14.0

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

@@ -61,6 +61,55 @@ const customStyle: StyleProp<ViewStyle> = {
 - Ensures type compatibility when passing styles to @terreno/ui components
 - Simplifies imports (one package instead of two)
 
+## Theme modes
+
+`TerrenoProvider` defaults to the Flourish Health light mode exported from
+Figma. Select the matching Figma dark mode explicitly or follow the operating
+system:
+
+``````tsx
+import {TerrenoProvider} from "@terreno/ui";
+
+<TerrenoProvider colorScheme="system">
+  <App />
+</TerrenoProvider>
+``````
+
+`colorScheme` accepts `"light"`, `"dark"`, or `"system"` and defaults to
+`"light"` for deterministic server rendering. `"system"` follows the operating
+system. Change the choice after startup with `setColorScheme`:
+
+``````tsx
+import {SelectField, themeColorSchemeOptions, useTheme, type ThemeColorScheme} from "@terreno/ui";
+
+const AppearanceSetting = () => {
+  const {colorSchemeSetting, setColorScheme} = useTheme();
+  return (
+    <SelectField
+      onChange={(value) => {
+        setColorScheme(value as ThemeColorScheme);
+      }}
+      options={themeColorSchemeOptions}
+      title="Appearance"
+      value={colorSchemeSetting}
+    />
+  );
+};
+``````
+
+Dark `surface.warningLight` uses `warning200`. The lighter warning orange, `warning100`, is 2.52:1 against warning text and misses WCAG AA. Highlighted `DataTable` cells switch to `text.inverted` when `text.primary` is below 4.5:1 on that fill. Inverted `MarkdownView` code uses `surface.neutralDark` when `surface.neutralLight` is below 4.5:1 against that text, and blockquotes do the same with `surface.baseAlternate`. Primary `Button` labels use `text.secondaryDark` when that pair meets 4.5:1 on `surface.primary`, and `text.inverted` otherwise, so `setTheme(darkThemeConfig)` stays readable without changing `colorScheme`. The demo palette generator emits status `050` steps so custom palettes update those dark error, success, and warning surfaces.
+
+`themeColorSchemeOptions` labels those values Light, Dark, and Follow system.
+`useTheme()` also returns the resolved `colorScheme` (`"light"` or `"dark"`)
+with `theme`, `setTheme`, `setPrimitives`, and `resetTheme`. An explicit
+`colorScheme` prop replaces the current choice whenever the parent changes it.
+
+The public `lightThemeConfig`, `darkThemeConfig`, and
+`defaultThemePrimitives` exports are the canonical token maps. They include the
+Figma AI surface/border roles and the dark status ramps. Custom overrides set
+through `useTheme()` are layered over the active mode; `resetTheme()` removes
+those overrides without changing the provider's selected mode.
+
 ### DashboardGrid and DashboardGridItem
 
 Eager layout-only wrapping grid. Default columns `{sm: 1, md: 2, lg: 3}`. Children stay caller-supplied `Card`s. Cell width is `(rowWidth - gap × (columns - 1)) / columns` so flex `gap` does not wrap extra columns.
@@ -473,10 +522,17 @@ rows, answers, and errors. Steps: [Add agent asks to a chat](../how-to/agent-ui-
 `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`,
+`card` groups children under an optional title, with an optional small muted `eyebrow` above it (test ID `<card path>-eyebrow`). 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
+`DataTable` and maps each dataset column type to a cell: `number` to a right-aligned
+`number` cell, `date` to a `date` cell (Luxon `DATE_MED`, such as "Mar 14, 2026"), and
+`string` to `text`. A listed column that the dataset does not have yet is `text`. Each header
+is the column name with underscores shown as spaces (`bone_in_lamb` reads "bone in lamb"). The table
+measures its container with `onLayout` and splits the width evenly across its columns, with
+at least 96 per column; past that it scrolls sideways. Before the first layout each column
+is 120 wide. Its height fits the header plus its rows (54 each), up to 10 rows; a longer table
+scrolls inside that height, so it never spills over the next block. 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.
@@ -494,6 +550,83 @@ action also stores the chosen dataset on the target chart for this view. Pass
 `hostActions` and every callback stays enabled. `pendingElementIds` shows those
 buttons as loading. `overrides` replaces a block by id.
 
+A `stepper` draws its `label` as a small muted line, then `IconButton` − and + around the
+value and its `unit`, then `itemsTitle`, a two-column grid of item labels and amounts
+(formatted with `decimals`, so `{amount: 2, unit: kg, decimals: 1}` reads "2.0 kg"), and the
+muted `note`. − is disabled when `value - step` would fall below `min`, and + when `value + step`
+would pass `max`, so with `max: 20` and `step: 2` + is disabled at 19. Both are disabled while either button's
+element id is in `pendingElementIds`, and when `hostActions` is passed without the stepper's
+`callback.name`. The buttons are labelled "Decrease <label>" and "Increase <label>". A tap
+calls `onAction` with `blockId: <id>`, `elementId: <id>_decrease` or `<id>_increase`, and
+`{kind: "callback", name, payload: {...payload, value: value ± step}}`. A host returns the
+new stepper, and `overrides[<id>]` paints it.
+
+A `checklist` draws its `title` on the left and an "n of m" counter on the right, then one
+`CheckBox` row per item: the bold `text` first, then the small muted `meta` (such as a time),
+then the muted `detail`. Each row is a pressable `Box` with the `checkbox` role, labelled with the item
+text, that reports `accessibilityState` `{checked, disabled}` (`aria-checked` and
+`aria-disabled` on web); Space toggles a focused row on web. A locked row keeps its role and
+label and reports `disabled: true`. Test ids are stable across states: the item wrapper is
+`<path>-<id>_<item id>`, the pressable row `<path>-<id>_<item id>-row-clickable`, its
+`CheckBox` `<path>-<id>_<item id>-checkbox`, its lines `<path>-<id>_<item id>-text`, `-meta`,
+and `-detail`, and the counter `<path>-counter`. A tick goes to the host when the checklist has a `callback`,
+`onAction` is passed, and `hostActions` is omitted (as for the stepper) or lists
+`callback.name`. Then a tap calls `onAction` with `blockId: <id>`,
+`elementId: <id>_<item id>`, and `{kind: "callback", name, payload: {...payload, itemId,
+checked, state}}`, where `state` maps every item id to its tick after this one. The tick is
+not drawn ahead of the reply. `BlocksView` disables the checklist while a tick is pending:
+while any of its `<id>_<item id>` element ids is in `pendingElementIds`, no row is pressable,
+so a second tick cannot send a `state` that misses the first. The counter changes when
+`overrides[<id>]` brings the returned checklist. Otherwise a tick stays in this `BlocksView` only and updates the counter at once.
+When an override for the checklist arrives or changes, earlier local ticks on it are dropped
+and the override's `checked` values show.
+On the server, `toggleChecklistHostAction` from `@terreno/ai` handles the callback and returns
+the stored checklist with the ticks from `state` (see [Host actions](ai.md#host-actions)). A host
+that records progress registers its own `handles: "checklist"` action.
+
+A `gallery` draws each image as a 4:3 `Image` tile (`fit` cover), with `alt` as the tile's
+accessible label and the optional `caption` as small muted text under it. Tiles are 8 apart
+(the `gap={2}` spacing step). The gallery measures its container with `onLayout`: up to three
+images share one row at equal widths, and more wrap into a three-column grid whose last row
+keeps the same tile width. When that width would fall under 160, every tile stays 160 wide in
+one row that scrolls sideways. A measured width decides this rather than the `sm` breakpoint, so
+a gallery inside a narrow `columns` child or card also scrolls. Before the first layout each tile
+is 160 wide. A `file:` tile loads through `resolveImage` like an `image` block. Until it has a
+URL, or when the lookup fails, the tile is a muted 4:3 placeholder that shows the alt text and
+keeps it as the label. Test ids: the gallery `<path>`, each grid row `<path>-row-<n>`, the
+scrolling row `<path>-scroll`, each tile `<path>-image-<index>`, the frame around a loaded
+image `<path>-image-<index>-image`, its caption `<path>-image-<index>-caption`, and a
+placeholder `<path>-image-<index>-placeholder`.
+`Image` passes `alt` to the native image as its `accessibilityLabel`.
+
+A `list` draws one row per item, 12 apart (`gap={3}`). The row starts with a 3:4 portrait
+`Image` thumbnail (`fit` cover), always 112 wide and 149 tall, with `alt` as its accessible label.
+Beside it, the optional `meta` sits small and muted above the bold `title`, and the optional
+`text` follows in muted body text. `text` is plain text, not markdown. When any item in the list
+has a thumbnail, an item without one keeps an empty 112-wide gutter so every title starts at the
+same place; a list with no thumbnails draws text only, with no gutter. A `file:` thumbnail loads
+through `resolveImage`, including in a list inside a card. Until it has a URL, or when the lookup
+fails, it is a muted 112 by 149 placeholder that shows the alt text and keeps it as the label.
+Test ids: the list `<path>`, each row `<path>-item-<index>`, its thumbnail
+`<path>-item-<index>-image`, placeholder `<path>-item-<index>-placeholder`, gutter
+`<path>-item-<index>-gutter`, text column `<path>-item-<index>-body`, and the
+`<path>-item-<index>-meta`, `-title`, and `-text` lines.
+
+A `copy` button writes the clipboard on the device and never calls `onAction`, so
+`hostActions` does not disable it. A press builds the text with `blockPlainText` from
+`@terreno/blocks`: a literal `text` as written, or the `target` block as it is shown now. That
+means the `overrides` replacement (a stepper at 6 copies the scaled amounts), the checklist's
+ticks made on the device, and a table's selected dataset, inline or a `ref` that
+`resolveDataset` has returned. `BlocksView` writes it with `expo-clipboard` `setStringAsync`
+(web and native), then shows "Copied" in small muted text beside the button for 2 seconds. A
+failed write, or a target with no text yet (such as a `ref` table still loading), shows
+"Couldn't copy" in error text for 2 seconds instead, logs `console.warn`, and does not throw.
+The status sits in a `Box` with `accessibilityLiveRegion="polite"`, which stays mounted while
+empty, so screen readers on web and Android announce the status when it appears (`Text` has
+no live-region prop, and VoiceOver on iOS does not announce React Native live regions).
+Test ids: the button `<path>-<element id>`, the live region `<path>-<element id>-status`, and
+the status text `<path>-<element id>-status-text`.
+
 ```tsx
 <BlocksView
   document={reply}
@@ -505,6 +638,23 @@ buttons as loading. `overrides` replaces a block by id.
 
 Demo story: `BlocksView`.
 
+### MarkdownView
+
+`MarkdownView` renders markdown with `react-native-markdown-display` and the current theme.
+GPTChat and the `text` block render through it.
+
+GFM tables use theme colors, never fixed hex values:
+
+- Cell borders draw a grid in `theme.border.default`.
+- Header cells sit on `theme.surface.secondaryLight` and use the bold text font (`text-bold`).
+  Body cells use `text-regular`.
+- Every column gets an equal share of the width, at least 96. A narrow table fills its
+  container. A table wider than its container scrolls sideways in a horizontal `ScrollView`.
+
+Test ids: `markdown-table-scroll` (the scroll view), `markdown-table`,
+`markdown-table-header-<column>`, and `markdown-table-cell-<row>-<column>` (body rows count
+from 0).
+
 ### 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.
@@ -738,7 +888,8 @@ top spacing, the navigation row, bottom spacing, and `bottomNavBarHeight`.
 opts into a labeled full-width pager on the narrow viewport. `narrowBelowWidth` uses that
 viewport when the window is at or below the given pixel width; when omitted, the narrow
 viewport follows `isNarrowViewport()`. These props are web only; the native `SplitPage`
-ignores them. See `SplitPageProps` for when each prop applies and what is ignored.
+ignores them. See `SplitPageProps` for when each prop applies and what is ignored. An unset
+`color` is `baseAlternate` on web and native.
 `IconButton`'s `backgroundOpacity` tints only that button's background.
 
 ```typescript
@@ -772,12 +923,25 @@ Buttons use a scale animation by default. Set `pressAnimation="opacity"` for an
 
 Disabled and loading buttons use a non-interactive pressable regardless of the selected animation.
 
+### Tooltip
+
+`Tooltip` (and `tooltipText` on `Button` / `IconButton`) renders its bubble outside the trigger's clipping and stacking context:
+
+| Platform | Mount point | Positioning |
+| --- | --- | --- |
+| Web | `document.body` | `position: fixed`, `z-index: 9999`, so it shows above an open `Modal` and nothing else covers the page |
+| iOS / Android | `TerrenoProvider` portal host | `position: absolute`, `z-index: 999` |
+
+The bubble stays off screen at `opacity: 0` until the trigger is measured, then `getTooltipPosition` places it at `idealPosition` or the first side that fits on screen.
+
 ### Toast
 
 `TerrenoProvider` mounts the toast container. Call `useToast()` for `success`, `info`, `warn`, `error`, `show`, `hide`, and `catch`.
 
 On web, that container is portaled to `document.body` (`position: fixed`, `z-index: 999999`, `pointerEvents: "box-none"`), so a toast stays above an open `Modal` and its backdrop. The web container is sized with `100%` rather than the measured window, so statically exported pages (where `Dimensions` reports 0×0 at build time) still center the toast on screen. Native iOS and Android keep the in-tree absolute container sized to the window.
 
+Only the visible toast takes clicks. Every full-width layer around it (the container, its safe area, and the `Toast` layout wrapper) uses `pointerEvents: "box-none"`, so a button at the same height as an open toast stays clickable. Declare that style through `StyleSheet.create`; react-native-web drops `pointerEvents` from inline styles.
+
 ## Authentication Components
 
 ### SocialLoginButton
@@ -1114,6 +1278,32 @@ Responsive `Box` direction props update automatically when the window resizes or
 All responsive Boxes share one dimension listener; non-responsive Boxes do not subscribe.
 When multiple direction props match, the largest active breakpoint wins (`xl` over `lg` over `md` over `sm`).
 
+`Box` takes an optional `accessibilityState` of `{checked?, disabled?}`. It is sent to screen
+readers as `accessibilityState` and as `aria-checked` / `aria-disabled`, on both a plain and a
+clickable Box. On a clickable Box, `disabled: true` also stops presses while the role and
+label stay. A clickable Box with `accessibilityRole` `checkbox` or `switch` also toggles on
+Space on web, as ARIA expects.
+
+```tsx
+<Box
+  accessibilityHint="Marks this item as done"
+  accessibilityLabel="Preheat the oven"
+  accessibilityRole="checkbox"
+  accessibilityState={{checked: false, disabled: isSaving}}
+  onClick={toggle}
+/>
+```
+
+`Box` also takes `accessibilityLiveRegion` (`polite` or `assertive`) on a Box without
+`onClick`. It is sent as `aria-live`, so screen readers announce changes to the Box's contents
+on web and Android. VoiceOver on iOS does not announce React Native live regions.
+
+```tsx
+<Box accessibilityLiveRegion="polite" testID="copy-status">
+  {status ? <Text size="sm">{status}</Text> : null}
+</Box>
+```
+
 ## Icons
 
 Terreno uses **FontAwesome 6** by default. Pass icon names via `iconName` on `Icon`, `Button`, `IconButton`, form fields, `Badge`, and other icon-aware components.
@@ -1233,8 +1423,8 @@ const buttonStyles = toggle(isPressed, pressedStyles, defaultStyles);
 
 @terreno/ui components do not require environment variables. All configuration is done at runtime via:
 
-- **TerrenoProvider props** — Theme customization, custom icon registry (`icons`), OpenAPI spec URL
-- **Theme hooks** — `useTheme()`, `setTheme()`, `setPrimitives()`
+- **TerrenoProvider props** — `colorScheme`, `initialPrimitives`, custom icons, and OpenAPI spec URL
+- **Theme hooks** — `useTheme()`, `setColorScheme()`, `setTheme()`, `setPrimitives()`
 - **Component props** — Direct prop overrides for individual components
 
 **Example configuration:**
@@ -1243,16 +1433,28 @@ const buttonStyles = toggle(isPressed, pressedStyles, defaultStyles);
 import {TerrenoProvider} from "@terreno/ui";
 
 <TerrenoProvider
-  baseUrl="https://api.example.com"
-  theme={{
-    surface: {primary: "secondary500"},
-  }}
-  onError={(error) => console.error(error)}
+  colorScheme="system"
+  openAPISpecUrl="https://api.example.com/openapi.json"
 >
   {children}
 </TerrenoProvider>
 ``````
 
+## DataTable column types
+
+`columnType` picks the cell a column draws, unless `customColumnComponentMap` has an entry
+for that type:
+
+| `columnType` | Cell |
+| --- | --- |
+| `text` (and any unmapped type) | The value as a string |
+| `number` | The value as a string, right-aligned, with the header right-aligned to match. A number or a numeric string both work |
+| `date` | An ISO string or a `Date`, formatted with Luxon `DATE_MED` ("Mar 14, 2026") in the local zone. A value Luxon cannot parse is shown as written, and an empty value is blank |
+| `boolean` | A check or a cross icon |
+
+A value that is already formatted, such as "Oct 8, 2026, 3:00 PM", is not ISO, so a `date`
+column shows it unchanged.
+
 ## DataTable server-side filtering
 
 `DataTable` is data-layer agnostic. Optional filter and search props emit a

package/dist/docs/versioned/next/tasks/agent-ui-rich-replies.md

@@ -0,0 +1,188 @@
+# Task List: Agent UI Rich Replies
+
+**Status:** approved 2026-10-07. Start with T1 (or T19, which is independent).
+**IP:** [`docs/implementationPlans/agent-ui-rich-replies.md`](../implementationPlans/agent-ui-rich-replies.md). The contracts, acceptance criteria (AC1–AC14, including AC6b), and open questions are there.
+**Supporting skills:** `terreno-ui`, `terreno-backend-api`, `ai-prompt-governance`, `update-docs`, `verify-ui-changes`, `backend-test-env`.
+
+Two write chains share files, so their tasks are ordered.
+
+- **Contract chain:** T1 → T2 → T5 → T6 → T7 → T8 → T9. These write `blocks/src/schema.ts`, `limits.ts`, `lint.ts`, `prompt.ts`, fixtures, and `docs/reference/blocks.md`.
+- **Renderer chain:** T1 → T3 → T10 → T11 → T12 → T13 → T14. These write `ui/src/blocks/blockRenderers.tsx`, `BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, and the BlocksView section of `docs/reference/ui.md`.
+
+Each renderer task also waits for its own contract task. T4 sits in the renderer chain between T3 and T10 because it also edits `docs/reference/ui.md`. Every contract task that adds fixtures also edits `blocks/src/parse.test.ts` (`expectedInvalid`); invalid cases that need validate options go in `blocks/src/lint.test.ts`. Fixtures under `valid/` use `data:image` or `file:` image sources.
+
+### Phase 1: Tracer
+
+- [x] **T1** — Stepper block round trips through a host callback
+  - Depends on: none
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/errors.ts` (`OUT_OF_RANGE`), `blocks/src/lint.ts` (stepper `callback.name` in `UNKNOWN_HOST_ACTION`; reserved `<id>_increase` / `<id>_decrease` in `DUPLICATE_ID`), `blocks/src/fixtures/valid/stepper*.yaml`, `blocks/src/fixtures/invalid/stepper*.yaml`, `blocks/src/parse.test.ts`, `blocks/src/lint.test.ts`, `blocks/src/index.ts`; `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`; `ai/src/service/agentBlocks.ts` (`findAgentBlock`), `ai/src/service/agentBlocks.test.ts`, `ai/src/service/scaleStepper.ts`, `ai/src/service/scaleStepper.test.ts`, `ai/src/types/index.ts` (`handles?`, `logResponse?` on host actions), `ai/src/routes/gptActions.ts` (honour `logResponse: false`), `ai/src/routes/gptActions.test.ts`, `ai/src/index.ts`; `docs/reference/blocks.md`, `docs/reference/ai.md`, `docs/reference/ui.md`.
+  - Delivers:
+    - The `stepper` contract from the IP.
+    - The renderer: − value +, unit, `itemsTitle`, an items grid formatted with `decimals`, and the note. It emits the callback with `{...payload, value}`. Buttons are disabled at the bounds, while pending, and when the callback is not in `hostActions`.
+    - `scaleStepperHostAction`: payload `z.object({value: z.number()}).passthrough()`. It reads the agent's stepper through `findAgentBlock`: `history.prompts[n]` (`msg-<n>`), or the only prompt holding that stepper id (409 when there are several, 404 when none). It checks `value` and returns `{replace: "block", blocks: {v: 1, blocks: [stepper]}}`.
+    - The `logResponse` host-action option. With it off, the log keeps the ids-only prompt plus `value`, with no response.
+  - Acceptance: AC4; AC5; the stepper rows of AC1 and AC2. `bun test blocks/`, `cd ui && bun test src/blocks`, and `cd ai && bun test --preload ./src/tests/bunSetup.ts src/service/scaleStepper.test.ts src/routes/gptActions.test.ts` are green.
+
+- [x] **T2** — Prompt offers the new blocks by default, with an opt-out
+  - Depends on: T1
+  - Files: `blocks/src/prompt.ts`, `blocks/src/prompt.test.ts`, `blocks/src/validate.ts` (`stepperActions`), `blocks/src/lint.ts`; `ai/src/types/index.ts` (`uiBlocks.richBlocks`), `ai/src/service/prompts.ts`, `ai/src/service/chatTurn.ts` (derive `stepperActions` and `checklistActions` from the host actions' `handles`; pass `richBlocks`), `ai/src/routes/gpt.test.ts`; `docs/reference/blocks.md`, `docs/reference/ai.md`.
+  - Delivers: the default-on table in the IP. It adds the `richBlocks` plumbing (default `true` in both `uiBlocks` and `blocksPromptSection`), the stepper gate (a `handles: "stepper"` action), and the `checklistActions` list that T5 uses. With `richBlocks: false`, the prompt text is byte-identical to `master`, even with a stepper action registered. Later contract tasks add their prompt line under `richBlocks`.
+  - Acceptance: the AC3 `false` case, the default-on check, and the stepper line; a chat-turn test where a stepper naming a non-stepper action fails `UNKNOWN_HOST_ACTION`. The full on-case snapshot is T9's.
+
+### Phase 2: Tables
+
+- [x] **T3** — Table block renders typed columns
+  - Depends on: T1
+  - Files: `ui/src/DataTable.tsx` (number and date cells), `ui/src/DataTable.test.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md` (DataTable and BlocksView sections).
+  - Delivers: right-aligned `number` cells and Luxon `DATE_MED` `date` cells in `DataTable`. The `table` block maps the dataset column types to these cells, measures its width with `onLayout`, and splits the width evenly, at least 96 per column, scrolling sideways past that.
+  - Acceptance: AC9 (table half); the new tests fail on `master`.
+
+- [x] **T4** — Markdown tables in `text` get theme styling
+  - Depends on: T3 (shares `docs/reference/ui.md`; T10 follows T4 for the same reason)
+  - Files: `ui/src/MarkdownView.tsx`, `ui/src/MarkdownView.test.tsx`, `docs/reference/ui.md` (MarkdownView section only).
+  - Delivers: `border.default` cell borders, a bold header on `surface.secondaryLight`, and horizontal scroll when the table is wide.
+  - Acceptance: AC9 (markdown half); the test fails on `master`.
+
+### Phase 3: Contracts
+
+- [x] **T5** — `checklist` contract
+  - Depends on: T2
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts` (item ids; reserved `<id>_<item id>` element ids; checklist `callback.name` against `checklistActions`), `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/checklist*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `checklist` schema from the IP, including the optional `callback`. Its prompt line sits under `richBlocks` and names the checklist action when there is one.
+  - Acceptance: the checklist rows of AC1 and AC3; `bun test blocks/`.
+
+- [x] **T6** — `gallery` contract
+  - Depends on: T5
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts` (image hosts per tile), `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/gallery*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `gallery` schema. `IMAGE_HOST_NOT_ALLOWED` names the tile path (`blocks[0].images[2].src`).
+  - Acceptance: the gallery rows of AC1 and AC3; an invalid fixture with a disallowed host.
+
+- [x] **T7** — `list` contract
+  - Depends on: T6
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/lint.ts`, `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/list*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `list` schema. The optional image on each item goes through image-host lint.
+  - Acceptance: the list rows of AC1 and AC3.
+
+- [x] **T8** — `card.eyebrow` contract
+  - Depends on: T7
+  - Files: `blocks/src/schema.ts`, `blocks/src/limits.ts`, `blocks/src/prompt.ts`, `blocks/src/fixtures/{valid,invalid}/card-eyebrow*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: an optional `eyebrow` (1–60) on `card`.
+  - Acceptance: the eyebrow rows of AC1 and AC3.
+
+- [x] **T9** — `copy` action contract and `blockPlainText`
+  - Depends on: T8
+  - Files: `blocks/src/schema.ts`, `blocks/src/errors.ts` (`COPY_TARGET_INVALID`), `blocks/src/lint.ts` (exactly one of `text` / `target`, as `open` does), `blocks/src/prompt.ts`, `blocks/src/plainText.ts`, `blocks/src/plainText.test.ts`, `blocks/src/index.ts`, `blocks/src/fixtures/{valid,invalid}/copy*.yaml`, `blocks/src/parse.test.ts`, `docs/reference/blocks.md`.
+  - Delivers: the `copy` action kind, target lint, and `blockPlainText` as the IP table describes it.
+  - Acceptance: the copy rows of AC1, AC2, and AC3; the full AC3 `richBlocks`-on snapshot. `plainText.test.ts` covers every row of the IP table.
+
+### Phase 4: Renderers
+
+- [x] **T10** — Checklist renders and toggles
+  - Depends on: T3, T4, T5
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/useChecklistState.ts`, `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: a `CheckBox` row per item (meta, bold text, detail) and the "n of m" counter. With a callback in `hostActions`, a tick emits `{...payload, itemId, checked, state}`, disables the whole checklist while a tick is pending (so a second tick cannot send a stale `state`), and shows the returned block. Without one, ticks are local for each rendered document.
+  - Acceptance: AC6.
+
+- [x] **T11** — Gallery renders
+  - Depends on: T6, T10
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: one row of 4:3 `Image` tiles up to 3, a 3-column grid above that, captions, `file:` ids through `useResolvedImages`, and sideways scroll on narrow screens.
+  - Acceptance: AC7 (gallery).
+
+- [x] **T12** — List renders
+  - Depends on: T7, T11
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `demo/stories/BlocksView.stories.tsx`, `docs/reference/ui.md`.
+  - Delivers: for each item, a 3:4 thumbnail on the left, a bold title, muted text, and the meta.
+  - Acceptance: AC7 (list).
+
+- [x] **T13** — Card eyebrow renders
+  - Depends on: T8, T12
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: small, muted eyebrow text above the card title.
+  - Acceptance: AC7 (eyebrow).
+
+- [x] **T14** — Copy action writes the clipboard
+  - Depends on: T9, T13
+  - Files: `ui/src/blocks/BlocksView.tsx`, `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: a copy button builds its text with `blockPlainText` from the current block (override and toggles applied), writes it with `expo-clipboard`, and shows "Copied" in a polite live region for 2 s. It never calls `onAction`.
+  - Acceptance: AC8.
+
+### Phase 5: The roast reply end to end
+
+- [x] **T15** — Sunday roast golden document and playground story
+  - Depends on: T14
+  - Files: `blocks/src/fixtures/golden/sunday-roast.yaml`, `blocks/src/golden.test.ts` (validate with `hostActions: ["scaleStepper"]`, `stepperActions: ["scaleStepper"]`, `imageHosts: ["images.example.com"]`), `demo/stories/BlocksPlayground.stories.tsx` (a roast preset).
+  - Delivers: the GPT-6 demo reply as one document: the title; the gallery; the summary card with an eyebrow; the menu list; the stepper and copy card; the checklist with its first item checked; the USDA note as `context`; the tips as `text`; and follow-up `reply` buttons. It also includes the GPT-5.6 "How much lamb?" table as a `table` block. Images use `https://images.example.com/...` and validate only with `imageHosts`, so the file lives under `golden/`, not `valid/`.
+  - Acceptance: AC10; a playground screenshot under `/opt/cursor/artifacts/`.
+
+- [x] **T16** — Example app runs the roast reply against the real callback route
+  - Depends on: T15, T20, T21
+  - Files:
+    - `example-backend/src/ai/hostActions.ts`: register `scaleStepper: scaleStepperHostAction` and `toggleChecklist: toggleChecklistHostAction` (`richBlocks` is on by default).
+    - `example-frontend/app/(tabs)/ai.tsx`: add `scaleStepper` and `toggleChecklist` to `hostActions`.
+    - `example-frontend/e2e/helpers/seedGptHistory.ts` (new): `POST /gpt/histories` as the logged-in user, with the roast document as the assistant prompt.
+    - `example-frontend/e2e/helpers/mockGpt.ts`: the mocked stream returns the seeded `historyId`, and `/gpt/actions` is no longer mocked for this spec.
+    - `example-frontend/e2e/ai-chat.spec.ts`.
+    - `docs/explanation/example-coverage.md`.
+  - Delivers: the seeded roast document uses `file:` ids from a test `PhotoLibraryEntry`. Playwright presses + (5 → 6, the quantities change) and ticks a checklist item, both through the real `POST /gpt/actions`, then presses copy. Only the signed-URL image download is stubbed.
+  - Acceptance: AC11.
+
+- [x] **T17** — Model smoke: a real model writes the roast reply
+  - Depends on: T15, T20
+  - Files: `example-backend/src/scripts/blocksSmoke.ts`, `example-backend/package.json` and root `package.json` (`blocks:smoke` script).
+  - Delivers: a script that runs the post's prompt through `AIService` with the opted-in blocks prompt and checks the reply. It skips cleanly when no model key is set.
+  - Acceptance: AC12.
+
+- [x] **T18** — Docs sweep, changelog, rules
+  - Depends on: T15, T20, T21
+  - Files:
+    - `docs/explanation/agent-ui-blocks.md`: the catalog list, adding the missing `callout`, `image`, `details`, and `html`; why the stepper is a callback; the default-on rollout and the `richBlocks: false` opt-out for shipped native builds.
+    - `docs/how-to/agent-ui-blocks.md`: a section "Add a stepper callback", including the warning that stored history prompts are owner-writable, so a handler whose numbers matter must use its own data.
+    - `changelog/unreleased/agent-ui-rich-replies.md`, with a "Behaviour change" note: hosts with `uiBlocks` get the new blocks in the prompt by default; set `uiBlocks.richBlocks: false` to keep the old catalog.
+    - `.rulesync/rules/ui/00-ui.md` and `.rulesync/rules/ai/00-ai.md`, then `bun run rules`.
+  - Delivers: docs a stranger can follow to build the roast reply without reading the PR.
+  - Acceptance: AC13.
+
+- [x] **T19** — Generated photo library: generate images once and store them
+  - Depends on: none
+  - Files: `example-backend/src/models/photoLibraryEntry.ts`, `example-backend/src/types/models/photoLibraryEntryTypes.ts`, `example-backend/src/scripts/photoPrompts.ts`, `example-backend/src/scripts/generatePhotoLibrary.ts`, `example-backend/src/scripts/generatePhotoLibrary.test.ts`, `knip.jsonc` (script entry), `example-backend/package.json` (`photos:generate`).
+  - Delivers: the `PhotoLibraryEntry` model and the `photos:generate` script from the IP. It runs AI SDK `generateImage` with the Vertex image model, then `FileStorageService.upload`, then upserts by `prompt`. It validates the required env up front, skips existing prompts, and takes `--force`. Supporting skill: `mongoose-schema-safety`.
+  - Acceptance: AC14 (generation half), using a fake image model and fake storage.
+
+- [x] **T20** — `findPhotos` tool and photo URLs in the example app
+  - Depends on: T19
+  - Files: `example-backend/src/ai/tools.ts` (`findPhotos`), `example-backend/src/ai/tools.test.ts`, `example-backend/src/api/photoLibrary.ts` (`modelRouter` with instance action `url`), `example-backend/src/api/photoLibrary.test.ts`, `example-backend/src/server.ts` (register it), `example-frontend/store/openApiSdk.ts` (regenerated with `bun run sdk`), `example-frontend/app/(tabs)/ai.tsx` (`resolveImage`), `docs/how-to/agent-ui-blocks.md` ("Give the agent photos"; T18 follows it).
+  - Delivers: `findPhotos({query, count})` returns `{src: "file:<id>", alt}` from the library. `GET /photoLibrary/:id/url` returns a signed URL to any authenticated user. The example chat resolves `file:` ids through the generated hook. Supporting skills: `model-router-actions`, `generate-sdk`.
+  - Acceptance: AC14 (tool and route half).
+
+- [x] **T21** — Checklist ticks round trip through a host callback
+  - Depends on: T10
+  - Files: `ai/src/service/toggleChecklist.ts`, `ai/src/service/toggleChecklist.test.ts`, `ai/src/routes/gptActions.test.ts`, `ai/src/index.ts`, `docs/reference/ai.md`.
+  - Delivers: `toggleChecklistHostAction` from the IP, built on `findAgentBlock`.
+  - Acceptance: AC6b.
+
+### Phase 6: Playground follow-up (D7)
+
+- [x] **T22** — Every block type has a playground preset
+  - Depends on: T15
+  - Files: `demo/stories/BlocksPlayground.stories.tsx`, `demo/story-config/BlocksPlayground.config.tsx`, a demo test that every schema block type appears in a preset and every preset validates.
+  - Delivers: one preset per block type plus "All blocks", covering every action kind and the segmented control.
+  - Acceptance: the coverage test fails when a block type has no preset; every preset validates; runtime screenshots at 1280 and 390.
+
+- [x] **T23** — Stepper and checklist callbacks run in the playground
+  - Depends on: T22
+  - Files: `blocks/src/hostActionLogic.ts` (or similar) + tests + `blocks/src/index.ts`, `ai/src/service/scaleStepper.ts`, `ai/src/service/toggleChecklist.ts`, `demo/stories/BlocksPlayground.stories.tsx`, `docs/reference/blocks.md`.
+  - Delivers: pure `scaleStepperBlock` and `applyChecklistState` in `@terreno/blocks`, used by both host actions and the playground; other actions show a toast.
+  - Acceptance: in the playground, + shows 6 and "2.4 kg", a tick shows "2 of 8", a reply button shows a toast; ai host-action tests unchanged and green.
+
+- [x] **T24** — Checklist rows read bold title, then time, then description
+  - Depends on: none
+  - Files: `ui/src/blocks/blockRenderers.tsx`, `ui/src/blocks/BlocksView.test.tsx`, `docs/reference/ui.md`.
+  - Delivers: the row order from D7, test IDs unchanged.
+  - Acceptance: a test asserts the order; the e2e roast spec still passes.
+
+- [x] **T25** — Demo blocks use real photos
+  - Depends on: T22
+  - Files: `demo/assets/blocks/*.jpg`, `demo/assets/blocks/ATTRIBUTION.md`, `demo/stories/BlocksView.stories.tsx`, `demo/stories/BlocksPlayground.stories.tsx`.
+  - Delivers: gallery, list, and image presets and stories show bundled public-domain photos through `file:` ids and `resolveImage`.
+  - Acceptance: in the browser every photo loads (`naturalWidth` 800); attribution lists each source and license.

package/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.12.0",
-    "@terreno/blocks": "57.12.0",
+    "@terreno/api": "57.14.0",
+    "@terreno/blocks": "57.14.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -105,5 +105,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.12.0"
+  "version": "57.14.0"
 }

package/src/docs/upgrades/57.13.0.md

@@ -0,0 +1,75 @@
+# Upgrading to 57.13.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai, @terreno/ui
+
+## Summary
+
+Agent replies can use rich blocks (stepper, checklist, gallery, list, card eyebrow, copy), and hosts with `uiBlocks` on offer them in the prompt by default. `DataTable` number and date columns render differently, `neutral500` is a slightly darker gray, and the admin Roles screen groups permissions by resource. `@terreno/api` adds a per-route rate limiter, and `DocumentStorageApp` can be opened to signed-in non-admins. Action is required only for hosts with `uiBlocks` on that still have native builds from before this release.
+
+## Breaking changes
+
+### Rich blocks are offered in the chat prompt by default
+
+**What changed**
+
+With `uiBlocks` on, the chat system prompt now offers `checklist`, `gallery`, `list`, card `eyebrow`, and `copy`, plus `stepper` when a host action has `handles: "stepper"`. A native build shipped before 57.13.0 cannot render those blocks and shows an error banner for a reply that uses them.
+
+**Why**
+
+Rich blocks make agent replies more useful, so new hosts get them without extra setup.
+
+**Migration**
+
+Keep the old catalog until every shipped native build is on 57.13.0 or later:
+
+```typescript
+// Before
+addGptRoutes(router, {aiService, uiBlocks: {hostActions}});
+
+// After (until old native builds age out)
+addGptRoutes(router, {aiService, uiBlocks: {hostActions, richBlocks: false}});
+```
+
+With `richBlocks: false` the prompt is the same as before. Validation accepts the new blocks either way.
+
+### `DataTable` number and date cells
+
+**What changed**
+
+`columnType: "number"` columns right-align cells and header. `columnType: "date"` cells format an ISO string or `Date` as Luxon `DATE_MED` (date only, local zone). Strings that are not ISO dates show as before.
+
+**Why**
+
+Numbers line up by digit, and raw ISO timestamps were hard to read.
+
+**Migration**
+
+To keep the old look for a column, render it with `customColumnComponentMap`:
+
+```typescript
+// Before
+{columnType: "date", title: "Created", width: 150}
+
+// After (keep the raw value)
+{columnType: "rawDate", title: "Created", width: 150}
+// with customColumnComponentMap={{rawDate: ({cellData}) => <Text>{String(cellData.value)}</Text>}}
+```
+
+## Deprecations
+
+None
+
+## New capabilities
+
+- `createRouteRateLimitMiddleware({name, max, windowMs, store?, keyBy?})` from `@terreno/api` for a fixed-window limit on one route.
+- `DocumentStorageApp` `access: "authenticated"` (non-admins see only `users/<userId>/`) and `uploadRateLimit`.
+- `scaleStepperHostAction`, `toggleChecklistHostAction`, `findAgentBlock`, and `runBufferedChatTurn` from `@terreno/ai`.
+- `SegmentedControl` `size="sm"`; `Box` `accessibilityState` and `accessibilityLiveRegion`.
+- The `neutral500` primitive is `#949494`. Override it with `setPrimitives({neutral500: "#9A9A9A"})` to keep the old gray.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- Send a chat prompt that asks for a checklist; on a current build it renders, and with `richBlocks: false` the agent replies with the old block types
+- Open a screen with a `DataTable` date column and check the dates read as `Oct 10, 2026`

package/src/docs/upgrades/57.14.0.md

@@ -0,0 +1,43 @@
+# Upgrading to 57.14.0
+
+**Action required:** No
+**Affected packages:** @terreno/syncdb
+
+## Summary
+
+`@terreno/syncdb` pages snapshot streams in parallel (up to 6 at once by default) instead of one at a time, so cold start, reconcile, subscribe catch-up, `forceResync`, and wipe re-bootstrap finish faster when an app has many collections or scopes. Each stream now runs one snapshot pass at a time, which stops a concurrent pass from marking a purged stream bootstrapped over rows it never paged. No code change is required.
+
+## Breaking changes
+
+None
+
+## Deprecations
+
+None
+
+## New capabilities
+
+### `snapshotConcurrency` on `createSyncDb`
+
+The client now sends up to `snapshotConcurrency` snapshot requests at once (default `DEFAULT_SNAPSHOT_CONCURRENCY`, 6). If your backend cannot take the extra parallel load at cold start, lower it. `1` restores the old one-stream-at-a-time behavior.
+
+```typescript
+// Before
+export const syncDb = createSyncDb({authProvider, baseUrl, collections, name: "my-app"});
+
+// After (only if you need to limit parallel snapshot requests)
+export const syncDb = createSyncDb({
+  authProvider,
+  baseUrl,
+  collections,
+  name: "my-app",
+  snapshotConcurrency: 2,
+});
+```
+
+A new how-to, `docs/how-to/use-syncdb-correctly.md`, lists library behavior apps have to handle.
+
+## Verification
+
+- `bun run compile` and `bun run lint` at the app root
+- Log in on a fresh device or after `wipeLocalData`; synced screens load, and the backend logs show several `/sync/snapshot` requests in flight together

package/src/docs/versioned/next/explanation/README.md

@@ -19,7 +19,7 @@ Understanding-oriented documentation: concepts, architecture, and context.
 - [Durable agent harness](durable-agent-harness.md) — Phases, checkpoints, and why the audit span shares the checkpoint transaction
 - [AI-powered workflows](ai-workflows.md) — Autonomous documentation, testing, and maintenance workflows
 - [Agent UI Asks](agent-ui-asks.md) — Why agent questions are client-side tool calls, the pause and resume round trip, why cards carry exact answers, the watch paths, asks vs blocks
-- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI
+- [Agent UI blocks](agent-ui-blocks.md) — Why chat replies use a closed YAML catalog instead of free-form UI, why steppers and checklists call the server, and the rich-blocks rollout
 - [Authentication architecture](authentication.md) — Better Auth, JWT, and optional MCP service tokens
 - [Organization tenancy](organizations.md) — Optional Membership-backed tenancy, context, and isolation boundaries
 - [Configuration system](configuration-system.md) — Runtime configuration with database persistence