@zeyos/zx 5.7.1 → 5.8.0

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 (326) hide show
  1. package/CHANGELOG.md +296 -0
  2. package/README.md +47 -9
  3. package/dist/types/components/activity-item/activity-item.d.ts +14 -3
  4. package/dist/types/components/agent-avatar/agent-avatar.d.ts +165 -0
  5. package/dist/types/components/agent-avatar/agent-face.d.ts +93 -0
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +21 -9
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +26 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +3 -1
  9. package/dist/types/components/approval-card/approval-card.d.ts +31 -2
  10. package/dist/types/components/aurora/aurora.d.ts +31 -5
  11. package/dist/types/components/calendar/calendar.d.ts +39 -26
  12. package/dist/types/components/chart/chart.d.ts +250 -20
  13. package/dist/types/components/chart/color.d.ts +66 -0
  14. package/dist/types/components/chart/svg-adapter.d.ts +103 -0
  15. package/dist/types/components/chart/svg-geometry.d.ts +203 -0
  16. package/dist/types/components/check-button/check-button.d.ts +1 -4
  17. package/dist/types/components/checklist/checklist.d.ts +19 -5
  18. package/dist/types/components/code-editor/code-editor.d.ts +55 -1
  19. package/dist/types/components/composer/composer.d.ts +41 -6
  20. package/dist/types/components/context-menu/context-menu.d.ts +36 -8
  21. package/dist/types/components/copy/copy-button.d.ts +6 -0
  22. package/dist/types/components/copy/copy-input.d.ts +1 -0
  23. package/dist/types/components/date-picker/date-picker.d.ts +14 -0
  24. package/dist/types/components/date-picker/time-picker.d.ts +26 -17
  25. package/dist/types/components/datebox/datebox.d.ts +8 -4
  26. package/dist/types/components/dialog/dialog.d.ts +13 -2
  27. package/dist/types/components/empty-state/empty-state.d.ts +10 -1
  28. package/dist/types/components/field/field.d.ts +4 -2
  29. package/dist/types/components/form/form.d.ts +2 -1
  30. package/dist/types/components/kanban-view/kanban-card.d.ts +7 -0
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +15 -3
  32. package/dist/types/components/launcher/launcher.d.ts +26 -0
  33. package/dist/types/components/master-panel/master-panel.d.ts +9 -4
  34. package/dist/types/components/menu-button/menu-button.d.ts +29 -5
  35. package/dist/types/components/message/message.d.ts +308 -5
  36. package/dist/types/components/modal/modal.d.ts +11 -0
  37. package/dist/types/components/modal/native-dialog.d.ts +40 -0
  38. package/dist/types/components/module-bar/module-bar.d.ts +9 -2
  39. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +5 -4
  40. package/dist/types/components/number-field/number-field.d.ts +7 -0
  41. package/dist/types/components/pagination/pagination.d.ts +341 -19
  42. package/dist/types/components/run-status/run-status.d.ts +26 -0
  43. package/dist/types/components/run-trace/run-trace.d.ts +10 -6
  44. package/dist/types/components/search/search.d.ts +16 -4
  45. package/dist/types/components/select/select.d.ts +19 -1
  46. package/dist/types/components/sheet/sheet.d.ts +18 -4
  47. package/dist/types/components/slider/slider.d.ts +2 -1
  48. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -3
  49. package/dist/types/components/stepper/stepper.d.ts +17 -4
  50. package/dist/types/components/surface/catalog.d.ts +61 -17
  51. package/dist/types/components/surface/surface.d.ts +6 -4
  52. package/dist/types/components/table/table.d.ts +207 -5
  53. package/dist/types/components/table/window.d.ts +25 -1
  54. package/dist/types/components/toggle/toggle.d.ts +38 -6
  55. package/dist/types/components/tooltip/tooltip.d.ts +5 -4
  56. package/dist/types/components/tree/tree.d.ts +43 -6
  57. package/dist/types/components/truncate/truncate.d.ts +4 -2
  58. package/dist/types/components/value-list/value-list.d.ts +9 -2
  59. package/dist/types/core/date.d.ts +2 -1
  60. package/dist/types/core/drag-axis.d.ts +10 -5
  61. package/dist/types/core/export.d.ts +2 -2
  62. package/dist/types/core/format.d.ts +3 -1
  63. package/dist/types/core/icons.d.ts +36 -3
  64. package/dist/types/core/keyboard.d.ts +7 -3
  65. package/dist/types/core/messages.d.ts +3 -0
  66. package/dist/types/core/storage.d.ts +4 -3
  67. package/dist/types/core/util.d.ts +3 -1
  68. package/dist/types/elements/define.d.ts +5 -2
  69. package/dist/types/index.d.ts +6 -4
  70. package/dist/types/internal/agent-model.d.ts +99 -0
  71. package/dist/types/internal/app-rail.d.ts +37 -2
  72. package/dist/types/internal/collections.d.ts +18 -0
  73. package/dist/types/internal/menu-items.d.ts +27 -0
  74. package/dist/types/internal/overlay-content.d.ts +23 -0
  75. package/dist/types/internal/presence-loop.d.ts +5 -2
  76. package/dist/types/locales/index.d.ts +3 -0
  77. package/dist/types/zeyos/calendar.d.ts +43 -7
  78. package/dist/types/zeyos/connect.d.ts +4 -0
  79. package/dist/types/zeyos/form.d.ts +13 -5
  80. package/dist/types/zeyos/select.d.ts +5 -2
  81. package/dist/types/zeyos/table.d.ts +16 -8
  82. package/dist/types/zeyos/view.d.ts +2 -1
  83. package/dist/zx-zeyos.esm.js +2998 -451
  84. package/dist/zx-zeyos.esm.min.js +4 -4
  85. package/dist/zx.core.css +4 -0
  86. package/dist/zx.core.min.css +1 -1
  87. package/dist/zx.css +948 -48
  88. package/dist/zx.esm.js +7432 -3408
  89. package/dist/zx.esm.min.js +26 -26
  90. package/dist/zx.global.js +7432 -3408
  91. package/dist/zx.global.min.js +26 -26
  92. package/dist/zx.layered.css +950 -48
  93. package/dist/zx.layered.min.css +1 -1
  94. package/dist/zx.min.css +1 -1
  95. package/docs/agent-catalog.json +159 -1
  96. package/docs/agent-surfaces.md +21 -21
  97. package/docs/api.json +3122 -528
  98. package/docs/components/account-menu.md +24 -0
  99. package/docs/components/activity-item.md +23 -0
  100. package/docs/components/activity-list.md +28 -0
  101. package/docs/components/agent-avatar.md +59 -0
  102. package/docs/components/agent-thread.md +275 -0
  103. package/docs/components/app-icon.md +36 -0
  104. package/docs/components/app-sidebar.md +92 -0
  105. package/docs/components/approval-card.md +71 -0
  106. package/docs/components/aurora.md +34 -0
  107. package/docs/components/avatar.md +37 -0
  108. package/docs/components/badge.md +36 -0
  109. package/docs/components/block-view.md +34 -0
  110. package/docs/components/breadcrumb.md +20 -0
  111. package/docs/components/button.md +23 -0
  112. package/docs/components/calendar.md +68 -0
  113. package/docs/components/card-view.md +73 -0
  114. package/docs/components/card.md +25 -0
  115. package/docs/components/chart.md +109 -0
  116. package/docs/components/check-button.md +16 -0
  117. package/docs/components/checklist.md +19 -0
  118. package/docs/components/code-editor.md +38 -0
  119. package/docs/components/composer.md +107 -0
  120. package/docs/components/context-menu.md +32 -0
  121. package/docs/components/copy.md +37 -0
  122. package/docs/components/data-filter.md +16 -0
  123. package/docs/components/date-picker.md +31 -0
  124. package/docs/components/date-range.md +21 -0
  125. package/docs/components/datebox.md +31 -0
  126. package/docs/components/dialog.md +25 -0
  127. package/docs/components/dock.md +57 -0
  128. package/docs/components/dropdown.md +39 -0
  129. package/docs/components/elements.md +63 -0
  130. package/docs/components/empty-state.md +17 -0
  131. package/docs/components/entity-ref.md +26 -0
  132. package/docs/components/field-upload.md +18 -0
  133. package/docs/components/file-item.md +27 -0
  134. package/docs/components/file-list.md +23 -0
  135. package/docs/components/filter-panel.md +45 -0
  136. package/docs/components/filter.md +47 -0
  137. package/docs/components/finder.md +25 -0
  138. package/docs/components/form-widgets.md +42 -0
  139. package/docs/components/form.md +80 -0
  140. package/docs/components/grid.md +26 -0
  141. package/docs/components/groupbox.md +11 -0
  142. package/docs/components/helpers.md +359 -0
  143. package/docs/components/icons.md +87 -0
  144. package/docs/components/index.md +99 -0
  145. package/docs/components/kanban-view.md +42 -0
  146. package/docs/components/kbd.md +23 -0
  147. package/docs/components/kernel.md +41 -0
  148. package/docs/components/launcher.md +66 -0
  149. package/docs/components/layout.md +33 -0
  150. package/docs/components/list-toolbar.md +38 -0
  151. package/docs/components/loading.md +48 -0
  152. package/docs/components/menu-button.md +47 -0
  153. package/docs/components/message.md +76 -0
  154. package/docs/components/modal.md +27 -0
  155. package/docs/components/module-bar.md +71 -0
  156. package/docs/components/multi-value-editor.md +16 -0
  157. package/docs/components/navigation-bar.md +22 -0
  158. package/docs/components/number-field.md +34 -0
  159. package/docs/components/pagination.md +73 -0
  160. package/docs/components/panel.md +28 -0
  161. package/docs/components/prompt-starters.md +40 -0
  162. package/docs/components/prose.md +38 -0
  163. package/docs/components/questionnaire.md +115 -0
  164. package/docs/components/rating.md +19 -0
  165. package/docs/components/run-status.md +50 -0
  166. package/docs/components/run-trace.md +72 -0
  167. package/docs/components/search.md +11 -0
  168. package/docs/components/select.md +129 -0
  169. package/docs/components/sheet-stack.md +39 -0
  170. package/docs/components/sheet.md +77 -0
  171. package/docs/components/skeleton.md +27 -0
  172. package/docs/components/slider.md +29 -0
  173. package/docs/components/sort-control.md +21 -0
  174. package/docs/components/source-list.md +30 -0
  175. package/docs/components/split-view.md +12 -0
  176. package/docs/components/stat-tile.md +49 -0
  177. package/docs/components/stepper.md +27 -0
  178. package/docs/components/surface.md +152 -0
  179. package/docs/components/tabbox.md +33 -0
  180. package/docs/components/table-view.md +43 -0
  181. package/docs/components/table.md +232 -0
  182. package/docs/components/tag-picker.md +39 -0
  183. package/docs/components/timebox.md +16 -0
  184. package/docs/components/toggle.md +21 -0
  185. package/docs/components/tokens.md +82 -0
  186. package/docs/components/toolbar.md +26 -0
  187. package/docs/components/tooltip.md +16 -0
  188. package/docs/components/tree.md +48 -0
  189. package/docs/components/truncate.md +21 -0
  190. package/docs/components/value-list.md +14 -0
  191. package/docs/components/view-settings.md +56 -0
  192. package/docs/components/workspace-switcher.md +42 -0
  193. package/docs/components/zeyos.md +196 -0
  194. package/docs/llms-small.txt +299 -0
  195. package/docs/llms.md +697 -100
  196. package/docs/llms.txt +46 -19
  197. package/package.json +9 -4
  198. package/src/components/activity-item/activity-item.js +21 -2
  199. package/src/components/agent-avatar/agent-avatar.css +195 -0
  200. package/src/components/agent-avatar/agent-avatar.js +333 -0
  201. package/src/components/agent-avatar/agent-face.js +292 -0
  202. package/src/components/agent-thread/ag-ui.js +44 -11
  203. package/src/components/agent-thread/agent-thread.js +103 -11
  204. package/src/components/agent-thread/ui-message-stream.js +3 -1
  205. package/src/components/app-rail/app-rail.css +5 -0
  206. package/src/components/app-sidebar/app-sidebar.css +3 -0
  207. package/src/components/app-sidebar/app-sidebar.js +4 -3
  208. package/src/components/approval-card/approval-card.css +6 -0
  209. package/src/components/approval-card/approval-card.js +55 -7
  210. package/src/components/aurora/aurora.css +149 -14
  211. package/src/components/aurora/aurora.js +49 -6
  212. package/src/components/calendar/calendar.css +6 -2
  213. package/src/components/calendar/calendar.js +127 -47
  214. package/src/components/card-view/card-view.js +5 -6
  215. package/src/components/chart/chart.css +159 -1
  216. package/src/components/chart/chart.js +450 -62
  217. package/src/components/chart/color.js +297 -0
  218. package/src/components/chart/svg-adapter.js +576 -0
  219. package/src/components/chart/svg-geometry.js +323 -0
  220. package/src/components/check-button/check-button.js +3 -18
  221. package/src/components/checklist/checklist.js +46 -17
  222. package/src/components/checklist/field-adapter.js +4 -1
  223. package/src/components/code-editor/code-editor.css +33 -0
  224. package/src/components/code-editor/code-editor.js +97 -8
  225. package/src/components/code-editor/field-adapter.js +3 -0
  226. package/src/components/composer/composer.css +3 -0
  227. package/src/components/composer/composer.js +100 -22
  228. package/src/components/context-menu/context-menu.js +41 -5
  229. package/src/components/copy/copy-button.js +9 -1
  230. package/src/components/copy/copy-input.js +5 -0
  231. package/src/components/data-filter/filter-core.js +0 -1
  232. package/src/components/date-picker/date-picker.css +8 -0
  233. package/src/components/date-picker/date-picker.js +47 -8
  234. package/src/components/date-picker/date-range-picker.js +1 -1
  235. package/src/components/date-picker/month-picker.js +19 -3
  236. package/src/components/date-picker/time-picker.js +54 -19
  237. package/src/components/datebox/date-range-box.js +7 -3
  238. package/src/components/datebox/datebox.js +32 -6
  239. package/src/components/dialog/dialog.css +6 -0
  240. package/src/components/dialog/dialog.js +22 -30
  241. package/src/components/dropdown/dropdown.js +1 -18
  242. package/src/components/empty-state/empty-state.js +21 -2
  243. package/src/components/field/field.js +19 -3
  244. package/src/components/fieldset/fieldset.js +3 -1
  245. package/src/components/filter/filter.js +9 -0
  246. package/src/components/form/form.js +19 -2
  247. package/src/components/kanban-view/kanban-card.js +15 -2
  248. package/src/components/kanban-view/kanban-view.css +21 -0
  249. package/src/components/kanban-view/kanban-view.js +29 -16
  250. package/src/components/launcher/launcher.css +14 -0
  251. package/src/components/launcher/launcher.js +54 -9
  252. package/src/components/master-panel/master-panel.js +24 -22
  253. package/src/components/menu-button/menu-button.js +26 -4
  254. package/src/components/message/message.css +228 -29
  255. package/src/components/message/message.js +664 -30
  256. package/src/components/modal/modal.js +70 -25
  257. package/src/components/modal/native-dialog.js +91 -0
  258. package/src/components/module-bar/module-bar.css +3 -0
  259. package/src/components/module-bar/module-bar.js +17 -4
  260. package/src/components/multi-value-editor/multi-value-editor.css +7 -2
  261. package/src/components/multi-value-editor/multi-value-editor.js +3 -2
  262. package/src/components/navigation-bar/navigation-bar.js +13 -1
  263. package/src/components/number-field/field-adapter.js +3 -0
  264. package/src/components/number-field/number-field.js +2 -1
  265. package/src/components/pagination/pagination.css +26 -2
  266. package/src/components/pagination/pagination.js +551 -65
  267. package/src/components/prose/prose.js +7 -1
  268. package/src/components/rating/field-adapter.js +3 -0
  269. package/src/components/run-status/run-status.js +43 -3
  270. package/src/components/run-trace/run-trace.js +15 -7
  271. package/src/components/search/search.js +3 -18
  272. package/src/components/select/field-adapter.js +8 -1
  273. package/src/components/select/select.js +68 -13
  274. package/src/components/sheet/sheet.js +27 -8
  275. package/src/components/slider/field-adapter.js +3 -0
  276. package/src/components/slider/slider.js +4 -6
  277. package/src/components/stat-tile/stat-tile.js +24 -9
  278. package/src/components/stepper/stepper.css +15 -0
  279. package/src/components/stepper/stepper.js +34 -2
  280. package/src/components/surface/catalog.js +185 -28
  281. package/src/components/surface/surface.js +10 -5
  282. package/src/components/tabbox/tabbox.js +13 -1
  283. package/src/components/table/table.css +160 -2
  284. package/src/components/table/table.js +479 -52
  285. package/src/components/table/window.js +46 -4
  286. package/src/components/table-view/table-view.js +1 -10
  287. package/src/components/tag-picker/field-adapter.js +3 -0
  288. package/src/components/tag-picker/tag-picker.js +2 -0
  289. package/src/components/timebox/field-adapter.js +3 -0
  290. package/src/components/toggle/toggle.js +51 -27
  291. package/src/components/tooltip/tooltip.js +21 -14
  292. package/src/components/tree/tree.js +87 -14
  293. package/src/components/truncate/truncate.js +21 -5
  294. package/src/components/value-list/value-list.js +37 -9
  295. package/src/components/view-settings/view-settings.js +1 -5
  296. package/src/core/component.js +34 -2
  297. package/src/core/date.js +5 -4
  298. package/src/core/drag-axis.js +24 -7
  299. package/src/core/export.js +4 -4
  300. package/src/core/fontawesome.js +34 -3
  301. package/src/core/format.js +3 -1
  302. package/src/core/http.js +23 -11
  303. package/src/core/icons.js +51 -10
  304. package/src/core/keyboard.js +83 -9
  305. package/src/core/messages.js +3 -0
  306. package/src/core/position.js +2 -2
  307. package/src/core/storage.js +80 -31
  308. package/src/core/util.js +16 -5
  309. package/src/elements/define.js +82 -47
  310. package/src/elements/kit.js +46 -35
  311. package/src/index.js +8 -4
  312. package/src/internal/agent-model.js +152 -0
  313. package/src/internal/app-rail.js +53 -2
  314. package/src/internal/collections.js +25 -0
  315. package/src/internal/menu-items.js +59 -0
  316. package/src/internal/overlay-content.js +35 -0
  317. package/src/internal/presence-loop.js +61 -14
  318. package/src/locales/de.js +3 -0
  319. package/src/zeyos/calendar.js +81 -19
  320. package/src/zeyos/connect.js +5 -1
  321. package/src/zeyos/form.js +29 -10
  322. package/src/zeyos/select.js +36 -12
  323. package/src/zeyos/table.js +43 -11
  324. package/src/zeyos/view.js +2 -1
  325. package/styles/tokens/semantic.css +7 -1
  326. package/styles/zx.css +1 -0
