@zeyos/zx 5.6.0 → 5.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (227) hide show
  1. package/CHANGELOG.md +188 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/checklist/checklist.d.ts +29 -0
  15. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  16. package/dist/types/components/composer/composer.d.ts +206 -4
  17. package/dist/types/components/composer/queue.d.ts +76 -0
  18. package/dist/types/components/copy/copy-button.d.ts +6 -4
  19. package/dist/types/components/copy/copy-input.d.ts +10 -6
  20. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  21. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  22. package/dist/types/components/dialog/dialog.d.ts +2 -2
  23. package/dist/types/components/dock/dock.d.ts +12 -3
  24. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  25. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  26. package/dist/types/components/file-item/file-item.d.ts +3 -2
  27. package/dist/types/components/file-list/file-list.d.ts +14 -8
  28. package/dist/types/components/filter/filter-model.d.ts +31 -1
  29. package/dist/types/components/filter/filter.d.ts +20 -2
  30. package/dist/types/components/finder/finder.d.ts +14 -6
  31. package/dist/types/components/flag/flag.d.ts +99 -0
  32. package/dist/types/components/grid/grid.d.ts +1 -1
  33. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  34. package/dist/types/components/launcher/launcher.d.ts +2 -0
  35. package/dist/types/components/modal/modal.d.ts +34 -8
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +41 -7
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/select/country.d.ts +106 -0
  45. package/dist/types/components/select/field-adapter.d.ts +2 -1
  46. package/dist/types/components/select/locale.d.ts +102 -0
  47. package/dist/types/components/select/select.d.ts +41 -2
  48. package/dist/types/components/sheet/sheet.d.ts +2 -2
  49. package/dist/types/components/slider/slider.d.ts +1 -0
  50. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  51. package/dist/types/components/source-list/source-list.d.ts +7 -5
  52. package/dist/types/components/split-view/split-view.d.ts +5 -3
  53. package/dist/types/components/surface/catalog.d.ts +260 -0
  54. package/dist/types/components/surface/elicit.d.ts +81 -0
  55. package/dist/types/components/surface/mcp.d.ts +165 -0
  56. package/dist/types/components/surface/schema.d.ts +314 -0
  57. package/dist/types/components/surface/stream.d.ts +118 -0
  58. package/dist/types/components/surface/surface.d.ts +718 -0
  59. package/dist/types/components/surface/text.d.ts +277 -0
  60. package/dist/types/components/surface/validate.d.ts +339 -0
  61. package/dist/types/components/table/table.d.ts +55 -3
  62. package/dist/types/components/table/window.d.ts +203 -0
  63. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  64. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  65. package/dist/types/components/tree/tree.d.ts +20 -13
  66. package/dist/types/core/component.d.ts +10 -0
  67. package/dist/types/core/date.d.ts +8 -1
  68. package/dist/types/core/dom.d.ts +15 -0
  69. package/dist/types/core/http.d.ts +10 -0
  70. package/dist/types/core/i18n.d.ts +38 -0
  71. package/dist/types/core/messages.d.ts +344 -1
  72. package/dist/types/core/storage.d.ts +7 -2
  73. package/dist/types/elements/define.d.ts +21 -46
  74. package/dist/types/elements/definitions.d.ts +147 -0
  75. package/dist/types/elements/kit.d.ts +7 -0
  76. package/dist/types/elements/reflect.d.ts +6 -3
  77. package/dist/types/index.d.ts +10 -1
  78. package/dist/types/internal/date-locale.d.ts +7 -0
  79. package/dist/types/internal/json-patch.d.ts +146 -0
  80. package/dist/types/locales/de.d.ts +13 -0
  81. package/dist/types/locales/en.d.ts +2 -0
  82. package/dist/types/locales/index.d.ts +823 -0
  83. package/dist/types/zeyos/view.d.ts +8 -1
  84. package/dist/zx-zeyos.esm.js +16852 -15131
  85. package/dist/zx-zeyos.esm.min.js +5 -5
  86. package/dist/zx.core.css +1276 -0
  87. package/dist/zx.core.min.css +1 -0
  88. package/dist/zx.css +520 -143
  89. package/dist/zx.esm.js +40940 -29684
  90. package/dist/zx.esm.min.js +36 -23
  91. package/dist/zx.global.js +40940 -29684
  92. package/dist/zx.global.min.js +36 -23
  93. package/dist/zx.layered.css +17315 -0
  94. package/dist/zx.layered.min.css +1 -0
  95. package/dist/zx.min.css +1 -1
  96. package/docs/agent-catalog.json +12501 -0
  97. package/docs/agent-surfaces.md +340 -0
  98. package/docs/api.json +909 -137
  99. package/docs/llms.md +1046 -80
  100. package/docs/llms.txt +30 -9
  101. package/package.json +29 -6
  102. package/src/components/account-menu/account-menu.js +6 -3
  103. package/src/components/activity-item/activity-item.js +2 -1
  104. package/src/components/activity-list/activity-list.js +16 -10
  105. package/src/components/agent-thread/ag-ui.js +1439 -0
  106. package/src/components/agent-thread/agent-thread.js +359 -54
  107. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  108. package/src/components/app-sidebar/app-sidebar.js +18 -8
  109. package/src/components/approval-card/approval-card.js +3 -2
  110. package/src/components/block-view/block-view.js +7 -6
  111. package/src/components/breadcrumb/breadcrumb.js +8 -5
  112. package/src/components/button/button.css +24 -11
  113. package/src/components/calendar/calendar-model.js +8 -2
  114. package/src/components/calendar/calendar.js +53 -18
  115. package/src/components/chart/chart.js +54 -23
  116. package/src/components/checklist/checklist.css +9 -1
  117. package/src/components/checklist/checklist.js +59 -3
  118. package/src/components/checklist/field-adapter.js +2 -11
  119. package/src/components/code-editor/code-editor.js +45 -8
  120. package/src/components/code-editor/field-adapter.js +1 -1
  121. package/src/components/composer/composer.css +80 -1
  122. package/src/components/composer/composer.js +390 -16
  123. package/src/components/composer/queue.js +78 -0
  124. package/src/components/context-menu/context-menu.js +12 -1
  125. package/src/components/copy/copy-button.js +9 -7
  126. package/src/components/copy/copy-input.js +10 -6
  127. package/src/components/date-picker/date-picker.js +2 -1
  128. package/src/components/date-picker/date-range-picker.js +8 -7
  129. package/src/components/datebox/date-range-box.js +3 -9
  130. package/src/components/datebox/datebox.js +18 -21
  131. package/src/components/datebox/placeholder.js +18 -0
  132. package/src/components/dialog/dialog.js +4 -5
  133. package/src/components/dock/dock.js +34 -13
  134. package/src/components/entity-ref/entity-ref.js +16 -5
  135. package/src/components/field-upload/field-upload.js +81 -38
  136. package/src/components/file-item/file-item.js +70 -40
  137. package/src/components/file-list/file-list.js +15 -9
  138. package/src/components/filter/filter-model.js +46 -8
  139. package/src/components/filter/filter.css +3 -3
  140. package/src/components/filter/filter.js +29 -10
  141. package/src/components/filter-panel/filter-panel.js +13 -5
  142. package/src/components/finder/finder.js +50 -26
  143. package/src/components/flag/flag.css +40 -0
  144. package/src/components/flag/flag.js +177 -0
  145. package/src/components/form/form.js +1 -1
  146. package/src/components/grid/grid.js +22 -8
  147. package/src/components/kanban-view/kanban-view.js +51 -81
  148. package/src/components/launcher/launcher.js +17 -2
  149. package/src/components/list-toolbar/list-toolbar.js +2 -1
  150. package/src/components/master-panel/master-panel.js +1 -1
  151. package/src/components/menu-button/menu-button.js +4 -0
  152. package/src/components/message/message.js +3 -0
  153. package/src/components/modal/modal.js +62 -8
  154. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  155. package/src/components/navigation-bar/navigation-bar.js +3 -3
  156. package/src/components/number-field/number-field.js +98 -29
  157. package/src/components/prompt-starters/prompt-starters.css +91 -0
  158. package/src/components/prompt-starters/prompt-starters.js +206 -0
  159. package/src/components/prose/prose.js +14 -10
  160. package/src/components/questionnaire/conditions.js +666 -0
  161. package/src/components/questionnaire/items.js +150 -41
  162. package/src/components/questionnaire/questionnaire.js +126 -32
  163. package/src/components/rating/rating.js +5 -4
  164. package/src/components/run-status/run-status.js +2 -2
  165. package/src/components/select/country.js +136 -0
  166. package/src/components/select/field-adapter.js +7 -2
  167. package/src/components/select/locale.js +219 -0
  168. package/src/components/select/select.css +20 -22
  169. package/src/components/select/select.js +94 -12
  170. package/src/components/sheet/sheet-stack.js +10 -1
  171. package/src/components/sheet/sheet.js +12 -5
  172. package/src/components/slider/slider.js +7 -2
  173. package/src/components/sort-control/sort-control.js +15 -5
  174. package/src/components/source-list/source-list.js +7 -4
  175. package/src/components/split-view/split-view.js +5 -3
  176. package/src/components/surface/catalog.js +1334 -0
  177. package/src/components/surface/elicit.js +107 -0
  178. package/src/components/surface/mcp.js +243 -0
  179. package/src/components/surface/schema.js +644 -0
  180. package/src/components/surface/stream.js +245 -0
  181. package/src/components/surface/surface.css +308 -0
  182. package/src/components/surface/surface.js +2291 -0
  183. package/src/components/surface/text.js +513 -0
  184. package/src/components/surface/validate.js +2218 -0
  185. package/src/components/tabbox/tabbox.js +9 -0
  186. package/src/components/table/table.css +63 -3
  187. package/src/components/table/table.js +167 -28
  188. package/src/components/table/window.js +317 -0
  189. package/src/components/toolbar/toolbar.js +12 -7
  190. package/src/components/tooltip/tooltip.css +2 -3
  191. package/src/components/tooltip/tooltip.js +32 -5
  192. package/src/components/tree/tree.js +53 -23
  193. package/src/core/component.js +25 -1
  194. package/src/core/date.js +62 -16
  195. package/src/core/dom.js +67 -4
  196. package/src/core/format.js +15 -13
  197. package/src/core/http.js +29 -20
  198. package/src/core/i18n.js +83 -10
  199. package/src/core/icons.js +13 -2
  200. package/src/core/keyboard.js +79 -8
  201. package/src/core/messages.js +376 -2
  202. package/src/core/overlay-host.js +1 -0
  203. package/src/core/position.js +3 -2
  204. package/src/core/storage.js +59 -6
  205. package/src/elements/define.js +178 -130
  206. package/src/elements/definitions.js +229 -0
  207. package/src/elements/kit.js +444 -0
  208. package/src/elements/reflect.js +8 -3
  209. package/src/index.js +10 -1
  210. package/src/internal/date-locale.js +11 -0
  211. package/src/internal/json-patch.js +405 -0
  212. package/src/locales/de.js +911 -0
  213. package/src/locales/en.js +2 -0
  214. package/src/locales/index.js +7 -0
  215. package/src/zeyos/calendar.js +2 -1
  216. package/src/zeyos/form.js +2 -1
  217. package/src/zeyos/launcher.js +7 -6
  218. package/src/zeyos/module-bar.js +2 -1
  219. package/src/zeyos/schema.js +37 -23
  220. package/src/zeyos/select.js +4 -3
  221. package/src/zeyos/table.js +2 -13
  222. package/src/zeyos/view.js +57 -17
  223. package/styles/core.css +11 -0
  224. package/styles/tokens/semantic.css +1 -0
  225. package/styles/zeyos.css +2 -0
  226. package/styles/zx.css +4 -8
  227. package/styles/zx.layered.css +1 -0
package/docs/llms.md CHANGED
@@ -9,6 +9,18 @@
9
9
  > component below is wrapped in `<!-- doc:<name> -->` markers so tools can extract a single
10
10
  > component's section (`website/docs.html` renders them as each component's Reference tab).
11
11
 
12
+ ## Optional integration requirements
13
+
14
+ Zx has no package runtime dependencies and its source modules import no external runtime packages.
15
+ Optional integrations still need application-provided assets or clients. `Chart` requires an injected
16
+ renderer; the only supplied renderer, `ChartJsAdapter`, requires Chart.js 4 supplied by the host.
17
+ There is no built-in chart renderer. Chart.js 4.5.1 is pinned as a development dependency and copied
18
+ to the documentation site's self-hosted vendor assets during its build; it is not bundled into Zx.
19
+ Core icons use bundled SVG by default. Opting into Font Awesome requires host-loaded CSS or a kit.
20
+ ZeyOS `moduleIcon()`, `moduleChip()`, and `zeyosAppIcon()` default to glyphs from the external custom
21
+ ZeyOS Font Awesome kit; `standard: true` still needs stock Font Awesome assets. `ZeyOS.connect()`
22
+ requires an injected compatible client and never imports the client package.
23
+
12
24
  ## Mental model
13
25
 
14
26
  Every visual component is an ES class extending `Component`, instantiated identically:
@@ -44,11 +56,52 @@ const t = new Table(target, options);
44
56
  - ESM: `import { … } from '/assets/zx.esm.js'` (or `../src/index.js` in-repo, no build).
45
57
  - Granular: `import { Slider } from '@zeyos/zx/src/components/slider/slider.js'` — one component
46
58
  rather than the whole library, for consumers running a bundler. Two components bundle 26 kB
47
- minified against 157 kB through the package entry. The stylesheet is still loaded whole.
59
+ minified against 157 kB through the package entry. `zx-css` does the same for the stylesheet.
48
60
  - Global: `<script src="/assets/zx.global.js">` → `window.zx.*`.
49
- - Styles: load `/assets/zx.css` once.
61
+ - Styles: load `/assets/zx.css` once, or one of the stylesheets below.
50
62
  - Build bundles with `npm run build` (esbuild). No build is needed to develop against `src/`.
51
63
 
64
+ Use one entry family for component instances and their registrations: source modules share the
65
+ source `Field` registry, while each distribution bundle contains its own classes and registry.
66
+ An adapter registered through a distribution bundle does not register a separately imported source
67
+ `Field`; import the related components from the same entry family.
68
+
69
+ ### Stylesheets
70
+
71
+ | Load | It holds | Choose it when |
72
+ | --- | --- | --- |
73
+ | `@zeyos/zx/zx.css`, `zx.min.css` | the whole library | the default |
74
+ | a file written by `zx-css` | the core sheet and the components named, with what they depend on | an application uses a few components |
75
+ | `@zeyos/zx/zx.layered.css` | the whole library in `@layer zx` | the application's own CSS should win without specificity work |
76
+ | `@zeyos/zx/zx.core.css`, `zx.core.min.css` | tokens, base rules, icons, reading type | composing stylesheets by hand |
77
+ | `@zeyos/zx/src/components/select/select.css` | one component's own rules | composing stylesheets by hand |
78
+ | `@zeyos/zx/styles/zeyos.css` | ZeyOS module colours | optional product palette for the ZeyOS binding |
79
+
80
+ **`zx-css`** ships with the package and runs on Node alone:
81
+
82
+ ```sh
83
+ npx zx-css select table --out public/zx.css # one stylesheet for these components
84
+ npx zx-css select table --out public/zx.css --min --layer
85
+ npx zx-css select table --list # the files it contains, in order
86
+ ```
87
+
88
+ The file starts with the core sheet, then every stylesheet the components reach, in `zx.css` order,
89
+ each once. A component reaches another by importing it, and by naming a `zx-<block>` class in the
90
+ source of any module it imports, because a component may draw another's markup without importing it.
91
+ A name is the file name of a stylesheet under `src/components/`: `select`, `progress-bar`,
92
+ `button` for `button()`, `layout` for `stack()` and `grid()`. An unknown name fails and lists the
93
+ known ones. Name what the page draws by hand as well: a `Form` that uses `type: 'zxselect'` needs
94
+ `form select`, because a field type is registered at run time, not imported. The print rules are not
95
+ part of a subset: a page that prints loads `@zeyos/zx/styles/print.css` after it.
96
+
97
+ **The layered build** puts the whole library in `@layer zx`, and an unlayered rule beats any layered
98
+ one whatever its specificity, so `button { padding: 0 }` overrides `.zx-btn[data-size="sm"]` with no
99
+ `!important`. The trade-off is that this holds for every unlayered rule on the page, not just the
100
+ application's: a reset or a third-party stylesheet that is not in a layer overrides Zx just as
101
+ easily. Choose `zx.layered.css` (or `zx-css --layer`) when the application controls the CSS on its
102
+ pages, and stay on `zx.css` when it does not. `!important` turns the other way round: one inside the
103
+ layer beats an unlayered one.
104
+
52
105
  ## Choosing what to build with
