@terreno/mcp 57.12.0 → 57.13.0

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

@@ -54,7 +54,7 @@ A dataset name matches `^[a-z][a-z0-9_]{0,63}$`. A document has at most 8 datase
 | `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`.
+`src` (on an `image` block, on each `gallery` tile, and on a `list` item's `image`) 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:
 
@@ -74,15 +74,153 @@ Warnings do not block rendering:
 | `badge` | `text` (1–80) | `status`: `info`, `error`, `warning`, `success`, `neutral`, `active`; `id` | `Badge` |
 | `divider` | — | `id` | `SectionDivider` |
 | `context` | `text` (1–280) | `id` | `Text` |
+| `stepper` | see [Stepper](#stepper) | | `IconButton` − and +, `Text`, `Heading` |
+| `checklist` | see [Checklist](#checklist) | | `CheckBox` rows, `Text`, `Heading` |
+| `gallery` | see [Gallery](#gallery) | | `Image` tiles in a row or grid, `Text` captions |
+| `list` | see [List](#list) | | `Image` thumbnails beside `Text` title, text, and meta |
 | `columns` | `children`: 2–4 blocks | `id` | `Box` row |
-| `card` | `children`: at least 1 block | `title` (1–120), `id` | `Card` |
+| `card` | `children`: at least 1 block | `title` (1–120), `eyebrow` (1–60), `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.
 
+A card's `eyebrow` is a short label that sits small and muted above the `title` (or above the
+children when there is no title). `BlocksView` draws it as a `Text` in the same small, muted style
+as the stepper label, with test ID `<card path>-eyebrow`.
+
 `id` matches `^[a-z][a-z0-9_]{0,63}$`.
 
+## Stepper
+
+A `stepper` is a − value + control. Each tap calls a host callback, and the host returns the
+replacement stepper (see `scaleStepperHostAction` in [the AI reference](ai.md)).
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `id` | yes | Block id pattern, at most 54 characters |
+| `label` | yes | 1–80 |
+| `value`, `min`, `max` | yes | Numbers. `min` < `max` and `min` ≤ `value` ≤ `max`, or `OUT_OF_RANGE` |
+| `step` | no | Above 0 (`OUT_OF_RANGE`). Default 1 |
+| `unit` | no | 1–40, shown under the value ("People") |
+| `callback` | yes | `{name, payload?}`. `name` is checked by `UNKNOWN_HOST_ACTION` against `stepperActions` when that is passed, otherwise against `hostActions` |
+| `itemsTitle` | no | 1–80, a small heading above the items |
+| `items` | no | 0–12 of `{label (1–80), amount, unit? (1–20), decimals? (0–3, default 0), round?: nearest or up (default nearest)}`. `decimals` below 0 or above 3 is `OUT_OF_RANGE` |
+| `note` | no | 1–280, muted under the items |
+
+```yaml
+- type: stepper
+  id: guests
+  label: Number of people
+  unit: People
+  value: 5
+  min: 1
+  max: 20
+  callback: {name: scaleStepper}
+  items:
+    - {label: Bone-in leg of lamb, amount: 2, unit: kg, decimals: 1}
+    - {label: Carrots, amount: 8, round: up}
+  note: Generous portions, with a little extra.
+```
+
+The renderer uses the element ids `<id>_decrease` and `<id>_increase` for the − and + buttons
+(`stepperElementIds(id)`). Another block or action element with either id is `DUPLICATE_ID`.
+A tap sends `{kind: callback, name, payload: {...payload, value: value ± step}}` with
+`blockId: <id>`.
+
+## Checklist
+
+A `checklist` is a list of tickable items with an "n of m" counter. `BlocksView` draws the title
+and counter, then one `CheckBox` row per item: the bold `text`, then the small muted `meta` (such
+as a time), then the muted `detail`. With a `callback` whose name is in `hostActions` (or with `hostActions` omitted), a
+tick calls `onAction` with `blockId: <id>`, `elementId: <id>_<item id>`, and
+`{kind: "callback", name, payload: {...payload, itemId, checked, state}}`. `state` maps every
+item id to its tick after this one. `BlocksView` disables the checklist while a tick is
+pending, and the tick shows only when the host's returned checklist arrives as an override.
+Without a `callback`, or when its name is not in `hostActions`, ticks stay on the device. On the
+server, `toggleChecklistHostAction` from `@terreno/ai` handles the callback and returns the stored
+checklist with `checked` from `state` (see [Host actions](ai.md#host-actions)).
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `id` | yes | Block id pattern, at most 31 characters |
+| `title` | no | 1–120 |
+| `callback` | no | `{name, payload?}`. `name` is checked by `UNKNOWN_HOST_ACTION` against `checklistActions` when that is passed, otherwise against `hostActions` |
+| `items` | yes | 1–30 of `{id, text (1–120), detail? (1–280), meta? (1–40), checked?: boolean}`. An item `id` uses the block id pattern, at most 32 characters, and is unique in the checklist (`DUPLICATE_ID`) |
+
+```yaml
+- type: checklist
+  id: cooking
+  title: Cooking checklist
+  callback: {name: toggleChecklist}
+  items:
+    - {id: oven, meta: "1:00 pm", text: Preheat the oven, detail: "220 C, fan off.", checked: true}
+    - {id: lamb_in, meta: "1:30 pm", text: Put the lamb in}
+```
+
+Each item's tick has the reserved element id `<id>_<item id>` (`checklistElementId(id, itemId)`).
+Another block or action element with that id, or a stepper or checklist that derives the same
+element id, is `DUPLICATE_ID`.
+
+## Gallery
+
+A `gallery` is a set of 2–6 photos shown together. `BlocksView` draws up to three in one row of
+equal 4:3 tiles and wraps more into a three-column grid. On a narrow screen the tiles keep a
+minimum width and the row scrolls sideways (see [BlocksView](ui.md#blocksview)).
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `id` | no | Block id pattern |
+| `images` | yes | 2–6 of `{src, alt (1–200), caption? (1–120)}`. Fewer is `TOO_FEW`, more is `TOO_MANY` |
+
+Each tile's `src` follows the `image` rules above. A tile that breaks them is
+`IMAGE_HOST_NOT_ALLOWED` at that tile's path, such as `blocks[0].images[2].src`.
+
+```yaml
+- type: gallery
+  id: roast_photos
+  images:
+    - {src: "file:roast-lamb", alt: Roast leg of lamb on a carving board, caption: Roast lamb}
+    - {src: "file:roast-potatoes", alt: Crisp roast potatoes in a tray}
+    - {src: "https://images.example.com/carrots.jpg", alt: Glazed carrots, caption: "Honey, thyme, and butter"}
+```
+
+The third tile validates only when `imageHosts` includes `images.example.com`.
+
+## List
+
+A `list` is a stack of 1–12 entries, each with a title and an optional thumbnail. `BlocksView`
+draws each item as a row: a 3:4 portrait thumbnail on the left, then the small muted `meta`, the
+bold `title`, and the muted `text` (see [BlocksView](ui.md#blocksview)).
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `id` | no | Block id pattern |
+| `items` | yes | 1–12 items. Fewer is `TOO_FEW`, more is `TOO_MANY` |
+| `items[].title` | yes | 1–120 characters |
+| `items[].text` | no | 1–500 characters of plain text, not markdown |
+| `items[].meta` | no | 1–40 characters, a short label such as a time or a price |
+| `items[].image` | no | `{src, alt}`. `alt` is 1–200 characters, the same cap as an `image` block's `alt` (`BLOCK_LIMITS.headingTextMaxLength`) |
+
+An item image's `src` follows the `image` rules above. One that breaks them is
+`IMAGE_HOST_NOT_ALLOWED` at that item's path, such as `blocks[0].items[1].image.src`.
+
+```yaml
+- type: list
+  id: menu
+  items:
+    - title: Roast leg of lamb
+      text: Rubbed with garlic and rosemary, then rested for 20 minutes.
+      meta: Main
+      image: {src: "file:roast-lamb", alt: Roast leg of lamb on a carving board}
+    - title: Honey carrots
+      text: "Glazed with honey, thyme, and butter."
+      image: {src: "https://images.example.com/carrots.jpg", alt: Glazed carrots}
+    - title: Mint sauce
+```
+
+The second item validates only when `imageHosts` includes `images.example.com`.
+
 ## Actions
 
 An `actions` block requires `id` and `elements` (1–25). An element is a `button` or a
@@ -94,10 +232,76 @@ An `actions` block requires `id` and `elements` (1–25). An element is a `butto
 | `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
+(`target` plus `data`), `callback` (`name` plus optional `payload`), or `copy` (`text` or
+`target`, exactly one; see [Copy](#copy)). 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.
+Omitting `hostActions` skips that check. A stepper `callback.name` is checked against
+`stepperActions` instead when that list is passed, so a stepper that names a registered action
+that does not handle steppers is `UNKNOWN_HOST_ACTION`. `checklistActions` does the same for
+checklist callbacks.
+
+## Copy
+
+A `copy` action puts text on the device clipboard. It never reaches the host, so `hostActions`
+does not apply to it. It is a `button` element's `action`:
+
+| Field | Rule |
+| --- | --- |
+| `text` | 1–4,000 characters (`BLOCK_LIMITS.copyTextMaxLength`), copied as written |
+| `target` | The `id` of a `stepper`, `checklist`, `list`, `table`, or `text` block in this document (`COPY_TARGET_TYPES`). Any other block, or an id no block has, is `COPY_TARGET_INVALID` |
+
+Set exactly one of the two. Neither or both is `MISSING_REQUIRED` at the action's path, as for
+`open`. The target may sit anywhere in the document, before or after the button, inside a
+`card` or `columns`.
+
+```yaml
+v: 1
+blocks:
+  - type: stepper
+    id: guests
+    label: Number of people
+    unit: People
+    value: 5
+    min: 1
+    max: 20
+    callback: {name: scaleStepper}
+    items:
+      - {label: Bone-in leg of lamb, amount: 2, unit: kg, decimals: 1}
+      - {label: Carrots, amount: 8}
+  - type: actions
+    id: shopping
+    elements:
+      - type: button
+        id: copy_list
+        text: Copy shopping list
+        variant: outline
+        action: {kind: copy, target: guests}
+      - type: button
+        id: copy_note
+        text: Copy note
+        action: {kind: copy, text: "Lamb 2 kg, carrots 8, mint sauce."}
+```
+
+`blockPlainText(block, {datasets?, checked?})` turns a target block into the copied text. Lines
+are joined with `\n`, with no trailing newline.
+
+| Block | Text |
+| --- | --- |
+| `stepper` | `<label>: <value> <unit>`, then one `<item label>: <amount> <unit>` line per item. Amounts use the item's `decimals` (2 at 1 decimal is `2.0`). A missing unit leaves no trailing space. For the example above: `Number of people: 5 People`, `Bone-in leg of lamb: 2.0 kg`, `Carrots: 8` |
+| `checklist` | One `[x] <text>` or `[ ] <text>` line per item. `checked` maps item ids to the current ticks and overrides each item's `checked`; ids the checklist lacks are ignored |
+| `list` | One `- <title>: <text>` line per item, or `- <title>` when the item has no text |
+| `table` | A header row of column names (the table's `columns` in order, or every dataset column) with each `_` shown as a space, as the table on screen shows them (`lamb_kg` is `lamb kg`), then one row per dataset row, tab-separated. A `null` cell is empty. The table's dataset must be inline in `datasets`; a missing dataset or an unresolved `ref` returns an empty string, so resolve refs first |
+| `text` | The `markdown` as written |
+
+Any other block returns an empty string. Pass the block as it is shown, with a host's
+replacement block applied, so a stepper at 6 copies the scaled amounts.
+
+`BlocksView` performs the copy on the device. A press builds the text with `blockPlainText`
+from the target as it is shown now (the host's override, the device's checklist ticks, and the
+table's selected dataset once it has rows), writes it with `expo-clipboard`, and shows "Copied"
+next to the button for 2 seconds. It never calls `onAction`. See
+[BlocksView](./ui.md#blocksview).
 
 ## Partial parsing
 
@@ -122,6 +326,21 @@ Unknown fields fail with `UNKNOWN_KEY`. `v` must be `1` (`UNSUPPORTED_VERSION`).
 | `columns` children | 2–4 |
 | Elements in one `actions` block | 25 |
 | Text in one `text` block | 4,000 characters |
+| Items in one `stepper` | 12 |
+| `stepper` id | 54 characters |
+| Items in one `checklist` | 1–30 |
+| `checklist` id | 31 characters |
+| `checklist` item id | 32 characters |
+| Images in one `gallery` | 2–6 |
+| `gallery` image `alt` | 200 characters |
+| `gallery` image `caption` | 120 characters |
+| Items in one `list` | 1–12 |
+| `list` item `title` | 120 characters |
+| `list` item `text` | 500 characters |
+| `list` item `meta` | 40 characters |
+| `list` item image `alt` | 200 characters |
+| `card` `eyebrow` | 60 characters |
+| `copy` action `text` | 4,000 characters |
 | Document version | 1 |
 
 ## Errors
@@ -134,19 +353,21 @@ heuristics and does not fail `ok`.
 | --- | --- |
 | `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. |
+| `COPY_TARGET_INVALID` | A copy action's `target` names a block that is not a `stepper`, `checklist`, `list`, `table`, or `text` block, or an id no block in the document has. |
 | `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. |
+| `DUPLICATE_ID` | A block id, an action-element id, or a column name is used more than once, an id takes a stepper's `<id>_decrease` or `<id>_increase` or a checklist's `<id>_<item id>`, or a checklist repeats an item id. |
 | `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. |
+| `IMAGE_HOST_NOT_ALLOWED` | An `image`, `gallery` tile, or `list` item image URL is not a `data:image` URL, a `file:` ref, or an `https` URL on an allowed host. A gallery error names the tile (`blocks[0].images[2].src`); a list error names the item (`blocks[0].items[1].image.src`). |
 | `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. |
+| `INVALID_TYPE` | A value has the wrong type, including a ref `limit` below 1. |
 | `KEY_ORDER` | Top-level keys are not in the order `v`, `datasets`, `blocks`. |
-| `MISSING_REQUIRED` | A required field is missing. |
+| `MISSING_REQUIRED` | A required field is missing, or an `open` or `copy` action sets neither or both of its two fields. |
 | `NOT_A_DOCUMENT` | The reply is not one YAML or JSON mapping with a `v` field. |
+| `OUT_OF_RANGE` | A number is outside its allowed range: a stepper `value` outside `min` and `max`, `min` not below `max`, `step` at or below 0, or `decimals` below 0 or above 3. |
 | `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. |
@@ -167,12 +388,23 @@ heuristics and does not fail `ok`.
 | --- | --- |
 | `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. |
+| `validateBlocks(doc, options?)` | Structure, then dataset, chart, table, action, stepper, checklist, image, gallery, and list image src, and html lint. `options.knownDatasets` checks `ref` columns. `options.hostActions` checks callback names. `options.stepperActions` and `options.checklistActions`, when set, check stepper and checklist `callback.name` instead (`UNKNOWN_HOST_ACTION`). `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. |
+| `blocksPromptSection({hostActions, allowHtml, imageHosts, richBlocks, stepperActions, checklistActions})` | System-prompt section. Limits come from `BLOCK_LIMITS`. `allowHtml` adds the `html` block. `richBlocks` (default `true`) offers the rich blocks; `false` returns the prompt as it was before them, whatever the other lists hold. With `richBlocks` on and a non-empty `stepperActions`, the prompt adds `stepper`, its rules and limits, and names those actions as its callbacks; without one it never mentions `stepper`. With `richBlocks` on, the prompt adds `checklist`, `gallery`, and `list` with their limits, plus the `card` `eyebrow` and its limit; gallery tile and list item image srcs follow the same image src line as `image`, so `https` is offered only with `imageHosts`. The word `list` appears in the prompt only as this block's name. A non-empty `checklistActions` is named as the callback to set; without one the prompt says to leave `callback` out, so ticks stay local. With `richBlocks` on, one line offers the `copy` action with its text limit and its target block types, naming `stepper` only when the stepper is offered. |
 | `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` |
+| `stepperElementIds(id)` | `{decrease, increase}`: the element ids of a stepper's buttons |
+| `checklistElementId(id, itemId)` | `<id>_<item id>`: the element id of a checklist item's tick. `ChecklistBlock`, `ChecklistItem`, and `ChecklistCallback` are type exports. |
+| `scaleStepperBlock(original, value)` | The stepper at `value` with each item's `amount` scaled linearly from `original` (`amount × value / original value`), rounded to its `decimals` (`round: up` rounds up). An `original` with `value: 0` keeps its amounts. Always pass the block the agent wrote, so rounding does not drift. `scaleStepperHostAction` and the demo playground use it |
+| `isStepperValueAllowed(stepper, value)` | `true` when `value` is finite, within `min` and `max`, and a whole number of `step`s from the stepper's `value` |
+| `applyChecklistState(checklist, {itemId, checked, state})` | The checklist with each item's `checked` from `state`; an item missing from `state` is unchecked and `itemId` takes `checked`. `toggleChecklistHostAction` and the demo playground use it. `ChecklistTick` is a type export |
+| `unknownChecklistItemIds(checklist, tick)` | The ids in a tick's `itemId` and `state` that the checklist has no item for, each once |
+| `blockPlainText(block, {datasets?, checked?})` | The text a copy action copies for its target block (see [Copy](#copy)). `BlockPlainTextOptions` is a type export |
+| `COPY_TARGET_TYPES` | `stepper`, `checklist`, `list`, `table`, `text`: the blocks a copy `target` may name. `CopyAction` is a type export |
+| `GalleryBlock`, `GalleryImage` | Type exports for the `gallery` block and its tiles |
+| `ListBlock`, `ListItem`, `ListItemImage` | Type exports for the `list` block, its items, and their thumbnails |
+| `STEPPER_ROUNDING` | `nearest`, `up`. `StepperBlock`, `StepperItem`, and `StepperCallback` are type exports. |
 | `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

@@ -136,9 +136,12 @@ Resolution order for API base URL (`rtk/src/constants.ts`):
 | Variable | Read by | Required | Default | Secret | Scope |
 |----------|---------|----------|---------|--------|-------|
 | `GCS_BUCKET` | example-backend, admin | ❌ | — | No | server |
+| `GCS_FOLDER_PREFIX` | example-backend `DocumentStorageApp` (`folderPrefix`) | ❌ | — | No | server |
 | `GCS_PROJECT_ID` | GCS clients | ❌ | — | No | server |
 | `GCS_SERVICE_ACCOUNT_KEY` | GCS clients | ❌ | — | Yes | server |
 
+Example-backend Cloud Run deploys set `GCS_BUCKET` (default `flourish-terreno-example-documents`). Preview deploys also set `GCS_FOLDER_PREFIX=pr-<number>/`.
+
 ## Feature flags
 
 | Variable | Read by | Required | Default | Secret | Scope |

package/src/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