@zeyos/zx 5.4.0 → 5.6.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 (145) hide show
  1. package/CHANGELOG.md +136 -0
  2. package/README.md +23 -16
  3. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  4. package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
  5. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  6. package/dist/types/components/avatar/avatar.d.ts +91 -4
  7. package/dist/types/components/badge/badge.d.ts +5 -4
  8. package/dist/types/components/block-view/block-view.d.ts +205 -0
  9. package/dist/types/components/composer/composer.d.ts +736 -0
  10. package/dist/types/components/datebox/date-range-box.d.ts +15 -2
  11. package/dist/types/components/datebox/datebox.d.ts +37 -3
  12. package/dist/types/components/kbd/kbd.d.ts +41 -0
  13. package/dist/types/components/launcher/launcher.d.ts +4 -2
  14. package/dist/types/components/prose/prose.d.ts +69 -0
  15. package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
  16. package/dist/types/components/run-status/run-status.d.ts +393 -0
  17. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  18. package/dist/types/components/source-list/source-list.d.ts +177 -0
  19. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
  20. package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
  21. package/dist/types/components/tree/tree.d.ts +44 -3
  22. package/dist/types/core/icons.d.ts +22 -1
  23. package/dist/types/core/messages.d.ts +135 -0
  24. package/dist/types/index.d.ts +12 -2
  25. package/dist/types/internal/agent-model.d.ts +587 -0
  26. package/dist/types/internal/app-rail.d.ts +10 -3
  27. package/dist/types/internal/highlight.d.ts +24 -0
  28. package/dist/types/internal/presence-loop.d.ts +148 -0
  29. package/dist/types/internal/row-actions.d.ts +151 -0
  30. package/dist/zx-zeyos.esm.js +4852 -4535
  31. package/dist/zx-zeyos.esm.min.js +4 -4
  32. package/dist/zx.css +3152 -434
  33. package/dist/zx.esm.js +13730 -6595
  34. package/dist/zx.esm.min.js +27 -8
  35. package/dist/zx.global.js +13730 -6595
  36. package/dist/zx.global.min.js +27 -8
  37. package/dist/zx.min.css +1 -1
  38. package/docs/api.json +1474 -205
  39. package/docs/llms.md +698 -39
  40. package/docs/llms.txt +12 -1
  41. package/package.json +1 -1
  42. package/src/components/account-menu/account-menu.js +2 -2
  43. package/src/components/agent-thread/agent-thread.css +417 -0
  44. package/src/components/agent-thread/agent-thread.js +1365 -0
  45. package/src/components/app-rail/app-rail.css +11 -11
  46. package/src/components/app-sidebar/app-sidebar.css +90 -17
  47. package/src/components/app-sidebar/app-sidebar.js +120 -12
  48. package/src/components/approval-card/approval-card.css +289 -0
  49. package/src/components/approval-card/approval-card.js +1377 -0
  50. package/src/components/avatar/avatar.css +56 -1
  51. package/src/components/avatar/avatar.js +148 -26
  52. package/src/components/badge/badge.css +33 -20
  53. package/src/components/badge/badge.js +5 -4
  54. package/src/components/block-view/block-view.css +300 -0
  55. package/src/components/block-view/block-view.js +523 -0
  56. package/src/components/breadcrumb/breadcrumb.css +28 -3
  57. package/src/components/breadcrumb/breadcrumb.js +2 -2
  58. package/src/components/button/button.css +24 -13
  59. package/src/components/button/button.js +20 -2
  60. package/src/components/calendar/calendar.css +14 -4
  61. package/src/components/card-view/card-view.js +2 -2
  62. package/src/components/chart/chart.js +20 -5
  63. package/src/components/check-button/check-button.css +11 -3
  64. package/src/components/check-button/check-button.js +3 -3
  65. package/src/components/composer/composer.css +403 -0
  66. package/src/components/composer/composer.js +1441 -0
  67. package/src/components/context-menu/context-menu.css +7 -1
  68. package/src/components/date-picker/date-picker.css +6 -0
  69. package/src/components/date-picker/date-picker.js +5 -5
  70. package/src/components/date-picker/date-range-picker.css +6 -0
  71. package/src/components/date-picker/date-range-picker.js +3 -3
  72. package/src/components/date-picker/month-picker.js +3 -3
  73. package/src/components/date-picker/time-picker.css +6 -0
  74. package/src/components/datebox/date-range-box.js +30 -6
  75. package/src/components/datebox/datebox.js +44 -7
  76. package/src/components/dialog/dialog.css +0 -1
  77. package/src/components/dialog/dialog.js +2 -1
  78. package/src/components/dock/dock.js +2 -2
  79. package/src/components/dropdown/dropdown.css +2 -1
  80. package/src/components/entity-ref/entity-ref.css +8 -1
  81. package/src/components/file-item/file-item.css +1 -1
  82. package/src/components/finder/finder.js +2 -2
  83. package/src/components/groupbox/groupbox.js +2 -2
  84. package/src/components/kanban-view/kanban-view.css +8 -4
  85. package/src/components/kanban-view/kanban-view.js +3 -3
  86. package/src/components/kbd/kbd.css +64 -0
  87. package/src/components/kbd/kbd.js +121 -0
  88. package/src/components/launcher/launcher.css +30 -25
  89. package/src/components/launcher/launcher.js +15 -21
  90. package/src/components/list-toolbar/list-toolbar.css +7 -1
  91. package/src/components/menu-button/menu-button.css +9 -2
  92. package/src/components/message/message.js +2 -2
  93. package/src/components/module-bar/module-bar.css +11 -1
  94. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  95. package/src/components/navigation-bar/navigation-bar.css +3 -2
  96. package/src/components/pagination/pagination.js +2 -2
  97. package/src/components/panel/panel.js +2 -2
  98. package/src/components/prose/prose.css +53 -0
  99. package/src/components/prose/prose.js +152 -0
  100. package/src/components/questionnaire/questionnaire.css +7 -17
  101. package/src/components/questionnaire/questionnaire.js +16 -1
  102. package/src/components/rating/rating.css +3 -1
  103. package/src/components/run-status/run-status.css +208 -0
  104. package/src/components/run-status/run-status.js +782 -0
  105. package/src/components/run-trace/run-trace.css +443 -0
  106. package/src/components/run-trace/run-trace.js +1209 -0
  107. package/src/components/search/search.js +2 -2
  108. package/src/components/select/glyphs.js +3 -3
  109. package/src/components/select/select.css +35 -7
  110. package/src/components/select/select.js +4 -4
  111. package/src/components/source-list/source-list.css +208 -0
  112. package/src/components/source-list/source-list.js +355 -0
  113. package/src/components/stat-tile/stat-tile.css +56 -2
  114. package/src/components/stat-tile/stat-tile.js +25 -2
  115. package/src/components/stepper/stepper.css +2 -1
  116. package/src/components/stepper/stepper.js +3 -3
  117. package/src/components/tabbox/tabbox.css +2 -2
  118. package/src/components/tabbox/tabbox.js +2 -2
  119. package/src/components/table/table.css +52 -16
  120. package/src/components/table/table.js +7 -5
  121. package/src/components/tag-picker/tag-picker.css +56 -43
  122. package/src/components/tag-picker/tag-picker.js +21 -16
  123. package/src/components/tree/tree.css +44 -0
  124. package/src/components/tree/tree.js +97 -9
  125. package/src/components/value-list/value-list.css +25 -4
  126. package/src/components/value-list/value-list.js +2 -1
  127. package/src/components/view/record-view.js +3 -3
  128. package/src/components/view-settings/view-settings.css +2 -1
  129. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  130. package/src/core/icons.js +34 -3
  131. package/src/core/messages.js +143 -0
  132. package/src/elements/define.js +1 -0
  133. package/src/index.js +12 -2
  134. package/src/internal/agent-model.js +488 -0
  135. package/src/internal/app-rail.js +5 -1
  136. package/src/internal/highlight.js +104 -0
  137. package/src/internal/presence-loop.js +343 -0
  138. package/src/internal/row-actions.js +203 -0
  139. package/styles/base.css +26 -1
  140. package/styles/prose.css +306 -0
  141. package/styles/tokens/dark.css +97 -120
  142. package/styles/tokens/global.css +24 -9
  143. package/styles/tokens/semantic.css +464 -184
  144. package/styles/tokens/themes.css +9 -0
  145. package/styles/zx.css +10 -0
package/docs/llms.md CHANGED
@@ -147,7 +147,7 @@ a second navigation.
147
147
  | A spreadsheet-like editable grid (lines, positions) | `Grid` (`Grid.BillingItems()`) | `Table` with `editMode` — that is for occasional cell edits |
148
148
  | A tree | `TreeView` (one column) or `Finder` (Miller columns) | nested `<ul>`s |
149
149
  | Events over time | `Calendar` (agenda, day, week, month, year) | — |