53
106
 
54
107
  Three decisions come before any code: which **layout** the screen is, which **component** does
@@ -422,6 +475,10 @@ await zeyos.api.updateTransaction({ ID, status: 9 });
422
475
  Feed results straight into Zx components (Table `data`, Select `items`, Form values). See the
423
476
  `website/layouts/zeyos-invoices.layout.js` layout for the reference integration. Zx also ships a minimal `Http` /
424
477
  `zeyosService(service, accesskey)` for ad-hoc `remotecall`, but `@zeyos/client` is the default.
478
+ `Http.request(path, options)` accepts a caller `signal` and multipart `paramName` (default
479
+ `'files'`). Caller cancellation aborts the request; the client's timeout rejects with
480
+ `TimeoutError`. Legacy envelopes with `error: false`, `0`, `null`, or no error return `result`;
481
+ string and object errors reject.
425
482
 
426
483
  <!-- doc:zeyos -->
427
484
  ## ZeyOS binding (zx-zeyos)
@@ -505,6 +562,12 @@ await records.saveView({ name: 'My open invoices', setDefault: true });
505
562
  paging and server sort. Paging is the same loader as `zeyosTable()` — same `pageSize: 50` default,
506
563
  validation, `replace`/`pageSize` load options, and destroy guard. Title, preview, group, column, and swim-lane fields stay in the projection
507
564
  even when hidden. Without `savedViews`, the host may persist `view.getViewState()` directly.
565
+ `savedViewFallback: 'error'` is the default: a saved-view initialization failure blocks loads.
566
+ Opt into `'baseline'` to load records using the configured query and sort when the registry
567
+ cannot be read. The failure is reported and `ready` still rejects; capture, save, apply, and
568
+ default restoration remain blocked. Later operations retry initialization so repaired storage
569
+ can restore its default. The unreadable document is never rewritten automatically, and a
570
+ failure while applying a view or query cannot fall back.
508
571
  - `createSavedViewRegistry(transport, {userId,workspaceId,resource})` coordinates private named
509
572
  Table/Card/Kanban configurations as one versioned, atomically replaced document. Entries capture
510
573
  component state plus filters/search and an explicit presentation type, never records, selection,
@@ -563,7 +626,8 @@ registerModules({ tickets: '#f04639', 'my-fork': { label: 'My Fork', icon: 'zeyo
563
626
  ```
564
627
 
565
628
  - `moduleIcon(name, {size, label, standard})` → the bare glyph; `standard: true` uses the stock
566
- Font Awesome fallback, for pages on a kit without the ZeyOS uploads.
629
+ Font Awesome fallback, for pages on a kit without the ZeyOS uploads. Stock Font Awesome
630
+ CSS or kit assets must still be loaded by the host.
567
631
  - `moduleChip(name, {size, iconSize, label, title, standard})` → `<span class="zx-module-icon">`
568
632
  with a centred white glyph on the module colour. `moduleGlyphColor(hex)` remains available as a
569
633
  separate contrast helper for non-AppIcon integrations that deliberately choose their foreground.
@@ -616,7 +680,10 @@ new ModuleBar(header, buildZeyosModuleBarConfig(state, { orientation: 'horizonta
616
680
  `defineElements()` (not auto-called) registers light-DOM `<zx-*>` wrappers with attribute↔option
617
681
  reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-button>`, `<zx-select>`,
618
682
  `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
619
- `<zx-table>`, `<zx-dialog>`.
683
+ `<zx-table>`, `<zx-dialog>`. The agent kit and the data views are elements too, with forwarded
684
+ methods and events under their plain names: `<zx-agent-thread>`, `<zx-composer>`, `<zx-block-view>`,
685
+ `<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`, `<zx-run-status>`, `<zx-card-view>`,
686
+ `<zx-kanban-view>`, `<zx-tree>`, `<zx-chart>`.
620
687
 
621
688
  ---
622
689
 
@@ -701,7 +768,9 @@ accept.
701
768
  `--zx-color-accent-solid*` roles, so in dark it keeps the deep stop with white ink rather than a
702
769
  bright slab. A `ghost` button's icon is drawn in `--zx-color-text-subtle` until hovered. A button
703
770
  with `aria-pressed="true"` (a Toolbar item with `active`, a view toggle) is a mode, not a pick:
704
- it takes the neutral `--zx-color-bg-current` fill and the text colour, never the accent.
771
+ it stays neutral, never the accent, and is drawn with a stronger fill plus a frame in
772
+ `--zx-color-text-subtle` (3:1 against its neighbours in both themes), so a pressed segment of a
773
+ `buttonGroup` is told apart without relying on the fill alone.
705
774
  <!-- /doc -->
706
775
 
707
776
  <!-- doc:badge -->
@@ -749,9 +818,9 @@ items that overflow — removing them from the tab order and the roving group
749
818
  a `MenuButton`, where choosing one activates the original control.
750
819
 
751
820
  - **Options** — `items: [Element | '-' | {name, label, icon, kind, size, disabled, title, active,
752
- onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, default `'Toolbar'`),
753
- `overflow` (default `true`), `overflowLabel` (default `'More'`), `dense`. `active` renders the
754
- item as a pressed toggle (`aria-pressed`).
821
+ onclick}]`, `align: 'start'|'end'|'between'`, `label` (accessible name, by default the `toolbar.label` message),
822
+ `overflow` (default `true`), `overflowLabel` (by default the `toolbar.more` message), `dense`; `null` gives either
823
+ no name. `active` renders the item as a pressed toggle (`aria-pressed`).
755
824
  - **Methods** — `setItems()`, `getItem(name)`, `enable(name)`, `disable(name)`,
756
825
  `setActive(name, active?)`, `destroy()`.
757
826
  - **Events** — `action {name, item}`, emitted for descriptor-built items in addition to their own
@@ -760,8 +829,8 @@ a `MenuButton`, where choosing one activates the original control.
760
829
  in visual order under `dir="rtl"`; Home/End jump to the first and last control. A text field, select,
761
830
  or contenteditable item keeps its own keys: Home/End and the arrows move its caret, and an arrow
762
831
  moves on to the neighbouring control only once the caret is at that edge of the text.
763
- - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes the neutral
764
- `--zx-color-bg-current` fill, never the accent.
832
+ - **Pressed items** — an item with `active` renders `aria-pressed="true"` and takes Button's
833
+ neutral pressed fill and frame, never the accent.
765
834
  <!-- /doc -->
766
835
 
767
836
  <!-- doc:empty-state -->
@@ -1081,8 +1150,9 @@ preview, or persists a file.
1081
1150
  An accessible ordered collection of `FileItem` rows with loading and empty presentations.
1082
1151
  Explicit duplicate file IDs are rejected; source order is preserved.
1083
1152
 
1084
- - **Options** — `items`, `label: 'Files'`, `loading`, `loadingCount: 3`,
1085
- `loadingText: 'Loading files'`, and `emptyText: 'No files'` (text, Node, or Component).
1153
+ - **Options** — `items`, `label`, `loading`, `loadingCount: 3`, `loadingText`, and `emptyText` (text,
1154
+ Node, or Component). Unset, the three read the `fileList.*` messages; `loadingText` or `emptyText`
1155
+ set to `null` shows no text.
1086
1156
  - **Methods** — `setItems(items,{silent?})`, `getItems()`, `getItem(id)`,
1087
1157
  `addItem(item,index?,{silent?})`, `updateItem(id,values,{silent?})`,
1088
1158
  `removeItem(id,{silent?})`, `setLoading()`, and `destroy()`.
@@ -1124,8 +1194,9 @@ incremental host-controlled mutation. It deliberately preserves source order ins
1124
1194
  whether a feed is newest- or oldest-first.
1125
1195
 
1126
1196
  - **Options** — `items`, `groupBy` (property, resolver, or null), `groupLabel`,
1127
- `label: 'Activity'`, `variant: 'default'|'compact'`, `loading`, `loadingCount: 3`,
1128
- `loadingText`, `emptyText`, `groupHeadingLevel`, and `itemHeadingLevel`.
1197
+ `label`, `variant: 'default'|'compact'`, `loading`, `loadingCount: 3`, `loadingText`, `emptyText`,
1198
+ `groupHeadingLevel`, and `itemHeadingLevel`. Unset, `label`, `loadingText` and `emptyText` read the
1199
+ `activityList.*` messages; `loadingText` or `emptyText` set to `null` shows no text.
1129
1200
  - **Compact** — `variant: 'compact'` (reflected as `data-variant`) keeps every entry on one line at
1130
1201
  any width, for a summary card narrower than 30rem: actor and title read as one sentence that
1131
1202
  wraps as text, the time keeps the trailing end instead of stacking under the title, an avatar
@@ -1271,6 +1342,68 @@ Unifies single-select, local filtering, and async loading.
1271
1342
  as a disabled Field does, and not a second time inside one.
1272
1343
  - **Quiet fields** — inside `[data-zx-fields="quiet"]` the value reads as text: no border, fill,
1273
1344
  chevron or clear button until hover; full field chrome while focused or open.
1345
+
1346
+ #### Select.locale()
1347
+
1348
+ `Select.locale(target, options)` returns an ordinary Select: each locale is named in its own language ("Deutsch") with the interface's
1349
+ name for it beneath ("German"), and the flag of its region or a language chip before it. Names come
1350
+ from `Intl.DisplayNames`, so no translation table ships. The value is the canonical BCP 47 tag
1351
+ (`'de-AT'`); `set()` and `value` accept any spelling of a listed tag (`'de_at'`). Everything else —
1352
+ keyboard map, events, `clearable`, `disabled`, `msg` — is Select's. Field type: `zxselect` with
1353
+ `props.preset: 'locale'`.
1354
+
1355
+ The picker supplies locale names, not translations for the application. It emits `change` without
1356
+ changing the active language. See the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales)
1357
+ for catalogues, message variables, formatting, and runtime language switching.
1358
+
1359
+ ```js
1360
+ Select.locale(el, { locales: ['en-GB', 'de', 'de-AT', 'fr'], value: 'de' });
1361
+ ```
1362
+
1363
+ - **Options** — `locales` (tags or `{code, name?, description?, region?}`; invalid tags are left
1364
+ out; a short list of common languages by default), `preferred: []` and `preferredLabel` (pinned
1365
+ above the list), `displayLocale` (default: the `lang` option, then `getLanguage()`),
1366
+ `display: 'both'|'native'|'localized'`, `flags: 'auto'|'emoji'|'code'|'none'|(region, item) => Node`,
1367
+ `flagUrl` (image template, `{code}`/`{CODE}`), `flagRegions` (`{ en: 'GB' }` — a language's flag
1368
+ when its likely region is not the one meant), `sort: false`, plus Select options. Message overrides
1369
+ retain the `localePicker.*` keys. A list longer
1370
+ than seven filters locally by native name, localized name, and tag.
1371
+ - **Flags** — a full-tag `flagRegions` override wins, then the tag's own region (`de-AT` → Austria),
1372
+ then a language-level override, then the language's likely region (`Intl.Locale#maximize()`:
1373
+ `ja` → Japan). A locale with no country (`es-419`) shows
1374
+ its language chip. `flags: 'code'` shows chips throughout — the honest choice where a language is
1375
+ not a country.
1376
+ - **Statics** — `Select.localeItems(locales, options)` returns the rows without the DOM;
1377
+ `canonicalLocale(tag)` canonicalizes one tag.
1378
+
1379
+ #### Select.country()
1380
+
1381
+ `Select.country(target, options)` returns an ordinary Select: a filterable list of ISO 3166-1 countries, named in the interface's language by
1382
+ `Intl.DisplayNames` and drawn with their flags. The value is the upper-case alpha-2 code (`'DE'`);
1383
+ `set()` accepts either case. Search matches the name, the code, and the English name, so "Germany"
1384
+ finds Deutschland in a German interface. Field type: `zxselect` with `props.preset: 'country'`.
1385
+ Custom descriptions are searchable too. Its `displayLocale` names countries without changing the
1386
+ application language; see the [Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
1387
+
1388
+ ```js
1389
+ Select.country(el, { preferred: ['DE', 'AT', 'CH'], value: 'AT', clearable: true });
1390
+ ```
1391
+
1392
+ - **Options** — `countries` (codes or `{code, name?, description?}`; all of `COUNTRY_CODES` by
1393
+ default), `preferred: []` and `preferredLabel`, `displayLocale`, `flags`, `flagUrl`,
1394
+ `showCode: false`, `sort: true` (by name, with `Intl.Collator`), plus Select options. Message
1395
+ overrides retain the `countryPicker.*` keys.
1396
+ - **Statics** — `Select.countryItems(countries, options)` returns the rows without the DOM.
1397
+
1398
+ #### flag()
1399
+
1400
+ `flag(code, { kind, src, text, label })` draws one flag as a `.zx-flag` span — for a picker row, a
1401
+ table cell, a profile. `kind: 'auto'` (default) draws the platform's flag emoji where it has them
1402
+ (`supportsFlagEmoji()`) and a muted code chip where it does not (Windows); `'emoji'`, `'code'`, and
1403
+ `'image'` force one. Zx ships no flag artwork: `src: '/flags/{code}.svg'` draws from any flag set
1404
+ the application serves. Decorative (`aria-hidden`) unless `label` is given. Also exported:
1405
+ `flagEmoji(code)`, `supportsFlagEmoji()`, and `COUNTRY_CODES`.
1406
+
1274
1407
  <!-- /doc -->
1275
1408
 
1276
1409
  <!-- doc:sort-control -->
@@ -1281,7 +1414,8 @@ appears once. Changing fields preserves direction; toggling direction preserves
1281
1414
  from `Select`, with its themed popover and keyboard behavior.
1282
1415
 
1283
1416
  - **Options** — `fields: [{id,label}]`, `value: {id,dir:'asc'|'desc'}` (null selects the first field
1284
- ascending), `label: 'Sort by'`, `labels: {asc,desc}` for localized direction text, `disabled`.
1417
+ ascending), `label` (by default the `sortControl.label` message, and `null` gives no name), `labels: {asc,desc}` to override
1418
+ the `sortControl.ascending` and `sortControl.descending` messages, `disabled`.
1285
1419
  - **Methods** — defensive `getValue()`, `setValue(value,{silent})`, `enable()`, `disable()`,
1286
1420
  `focus()`, `destroy()`. Unknown fields or directions are rejected. An empty catalogue disables
1287
1421
  selection and returns null.
@@ -1298,12 +1432,15 @@ from `Select`, with its themed popover and keyboard behavior.
1298
1432
  Searchable multi-check list with optional async loading.
1299
1433
 
1300
1434
  - **Options** — `items`, `valueKey: 'ID'`, `labelKey: 'name'`, `checkedKey: 'on'`, `search: true`,
1301
- `height: 280`, `defaultChecked: false`, `hideLabel: false` (leaves out the heading; the group
1302
- keeps its text as `aria-label`), `load: async ()=>items`.
1435
+ `height: 280`, `defaultChecked: false`, `label: null` (heading text and the group's accessible
1436
+ name; null uses the `checklist.label` message), `disabled: false`, `hideLabel: false` (leaves out
1437
+ the heading; the group keeps its text as `aria-label`), `load: async ()=>items`.
1303
1438
  - **In a Field** — field type `checklist` draws no heading of its own: the field's label names the
1304
1439
  group (`aria-labelledby`).
1305
1440
  - **Methods** — `setItems()`, `getValues()`, `setValues(ids)`, `checkAll()`/`uncheckAll()`,
1306
- `search(query)`, `reload()`.
1441
+ `search(query)`, `reload()`, `setLabel(text)`, `enable()`/`disable()`, `isDisabled()`. Disabled,
1442
+ the search field and every checkbox are disabled (`aria-disabled="true"` on the group) through
1443
+ searches, `setItems()` and reloads; values can still be set from code.
1307
1444
  - **Events** — `change {values}`, `loaded`.
1308
1445
  <!-- /doc -->
1309
1446
 
@@ -1315,7 +1452,8 @@ buttons are `tabindex="-1"`/`aria-hidden` pointer affordances — the input itse
1315
1452
  Field type: `number`.
1316
1453
 
1317
1454
  - **Options** — `value` (number|null), `min`, `max`, `step: 1`, `largeStep: 10` (PageUp/PageDown
1318
- multiplier), `precision` (decimals; derived from `step` when null), `wrap: false` (stepping past
1455
+ multiplier), `precision` (decimals; derived from `step` when null), `snap: true` (see
1456
+ **Snapping**), `wrap: false` (stepping past
1319
1457
  a bound jumps to the other one), `placeholder`, `unit` (suffix rendered inside the control),
1320
1458
  `group: false` (thousands separators while idle), `locale`, `disabled`, `readonly`, `required`,
1321
1459
  `name`.
@@ -1323,6 +1461,11 @@ Field type: `number`.
1323
1461
  the range; `''`/null clear it), `stepUp(n)`, `stepDown(n)`, `setRange(min, max)`,