@@ -0,0 +1,24 @@
1
+ # AccountMenu
2
+
3
+ A single accessible Avatar trigger and grouped account-action popup; identity, permissions, preferences, and sign-out stay application-owned.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/account-menu · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ Composes `Avatar` and `MenuButton` into one account trigger and APG menu. The popup repeats the
8
+ identity before its actions; Zx never decides role visibility, changes preferences, signs a user
9
+ out, or mutates the session.
10
+
11
+ - **Options** — `account: {name, secondary, src?, initials?, status?, statusLabel?}`, `items`,
12
+ `compact: false`, `label`, and any top/bottom/left/right `placement`.
13
+ - **Methods** — `open()`, `close()`, `toggle()`, `isOpen()`, `setAccount()`, `setItems()`,
14
+ `setCompact(compact)` (the avatar alone, or with the name and secondary line — for a navigation
15
+ column that narrows and widens), `focus()`,
16
+ `getPanel()`, `destroy()`.
17
+ - **Events** — cancelable `select {value, item}`, `open`, and `close`. A canceled selection does
18
+ not run the item's callback and leaves the menu open, so an application can reject or confirm an
19
+ action without rebuilding the account surface.
20
+ - **Accessibility** — compact mode is visually avatar-only but keeps the full account-menu name on
21
+ its single native trigger; MenuButton retains focus return, typeahead, and arrow-key behavior.
22
+ - **Appearance** — the trigger is a flat row (avatar, name, secondary line, chevron) with the hover
23
+ fill, not a button: it takes back the border, glass fill, blur and shadow MenuButton's `.zx-btn`
24
+ would give it, whatever order the stylesheets load in.
@@ -0,0 +1,23 @@
1
+ # ActivityItem
2
+
3
+ One chronological record with actor identity, timestamp, metadata, attachments, content, and host actions.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/activity-item · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ One chronological activity entry. It owns actor/avatar anatomy, semantic time, safe content slots,
8
+ attachments, and actions; the application owns posting, reactions, permissions, routing,
9
+ persistence, and sanitization before any rich content becomes a Node.
10
+
11
+ - **Options** — `id`, `actor`, `avatar` (Avatar options or Element; with `face` — `{seed, tone,
12
+ body, eyes, material}` or `true` — an agent's `AgentAvatar`, taking `name`, `label`, `size`,
13
+ `tone`, `activity`, `activityLabel`, `animate` and `phase`), `title`, `content`,
14
+ `timestamp`, `timeLabel`, `metadata`, `attachments`, `actions`, `kind`, and
15
+ `headingLevel: 1..6`. Content slots accept text, Nodes, or Components and never parse HTML.
16
+ - **Actions** — Elements pass through; descriptors accept
17
+ `{id,label?,icon?,href?,target?,rel?,title?,disabled?,kind?,onselect?}`. Unsafe links and unnamed
18
+ icon-only controls are omitted.
19
+ - **Methods** — `setActivity(values)`, `getActivity()`, and `destroy()`.
20
+ - **Events** — cancelable `action {id,action,event}` before a callback or native navigation; its
21
+ bubbling `zx-action` mirror can cancel the same boundary.
22
+ - **Accessibility** — an entry is a native list item containing an article and semantic heading;
23
+ valid timestamps use `<time datetime>`, while display-only labels remain ordinary text.
@@ -0,0 +1,28 @@
1
+ # ActivityList
2
+
3
+ A chronological ordered collection with stable grouping, incremental updates, and loading/empty states.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/activity-list · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ An accessible chronological ordered collection with stable grouping, loading/empty states, and
8
+ incremental host-controlled mutation. It deliberately preserves source order instead of guessing
9
+ whether a feed is newest- or oldest-first.
10
+
11
+ - **Options** — `items`, `groupBy` (property, resolver, or null), `groupLabel`,
12
+ `label`, `variant: 'default'|'compact'`, `loading`, `loadingCount: 3`, `loadingText`, `emptyText`,
13
+ `groupHeadingLevel`, and `itemHeadingLevel`. Unset, `label`, `loadingText` and `emptyText` read the
14
+ `activityList.*` messages; `loadingText` or `emptyText` set to `null` shows no text.
15
+ - **Compact** — `variant: 'compact'` (reflected as `data-variant`) keeps every entry on one line at
16
+ any width, for a summary card narrower than 30rem: actor and title read as one sentence that
17
+ wraps as text, the time keeps the trailing end instead of stacking under the title, an avatar
18
+ descriptor without a `size` is small, and metadata follows as a muted second line.
19
+ - **Methods** — `setItems(items,{silent?})`, `getItems()`, `getItem(id)`,
20
+ `appendItems(items,{silent?})`, `prependItems(items,{silent?})`,
21
+ `updateItem(id,values,{silent?})`, `removeItem(id,{silent?})`, `setLoading()`, and `destroy()`.
22
+ - **Events** — `datachange {items}` after mutation. Each child's cancelable `zx-action` bubbles
23
+ naturally through the list for delegated application handling.
24
+ - **Focus** — entries are regrouped on every mutation; focus on an entry's control returns to the
25
+ same control of the same activity (matched by `id`, else position), so a feed prepending live
26
+ entries does not drop the reader to `<body>`.
27
+ - **Grouping** — groups keep first-seen group order and item source order. The exported pure
28
+ `groupActivityItems()` and `normalizeActivityItems()` helpers do not mutate caller arrays.
@@ -0,0 +1,59 @@
1
+ # AgentAvatar
2
+
3
+ A generated face for an agent without a picture: a coloured geometric shape with eyes that take what the agent is doing.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/agent-avatar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A generated face for an agent that has no picture: a coloured geometric silhouette with eyes that
8
+ take the agent's activity. Everything about it is derived from a
9
+ seed, so the same agent has the same face on every screen; it is decorative by default, like
10
+ Avatar.
11
+
12
+ - **Options** — `seed` (the agent's stable id; `null` uses `name`, but a rename then changes the
13
+ face), `name`, `tone` (the Avatar tones, or `null` to derive it), `body` and `eyes` (fix one
14
+ trait instead of deriving it), `spacing: 0|1|2` (the eye spacing), `material: 'flat'|'soft'`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 / 40px at the default
15
+ spacing unit), `label`, `activity: 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`,
16
+ `activityLabel`, `indicator: true`, `animate: false`, and `phase: null|number`.
17
+ - **Silhouettes** — fourteen, filled with the tone's `-solid`: circle, squircle, hexagon,
18
+ triangle, drop, tilted pill, clover, dome, wedge, pentagon, trapezoid, cross, diamond and
19
+ octagon; polygons round their corners. Eyes are `round`, `oval` or `square`, white with dark
20
+ pupils, in `--zx-color-agent-eye` and `--zx-color-agent-pupil`, which keep their
21
+ colour in both themes.
22
+ - **Material** — `material: 'soft'` paints the body with a quiet vertical ramp: 10% toward the eye
23
+ white at the top, the plain tone from 30% to 50% — across the eyes, which keep their flat-fill
24
+ contrast — and 14% toward the pupil ink at the foot. It is an application-wide choice, not a
25
+ trait. A soft avatar is drawn flat below 28px, when offline, in print and in forced colours; the
26
+ root carries `data-material`.
27
+ - **Traits** — `agentTraits(seed, overrides?)` returns `{tone, body, eyes, spacing}`. The tone is
28
+ `avatarTone(seed)`, so the face matches an initials Avatar keyed the same way; each other trait
29
+ hashes the same normalised key with its own salt. The tables `AGENT_BODIES` and `AGENT_EYES` are
30
+ contract, order and length included. `agentFace(traits, activity, px)` returns the
31
+ drawing as plain data (`{tag, part, attrs, children?}` in a 64-unit view box), for tests or a
32
+ server.
33
+ - **Sizes** — small sizes draw less: no pupils below 20px, and larger eyes at 24px and below.
34
+ - **Activity** — the eyes take a static expression: open (idle), looking up and aside (thinking),
35
+ lowered (working), wide (needs you), flat bars (blocked), closed on a faded, colourless face
36
+ (offline). No mouths and nothing angry or sad. The Avatar activity dot (`indicator`) and the
37
+ activity word in the accessible name stay the primary signal; the root carries `data-activity`.
38
+ The dot is notched out of the face with a mask rather than ringed in a surface colour, so it reads
39
+ on any background, glass navigation included.
40
+ `animate: true` moves the root in the shared presence loop exactly as Avatar does and lets the eyes
41
+ blink, drift and scan — never without the motion preference, and not inside a
42
+ `data-zx-motion="reduced"` region. `phase` offsets both.
43
+ - **Methods** — `set(values)` (any option above), `setActivity(activity, label?)`,
44
+ `getActivity()`, `getActivityWord()` (the localized word, for a host that names its own
45
+ control), `getTraits()`, `destroy()`. No events: wrap it in a button or link to make it
46
+ interactive.
47
+ - **In navigation** — `AppSidebar` and `ModuleBar` items take `agent` (these options, or `true`)
48
+ and draw the AgentAvatar in place of their icon or tile, with the activity in the control's
49
+ name; Composer mention items and Launcher items take `agent` too; AgentThread and RunTrace authors and ActivityItem
50
+ avatar descriptors take `face`. Only a
51
+ face's trait strings are read, so agent-supplied data cannot animate or name it.
52
+ - **Elsewhere** — `emptyState()`, ApprovalCard and RunStatus take `agent` (traits and `name`, or
53
+ `true`) in place of their icon: still and decorative, ApprovalCard's face looking up at you while
54
+ the request waits, RunStatus's with the run's expression. KanbanView assignee descriptors take
55
+ `face`, so an agent on a card's team is drawn as its face. The thread adapters
56
+ (`connectAgUi()`, `connectUiMessageStream()`) draw the faces the thread's own `authors` give.
57
+ Message `leading` and Card `media` accept an AgentAvatar like any other component.
58
+ - **Accessibility** — the SVG is always hidden. With `label` the root is `role="img"`, named
59
+ "label, activity word"; without one it is `aria-hidden`, for use beside the agent's name.
@@ -0,0 +1,275 @@
1
+ # AgentThread
2
+
3
+ A conversation with agents: messages, streamed answers, the steps a run took, and the approvals that hold it.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/agent-thread · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A conversation with one or more agents, drawn from the items above: the person's messages, the
8
+ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a run took
9
+ (`RunTrace`), the approvals that hold it (`ApprovalCard`), and one-line notices.
10
+
11
+ - **Options** — `items: []`, `authors: {}`, `me: 'me'` (the reader's author key; an item without
12
+ `author` is the reader's when it is a `user` item), `label` (the feed's name, "Conversation"),
13
+ `headingLevel: 3`, `emptyState: null` (`emptyState()` options shown while empty),
14
+ `followOutput: true`, `scroller: null` (the element that scrolls; the nearest scrolling ancestor
15
+ when null), `answerActions: ['copy', 'regenerate', 'branch']` (add `'rate'` for helpful / not
16
+ helpful), `userActions: []` (`'edit'`, `'copy'` on the reader's own messages, revealed while the
17
+ message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
18
+ `rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
19
+ "today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
20
+ - **Surfaces** — a `{type: 'surface', id, document?, token?, catalog?, reply?}` item draws a
21
+ `Surface`. The item comes from the application, never from a model line, so its `token` and
22
+ `catalog` are the application's. `surfaceOptions` (`policy`, `resolve`, `chartAdapter`, `msg`)
23
+ is handed to every surface the thread draws. `thread.surface(id)` returns it to stream into, and
24
+ its one reply arrives as the thread's `reply {item, reply}`. Redrawing the item — `patch`,
25
+ `upsert(thread.get(id))`, `setItems(thread.getItems())` — keeps the live surface; an item with a
26
+ different `document` supersedes it, which replies `dismiss`. Removing the item or destroying the
27
+ thread dismisses it. A surface that waits for an answer is announced ("Finance agent needs your
28
+ answer") when it arrives, or when a streamed one begins. When a run stops, the application calls
29
+ `thread.surface(id).cancel('stopped')`.
30
+ - **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
31
+ application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
32
+ (names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
33
+ did inline above its text (`stepsOpen` opens them) and, like `stopped`, `rating` and `at`, follow
34
+ its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
35
+ "Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
36
+ (`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
37
+ initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an agent author with
38
+ `face` (`{seed, tone, body, eyes, material}` or `true`) is drawn as its generated `AgentAvatar`,
39
+ with the author's `activity` — `face` wins over `icon`; an `approval`'s
40
+ `editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
41
+ drawn later; `sourceIcons` is handed to every `SourceList`.
42
+ - **Placeholders** — a `{type: 'zx-placeholder', id, author?, lines?}` item stands for something
43
+ still on its way, as a Skeleton under its author's byline; replace or remove it once the real
44
+ item is there. It neither replies nor is announced. The name is reserved; `placeholder` is free
45
+ for an application's own items.
46
+ - **Methods** — `setItems(items)` (replaces the conversation: everything is dropped and drawn anew,
47
+ except a surface already drawn, which stays so that one still matching keeps what was typed; an
48
+ item bringing a `reply` that surface never gave freezes it as answered elsewhere),
49
+ `upsert(item, {after?})` (adds, or replaces in place by `id`;
50
+ a new item goes at the end, or right after the item `after` names — nothing else is redrawn),
51
+ `patch(id, partial)` (an answer finishing, stopping or gaining sources, a trace's steps, an
52
+ approval's status change in place; anything else redraws the item). Metadata patches preserve
53
+ streamed answer blocks, including the selected version; explicit `blocks` or `versions`
54
+ replacements remain authoritative. `appendText(id, text)`
55
+ (streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
56
+ block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
57
+ through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
58
+ artifact is open in an inspector, on every card naming it), `remove(id)`, `get(id)`,
59
+ `getItems()`, `getComponent(id)`, `reveal(target)` (`item:<id>`, `step:<id>`, `source:<n>`,
60
+ `source:<n>:<id>`, a source in the list of that answer),
61
+ `scrollToEnd()`, `surface(id)` (the `Surface` of a `surface` item, to stream into), `destroy()`. The static `AgentThread.register(type, render)` draws an item type
62
+ of the application's own; `render(item, {thread, author, own})` returns its content, and `own()`
63
+ hands a component to the thread to destroy with the item. An application's renderer for
64
+ `surface` replaces the library's drawing of that type, and `has('surface')` answers false until
65
+ it does; the other built-in types cannot be replaced.
66
+ - **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
67
+ `up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
68
+ reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
69
+ step's),
70
+ `reply {item, reply}` (a surface's one reply; the item keeps it as `reply`),
71
+ `approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
72
+ stays pending), `cite {item, n, source}` (preventable: by default the cited source is
73
+ highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
74
+ root once, as the thread's `zx-*` event: the cards, answers and traces inside it do not bubble
75
+ their own copies past it. A source that names a `call` reveals that
76
+ step in the trace.
77
+ - **Turns** — consecutive items by the same agent read as one turn: the avatar and byline are drawn
78
+ once, and the byline still names every article. The reader's own messages sit at the end as a
79
+ bubble without an avatar.
80
+ - **Following output** — while the reader is at the end, new output keeps the end in view;
81
+ scrolled up, a "Jump to latest" button appears and the reader is never moved. While a streaming
82
+ answer has nothing yet, a quiet line says who is writing.
83
+ - **Narrow** — the thread is a size container; below 30rem the content takes the full width and
84
+ the avatar stays beside the byline.
85
+ - **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
86
+ with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
87
+ between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
88
+ A control inside an item keeps those keys: they move a caret, not the feed.
89
+ The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
90
+ writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
91
+
92
+ ## connectUiMessageStream() — the AI SDK UI message stream
93
+
94
+ Draws a server's AI SDK UI message stream (the response header `x-vercel-ai-ui-message-stream: v1`;
95
+ `UI_MESSAGE_STREAM_VERSION` is the version implemented) in a thread. The application keeps the
96
+ request, the event source, retries, and authentication: it strips the `data: ` framing and the
97
+ `[DONE]` sentinel, and hands each parsed part to `handle()`. Authors are drawn from the thread's own
98
+ `authors`: an agent given a `face` there is drawn as its AgentAvatar in every item the stream
99
+ writes, and the stream can never set or change one.
100
+
101
+ ```js
102
+ const stream = connectUiMessageStream(thread, {
103
+ agent: 'finance',
104
+ runStatus,
105
+ onapproval: (approvalId, approved, reason) => sendNextRequest({ approvalId, approved, reason }),
106
+ ondata: (name, data, id) => store.set(`${name}/${id}`, data)
107
+ });
108
+ for await (const part of parsedParts(response)) stream.handle(part);
109
+ ```
110
+
111
+ - **Options** — `runStatus` (a `RunStatus` to keep up to date), `authors`, `agent` (the author key
112
+ of the assistant's output; without it, the first author who is not a person), `tools: {}`,
113
+ `onapproval(approvalId, approved, reason)`, `ondata(name, data, id)`, `onmetadata(metadata)`,
114
+ `onunknown(part)`, `onerror(error)`, `showReasoning: false`. It returns
115
+ `{handle(part), replay(messageId), destroy()}`.
116
+ - **Keep one connection for the conversation.** The answer to an approval goes out with the
117
+ application's next request, and the response to it continues the same message: its `start` names
118
+ a message that has finished or was stopped, and the message picks up where it stopped, once it has
119
+ something to say. A `start` without a `messageId` opens a new answer, or, during an open message,
120
+ joins it, because streams merged into one each send their own. `destroy()` stops a message still open and every
121
+ call still going, and expires a pending approval, because no decision could reach the application
122
+ any more.
123
+ - **After a reconnect, call `replay(messageId)`.** A reconnect can return the whole response from its
124
+ beginning. Only the application knows it reconnected, so it calls `replay()` before it feeds the
125
+ stream again from the `start`: what that response drew goes and is rebuilt, with nothing doubled
126
+ and nothing reported. Earlier responses of the message are not sent again, so what they drew stays.
127
+ A decision stands: its card comes back with its answer, and `onapproval` does not fire twice.
128
+ `ondata` and `onmetadata` hear what the replay sends again. Without an id it takes the message being
129
+ read, or the one read last. Without `replay()`, a `start` for a finished message resumes it, and a
130
+ second copy of a response is drawn twice.
131
+
132
+ ```js
133
+ stream.replay(lastMessageId);
134
+ for await (const part of parsedParts(await reconnect())) stream.handle(part);
135
+ ```
136
+ - **What stands in the thread stays.** A `start` for an answer this connection did not draw, restored
137
+ with the conversation or drawn by an earlier connection, takes it over: the message goes on below
138
+ what stands under it, and a call on one of its steps finds that step. A `start` naming any other
139
+ item opens an answer of its own, and a continuation skips a number already in use.
140
+ - **Message** — `start` opens an `answer` under the message id, `finish` closes it and settles
141
+ `runStatus` (`waiting` while an approval is pending), `abort` closes it as stopped. Text blocks
142
+ stream through `appendText`, each block a new paragraph of the same answer; blocks open side by side
143
+ go out one after the other. `error` draws a
144
+ `notice` with tone `danger`. `start-step` and `finish-step` draw nothing. `message-metadata`, and
145
+ the `messageMetadata` of `start` and `finish`, go to `onmetadata`.
146
+ - **Stream order** — the thread adds at its end, so what a message says after a card, a tile, or
147
+ another item the adapter added continues in a new answer `<messageId>#<n>`, counting from 2, by
148
+ the same author, and the thread draws it as the same turn. The steps stay on the message's first
149
+ answer, and the sources are listed under its last, while citations in any of its answers count
150
+ them all and lead to that list. Each answer is its own item: `thread.get(messageId)` is the first one alone, and an
151
+ action under a continuation carries the id `<messageId>#<n>`, so strip `#<n>` to name the message.
152
+ - **`reset-step`** withdraws the current step: everything the message added since its last
153
+ `start-step` goes, or all of it when it has none, and the answer goes on where the step began. Its
154
+ text, files, continuation answers, sources, reasoning, and tool calls with their tiles and cards
155
+ go, and so does an error notice, because a step the server takes back has not failed. An earlier
156
+ call keeps what the step did to it. A person can no longer answer a withdrawn card. What already
157
+ went out through `ondata`, `onmetadata`, or `onapproval` stays with the application.
158
+ - **Reasoning stays private.** All of a message's reasoning is one collapsed "Thought for 12 s" step.
159
+ The text is not kept at all unless `showReasoning: true` puts it on the step. A `reasoning-file` is
160
+ never drawn. The step says its duration in words, so the trace's "Worked for" total leaves it out.
161
+ - **Tool calls** are steps of the answer: `queued` while the input streams, `running` once it is
162
+ available, then `done`, `failed`, or `skipped`. The input is shown once it is complete. A
163
+ preliminary output leaves the step running.
164
+ - **The server asks; the person answers; the application sends.** A `tool-approval-request` draws an
165
+ `ApprovalCard` and its step waits. The person's decision goes to `onapproval`, and a prevented
166
+ `approve` or `reject` decides nothing. Nothing is approved by default, and an automatic decision
167
+ (`isAutomatic`) draws no card, because nobody is asked. A call the server settles while its card
168
+ is pending expires the card, and a `tool-approval-response` shows on it what was decided elsewhere,
169
+ without `onapproval`. `onapproval` fires once per approval: a request that arrives again, from a
170
+ retried step or a replay, draws its card with the answer it already has.
171
+ - **No address is loaded.** A `source-url` keeps its link only when it is `https:` and passes
172
+ `safeHref()`; otherwise the source stays, so `[n]` citations count the same sources, and opens
173
+ nothing. A `source-document` is a `file` source. A `file` part draws its name and type, never its
174
+ content.
175
+ - **Tiles** — `tools` maps a tool's name to the application's own renderer: `(call) => ThreadItem|null`,
176
+ called at each status change and never on an input delta, with `{id, name, args, argsText, result?,
177
+ error?, status}`. `args` is `null` until the input is complete. The first result that is not null
178
+ joins the thread as `tool:<toolCallId>` (a card that holds the call stays ahead of it), and later
179
+ results patch it in place; the adapter sets the id. The call's step links to the tile, and the
180
+ adapter answers that link with `thread.reveal()`. Draw the tile with `AgentThread.register()`. A
181
+ renderer that throws is reported through `onerror`, and the step stays.
182
+ - **Data parts** — `data-<name>` goes to `ondata(name, data, id)`. A part with an `id` replaces the
183
+ earlier one of that name and id, so keep the latest value per name and id.
184
+ - **Reported, never guessed at.** A part the adapter does not draw goes to `onunknown`, among them
185
+ `custom` and a `tool-approval-response` with no card here. A delta ahead of its start creates the item, a `start`
186
+ naming a message still open is ignored, a `start` naming another message stops the open one, and a
187
+ `reset-step` outside a message draws nothing; each goes to `onerror`.
188
+
189
+ ## AG-UI event streams: `connectAgUi(thread, options)`
190
+
191
+ `connectAgUi()` draws an [AG-UI](https://docs.ag-ui.com) event stream in a thread. It implements
192
+ AG-UI `AG_UI_VERSION` (`'1.0'`). It takes events already parsed — the application keeps the
193
+ transport, retries and authentication — and returns `{handle(event), state(), destroy()}`. As with
194
+ the UI message stream, faces come from the thread's own `authors`, never from the events, and a
195
+ `runStatus` given an `agent` keeps it while the run's states change its expression.
196
+
197
+ ```js
198
+ const status = new RunStatus(null, { compact: true });
199
+ const adapter = connectAgUi(thread, {
200
+ agent: 'finance', runStatus: status, inlineSurfaces: true,
201
+ requiresApproval: (call) => call.name === 'send_reminder',
202
+ tools: { show_company: (call) => (call.args ? { type: 'company-card', company: call.args.id, status: call.status } : null) },
203
+ ontoolresult: (id, result) => sendWithNextRun(id, result)
204
+ });
205
+ source.onmessage = (message) => adapter.handle(JSON.parse(message.data));
206
+ ```
207
+
208
+ - **Options** — `runStatus` (a `RunStatus` the run's lifecycle drives), `authors` (a text message
209
+ whose `name` is an author key is that author's), `agent` (the author key of agent output),
210
+ `requiresApproval(call)`, `ontoolresult(id, result)`, `onstate(state)`, `onunknown(event)`,
211
+ `onerror(problem)` (`{code, message, event?, cause?, errors?}`), `showReasoning: false`,
212
+ `surfaceEvent: 'zx.surface'`, `tools: {}` (tile renderers by tool name), `surfaceTools:
213
+ ['show_surface', 'ask_user']`, `inlineSurfaces: false`, `catalog` (a narrowed surface catalog).
214
+ - **What is drawn** — a run drives `runStatus` (`running`, then `done`, `waiting` while a call of
215
+ the run has no result, listed in `pendingToolCallIds` or not, `stopped` when cancelled, `failed`),
216
+ and a run error adds a `notice` (`error:<runId>`). A run error outside an open run marks the last
217
+ run failed and reports `no-run`, but closes nothing: approvals and surfaces still waiting for a
218
+ person stay open. A text message is an `answer` with the message id. Tool calls are steps of a
219
+ `trace` (`trace:<runId>`, a new one, `#2`, after anything else was drawn): the arguments show once
220
+ complete, the result fills the step. Reasoning is one collapsed "Thought for 0.7 s" step; its text
221
+ only with `showReasoning: true`. State snapshots and JSON Patch deltas keep `state()`.
222
+ - **`ToolCall`** — what a tile renderer receives: `{id, name, args, argsText, result?, error?,
223
+ status}`; `args` is the parsed arguments once complete, `null` before; `result` the result's
224
+ `content` unchanged; `status` is `queued` while arguments arrive, `waiting`, `running`, then
225
+ `done`, `failed`, `skipped` (rejected) or `stopped`.
226
+ - **Tiles** — a call named in `tools` is drawn by the application's renderer, an item type
227
+ registered with `AgentThread.register()`. The renderer runs at each status change, never on an
228
+ argument delta; its first item that is not `null` is inserted as `tool:<toolCallId>` at the
229
+ call's place — after its trace and the items of earlier calls in it, even when text was drawn
230
+ below since — later items replace it in place, and the step links to it. A gated call's tile
231
+ follows its card. A renderer that throws is reported and the step stays as it was. Put arguments
232
+ and results on the page as text.
233
+ - **Approvals** — a call `requiresApproval` answers truthy for waits at an ApprovalCard
234
+ (`approval:<toolCallId>`); nothing is approved by default, so a check that throws or returns a
235
+ Promise holds the call too. The decision is the call's result:
236
+ `ontoolresult(id, {approved: true})` or `{approved: false, reason?}`. AG-UI 1.0 asks by ending the
237
+ run with an `interrupt` outcome: keep each `interrupt.id` from that event and send the result as
238
+ the next run's `resume` entry `{interruptId, status: 'resolved', payload: result}`. A `tool_call`
239
+ interrupt for a call `requiresApproval` let through draws the card too; any other interrupt
240
+ (`input_required`, `confirmation`, …) goes to `onunknown`. A result that arrives before the
241
+ decision is drawn, the card expires, and no decision is sent; a result after a rejection only
242
+ fills the step. A result for a surface tool still waiting closes its surface the same way.
243
+ - **Surfaces** — a call named in `surfaceTools` is an `ask` step and a surface at the call's place,
244
+ a `zx-placeholder` until its arguments are complete; its reply, plus the surface's `errors` when there are any, is the call's
245
+ result through `ontoolresult` — in AG-UI 1.0 a frontend tool, answered in the next run's input as
246
+ `{role: 'tool', toolCallId, content}`. A `show` surface with no actions has nothing to answer, so
247
+ the call is answered at once with `{shown: true, surface, errors?}` and the surface stays on
248
+ screen. Arguments that are not a surface, or a surface with no valid intent, answer at once with
249
+ `{error: 'invalid-arguments'}`. Where `thread.surface(id)` gives nothing, as with an application's
250
+ own `surface` renderer, an operation is reported (`surface-unavailable`) and a surface tool's call
251
+ answered at once with `{error: 'surface-unavailable'}`. With `inlineSurfaces`, surface fences in answer text become
252
+ surfaces after the prose before them, and the prose after continues in `<messageId>#2`; a fence
253
+ still open at the message's end is reported and its surface cancelled when the run ends, and so
254
+ is any surface that reaches the end of its run without its `end` (`unterminated-surface`). A
255
+ `CUSTOM` event named `surfaceEvent` carries one operation or `{ops, token?}`; the token of the
256
+ event that opens a surface is kept. Each surface is `surface:<runId>/<surface>`, so `s1` in two
257
+ runs is two surfaces; an operation for an answered surface is refused and reported. A surface
258
+ belongs to the source that opened it — custom event, surface tool or fence — and an operation
259
+ from another source is refused (`not-allowed`), never merged; give custom-event surfaces ids a
260
+ model cannot predict, since a server `begin` for an id the model took first is refused. A reply's
261
+ token is the application's for a custom event, the tool call id for a surface tool, and the run
262
+ id for an inline surface.
263
+ - **Strictness** — `*_CHUNK` events are expanded into start, content and end. Content, arguments
264
+ or an end for something never started is dropped and reported (`out-of-order`), never drawn. A
265
+ start for a closed message or tool call reopens it, in this run or a later one, and its content
266
+ continues; a reopened call stands as `queued`, loses its card or surface, and is asked about
267
+ again once its arguments are complete. A start for an id still open, or for a call already
268
+ decided or answered, is ignored and reported (`duplicate-start`), so `ontoolresult` fires once
269
+ 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:`,
270
+ `error:`, `think:`) is refused. `handle()` never throws: what it cannot read is reported and
271
+ dropped. `destroy()` closes a run still open as stopped, cancels unanswered surface-tool surfaces
272
+ (their replies still reach `ontoolresult`, with `reason: 'stopped'`) and expires undecided
273
+ approvals before it stops listening, and reports none of that through `onerror`. Every event the thread does not draw goes to
274
+ `onunknown`, including steps, message snapshots, activities, subagents and the deprecated
275
+ `THINKING_*` names.
@@ -0,0 +1,36 @@
1
+ # AppIcon — application identity
2
+
3
+ A stable application identity with a centred white glyph, module colour, tile or circle geometry, accessible labeling, interaction-aware feedback, badges, selection state, and an optional CSS-first glass material.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/app-icon · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A fixed-size, product-agnostic application identity. It keeps glyph geometry stable in launchers,
8
+ sidebars, entity results, and recent-item rows while identity colour and material remain explicit
9
+ options rather than application globals.
10
+
11
+ - **Options** — `icon` (bundled name, Node, or lazy renderer), `color` (any CSS colour) or `tone`
12
+ (one of the nine categorical tones, drawn with its `--zx-color-tone-<tone>-solid` fill; `color`
13
+ wins when both are given), `size: 36`,
14
+ `iconSize: '52%'`, `label`, `badge`, `selected: false`, `shape: 'tile'|'circle'`,
15
+ `glass: false|'subtle'|'strong'`, and
16
+ additional `class` names.
17
+ - **Methods** — `set(partialOptions)` updates the existing root; `destroy()` restores an enhanced
18
+ target. `appIcon(options)` is the element-returning convenience factory.
19
+ - **ZeyOS preset** — import `zeyosAppIcon(module, options)` from `@zeyos/zx/zeyos`. Every current
20
+ ZeyOS application/module has a canonical colour and icon mapping in `src/zeyos/modules.js`;
21
+ entity names and aliases resolve through the same catalogue. `zeyosAppIcon()` defaults to a
22
+ circular application vessel; `moduleChip()` deliberately keeps a compact tile for entity and
23
+ record identity. An application may call `useZeyosIcons()` for the existing custom glyph kit or
24
+ inject an offline `icon` override; Zx never loads a network asset automatically.
25
+ - **Shape and material** — core `AppIcon` keeps the backward-compatible `tile` default. Application
26
+ launchers and rails use `circle`; entity rows, recent records, badges, and tables use `tile`.
27
+ Subtle glass uses a quiet colour bloom, rim, reflection, and shadow without per-icon backdrop
28
+ blur; strong glass increases those material cues without changing geometry.
29
+ `prefers-reduced-transparency` receives a solid surface. Glyphs remain crisp white and
30
+ geometrically centred in either built-in SVG or Font Awesome form. Enabled interactive hosts
31
+ respond through rim, light, and shadow without translating the icon; decorative and disabled
32
+ identities do not imply clickability.
33
+ - **Accessibility** — on an owned identity surface, a non-empty `label` gives the root
34
+ `role="img"`; otherwise it is decorative. When AppIcon enhances a button or link, it preserves
35
+ that control's native role and uses `label` only as its accessible name. The badge is visual
36
+ supplementary status, so include its meaning in `label` when it matters.
@@ -0,0 +1,92 @@
1
+ # AppSidebar — application navigation in every presentation
2
+
3
+ One application-navigation component with an expanded vertical tree, a minimized vertical rail, and horizontal rail layouts.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/app-sidebar · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ One route-agnostic application-navigation owner with an expanded vertical tree, a minimized
8
+ vertical rail, and horizontal rail layouts. It mounts exactly one presentation at a time while
9
+ preserving active and expanded branch state. Only the expanded vertical state reveals descendants
10
+ inline; every rail state opens descendants toward the workspace in anchored flyouts.
11
+
12
+ - **Options** — `items`, `active`, `expanded`, `collapsed`, `collapsible` (`false` removes the
13
+ minimise and expand buttons), `orientation: 'vertical'|'horizontal'`,
14
+ `side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
15
+ (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
16
+ strip), `label`,
17
+ `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
18
+ `moreLabel` (by default the `appSidebar.more` message), and `renderIcon(item, context)`. Icon values may also be names,
19
+ nodes, components, or factories.
20
+ - **Agents** — an item's `agent` (AgentAvatar options, or `true`) draws the destination as an
21
+ agent: an `AgentAvatar` in place of its icon, in the tree, on the rail and in flyouts, sized by
22
+ the icon slot, `name` defaulting to the label. It is drawn at rest and flat, at the small level of
23
+ detail whatever the slot measures — the activity is the face and the dot, never motion — and the activity's word joins the control's accessible name, with the
24
+ count when there is one ("Ledger, Needs you (1)"). Redraw with `setItems()` when it changes.
25
+ - **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
26
+ disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
27
+ rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
28
+ for them, and show while the row is pointed at, holds focus, is the current page or has its menu
29
+ open — always on a touch screen, under a contrast preference and in forced colours. Each is named
30
+ after its action and the destination ("Rename: Customers"). Only the actions of the destination
31
+ holding focus are Tab stops, right after it; a right-click or Shift+F10 on the destination lists
32
+ them all. The expanded tree and the modules layout's panel draw them; minimized flyouts show the
33
+ destinations only.
34
+ - **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
35
+ at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
36
+ `actions` (a node) adds trailing controls such as an add button. Sections replace stacking
37
+ several sidebars: one `<nav>`, one keyboard sequence, one rail. On a rail a section becomes a
38
+ rule; in a flyout, a caption.
39
+ - **Modules layout** — `layout: 'modules'` reads the top level as modules (`ModuleItem`s: `tone`
40
+ or `color`, `badge`, `pinned`, `group`) and draws them as a `ModuleBar` strip beside a panel
41
+ with one module's menu. A module with `children`, `header` (a node above its menu, such as its
42
+ primary action), or `content` (a node below it, such as a tree or a history) is a panel module:
43
+ choosing its tile shows its panel and fires a cancelable `modulechange`; any other module is a
44
+ destination and fires `select`. The panel starts on `module`, else the module holding `active`,
45
+ and follows `setActive()` into another module. A `section` at the top level heads its modules on
46
+ the strip.
47
+ - **Presentations** — the modules layout shows `'expanded'` (both menus: the strip names its
48
+ modules beside their tiles, and the side menu shows), `'compact'` (the module menu collapsed to
49
+ icons beside the side menu), or `'collapsed'` (the icon strip alone; every module's menu opens as
50
+ a flyout beside its tile). A small three-way switch at the foot of the strip, above
51
+ `railFooter`, chooses between them: an APG radio group ("Navigation layout") of one pictogram per
52
+ presentation, in a row while the modules are named and a column on the icon strip; arrow keys
53
+ move and choose, Home and End jump. `presentationSwitch: false` leaves it out when the choice
54
+ lives in a menu instead: `presentationChoice({label})` returns the same choice as a menu
55
+ `choice` entry (`account.setItems([sidebar.presentationChoice(), …])`; rebuild it after
56
+ `presentationchange`), and `presentationGlyph(name)` is its pictogram. `presentations` (default all three) decides which it offers;
57
+ `presentation` sets the first one; `getPresentation()`, `setPresentation()`, and
58
+ `togglePresentation()` (the next one, wrapping — Mod+B in an application) drive it, and
59
+ `presentationchange {presentation, previous}` reports it. `moduleBar.labels: 'hidden'` never
60
+ names the modules. `railHeader`/`railFooter` are the strip's head and foot in every
61
+ presentation. The arrow toward the panel moves from a tile into its menu, and Left Arrow on a
62
+ top-level row of the menu returns to the tile.
63
+ - **Methods** — `setItems()`, `getItems()`, `setActive()`, `setBadge(id, badge)`, `setExpanded()`,
64
+ `getExpanded()`, `toggleBranch()`, `expand()`, `collapse()`, `setCollapsed()`, `isCollapsed()`,
65
+ `setModule(id, {silent})`, `getModule()`, `setModuleLabels(labels)`, `getPresentation()`,
66
+ `setPresentation(presentation, {silent})`, `togglePresentation()`, `presentationChoice({label})`,
67
+ `setLayout({orientation, side})`, `openFlyout(id, {focus})`, `closeFlyout()`,
68
+ `closeAllFlyouts()`, `isFlyoutOpen()`, `focus()`, `destroy()`. `getItems()` returns copies of
69
+ the normalized tree; a leaf carries no `children` property.
70
+ - **Events** — cancelable `select {item, id, value, href, event}`,
71
+ `branchchange {item, id, expanded, ids}`, `collapsechange {collapsed}`,
72
+ `flyoutchange {item, id, open}`, cancelable `modulechange {item, id, previous}`, and
73
+ `presentationchange {presentation, previous}`.
74
+ - **Presentation state** — horizontal navigation is always effectively minimized and never exposes
75
+ an expand control. Switching layouts does not erase the saved vertical collapsed preference or
76
+ expanded branch IDs. `AppSidebar` is the one component that owns an application's navigation
77
+ tree; use `collapsed: true` or `orientation: 'horizontal'` for its rail presentations, and
78
+ `layout: 'modules'` for the module strip it composes from `ModuleBar`.
79
+ - **Current state** — the current page is neutral: the `--zx-color-bg-current` fill, the full
80
+ text colour and a semibold label, in the tree, the rail and every flyout; hover is a lighter
81
+ step of the same overlay. A closed branch (or a rail item) over the active route takes the
82
+ semibold label or the text colour, never the accent. Nothing is docked to an edge.
83
+ - **Pointer and focus** — hover or focus reveals rail descendants without stealing focus. Click,
84
+ Enter, Space, and the arrow toward the workspace also open a flyout; Escape, outside activation,
85
+ or selection closes it. Expanded navigation supports arrows plus Home/End across visible rows.
86
+ - **Semantics** — persistent navigation uses `<nav>` and nested lists with native links and
87
+ disclosure buttons, not menu or menubar roles. The `<nav>` is the only landmark: a root the
88
+ sidebar creates is a plain `<div>`, and a caller's own root keeps its element and attributes.
89
+ Icon-only destinations retain an accessible name
90
+ and Tooltip. A parent with children is disclosure-only; add an Overview child when it also needs
91
+ a destination. Malformed and executable URL schemes are stripped; an item with no remaining
92
+ link or callback is disabled in every presentation.
@@ -0,0 +1,71 @@
1
+ # ApprovalCard
2
+
3
+ A request that holds an agent’s run until a person answers it: what will happen, a preview of what it produces, and Approve, Edit, and Reject.
4
+
5
+ Full reference: https://zx.zeyos.com/docs/llms.md · Live demo: https://zx.zeyos.com/docs.html#components/approval-card · All components: https://zx.zeyos.com/docs/components/index.md
6
+
7
+ A request that holds an agent's run until a person answers it: what the agent wants to do, what
8
+ will happen, a preview of what it produces, and Approve, Edit, and Reject. Answered, it freezes
9
+ into the record of what was decided, by whom, and when. The card never acts on its own — it emits
10
+ the answer, and the application carries it out.
11
+
12
+ - **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
13
+ 'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `agent: null` (the asking
14
+ agent's AgentAvatar face in place of the tile — `{seed?, name?, tone?, body?, eyes?, material?}`
15
+ or `true`; it looks up at you while the request waits and rests once answered), `headingLevel: 3`,
16
+ `status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
17
+ amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
18
+ is accepted for `content`, as the thread model spells it), `fields: Record<string,
19
+ FieldOptions>|null` (the Edit form — no fields, no Edit), `values: {}`, `confirmText: null`,
20
+ `reason: 'optional'|'required'|'none'` (whether Reject asks why), `answeredBy: null` (the verdict's
21
+ "you" when null), `answeredAt: null` (local ISO date-time or Date), `edited: false`,
22
+ `editedKeys: null` and `rejectReason: null` (for a card restored from a record), `now: null`
23
+ (a `() => Date` clock), `keys: true`, and `msg`.
24
+ - **Edited values** — `edited: true` lists every field under "Edited by you"; `editedKeys:
25
+ ['subject']` lists only those (in field order) and on its own marks the card edited. The card's
26
+ own Edit flow keeps `editedKeys` as the union of every save so far, so a restored card and a
27
+ card edited in place list the same thing.
28
+ - **Events** — `approve {values}`, `edit {values, changed, editedKeys}`, `reject {reason}`, all
29
+ **preventable** (on the component or on the bubbling `zx-*` event). Unless `approve` or `reject`
30
+ is prevented the card moves to its answered state; a saved `edit` keeps it pending and adopts
31
+ the values. `changed` names the fields this save changed. `editedKeys` is the union the card
32
+ will list (null when it lists every field), so the application can store it with the record.
33
+ Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
34
+ - **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`, `agent`,
35
+ `details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
36
+ place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
37
+ now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
38
+ included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
39
+ `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
40
+ starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
41
+ dialogs, including an open confirmation).
42
+ - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
43
+ that changed. It redraws only what changed: values equal to what is drawn (compared by content,
44
+ so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
45
+ where it was. When the focused control goes away (Edit when `fields` go, the preview toggle when
46
+ `preview` goes), focus moves to the card. A change closes a dialog only when the dialog no
47
+ longer applies: new `fields` close the Edit form, a new `reason` closes the Reject dialog, a new
48
+ `confirmText` closes the typed confirmation without approving. An open Edit form stays open over
49
+ new `values`. Status goes through `setStatus()`. `update()` emits nothing.
50
+ - **Approve** — with `confirmText`, Approve first opens `Dialog.confirm({confirmText, danger:
51
+ true})` titled with the card's title; only a confirmed approval emits `approve`.
52
+ - **Reject** — `reason: 'optional'` asks in a dialog with a textarea and accepts an empty answer;
53
+ `'required'` keeps the Reject button disabled until the reason is non-empty; `'none'` rejects at
54
+ once with `reason: ''`. Mod+Enter submits the Reject and Edit dialogs.
55
+ - **Answered state** — no actions; the line under the title becomes the verdict ("Approved by you
56
+ at 10:31"; the date is added when it is not today, by the `now` clock); the edited values and
57
+ the reason (as a quote) stay. An answer given on the card, or a `setStatus()` without `at`,
58
+ takes its time from `now`. `data-state` is the status, and the state pill is a `statusIcon()`
59
+ glyph plus its word (waiting, done, skipped, stopped glyphs for pending, approved, rejected,
60
+ expired).
61
+ - **Keyboard** — A approves, E edits, R rejects, only while focus is inside the pending card, not
62
+ in a text control, with no modifier held, and while none of the card's dialogs is open. The card
63
+ binds no document key: an application that wants them from elsewhere forwards the event to
64
+ `handleKey(event)`, which returns true and prevents the default when it used the key.
65
+ `keys: false` stops the card listening on itself (and drops the key hints on its buttons).
66
+ - **Accessibility** — `role="group"` labelled by the title heading and described by the
67
+ description and the state line; a pending card says "The run is paused until you answer."
68
+ (message `approvalCard.paused`). The preview toggle follows the APG Disclosure pattern.
69
+ - **Consequence comes from the application** — whether an action needs `confirmText` (or
70
+ `reason: 'required'`) is decided by the application from the tool the action triggers. It is
71
+ never taken from model output: an agent that could set its own confirmation could also waive it.