150
- | One number with context | `StatTile` (delta, sparkline, loading) | a card with a big figure |
150
+ | One number with context | `StatTile` (delta, sparkline, loading; plain and one leading for a record's figures) | a card with a big figure |
151
151
  | A chart | `Chart` with `ChartJsAdapter` (Chart.js injected, never bundled) | — |
152
152
  | A linked record inline | `EntityRef` | a link |
153
153
  | Files | `FileItem` / `FileList`; uploading: `FieldUpload` | — |
@@ -183,12 +183,13 @@ the library already reads — never as component CSS:
183
183
 
184
184
  1. **Theme** — `data-zx-theme="auto"` unless the product pins `light` or `dark`. Both must work; a
185
185
  region may differ from the page.
186
- 2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate"`) or a five-stop
186
+ 2. **Accent** — a preset (`data-zx-preset="zx|zeyos|ocean|violet|rose|slate|folio"`) or a five-stop
187
187
  `--zx-accent-300…700` ramp built in the theme studio (<https://zx.zeyos.com/theme.html>), which
188
188
  exports the CSS. Never a one-off colour on a button.
189
189
  3. **Geometry** — the rhythm is three tokens on `:root` (or on a dense region): `--zx-space-unit`,
190
190
  `--zx-control-height`, `--zx-radius`. Dense data tools sit around 3.5px / 28px; comfortable
191
- products around 4.5px / 32–34px. Never a per-component size.
191
+ products around 4.5px / 32–34px. Never a per-component size. Data rows follow the control
192
+ height through `--zx-row-height`; set it only to make rows tighter or more relaxed than that.
192
193
  4. **Material** — how surfaces answer light, exported from the studio as token overrides (there
193
194
  is no attribute). `Glass` (the default: a thin lit pane), `Deep glass` (a thick one), `Frost`
194
195
  (milk glass for reading surfaces), `Smoke` (tinted glass that darkens the scene; dark-first
@@ -201,13 +202,20 @@ the library already reads — never as component CSS:
201
202
  6. **Colour roles** — `--zx-color-tone-*` for categories (tags, modules, avatars),
202
203
  `--zx-color-danger|warning|success|info` for status, `--zx-color-bg-current` for "you are here"
203
204
  and `--zx-color-bg-selected` for "what you picked", `--zx-color-bg-chrome` for navigation and
204
- inspector columns. A module's colour is its `tone` on `ModuleBar`.
205
- 7. **Type** — `--zx-font-sans`, `--zx-font-mono`, `--zx-text-md` (the control size); the steps
206
- follow.
207
- 8. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
205
+ inspector columns. A module's colour is its `tone` on `ModuleBar`. A product's own colour is a
206
+ role overridden once on `:root`, `light-dark(<light>, <dark>)` where the appearances differ —
207
+ never per theme attribute (see **Override once**).
208
+ 7. **Type** — two registers. Interface type is `--zx-font-sans`, `--zx-font-mono` and
209
+ `--zx-text-base` (every `--zx-text-*` step derives from it). Reading type is a second, separate
210
+ decision for authored content in `.zx-prose`: `--zx-font-prose` (a serif here leaves the
211
+ interface alone), `--zx-prose-size`, `--zx-prose-measure`.
212
+ 8. **Content** — wrap authored text (a document, notes, a message body, an assistant's answer) in
213
+ `.zx-prose`; set emphasis apart with `.zx-callout` (neutral unless it is a status or a
214
+ category). Never style headings and paragraphs per screen.
215
+ 9. **Fields** — `data-zx-fields="quiet"` on property panels (no border or fill until hovered or
208
216
  focused).
209
- 9. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
210
- 10. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
217
+ 10. **Print** — works without work; keep status badges, hide chrome. Nothing to add.
218
+ 11. **Markup-first pages** — `defineElements()` for `<zx-*>` custom elements where templates are
211
219
  authored as HTML.
212
220
 
213
221
  ### Never
@@ -234,18 +242,53 @@ Themes: `light` | `dark` | `auto` (follows OS).
234
242
  **One geometry.** Spacing steps are multiples of one unit
235
243
  (`--zx-space-unit`, 4px: `--zx-space-1…8` = 4/8/12/16/20/24/32/40px), radius steps are fractions of
236
244
  one base (`--zx-radius`, 4px: `-sm/-md/-lg/-xl` = 2/3/4/6px; `-full` only for shapes whose roundness
237
- is the meaning — badges, avatars, toggles), and controls are `--zx-control-height` (30px) tall.
245
+ is the meaning — status pills, avatars, toggles; a tag takes `-md`; `-panel` is the corner of a panel that holds rounded
246
+ items, a menu or a listbox, concentric with them: the item corner plus the inset between them, 6px
247
+ at the default and square when the base is 0), and controls are `--zx-control-height` (30px) tall.
248
+ A data row — a table row, a single-line list row — is `--zx-row-height`, derived from the control
249
+ height (36px at the default), so every list on a screen shares one rhythm and a tighter product is
250
+ still one decision. Type is one base: `--zx-text-base` (14px) with every `--zx-text-*` step derived
251
+ from it (12 / 13 / 14 / 16 / 18 / 24 / 30px at the default), so changing the base keeps the
252
+ hierarchy; setting `--zx-text-md` alone still moves only the control size.
238
253
  To tighten or loosen an application, override those tokens on `:root` or on any region. The
239
254
  geometry and material tokens (control size, radius, spacing, blur and glass filters, durations,
240
- easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` block, so an
241
- override on `:root` reaches nested light and dark regions alike; theme blocks carry colours only:
255
+ easings, the type scale) are declared on `:root` only, never on a `[data-zx-theme]` element, so an
256
+ override on `:root` reaches nested light and dark regions alike — and colours work the same way
257
+ (see **Override once**):
242
258
 
243
259
  ```css
244
260
  :root { --zx-space-unit: 3.5px; --zx-control-height: 28px; }
245
261
  ```
246
262
 
263
+ **Override once.** Every colour role is declared once, on `:root`; a theme element sets only
264
+ `color-scheme`, which picks the half of each `light-dark()` pair it reads. So a colour override
265
+ belongs on `:root` as well, written as `light-dark(<light>, <dark>)` where the two appearances
266
+ differ, and it reaches light, dark, auto and every nested region alike — together with everything
267
+ derived from it (hover, current, the glass and overlay tiers, and the tone tints follow
268
+ `--zx-color-text` and `--zx-color-bg-surface`) and every material the theme studio exports:
269
+
270
+ ```css
271
+ :root {
272
+ --zx-color-bg-page: light-dark(#f7f8fa, #14161b);
273
+ --zx-color-text-muted: light-dark(#5b6170, #a3a9b6);
274
+ }
275
+ ```
276
+
277
+ A value without `light-dark()` applies to both appearances. The accent is a ramp, not a role: set
278
+ `--zx-accent-300…700` (or use a preset) and each appearance takes its own stop. A nested
279
+ `data-zx-preset` region restates the roles that read that ramp (`--zx-color-accent*`,
280
+ `--zx-color-bg-selected`, `--zx-color-ring`, `--zx-focus-ring`, `--zx-color-overlay-selected`, the
281
+ overlay images), so an override of one of those meant to reach such a region too is written
282
+ `:root, [data-zx-preset] { … }`. Never register a colour role with `@property`: a registered colour
283
+ resolves where it is declared and stops following the region. Script that needs a role's value
284
+ reads a probe element's computed `color`, not the property's text, which may be a `light-dark()`
285
+ pair that a canvas cannot parse. `light-dark()` needs a 2024 browser; older ones read Xenon's own
286
+ per-theme fallback, where a `:root` override stops at a nested theme region, so an application that
287
+ supports them puts its own `light-dark()` overrides inside `@supports (color: light-dark(#000,
288
+ #fff))`.
289
+
247
290
  **Accent presets.** A second, orthogonal attribute picks the accent ramp:
248
- `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate"` (`zx` is the default and
291
+ `data-zx-preset="zx" | "zeyos" | "ocean" | "violet" | "rose" | "slate" | "folio"` (`zx` is the default and
249
292
  need not be set). A preset repoints five tier-1 tokens — `--zx-accent-300` … `--zx-accent-700` —
250
293
  and the semantic tier takes its own stop per polarity (600/700 on light surfaces, 300/400/500 on
251
294
  dark), so one five-line block rethemes light, dark, and auto together. Status colours are not part
@@ -293,10 +336,16 @@ increased-contrast, forced-colour, and unsupported-filter environments restore s
293
336
  Top-layer components remain DOM children of their nearest Zx theme scope, so a theme or material
294
337
  set on an application region continues to inherit through its menus, dialogs, tooltips, and toasts.
295
338
 
296
- Define a product theme by overriding **semantic** tokens under a `[data-zx-theme="name"]` selector:
339
+ Define a product theme as an accent ramp (a preset) plus **semantic** token overrides, each declared
340
+ once on `:root` as above — not under a `[data-zx-theme="name"]` selector, which would stop at the
341
+ first nested region:
297
342
  `--zx-color-bg-page/surface/raised/control/muted/hover/selected`, `--zx-color-bg-current` (the
298
343
  neutral "you are here" fill of the current nav item, row, tab, or pressed toggle — never the
299
344
  accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off the canvas),
345
+ `--zx-color-text-chrome` (navigation labels at rest, one ink step under the content and above 7:1;
346
+ hover, focus and the current item take the full text colour), `--zx-color-border-chrome` (the line
347
+ where a chrome column meets the canvas: none in light, where the tone step separates them; a
348
+ hairline in dark, under `prefers-contrast: more`, and in forced colours),
300
349
  `--zx-color-glass-chrome/surface`,
301
350
  `--zx-color-overlay-surface/panel/backdrop/border/hover/selected/divider/scrim`,
302
351
  `--zx-overlay-surface-image/toast-image/panel-image`,
@@ -309,12 +358,29 @@ accent), `--zx-color-bg-chrome` (navigation and inspector columns, one tone off
309
358
  tiles, avatars — neither the accent nor a status) and `-solid` (a solid identity fill, such as a
310
359
  module tile, that the white icon glyph reads on at 3:1 in both themes), the chart series
311
360
  `--zx-color-chart-1…8`,
312
- `--zx-focus-ring`, `--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
361
+ `--zx-color-ring` with `--zx-focus-ring` (keyboard focus; see **Focus** below),
362
+ `--zx-control-height/-radius`, `--zx-space-*`, `--zx-radius-*`, `--zx-text-*`
313
363
  (`-3xl` for document titles), `--zx-weight-medium/-semibold`, `--zx-tracking-tight/-title`. Never
314
364
  use tier-1 palette tokens (`--zx-gray-*`, `--zx-green-*`, `--zx-emerald-*`, `--zx-tone-*`) or raw
315
365
  color literals in application/component CSS. Prefer the least-specific override that works (global
316
366
  token → then, if needed, a component style).
317
367
 
368
+ **Focus.** Keyboard focus is one quiet line: `--zx-focus-ring` is a single 2px spread shadow in
369
+ `--zx-color-ring` (the accent, at the stop each theme reads as text), opaque, so it clears the 3:1
370
+ a focus indicator needs against everything it sits on — the page, the chrome, a card, a raised
371
+ panel, a current row and a selected row — in both themes, under every preset and tint, and for any
372
+ custom ramp that keeps the promise above. Being one shadow, it works both ways round:
373
+ `box-shadow: var(--zx-focus-ring)` draws it around a control, `box-shadow: inset
374
+ var(--zx-focus-ring)` inside a row, a tab, or a cell. Combine it by listing it after the
375
+ element's own shadows (`var(--zx-focus-ring), var(--zx-drag-shadow)`), with any `inset` layer
376
+ first, since `inset` belongs to one shadow of a list rather than to the list. Where the focused
377
+ element is itself an accent fill — a primary button, a chosen day — the ring would only make it
378
+ look larger, so lead with a 1px line in the fill's ink: `box-shadow: inset 0 0 0 1px
379
+ var(--zx-color-on-accent-solid), var(--zx-focus-ring)` (`--zx-color-on-accent` on a
380
+ `--zx-color-accent` fill). Leave the outline transparent rather than removing it: forced colours
381
+ drop every shadow and paint that outline in the system highlight instead. A product that restyles
382
+ the ring keeps it one shadow, at least 2px, and at 3:1; to recolour it, set `--zx-color-ring`.
383
+
318
384
  **Print.** `zx.css` imports `styles/print.css` last. It releases sticky headers and scroll
319
385
  containers, drops fills, shadows, zebra striping and focus rings, hides overlays and navigation
320
386
  chrome, repeats table headers across pages, keeps cards and rows from breaking, and prints link
@@ -559,6 +625,65 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
559
625
  Each component is `new Component(target, options)`. Events are the component-level names (also
560
626
  dispatched as bubbling `zx-<name>` on the root). Detail is always an object.
561
627
 
628
+ <!-- doc:prose -->
629
+ ### Prose — `.zx-prose` and `.zx-callout`
630
+
631
+ The reading register: a class, not a component, that sets authored content — a document, a
632
+ record's notes, a message body, an assistant's answer — in the reading tokens rather than the
633
+ interface ones. Write plain HTML inside it: `h1`–`h4`, `p`, `ul`/`ol`, `blockquote`, `hr`, links,
634
+ inline `code`, `pre`, `kbd`, `mark`, tables, `figure`/`figcaption`, `img`.
635
+
636
+ - **Tokens** — `--zx-font-prose` (the interface stack by default; a serif here leaves the interface
637
+ alone), `--zx-prose-size` (16px, `--zx-text-lg`), `--zx-prose-leading` (1.7), `--zx-prose-measure`
638
+ (62ch, the reading width). Headings scale with the reading size and read `--zx-weight-title`.
639
+ - **Attributes** — `data-size="sm"` sets prose at the interface size, for comments, previews, and
640
+ panels; `data-zx-measure="full"` drops the measure where the column already sets the width.
641
+ - **Rhythm** — one gap between blocks, more above a heading and less below it; links in the body
642
+ colour over a quiet underline, accent on hover; tables without a frame, a muted header over
643
+ hairline rows, `data-align="end"` cells in tabular figures.
644
+ - **Content colour** — a bare `mark` highlights in the amber tone; `mark[data-tone]` in any of the
645
+ nine tones; a bare `span[data-tone]` colours its text, and `data-fill` highlights it as well.
646
+ - **Callout** — `.zx-callout` with an optional `.zx-callout__icon` and a `.zx-callout__body`
647
+ (`.zx-callout__title` for a bold first line): a tinted fill, no frame, at the interface size.
648
+ Neutral by default, because most callouts are emphasis; `data-kind="info|success|warning|danger"`
649
+ makes it a status and `data-tone` a category. Works inside or outside prose.
650
+ - **Specificity** — every rule is `.zx-prose` plus `:where()`, and the stylesheet loads before the
651
+ components, so a badge, an entity reference, or a table placed in prose keeps its own styles,
652
+ while an application's bare element reset cannot undo the rhythm.
653
+ - **Section links** — `proseAnchors(root, options)` ends every `h2`–`h4` with an `id` inside a
654
+ `.zx-prose` under `root` with a small link to itself (`a.zx-prose__anchor`, "Copy link to …").
655
+ It shows while the heading is pointed at or the link has focus (and always on a touch screen or
656
+ under a contrast preference). A click copies the address with the section's hash — the current
657
+ address by default, `href(id)` to build another — and confirms with a tick and a polite "Link
658
+ copied"; it never changes the location, and a middle or modified click is left to the browser.
659
+ Options: `selector`, `label` (`%1` is the heading), `title`, `feedback`, `feedbackDuration`,
660
+ `href`, `oncopy(url, copied)`. It returns `{refresh(), destroy()}`: call `refresh()` after
661
+ re-rendering the content. Headings without an id are skipped — give the ones worth linking a
662
+ stable id. `sectionHref(base, id)` builds the address.
663
+ <!-- /doc -->
664
+
665
+ <!-- doc:kbd -->
666
+ ### Kbd — `kbd(keys, options)`
667
+
668
+ A factory (not a class) returning keycaps: one `<kbd class="zx-kbd">` holding a nested
669
+ `<kbd class="zx-kbd__key">` per key, which is how HTML marks up a combination. Button shortcuts,
670
+ the launcher's hints, and shortcut references all use it, so a key looks the same everywhere.
671
+
672
+ - **Signature** — `kbd(keys, { size, tone })` → `HTMLElement`. `keys` is a chord written like
673
+ `aria-keyshortcuts` (`'Mod+Shift+K'`; a literal plus as `'Mod++'`) or an array of keys for a
674
+ sequence (`['g', 'i']`). `size: 'md'|'sm'` (`sm` inside buttons and menu rows); `tone:
675
+ 'neutral'|'inherit'` (`inherit` draws the caps in the surrounding ink, for a solid button or a
676
+ dark toast). `keyLabels(keys, { apple })` returns the labels without building DOM.
677
+ - **Labels** — `Mod` is ⌘ on Apple platforms and Ctrl elsewhere; `Alt`, `Shift`, `Ctrl`,
678
+ `Backspace`, `Delete`, `Tab` become ⌥ ⇧ ⌃ ⌫ ⌦ ⇥ on Apple platforms and words elsewhere; `Enter`,
679
+ `Escape` and the arrows become ↵, Esc, ↑ ↓ ← →; single letters are upper-cased.
680
+ - **Look** — a surface fill, one hairline and a 1px foot, the label at the small size and medium
681
+ weight, centred on its capital height; a single key is square. Retint it with `--zx-kbd-ink`,
682
+ `--zx-kbd-fill` and `--zx-kbd-line` on any ancestor.
683
+ - **Accessibility** — the caps are presentation. Announce a control's shortcut with
684
+ `aria-keyshortcuts` on the control and mark a hint that repeats it `aria-hidden`.
685
+ <!-- /doc -->
686
+
562
687
  <!-- doc:button -->
563
688
  ### Button — `button(options)` / `buttonGroup(buttons)`
564
689
 
@@ -582,9 +707,9 @@ accept.
582
707
  <!-- doc:badge -->
583
708
  ### Badge — `badge(options)` / `badgeGroup(badges)`
584
709
 
585
- Factories (not classes) returning a status pill: a small, non-interactive `<span>` carrying a
586
- semantic colour — or, with `tone`, a categorical one — used for stages, counts, tags, and
587
- record-header metadata. A badge with no label but a `title` is named for assistive technology
710
+ Factories (not classes) returning a chip: a small, non-interactive `<span>` carrying a semantic
711
+ colour — a status — or, with `tone`, a categorical one — a tag — used for stages, counts, labels,
712
+ and record-header metadata. A badge with no label but a `title` is named for assistive technology
588
713
  through `role="img"`; everything else is plain text and needs no ARIA.
589
714
 
590
715
  - **Options** — `label`, `icon` (an icon name, rendered before the label), `kind:
@@ -597,11 +722,18 @@ through `role="img"`; everything else is plain text and needs no ARIA.
597
722
  accent nor the status set, so a project tagged red never reads as an error. When `tone` is set it
598
723
  decides the colour and `kind` is ignored for it; every `variant` still applies (soft: tinted,
599
724
  borderless; solid: filled with the tone's ink; outline). The badge carries `data-tone`. Badges
600
- are medium weight and sentence case.
725
+ are sentence case.
726
+ - **Two shapes, one construction** — a status is a pill (`--zx-radius-full`); give a workflow state
727
+ `dot: true`, a 6px dot centred in the pill's round end. A tag (any badge with a `tone`) has small
728
+ corners (`--zx-radius-md`). Both are one fill and no line, 12px at weight 500 at either size,
729
+ and their height follows the row they sit in: about five ninths of `--zx-row-height` for `md`
730
+ and half of it for `sm` (20px and 18px in the default row), never below a line of their own text,
731
+ so a chip follows the row height setting without making a row taller. `TagPicker` builds its tags with
732
+ `badge()`, so a label reads the same in a list row, a record header and the field that edits it.
601
733
  - **Neutral and small** — the neutral soft fill is a wash of the text colour, not an opaque surface
602
734
  step, so it stays visible on raised surfaces in the dark theme. `size: 'sm'` fits table cells
603
- and board cards; a small badge with `dot` keeps the 12px text and a full spacing step between
604
- dot and label.
735
+ and board cards; it is shorter and tighter, never smaller type. Under `prefers-contrast: more` a
736
+ soft badge gets its edge back, and under forced colours every badge does.
605
737
  - **Methods** — none. `badge(options)` → `HTMLSpanElement`, `badgeGroup([badge(…), …])` → a wrapping
606
738
  inline row with its own spacing; you own both elements.
607
739
  - **Events** — none; a badge is not interactive.
@@ -866,14 +998,28 @@ and the component is decorative by default so adjacent identity text is not anno
866
998
  - **Options** — `src`, `name`, `initials`, `label`, `size: 'sm'|'md'|'lg'|<pixels>` (24 / 32 /
867
999
  40px at the default spacing unit), `shape: 'circle'|'rounded'|'square'`, `tone:
868
1000
  'blue'|'teal'|'green'|'amber'|'orange'|'red'|'pink'|'violet'|'slate'|null`, `status:
869
- 'online'|'away'|'busy'|'offline'|null`, and `statusLabel`.
1001
+ 'online'|'away'|'busy'|'offline'|null`, `statusLabel`, `activity:
1002
+ 'idle'|'thinking'|'working'|'needs-you'|'blocked'|'offline'|null`, `activityLabel`, `animate: false`, and `phase: null|number`.
870
1003
  - **Fallback** — no ring; the `--zx-color-tone-*-bg` fill with its `-fg` ink, initials at 0.4× the
871
1004
  size (never under 10px), weight 600, one initial below 24px. `tone: null` derives the tone with
872
1005
  `avatarTone(name)` (exported from the module): FNV-1a over the trimmed, NFC-normalised,
873
1006
  lower-cased name, mapped onto the eight chromatic tones, so a person keeps their colour on every
874
1007
  screen. `slate`, the neutral, is reserved for an avatar with no name and can be set explicitly.
875
1008
  The root carries `data-tone`. `avatarInitials(name, limit = 2)` returns the initials.
876
- - **Methods** — `set(values)`, `setStatus(status, label?)`, `hasImage()`, `destroy()`.
1009
+ - **Agent activity** — `activity` draws what an agent is doing as a dot whose shape differs as
1010
+ well as its tone: solid success (working), solid info (thinking), solid warning (needs you), a
1011
+ danger square (blocked), a hollow ring (idle), and a dashed ring (offline). Its word ("Needs
1012
+ you", or `activityLabel`) joins the accessible name and the dot's tooltip, and the root carries
1013
+ `data-activity`. When both are given, `activity` wins over `status`. `animate: true` moves the
1014
+ avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and
1015
+ blinks — in the one `requestAnimationFrame` loop every animated avatar on the page shares: only
1016
+ on screen, never while the page is hidden, and back at rest under reduced motion (the system's
1017
+ or a `data-zx-motion="reduced"` region). While it is on, the loop owns the root's `transform`. `phase` sets where in its activity's cycle the avatar moves, as a fraction from 0 up to 1
1018
+ (whole turns wrap): two avatars of one agent on the same screen — a roster and an inspector —
1019
+ at `phase: 0` and `phase: 0.5` move half a cycle apart. `null` derives the phase from the name
1020
+ (or the initials), so avatars of the same agent without a phase move in step.
1021
+ - **Methods** — `set(values)` (any option above, `phase` included, applied while the avatar moves), `setStatus(status, label?)`,
1022
+ `setActivity(activity, label?)`, `getActivity()`, `hasImage()`, `destroy()`.
877
1023
  - **Accessibility** — set `label` only when the avatar stands alone. Presence is supplementary
878
1024
  status, not the account's accessible name; supply `statusLabel` when it conveys information.
879
1025
  <!-- /doc -->
@@ -1305,9 +1451,19 @@ Text date input with a calendar popover. `DateTimeBox(target, opts)` is a Datebo
1305
1451
  `time: true`, which also brings the TimePicker (and its clock face) into the popover. Format
1306
1452
  tokens are the date-utility ones: `%d %m %Y %H %M`.
1307
1453
 
1308
- - **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `time: false`, `min`,
1309
- `max`, `placeholder`, `clearable: true` (the clear button shows while there is a value and the
1310
- box is enabled; without `clearable` the input keeps no room for it), `disabled`.
1454
+ - **Options** — `value: Date | number(unix) | string`, `format: '%d.%m.%Y'`, `displayFormat: null`,
1455
+ `time: false`, `min`, `max`, `placeholder`, `clearable: true` (the clear button shows while
1456
+ there is a value and the box is enabled; without `clearable` the input keeps no room for it),
1457
+ `disabled`.
1458
+ - **Two formats** — `format` is what the reader types, and what the field shows while it has
1459
+ focus; it is parsed, so it takes numeric tokens only. `displayFormat` is what the field shows at
1460
+ rest, so a date field reads the way the rest of the screen writes dates (`'%e %b %Y'` → "2 Nov
1461
+ 2026" beside a header that says "Created 19 Jul 2026"). It is never parsed, so month and weekday
1462
+ names (`%b %B %a %A`) are fine; `null` shows `format`. Focus switches the text to the typing
1463
+ format, a valid commit on blur or Enter switches it back, and text that failed to parse stays as
1464
+ typed. With `time`, a format without `%H`/`%M` gets ` %H:%M` appended, the display format too.
1465
+ The placeholder still describes `format`, and string values passed to `set()` are parsed with it.
1466
+ `dateboxFormats({format, displayFormat, time})` → `{format, display}` resolves both the same way.
1311
1467
  - **In a Field** — field types `date`/`datetime` (and `daterange`) fill the control column like a
1312
1468
  text input and give way in a narrow two-column row; standalone, the box keeps its own width.
1313
1469
  - **Methods** — `get(unit='date')` (`'seconds'` → unix), `set(value, {silent})` (accepts a Date;
@@ -1333,7 +1489,7 @@ An inline two-month calendar for picking a start and an end day, plus the form-u
1333
1489
 
1334
1490
  #### DateRangeBox
1335
1491
 
1336
- - **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open.
1492
+ - **Options** — everything DateRangePicker takes, plus `format: '%d.%m.%Y'`, `displayFormat: null`, `separator: ' – '`, `placeholder: null` (derived from the format when null), `clearable: true` (no clear button while disabled, and no room kept for one without it). Typed text is parsed as `"<start><separator><end>"`; a lone date reads as a one-day range and a trailing separator keeps the range half open. `displayFormat` is the endpoints' format at rest, as on Datebox (`'%e %b %Y'` → "3 Aug 2026 – 9 Aug 2026"); focus switches to `format`, and text left untouched while the calendar holds focus goes back to the display format.
1337
1493
  - **Methods** — `get(unit = 'date')` (`'seconds'` returns `{start, end}` as Unix seconds), `set(range, {silent})` accepting `{start, end}` of Dates, Unix-seconds numbers, or formatted strings, `clear({silent})`, `open()`, `close()`, `enable()`, `disable()`, `focus()`, `destroy()`.
1338
1494
  - **Events** — `change {start, end}`, `invalid {text}` when the typed value cannot be parsed (the text stays editable and the field takes `data-state="invalid"` plus `aria-invalid`), `open`, `close`.
1339
1495
  <!-- /doc -->
@@ -2221,7 +2377,17 @@ mutate the caller's data.
2221
2377
  - **Options** — `items` (nested), `valueKey: 'ID'`, `labelKey: 'name'`, `childrenKey: 'children'`,
2222
2378
  `expanded: []`, `selection: 'single'|'multi'|false`, `selected: []`, `checkboxes: false`
2223
2379
  (tri-state), `checked: []`, `icons: true`, `renderLabel`, `load: (node)=>Promise<children>`
2224
- (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`.
2380
+ (lazy children; mark a branch with `hasChildren: true`), `filter`, `emptyText`, `height`,
2381
+ `rowActions: (node) => actions`, `moreLabel: 'More actions'`.
2382
+ - **Row actions** — `rowActions(node)` returns the row's commands: `{icon, label, onSelect(node),
2383
+ disabled?, danger?}` descriptors, or nodes of your own placed as given. One or two show as icon
2384
+ buttons at the row's end; with more, the first shows and the rest fold into a "More actions"
2385
+ menu (a node never folds). They rest out of sight and keep their room, and show while the row is
2386
+ pointed at, focused or selected, while its menu is open, and always on a touch screen, under a
2387
+ contrast preference and in forced colours — the `data-zx-reveal` utility. Every descriptor is
2388
+ also in the row's context menu (right-click, Shift+F10, the Menu key), and each control is named
2389
+ after its action and its row ("Add sub-page: Onboarding"); the row's own name stays its label.
2390
+ Use them only for repeated, secondary commands that are reachable another way too.
2225
2391
  - **Methods** — `setItems()`, `getItems()`, `getNode(id)`, `getPath(id)`, `setFilter(query)` (keeps
2226
2392
  matching nodes' ancestors and opens the surviving branches),
2227
2393
  `expand(id)`/`collapse(id)`/`toggle(id)` (async — they await the loader),
@@ -2234,6 +2400,9 @@ mutate the caller's data.
2234
2400
  activates, Space selects or toggles the checkbox, `*` expands every sibling, typing jumps to the
2235
2401
  next match. A typed character's default action is prevented, so find-as-you-type and page
2236
2402
  shortcuts do not act on it too; typing into a control inside a row is left to that control.
2403
+ With row actions, Tab from the focused row walks that row's actions and then leaves the tree
2404
+ (Shift+Tab comes back); keys pressed on an action belong to it, and clicking one neither selects
2405
+ nor focuses the row.
2237
2406
  - **Appearance** — the selected node of a single-selection tree is where you are: the neutral
2238
2407
  `--zx-color-bg-current` fill, the text colour, a semibold label. A `selection: 'multi'` tree is a
2239
2408
  set of picks and keeps the accent tint. Icons, folders included, are drawn in
@@ -2503,12 +2672,16 @@ yet. Field type: `tagpicker`.
2503
2672
  `filter: 'local'|(query)=>Promise<items>`, `minQuery: 0`, `debounce: 200`, `allowCreate: false`,
2504
2673
  `max` (maximum tags; further options become `aria-disabled`), `closeOnSelect: false`,
2505
2674
  `placeholder`, `listHeight: 260`, `disabled`, `readonly`, `renderItem`, `renderTag`.
2675
+ - **Tags are Badges** — every selected tag is built by `badge()` (`.zx-badge.zx-tag-picker__tag`):
2676
+ the Badge's height from the row, 12px medium type, padding and one fill, with the tag shape's
2677
+ small corners. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
2678
+ `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`), so a toned tag is exactly the
2679
+ `badge({ tone })` a list row or record header shows for the same item; a tone wins over a colour.
2680
+ An untoned tag keeps the text ink, because in a field it is the value.
2506
2681
  - **Tag identity** — icon values accept a bundled icon name or Node; colors (a CSS colour or a token
2507
2682
  reference such as `var(--zx-color-tone-blue-fg)`) are scoped to the tag and its option through
2508
- `--zx-tag-color`. `toneKey` names a categorical tone from the Badge palette (`blue`, `teal`,
2509
- `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`): the tag takes its fill and ink as a
2510
- toned Badge does (`data-tone`), and a tone wins over a colour. Custom `renderItem`/`renderTag`
2511
- remain authoritative.
2683
+ `--zx-tag-color`. An option shows its icon on a tile of its colour; inside a tag the icon is a bare
2684
+ glyph, since the tag is already the fill. Custom `renderItem`/`renderTag` remain authoritative.
2512
2685
  - **Read-only** — `readonly` (or `setReadonly(true)`) shows only the tags: no input, chevron, or
2513
2686
  remove buttons, so a full row of tags never wraps onto an empty line.
2514
2687
  - **Methods** — `getValues()`, `getItems()`, `setValues(values, {silent})`, `addValue()`,
@@ -2567,13 +2740,21 @@ returns the component, the way `tooltip()` does; call `.toElement()` for the nod
2567
2740
 
2568
2741
  - **Options** — `label`, `value`, `format: 'number'|'currency'|'percent'|'fileSize'|null|fn`,
2569
2742
  `currency`, `locale`, `caption`, `delta`, `deltaKind: 'positive'|'negative'|'neutral'`,
2570
- `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `href`, `clickable`, `loading`,
2571
- `msg`.
2743
+ `deltaFormat`, `deltaLabel`, `trend: number[]`, `icon`, `kind`, `variant: 'default'|'plain'`,
2744
+ `emphasis`, `href`, `clickable`, `loading`, `msg`.
2572
2745
  - **Appearance** — the label is a sentence-case muted line (13px, medium); the value is the loud
2573
2746
  part (24px, weight 650, tabular figures); `caption` is one muted context line under it ("of
2574
2747
  13,184"). `icon` is a muted glyph beside the label, never a coloured chip; `kind` tints only the
2575
2748
  sparkline. The tile is a column with the sparkline at its foot, so tiles in a row are the same
2576
2749
  height and line up whether or not each has a caption, a delta or a trend.
2750
+ - **Framed or plain** — the default is a framed tile on its own surface: use it where a figure
2751
+ stands among other content, as on a dashboard. `variant: 'plain'` drops the frame, the fill and
2752
+ the padding, for a record's own figures under its title: its text sits on the content edge,
2753
+ space alone separates it from the next, and the figure steps down to 16px. Do not draw boxes
2754
+ around plain figures in the layout either. Reflected as `data-variant`.
2755
+ - **One figure leads** — `emphasis: true` sets one figure per row above the others: 24px in a
2756
+ plain row (the record title's size, never above it), 30px on a framed tile. Reflected as
2757
+ `data-emphasis`. The size is `--zx-stat-tile-value-size`, which the loading skeleton reads too.
2577
2758
  - **Methods** — `update(options)`, `getAccessibleName()`.
2578
2759
  - **Events** — `click {event}`.
2579
2760
 
@@ -2971,8 +3152,18 @@ inline; every rail state opens descendants toward the workspace in anchored flyo
2971
3152
  `side: 'left'|'right'|'top'|'bottom'`, `layout: 'tree'|'modules'`, `module`, `moduleBar`
2972
3153
  (`{appearance, labels: 'auto'|'beside'|'below'|'hidden', allModules, label}` for the module
2973
3154
  strip), `label`,
2974
- `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`, and
2975
- `renderIcon(item, context)`. Icon values may also be names, nodes, components, or factories.
3155
+ `header`, `footer`, `railHeader`, `railFooter`, `openDelay: 80`, `closeDelay: 160`,
3156
+ `moreLabel: 'More actions'`, and `renderIcon(item, context)`. Icon values may also be names,
3157
+ nodes, components, or factories.
3158
+ - **Row actions** — `actions` on a destination lists its commands: `{icon, label, onSelect(item),
3159
+ disabled?, danger?}` descriptors or nodes, laid out as TreeView's `rowActions` (two at most, the
3160
+ rest in a "More actions" menu). They rest out of sight over the end of the row, which keeps room
3161
+ for them, and show while the row is pointed at, holds focus, is the current page or has its menu
3162
+ open — always on a touch screen, under a contrast preference and in forced colours. Each is named
3163
+ after its action and the destination ("Rename: Customers"). Only the actions of the destination
3164
+ holding focus are Tab stops, right after it; a right-click or Shift+F10 on the destination lists
3165
+ them all. The expanded tree and the modules layout's panel draw them; minimized flyouts show the
3166
+ destinations only.
2976
3167
  - **Sections** — an item with `section: true` is a quiet heading over its `children`, which stay
2977
3168
  at its own level: never indented, collapsed, focused, or selected, and it needs no `id`.
2978
3169
  `actions` (a node) adds trailing controls such as an add button. Sections replace stacking
@@ -3101,6 +3292,445 @@ bar.setBadge('mail', 8);
3101
3292
  `--zx-control-height` resizes the bar; a coarse pointer keeps a 40px target.
3102
3293
  <!-- /doc -->
3103
3294
 
3295
+ ### Agents — the conversation model
3296
+
3297
+ The agent components draw a conversation with one or more AI agents from **plain JSON**: no
3298
+ functions and no DOM nodes in the data, so an agent can produce it, an application can store and
3299
+ replay it, and a component can render it. Three rules hold for every agent component:
3300
+
3301
+ 1. **The application owns transport and state.** No agent component fetches anything. The
3302
+ application feeds them (`upsert`, `patch`, `appendText`) and acts on the intents they emit
3303
+ (`send`, `stop`, `approve`, `regenerate`, …).
3304
+ 2. **Model text is data.** Every string an agent wrote reaches the page as text. Inside a text run
3305
+ the whole grammar is `**bold**`, `` `code` `` and `[n]` citations (a backslash makes a marker
3306
+ literal); there are no links, no HTML, and no images in answer text.
3307
+ 3. **Consequence comes from the application.** Whether an action needs a confirmation — and which
3308
+ — is decided by the application from the tool the action triggers, never taken from model
3309
+ output.
3310
+
3311
+ A thread is a list of items, each `{id, type, at?, author?, …}`, where `author` is a key into
3312
+ the thread's `authors` (`{name, kind: 'person'|'agent'|'model', initials?, tone?, activity?, via?}`):
3313
+
3314
+ ```json
3315
+ [
3316
+ {"id": "ask", "type": "user", "text": "Reconcile September and draft reminders.", "files": [{"name": "Policy.pdf", "size": 188416}]},
3317
+ {"id": "note", "type": "text", "author": "finance", "text": "I’ll check the bank feed first."},
3318
+ {"id": "work", "type": "trace", "author": "finance", "steps": [
3319
+ {"id": "q", "kind": "query", "label": "Queried invoices", "count": "42 rows", "ms": 800, "tool": "invoices.search", "args": "{\"month\": \"2026-09\"}", "result": "42 invoices"}
3320
+ ]},
3321
+ {"id": "a1", "type": "answer", "author": "finance", "blocks": [
3322
+ {"type": "p", "text": "Three invoices are more than **14 days** late [1]."},
3323
+ {"type": "figures", "rows": [["Late", "3 invoices", "€19,375.50"]]}
3324
+ ], "sources": [{"id": "inv", "title": "Invoices · September", "kind": "call", "call": "q"}]},
3325
+ {"id": "ok", "type": "approval", "author": "finance", "title": "Send 3 reminder emails?", "status": "pending"},
3326
+ {"id": "n1", "type": "notice", "text": "The bank feed timed out; retried once.", "tone": "warning"}
3327
+ ]
3328
+ ```
3329
+
3330
+ - **Blocks** — `p`, `quote`, `heading` (`level: 2|3`), `list` (`ordered`), `code` (`language`),
3331
+ `table` (`columns`, `rows`, `align`), `figures` (`rows` of `[label, detail, value]` or
3332
+ `{label, detail?, value, call?}`), `callout` (`tone`, `title`), `artifact` (`id`, `title`,
3333
+ `kind: 'document'|'code'`, `versions`).
3334
+ - **Steps** — `{id, kind: 'search'|'read'|'query'|'write'|'run'|'call'|'handoff'|'think', label,
3335
+ status, doing?, detail?, ms?, count?, sources?, tool?, args?, result?, error?, retryOf?, actor?,
3336
+ to?, at?}`. A retry names the step it repeats with `retryOf`; a hand-off names `actor` and `to`.
3337
+ - **States** — runs and steps are `queued`, `running`, `waiting`, `paused`, `done`, `failed`,
3338
+ `stopped`, or `skipped`; an agent's activity is `idle`, `thinking`, `working`, `needs-you`,
3339
+ `blocked`, or `offline`. Each is always drawn as a glyph and a word, never by colour or motion
3340
+ alone.
3341
+
3342
+ <!-- doc:block-view -->
3343
+ ### BlockView — `new BlockView(target, options)` / `renderBlocks(blocks, options)`
3344
+
3345
+ An answer an agent wrote, drawn block by block as semantic elements inside `.zx-prose`, and
3346
+ written to as it streams. Finished blocks are never redrawn: `append()` and `appendText()` touch
3347
+ only the last block, so a reader's selection or focus in an earlier paragraph survives the rest of
3348
+ the answer arriving.
3349
+
3350
+ - **Options** — `blocks: []`, `headingLevel: 3` (the element level of a level-2 `heading` block;
3351
+ set it one below the heading that names the answer), `size: 'sm'|'md'` (interface or reading
3352
+ size), `streaming: false`, `sources: null` (names the citation buttons by title), `msg`.
3353
+ - **Methods** — `setBlocks(blocks, {streaming?})`, `append(block)`, `appendText(text)` (continues
3354
+ the last paragraph, or opens one; a blank line in the text starts a new paragraph; a marker split
3355
+ across two chunks resolves when its close arrives), `end()`, `stop()` (adds "Stopped here."),
3356
+ `setSources(sources)`, `setArtifactState(id, {expanded, controls})` (reflects whether the
3357
+ application has the artifact open somewhere), `getBlocks()`, `isStreaming()`, `toText()`,
3358
+ `toMarkdown()`, `destroy()`. A single line break in model text is kept (an address, a sign-off); a
3359
+ blank line starts a new paragraph.
3360
+ - **Events** — `cite {n, source}` from a citation button, `artifact {id}` from an artifact card,
3361
+ `end` when a streamed answer is marked finished.
3362
+ - **Rendering** — code is a figure with its language, a copy button and a focusable `<pre>`
3363
+ (`lines: true` on a code block numbers its lines and wraps long ones under their own indent, for
3364
+ code read at length in an inspector),
3365
+ coloured for js, ts, json, sql, python, shell and css (anything else stays plain); a wide table
3366
+ scrolls inside the answer and becomes a named, focusable region only while it overflows; figures
3367
+ are a `<dl>` with tabular numbers; a callout uses `.zx-callout` with its tone as `data-kind`.
3368
+ - **Static** — `renderBlocks(blocks, options)` returns a `DocumentFragment` for a transcript or a
3369
+ print view: citations are plain superscripts and artifacts plain cards. `blocksToMarkdown(blocks)`
3370
+ and `blocksToText(blocks)` export an answer for copying and search.
3371
+ - **State** — `data-state` is `streaming`, `done` or `stopped`; the root is `aria-busy` while it
3372
+ streams. Streamed text is never inside a live region.
3373
+ <!-- /doc -->
3374
+
3375
+ <!-- doc:agent-thread -->
3376
+ ### AgentThread
3377
+
3378
+ A conversation with one or more agents, drawn from the items above: the person's messages, the
3379
+ agents' answers as they stream (`BlockView` with a `SourceList`), the steps a run took
3380
+ (`RunTrace`), the approvals that hold it (`ApprovalCard`), and one-line notices.
3381
+
3382
+ - **Options** — `items: []`, `authors: {}`, `me: 'me'` (the reader's author key; an item without
3383
+ `author` is the reader's when it is a `user` item), `label` (the feed's name, "Conversation"),
3384
+ `headingLevel: 3`, `emptyState: null` (`emptyState()` options shown while empty),
3385
+ `followOutput: true`, `scroller: null` (the element that scrolls; the nearest scrolling ancestor
3386
+ when null), `answerActions: ['copy', 'regenerate', 'branch']` (add `'rate'` for helpful / not
3387
+ helpful), `userActions: []` (`'edit'`, `'copy'` on the reader's own messages, revealed while the
3388
+ message is pointed at or holds focus), `icons` (glyphs for `regenerate`, `branch`, `rateUp`,
3389
+ `rateDown`, `edit`), `traceIcons` (handed to every `RunTrace` it draws), `now: null` (the clock
3390
+ "today" is measured against, for a world on fixed dates), `formatTime`, `locale`, `msg`.
3391
+ - **Item extras** — any item's `refs: [{id, label, icon?, entity?}]` draws links to the
3392
+ application's own things after its content (`open {item, ref}`); a `user` item's `mentions`
3393
+ (names, or `{name, tone}`) marks each `@name` in its text; an `answer`'s `steps` show the work it
3394
+ did inline above its text (`stepsOpen` opens them) and, like `stopped`, `rating` and `at`, follow
3395
+ its version (`versions[]`); a `trace`'s `title` replaces its summary (a plan:
3396
+ "Plan · 5 of 6 done"); a `notice` is named by its own text and may carry `action: {id, label}`
3397
+ (`action {item, action: id}`); an author with an `icon` is drawn as a tinted tile instead of
3398
+ initials (round for a `model`; `tone: 'accent'` for the accent's quiet fill); an `approval`'s
3399
+ `editedKeys` say which values the person changed. `setArtifactState()` is remembered for answers
3400
+ drawn later; `sourceIcons` is handed to every `SourceList`.
3401
+ - **Methods** — `setItems(items)`, `upsert(item)` (adds, or replaces in place by `id`),
3402
+ `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)`
3404
+ (streams into an answer, creating it when the id is new), `appendBlock(id, block)` (adds a whole
3405
+ block — figures, a table — without redrawing the answer), `announce(text)` (says an outcome
3406
+ through the thread's polite status), `setArtifactState(id, {expanded, controls})` (whether an
3407
+ 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
3410
+ 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.
3412
+ - **Events** — `action {item, action, value?}` (`copy`, `regenerate`, `branch`, `rate` with
3413
+ `up`/`down`/null, `version` with an index — preventable for `rate` and `version`; `edit` on the
3414
+ reader's message; a notice's action id), `open {item, ref, step?}` (an item's link, or a trace
3415
+ step's),
3416
+ `approve {item, values}`, `edit {item, values}`, `reject {item, reason}` (preventable: the card
3417
+ stays pending), `cite {item, n, source}` (preventable: by default the cited source is
3418
+ highlighted), `artifact {item, id}`, `reveal {target}`. Each reaches a listener on the thread's
3419
+ root once, as the thread's `zx-*` event: the cards, answers and traces inside it do not bubble
3420
+ their own copies past it. A source that names a `call` reveals that
3421
+ step in the trace.
3422
+ - **Turns** — consecutive items by the same agent read as one turn: the avatar and byline are drawn
3423
+ once, and the byline still names every article. The reader's own messages sit at the end as a
3424
+ bubble without an avatar.
3425
+ - **Following output** — while the reader is at the end, new output keeps the end in view;
3426
+ scrolled up, a "Jump to latest" button appears and the reader is never moved. While a streaming
3427
+ answer has nothing yet, a quiet line says who is writing.
3428
+ - **Narrow** — the thread is a size container; below 30rem the content takes the full width and
3429
+ the avatar stays beside the byline.
3430
+ - **Keyboard and semantics** — the APG feed pattern: each item is an `article` in a `role="feed"`
3431
+ with `aria-posinset`, `aria-setsize` and `aria-labelledby` its byline; PageDown and PageUp move
3432
+ between articles; Ctrl+End and Ctrl+Home move focus past the end or before the start of the feed.
3433
+ The feed is `aria-busy` while an answer streams. One polite status says when an agent starts
3434
+ writing, answers, needs approval, or is stopped — streamed text is never read aloud as it arrives.
3435
+ <!-- /doc -->
3436
+
3437
+ <!-- doc:run-status -->
3438
+ ### RunStatus
3439
+
3440
+ Where an agent's run stands, for a run panel or a narrow header: the state as a glyph and a word,
3441
+ one sentence on what is happening, the steps as a progressbar, when it started and how long the
3442
+ agent has worked, the tokens, and the cost against a budget. It draws the values it is given and
3443
+ announces nothing itself; the thread the run belongs to announces its milestones.
3444
+
3445
+ - **Options** — `state` (a run state: `queued`, `running`, `waiting`, `paused`, `blocked`, `done`,
3446
+ `failed`, `stopped`, `skipped`; default `'queued'`, reflected as `data-state`), `summary` (one
3447
+ sentence, text only), `steps: {done, total}|null`, `started`, `finished` and `waitingSince`
3448
+ (local ISO date-time strings or `Date`s), `workMs` (milliseconds worked; the row shows only when
3449
+ it is a number), `tokens: [in, out]|number|null` (the pair, or the total as one number),
3450
+ `tokenBudget: number|null`, `cost: {amount, budget?, currency}|null`, `model`,
3451
+ `actions: [{label, kind?, icon?, onclick?}]`, `ticking: true`, `compact: false|true|'icon'`,
3452
+ `now: (() => Date)|null`, `locale`, and `msg` (the `agent.status.*` words and the `runStatus.*`
3453
+ labels).
3454
+ - **Rendering** — the state line; the summary; a `role="progressbar"` whose `aria-valuetext` reads
3455
+ "3 of 6 steps"; the actions as small buttons; and a `<dl>` of Started, Working time, Waiting
3456
+ since (while `waiting`) or Blocked since (while `blocked`), Finished / Failed at / Stopped at
3457
+ (once the run is over), Model, Tokens ("18,420 in · 1,236 out", or "22,840" for a total) and
3458
+ Cost. With a `budget` the cost is a `role="meter"` reading "€0.14 of €2.00" whose `data-level`
3459
+ is `warning` from 80% and `danger` at 100%. With a `tokenBudget` the tokens are a meter the same
3460
+ way, in the locale's compact figures (`Intl.NumberFormat` `notation: 'compact'`): "22.8K of 60K
3461
+ tokens"; without one they stay text. A time on another day than today shows its date too.
3462
+ - **Blocked** — `blocked` is a glyph and the word "Blocked" in the danger tone, and the steps bar
3463
+ takes the danger tone. A blocked run is not over: it shows "Blocked since" from `waitingSince`
3464
+ and never a finished time.
3465
+ - **Compact** — `compact: true` (reflected as `data-compact`) draws only the state, glyph and
3466
+ word, as a pill for a header too narrow for the panel. `compact: 'icon'`
3467
+ (`data-compact="icon"`) draws the glyph alone, for a list row: the word stays in the pill,
3468
+ visually hidden, as its accessible text, and is the pill's `title` tooltip.
3469
+ - **Ticking** — while `state` is `running` and `ticking` is on, the working time counts on once a
3470
+ second from `workMs` and the moment of the last `update()`, through one interval that sleeps
3471
+ while the page is hidden. Leaving `running` freezes the clock where it stands. `now` replaces
3472
+ the clock, both for that count and for deciding whether a time is today; a fixed `now` makes the
3473
+ panel deterministic for screenshots and tests. It is fixed at construction.
3474
+ - **Focus** — `update()` keeps focus where it was: an action row whose labels, kinds, and icons did
3475
+ not change is kept as it is, so the focused button never leaves the DOM; otherwise focus goes to
3476
+ the action at the same index, or the nearest one left. When no action is left the panel itself
3477
+ holds focus (`tabindex="-1"`, removed again once focus moves on).
3478
+ - **Methods** — `update(values)` merges new values and redraws (the clock carries on unless the
3479
+ update brings a new `workMs`; `locale`, `msg`, `now`, and `onaction` are fixed), `getState()`
3480
+ (the values as copies, `tokenBudget` included, `workMs` counted up to now), `destroy()`.
3481
+ - **Events** — `action {index, action}`, after the descriptor's own `onclick`.
3482
+ <!-- /doc -->
3483
+
3484
+ <!-- doc:composer -->
3485
+ ### Composer — the message box of an agent conversation
3486
+
3487
+ 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.
3491
+
3492
+ - **Constructor** — `new Composer(null, options)` creates its own root; `new Composer(element,
3493
+ options)` takes over an element and restores it on `destroy()`.
3494
+ - **Options** — `label` (accessible name of the text and of the `role="group"` root, English
3495
+ `Message`), `placeholder`, `value`, `submitKey: 'enter'|'mod+enter'`, `busy: false`,
3496
+ `disabled: false`, `attachments: false`, `accept: ''` (the `<input type="file">` syntax),
3497
+ `maxFiles: 10`, `mentions: null|{trigger: '@', items}` where `items` is `[{id, label,
3498
+ description?, icon?}]` or `(query) => items | Promise<items>`, `commands: null|LauncherItem[]`,
3499
+ `tools: []` (`[{id, label, icon, pressed?, expanded?, controls?, disabled?}]` — `pressed` makes a
3500
+ toggle, `expanded`/`controls` a disclosure; see Tools), `icons: {}` (`attach`, `commands` glyphs),
3501
+ `context: [{id, label,
3502
+ icon?, ref?}]`, `hint` (quiet text beside Send), `note` (a quiet line under the composer, also
3503
+ its description), `sendLabel: null` (visible text on Send, see Send), `draftKey: null`,
3504
+ `minRows: 1` (the text never shrinks below it, even empty; capped at `maxRows`), `maxRows: 10`
3505
+ (it scrolls beyond), `msg`.
3506
+ - **Methods** — `focus()`, `getValue()`, `setValue(text)`, `insertText(text)` (types at the caret
3507
+ as the person would — text ending in `@` opens the suggestions), `clear()` (text, files and draft;
3508
+ context stays), `setBusy(busy)`, `isBusy()`, `setDisabled(disabled)`, `setHint(text)`,
3509
+ `setNote(text)` (an empty text hides either), `update(partial)`, `setTools(tools)`,
3510
+ `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.
3513
+ - **update(partial)** — changes `label`, `placeholder`, `hint`, `note`, `submitKey`, `sendLabel`,
3514
+ `disabled` and `busy` in place; a key left out or `undefined` is kept, other keys are ignored.
3515
+ The text, its caret and selection, the focus, the attachments, the context chips and the draft
3516
+ all stay, so a placeholder that names the chosen model follows the model picker without
3517
+ recreating the composer: `composer.update({placeholder: 'Message Halden 3 Deep'})`.
3518
+ `label: null` returns to `composer.label`; an empty `placeholder` removes it.
3519
+ - **Events** — `send {text, files, mentions, context}` is preventable: unless prevented, the text,
3520
+ 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`,
3522
+ `input {text}`, `attach {files}` (preventable, before the files are added), `remove {kind:
3523
+ 'file'|'context', id, file?, chip?}` (after the reader removes one), `mention {item}`,
3524
+ `command {item}` (the application's own item), `tool {id, tool}` (a copy of the tool as it
3525
+ stands, `pressed` included), `historyprevious`.
3526
+ - **Keyboard** — `submitKey: 'enter'`: Enter sends, Shift+Enter breaks the line;
3527
+ `'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends, Enter breaks the line. A key during an IME
3528
+ composition never sends. Escape closes the suggestions, otherwise emits `stop` while busy (and is
3529
+ left alone when idle, so a surrounding dialog can close). ArrowUp on an empty text emits
3530
+ `historyprevious`; `/` on an empty text opens the commands. In the suggestions, Up and Down move,
3531
+ 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.
3533
+ - **Tools** — icon buttons in the bar after Attach and Commands, each named by its `label` (also
3534
+ its `title` tooltip). A boolean `pressed` makes a toggle with `aria-pressed`, drawn with the
3535
+ neutral current fill and an edge; without it the tool is a plain button. Pressing one emits
3536
+ `tool`; the composer never changes `pressed` itself — call `setToolPressed(id, !tool.pressed)`.
3537
+ `setTools(tools)` redraws them, keeping the focus on the tool with the same id (on the text when
3538
+ that tool is gone or disabled). An entry without `id`, `label` or `icon` is left out, as is a
3539
+ repeated id; other fields on a tool are handed back in `tool`. `icon` is a built-in glyph name or
3540
+ one the application registered with `registerIcons()`. Tools are disabled with the composer.
3541
+ - **Send** — one button that swaps its glyph, name and `aria-keyshortcuts` between Send and Stop.
3542
+ With `sendLabel` (`'Start task'`) it shows the glyph and that text, which is also its accessible
3543
+ name; while busy it reads `composer.stop` ("Stop"). In a composer narrower than 24rem (a phone, a
3544
+ side column) the text is visually hidden and Send is the square glyph again — the text stays its
3545
+ accessible name and its tooltip.
3546
+ - **Mentions** — the query is the text after the trigger up to the caret, with no whitespace;
3547
+ picking writes `@<label> `. An array is filtered by label prefix, word prefix, label substring,
3548
+ then id prefix or a word of the description, ignoring case and accents. A function answers the
3549
+ query itself; a stale Promise is ignored.
3550
+ - **Commands** — opened in a `Launcher` the composer creates on first use and destroys with
3551
+ itself; an item with `items` opens a page. The commands keep the order given. A Commands button
3552
+ in the bar opens the same list for pointer and touch.
3553
+ - **Files** — the Attach button, pasting files, and dropping files on the composer (the root shows
3554
+ `data-state="dropping"` and a drop label meanwhile) add attachments, filtered by `accept` and
3555
+ capped by `maxFiles`.
3556
+ - **Accessibility** — the `<textarea>` keeps its textbox role. While suggestions show it carries
3557
+ `aria-autocomplete="list"`, `aria-controls` (the listbox) and `aria-activedescendant` (the
3558
+ highlighted `role="option"`), and a polite status says how many there are. Attachments and
3559
+ context chips are labelled lists, each chip with a button named "Remove <name>". Send is never
3560
+ disabled while the composer is live (it is `aria-disabled` when there is nothing to send), so
3561
+ the focus it holds survives a run ending. A toggled tool states itself with `aria-pressed`, not
3562
+ colour alone.
3563
+ - **Draft** — with `draftKey`, the unsent text is kept through `storage('composer')`, restored
3564
+ when the composer is created without a `value`, and cleared on send and `clear()`.
3565
+ <!-- /doc -->
3566
+
3567
+ <!-- doc:approval-card -->
3568
+ ### ApprovalCard
3569
+
3570
+ A request that holds an agent's run until a person answers it: what the agent wants to do, what
3571
+ will happen, a preview of what it produces, and Approve, Edit, and Reject. Answered, it freezes
3572
+ into the record of what was decided, by whom, and when. The card never acts on its own — it emits
3573
+ the answer, and the application carries it out.
3574
+
3575
+ - **Options** — `title`, `description`, `icon: null` (an icon name for the tinted tile), `tone:
3576
+ 'blue'` (`slate|blue|teal|green|amber|orange|red|pink|violet`), `headingLevel: 3`,
3577
+ `status: 'pending'|'approved'|'rejected'|'expired'`, `details: Node|Block[]|null` (recipients,
3578
+ amounts, records), `preview: {label, content: Node|Block[]}|null` (behind a disclosure; `blocks`
3579
+ is accepted for `content`, as the thread model spells it), `fields: Record<string,
3580
+ FieldOptions>|null` (the Edit form — no fields, no Edit), `values: {}`, `confirmText: null`,
3581
+ `reason: 'optional'|'required'|'none'` (whether Reject asks why), `answeredBy: null` (the verdict's
3582
+ "you" when null), `answeredAt: null` (local ISO date-time or Date), `edited: false`,
3583
+ `editedKeys: null` and `rejectReason: null` (for a card restored from a record), `now: null`
3584
+ (a `() => Date` clock), `keys: true`, and `msg`.
3585
+ - **Edited values** — `edited: true` lists every field under "Edited by you"; `editedKeys:
3586
+ ['subject']` lists only those (in field order) and on its own marks the card edited. The card's
3587
+ own Edit flow keeps `editedKeys` as the union of every save so far, so a restored card and a
3588
+ card edited in place list the same thing.
3589
+ - **Events** — `approve {values}`, `edit {values, changed, editedKeys}`, `reject {reason}`, all
3590
+ **preventable** (on the component or on the bubbling `zx-*` event). Unless `approve` or `reject`
3591
+ is prevented the card moves to its answered state; a saved `edit` keeps it pending and adopts
3592
+ the values. `changed` names the fields this save changed. `editedKeys` is the union the card
3593
+ will list (null when it lists every field), so the application can store it with the record.
3594
+ Prevent an answer to refuse or defer it, then settle the card with `setStatus()`.
3595
+ - **Methods** — `update(partial)` changes any of `title`, `description`, `icon`, `tone`,
3596
+ `details`, `preview`, `fields`, `values`, `confirmText`, `reason`, `edited`, `editedKeys` in
3597
+ place (see below); `setStatus(status, {by?, at?, reason?})` (emits nothing; `at` defaults to
3598
+ now; closes any of the card's open dialogs), `getStatus()`, `getValues()` (a copy, edits
3599
+ included), `getEditedKeys()` (`[]` when not edited, `null` when every field is listed),
3600
+ `focus()` (the root is `tabindex="-1"`, so a thread can move focus to a request when a run
3601
+ starts waiting), `handleKey(event)` → `boolean`, and `destroy()` (also destroys the card's
3602
+ dialogs, including an open confirmation).
3603
+ - **Update in place** — `update()` is for a request the agent revises while it waits, or a record
3604
+ that changed. It redraws only what changed: values equal to what is drawn (compared by content,
3605
+ so a fresh copy of the same blocks or fields counts as equal) are left alone, and focus stays
3606
+ where it was. When the focused control goes away (Edit when `fields` go, the preview toggle when
3607
+ `preview` goes), focus moves to the card. A change closes a dialog only when the dialog no
3608
+ longer applies: new `fields` close the Edit form, a new `reason` closes the Reject dialog, a new
3609
+ `confirmText` closes the typed confirmation without approving. An open Edit form stays open over
3610
+ new `values`. Status goes through `setStatus()`. `update()` emits nothing.
3611
+ - **Approve** — with `confirmText`, Approve first opens `Dialog.confirm({confirmText, danger:
3612
+ true})` titled with the card's title; only a confirmed approval emits `approve`.
3613
+ - **Reject** — `reason: 'optional'` asks in a dialog with a textarea and accepts an empty answer;
3614
+ `'required'` keeps the Reject button disabled until the reason is non-empty; `'none'` rejects at
3615
+ once with `reason: ''`. Mod+Enter submits the Reject and Edit dialogs.
3616
+ - **Answered state** — no actions; the line under the title becomes the verdict ("Approved by you
3617
+ at 10:31"; the date is added when it is not today, by the `now` clock); the edited values and
3618
+ the reason (as a quote) stay. An answer given on the card, or a `setStatus()` without `at`,
3619
+ takes its time from `now`. `data-state` is the status, and the state pill is a `statusIcon()`
3620
+ glyph plus its word (waiting, done, skipped, stopped glyphs for pending, approved, rejected,
3621
+ expired).
3622
+ - **Keyboard** — A approves, E edits, R rejects, only while focus is inside the pending card, not
3623
+ in a text control, with no modifier held, and while none of the card's dialogs is open. The card
3624
+ binds no document key: an application that wants them from elsewhere forwards the event to
3625
+ `handleKey(event)`, which returns true and prevents the default when it used the key.
3626
+ `keys: false` stops the card listening on itself (and drops the key hints on its buttons).
3627
+ - **Accessibility** — `role="group"` labelled by the title heading and described by the
3628
+ description and the state line; a pending card says "The run is paused until you answer."
3629
+ (message `approvalCard.paused`). The preview toggle follows the APG Disclosure pattern.
3630
+ - **Consequence comes from the application** — whether an action needs `confirmText` (or
3631
+ `reason: 'required'`) is decided by the application from the tool the action triggers. It is
3632
+ never taken from model output: an agent that could set its own confirmation could also waive it.
3633
+ <!-- /doc -->
3634
+
3635
+ <!-- doc:run-trace -->
3636
+ ### RunTrace
3637
+
3638
+ What an agent did during a run: a one-line summary ("Worked for 41 s · 5 tool calls · 9 sources ·
3639
+ 1 retry") that opens into a timeline of its steps. A tool call opens to the arguments it was made
3640
+ with and what came back; a retry is drawn under the call it repeats; a hand-off shows both agents.
3641
+ The same component draws a plan: `task` steps under a `label` of the plan's own, the people's
3642
+ `ask` and `decision` steps among them, chosen one at a time with `selectable`. The trace changes
3643
+ only when the application calls `setSteps()`, `upsert()` or `setLabel()`.
3644
+
3645
+ - **Options** — `steps: []` (`TraceStep[]`, in the order they started), `open: false` (the step
3646
+ list starts open), `label: null` (text the summary reads instead of the computed line — "Close
3647
+ September · 2 of 5 done"; every state but done still follows it as a word, "· Running"),
3648
+ `authors: {}` (who the steps' `actor` and `to` keys name), `showArguments: true`,
3649
+ `maxResult: 4000` (characters of a result shown before a "Show all" button; 0 shows every
3650
+ result whole), `summary: true` (false: no summary line, the list always shows — for a run panel
3651
+ whose state is told beside it), `kindIcons: null` (whether a step leads with its kind's glyph;
3652
+ null hides them for a plan whose steps are all `task`s), `selectable: false` (every step can be chosen, see Events), `ticking: false`
3653
+ (a running step that has `at` counts its time once a second, on from its `ms` when it was
3654
+ resumed), `now: null` (`() => Date`, the
3655
+ clock `ticking` counts against, for an application whose world is fixed on another date; real
3656
+ time when null), `formatTime: null` (`(at) => string`, how a step's start time is written;
3657
+ "10:31:05" when null), `icons: {}` (glyph per step kind over the built-in `search`→search,
3658
+ `read`→file, `query`→table, `write`→type, `run`→code, `call`→gear, `handoff`→link-2,
3659
+ `think`→dots, `task`→list, `ask`→mail, `decision`→check), `msg` (`runTrace.*` and the
3660
+ `agent.status.*` words).
3661
+ - **Methods** — `setSteps(steps)` (open steps stay open, focus stays on its step),
3662
+ `upsert(step)` (replaces the step with the same `id` and redraws only that step, keeping its
3663
+ retries, its open state, and focus on its row or links; a new step is appended, under the step
3664
+ it repeats when it has `retryOf`), `setLabel(text|null)` (null or `''` goes back to the computed
3665
+ line), `expand(id?)` (opens the list, and that step), `collapse(id?)` (closes the list, or only
3666
+ that step), `reveal(id)` (opens the list and the step, scrolls to it, focuses its row and marks
3667
+ it `data-state="revealed"` for 2 s; the scroll jumps under reduced motion), `getSteps()`,
3668
+ `isOpen()`, `destroy()` (also stops the clock).
3669
+ - **Events** — `toggle {id, open}` whenever the list (`id: null`) or a step opens or closes, from a
3670
+ click or a method; `reveal {id}`; `open {step, ref}` when one of a step's links is activated
3671
+ (copies; the application opens what the `ref` names); `select {id}` in a `selectable` trace when
3672
+ the reader activates a row with nothing to open, or opens a step's disclosure (not from
3673
+ `expand()` or `reveal()`, so an application can answer `select` with them).
3674
+ - **Rendering** — while a step runs the summary reads "Working…" with the step's `doing` line, and
3675
+ the step shows "Reading the policy…"; with `ticking` and an `at`, its end shows how long it has
3676
+ run ("41 s", "1 min 42 s"). A waiting or blocked run says so and names the step ("Blocked after
3677
+ 12 s · 3 tool calls"); paused, stopped and failed runs say so first ("Failed after 12 s · 3
3678
+ tool calls"); a run no step of which has started reads "Not started · 6 steps". Counts are left
3679
+ out at zero, and `think`, `handoff`, `task`, `ask` and `decision` steps are not tool calls. Each
3680
+ step's muted meta line follows its label and wraps under it only when narrow: the `count`, a
3681
+ search's `sources`, the actor's name, the start time (`<time>`, tabular figures) and the
3682
+ `tokens` it used ("912 tokens"), each only when present. A step's `refs` (`ItemRef[]`, `{id,
3683
+ label, icon?, entity?}`) are quiet underlined link buttons under its words, with the glyph when
3684
+ `icon` is set. A step with `args`, `result`, `error` or `detail` is a disclosure holding the tool
3685
+ name (mono), the detail, the arguments (pretty-printed when they parse as JSON, verbatim
3686
+ otherwise) and the result or the error, each in a focusable `<pre>` with a copy button. A
3687
+ `handoff` step reads "Finance agent handed over to Collections agent" beside both authors'
3688
+ avatars joined by a dotted line — round for a `person`, a rounded square for an agent or a
3689
+ model — and its own label moves to the meta line.
3690
+ - **Accessibility** — the summary and every step with content follow the APG Disclosure pattern
3691
+ (`aria-expanded`, `aria-controls`); in a `selectable` trace a step without content is a plain
3692
+ `<button>`. A step's links are buttons beside its row, never inside it, so no control holds
3693
+ another; each is reached with Tab. The running step carries `aria-current="step"`. Every state
3694
+ is a glyph and a word: visible for waiting, blocked, failed, stopped, skipped and queued steps
3695
+ (blocked and failed in the danger tone), visually hidden beside a finished step's duration and a
3696
+ running step's "…ing" line. The running glyph pulses only without a reduced-motion preference.
3697
+ The clock is one interval for the whole trace, running only while a counting step is in the open
3698
+ list and the page is visible. The trace has no live region; the thread it sits in announces
3699
+ milestones.
3700
+ - **State** — the root's `data-state` is the run's state (`running`, `waiting`, `blocked`,
3701
+ `paused`, `stopped`, `failed`, `queued`, `done`), and it is hidden while it has no steps. Each
3702
+ step's `<li>` carries `data-kind` and `data-status`.
3703
+ <!-- /doc -->
3704
+
3705
+ <!-- doc:source-list -->
3706
+ ### SourceList
3707
+
3708
+ The sources an answer cites: a numbered chip (or row) for each, naming its site or title, with a
3709
+ card of its title, where it is, and the passage used on hover and focus. It never loads a favicon,
3710
+ a thumbnail, or any other remote resource.
3711
+
3712
+ - **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
3715
+ its title and site), `numbered: true`, `icons: {}` (glyph per kind over the built-in
3716
+ `web`→link-2, `file`→file, `record`→table, `call`→gear), `msg`.
3717
+ - **Methods** — `setSources(sources)` (focus stays on the same source), `highlight(n)` (a number is
3718
+ the 1-based position, a string an `id`: scrolls to it, focuses it, and marks it
3719
+ `data-state="highlighted"` for 2 s — the answer to a BlockView `cite`), `getSources()`,
3720
+ `destroy()`.
3721
+ - **Events** — `select {source, n}`, **preventable** (on the component or on the bubbling
3722
+ `zx-select`). Unprevented, a `web` source opens its `href` in a new tab with
3723
+ `noopener,noreferrer`, and only when `safeHref()` accepts it and it is an absolute `https:` URL;
3724
+ the card shows that host. Every other kind is the application's to act on, for example
3725
+ `runTrace.reveal(source.call)`.
3726
+ - **Accessibility** — each source is a native `<button>` named "Source 1: bank.example" (the
3727
+ visible number and name, plus visually hidden words); its card is a `Tooltip`, so it is the
3728
+ button's description while open. The list is an `<ol>` labelled by the visible label. It is not
3729
+ a landmark, so a thread with many answers does not repeat a "Sources" region.
3730
+ - **Privacy** — the pure `sourceHref(source)` returns the only address a source may open, or null;
3731
+ nothing is fetched to draw a source.
3732
+ <!-- /doc -->
3733
+
3104
3734
  <!-- doc:kernel -->
3105
3735
  ### Core helpers
3106
3736
 
@@ -3119,8 +3749,8 @@ bar.setBadge('mail', 8);
3119
3749
  newest-first handler registry. Existing `DOM.on/remEvt/fireEvt` methods can delegate to this
3120
3750
  triad. Zx never installs globals or alters DOM prototypes; applications decide whether to expose
3121
3751
  these functions globally or compose them into their own UI and routing layer.
3122
- - **Icons** — `icon(name, {size, label})` and `icons`; see the Icons section — bundled inline SVG
3123
- by default, Font Awesome after an opt-in.
3752
+ - **Icons** — `icon(name, {size, label})`, `icons`, and `ICON_SIZE` (one size per role); see the
3753
+ Icons section — bundled inline SVG by default, Font Awesome after an opt-in.
3124
3754
  - **Positioning** — `position(anchor, floating, {placement, offset, flip, matchWidth})` →
3125
3755
  `{update, destroy}`. It anchors a manual popover with CSS anchor positioning where the browser
3126
3756
  supports it and a scroll/resize-tracked fallback where it does not. Options are resolved once,
@@ -3193,6 +3823,26 @@ old `RangeError`, at a call site that can afford to fail: a test, or a build-tim
3193
3823
  Font Awesome elements are sized with `font-size` and occupy 1em; bundled SVGs use width/height
3194
3824
  attributes (default 16). Both honour `label` (`null` ⇒ `aria-hidden`, otherwise `role="img"` +
3195
3825
  `aria-label`).
3826
+
3827
+ **Size an icon by its role.** `ICON_SIZE` names one pixel size per role, so every chevron, every
3828
+ dismiss ×, and every check renders alike wherever it appears, and a call site says what a glyph is
3829
+ for rather than how big it is: `icon('chevron-down', { size: ICON_SIZE.chevron })`. The components
3830
+ use it throughout; use it in application code too, and never write a number for one of these roles.
3831
+
3832
+ - `ICON_SIZE.control` (16) — the default: an icon that is a control's content or leads its label.
3833
+ - `ICON_SIZE.chevron` (14) — dropdown, disclosure, and reorder chevrons; calendar and pager
3834
+ arrows; breadcrumb separators.
3835
+ - `ICON_SIZE.dismiss` (14) — the × that clears a field, closes a tab, dialog, or message, or
3836
+ removes a row.
3837
+ - `ICON_SIZE.check` (14) — the check of a selected option, a pressed toggle button, or a completed
3838
+ step.
3839
+ - `ICON_SIZE.sort` (14) — the sort-direction arrow beside a column heading.
3840
+ - `ICON_SIZE.chip` (12) — any glyph inside a chip or token, its remove × included.
3841
+ - `ICON_SIZE.marker` (8) — a glyph drawn inside a small status marker.
3842
+
3843
+ Several roles share a value and are named apart so one can change on its own. At 14px and below an
3844
+ outline is drawn with a one-pixel line, so the indicator roles also share a stroke weight. A text
3845
+ character is never a stand-in for an icon: draw "×", "✓", or an arrow with `icon()`.
3196
3846
  <!-- /doc -->
3197
3847
 
3198
3848
  <!-- doc:helpers -->
@@ -3298,7 +3948,8 @@ destroys its component.
3298
3948
 
3299
3949
  Registered elements: `<zx-toggle>`, `<zx-check-button>`, `<zx-select items='[…]' required>`,
3300
3950
  `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
3301
- `<zx-table>`, `<zx-dialog>`.
3951
+ `<zx-table>`, `<zx-dialog>`. `<zx-datebox>` takes `display-format` beside `format`, as the
3952
+ Datebox options `displayFormat` and `format`.
3302
3953
  <!-- /doc -->
3303
3954
 
3304
3955
  <!-- doc:tokens -->
@@ -3369,4 +4020,12 @@ record: native inputs, selects, and textareas inside it drop their border and fi
3369
4020
  (`--zx-color-bg-hover`) or focus (the normal border, the control fill, and the focus ring), so values
3370
4021
  read as text rather than as a wall of boxes. Read-only and disabled fields stay quiet. The rules have
3371
4022
  zero specificity, so a component's own input styling still wins.
4023
+
4024
+ **Revealed actions.** Mark a row or a section heading `data-zx-reveal-host` and a secondary action
4025
+ inside it `data-zx-reveal`: the action rests invisible and appears while the host is pointed at,
4026
+ holds focus, is current or selected, or has a menu open. It keeps its space, so nothing shifts, and
4027
+ stays in the tab order, so focusing it shows it. On touch screens, under `prefers-contrast: more`
4028
+ and in forced colours it is always visible. Use it only for repeated, secondary per-row actions
4029
+ that are reachable another way (a context menu, a keyboard shortcut); a primary action stays
4030
+ visible. Hosts do not nest.
3372
4031
  <!-- /doc -->