1324
1462
  `setReadonly()`, `reset()`, `focus()`, `getInput()`, `enable()`/`disable()`.
1325
1463
  - **Events** — `change {value}` (committed), `input {value}` (per keystroke, possibly unsnapped).
1464
+ - **Snapping** — by default a typed or assigned value is moved onto the `step` grid (step 2 turns
1465
+ 123 into 124) and rounded to the step's decimals. That suits quantities; it is wrong for a value
1466
+ that is not a multiple of anything — an identifier, a seed, a measurement. `snap: false` keeps
1467
+ the value exactly as entered: `step` is then only what the buttons and arrow keys add, decimals
1468
+ are rounded only to an explicit `precision`, and `min`/`max` still clamp.
1326
1469
  - **Keyboard** — ↑/↓ one step, PageUp/PageDown `largeStep` steps, Home/End jump to `min`/`max` when
1327
1470
  set (otherwise they keep their caret meaning), Enter commits, wheel steps while focused.
1328
1471
  - **Also exported** — `parseNumber(raw)` (accepts `.` and `,` as the decimal separator, ignores
@@ -1369,7 +1512,7 @@ from; everything Zx adds is chrome around it. Field type: `slider`.
1369
1512
  - **Methods** — `get()`, `set(value, {silent})`, `setRange(min, max, step?)`, `setLabel()`,
1370
1513
  `setReadonly()`, `focus()`, `enable()`/`disable()`. `value` is also a getter/setter.
1371
1514
  - **Events** — `input {value}` continuously while dragging, `change {value}` once the value is
1372
- committed (pointer released, or a key pressed).
1515
+ committed (pointer released, a range key pressed, or the optional number box committed).
1373
1516
  - **Behaviour** — values snap to the step grid anchored at `min`, so 5…95 by 10 gives 5, 15, 25 —
1374
1517
  not 10, 20, 30. Bounds win over the grid, so a `max` that is not a whole number of steps above
1375
1518
  `min` stays reachable. A fractional step snaps to the decimals it carries: 0.1 gives 0.3, never
@@ -1393,7 +1536,7 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
1393
1536
  → `HTMLButtonElement`.
1394
1537
  - **Options** — `text: ''` — a string, or **a function returning one**, which is what a button
1395
1538
  beside a live value needs so the copy is never stale; `label: ''` (empty renders an icon-only
1396
- ghost button), `title: 'Copy'`, `feedback: 'Copied'`, `feedbackDuration: 2000`,
1539
+ ghost button), `title`, `feedback` (by default the `copy.copy` and `copy.copied` messages, and `null` gives no text), `feedbackDuration: 2000`,
1397
1540
  `size: 'md'|'sm'`, `kind: 'default'|'primary'|'ghost'`.
1398
1541
  - **Events** — `oncopy(text, copied)` is called for every attempt; `copied` is `false` when the
1399
1542
  clipboard refused the write, and the button then stays untouched rather than claiming a copy
@@ -1405,8 +1548,8 @@ to a hidden textarea when the async Clipboard API is unavailable or denied.
1405
1548
 
1406
1549
  #### CopyInput
1407
1550
 
1408
- - **Options** — `value: ''`, `label: ''`, `hideLabel: false`, `feedback: 'Copied'`,
1409
- `buttonTitle: 'Copy'`, `size: 'md'|'sm'`.
1551
+ - **Options** — `value: ''`, `label: ''`, `hideLabel: false`, `feedback`, `buttonTitle` (by default
1552
+ the `copy.copied` and `copy.copy` messages, and `null` gives no text), `size: 'md'|'sm'`.
1410
1553
  - **Methods** — `get()`, `set(value)`, `focus()` (focuses and selects the whole value).
1411
1554
  - **Events** — `copy {value, copied}`.
1412
1555
  - **Behaviour** — the field is `readonly`, not `disabled`, so the text stays selectable and
@@ -1556,7 +1699,14 @@ panel material; the backdrop uses `--zx-color-overlay-backdrop`, and focus retur
1556
1699
  scope is resolved again on every `open()`; a `scope` element not yet in the document leaves the
1557
1700
  dialog detached until then, rather than parking it on `<body>` outside the theme.
1558
1701
  - **Methods** — `open()`, `close(result?)`, `setContent()`, `isOpen()`.
1559
- - **Events** — `open`, `close {result}`, `cancel` (Esc; preventable with `event.preventDefault()`).
1702
+ - **Events** — `open`, `close {result}`, `cancel {reason}`.
1703
+ - **Dismissal** — everything the reader does to dismiss an overlay raises `cancel` first, with
1704
+ `reason` `'escape'`, `'close-button'` (Dialog/Sheet header ✕), `'button'` (a footer button whose
1705
+ action is `'cancel'`), `'backdrop'` (`lightDismiss`), `'outside'` or `'drag'` (Sheet).
1706
+ `event.preventDefault()` keeps it open, which is the place for an "unsaved changes" check.
1707
+ A programmatic `close()` raises no `cancel`. Escape is handled by Zx rather than by the browser's
1708
+ close request, so preventing it holds however often the key is pressed; a handler that calls
1709
+ `preventDefault()` on the Escape keydown (a popup inside the dialog, your own) keeps the key.
1560
1710
  <!-- /doc -->
1561
1711
 
1562
1712
  <!-- doc:dialog -->
@@ -1598,7 +1748,8 @@ When a Dock adopts it, the Sheet becomes an opaque layout surface instead.
1598
1748
  - **Methods** — `open()`, `close(result?)`, `setSide(side)`, `getSide()`, `setSize(size)`,
1599
1749
  `isModal()`, `isDocked()`, `isOpen()`, `getSize()`, `snapTo(target)`, plus Dialog's `setTitle()`, `setContent()`,
1600
1750
  `setButtons()`, `addView()`, `showView()`.
1601
- - **Events** — `open`, `close {result}`, `cancel` (preventable with `event.preventDefault()`),
1751
+ - **Events** — `open`, `close {result}`, `cancel {reason}` (preventable; raised by Escape, the ✕,
1752
+ a backdrop click or outside press, and a dismissing drag — see Modal's **Dismissal**),
1602
1753
  `resize {size, ratio}`, `dockchange {docked, dock}`.
1603
1754
  - **Docked** — a sheet has two lives, and it does not choose between them: `Dock.adopt(sheet)`
1604
1755
  makes it a track in that dock's flow instead of an overlay, and the dock then owns its side,
@@ -1806,7 +1957,7 @@ parked at the pointer, so it flips near a viewport edge like every other floatin
1806
1957
  <!-- doc:tooltip -->
1807
1958
  ### Tooltip
1808
1959
 
1809
- A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble is never interactive: `pointer-events: none` keeps it from stealing the hover it depends on, and nothing inside it can take focus. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
1960
+ A description bubble anchored to another element. The panel is a manual popover positioned by the kernel's `position()`, so it escapes clipping and stacking contexts and flips near a viewport edge; it carries `role="tooltip"` and a generated id, and the anchor gets `aria-describedby` pointing at it only while it is open — closing puts the anchor's original value back, including no value at all. The bubble contains no focusable controls and stays visible while the pointer is over either the anchor or the bubble. Keyboard focus on the anchor independently keeps it visible. Hover opens it after `delay`; keyboard focus opens it immediately, because a keyboard user cannot hover a moment longer; a touch pointer never opens it, since a bubble with no "move away" gesture would simply stick. Only one is ever visible at a time, which falls out of the dismissal rules rather than a registry.
1810
1961
 
1811
1962
  - **Options** — `content` (string, Node, or a function re-evaluated on every open), `placement`
1812
1963
  (`'top'` default, plus top/bottom/left/right and their start/end variants), `offset` (6), `delay`
@@ -1815,7 +1966,7 @@ A description bubble anchored to another element. The panel is a manual popover
1815
1966
  at all and leaves everything to the methods), `disabled` (false).
1816
1967
  - **Methods** — `show()`, `hide()`, `toggle()`, `isOpen()`, `setContent(content)`, `enable()`, `disable()`, `isDisabled()`, `getAnchor()`, `destroy()`. Convenience factories: `tooltip(anchor, contentOrOptions)` takes either a content value or a full option object, and `describe(anchor, text)` is the one-liner replacement for a `title` attribute. Both return the instance.
1817
1968
  - **Events** — `open`, `close`. Both fire only on a real transition, so a `show()` on an open tooltip is silent.
1818
- - **Keyboard** — Focusing the anchor opens the tooltip at once; moving focus away closes it. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
1969
+ - **Keyboard** — Focusing the anchor opens the tooltip at once; it closes after both focus and hover have left the anchor and bubble. `Escape` closes it without moving focus (WCAG 1.4.13 "dismissible") — and only it, when it is the topmost open overlay, so one press never closes a tooltip and the menu beneath it. A `pointerdown` anywhere closes it, and focus that arrives with a click does not re-open it. A closed tooltip listens to nothing outside its anchor; an open one is an entry on the shared overlay stack.
1819
1970
  <!-- /doc -->
1820
1971
 
1821
1972
  <!-- doc:split-view -->
@@ -1849,7 +2000,7 @@ range select.
1849
2000
  type?: 'text'|'number'|'currency'|'percent'|'unit', locale?, decimals?, currency?, unit?,
1850
2001
  render?: (row,i)=>Node|string, sortValue?, headerTitle? }]`, `data`, `rowId: 'ID'`,
1851
2002
  `sort: { id, dir }`, `sortMode: 'local'|'server'`, `selectable: false|'single'|'multi'`,
1852
- `stickyHeader: true`, `height`, `emptyText`, `rowClass`, `zebra: true`, `variant:
2003
+ `stickyHeader: true`, `height`, `virtual: false`, `emptyText`, `rowClass`, `zebra: true`, `variant:
1853
2004
  'default'|'plain'`, `hierarchy: false|{parentId, column?, expanded?}`, `interactive: false`,
1854
2005
  and `label`/`labelledBy`. Locale, currency, unit, and decimals may be row callbacks; values
1855
2006
  remain numbers in row data while display formatting is locale-aware.
@@ -1869,8 +2020,8 @@ range select.
1869
2020
  root; TableView passes it through `table: { variant: 'plain' }`.
1870
2021
  - **Methods** — `setData()`, `addData()`, `updateRow(id,row)`, `removeRow(id)`, `getRow(id)`,
1871
2022
  `getData()`, `empty()`, `setSort(id,dir)`, `getSort()`, `clearSort()`, `getSelection()`, `setSelection(ids)`,
1872
- `clearSelection()`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an indeterminate
1873
- top bar, sets `aria-busy`, and is cleared by the next `setData`).
2023
+ `clearSelection()`, `reveal(id)`, `setLoading(bool)` (busy/skeleton state — dims rows, shows an
2024
+ indeterminate top bar, sets `aria-busy`, and is cleared by the next `setData`).
1874
2025
  - **Events** — `rowclick {row, id, index, event}`, `rowdblclick`, `sort {id, dir}`,
1875
2026
  `selectionchange {rows, ids}`, `datachange {rows}`, and `rowtoggle {row, id, expanded}`.
1876
2027
  `rowclick` fires for Enter on a focused row as well as for a click; `event` is then the keydown.
@@ -1968,6 +2119,26 @@ range select.
1968
2119
  call `showAll()` first to mean all of them. While growing, the table carries `aria-rowcount` and
1969
2120
  each row an `aria-rowindex`, so assistive technology hears the real total rather than the size of
1970
2121
  the batch.
2122
+ - **Windowed rendering** — `virtual: true` draws only the rows in view and one viewport of overscan
2123
+ above and below; spacer rows keep the scroll height, so what the table costs stops depending on
2124
+ how many rows it holds. It is off by default, and a table that does not ask for it renders exactly
2125
+ as before. A windowed table is one grid over all of its rows, so `virtual` implies `interactive`:
2126
+ the table carries `aria-rowcount`, every drawn row an `aria-rowindex`, and the whole keyboard map
2127
+ moves through every row, drawing the one it lands on. The focused row and the row being edited
2128
+ stay drawn wherever the reader scrolls. Sorting, filtering through `setData()`, section rows,
2129
+ hierarchy, row-level controls in cells, inline editing, and the sticky header work as usual, and
2130
+ `getData()`, `getSelection()`, and exports built on them read the data, not the DOM. Selection
2131
+ reaches rows that are not drawn: a Shift range covers them, and **the header checkbox and
2132
+ Ctrl/Cmd+A take every row**, not only the drawn ones. `reveal(id)` scrolls a row into view, drawing
2133
+ it first, and returns whether it could; it works without `virtual` too, on any row in the DOM.
2134
+ `getRenderedCount()` reports the rows drawn. `virtual` wins over `growing`, and the conflict is
2135
+ reported once through the console. Limits: give the table a `height`, or its scroll region stops at
2136
+ the height of the window. **Rows have one height:** the table measures one row and takes that
2137
+ height for all, following `--zx-row-height`, so rows of differing height are not supported, and
2138
+ long text is cut short with an ellipsis rather than wrapped. Column widths cannot follow content
2139
+ that is not drawn, so the layout is fixed: `auto` columns share the width evenly, and a column that
2140
+ needs more sets `width`. **Find-in-page does not see rows that are not drawn**, and printing prints
2141
+ the drawn rows only.
1971
2142
  - **Responsive stacking** — `responsive: false|'sm'|'md'|'lg'|'xl'` stacks each row into a card of
1972
2143
  label/value pairs below that width, instead of leaving a horizontal scrollbar with the data
1973
2144
  hidden behind it. The width measured is **the table's own container**, not the viewport, so this
@@ -2177,7 +2348,8 @@ editable cells/rows, loading, events, and teardown keep the Table contract.
2177
2348
 
2178
2349
  An accessible, engine-neutral chart host. Zx renders state, canvas, semantic data summary, tokens,
2179
2350
  and lifecycle; an injected adapter owns the drawing engine. The Zx runtime imports no Chart.js
2180
- code, so future adapters do not change the public `Chart` API.
2351
+ code. A renderer must be injected: without one Chart cannot draw data. The only supplied renderer
2352
+ is `ChartJsAdapter`, which requires host-provided Chart.js 4.
2181
2353
 
2182
2354
  - **Options** — `adapter`, `type: 'bar'`, `data`, engine-specific `chartOptions`, `label`,
2183
2355
  `description`, `summary: 'hidden'|'visible'`, `loading`, loading/empty/error text, and
@@ -2192,8 +2364,8 @@ code, so future adapters do not change the public `Chart` API.
2192
2364
  system preference or inside a `data-zx-motion="reduced"` region, and an adapter must then turn its
2193
2365
  engine's animation off; Chart watches for the answer changing and updates the mounted engine.
2194
2366
  - **`ChartJsAdapter`** — construct it with a Chart.js constructor or namespace:
2195
- `new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development-only
2196
- asset; `package.json` has no runtime dependencies and application builds explicitly choose how
2367
+ `new ChartJsAdapter(window.Chart)`. The documentation pins Chart.js 4.5.1 as a development dependency and copies it to its
2368
+ self-hosted vendor assets during the website build; `package.json` has no runtime dependencies and application builds explicitly choose how
2197
2369
  the engine is loaded. Under reduced motion it sets `animation: false`, over any animation the
2198
2370
  application configured.
2199
2371
  - **Accessibility** — the canvas always has a name and optional description, while synchronized
@@ -2296,7 +2468,8 @@ form renders, with no per-application translation layer in between.
2296
2468
  `int:range` / `float:range` / `number:range`. An unrecognised type renders a visible,
2297
2469
  labelled placeholder naming it and is excluded from the value — never dropped silently.
2298
2470
  - **Methods** — `getValue()`, `setValue()`, `apply()`, `reset()`, `clear()`.
2299
- - **Events** — `apply {value}`, `change {value, field}`.
2471
+ - **Events** — `apply {value}`, `change {value, field}`. Values read back from typed controls
2472
+ include their normalization, such as integer rounding and numeric bounds.
2300
2473
 
2301
2474
  Five behaviours are deliberate rather than incidental:
2302
2475
 
@@ -2335,7 +2508,9 @@ adapter to compile into its own backend query language.
2335
2508
  - **Fields** — `{id,label,type,operators?,defaultOperator?,choices?,loadChoices?,editor?,minQuery?,
2336
2509
  debounce?}`. Built-in types cover text, number/money, date/datetime, boolean, enum/status/
2337
2510
  priority/country/currency/unit/entity, and tags. Compatible operators and their arity come from
2338
- the exported `filterOperators` matrix; applications may explicitly override/add operator IDs.
2511
+ the exported `filterOperators` matrix; applications may explicitly override/add operator IDs. The
2512
+ labels in that matrix are English data. `Filter` shows a built-in operator through its
2513
+ `filter.op.<id>` message, and an operator the `operators` option supplies through its own `label`.
2339
2514
  - **Relative dates** — `withinLast` and `withinNext` take a span, not two dates: the editor is a
2340
2515
  whole-number amount and a unit select, and the value is the pair `[amount, unit]` with `unit` one
2341
2516
  of `RELATIVE_DATE_UNITS` (`'days'|'weeks'|'months'`), e.g. `[7, 'days']`. `validate()` requires a
@@ -2378,7 +2553,9 @@ mutate the caller's data.
2378
2553
  `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
2379
2554
  (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
2380
2555
  (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
2381
- `rowActions: (node) => actions`, `moreLabel: 'More actions'`.
2556
+ `rowActions: (node) => actions`, `moreLabel`. Unset, `label`, `emptyText` and `moreLabel` read the
2557
+ `tree.label`, `tree.noItems` and `tree.more` messages; `tree.empty` still wins over `emptyText`, and
2558
+ `emptyText: null` shows no text.
2382
2559
  - **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
2383
2560
  disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
2384
2561
  buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
@@ -2420,7 +2597,8 @@ breadcrumb.
2420
2597
  - **Options** — `items` (the same nested shape as `TreeView`), `valueKey`, `labelKey`,
2421
2598
  `childrenKey`, `path: []` (initial selection, root first), `load: (node)=>Promise<children>`,
2422
2599
  `preview: (node)=>Node|null` (renders a pane after the last column for a selected leaf),
2423
- `rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText`.
2600
+ `rootLabel`, `columnWidth: 220`, `height: 320`, `icons: true`, `renderItem`, `emptyText` (unset, the
2601
+ `finder.noItems` message; `null` shows no text).
2424
2602
  - **Methods** — `getPath()`, `getNodes()`, `getSelection()`, `setPath(ids, {silent, focus})`
2425
2603
  (async — loads every branch along the way), `reveal(id)`, `setItems()`, `focus()`.
2426
2604
  - **Events** — `change {path, nodes, node}`, `activate {node, id}`.
@@ -2555,9 +2733,10 @@ a feedback survey. The questionnaire owns the ordered items, the active one, the
2555
2733
  validation, progress and navigation; the page, card, dialog or drawer around it owns closing,
2556
2734
  persistence and transport.
2557
2735
 
2558
- The root is a real `<form>` and the choices are native radios and checkboxes carrying the item
2559
- name, so `new FormData(questionnaire.toElement())` reads the answers, arrow keys inside a choice
2560
- group are the browser's rather than ours, and the semantics do not depend on JavaScript. Three
2736
+ The created root is a real `<form>`, so `new FormData(questionnaire.toElement())` reads the
2737
+ applicable answers. When enhancing a non-form target, pass its contained `<form>` to `FormData`
2738
+ or call `toFormData()`. Choices are native radios and checkboxes carrying the item name, and
2739
+ arrow keys inside a choice group use the browser's navigation. Three
2561
2740
  things separate it from a `Form` with one `Fieldset` per question: it branches, its answer control
2562
2741
  can be any registered `Field` type, and its validation may be asynchronous.
2563
2742
 
@@ -2573,7 +2752,10 @@ can be any registered `Field` type, and its validation may be asynchronous.
2573
2752
  `setAnswer(name, value, {silent})`, `getActive()`, `getPath()`, `getProgress()`, `getState()`,
2574
2753
  `toFormData()`, `reset()`, `focus()`, `destroy()`. `next()`, `skip()` and `submit()` return
2575
2754
  **promises** — `next()` because an item's `validate` may be asynchronous, and `skip()` because
2576
- skipping the last question submits. Everything else is synchronous.
2755
+ skipping the last question submits. Everything else is synchronous. Async validation applies
2756
+ only to the answer and step it started on; editing, navigating, replacing items, resetting, or
2757
+ destroying the questionnaire invalidates a pending result. The last answer is validated once,
2758
+ and skipping an optional last question does not validate it again.
2577
2759
  - **Events** — `change {name, value, answers}`, `navigate {from, to, reason}` **preventable**,
2578
2760
  `skip {name}`, `invalid {name, message}`, `submit {answers, path}` **preventable**,
2579
2761
  `complete {answers, path}`.
@@ -2582,9 +2764,49 @@ can be any registered `Field` type, and its validation may be asynchronous.
2582
2764
  only the answers of visible items declared before it, so hiding the VAT question also hides
2583
2765
  whatever depended on the VAT id. An answer to a conditioned-out question is kept internally —
2584
2766
  walk back into the branch and it is still there — but is left out of `getAnswers()` and
2585
- `toFormData()`, so an abandoned branch never submits stale data. A `next` naming a hidden item
2767
+ `toFormData()` and native `new FormData(questionnaire.toElement())`, so an abandoned branch
2768
+ never submits stale data. Native form data includes applicable answers from earlier steps too. A `next` naming a hidden item
2586
2769
  walks forward from it rather than stranding the reader; naming an item that does not exist
2587
- throws `RangeError`.
2770
+ throws `RangeError`. `next: '$review'` opens the review screen and `next: '$submit'` submits at
2771
+ once, wherever the item stands; an item of that name goes first. A `when`, `next` or `validate`
2772
+ that is neither a function nor a declarative form (`false`, `[]`, `{}`) reads as absent, so
2773
+ `validate: strict && check` is safe.
2774
+ - **Declarative logic** — `when`, `next` and `validate` also take plain JSON, so a questionnaire can
2775
+ be stored, sent, or written by an agent; the function forms keep working beside them.
2776
+ - A condition is `{field, op, value?}` with `op` one of `eq`, `ne`, `in`, `nin`, `gt`, `gte`,
2777
+ `lt`, `lte`, `empty`, `filled`, `contains`, combined with `{all: […]}`, `{any: […]}` and
2778
+ `{not: …}`, at most four levels deep. A `when` condition may only name items declared before
2779
+ it, and sees only their visible answers, so it cascades like a predicate. A `value` is never
2780
+ `null`: an unanswered item has no answer to compare, so test it with `empty` or `filled`. A
2781
+ `Date` answer compares by its local date against `YYYY-MM-DD`, and by its local
2782
+ `YYYY-MM-DDTHH:MM` against a date-time.
2783
+ - `next` may be a list of branches, `[{if: condition, goto: name}, …, {goto: name}]`; the first
2784
+ match wins, and no match falls through to the next visible item. A branch condition may also
2785
+ name the item itself.
2786
+ - `validate` may be a list of rules, each one key plus an optional `message`: `{required: true}`,
2787
+ `{minLength: n}`, `{maxLength: n}` (characters, or entries of a multiple answer),
2788
+ `{minimum: n}`, `{maximum: n}`, `{format: 'date'|'date-time'|'time'|'email'|'uri'}`,
2789
+ `{oneOf: [values]}`. Rules other than `required` pass an empty answer; there are no patterns.
2790
+ A `{required: true}` rule marks the item required, like `required: true`.
2791
+ A rule's own `message` wins; otherwise its text resolves through `msg()` under
2792
+ `questionnaire.rule.<rule>` (`minLength`, `maxLength`, `minItems`, `maxItems`, `minimum`,
2793
+ `maximum`, `oneOf`, `date`, `dateTime`, `time`, `email`, `uri`), the same keys a Surface's
2794
+ fields use.
2795
+ - A malformed condition, branch list or rule list throws `TypeError` when the items are set.
2796
+ `evaluate(condition, answers)`, `resolveNext(next, answer, answers)`, `checkRules(rules,
2797
+ value)` and the shape checks `checkCondition()`, `checkNext()` and `checkRuleList()` are pure
2798
+ exports of `src/components/questionnaire/conditions.js`, for evaluating the same JSON elsewhere.
2799
+
2800
+ ```js
2801
+ items: [
2802
+ { name: 'method', prompt: 'How will you pay?', required: true,
2803
+ choices: [{ value: 'card', label: 'Card' }, { value: 'transfer', label: 'Bank transfer' }],
2804
+ next: [{ if: { field: 'method', op: 'eq', value: 'card' }, goto: '$submit' }] },
2805
+ { name: 'iban', prompt: 'IBAN', input: {},
2806
+ when: { field: 'method', op: 'eq', value: 'transfer' },
2807
+ validate: [{ required: true }, { minLength: 15, message: 'An IBAN has at least 15 characters.' }] }
2808
+ ]
2809
+ ```
2588
2810
  - **Path and progress** — `getPath()` is the questionnaire's memory of the route walked, and
2589
2811
  `previous()` pops it: once a branch has been taken, "previous" is not `index - 1`. `getProgress()`
2590
2812
  returns `{index, answered, total, percent, section}` where `total` is the path plus the items
@@ -2595,8 +2817,8 @@ can be any registered `Field` type, and its validation may be asynchronous.
2595
2817
  itself. The `<legend>` already asks the question, so the Field's own label is hidden from sight
2596
2818
  but kept as the control's accessible name unless the item gives `field.label` explicitly; the
2597
2819
  Field draws its own highlight, so a failing answer shows one message, not two.
2598
- - **Validation** — `required` is checked synchronously; an item's `validate(answer, answers)` may
2599
- return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
2820
+ - **Validation** — `required` and declarative rules are checked synchronously; a function
2821
+ `validate(answer, answers)` may return a message, `null`, or a **promise** of either, and a rejection is reported as its message.
2600
2822
  While the check is pending the root carries `data-state="checking"` and `aria-busy="true"` and
2601
2823
  the actions are disabled.
2602
2824
  - **Review** — `review: true` shows a summary of every answer on the path before submitting, each
@@ -2649,7 +2871,11 @@ Ordered value editor with explicit rows (add / remove / move).
2649
2871
  ### FieldUpload
2650
2872
 
2651
2873
  Click/drop file upload with progress. The drop zone is keyboard-accessible and progress comes from
2652
- `XMLHttpRequest`.
2874
+ `XMLHttpRequest`. Passing the shipped `Http` client keeps XHR upload progress while applying its
2875
+ base URL, default headers, timeout, JSON/envelope parsing, and error observer. Per-upload headers
2876
+ can override defaults; the browser supplies the multipart boundary. Custom `upload()` or
2877
+ `request()` transports receive files, `paramName`, a cancellation signal, and a progress callback.
2878
+ Aborted uploads ignore late progress and success callbacks.
2653
2879
 
2654
2880
  - **Options** — `url`, `paramName: 'upload'`, `params`, `headers`, `multiple: false`, `accept`,
2655
2881
  `maxSize`, `autoUpload: true`, `preview: true`, `http`.
@@ -2979,7 +3205,8 @@ first and last items.
2979
3205
  - **Options** — `items: [{name, label, icon?, href?}]`, `maxVisible: 0` (0 shows all),
2980
3206
  `separator: 'chevron'|'slash'`, `rootIcon: null`.
2981
3207
  - **Methods** — `setItems()`, `getItems()`, `push(item)`, `pop()`, `truncateTo(name)`, `destroy()`.
2982
- - **Events** — `select {name, item, index}`. An item with an `href` renders as a real `<a>` and its
3208
+ - **Events** — `select {name, item, index}` **preventable**, including overflow items. An item
3209
+ with an `href` renders as a real `<a>` in the trail or overflow, and its
2983
3210
  default is left alone, so ordinary navigation and middle-click still work; without one it renders
2984
3211
  as a `<button>` and only the event fires.
2985
3212
  - **Semantics** — `<nav aria-label="Breadcrumb"><ol>`; the last item is plain text carrying
@@ -3153,7 +3380,7 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
3153
3380
  (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
3154
3381
  strip), `label`,
3155
3382
  `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
3156
- `moreLabel: 'More actions'`, and `renderIcon(item, context)`. Icon values may also be names,
3383
+ `moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
3157
3384
  nodes, components, or factories.
3158
3385
  - **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
3159
3386
  disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
@@ -3388,6 +3615,16 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
3388
3615
  message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
3389
3616
  `rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
3390
3617
  "today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
3618
+ - **Surfaces** — a `{type: 'surface', id, document?, token?, catalog?, reply?}` item draws a
3619
+ `Surface`. The item comes from the application, never from a model line, so its `token` and
3620
+ `catalog` are the application's. `surfaceOptions` (`policy`, `resolve`, `chartAdapter`, `msg`)
3621
+ is handed to every surface the thread draws. `thread.surface(id)` returns it to stream into, and
3622
+ its one reply arrives as the thread's `reply {item, reply}`. Redrawing the item — `patch`,
3623
+ `upsert(thread.get(id))`, `setItems(thread.getItems())` — keeps the live surface; an item with a
3624
+ different `document` supersedes it, which replies `dismiss`. Removing the item or destroying the
3625
+ thread dismisses it. A surface that waits for an answer is announced ("Finance agent needs your
3626
+ answer") when it arrives, or when a streamed one begins. When a run stops, the application calls
3627
+ `thread.surface(id).cancel('stopped')`.
3391
3628
  - **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
3392
3629
  application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
3393
3630
  (names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
@@ -3398,21 +3635,35 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
3398
3635
  initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
3399
3636
  `editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
3400
3637
  drawn later; `sourceIcons` is handed to every `SourceList`.
3401
- - **Methods** — `setItems(items)`, `upsert(item)` (adds, or replaces in place by `id`),
3638
+ - **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
3639
+ still on its way, as a Skeleton under its author's byline; replace or remove it once the real
3640
+ item is there. It neither replies nor is announced. The name is reserved; `placeholder` is free
3641
+ for an application's own items.
3642
+ - **Methods** — `setItems(items)` (replaces the conversation: everything is dropped and drawn anew,
3643
+ except a surface already drawn, which stays so that one still matching keeps what was typed; an
3644
+ item bringing a `reply` that surface never gave freezes it as answered elsewhere),
3645
+ `upsert(item, {after?})` (adds, or replaces in place by `id`;
3646
+ a new item goes at the end, or right after the item `after` names — nothing else is redrawn),
3402
3647
  `patch(id, partial)` (an answer finishing, stopping or gaining sources, a trace's steps, an
3403
- approval's status change in place; anything else redraws the item), `appendText(id, text)`
3648
+ approval's status change in place; anything else redraws the item). Metadata patches preserve
3649
+ streamed answer blocks, including the selected version; explicit `blocks` or `versions`
3650
+ replacements remain authoritative. `appendText(id, text)`
3404
3651
  (streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
3405
3652
  block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
3406
3653
  through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
3407
3654
  artifact is open in an inspector, on every card naming it), `remove(id)`, `get(id)`,
3408
- `getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`),
3409
- `scrollToEnd()`, `destroy()`. The static `AgentThread.register(type, render)` draws an item type
3655
+ `getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`,
3656
+ `source:<n>:<id>`, a source in the list of that answer),
3657
+ `scrollToEnd()`, `surface(id)` (the `Surface` of a `surface` item, to stream into), `destroy()`. The static `AgentThread.register(type, render)` draws an item type
3410
3658
  of the application's own; `render(item, {thread, author, own})` returns its content, and `own()`
3411
- hands a component to the thread to destroy with the item.
3659
+ hands a component to the thread to destroy with the item. An application's renderer for
3660
+ `surface` replaces the library's drawing of that type, and `has('surface')` answers false until
3661
+ it does; the other built-in types cannot be replaced.
3412
3662
  - **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
3413
3663
  `up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
3414
3664
  reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
3415
3665
  step's),
3666
+ `reply {item, reply}` (a surface's one reply; the item keeps it as `reply`),
3416
3667
  `approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
3417
3668
  stays pending), `cite {item, n, source}` (preventable: by default the cited source is
3418
3669
  highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
@@ -3430,8 +3681,328 @@ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a ru
3430
3681
  - **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
3431
3682
  with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
3432
3683
  between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
3684
+ A control inside an item keeps those keys: they move a caret, not the feed.
3433
3685
  The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
3434
3686
  writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
3687
+
3688
+ #### connectUiMessageStream() — the AI SDK UI message stream
3689
+
3690
+ Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
3691
+ `UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
3692
+ request, the event source, retries, and authentication: it strips the `data: ` framing and the
3693
+ `[DONE]` sentinel, and hands each parsed part to `handle()`.
3694
+
3695
+ ```js
3696
+ const stream = connectUiMessageStream(thread, {
3697
+ agent: 'finance',
3698
+ runStatus,
3699
+ onapproval: (approvalId, approved, reason) => sendNextRequest({ approvalId, approved, reason }),
3700
+ ondata: (name, data, id) => store.set(`${name}/${id}`, data)
3701
+ });
3702
+ for await (const part of parsedParts(response)) stream.handle(part);
3703
+ ```
3704
+
3705
+ - **Options** — `runStatus` (a `RunStatus` to keep up to date), `authors`, `agent` (the author key
3706
+ of the assistant's output; without it, the first author who is not a person), `tools: {}`,
3707
+ `onapproval(approvalId, approved, reason)`, `ondata(name, data, id)`, `onmetadata(metadata)`,
3708
+ `onunknown(part)`, `onerror(error)`, `showReasoning: false`. It returns
3709
+ `{handle(part), replay(messageId), destroy()}`.
3710
+ - **Keep one connection for the conversation.** The answer to an approval goes out with the
3711
+ application's next request, and the response to it continues the same message: its `start` names
3712
+ a message that has finished or was stopped, and the message picks up where it stopped, once it has
3713
+ something to say. A `start` without a `messageId` opens a new answer, or, during an open message,
3714
+ joins it, because streams merged into one each send their own. `destroy()` stops a message still open and every
3715
+ call still going, and expires a pending approval, because no decision could reach the application
3716
+ any more.
3717
+ - **After a reconnect, call `replay(messageId)`.** A reconnect can return the whole response from its
3718
+ beginning. Only the application knows it reconnected, so it calls `replay()` before it feeds the
3719
+ stream again from the `start`: what that response drew goes and is rebuilt, with nothing doubled
3720
+ and nothing reported. Earlier responses of the message are not sent again, so what they drew stays.
3721
+ A decision stands: its card comes back with its answer, and `onapproval` does not fire twice.
3722
+ `ondata` and `onmetadata` hear what the replay sends again. Without an id it takes the message being
3723
+ read, or the one read last. Without `replay()`, a `start` for a finished message resumes it, and a
3724
+ second copy of a response is drawn twice.
3725
+
3726
+ ```js
3727
+ stream.replay(lastMessageId);
3728
+ for await (const part of parsedParts(await reconnect())) stream.handle(part);
3729
+ ```
3730
+ - **What stands in the thread stays.** A `start` for an answer this connection did not draw, restored
3731
+ with the conversation or drawn by an earlier connection, takes it over: the message goes on below
3732
+ what stands under it, and a call on one of its steps finds that step. A `start` naming any other
3733
+ item opens an answer of its own, and a continuation skips a number already in use.
3734
+ - **Message** — `start` opens an `answer` under the message id, `finish` closes it and settles
3735
+ `runStatus` (`waiting` while an approval is pending), `abort` closes it as stopped. Text blocks
3736
+ stream through `appendText`, each block a new paragraph of the same answer; blocks open side by side
3737
+ go out one after the other. `error` draws a
3738
+ `notice` with tone `danger`. `start-step` and `finish-step` draw nothing. `message-metadata`, and
3739
+ the `messageMetadata` of `start` and `finish`, go to `onmetadata`.
3740
+ - **Stream order** — the thread adds at its end, so what a message says after a card, a tile, or
3741
+ another item the adapter added continues in a new answer `<messageId>#<n>`, counting from 2, by
3742
+ the same author, and the thread draws it as the same turn. The steps stay on the message's first
3743
+ answer, and the sources are listed under its last, while citations in any of its answers count
3744
+ them all and lead to that list. Each answer is its own item: `thread.get(messageId)` is the first one alone, and an
3745
+ action under a continuation carries the id `<messageId>#<n>`, so strip `#<n>` to name the message.
3746
+ - **`reset-step`** withdraws the current step: everything the message added since its last
3747
+ `start-step` goes, or all of it when it has none, and the answer goes on where the step began. Its
3748
+ text, files, continuation answers, sources, reasoning, and tool calls with their tiles and cards
3749
+ go, and so does an error notice, because a step the server takes back has not failed. An earlier
3750
+ call keeps what the step did to it. A person can no longer answer a withdrawn card. What already
3751
+ went out through `ondata`, `onmetadata`, or `onapproval` stays with the application.
3752
+ - **Reasoning stays private.** All of a message's reasoning is one collapsed "Thought for 12 s" step.
3753
+ The text is not kept at all unless `showReasoning: true` puts it on the step. A `reasoning-file` is
3754
+ never drawn. The step says its duration in words, so the trace's "Worked for" total leaves it out.
3755
+ - **Tool calls** are steps of the answer: `queued` while the input streams, `running` once it is
3756
+ available, then `done`, `failed`, or `skipped`. The input is shown once it is complete. A
3757
+ preliminary output leaves the step running.
3758
+ - **The server asks; the person answers; the application sends.** A `tool-approval-request` draws an
3759
+ `ApprovalCard` and its step waits. The person's decision goes to `onapproval`, and a prevented
3760
+ `approve` or `reject` decides nothing. Nothing is approved by default, and an automatic decision
3761
+ (`isAutomatic`) draws no card, because nobody is asked. A call the server settles while its card
3762
+ is pending expires the card, and a `tool-approval-response` shows on it what was decided elsewhere,
3763
+ without `onapproval`. `onapproval` fires once per approval: a request that arrives again, from a
3764
+ retried step or a replay, draws its card with the answer it already has.
3765
+ - **No address is loaded.** A `source-url` keeps its link only when it is `https:` and passes
3766
+ `safeHref()`; otherwise the source stays, so `[n]` citations count the same sources, and opens
3767
+ nothing. A `source-document` is a `file` source. A `file` part draws its name and type, never its
3768
+ content.
3769
+ - **Tiles** — `tools` maps a tool's name to the application's own renderer: `(call) => ThreadItem|null`,
3770
+ called at each status change and never on an input delta, with `{id, name, args, argsText, result?,
3771
+ error?, status}`. `args` is `null` until the input is complete. The first result that is not null
3772
+ joins the thread as `tool:<toolCallId>` (a card that holds the call stays ahead of it), and later
3773
+ results patch it in place; the adapter sets the id. The call's step links to the tile, and the
3774
+ adapter answers that link with `thread.reveal()`. Draw the tile with `AgentThread.register()`. A
3775
+ renderer that throws is reported through `onerror`, and the step stays.
3776
+ - **Data parts** — `data-<name>` goes to `ondata(name, data, id)`. A part with an `id` replaces the
3777
+ earlier one of that name and id, so keep the latest value per name and id.
3778
+ - **Reported, never guessed at.** A part the adapter does not draw goes to `onunknown`, among them
3779
+ `custom` and a `tool-approval-response` with no card here. A delta ahead of its start creates the item, a `start`
3780
+ naming a message still open is ignored, a `start` naming another message stops the open one, and a
3781
+ `reset-step` outside a message draws nothing; each goes to `onerror`.
3782
+
3783
+ #### AG-UI event streams: `connectAgUi(thread, options)`
3784
+
3785
+ `connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
3786
+ AG-UI `AG_UI_VERSION` (`'1.0'`). It takes events already parsed — the application keeps the
3787
+ transport, retries and authentication — and returns `{handle(event), state(), destroy()}`.
3788
+
3789
+ ```js
3790
+ const status = new RunStatus(null, { compact: true });
3791
+ const adapter = connectAgUi(thread, {
3792
+ agent: 'finance', runStatus: status, inlineSurfaces: true,
3793
+ requiresApproval: (call) => call.name === 'send_reminder',
3794
+ tools: { show_company: (call) => (call.args ? { type: 'company-card', company: call.args.id, status: call.status } : null) },
3795
+ ontoolresult: (id, result) => sendWithNextRun(id, result)
3796
+ });
3797
+ source.onmessage = (message) => adapter.handle(JSON.parse(message.data));
3798
+ ```
3799
+
3800
+ - **Options** — `runStatus` (a `RunStatus` the run's lifecycle drives), `authors` (a text message
3801
+ whose `name` is an author key is that author's), `agent` (the author key of agent output),
3802
+ `requiresApproval(call)`, `ontoolresult(id, result)`, `onstate(state)`, `onunknown(event)`,
3803
+ `onerror(problem)` (`{code, message, event?, cause?, errors?}`), `showReasoning: false`,
3804
+ `surfaceEvent: 'zx.surface'`, `tools: {}` (tile renderers by tool name), `surfaceTools:
3805
+ ['show_surface', 'ask_user']`, `inlineSurfaces: false`, `catalog` (a narrowed surface catalog).
3806
+ - **What is drawn** — a run drives `runStatus` (`running`, then `done`, `waiting` while a call of
3807
+ the run has no result, listed in `pendingToolCallIds` or not, `stopped` when cancelled, `failed`),
3808
+ and a run error adds a `notice` (`error:<runId>`). A run error outside an open run marks the last
3809
+ run failed and reports `no-run`, but closes nothing: approvals and surfaces still waiting for a
3810
+ person stay open. A text message is an `answer` with the message id. Tool calls are steps of a
3811
+ `trace` (`trace:<runId>`, a new one, `#2`, after anything else was drawn): the arguments show once
3812
+ complete, the result fills the step. Reasoning is one collapsed "Thought for 0.7 s" step; its text
3813
+ only with `showReasoning: true`. State snapshots and JSON Patch deltas keep `state()`.
3814
+ - **`ToolCall`** — what a tile renderer receives: `{id, name, args, argsText, result?, error?,
3815
+ status}`; `args` is the parsed arguments once complete, `null` before; `result` the result's
3816
+ `content` unchanged; `status` is `queued` while arguments arrive, `waiting`, `running`, then
3817
+ `done`, `failed`, `skipped` (rejected) or `stopped`.
3818
+ - **Tiles** — a call named in `tools` is drawn by the application's renderer, an item type
3819
+ registered with `AgentThread.register()`. The renderer runs at each status change, never on an
3820
+ argument delta; its first item that is not `null` is inserted as `tool:<toolCallId>` at the
3821
+ call's place — after its trace and the items of earlier calls in it, even when text was drawn
3822
+ below since — later items replace it in place, and the step links to it. A gated call's tile
3823
+ follows its card. A renderer that throws is reported and the step stays as it was. Put arguments
3824
+ and results on the page as text.
3825
+ - **Approvals** — a call `requiresApproval` answers truthy for waits at an ApprovalCard
3826
+ (`approval:<toolCallId>`); nothing is approved by default, so a check that throws or returns a
3827
+ Promise holds the call too. The decision is the call's result:
3828
+ `ontoolresult(id, {approved: true})` or `{approved: false, reason?}`. AG-UI 1.0 asks by ending the
3829
+ run with an `interrupt` outcome: keep each `interrupt.id` from that event and send the result as
3830
+ the next run's `resume` entry `{interruptId, status: 'resolved', payload: result}`. A `tool_call`
3831
+ interrupt for a call `requiresApproval` let through draws the card too; any other interrupt
3832
+ (`input_required`, `confirmation`, …) goes to `onunknown`. A result that arrives before the
3833
+ decision is drawn, the card expires, and no decision is sent; a result after a rejection only
3834
+ fills the step. A result for a surface tool still waiting closes its surface the same way.
3835
+ - **Surfaces** — a call named in `surfaceTools` is an `ask` step and a surface at the call's place,
3836
+ a `zx-placeholder` until its arguments are complete; its reply, plus the surface's `errors` when there are any, is the call's
3837
+ result through `ontoolresult` — in AG-UI 1.0 a frontend tool, answered in the next run's input as
3838
+ `{role: 'tool', toolCallId, content}`. A `show` surface with no actions has nothing to answer, so
3839
+ the call is answered at once with `{shown: true, surface, errors?}` and the surface stays on
3840
+ screen. Arguments that are not a surface, or a surface with no valid intent, answer at once with
3841
+ `{error: 'invalid-arguments'}`. Where `thread.surface(id)` gives nothing, as with an application's
3842
+ own `surface` renderer, an operation is reported (`surface-unavailable`) and a surface tool's call
3843
+ answered at once with `{error: 'surface-unavailable'}`. With `inlineSurfaces`, surface fences in answer text become
3844
+ surfaces after the prose before them, and the prose after continues in `<messageId>#2`; a fence
3845
+ still open at the message's end is reported and its surface cancelled when the run ends, and so
3846
+ is any surface that reaches the end of its run without its `end` (`unterminated-surface`). A
3847
+ `CUSTOM` event named `surfaceEvent` carries one operation or `{ops, token?}`; the token of the
3848
+ event that opens a surface is kept. Each surface is `surface:<runId>/<surface>`, so `s1` in two
3849
+ runs is two surfaces; an operation for an answered surface is refused and reported. A surface
3850
+ belongs to the source that opened it — custom event, surface tool or fence — and an operation
3851
+ from another source is refused (`not-allowed`), never merged; give custom-event surfaces ids a
3852
+ model cannot predict, since a server `begin` for an id the model took first is refused. A reply's
3853
+ token is the application's for a custom event, the tool call id for a surface tool, and the run
3854
+ id for an inline surface.
3855
+ - **Strictness** — `*_CHUNK` events are expanded into start, content and end. Content, arguments
3856
+ or an end for something never started is dropped and reported (`out-of-order`), never drawn. A
3857
+ start for a closed message or tool call reopens it, in this run or a later one, and its content
3858
+ continues; a reopened call stands as `queued`, loses its card or surface, and is asked about
3859
+ again once its arguments are complete. A start for an id still open, or for a call already
3860
+ decided or answered, is ignored and reported (`duplicate-start`), so `ontoolresult` fires once
3861
+ for a call and an answered surface's receipt stays; and a message id with one of the adapter's prefixes (`approval:`, `tool:`, `trace:`, `surface:`,
3862
+ `error:`, `think:`) is refused. `handle()` never throws: what it cannot read is reported and
3863
+ dropped. `destroy()` closes a run still open as stopped, cancels unanswered surface-tool surfaces
3864
+ (their replies still reach `ontoolresult`, with `reason: 'stopped'`) and expires undecided
3865
+ approvals before it stops listening, and reports none of that through `onerror`. Every event the thread does not draw goes to
3866
+ `onunknown`, including steps, message snapshots, activities, subagents and the deprecated
3867
+ `THINKING_*` names.
3868
+ <!-- /doc -->
3869
+
3870
+ <!-- doc:surface -->
3871
+ ### Surface — `new Surface(target, options)` / `openSurface()` / `elicit()` / `surfaceText()`
3872
+
3873
+ Interface an agent composes as JSON — a rich answer, or a dialog asking the person something —
3874
+ validated and drawn with the library's own components. A surface declares one `intent`, which fixes
3875
+ its frame, default actions and reply, and composes its body from catalog nodes laid out by id. The
3876
+ format, the node reference and the rules a model reads are in `docs/agent-surfaces.md`; the catalog
3877
+ functions (`narrowCatalog`, `surfaceSchema`, `surfaceTools`, `surfacePrompt`) and the validator are
3878
+ in `src/components/surface/catalog.js` and `validate.js`, importable on a server.
3879
+
3880
+ - **Options** — `document` (a whole surface; leave it out to stream), `policy`, `resolve: {ref,
3881
+ link, asset, entities}`, `authors`, `userInitiated: false`, `headingLevel: 3`, `locale`,
3882
+ `catalog` (a narrowed catalog; the full one by default), `token: null` (the application's opaque
3883
+ string, at most 512 characters, copied unchanged into every reply), `reply: null` (a stored reply:
3884
+ the surface starts as its receipt), `labelledBy: null` (the id of a title shown by a host),
3885
+ `chartAdapter: null` (draws `chart` nodes; without one a chart shows its data table), `msg`.
3886
+ - **Methods** — `apply(op)`, `write(chunk)` (operation lines in chunks), `end()` (the stream is
3887
+ over), `getValues()`, `getErrors()`, `cancel(reason)`, `supersede()`, `focus()`, `toDocument()`,
3888
+ `getReply()`, `destroy()`.
3889
+ - **Events** — `reply {reply}` exactly once, `error {errors}` each time new problems are found,
3890
+ `change {name, value}`, `ready` at the first drawn state, `end`.
3891
+ - **Streaming** — every line is validated before it is drawn. A child that has not arrived is a
3892
+ skeleton line, and every action but Cancel stays disabled until the surface's `end`. What is
3893
+ invalid is dropped and reported; an unknown node, or one outside a narrowed catalog, draws "This
3894
+ part could not be shown". A surface whose stream ends without its `end` keeps its actions
3895
+ disabled. A node that fails while drawing shows the same line beside the rest of the surface, and
3896
+ is reported as `draw-failed`. One operation costs what it touches: a `data` operation redraws only
3897
+ the nodes bound to the path it changed.
3898
+ - **Limits** — 400 nodes, depth 12, 20,000 characters per string, 1,000 rows per table, 50 fields,
3899
+ 64 choices, 8 actions, 1 MB of data, and 100,000 table cells across all tables, each `$data`
3900
+ binding counted where it is used. What is over a limit is dropped and reported, and the table
3901
+ budget holds while a surface streams; rows past it draw the fallback.
3902
+ - **Actions** — the intent's defaults (`submit`, `confirm`, `approve`/`reject`) or the surface's own,
3903
+ plus Cancel for `ask`, `choose`, `confirm` and `questionnaire`, and for a `review` left without
3904
+ its `reject`. The ids `cancel` and `dismiss` are reserved: an action using one is dropped and
3905
+ reported, as is any action of a `questionnaire`'s own. Escape closes whatever waits for an answer
3906
+ (`cancel`, or `dismiss` for a `show` surface with actions), except while it closes something
3907
+ inside the surface (an open picker, an expanded list) or another handler took it. The answering
3908
+ defaults (`submit`, `confirm`, `approve`) and an own action with `kind: 'primary'` check the
3909
+ visible inputs first, move focus to the first invalid one, and send the values; any other own
3910
+ action replies at once with `values: {}`. With several primary actions the one pressed answers,
3911
+ and Enter in a field presses the first. A single `choice` must be picked before an answering
3912
+ action replies; a `multiple` one may be empty. A questionnaire's `next` that names a dropped step,
3913
+ or can lead back to its own step, is dropped and reported.
3914
+ - **Policy** — `policy(action, surface)` returns `'allow'`, `'confirm'` (a confirmation Dialog),
3915
+ `'type-to-confirm'` (`Dialog.confirm({confirmText})`) or `'deny'` (the action is not drawn, and
3916
+ the reply lists it under `removed`), or `{level, confirmText?, message?}`. Supply `confirmText`
3917
+ for `type-to-confirm`: without it the person types the fixed word "confirm"
3918
+ (`surface.typeToConfirm`), never text from the surface. A questionnaire's own Submit is put to the
3919
+ policy up front, as `submit`; denied, it is hidden and reported. The policy is synchronous:
3920
+ nothing waits for it, so a Promise denies, like a policy that throws. Anything else counts as
3921
+ `confirm`. Nothing in a surface can lower it: `kind: 'danger'` is presentation only, and
3922
+ confirmation keys in a surface are dropped.
3923
+ - **Reply** — `{zx: 'reply/1', surface, action, key, values, confirmation, at, token?, removed?,
3924
+ reason?}`. `key` is `<surface>#<action>`; `confirmation` is `clicked`, `typed` or `null`;
3925
+ `reason` says why a closing reply (`cancel`, `dismiss`) was sent: `cancelled`, `escape`,
3926
+ `closed`, `superseded`, `stopped`, `destroyed`, or the application's. Submit and every action
3927
+ reply, and so do Cancel, Escape, `cancel()`, `supersede()` and destroying an unanswered surface
3928
+ (`dismiss`), whatever happens while its receipt is drawn. When its run stops, the application
3929
+ calls `surface.cancel('stopped')`. A surface
3930
+ whose `begin` never validated still replies once: `surface` is the id it was given when that was
3931
+ a valid id, `null` otherwise. A reply records what the page did; the server runs its policy again
3932
+ before it acts.
3933
+ - **Conditions** — a node's `visible` and a schema property's `x-zx.visible` are evaluated as values
3934
+ change. A hidden input keeps what was typed, is not required, and is left out of `getValues()`
3935
+ and the reply. A node that hides while it holds the focus hands it to the input whose value hid
3936
+ it.
3937
+ - **Receipt** — answered, the surface carries `data-state="answered"`: inputs become read-only
3938
+ displays of what was answered, tables stay with their selected rows marked, and the actions give
3939
+ way to a verdict line. A restored surface (`reply`) shows what that reply answered.
3940
+ `surfaceText(document, reply)` gives the same receipt as plain text, with choice titles rather
3941
+ than raw values and never a hidden input or step, whatever the reply carries.
3942
+ - **Field types** — a schema property's `x-zx.field` draws through `Field`. The surface registers the
3943
+ types it needs only where nothing draws them yet, so an adapter the application registered with
3944
+ `Field.register()` stays.
3945
+ - **Placement** — `openSurface(document, {placement, target, …})` resolves with the reply. A sheet
3946
+ or a dialog the document asks for is honoured only with `userInitiated`; otherwise the surface goes
3947
+ inline into `target`. Closing the sheet or dialog replies `cancel`. A document that cannot begin
3948
+ rejects with a `TypeError` (its `errors` attached) before anything opens; given its `reply`, it
3949
+ resolves with it at once. `signal` withdraws it: on abort the surface is cancelled with the reason
3950
+ `stopped` and the promise resolves that reply — a sheet or dialog closes, an inline surface stays
3951
+ as its receipt — and a signal already aborted resolves it without drawing anything. Removing an
3952
+ inline `target` is not noticed: abort the signal or destroy the surface so the promise settles.
3953
+ - **Elicitation** — `elicit({message, requestedSchema}, options)` draws an `ask` form in a Dialog,
3954
+ or inline into `options.target`, and resolves `{action: 'accept', content}`, `{action: 'decline'}`
3955
+ or `{action: 'cancel'}`. A schema outside the subset (a nested object, a pattern, …) rejects with
3956
+ a `TypeError` naming what is unsupported. The message is drawn as plain text, never as markup;
3957
+ the labels resolve through `msg` (by language, then flat), the host translator, then English.
3958
+ `options.signal` withdraws the request: it resolves `cancel`.
3959
+ - **MCP elicitation** — `elicitationHandler({serverName, authors?, target?, open?, msg?})` returns
3960
+ `(params, {signal}?) => Promise<{action, content?}>` for an MCP client to install; `MCP_ELICITATION_VERSION`
3961
+ (`'2026-07-28'`) names the revision it implements. Call it with the `params` of an
3962
+ `elicitation/create` request, or of each `inputRequests` entry whose `method` is
3963
+ `elicitation/create` in an `input_required` result, and send what it resolves back — in
3964
+ `inputResponses` under the same key, with `requestState` echoed unchanged. Fields a mode does not
3965
+ use, such as an `elicitationId`, are ignored. The byline says "Asked by <server>": the
3966
+ `authors[serverName].name` when listed, else `serverName`, which is required. Abort `signal` when
3967
+ the request is withdrawn (the server cancelled it, the call timed out, the session closed, or the
3968
+ inline `target` was removed): the surface is cancelled, nothing opens, and it resolves `cancel`.
3969
+ - Form mode, the default without `mode`, is `elicit()`; a schema outside the subset rejects with
3970
+ its `TypeError`, so the client can answer the server with an error. Single and multiple choice
3971
+ (`enum`, `oneOf`, `items.enum`, `items.anyOf`) and defaults are supported; the deprecated
3972
+ `enumNames` is reported as unsupported.
3973
+ - URL mode is a `confirm` surface that asks first: the server's message as plain text, the page's
3974
+ host emphasised, its full address, a warning for an internationalised host, and no link. Nothing
3975
+ is fetched or opened before the person agrees. Open page opens the address in a new tab with
3976
+ `noopener` and `noreferrer`, inside the click, and resolves `{action: 'accept'}`; Decline
3977
+ resolves `decline`; Cancel, Escape or closing the dialog resolves `cancel`. The address must be
3978
+ an absolute lower-case `https://` URL without credentials, checked and normalised like a surface
3979
+ link; anything else rejects with a `TypeError`. `open(url)` replaces the opener: it must open a
3980
+ browsing context that cannot reach the application, and `false` or a throw answers `cancel`.
3981
+
3982
+ ```js
3983
+ const answer = elicitationHandler({ serverName: 'Orders server' });
3984
+ const inputResponses = {};
3985
+ for (const [key, request] of Object.entries(result.inputRequests ?? {})) {
3986
+ if (request.method === 'elicitation/create') inputResponses[key] = await answer(request.params);
3987
+ }
3988
+ await client.callTool({ ...call, inputResponses, requestState: result.requestState });
3989
+ ```
3990
+ - **Safety** — no string reaches the page as HTML. Records are drawn through `resolve.ref` as an
3991
+ `EntityRef`; links are `https:` only, show their host, and pass `resolve.link`, which may refuse
3992
+ them; nothing is loaded from an address the surface gives.
3993
+ - **Accessibility** — a surface that asks is a `<form>` labelled by its title, any other a labelled
3994
+ region; the title is at `headingLevel` and its `heading` nodes one and two below, up to h6; a chart offers its data table; the byline says
3995
+ "Composed by <author>".
3996
+
3997
+ ```js
3998
+ const surface = new Surface(null, {
3999
+ document, // from the model's show_surface call
4000
+ token: issuedToken,
4001
+ policy: (action) => (action.tool === 'mail.send' ? 'confirm' : 'allow'),
4002
+ resolve: { entities: ['company'], ref: (ref) => ({ id: ref.id, title: names[ref.id] }) },
4003
+ onreply: ({ detail }) => sendToolResult(detail.reply)
4004
+ });
4005
+ ```
3435
4006
  <!-- /doc -->
3436
4007
 
3437
4008
  <!-- doc:run-status -->
@@ -3485,14 +4056,15 @@ announces nothing itself; the thread the run belongs to announces its milestones
3485
4056
  ### Composer — the message box of an agent conversation
3486
4057
 
3487
4058
  A text that grows with what is written, Send (Stop while the agent works), attachments, `@`
3488
- mentions, `/` commands, extra tools and removable context chips. It keeps only the unsent message:
3489
- `send` hands the text, files, mentions and context to the application, which owns the conversation
3490
- and the transport.
4059
+ mentions, `/` commands, extra tools, removable context chips, and a queue for messages written while
4060
+ the agent works. It keeps only unsent messages: `send` hands the text, files, mentions and context to
4061
+ the application, which owns the conversation and the transport.
3491
4062
 
3492
4063
  - **Constructor** — `new Composer(null, options)` creates its own root; `new Composer(element,
3493
4064
  options)` takes over an element and restores it on `destroy()`.
3494
4065
  - **Options** — `label` (accessible name of the text and of the `role="group"` root, English
3495
4066
  `Message`), `placeholder`, `value`, `submitKey: 'enter'|'mod+enter'`, `busy: false`,
4067
+ `queue: false`, `queueLimit: 10` (see Queue),
3496
4068
  `disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
3497
4069
  `maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
3498
4070
  description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
@@ -3508,8 +4080,9 @@ and the transport.
3508
4080
  context stays), `setBusy(busy)`, `isBusy()`, `setDisabled(disabled)`, `setHint(text)`,
3509
4081
  `setNote(text)` (an empty text hides either), `update(partial)`, `setTools(tools)`,
3510
4082
  `setToolPressed(id, pressed)`, `addFiles(files)`, `getFiles()`, `addContext(chip)` (replaces a
3511
- chip with the same id), `removeContext(id)`, `getContext()`, `destroy()`. The setters emit
3512
- nothing.
4083
+ chip with the same id), `removeContext(id)`, `getContext()`, `getQueue()`, `clearQueue()`,
4084
+ `removeQueued(id)`, `destroy()`. The setters emit nothing, except that `setBusy(false)` sends the
4085
+ next queued message; `clearQueue()` and `removeQueued(id)` emit `dequeue`.
3513
4086
  - **update(partial)** — changes `label`, `placeholder`, `hint`, `note`, `submitKey`, `sendLabel`,
3514
4087
  `disabled` and `busy` in place; a key left out or `undefined` is kept, other keys are ignored.
3515
4088
  The text, its caret and selection, the focus, the attachments, the context chips and the draft
@@ -3518,7 +4091,9 @@ and the transport.
3518
4091
  `label: null` returns to `composer.label`; an empty `placeholder` removes it.
3519
4092
  - **Events** — `send {text, files, mentions, context}` is preventable: unless prevented, the text,
3520
4093
  files and draft clear; it never fires with an empty text and no files, nor while busy. `text` is
3521
- trimmed; `mentions` are the picked items whose `@<label>` is still in the text. `stop`,
4094
+ trimmed; `mentions` are the picked items whose `@<label>` is still in the text. A message from the
4095
+ queue also carries `queued: true`. `queue {item, items}`, `dequeue {item, items, reason:
4096
+ 'sent'|'removed'|'edited'|'cleared'}`; `items` is the queue as it then stands. `stop`,
3522
4097
  `input {text}`, `attach {files}` (preventable, before the files are added), `remove {kind:
3523
4098
  'file'|'context', id, file?, chip?}` (after the reader removes one), `mention {item}`,
3524
4099
  `command {item}` (the application's own item), `tool {id, tool}` (a copy of the tool as it
@@ -3529,7 +4104,9 @@ and the transport.
3529
4104
  left alone when idle, so a surrounding dialog can close). ArrowUp on an empty text emits
3530
4105
  `historyprevious`; `/` on an empty text opens the commands. In the suggestions, Up and Down move,
3531
4106
  Enter or Tab picks, Escape closes. Tools are ordinary buttons in the tab order (Enter or Space).
3532
- No key is bound on the document.
4107
+ With `queue`, the send key queues while busy. Tab reaches each queued row, a toolbar of Edit and
4108
+ Remove: Left and Right move between them, Home and End go to the first and last, and Delete on
4109
+ either removes the row. No key is bound on the document.
3533
4110
  - **Tools** — icon buttons in the bar after Attach and Commands, each named by its `label` (also
3534
4111
  its `title` tooltip). A boolean `pressed` makes a toggle with `aria-pressed`, drawn with the
3535
4112
  neutral current fill and an edge; without it the tool is a plain button. Pressing one emits
@@ -3543,6 +4120,20 @@ and the transport.
3543
4120
  name; while busy it reads `composer.stop` ("Stop"). In a composer narrower than 24rem (a phone, a
3544
4121
  side column) the text is visually hidden and Send is the square glyph again — the text stays its
3545
4122
  accessible name and its tooltip.
4123
+ - **Queue** — with `queue: true`, the send key while busy adds the message to the queue and clears
4124
+ the composer; the button stays Stop and Escape still stops the run. A queued message keeps the
4125
+ text, files, mentions and context chips it had when it was queued. The queue shows at the top of
4126
+ the box as a list labelled "Queued (2)", each row with its text on one line, Edit and Remove, and a
4127
+ polite status says "Queued; sends when the agent finishes" once per message. When `setBusy(false)`
4128
+ ends busy, the first message is sent as a normal `send`, and the next waits for the next time busy
4129
+ ends. Nothing is sent while the composer is disabled, and what is being written stays in the text.
4130
+ A prevented `send` keeps the message first in line. Edit takes the text, files and mentions back
4131
+ into the composer, removes the row and emits `input`; when something is already written or
4132
+ attached it asks first through `Dialog.confirm`. At `queueLimit` the send key is refused, the
4133
+ message stays where it is, and the hint says why until there is room. Stop keeps the queue, so the
4134
+ next message goes when the application ends busy: call `clearQueue()` in the `stop` listener to
4135
+ drop it with the run. The queue is session state: it is not kept with the draft, and `destroy()`
4136
+ drops it. Only a sent message belongs in the conversation, so queued messages are not thread items.
3546
4137
  - **Mentions** — the query is the text after the trigger up to the caret, with no whitespace;
3547
4138
  picking writes `@<label> `. An array is filtered by label prefix, word prefix, label substring,
3548
4139
  then id prefix or a word of the description, ignoring case and accents. A function answers the
@@ -3559,11 +4150,52 @@ and the transport.
3559
4150
  context chips are labelled lists, each chip with a button named "Remove <name>". Send is never
3560
4151
  disabled while the composer is live (it is `aria-disabled` when there is nothing to send), so
3561
4152
  the focus it holds survives a run ending. A toggled tool states itself with `aria-pressed`, not
3562
- colour alone.
4153
+ colour alone. The queue is a labelled ordered list; each row's toolbar is named by its text, and
4154
+ when a message leaves the queue the focus stays on the row, on the row now in its place, or in the
4155
+ text.
3563
4156
  - **Draft** — with `draftKey`, the unsent text is kept through `storage('composer')`, restored
3564
4157
  when the composer is created without a `value`, and cleared on send and `clear()`.
3565
4158
  <!-- /doc -->
3566
4159
 
4160
+ <!-- doc:prompt-starters -->
4161
+ ### PromptStarters — starting points for an empty conversation
4162
+
4163
+ A labelled group of buttons, each with a title and, muted beneath it, its description or else its
4164
+ text. PromptStarters only reports the pick and never sends anything: the application decides
4165
+ whether a starter fills the composer or sends at once.
4166
+
4167
+ - **Constructor** — `new PromptStarters(null, options)` creates its own root; `new
4168
+ PromptStarters(element, options)` takes over an element and restores it on `destroy()`.
4169
+ - **Options** — `items: [{id, title, text, description?, icon?}]`, `label` (the group's accessible
4170
+ name, English `Suggestions`), `columns: 'auto'|1|2`, `headingLevel: null`, `msg`. An item without
4171
+ `id`, `title` or `text` is left out, as is a repeated id; other fields on an item are handed back
4172
+ in `pick`. `text` keeps its spaces and line breaks, so a prompt can end where the person goes on
4173
+ writing.
4174
+ - **Columns** — `'auto'` is two columns and one in a container narrower than 32rem, read through a
4175
+ container query, so it behaves the same in a split pane, a dialog or a phone. The root fills the
4176
+ width it is given.
4177
+ - **Heading** — `headingLevel: null` keeps `label` for assistive technology only. A level draws it
4178
+ above the starters as a heading of that level, which then names the group.
4179
+ - **Methods** — `setItems(items)` (the focus on a starter stays on the starter with the same id;
4180
+ emits nothing), `destroy()`.
4181
+ - **Events** — `pick {item}`, with a copy of the starter as given.
4182
+ - **Keyboard** — each starter is a button in the Tab order, pressed with Enter or Space. There are
4183
+ no custom keys.
4184
+ - **Accessibility** — the root is `role="group"`. Each button is named by its title and described
4185
+ by the line beneath it. The line is clamped to two lines on screen; its whole text stays the
4186
+ description. Without items the group is hidden.
4187
+
4188
+ ```js
4189
+ const starters = new PromptStarters(null, {
4190
+ items: [
4191
+ { id: 'reply', title: 'Draft a reply', text: 'Draft a short, friendly reply to this customer:\n\n' },
4192
+ { id: 'review', title: 'Prepare the review', text: 'Summarise this week’s escalations.', icon: 'list' }
4193
+ ],
4194
+ onpick: ({ detail }) => composer.setValue(detail.item.text).focus()
4195
+ });
4196
+ ```
4197
+ <!-- /doc -->
4198
+
3567
4199
  <!-- doc:approval-card -->
3568
4200
  ### ApprovalCard
3569
4201
 
@@ -3710,8 +4342,8 @@ card of its title, where it is, and the passage used on hover and focus. It neve
3710
4342
  a thumbnail, or any other remote resource.
3711
4343
 
3712
4344
  - **Options** — `sources: []` (`Source[]`, numbered in order as the answer's `[n]` markers are),
3713
- `label: 'Sources'` (the visible label naming the list; `''` drops it and names the list with
3714
- the `sourceList.label` message), `layout: 'chips'|'list'` (`list` gives each source a row with
4345
+ `label` (the visible label naming the list, by default the `sourceList.label` message; `''` or
4346
+ `null` drops it and names the list with that message), `layout: 'chips'|'list'` (`list` gives each source a row with
3715
4347
  its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
3716
4348
  `web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
3717
4349
  - **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
@@ -3755,12 +4387,13 @@ a thumbnail, or any other remote resource.
3755
4387
  `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
3756
4388
  supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
3757
4389
  so changing a placement means `destroy()` and a fresh `position()` call.
3758
- - **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `printf`, and
4390
+ - **i18n** — `setTranslator`, `setLanguage`, `getLanguage`, `translate`, `translatePlural`, `printf`, and
3759
4391
  `defaultMessages`, the frozen English catalogue of every component key (`table.empty` → "No
3760
4392
  records") that a host copies as the starting point for a locale.
3761
- - **Dates** — `formatDate(d, fmt)`, `parseDate(s, fmt)` (tokens
4393
+ - **Dates** — `formatDate(d, fmt, {locale})`, `parseDate(s, fmt)` (tokens
3762
4394
  `%d %m %Y %y %H %M %S %a %A %b %B %s`), `clampDate`, `isSameDay`, `addDays`, `addMonths`,
3763
- `getWeekStart`.
4395
+ `getWeekStart`. A supported explicit `locale` takes precedence over `getLanguage()`, then
4396
+ English. Names and abbreviations come from `Intl`, preserving regional differences.
3764
4397
  - **Keyboard** — `focusTrap`, `rovingTabindex`, `typeahead`.
3765
4398
  - **Motion** — `prefersReducedMotion(element?)` → boolean, and
3766
4399
  `watchMotion(element, fn, {signal?, immediate?})` → disposer, for code that animates in script;
@@ -3852,18 +4485,23 @@ Standalone exports with no DOM ownership and no lifecycle, importable individual
3852
4485
  entry point as the components. See also the Kernel section for `Component`, `h`, `icon`, and
3853
4486
  `position` — the substrate the components themselves are built on.
3854
4487
 
3855
- - **Dates** — `formatDate(date, fmt)`, `parseDate(str, fmt)` (returns `null` when the string does
3856
- not match, so it doubles as a validator), `clampDate(date, min, max)`, `isSameDay(a, b)`,
3857
- `addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday) or `1` (Monday).
3858
- strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`.
4488
+ - **Dates** — `formatDate(date, fmt, {locale})`, `parseDate(str, fmt)` (returns `null` when the
4489
+ string does not match, so it doubles as a validator), `clampDate(date, min, max)`,
4490
+ `isSameDay(a, b)`, `addDays(date, n)`, `addMonths(date, n)`, `getWeekStart(lang?)` → `0` (Sunday)
4491
+ or `1` (Monday). strftime-style tokens: `%d %m %Y %y %H %M %S %a %A %b %B %s`. Month and weekday
4492
+ names come from `Intl` in a supported explicit `locale`, then `getLanguage()`, then English.
4493
+ Regional English tags keep their own abbreviations and conventions. Explicit locale names take
4494
+ precedence over host date-name translations; without an explicit locale those translations apply.
4495
+ Short names use `Intl` unless a host supplies the corresponding short-name key.
3859
4496
  - **Numbers, money and time** — `formatNumber(value, {locale, decimals, minDecimals, maxDecimals,
3860
4497
  group=true})`, `formatCurrency(value, currency, {locale, decimals})`, `formatPercent(value,
3861
4498
  {locale, decimals=0})` (takes a fraction, so `0.42` → `42%`), `formatFileSize(bytes, {locale,
3862
4499
  decimals=1, standard='iec'})` (`'iec'` → KiB/MiB/GiB in steps of 1024, `'si'` → kB/MB/GB in steps
3863
4500
  of 1000; `0` → `'0 B'`, trailing zeros dropped), `formatRelativeTime(date, {now=new Date(),
3864
4501
  locale, numeric='auto'})` (picks the largest sensible unit from second to year; accepts a `Date`,
3865
- Unix seconds, or an ISO string). `locale` defaults to `getLanguage()` throughout, so
3866
- `setLanguage()` drives all five. Nothing throws: `null`, `undefined` and `NaN` all format as
4502
+ Unix seconds, or an ISO string). A supported explicit `locale` takes precedence over
4503
+ `getLanguage()`, then English, so `setLanguage()` drives all five when no usable option is given.
4504
+ Nothing throws: `null`, `undefined` and `NaN` all format as
3867
4505
  `''`, an invalid currency code falls back to plain number formatting, and every `Intl` instance
3868
4506
  is cached because tables call these once per cell.
3869
4507
  - **Utilities** — `debounce(fn, ms)` (trailing edge, preserves `this`), `throttle(fn, ms,
@@ -3877,15 +4515,23 @@ entry point as the components. See also the Kernel section for `Component`, `h`,
3877
4515
  name, a `'-name'` prefix or a `{key, dir}` object for descending, or an accessor function,
3878
4516
  comparing digit runs numerically and always sorting `null`, `undefined` and `NaN` last in either
3879
4517
  direction; `uniqueBy(items, key?)` keeps the first occurrence.
3880
- - **Escaping** — `htmlEscape(str)`, and `h.raw(html)` as the only sanctioned `innerHTML` path, for
4518
+ - **Escaping** — `h()` rejects `innerHTML`, `outerHTML`, and `srcdoc` properties regardless of
4519
+ casing, and sanitizes `href` through `safeHref`. `htmlEscape(str)`, and `h.raw(html)` as the only
4520
+ sanctioned `innerHTML` path, for
3881
4521
  component-generated markup only. `escapeRegExp(value)` makes user input safe as a literal
3882
4522
  pattern, and `highlightMatch(text, query, {className='zx-mark'})` → `DocumentFragment` wraps
3883
4523
  every case-insensitive occurrence in a `<mark>` built from text nodes, with no `innerHTML`
3884
4524
  involved — the pairing every filtering list wants.
3885
- - **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear}`, a
4525
+ - **Storage** — `storage(namespace, {area='local'})` → `{get, set, remove, keys, clear, migrateLegacy}`, a
3886
4526
  namespaced JSON-encoded view of `localStorage` (or `sessionStorage` with `{area: 'session'}`).
3887
- Keys are written as `zx:<namespace>:<key>`, so features share an origin without colliding and
3888
- `clear()` empties only its own namespace; `keys()` reports namespace-relative names.
4527
+ Keys are written as `zx2:<namespace length>:<namespace>:<key>` (UTF-16 string length), so names
4528
+ containing colons cannot overlap. `clear()` empties only its own namespace; `keys()` reports
4529
+ namespace-relative names. To retain values from the earlier `zx:` format, call
4530
+ `migrateLegacy(['known-key'])` before reading them. It copies only the exact keys you name, only
4531
+ when they contain valid JSON and the current key is absent, and returns the names copied.
4532
+ Legacy values are never deleted. Migration is recorded once per key, including missing keys;
4533
+ removing or clearing a migrated value does not restore it on the next load. Invalid legacy JSON
4534
+ remains retryable. Built-in persisted components migrate their own known keys automatically.
3889
4535
  `get(key, fallback)` returns the fallback both for a missing key and for unparseable JSON, and
3890
4536
  `set()` drops values JSON cannot represent rather than throwing. When the area is missing or
3891
4537
  refuses a write — private browsing, a full quota, cookies disabled — the view degrades silently
@@ -3906,16 +4552,288 @@ entry point as the components. See also the Kernel section for `Component`, `h`,
3906
4552
  defaults → the default English catalogue → the key. The translator answers one key at a time;
3907
4553
  null, undefined, or the key itself means "not translated" and English shows, so an application
3908
4554
  without a translator never sees a raw key. `defaultMessages` is that catalogue — copy it to
3909
- start a locale (`setTranslator((key) => de[key])`). `setLanguage()` also selects the language
3910
- table of a `msg` option and drives locale-dependent behaviour such as the first day of the week.
3911
- - **Keyboard** — `focusTrap(container)` → `{activate, release}` confines Tab to a container;
4555
+ start a locale (`setTranslator((key) => de[key])`), or install the German one below.
4556
+ `setLanguage()` also selects the language table of a `msg` option and drives locale-dependent
4557
+ behaviour such as the first day of the week and the month and weekday names `formatDate()` writes.
4558
+ `translatePlural(key, count, args, {locale}?)` and `component.msgPlural(key, count, ...args)`
4559
+ select cardinal forms using `Intl.PluralRules`. Pass the finite numeric count separately from
4560
+ display arguments: `translatePlural('items', 2, ['two'])`. At each message source, resolution
4561
+ tries `items.<category>`, `items.other`, then `items` (including a legacy alias). Instance overrides
4562
+ precede the host translator, inherited component messages, and English defaults. English fallback
4563
+ selects its category using English rules. Existing unsuffixed overrides remain valid.
4564
+ - **Keyboard** — `focusTrap(container)` → `{activate, deactivate}` confines Tab to a container;
4565
+ an empty trap focuses its boundary, temporarily adding `tabindex="-1"` when needed and removing
4566
+ it on deactivation. Deactivation restores the previous focus when it is still connected.
3912
4567
  `rovingTabindex(container, itemSelector, {orientation, wrap, rtl: 'auto'})` → `{focusFirst,
3913
4568
  focusLast, destroy}` keeps one tab stop in a group — horizontal arrows follow `dir="rtl"`, and a
3914
4569
  text field, select, or contenteditable item keeps Home/End and its arrows (an arrow leaves a text
3915
4570
  field only from the edge of its text); toggling a `<fieldset disabled>` around items inside the
3916
- container moves the tab stop off them; `typeahead(getItems, onMatch)` →
4571
+ container moves the tab stop off them. Removed items regain their original tabindex and are
4572
+ released; reinserted items use their new baseline. `typeahead(getItems, onMatch)` →
3917
4573
  `(event|string) => void` resolves buffered printable keystrokes to an item (500 ms buffer,
3918
4574
  repeated-letter cycling).
4575
+
4576
+ #### Locales
4577
+
4578
+ [Open the Locales guide](https://zx.zeyos.com/docs.html#getting-started/locales).
4579
+
4580
+ Its [live language-switching example](https://zx.zeyos.com/docs.html#getting-started/locales/try-language-switching)
4581
+ offers English, German, and an application-owned French catalogue. Edit the name, record, and
4582
+ count to try positional/named variables, plural forms, and number formatting. Switching preserves
4583
+ the input values and recreates the translated Select. French intentionally omits `table.empty`
4584
+ to demonstrate English fallback. The embedded example has its own language state, and its running
4585
+ source and catalogues are available under Code.
4586
+
4587
+ ##### Language, locale, and catalogue
4588
+
4589
+ Zx ships English and German interface messages. Other languages can be supplied by the application.
4590
+ Locale tags such as `en-GB`, `de-AT`, and `fr-CA` describe language and regional conventions; adding a
4591
+ tag to a picker does not install a translation.
4592
+
4593
+ - `setTranslator(fn)` supplies the words. The function receives a flat message key and returns its text.
4594
+ - `setLanguage(tag)` selects the active language for plural rules, default formatting, and language-specific `msg` tables. It does not load a catalogue or change the page's HTML `lang` attribute.
4595
+ - `locale` selects formatting on helpers and components that expose this option. It does not select translated interface messages.
4596
+ - `displayLocale` controls the names shown by Select.locale() and Select.country(), independently of their selected value.
4597
+ - `msg` overrides messages for one component. Application labels, record values, and server text remain application-owned.
4598
+
4599
+ ##### Enable a shipped language
4600
+
4601
+ Install the catalogue and language before creating components:
4602
+
4603
+ ```js
4604
+ import { setLanguage, setTranslator } from '@zeyos/zx';
4605
+ import { de } from '@zeyos/zx/locales/de.js';
4606
+
4607
+ setTranslator((key) => de[key]);
4608
+ setLanguage('de-AT');
4609
+ document.documentElement.lang = 'de-AT';
4610
+ ```
4611
+
4612
+ This uses German messages with Austrian formatting conventions. `setTranslator(null)` restores
4613
+ English message fallback; call `setLanguage('en')` as well to return formatting to English.
4614
+ `en` from `@zeyos/zx/locales/en.js` is the frozen `defaultMessages` object. The optional
4615
+ `@zeyos/zx/locales/index.js` exports `en`, `de`, and the frozen `locales` manifest. Importing that
4616
+ manifest includes both catalogues; the main entry does not load German automatically.
4617
+
4618
+ ##### Add a new language
4619
+
4620
+ Create an application-owned module, for example `app/locales/fr.js`, served at `/app/locales/fr.js`.
4621
+ This intentionally partial example translates two Select messages:
4622
+
4623
+ ```js
4624
+ export const fr = Object.freeze({
4625
+ 'select.none': 'Aucune sélection',
4626
+ 'select.empty': 'Aucun résultat'
4627
+ });
4628
+ ```
4629
+
4630
+ ```js
4631
+ import { setLanguage, setTranslator } from '@zeyos/zx';
4632
+ import { fr } from '/app/locales/fr.js';
4633
+
4634
+ setTranslator((key) => fr[key]);
4635
+ setLanguage('fr-FR');
4636
+ document.documentElement.lang = 'fr-FR';
4637
+ ```
4638
+
4639
+ Use `defaultMessages` as the inventory of built-in keys to translate. Keep their placeholders,
4640
+ including each plural form's placeholders, and test the controls and accessible labels that your
4641
+ application uses. A partial catalogue should return `undefined` for untranslated keys so Zx can
4642
+ apply its English fallback with English plural rules. Do not fill a partial non-English catalogue
4643
+ by spreading `defaultMessages` into it. `null` and an echoed key also mean “no translation”; an
4644
+ empty string is an intentional empty translation.
4645
+
4646
+ Application catalogues need no change to Zx or its shipped manifest. Keep a registry of the languages
4647
+ your application actually supports, and pass those tags to Select.locale().
4648
+
4649
+ ##### Regional variants and catalogue lookup
4650
+
4651
+ The application chooses how a regional tag maps to a catalogue. Zx does not automatically search
4652
+ `de-AT`, then `de`, inside your translator. Reuse a language catalogue, or create regional overrides:
4653
+
4654
+ ```js
4655
+ import { setLanguage, setTranslator } from '@zeyos/zx';
4656
+ import { en, de } from '@zeyos/zx/locales/index.js';
4657
+
4658
+ const deAT = Object.freeze({ ...de, 'table.empty': 'Keine Einträge' });
4659
+ const catalogues = { en, de, 'de-AT': deAT };
4660
+
4661
+ function applyLocale(tag) {
4662
+ const locale = Intl.getCanonicalLocales(tag)[0];
4663
+ const language = new Intl.Locale(locale).language;
4664
+ const catalogue = catalogues[locale] ?? catalogues[language];
4665
+ setTranslator(catalogue ? (key) => catalogue[key] : null);
4666
+ setLanguage(locale);
4667
+ document.documentElement.lang = locale;
4668
+ }
4669
+
4670
+ applyLocale('de-AT');
4671
+ ```
4672
+
4673
+ Here `en-GB` reuses English messages, while `de-AT` keeps its regional override. This function expects
4674
+ a valid BCP 47 tag; picker values are already canonical. General locale APIs use hyphenated tags.
4675
+
4676
+ ##### Message keys and interpolation variables
4677
+
4678
+ Use flat string keys for your own messages. A dotted key is a name, not a nested object path.
4679
+ Positional placeholders are `%1`, `%2`, and so on; named placeholders use `%name%`:
4680
+
4681
+ ```js
4682
+ import { setLanguage, setTranslator, translate } from '@zeyos/zx';
4683
+ import { de } from '@zeyos/zx/locales/de.js';
4684
+
4685
+ const messages = Object.freeze({
4686
+ ...de,
4687
+ 'app.welcome': 'Willkommen, %1!',
4688
+ 'app.assigned': '%person% bearbeitet %record%.'
4689
+ });
4690
+ setTranslator((key) => messages[key]);
4691
+ setLanguage('de');
4692
+
4693
+ translate('app.welcome', ['Ada']);
4694
+ translate('app.assigned', { person: 'Ada', record: 'INV-42' });
4695
+ ```
4696
+
4697
+ `component.msg(key, ...args)` takes positional arguments. For a named template, use
4698
+ `translate(key, values)` or `printf(component.msg(key), values)`. Interpolation produces plain text;
4699
+ render it with text nodes or `textContent`.
4700
+
4701
+ For a single component, pass `msg: { 'select.empty': 'Nothing found here' }`. Resolution is instance
4702
+ messages, host translator, inherited component messages, English catalogue, then the key.
4703
+ Language-specific tables such as `msg: { de: { 'select.empty': 'Nichts gefunden' } }` match the exact
4704
+ active language identifier; provide a `de-AT` table or a flat entry when that is the active tag.
4705
+
4706
+ ##### Plural forms
4707
+
4708
+ Pass a numeric count separately from its displayed text. The selected cardinal category comes
4709
+ from `Intl.PluralRules`; messages remain flat strings:
4710
+
4711
+ ```js
4712
+ import { formatNumber, setLanguage, setTranslator, translatePlural } from '@zeyos/zx';
4713
+ import { de } from '@zeyos/zx/locales/de.js';
4714
+
4715
+ const messages = Object.freeze({
4716
+ ...de,
4717
+ 'app.results.one': '%1 Ergebnis',
4718
+ 'app.results.other': '%1 Ergebnisse'
4719
+ });
4720
+ setTranslator((key) => messages[key]);
4721
+ setLanguage('de');
4722
+
4723
+ const count = 1200;
4724
+ translatePlural('app.results', count, [formatNumber(count)]);
4725
+ ```
4726
+
4727
+ Use `component.msgPlural(key, count, ...args)` inside a component. Supply `.other` and the categories
4728
+ your language needs: `.zero`, `.one`, `.two`, `.few`, and `.many` are supported too. At each message
4729
+ source, lookup tries the selected category, `.other`, then the unsuffixed key and any supported legacy
4730
+ alias before moving to the next source. Existing flat overrides therefore keep their precedence.
4731
+ English fallback uses English rules. Custom application keys need their own fallback text; they are
4732
+ not part of the built-in English catalogue. Ordinary `translate()` and `msg()` never infer a count.
4733
+
4734
+ ##### Formatting and date-name overrides
4735
+
4736
+ Formatting uses a supported explicit locale, then the active language, then English. Support is
4737
+ checked for the particular Intl service, since a language may support numbers but not plural rules.
4738
+ Regional English tags retain their own conventions.
4739
+
4740
+ ```js
4741
+ import { formatCurrency, formatDate, formatNumber } from '@zeyos/zx';
4742
+
4743
+ formatNumber(1234.5, { locale: 'en-GB', decimals: 2 });
4744
+ formatCurrency(1234.5, 'EUR', { locale: 'de-AT' });
4745
+ formatDate(new Date(2026, 8, 1), '%b', { locale: 'en-GB' });
4746
+ ```
4747
+
4748
+ Components with a `locale` option can use the same override. For NumberField, locale-aware display
4749
+ and parsing apply with `group: true`; ungrouped fields retain their machine-format input behavior.
4750
+ Currency, time zone, week start, and display patterns are separate settings where the API exposes
4751
+ them; a locale tag alone does not choose them all.
4752
+
4753
+ `formatDate()` normally obtains month and weekday names from Intl. A host translator can override
4754
+ `date.month.0` through `date.month.11` and `date.weekday.0` through `date.weekday.6` (Sunday is zero).
4755
+ Use `date.month.short.0` and `date.weekday.short.0` for their short forms. Missing short names come
4756
+ from Intl, not a shortened translated long name. These overrides apply when no explicit locale is
4757
+ passed; an explicit `formatDate(..., { locale })` takes precedence. `locale: null` remains implicit.
4758
+
4759
+ ##### Use the Select-based pickers
4760
+
4761
+ Select.locale() and Select.country() return ordinary Select instances. They keep its popup, keyboard map, events, field
4762
+ adapter, and `.zx-select` styling, adding item generation, names, flags, and value normalization.
4763
+ A locale selection emits `change`; it does not install translations or change the application language.
4764
+
4765
+ Using `applyLocale()` from the regional-lookup example:
4766
+
4767
+ ```js
4768
+ import { getLanguage, Select } from '@zeyos/zx';
4769
+
4770
+ const picker = Select.locale(null, {
4771
+ locales: ['en-GB', 'de-DE', 'de-AT'],
4772
+ value: getLanguage(),
4773
+ displayLocale: 'en-GB',
4774
+ flags: 'code',
4775
+ filter: 'local'
4776
+ });
4777
+ picker.on('change', ({ detail }) => {
4778
+ if (detail.value) applyLocale(detail.value);
4779
+ });
4780
+ document.querySelector('#language').append(picker.toElement());
4781
+ ```
4782
+
4783
+ `displayLocale` changes the language names shown, while the selected value stays a locale tag.
4784
+ Select.locale() filters automatically for lists longer than seven; `filter: 'local'` also enables
4785
+ search for short lists. For a form, use the existing Select field preset:
4786
+
4787
+ ```js
4788
+ import { Field } from '@zeyos/zx';
4789
+
4790
+ const languageField = new Field(null, {
4791
+ type: 'zxselect',
4792
+ name: 'language',
4793
+ label: 'Language',
4794
+ value: 'de-AT',
4795
+ props: { preset: 'locale', locales: ['en-GB', 'de-AT'], flags: 'code' }
4796
+ });
4797
+ ```
4798
+
4799
+ Use `props.preset: 'country'` for the country factory. Preset names are Field adapter options;
4800
+ for direct construction call `Select.locale()` or `Select.country()`.
4801
+
4802
+ ##### Switching language at runtime
4803
+
4804
+ Set the translator and active language together, then refresh your application UI. Zx does not
4805
+ broadcast a language-change event or automatically relabel every mounted component. Preserve the
4806
+ application's values, destroy affected instances, and recreate them with the new messages; merely
4807
+ changing the picker value does not do this. Use each component's documented update methods where
4808
+ they cover the text being changed, rather than calling its internal `render()` method.
4809
+
4810
+ Set the document or region's HTML `lang` for pronunciation, and set `dir="rtl"` when your application
4811
+ selects a right-to-left language. Zx does not infer text direction from `setLanguage()`. Verify visible
4812
+ labels, accessible names, plural counts, date/number entry, and layout after a switch.
4813
+
4814
+ ##### German catalogue glossary
4815
+
4816
+ - **Voice** — a business application. The reader is addressed formally ("Sie"), and preferably not
4817
+ at all ("Änderungen speichern"). Buttons and menu items use the infinitive ("Speichern",
4818
+ "Abbrechen").
4819
+ - **Typography** — quotation marks „…“; the ellipsis character attached to its word ("Wird
4820
+ geladen…"); a non-breaking space between a number and its unit ("Letzte 30 Tage").
4821
+ - **Kept as they are** — Agent, Board, Code, Swimlanes, Tags, Token, Tool, Upload; also Dashboard,
4822
+ Prompt, and Tab where a key needs them. A work-in-progress limit is a WIP-Limit.
4823
+ - **Agents** — approve → genehmigen, approval → Genehmigung, reject → ablehnen, request → Anfrage,
4824
+ run → Ausführung, working time → Laufzeit, step → Schritt, tool call → Tool-Aufruf, retry →
4825
+ Wiederholung, stop → stoppen, conversation → Unterhaltung, source → Quelle, attachment → Anhang.
4826
+ - **Records** — record → Datensatz, field → Feld, row → Zeile, column → Spalte, view → Ansicht,
4827
+ group by → gruppieren nach, no records → Keine Datensätze.
4828
+ - **Dates** — event → Termin, date range and period → Zeitraum, week number → Kalenderwoche.
4829
+ - **Actions** — choose and select → auswählen, clear → zurücksetzen (a selection: aufheben), search
4830
+ → suchen, or durchsuchen with an object, expand → ausklappen, collapse → einklappen, hide →
4831
+ ausblenden, remove → entfernen, no matches → Keine Treffer, no results → Keine Ergebnisse.
4832
+ - **Parts of the interface** — message → Nachricht in a conversation and Meldung in a notice,
4833
+ launcher → Schnellsuche, workspace → Arbeitsbereich, panel → Bereich, sheet → Seitenbereich,
4834
+ breadcrumb → Pfadnavigation.
4835
+ - **Keys** — arrow keys → Pfeiltasten, Space → Leertaste, Enter → Eingabetaste, Escape → Esc, Ctrl →
4836
+ Strg, Delete → Entf.
3919
4837
  <!-- /doc -->
3920
4838
 
3921
4839
  <!-- doc:truncate -->
@@ -3950,6 +4868,54 @@ Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…
3950
4868
  `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
3951
4869
  `<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
3952
4870
  Datebox options `displayFormat` and `format`.
4871
+
4872
+ **Agent kit and data views.** `<zx-agent-thread>`, `<zx-composer>`, `<zx-block-view>`,
4873
+ `<zx-run-trace>`, `<zx-approval-card>`, `<zx-source-list>`, `<zx-run-status>`, `<zx-card-view>`,
4874
+ `<zx-kanban-view>`, `<zx-tree>` (TreeView) and `<zx-chart>` are made for an application written in a
4875
+ framework: it renders the tag, sets properties, calls methods, and listens for events. None of them
4876
+ is form-associated.
4877
+
4878
+ ```js
4879
+ thread.authors = authors; // data goes on the property
4880
+ thread.items = items;
4881
+ composer.addEventListener('send', (event) => {
4882
+ thread.upsert({ id, type: 'user', text: event.detail.text });
4883
+ composer.busy = true;
4884
+ });
4885
+ thread.appendText('answer-1', chunk); // forwarded to the component
4886
+ ```
4887
+
4888
+ - **Options.** Every component option keeps its name and default. A scalar is an attribute, kebab-cased
4889
+ (`heading-level`, `submit-key`), and its property reflects to it. Two stay on the property: a
4890
+ Composer's `value`, as an input's does, and an ApprovalCard's `title`, which as an attribute
4891
+ would be a tooltip over the whole card. A boolean that defaults to `true` is turned off with
4892
+ `="false"` (`numbered="false"`, `follow-output="false"`).
4893
+ - **Data is a property.** Lists, items, columns and records are properties first. A JSON attribute
4894
+ is read for static markup, but a value set on the property is never written to an attribute, so
4895
+ a long thread does not pass through `JSON.stringify`. Functions, nodes and the chart `adapter`
4896
+ have no attribute at all: `chart.adapter = new ChartJsAdapter(ChartJs)`, `tree.load = fetchChildren`.
4897
+ A property set before `defineElements()` ran is taken over at upgrade.
4898
+ - **Methods are forwarded.** Call them on the element: `thread.upsert(item)`, `composer.setBusy(true)`,
4899
+ `tree.expandAll()`, not `element.component`. The streaming and update methods of every component
4900
+ are forwarded, and on AgentThread also `get`, `getItems` and `getComponent`. A call made before
4901
+ the component exists is queued and runs, in order, once it does; a queued call returns
4902
+ `undefined`. Once running, a call returns the component's answer, with the component replaced by
4903
+ the element so a chain stays on it.
4904
+ - **Two names shared with the DOM.** `thread.remove(id)` removes an item and `thread.remove()` the
4905
+ element. `blockView.append(block)` adds a block and `blockView.append(node)` a child node.
4906
+ - **Events.** Each event the component documents is dispatched on the host under its plain name,
4907
+ so `addEventListener('send', …)` and a framework's `onsend` both work. It does not bubble, and
4908
+ `zx-send` does; use that one to delegate. Cancelling either cancels the component's event. A
4909
+ DOM event of a declared name stops at the component's root, so `input` on `<zx-composer>` is the
4910
+ component's, with `detail.text`, once per change. Setting a property emits nothing; a forwarded
4911
+ method emits what the component's method emits.
4912
+ - **Lifecycle.** Removing the element destroys its component, and re-inserting it rebuilds one from
4913
+ the current properties, including what forwarded methods changed: a streamed answer, a board's
4914
+ moved records, a tree's selection. Unsent attachments, a tree's open branches and a stopped
4915
+ answer's note live only in the component and do not come back. An option the component cannot
4916
+ change in place rebuilds it the same way.
4917
+ - **Display.** A host is `display: inline` until the page says otherwise. Give it `display: block`
4918
+ when it must fill a height, as a scrolling thread does.
3953
4919
  <!-- /doc -->
3954
4920
 
3955
4921
  <!-- doc:tokens -->