@zeyos/zx 5.5.0 → 5.7.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 (235) hide show
  1. package/CHANGELOG.md +210 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +711 -0
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  11. package/dist/types/components/avatar/avatar.d.ts +91 -4
  12. package/dist/types/components/block-view/block-view.d.ts +205 -0
  13. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  14. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  15. package/dist/types/components/calendar/calendar.d.ts +12 -4
  16. package/dist/types/components/chart/chart.d.ts +25 -13
  17. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  18. package/dist/types/components/composer/composer.d.ts +938 -0
  19. package/dist/types/components/composer/queue.d.ts +76 -0
  20. package/dist/types/components/copy/copy-button.d.ts +6 -4
  21. package/dist/types/components/copy/copy-input.d.ts +10 -6
  22. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  23. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  24. package/dist/types/components/dock/dock.d.ts +12 -3
  25. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  26. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  27. package/dist/types/components/file-item/file-item.d.ts +3 -2
  28. package/dist/types/components/file-list/file-list.d.ts +14 -8
  29. package/dist/types/components/filter/filter-model.d.ts +31 -1
  30. package/dist/types/components/filter/filter.d.ts +20 -2
  31. package/dist/types/components/finder/finder.d.ts +14 -6
  32. package/dist/types/components/flag/flag.d.ts +99 -0
  33. package/dist/types/components/grid/grid.d.ts +1 -1
  34. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  35. package/dist/types/components/launcher/launcher.d.ts +2 -0
  36. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  37. package/dist/types/components/number-field/number-field.d.ts +17 -6
  38. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  39. package/dist/types/components/prose/prose.d.ts +9 -6
  40. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  41. package/dist/types/components/questionnaire/items.d.ts +52 -30
  42. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  43. package/dist/types/components/rating/rating.d.ts +5 -3
  44. package/dist/types/components/run-status/run-status.d.ts +393 -0
  45. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  46. package/dist/types/components/select/country.d.ts +106 -0
  47. package/dist/types/components/select/field-adapter.d.ts +2 -1
  48. package/dist/types/components/select/locale.d.ts +102 -0
  49. package/dist/types/components/select/select.d.ts +41 -2
  50. package/dist/types/components/slider/slider.d.ts +1 -0
  51. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  52. package/dist/types/components/source-list/source-list.d.ts +179 -0
  53. package/dist/types/components/split-view/split-view.d.ts +5 -3
  54. package/dist/types/components/surface/catalog.d.ts +260 -0
  55. package/dist/types/components/surface/elicit.d.ts +81 -0
  56. package/dist/types/components/surface/mcp.d.ts +165 -0
  57. package/dist/types/components/surface/schema.d.ts +314 -0
  58. package/dist/types/components/surface/stream.d.ts +118 -0
  59. package/dist/types/components/surface/surface.d.ts +718 -0
  60. package/dist/types/components/surface/text.d.ts +277 -0
  61. package/dist/types/components/surface/validate.d.ts +339 -0
  62. package/dist/types/components/table/table.d.ts +55 -3
  63. package/dist/types/components/table/window.d.ts +203 -0
  64. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  65. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  66. package/dist/types/components/tree/tree.d.ts +20 -13
  67. package/dist/types/core/component.d.ts +10 -0
  68. package/dist/types/core/date.d.ts +8 -1
  69. package/dist/types/core/dom.d.ts +1 -0
  70. package/dist/types/core/http.d.ts +10 -0
  71. package/dist/types/core/i18n.d.ts +38 -0
  72. package/dist/types/core/messages.d.ts +479 -1
  73. package/dist/types/core/storage.d.ts +7 -2
  74. package/dist/types/elements/define.d.ts +21 -46
  75. package/dist/types/elements/definitions.d.ts +147 -0
  76. package/dist/types/elements/kit.d.ts +7 -0
  77. package/dist/types/elements/reflect.d.ts +6 -3
  78. package/dist/types/index.d.ts +18 -1
  79. package/dist/types/internal/agent-model.d.ts +587 -0
  80. package/dist/types/internal/date-locale.d.ts +7 -0
  81. package/dist/types/internal/highlight.d.ts +24 -0
  82. package/dist/types/internal/json-patch.d.ts +146 -0
  83. package/dist/types/internal/presence-loop.d.ts +148 -0
  84. package/dist/types/locales/de.d.ts +13 -0
  85. package/dist/types/locales/en.d.ts +2 -0
  86. package/dist/types/locales/index.d.ts +823 -0
  87. package/dist/types/zeyos/view.d.ts +8 -1
  88. package/dist/zx-zeyos.esm.js +20505 -18748
  89. package/dist/zx-zeyos.esm.min.js +5 -5
  90. package/dist/zx.core.css +1276 -0
  91. package/dist/zx.core.min.css +1 -0
  92. package/dist/zx.css +2424 -134
  93. package/dist/zx.esm.js +46167 -28468
  94. package/dist/zx.esm.min.js +40 -8
  95. package/dist/zx.global.js +46167 -28468
  96. package/dist/zx.global.min.js +40 -8
  97. package/dist/zx.layered.css +17302 -0
  98. package/dist/zx.layered.min.css +1 -0
  99. package/dist/zx.min.css +1 -1
  100. package/docs/agent-catalog.json +12501 -0
  101. package/docs/agent-surfaces.md +340 -0
  102. package/docs/api.json +2057 -166
  103. package/docs/llms.md +1458 -58
  104. package/docs/llms.txt +38 -8
  105. package/package.json +29 -6
  106. package/src/components/account-menu/account-menu.js +6 -3
  107. package/src/components/activity-item/activity-item.js +2 -1
  108. package/src/components/activity-list/activity-list.js +16 -10
  109. package/src/components/agent-thread/ag-ui.js +1439 -0
  110. package/src/components/agent-thread/agent-thread.css +417 -0
  111. package/src/components/agent-thread/agent-thread.js +1670 -0
  112. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  113. package/src/components/app-sidebar/app-sidebar.js +18 -8
  114. package/src/components/approval-card/approval-card.css +289 -0
  115. package/src/components/approval-card/approval-card.js +1378 -0
  116. package/src/components/avatar/avatar.css +56 -1
  117. package/src/components/avatar/avatar.js +148 -26
  118. package/src/components/block-view/block-view.css +300 -0
  119. package/src/components/block-view/block-view.js +524 -0
  120. package/src/components/breadcrumb/breadcrumb.js +8 -5
  121. package/src/components/calendar/calendar-model.js +8 -2
  122. package/src/components/calendar/calendar.js +53 -18
  123. package/src/components/chart/chart.js +54 -23
  124. package/src/components/code-editor/code-editor.js +45 -8
  125. package/src/components/code-editor/field-adapter.js +1 -1
  126. package/src/components/composer/composer.css +482 -0
  127. package/src/components/composer/composer.js +1815 -0
  128. package/src/components/composer/queue.js +78 -0
  129. package/src/components/context-menu/context-menu.js +12 -1
  130. package/src/components/copy/copy-button.js +9 -7
  131. package/src/components/copy/copy-input.js +10 -6
  132. package/src/components/date-picker/date-picker.js +2 -1
  133. package/src/components/date-picker/date-range-picker.js +8 -7
  134. package/src/components/datebox/date-range-box.js +3 -9
  135. package/src/components/datebox/datebox.js +18 -21
  136. package/src/components/datebox/placeholder.js +18 -0
  137. package/src/components/dialog/dialog.js +1 -1
  138. package/src/components/dock/dock.js +34 -13
  139. package/src/components/entity-ref/entity-ref.js +16 -5
  140. package/src/components/field-upload/field-upload.js +81 -38
  141. package/src/components/file-item/file-item.js +70 -40
  142. package/src/components/file-list/file-list.js +15 -9
  143. package/src/components/filter/filter-model.js +46 -8
  144. package/src/components/filter/filter.css +3 -3
  145. package/src/components/filter/filter.js +29 -10
  146. package/src/components/filter-panel/filter-panel.js +13 -5
  147. package/src/components/finder/finder.js +50 -26
  148. package/src/components/flag/flag.css +40 -0
  149. package/src/components/flag/flag.js +177 -0
  150. package/src/components/form/form.js +1 -1
  151. package/src/components/grid/grid.js +22 -8
  152. package/src/components/kanban-view/kanban-view.js +51 -81
  153. package/src/components/launcher/launcher.js +17 -2
  154. package/src/components/list-toolbar/list-toolbar.js +2 -1
  155. package/src/components/master-panel/master-panel.js +1 -1
  156. package/src/components/menu-button/menu-button.js +4 -0
  157. package/src/components/message/message.js +3 -0
  158. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  159. package/src/components/navigation-bar/navigation-bar.js +3 -3
  160. package/src/components/number-field/number-field.js +29 -13
  161. package/src/components/prompt-starters/prompt-starters.css +91 -0
  162. package/src/components/prompt-starters/prompt-starters.js +206 -0
  163. package/src/components/prose/prose.js +14 -10
  164. package/src/components/questionnaire/conditions.js +666 -0
  165. package/src/components/questionnaire/items.js +150 -41
  166. package/src/components/questionnaire/questionnaire.js +126 -32
  167. package/src/components/rating/rating.js +5 -4
  168. package/src/components/run-status/run-status.css +208 -0
  169. package/src/components/run-status/run-status.js +782 -0
  170. package/src/components/run-trace/run-trace.css +443 -0
  171. package/src/components/run-trace/run-trace.js +1209 -0
  172. package/src/components/select/country.js +136 -0
  173. package/src/components/select/field-adapter.js +7 -2
  174. package/src/components/select/locale.js +219 -0
  175. package/src/components/select/select.css +20 -22
  176. package/src/components/select/select.js +94 -12
  177. package/src/components/sheet/sheet-stack.js +10 -1
  178. package/src/components/slider/slider.js +7 -2
  179. package/src/components/sort-control/sort-control.js +15 -5
  180. package/src/components/source-list/source-list.css +208 -0
  181. package/src/components/source-list/source-list.js +358 -0
  182. package/src/components/split-view/split-view.js +5 -3
  183. package/src/components/surface/catalog.js +1334 -0
  184. package/src/components/surface/elicit.js +107 -0
  185. package/src/components/surface/mcp.js +243 -0
  186. package/src/components/surface/schema.js +644 -0
  187. package/src/components/surface/stream.js +245 -0
  188. package/src/components/surface/surface.css +308 -0
  189. package/src/components/surface/surface.js +2291 -0
  190. package/src/components/surface/text.js +513 -0
  191. package/src/components/surface/validate.js +2218 -0
  192. package/src/components/tabbox/tabbox.js +9 -0
  193. package/src/components/table/table.css +63 -3
  194. package/src/components/table/table.js +167 -28
  195. package/src/components/table/window.js +317 -0
  196. package/src/components/toolbar/toolbar.js +12 -7
  197. package/src/components/tooltip/tooltip.css +2 -3
  198. package/src/components/tooltip/tooltip.js +32 -5
  199. package/src/components/tree/tree.js +53 -23
  200. package/src/core/component.js +25 -1
  201. package/src/core/date.js +62 -16
  202. package/src/core/dom.js +22 -2
  203. package/src/core/format.js +15 -13
  204. package/src/core/http.js +29 -20
  205. package/src/core/i18n.js +83 -10
  206. package/src/core/keyboard.js +79 -8
  207. package/src/core/messages.js +519 -2
  208. package/src/core/overlay-host.js +1 -0
  209. package/src/core/storage.js +59 -6
  210. package/src/elements/define.js +178 -130
  211. package/src/elements/definitions.js +229 -0
  212. package/src/elements/kit.js +444 -0
  213. package/src/elements/reflect.js +8 -3
  214. package/src/index.js +18 -1
  215. package/src/internal/agent-model.js +488 -0
  216. package/src/internal/date-locale.js +11 -0
  217. package/src/internal/highlight.js +104 -0
  218. package/src/internal/json-patch.js +405 -0
  219. package/src/internal/presence-loop.js +343 -0
  220. package/src/locales/de.js +911 -0
  221. package/src/locales/en.js +2 -0
  222. package/src/locales/index.js +7 -0
  223. package/src/zeyos/calendar.js +2 -1
  224. package/src/zeyos/form.js +2 -1
  225. package/src/zeyos/launcher.js +7 -6
  226. package/src/zeyos/module-bar.js +2 -1
  227. package/src/zeyos/schema.js +37 -23
  228. package/src/zeyos/select.js +4 -3
  229. package/src/zeyos/table.js +2 -13
  230. package/src/zeyos/view.js +57 -17
  231. package/styles/core.css +11 -0
  232. package/styles/tokens/semantic.css +1 -0
  233. package/styles/zeyos.css +2 -0
  234. package/styles/zx.css +11 -8
  235. package/styles/zx.layered.css +1 -0
package/docs/api.json CHANGED
@@ -23,7 +23,7 @@
23
23
  "name": "label",
24
24
  "type": "string|null",
25
25
  "default": "null",
26
- "description": "Trigger label; defaults to `Account menu for <name>`."
26
+ "description": "Trigger label; null reads the `accountMenu.labelFor` message (\"Account menu for <name>\"), or `accountMenu.label` without a name."
27
27
  },
28
28
  {
29
29
  "name": "placement",
@@ -249,9 +249,9 @@
249
249
  },
250
250
  {
251
251
  "name": "label",
252
- "type": "string",
253
- "default": "'Activity'",
254
- "description": "Accessible collection name."
252
+ "type": "string|null",
253
+ "default": "null",
254
+ "description": "Accessible collection name; null reads the `activityList.label` message (\"Activity\")."
255
255
  },
256
256
  {
257
257
  "name": "variant",
@@ -273,15 +273,15 @@
273
273
  },
274
274
  {
275
275
  "name": "loadingText",
276
- "type": "string",
277
- "default": "'Loading activity'",
278
- "description": "Loading status text."
276
+ "type": "string|null",
277
+ "default": null,
278
+ "description": "Loading status text, by default the `activityList.loading` message (\"Loading activity\"). Null shows none."
279
279
  },
280
280
  {
281
281
  "name": "emptyText",
282
282
  "type": "ActivityListContent",
283
- "default": "'No activity yet'",
284
- "description": "Empty-state content."
283
+ "default": null,
284
+ "description": "Empty-state content, by default the `activityList.empty` message (\"No activity yet\"). Null shows none."
285
285
  },
286
286
  {
287
287
  "name": "groupHeadingLevel",
@@ -360,6 +360,344 @@
360
360
  }
361
361
  ]
362
362
  },
363
+ "AgUi": {
364
+ "options": [
365
+ {
366
+ "name": "runStatus",
367
+ "type": "{update: (values: Record<string, unknown>) => unknown}|null",
368
+ "default": "null",
369
+ "description": "A RunStatus the run's lifecycle drives: `running` when it starts, `done`, `waiting` (an interrupt, or calls of the run still without a result), `stopped` (cancelled) or `failed`."
370
+ },
371
+ {
372
+ "name": "authors",
373
+ "type": "Record<string, Author>",
374
+ "default": "{}",
375
+ "description": "The thread's authors. A text message whose `name` is one of their keys is written by that author; every other item by `agent`."
376
+ },
377
+ {
378
+ "name": "agent",
379
+ "type": "string|null",
380
+ "default": "null",
381
+ "description": "The author key of the agent's output; the thread's first agent when null."
382
+ },
383
+ {
384
+ "name": "requiresApproval",
385
+ "type": "((call: ToolCall) => unknown)|null",
386
+ "default": "null",
387
+ "description": "Asked once a call's arguments are complete: any truthy answer holds the call at an ApprovalCard until the person decides. Nothing is approved by default: a check that throws holds the call too, and so does a Promise, whatever it resolves to, so an asynchronous check never lets a call through. Not asked for surface tools, whose surface is the person's say."
388
+ },
389
+ {
390
+ "name": "showReasoning",
391
+ "type": "boolean",
392
+ "default": "false",
393
+ "description": "Show the reasoning text in its trace step. Without it, reasoning is one collapsed \"Thought for 12 s\" step."
394
+ },
395
+ {
396
+ "name": "surfaceEvent",
397
+ "type": "string",
398
+ "default": "'zx.surface'",
399
+ "description": "The name of the custom event that carries surface operations: its `value` is one operation, or `{ops: [...], token?}`. The token of the event that opens a surface is kept; later ones are ignored. Give these surfaces ids a model cannot predict: a surface belongs to the source that opened it, and a `begin` for an id the model already took is refused."
400
+ },
401
+ {
402
+ "name": "tools",
403
+ "type": "Record<string, ToolTileRenderer>",
404
+ "default": "{}",
405
+ "description": "The tools whose calls the application draws itself, by name. The renderer is called at each status change of the call, never while its arguments stream; its first item that is not `null` is inserted after the call's step, later ones replace it where it stands, and the step links to it."
406
+ },
407
+ {
408
+ "name": "surfaceTools",
409
+ "type": "string[]",
410
+ "default": "['show_surface','ask_user']",
411
+ "description": "The tools whose arguments are a whole surface document. The surface is drawn once the arguments are complete, and its reply is the call's result."
412
+ },
413
+ {
414
+ "name": "inlineSurfaces",
415
+ "type": "boolean",
416
+ "default": "false",
417
+ "description": "Split surface fences out of answer text."
418
+ },
419
+ {
420
+ "name": "catalog",
421
+ "type": "SurfaceCatalog",
422
+ "default": null,
423
+ "description": "A narrowed catalog, given to every surface the adapter creates."
424
+ }
425
+ ],
426
+ "events": [
427
+ {
428
+ "name": "toolresult",
429
+ "payload": null,
430
+ "description": "What the person decided, for the application to send back to the agent. An approval answers `{approved: true}` or `{approved: false, reason?}`; a surface tool its reply, with `errors` when the surface had any; a `show` surface with no actions answers at once with `{shown: true, surface, errors?}` and stays on screen; a surface tool whose arguments are not a surface answers at once with `{error: 'invalid-arguments'}`, and one the thread cannot draw with `{error: 'surface-unavailable'}`. It fires once for a call. In AG-UI 1.0 the application turns it into a `resume` entry (`{interruptId, status: 'resolved', payload}`) when the run ended with an interrupt for the call, or into a tool message (`{role: 'tool', toolCallId, content}`) when it ended with the call among its `pendingToolCallIds`; either goes in the next run's input."
431
+ },
432
+ {
433
+ "name": "state",
434
+ "payload": null,
435
+ "description": "The application state after each snapshot or delta."
436
+ },
437
+ {
438
+ "name": "unknown",
439
+ "payload": null,
440
+ "description": "Every event the adapter does not draw: unknown types, and known ones without a place in the thread (steps, message snapshots, activities, raw and encrypted values, subagents, custom events of another name)."
441
+ },
442
+ {
443
+ "name": "error",
444
+ "payload": null,
445
+ "description": "Problems found in the stream."
446
+ }
447
+ ],
448
+ "methods": []
449
+ },
450
+ "AgentThread": {
451
+ "options": [
452
+ {
453
+ "name": "items",
454
+ "type": "ThreadItem[]",
455
+ "default": "[]",
456
+ "description": "The conversation, oldest first."
457
+ },
458
+ {
459
+ "name": "authors",
460
+ "type": "Record<string, Author>",
461
+ "default": "{}",
462
+ "description": "Who wrote the items and took the steps, by key. An item without an `author` is the person's own (`user`) or the first agent's (anything else)."
463
+ },
464
+ {
465
+ "name": "me",
466
+ "type": "string",
467
+ "default": "'me'",
468
+ "description": "Author key of the person reading; their items read as \"You\"."
469
+ },
470
+ {
471
+ "name": "label",
472
+ "type": "string|null",
473
+ "default": "null",
474
+ "description": "Accessible name of the feed; \"Conversation\" when null."
475
+ },
476
+ {
477
+ "name": "headingLevel",
478
+ "type": "2|3|4|5",
479
+ "default": "3",
480
+ "description": "Heading level inside answers and cards."
481
+ },
482
+ {
483
+ "name": "emptyState",
484
+ "type": "EmptyStateOptions|null",
485
+ "default": "null",
486
+ "description": "Shown while there are no items."
487
+ },
488
+ {
489
+ "name": "followOutput",
490
+ "type": "boolean",
491
+ "default": "true",
492
+ "description": "Keep the end in view while new output arrives, as long as the reader is at the end; otherwise offer \"Jump to latest\" and leave them where they are."
493
+ },
494
+ {
495
+ "name": "scroller",
496
+ "type": "Element|null",
497
+ "default": "null",
498
+ "description": "The element that scrolls; the nearest scrolling ancestor (or the thread itself) when null."
499
+ },
500
+ {
501
+ "name": "answerActions",
502
+ "type": "AnswerAction[]",
503
+ "default": "['copy','regenerate','branch']",
504
+ "description": "Actions under each finished answer; `regenerate` only under the latest one."
505
+ },
506
+ {
507
+ "name": "icons",
508
+ "type": "Partial<Record<'regenerate'|'branch'|'rateUp'|'rateDown'|'edit', string>>",
509
+ "default": null,
510
+ "description": "Glyph names for the answer and message actions."
511
+ },
512
+ {
513
+ "name": "userActions",
514
+ "type": "Array<'edit'|'copy'>",
515
+ "default": "[]",
516
+ "description": "Actions on the person's own messages, shown while the message is pointed at or holds focus (always on a touch screen): `edit` asks the application to put the message back in the composer, `copy` copies its text."
517
+ },
518
+ {
519
+ "name": "traceIcons",
520
+ "type": "Record<string, string>",
521
+ "default": "{}",
522
+ "description": "Glyph names for trace step kinds, handed to every `RunTrace` the thread draws."
523
+ },
524
+ {
525
+ "name": "sourceIcons",
526
+ "type": "Record<string, string>",
527
+ "default": "{}",
528
+ "description": "Glyph names for source kinds, handed to every `SourceList` the thread draws."
529
+ },
530
+ {
531
+ "name": "now",
532
+ "type": "(() => Date)|null",
533
+ "default": "null",
534
+ "description": "The clock \"today\" is measured against in cards and traces, for an application whose world runs on fixed dates; the real clock when null."
535
+ },
536
+ {
537
+ "name": "formatTime",
538
+ "type": "((at: string) => string)|null",
539
+ "default": "null",
540
+ "description": "Formats an item's `at`; the local clock time when null."
541
+ },
542
+ {
543
+ "name": "locale",
544
+ "type": "string",
545
+ "default": null,
546
+ "description": "Locale for times."
547
+ },
548
+ {
549
+ "name": "surfaceOptions",
550
+ "type": "Omit<SurfaceOptions, 'document'|'token'|'catalog'|'reply'>",
551
+ "default": "{}",
552
+ "description": "Options handed to every Surface the thread draws: the application's `policy`, `resolve`, `chartAdapter` and `msg`. Its authors, heading level and locale are the thread's unless given here."
553
+ },
554
+ {
555
+ "name": "msg",
556
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
557
+ "default": null,
558
+ "description": "Localized messages."
559
+ }
560
+ ],
561
+ "events": [
562
+ {
563
+ "name": "action",
564
+ "payload": "{item: ThreadItem, action: string, value?: unknown}",
565
+ "description": "Answer action listener."
566
+ },
567
+ {
568
+ "name": "reply",
569
+ "payload": "{item: ThreadItem, reply: SurfaceReply}",
570
+ "description": "Surface reply listener."
571
+ },
572
+ {
573
+ "name": "approve",
574
+ "payload": "{item: ThreadItem, values: Record<string, unknown>}",
575
+ "description": "Approval listener."
576
+ },
577
+ {
578
+ "name": "edit",
579
+ "payload": "{item: ThreadItem, values: Record<string, unknown>}",
580
+ "description": "Edit listener."
581
+ },
582
+ {
583
+ "name": "reject",
584
+ "payload": "{item: ThreadItem, reason: string}",
585
+ "description": "Rejection listener."
586
+ },
587
+ {
588
+ "name": "cite",
589
+ "payload": "{item: ThreadItem, n: number, source: Source|null}",
590
+ "description": "Citation listener."
591
+ },
592
+ {
593
+ "name": "artifact",
594
+ "payload": "{item: ThreadItem, id: string}",
595
+ "description": "Artifact listener."
596
+ },
597
+ {
598
+ "name": "reveal",
599
+ "payload": "{target: string}",
600
+ "description": "Reveal listener."
601
+ },
602
+ {
603
+ "name": "open",
604
+ "payload": "{item: ThreadItem, ref: import('../../internal/agent-model.js').ItemRef}",
605
+ "description": "Link listener."
606
+ }
607
+ ],
608
+ "methods": [
609
+ {
610
+ "name": "register",
611
+ "signature": "register(type, render)",
612
+ "returns": "typeof AgentThread",
613
+ "description": "Registers how items of another type are drawn. An application's own renderer for `surface` replaces the library's drawing of that type; the types the library always draws cannot be replaced."
614
+ },
615
+ {
616
+ "name": "has",
617
+ "signature": "has(type)",
618
+ "returns": "boolean",
619
+ "description": "Reports whether a type has a registered renderer. `surface` answers false until an application registers its own, so a guarded `register()` still takes effect."
620
+ },
621
+ {
622
+ "name": "setItems",
623
+ "signature": "setItems(items)",
624
+ "returns": "this",
625
+ "description": "Replaces the conversation. Everything is dropped and then drawn anew, except a surface already drawn, which stays so that one still matching keeps answering."
626
+ },
627
+ {
628
+ "name": "upsert",
629
+ "signature": "upsert(item, [options])",
630
+ "returns": "this",
631
+ "description": "Adds an item, or replaces the item with the same id where it stands. A new item goes at the end, or right after the item `options.after` names."
632
+ },
633
+ {
634
+ "name": "patch",
635
+ "signature": "patch(id, partial)",
636
+ "returns": "this",
637
+ "description": "Changes part of an item. The common changes are made in place — an answer finishing, stopping or writing on, a trace's steps, an approval's status — so what the reader opened, and focus and selection where the blocks stay, survive; anything else redraws the item. Metadata patches retain an answer's live blocks; explicit `blocks` or `versions` remain authoritative."
638
+ },
639
+ {
640
+ "name": "appendText",
641
+ "signature": "appendText(id, text)",
642
+ "returns": "this",
643
+ "description": "Streams text into an answer, creating it when the id is new. Only the answer's last paragraph is redrawn."
644
+ },
645
+ {
646
+ "name": "appendBlock",
647
+ "signature": "appendBlock(id, block)",
648
+ "returns": "this",
649
+ "description": "Adds a whole block to an answer — a figures block, a table, code — after what it already shows, without redrawing the rest of the answer. Creates the answer when the id is new."
650
+ },
651
+ {
652
+ "name": "announce",
653
+ "signature": "announce(text)",
654
+ "returns": "this",
655
+ "description": "Says something through the thread's polite status — an outcome the thread cannot see itself, such as \"Reminders sent\". Said once; the same words said twice are heard twice."
656
+ },
657
+ {
658
+ "name": "remove",
659
+ "signature": "remove(id)",
660
+ "returns": "this",
661
+ "description": "Removes an item. Focus inside it moves to the item above, or the one below when it was the first, so that a keyboard user is not thrown back to the top of the page."
662
+ },
663
+ {
664
+ "name": "get",
665
+ "signature": "get(id)",
666
+ "returns": "ThreadItem|null",
667
+ "description": "An item as it stands, an answer's streamed text included."
668
+ },
669
+ {
670
+ "name": "getComponent",
671
+ "signature": "getComponent(id)",
672
+ "returns": "Component|null",
673
+ "description": "The main component drawn for an item: an answer's BlockView, a trace's RunTrace, an approval's ApprovalCard."
674
+ },
675
+ {
676
+ "name": "surface",
677
+ "signature": "surface(id)",
678
+ "returns": "Surface|null",
679
+ "description": "The Surface drawn for a `surface` item, to stream its operations into with `apply()` or `write()`."
680
+ },
681
+ {
682
+ "name": "reveal",
683
+ "signature": "reveal(target)",
684
+ "returns": "boolean",
685
+ "description": "Brings something into view and moves focus to it: `item:<id>` an item, `step:<id>` a trace step (in whichever trace holds it), `source:<n>` a source of the latest answer that has one, `source:<n>:<id>` a source in the list of the answer `id`."
686
+ },
687
+ {
688
+ "name": "setArtifactState",
689
+ "signature": "setArtifactState(id, state)",
690
+ "returns": "this",
691
+ "description": "Reflects whether an artifact is open somewhere — an inspector, a drawer — on every card that names it, in every answer. See `BlockView#setArtifactState()`."
692
+ },
693
+ {
694
+ "name": "scrollToEnd",
695
+ "signature": "scrollToEnd()",
696
+ "returns": "this",
697
+ "description": "Scrolls to the end of the conversation."
698
+ }
699
+ ]
700
+ },
363
701
  "Alert": {
364
702
  "options": [
365
703
  {
@@ -551,15 +889,15 @@
551
889
  },
552
890
  {
553
891
  "name": "label",
554
- "type": "string",
555
- "default": "'Applications'",
556
- "description": "Navigation accessible label."
892
+ "type": "string|null",
893
+ "default": null,
894
+ "description": "Navigation accessible label, by default the `appSidebar.label` message (\"Applications\"). Null leaves the navigation unnamed."
557
895
  },
558
896
  {
559
897
  "name": "moreLabel",
560
- "type": "string",
561
- "default": "'More actions'",
562
- "description": "Name of a destination's overflow menu when its `actions` fold; every action name is followed by the destination's label."
898
+ "type": "string|null",
899
+ "default": "null",
900
+ "description": "Name of a destination's overflow menu when its `actions` fold; every action name is followed by the destination's label. Null reads the `appSidebar.more` message (\"More actions\")."
563
901
  },
564
902
  {
565
903
  "name": "header",
@@ -819,6 +1157,173 @@
819
1157
  "events": [],
820
1158
  "methods": []
821
1159
  },
1160
+ "ApprovalCard": {
1161
+ "options": [
1162
+ {
1163
+ "name": "title",
1164
+ "type": "string",
1165
+ "default": "''",
1166
+ "description": "What the agent wants to do, as a question: \"Send 3 payment reminders?\"."
1167
+ },
1168
+ {
1169
+ "name": "description",
1170
+ "type": "string",
1171
+ "default": "''",
1172
+ "description": "One line under the title: what follows from approving."
1173
+ },
1174
+ {
1175
+ "name": "icon",
1176
+ "type": "string|null",
1177
+ "default": "null",
1178
+ "description": "Icon name for the tile beside the title; none when null."
1179
+ },
1180
+ {
1181
+ "name": "tone",
1182
+ "type": "ApprovalTone",
1183
+ "default": "'blue'",
1184
+ "description": "Categorical tone of the icon tile."
1185
+ },
1186
+ {
1187
+ "name": "headingLevel",
1188
+ "type": "2|3|4|5|6",
1189
+ "default": "3",
1190
+ "description": "Element level of the title heading."
1191
+ },
1192
+ {
1193
+ "name": "status",
1194
+ "type": "ApprovalStatus",
1195
+ "default": "'pending'",
1196
+ "description": "Where the request stands."
1197
+ },
1198
+ {
1199
+ "name": "details",
1200
+ "type": "Node|Block[]|null",
1201
+ "default": "null",
1202
+ "description": "What will happen — recipients, amounts, records — as a node the application built, or as blocks. Model text in blocks is drawn as text only."
1203
+ },
1204
+ {
1205
+ "name": "preview",
1206
+ "type": "ApprovalPreview|null",
1207
+ "default": "null",
1208
+ "description": "What the request produces, behind a disclosure."
1209
+ },
1210
+ {
1211
+ "name": "fields",
1212
+ "type": "Record<string, FieldOptions>|null",
1213
+ "default": "null",
1214
+ "description": "The Edit form, keyed by value name. No fields, no Edit."
1215
+ },
1216
+ {
1217
+ "name": "values",
1218
+ "type": "Record<string, unknown>",
1219
+ "default": "{}",
1220
+ "description": "The values the request carries; the Edit form starts from them and `approve` reports them."
1221
+ },
1222
+ {
1223
+ "name": "confirmText",
1224
+ "type": "string|null",
1225
+ "default": "null",
1226
+ "description": "Text the person must type before Approve goes through, for an action that cannot be undone. Decided by the application from the tool the action triggers, never taken from model output."
1227
+ },
1228
+ {
1229
+ "name": "reason",
1230
+ "type": "ApprovalReasonMode",
1231
+ "default": "'optional'",
1232
+ "description": "Whether Reject asks why."
1233
+ },
1234
+ {
1235
+ "name": "edited",
1236
+ "type": "boolean",
1237
+ "default": "false",
1238
+ "description": "Whether the values were already edited, for a request restored from a record. Without `editedKeys` every field is listed under \"Edited by you\"."
1239
+ },
1240
+ {
1241
+ "name": "editedKeys",
1242
+ "type": "string[]|null",
1243
+ "default": "null",
1244
+ "description": "Which values were edited: only these fields are listed under \"Edited by you\", in field order. A non-empty list implies `edited`; null lists every field of an edited request."
1245
+ },
1246
+ {
1247
+ "name": "rejectReason",
1248
+ "type": "string|null",
1249
+ "default": "null",
1250
+ "description": "The reason a rejected request was given, for a request restored from a record."
1251
+ },
1252
+ {
1253
+ "name": "answeredBy",
1254
+ "type": "string|null",
1255
+ "default": "null",
1256
+ "description": "Who answers, as the verdict names them; the message `approvalCard.you` (\"you\") when null."
1257
+ },
1258
+ {
1259
+ "name": "answeredAt",
1260
+ "type": "string|Date|null",
1261
+ "default": "null",
1262
+ "description": "When an answered request was answered: a local ISO date-time or a Date. An answer given on the card takes the time it was given."
1263
+ },
1264
+ {
1265
+ "name": "now",
1266
+ "type": "(() => Date)|null",
1267
+ "default": "null",
1268
+ "description": "The clock: decides whether `answeredAt` is today (the time alone) or another day (date and time), and gives the time of an answer recorded without an explicit `at`. Real time when null."
1269
+ },
1270
+ {
1271
+ "name": "keys",
1272
+ "type": "boolean",
1273
+ "default": "true",
1274
+ "description": "Whether A, E, and R act while focus is inside the pending card. `handleKey()` works either way."
1275
+ },
1276
+ {
1277
+ "name": "msg",
1278
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1279
+ "default": null,
1280
+ "description": "Localized messages."
1281
+ }
1282
+ ],
1283
+ "events": [
1284
+ {
1285
+ "name": "approve",
1286
+ "payload": "{values: Record<string, unknown>}",
1287
+ "description": "Approve listener."
1288
+ },
1289
+ {
1290
+ "name": "edit",
1291
+ "payload": "{values, changed, editedKeys}",
1292
+ "description": "Edit listener."
1293
+ },
1294
+ {
1295
+ "name": "reject",
1296
+ "payload": "{reason: string}",
1297
+ "description": "Reject listener."
1298
+ }
1299
+ ],
1300
+ "methods": [
1301
+ {
1302
+ "name": "update",
1303
+ "signature": "update([partial])",
1304
+ "returns": "this",
1305
+ "description": "Changes the request in place — the agent revised it, or the record it is drawn from changed — and redraws only what changed. Focus stays where it was; when the element that held it is gone (the Edit button, the preview toggle), the card takes it. Of the card's dialogs only one the change makes meaningless closes: the Edit form when `fields` change, the Reject dialog when `reason` changes, the typed confirmation when `confirmText` changes. An open Edit form stays open over new `values` and saves what the person typed. Emits nothing. `edited` and `editedKeys` follow the options' rules: `edited: true` alone keeps the fields already listed (every field, on a card that was not edited); `edited: false` alone clears the list; a non-empty `editedKeys` marks the card edited."
1306
+ },
1307
+ {
1308
+ "name": "setStatus",
1309
+ "signature": "setStatus(status, [answer])",
1310
+ "returns": "this",
1311
+ "description": "Settles the request from outside: an answer the application received elsewhere, a request that timed out, or a prevented answer the application has now carried out. Emits nothing."
1312
+ },
1313
+ {
1314
+ "name": "focus",
1315
+ "signature": "focus([options])",
1316
+ "returns": "this",
1317
+ "description": "Moves focus to the card, so a thread can bring the reader to a request when a run starts waiting on it."
1318
+ },
1319
+ {
1320
+ "name": "handleKey",
1321
+ "signature": "handleKey(event)",
1322
+ "returns": "boolean",
1323
+ "description": "Answers a key: A approves, E edits, R rejects. Acts only while the request is pending, never from a text control or with a modifier held, and never while one of the card's dialogs is open. The card calls it for keys inside itself; an application may forward keys from elsewhere."
1324
+ }
1325
+ ]
1326
+ },
822
1327
  "Aspect": {
823
1328
  "options": [
824
1329
  {
@@ -940,13 +1445,43 @@
940
1445
  "name": "status",
941
1446
  "type": "'online'|'away'|'busy'|'offline'|null",
942
1447
  "default": "null",
943
- "description": "Optional presence state."
1448
+ "description": "Optional presence state of a person. An agent's `activity` takes its place: when both are given, only the activity is drawn and named."
944
1449
  },
945
1450
  {
946
1451
  "name": "statusLabel",
947
1452
  "type": "string|null",
948
1453
  "default": "null",
949
1454
  "description": "Text alternative for the presence state."
1455
+ },
1456
+ {
1457
+ "name": "activity",
1458
+ "type": "AgentActivity|null",
1459
+ "default": "null",
1460
+ "description": "What an agent is doing: `'idle'`, `'thinking'`, `'working'`, `'needs-you'`, `'blocked'` or `'offline'`. Drawn as a dot whose shape and tone differ per activity (a square for blocked, a hollow ring for idle, a dashed ring for offline); its word joins the accessible name and the dot's tooltip. Wins over `status`."
1461
+ },
1462
+ {
1463
+ "name": "activityLabel",
1464
+ "type": "string|null",
1465
+ "default": "null",
1466
+ "description": "The activity's word, when the default (\"Working\", \"Needs you\", …) is not the one to show."
1467
+ },
1468
+ {
1469
+ "name": "animate",
1470
+ "type": "boolean",
1471
+ "default": "false",
1472
+ "description": "Moves the avatar with its activity — idle breathes, thinking sways, working bobs, needs-you leans and blinks — in the one animation loop every animated avatar on the page shares. Motion is never the only signal, stops off screen and while the page is hidden, and returns the avatar to rest under reduced motion (the system's, or a `data-zx-motion=\"reduced\"` region). While it is on, the root's `transform` belongs to the loop."
1473
+ },
1474
+ {
1475
+ "name": "phase",
1476
+ "type": "number|null",
1477
+ "default": "null",
1478
+ "description": "Where in its activity's cycle the avatar moves, as a fraction from 0 up to 1 (whole turns wrap): two avatars of the same agent on one screen — a roster and an inspector — at different phases never move in step, and 0.5 puts them half a cycle apart. `null` derives the phase from the name (or the initials), so the same agent always moves the same way."
1479
+ },
1480
+ {
1481
+ "name": "msg",
1482
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1483
+ "default": null,
1484
+ "description": "Localized messages: the activity words, `agent.activity.<activity>`."
950
1485
  }
951
1486
  ],
952
1487
  "events": [],
@@ -955,7 +1490,7 @@
955
1490
  "name": "set",
956
1491
  "signature": "set(values)",
957
1492
  "returns": "this",
958
- "description": "Replaces avatar identity and presentation values."
1493
+ "description": "Replaces avatar identity and presentation values: any option but `msg`, `phase` included, so an animated avatar can be moved out of step with another of the same agent while it runs."
959
1494
  },
960
1495
  {
961
1496
  "name": "setStatus",
@@ -963,6 +1498,12 @@
963
1498
  "returns": "this",
964
1499
  "description": "Sets the presence state and its text alternative."
965
1500
  },
1501
+ {
1502
+ "name": "setActivity",
1503
+ "signature": "setActivity(activity, [label])",
1504
+ "returns": "this",
1505
+ "description": "Sets what an agent is doing and, optionally, the word for it. `null` clears the activity, and a person's `status` shows again if one is set."
1506
+ },
966
1507
  {
967
1508
  "name": "hasImage",
968
1509
  "signature": "hasImage()",
@@ -1064,44 +1605,145 @@
1064
1605
  "description": "Fallback currency."
1065
1606
  },
1066
1607
  {
1067
- "name": "locale",
1068
- "type": "string",
1069
- "default": null,
1070
- "description": "Number/currency locale."
1608
+ "name": "locale",
1609
+ "type": "string",
1610
+ "default": null,
1611
+ "description": "Number/currency locale."
1612
+ },
1613
+ {
1614
+ "name": "decimals",
1615
+ "type": "number",
1616
+ "default": "2",
1617
+ "description": "Currency fraction digits."
1618
+ },
1619
+ {
1620
+ "name": "columnOverrides",
1621
+ "type": "Record<string, object>",
1622
+ "default": "{}",
1623
+ "description": "Per-canonical-column overrides."
1624
+ },
1625
+ {
1626
+ "name": "lineTotal",
1627
+ "type": "(row: BillingRow, changes: Record<string, unknown>) => number|null|undefined",
1628
+ "default": null,
1629
+ "description": "Optional total calculation; defaults to quantity × unit price."
1630
+ },
1631
+ {
1632
+ "name": "columns",
1633
+ "type": "import('../table/table.js').TableColumn[]",
1634
+ "default": null,
1635
+ "description": "Complete column replacement."
1636
+ }
1637
+ ],
1638
+ "events": [
1639
+ {
1640
+ "name": "editcommit",
1641
+ "payload": "import('../table/table.js').TableEditCommitDetail",
1642
+ "description": "Caller edit listener, invoked after total calculation."
1643
+ }
1644
+ ],
1645
+ "methods": []
1646
+ },
1647
+ "BlockView": {
1648
+ "options": [
1649
+ {
1650
+ "name": "blocks",
1651
+ "type": "Block[]",
1652
+ "default": "[]",
1653
+ "description": "The answer's blocks. Model text is data: every string reaches the page as text, through the inline grammar of `**bold**`, `` `code` `` and `[n]` citations."
1654
+ },
1655
+ {
1656
+ "name": "headingLevel",
1657
+ "type": "2|3|4|5",
1658
+ "default": "3",
1659
+ "description": "Element level of a `heading` block of level 2; a level-3 heading goes one deeper. Set it one below the heading that names the answer."
1660
+ },
1661
+ {
1662
+ "name": "size",
1663
+ "type": "'sm'|'md'",
1664
+ "default": "'sm'",
1665
+ "description": "Prose size: `'sm'` sets the answer at the interface size, for a conversation; `'md'` at the reading size, for a document."
1666
+ },
1667
+ {
1668
+ "name": "streaming",
1669
+ "type": "boolean",
1670
+ "default": "false",
1671
+ "description": "Whether more is still being written. The last block stays open to `appendText()`, and the root is busy until `end()` or `stop()`."
1672
+ },
1673
+ {
1674
+ "name": "sources",
1675
+ "type": "Source[]|null",
1676
+ "default": "null",
1677
+ "description": "The sources citations point at; their titles name the citation buttons."
1678
+ },
1679
+ {
1680
+ "name": "msg",
1681
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1682
+ "default": null,
1683
+ "description": "Localized messages."
1684
+ }
1685
+ ],
1686
+ "events": [
1687
+ {
1688
+ "name": "cite",
1689
+ "payload": "{n: number, source: Source|null}",
1690
+ "description": "Citation listener."
1691
+ },
1692
+ {
1693
+ "name": "artifact",
1694
+ "payload": "{id: string}",
1695
+ "description": "Artifact listener."
1696
+ },
1697
+ {
1698
+ "name": "end",
1699
+ "payload": "Record<string, never>",
1700
+ "description": "End-of-stream listener."
1701
+ }
1702
+ ],
1703
+ "methods": [
1704
+ {
1705
+ "name": "setBlocks",
1706
+ "signature": "setBlocks(blocks, [options])",
1707
+ "returns": "this",
1708
+ "description": "Replaces every block, clearing a stopped state."
1709
+ },
1710
+ {
1711
+ "name": "append",
1712
+ "signature": "append(block)",
1713
+ "returns": "this",
1714
+ "description": "Adds a block after the last one. The blocks before it are left as they are."
1071
1715
  },
1072
1716
  {
1073
- "name": "decimals",
1074
- "type": "number",
1075
- "default": "2",
1076
- "description": "Currency fraction digits."
1717
+ "name": "appendText",
1718
+ "signature": "appendText(text)",
1719
+ "returns": "this",
1720
+ "description": "Streams text into the answer. It continues the last paragraph, or opens one when the answer ends in anything else; a blank line in the text starts a new paragraph. Only the last paragraph is redrawn, so a marker split across two calls (`**bo` … `ld**`) resolves as soon as its close arrives."
1077
1721
  },
1078
1722
  {
1079
- "name": "columnOverrides",
1080
- "type": "Record<string, object>",
1081
- "default": "{}",
1082
- "description": "Per-canonical-column overrides."
1723
+ "name": "end",
1724
+ "signature": "end()",
1725
+ "returns": "this",
1726
+ "description": "Marks the answer finished."
1083
1727
  },
1084
1728
  {
1085
- "name": "lineTotal",
1086
- "type": "(row: BillingRow, changes: Record<string, unknown>) => number|null|undefined",
1087
- "default": null,
1088
- "description": "Optional total calculation; defaults to quantity × unit price."
1729
+ "name": "stop",
1730
+ "signature": "stop()",
1731
+ "returns": "this",
1732
+ "description": "Marks the answer stopped where it is, with a line saying so."
1089
1733
  },
1090
1734
  {
1091
- "name": "columns",
1092
- "type": "import('../table/table.js').TableColumn[]",
1093
- "default": null,
1094
- "description": "Complete column replacement."
1095
- }
1096
- ],
1097
- "events": [
1735
+ "name": "setSources",
1736
+ "signature": "setSources(sources)",
1737
+ "returns": "this",
1738
+ "description": "Sets the sources citations point at."
1739
+ },
1098
1740
  {
1099
- "name": "editcommit",
1100
- "payload": "import('../table/table.js').TableEditCommitDetail",
1101
- "description": "Caller edit listener, invoked after total calculation."
1741
+ "name": "setArtifactState",
1742
+ "signature": "setArtifactState(id, state)",
1743
+ "returns": "this",
1744
+ "description": "Says whether an artifact's card has its artifact open somewhere — an inspector, a drawer — so the card reads as pressed and names what it controls. The application owns the open state; the card only reflects it."
1102
1745
  }
1103
- ],
1104
- "methods": []
1746
+ ]
1105
1747
  },
1106
1748
  "Breadcrumb": {
1107
1749
  "options": [
@@ -1272,7 +1914,7 @@
1272
1914
  "name": "locale",
1273
1915
  "type": "string|string[]",
1274
1916
  "default": null,
1275
- "description": "Intl locale override."
1917
+ "description": "Intl locale override. Unset, dates follow `setLanguage()`, and the browser's language under an English one."
1276
1918
  },
1277
1919
  {
1278
1920
  "name": "weekStart",
@@ -1655,6 +2297,12 @@
1655
2297
  "type": "'milliseconds'|'seconds'",
1656
2298
  "default": "'milliseconds'",
1657
2299
  "description": "Unit used for numeric dates."
2300
+ },
2301
+ {
2302
+ "name": "untitledTitle",
2303
+ "type": "string",
2304
+ "default": null,
2305
+ "description": "Title of an event without one, by default the `calendar.untitled` message (\"Untitled event\")."
1658
2306
  }
1659
2307
  ],
1660
2308
  "events": [],
@@ -2019,9 +2667,9 @@
2019
2667
  },
2020
2668
  {
2021
2669
  "name": "label",
2022
- "type": "string",
2023
- "default": "'Chart'",
2024
- "description": "Accessible canvas and summary label; blank text falls back to `Chart`."
2670
+ "type": "string|null",
2671
+ "default": "null",
2672
+ "description": "Accessible canvas and summary label; null or blank text reads the `chart.label` message (\"Chart\")."
2025
2673
  },
2026
2674
  {
2027
2675
  "name": "description",
@@ -2043,21 +2691,21 @@
2043
2691
  },
2044
2692
  {
2045
2693
  "name": "emptyText",
2046
- "type": "string",
2047
- "default": "'No chart data'",
2048
- "description": "Empty-state text."
2694
+ "type": "string|null",
2695
+ "default": null,
2696
+ "description": "Empty-state text, by default the `chart.empty` message (\"No chart data\"). Null shows none."
2049
2697
  },
2050
2698
  {
2051
2699
  "name": "loadingText",
2052
- "type": "string",
2053
- "default": "'Loading chart…'",
2054
- "description": "Loading-state text."
2700
+ "type": "string|null",
2701
+ "default": null,
2702
+ "description": "Loading-state text, by default the `chart.loading` message (\"Loading chart…\"). Null shows none."
2055
2703
  },
2056
2704
  {
2057
2705
  "name": "errorText",
2058
- "type": "string",
2059
- "default": "'Unable to render chart'",
2060
- "description": "Error fallback text."
2706
+ "type": "string|null",
2707
+ "default": null,
2708
+ "description": "Error fallback text, by default the `chart.error` message (\"Unable to render chart\"). Null shows none."
2061
2709
  },
2062
2710
  {
2063
2711
  "name": "aspectRatio",
@@ -2390,9 +3038,9 @@
2390
3038
  },
2391
3039
  {
2392
3040
  "name": "label",
2393
- "type": "string",
2394
- "default": "'Code editor'",
2395
- "description": "Accessible editor label."
3041
+ "type": "string|null",
3042
+ "default": "null",
3043
+ "description": "Accessible editor label; null reads the `codeEditor.label` message (\"Code editor\")."
2396
3044
  },
2397
3045
  {
2398
3046
  "name": "placeholder",
@@ -2450,17 +3098,320 @@
2450
3098
  "description": "Input listener."
2451
3099
  },
2452
3100
  {
2453
- "name": "change",
2454
- "payload": "{value:string}",
2455
- "description": "Change listener."
2456
- }
2457
- ],
2458
- "methods": [
3101
+ "name": "change",
3102
+ "payload": "{value:string}",
3103
+ "description": "Change listener."
3104
+ }
3105
+ ],
3106
+ "methods": [
3107
+ {
3108
+ "name": "setValue",
3109
+ "signature": "setValue(value, [options])",
3110
+ "returns": "this",
3111
+ "description": "Replaces the editor text."
3112
+ }
3113
+ ]
3114
+ },
3115
+ "Composer": {
3116
+ "options": [
3117
+ {
3118
+ "name": "label",
3119
+ "type": "string|null",
3120
+ "default": "null",
3121
+ "description": "Accessible name of the text and of the group around it. Omitted resolves `composer.label`, English `Message`."
3122
+ },
3123
+ {
3124
+ "name": "placeholder",
3125
+ "type": "string",
3126
+ "default": "''",
3127
+ "description": "Placeholder of the text."
3128
+ },
3129
+ {
3130
+ "name": "value",
3131
+ "type": "string",
3132
+ "default": "''",
3133
+ "description": "Initial text. Without it, a saved draft is restored."
3134
+ },
3135
+ {
3136
+ "name": "submitKey",
3137
+ "type": "'enter'|'mod+enter'",
3138
+ "default": "'enter'",
3139
+ "description": "`'enter'`: Enter sends and Shift+Enter breaks the line. `'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends and Enter breaks the line."
3140
+ },
3141
+ {
3142
+ "name": "busy",
3143
+ "type": "boolean",
3144
+ "default": "false",
3145
+ "description": "Whether an agent is working: Send becomes Stop."
3146
+ },
3147
+ {
3148
+ "name": "queue",
3149
+ "type": "boolean",
3150
+ "default": "false",
3151
+ "description": "Whether the send key holds a message back while the agent works. It is sent when the agent is no longer busy, one message each time busy ends, in order. The queue lives as long as the composer: it is not kept with the draft."
3152
+ },
3153
+ {
3154
+ "name": "queueLimit",
3155
+ "type": "number",
3156
+ "default": "10",
3157
+ "description": "Most messages that wait at once. At the limit the send key is refused, and the hint says why."
3158
+ },
3159
+ {
3160
+ "name": "disabled",
3161
+ "type": "boolean",
3162
+ "default": "false",
3163
+ "description": "Whether the composer takes no input."
3164
+ },
3165
+ {
3166
+ "name": "attachments",
3167
+ "type": "boolean",
3168
+ "default": "false",
3169
+ "description": "Whether files can be attached: an Attach button, paste, and drop."
3170
+ },
3171
+ {
3172
+ "name": "accept",
3173
+ "type": "string",
3174
+ "default": "''",
3175
+ "description": "File types accepted, in the `<input type=\"file\">` syntax (`'image/*,.pdf'`). Empty accepts every file."
3176
+ },
3177
+ {
3178
+ "name": "maxFiles",
3179
+ "type": "number",
3180
+ "default": "10",
3181
+ "description": "Most files one message carries."
3182
+ },
3183
+ {
3184
+ "name": "mentions",
3185
+ "type": "MentionSource|null",
3186
+ "default": "null",
3187
+ "description": "Enables `@` mentions."
3188
+ },
3189
+ {
3190
+ "name": "commands",
3191
+ "type": "LauncherItem[]|null",
3192
+ "default": "null",
3193
+ "description": "Commands opened by `/` on an empty text, in a Launcher; an item with `items` opens a page of further commands."
3194
+ },
3195
+ {
3196
+ "name": "context",
3197
+ "type": "ContextChip[]",
3198
+ "default": "[]",
3199
+ "description": "Initial context chips."
3200
+ },
3201
+ {
3202
+ "name": "hint",
3203
+ "type": "string",
3204
+ "default": "''",
3205
+ "description": "Quiet text in the bar beside Send."
3206
+ },
3207
+ {
3208
+ "name": "note",
3209
+ "type": "string",
3210
+ "default": "''",
3211
+ "description": "Quiet line under the composer."
3212
+ },
3213
+ {
3214
+ "name": "draftKey",
3215
+ "type": "string|null",
3216
+ "default": "null",
3217
+ "description": "Key the unsent text is kept under (through `storage()`), restored on create and cleared on send."
3218
+ },
3219
+ {
3220
+ "name": "minRows",
3221
+ "type": "number",
3222
+ "default": "1",
3223
+ "description": "Rows the text never shrinks below, even when empty. Capped at `maxRows`."
3224
+ },
3225
+ {
3226
+ "name": "maxRows",
3227
+ "type": "number",
3228
+ "default": "10",
3229
+ "description": "Rows the text grows to before it scrolls."
3230
+ },
3231
+ {
3232
+ "name": "icons",
3233
+ "type": "{attach?: string, commands?: string}",
3234
+ "default": "{}",
3235
+ "description": "Glyph names for the Attach and Commands buttons (a paperclip, a book) where the application registered its own."
3236
+ },
3237
+ {
3238
+ "name": "tools",
3239
+ "type": "ComposerTool[]",
3240
+ "default": "[]",
3241
+ "description": "Further icon buttons in the bar, after Attach and Commands. An entry without `id`, `label` or `icon` is left out, as is a repeated id."
3242
+ },
3243
+ {
3244
+ "name": "sendLabel",
3245
+ "type": "string|null",
3246
+ "default": "null",
3247
+ "description": "Visible text beside the Send glyph (`'Start task'`), which is then also its accessible name; while busy the button reads `composer.stop`. Null keeps Send icon-only. In a composer narrower than 24rem the text is visually hidden and stays the name."
3248
+ },
3249
+ {
3250
+ "name": "msg",
3251
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
3252
+ "default": null,
3253
+ "description": "Localized messages."
3254
+ }
3255
+ ],
3256
+ "events": [
3257
+ {
3258
+ "name": "send",
3259
+ "payload": "{text, files, mentions, context, queued}",
3260
+ "description": "Preventable send listener."
3261
+ },
3262
+ {
3263
+ "name": "stop",
3264
+ "payload": "Record<string, never>",
3265
+ "description": "Stop listener."
3266
+ },
3267
+ {
3268
+ "name": "input",
3269
+ "payload": "{text: string}",
3270
+ "description": "Text listener."
3271
+ },
3272
+ {
3273
+ "name": "attach",
3274
+ "payload": "{files: File[]}",
3275
+ "description": "Preventable attach listener."
3276
+ },
3277
+ {
3278
+ "name": "remove",
3279
+ "payload": "{kind, id, file, chip}",
3280
+ "description": "Chip removal listener."
3281
+ },
3282
+ {
3283
+ "name": "mention",
3284
+ "payload": "{item: MentionItem}",
3285
+ "description": "Mention listener."
3286
+ },
3287
+ {
3288
+ "name": "command",
3289
+ "payload": "{item: LauncherItem}",
3290
+ "description": "Command listener."
3291
+ },
3292
+ {
3293
+ "name": "tool",
3294
+ "payload": "{id, tool}",
3295
+ "description": "Tool listener."
3296
+ },
3297
+ {
3298
+ "name": "queue",
3299
+ "payload": "{item, items}",
3300
+ "description": "Listener for a message being queued."
3301
+ },
3302
+ {
3303
+ "name": "dequeue",
3304
+ "payload": "{item, items, reason}",
3305
+ "description": "Listener for a message leaving the queue."
3306
+ },
3307
+ {
3308
+ "name": "historyprevious",
3309
+ "payload": "Record<string, never>",
3310
+ "description": "Listener for ArrowUp on an empty text."
3311
+ }
3312
+ ],
3313
+ "methods": [
3314
+ {
3315
+ "name": "focus",
3316
+ "signature": "focus()",
3317
+ "returns": "this",
3318
+ "description": "Focuses the text."
3319
+ },
3320
+ {
3321
+ "name": "setValue",
3322
+ "signature": "setValue(text)",
3323
+ "returns": "this",
3324
+ "description": "Replaces the text, keeps the draft in step, and puts the caret at the end. Emits nothing."
3325
+ },
3326
+ {
3327
+ "name": "insertText",
3328
+ "signature": "insertText(text)",
3329
+ "returns": "this",
3330
+ "description": "Types text at the caret, replacing any selection, as if the person had typed it: the draft follows, and text ending in the mention trigger (`'@'`) opens the suggestions. Emits `input`. Use it for a button that starts a mention or inserts a snippet."
3331
+ },
3332
+ {
3333
+ "name": "clear",
3334
+ "signature": "clear()",
3335
+ "returns": "this",
3336
+ "description": "Empties the text, the attachments and the draft. Context chips stay. Emits nothing."
3337
+ },
3338
+ {
3339
+ "name": "setBusy",
3340
+ "signature": "setBusy(busy)",
3341
+ "returns": "this",
3342
+ "description": "Shows Stop in place of Send while an agent works; Escape in the text then emits `stop`. When busy ends, the first queued message is sent; the next waits for the next time it ends."
3343
+ },
3344
+ {
3345
+ "name": "setHint",
3346
+ "signature": "setHint(text)",
3347
+ "returns": "this",
3348
+ "description": "Changes the quiet text in the bar beside Send — what Enter does now, or why sending waits. An empty text hides it."
3349
+ },
3350
+ {
3351
+ "name": "setNote",
3352
+ "signature": "setNote(text)",
3353
+ "returns": "this",
3354
+ "description": "Changes the line under the composer, which also describes the text box. An empty text hides it."
3355
+ },
3356
+ {
3357
+ "name": "setDisabled",
3358
+ "signature": "setDisabled(disabled)",
3359
+ "returns": "this",
3360
+ "description": "Turns input on or off."
3361
+ },
3362
+ {
3363
+ "name": "update",
3364
+ "signature": "update([partial])",
3365
+ "returns": "this",
3366
+ "description": "Changes the composer in place: the text, its caret and selection, the focus, the attachments, the context chips and the draft all stay. This is how a placeholder follows the model picked beside the composer. Keys left out (or `undefined`) are kept; other keys are ignored. Emits nothing."
3367
+ },
3368
+ {
3369
+ "name": "setTools",
3370
+ "signature": "setTools(tools)",
3371
+ "returns": "this",
3372
+ "description": "Replaces the bar's extra tools. A tool that held the focus keeps it when a tool with the same id is still there (and enabled); otherwise the focus moves to the text. Emits nothing."
3373
+ },
3374
+ {
3375
+ "name": "setToolPressed",
3376
+ "signature": "setToolPressed(id, pressed)",
3377
+ "returns": "this",
3378
+ "description": "Presses or releases a tool, which makes it a toggle if it was a plain button. Emits nothing."
3379
+ },
3380
+ {
3381
+ "name": "addFiles",
3382
+ "signature": "addFiles(files)",
3383
+ "returns": "this",
3384
+ "description": "Attaches files, as far as `accept` and `maxFiles` allow. Emits `attach` with the files taken."
3385
+ },
3386
+ {
3387
+ "name": "addContext",
3388
+ "signature": "addContext(chip)",
3389
+ "returns": "this",
3390
+ "description": "Adds a context chip, or replaces the chip with the same id. Emits nothing."
3391
+ },
3392
+ {
3393
+ "name": "removeContext",
3394
+ "signature": "removeContext(id)",
3395
+ "returns": "this",
3396
+ "description": "Removes a context chip. Emits nothing."
3397
+ },
3398
+ {
3399
+ "name": "clearQueue",
3400
+ "signature": "clearQueue()",
3401
+ "returns": "this",
3402
+ "description": "Removes every queued message. Emits `dequeue` for each, with `reason: 'cleared'`. Stop does not do this: call it from a `stop` listener to drop what was waiting along with the run."
3403
+ },
2459
3404
  {
2460
- "name": "setValue",
2461
- "signature": "setValue(value, [options])",
3405
+ "name": "removeQueued",
3406
+ "signature": "removeQueued(id)",
2462
3407
  "returns": "this",
2463
- "description": "Replaces the editor text."
3408
+ "description": "Removes one queued message. Emits `dequeue` with `reason: 'removed'`. An id that is not queued, because the message has been sent, say, changes nothing."
3409
+ },
3410
+ {
3411
+ "name": "destroy",
3412
+ "signature": "destroy()",
3413
+ "returns": "void",
3414
+ "description": "Removes what the composer drew and the launcher it opened, drops the queue, and stops listening."
2464
3415
  }
2465
3416
  ]
2466
3417
  },
@@ -2599,15 +3550,15 @@
2599
3550
  },
2600
3551
  {
2601
3552
  "name": "title",
2602
- "type": "string",
2603
- "default": "'Copy'",
2604
- "description": "Accessible name, and the native tooltip on the icon-only form."
3553
+ "type": "string|null",
3554
+ "default": null,
3555
+ "description": "Accessible name, and the native tooltip on the icon-only form; by default the `copy.copy` message (\"Copy\"). Null gives none."
2605
3556
  },
2606
3557
  {
2607
3558
  "name": "feedback",
2608
- "type": "string",
2609
- "default": "'Copied'",
2610
- "description": "Confirmation announced and shown after a copy."
3559
+ "type": "string|null",
3560
+ "default": null,
3561
+ "description": "Confirmation announced and shown after a copy; by default the `copy.copied` message (\"Copied\"). Null says nothing."
2611
3562
  },
2612
3563
  {
2613
3564
  "name": "feedbackDuration",
@@ -2659,15 +3610,15 @@
2659
3610
  },
2660
3611
  {
2661
3612
  "name": "feedback",
2662
- "type": "string",
2663
- "default": "'Copied'",
2664
- "description": "Confirmation shown after a copy."
3613
+ "type": "string|null",
3614
+ "default": null,
3615
+ "description": "Confirmation shown after a copy, by default the `copy.copied` message (\"Copied\"). Null says nothing."
2665
3616
  },
2666
3617
  {
2667
3618
  "name": "buttonTitle",
2668
- "type": "string",
2669
- "default": "'Copy'",
2670
- "description": "Accessible name of the copy button."
3619
+ "type": "string|null",
3620
+ "default": null,
3621
+ "description": "Accessible name of the copy button, by default the `copy.copy` message (\"Copy\"). Null gives none."
2671
3622
  },
2672
3623
  {
2673
3624
  "name": "size",
@@ -2710,6 +3661,60 @@
2710
3661
  }
2711
3662
  ]
2712
3663
  },
3664
+ "CountrySelect": {
3665
+ "options": [
3666
+ {
3667
+ "name": "countries",
3668
+ "type": "Array<string|CountryItem>",
3669
+ "default": null,
3670
+ "description": "The countries to offer. Without it, every ISO 3166-1 country (`COUNTRY_CODES`). A code that is not two letters is left out."
3671
+ },
3672
+ {
3673
+ "name": "preferred",
3674
+ "type": "Array<string|CountryItem>",
3675
+ "default": "[]",
3676
+ "description": "Countries pinned above the list, in the order given and kept through filtering — the markets an application serves, say."
3677
+ },
3678
+ {
3679
+ "name": "preferredLabel",
3680
+ "type": "string|null",
3681
+ "default": "null",
3682
+ "description": "Heading above the pinned countries."
3683
+ },
3684
+ {
3685
+ "name": "displayLocale",
3686
+ "type": "string|null",
3687
+ "default": "null",
3688
+ "description": "The language country names are written in. By default the component's `lang` option, then the library language (`setLanguage()`)."
3689
+ },
3690
+ {
3691
+ "name": "flags",
3692
+ "type": "FlagMode",
3693
+ "default": "'auto'",
3694
+ "description": "What stands before each country: its flag (`auto` draws flag emoji where the platform has them and a code chip where it does not; `emoji` forces the emoji), the code chip (`code`), nothing (`none`), or a function returning the content."
3695
+ },
3696
+ {
3697
+ "name": "flagUrl",
3698
+ "type": "string|null",
3699
+ "default": "null",
3700
+ "description": "Flag image URL template, such as `'/flags/{code}.svg'`; `{code}` is the lower-case code, `{CODE}` the upper-case. Draws flags from the application's own flag set instead of emoji."
3701
+ },
3702
+ {
3703
+ "name": "showCode",
3704
+ "type": "boolean",
3705
+ "default": "false",
3706
+ "description": "Shows the ISO code as secondary text."
3707
+ },
3708
+ {
3709
+ "name": "sort",
3710
+ "type": "boolean",
3711
+ "default": "true",
3712
+ "description": "Orders the countries by name in the display language; `false` keeps the order given."
3713
+ }
3714
+ ],
3715
+ "events": [],
3716
+ "methods": []
3717
+ },
2713
3718
  "DataFilter": {
2714
3719
  "options": [
2715
3720
  {
@@ -3489,9 +4494,9 @@
3489
4494
  },
3490
4495
  {
3491
4496
  "name": "label",
3492
- "type": "string",
3493
- "default": "'Resize panes'",
3494
- "description": "Accessible name given to every divider."
4497
+ "type": "string|null",
4498
+ "default": "null",
4499
+ "description": "Accessible name given to every divider; null reads the `dock.resize` message (\"Resize panes\")."
3495
4500
  }
3496
4501
  ],
3497
4502
  "events": [
@@ -3734,6 +4739,42 @@
3734
4739
  }
3735
4740
  ]
3736
4741
  },
4742
+ "ElicitationHandler": {
4743
+ "options": [
4744
+ {
4745
+ "name": "serverName",
4746
+ "type": "string",
4747
+ "default": null,
4748
+ "description": "The name of the server that asks, as the client knows it; shown as \"Asked by <server>\". Required: the person must always see who asks."
4749
+ },
4750
+ {
4751
+ "name": "authors",
4752
+ "type": "Record<string, {name: string}>",
4753
+ "default": "{}",
4754
+ "description": "Display names by key; when it lists `serverName`, that entry's name is shown instead."
4755
+ },
4756
+ {
4757
+ "name": "target",
4758
+ "type": "Element|string|null",
4759
+ "default": "null",
4760
+ "description": "Where the surface goes inline; a Dialog without one."
4761
+ },
4762
+ {
4763
+ "name": "open",
4764
+ "type": "(url: string) => boolean|void",
4765
+ "default": null,
4766
+ "description": "Opens the page in URL mode, after the person agreed. It receives the normalised address and must open it in a new browsing context that cannot reach the application; returning `false` or throwing means it was not opened, and the request answers `cancel`. The default opens a new tab with `noopener` and `noreferrer`."
4767
+ },
4768
+ {
4769
+ "name": "msg",
4770
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
4771
+ "default": null,
4772
+ "description": "Localized messages, flat or by language: the `mcp.*` keys, and the `surface.*` keys of the form."
4773
+ }
4774
+ ],
4775
+ "events": [],
4776
+ "methods": []
4777
+ },
3737
4778
  "EmptyState": {
3738
4779
  "options": [
3739
4780
  {
@@ -3834,9 +4875,9 @@
3834
4875
  },
3835
4876
  {
3836
4877
  "name": "actionsLabel",
3837
- "type": "string",
3838
- "default": "'Entity actions'",
3839
- "description": "Accessible name for secondary actions."
4878
+ "type": "string|null",
4879
+ "default": "null",
4880
+ "description": "Accessible name for secondary actions; null reads the `entityRef.actions` message (\"Entity actions\")."
3840
4881
  }
3841
4882
  ],
3842
4883
  "events": [
@@ -3906,9 +4947,9 @@
3906
4947
  },
3907
4948
  {
3908
4949
  "name": "recentLabel",
3909
- "type": "string",
3910
- "default": "'Recent'",
3911
- "description": "Heading above recent choices."
4950
+ "type": "string|null",
4951
+ "default": null,
4952
+ "description": "Heading above recent choices, by default the `select.recent` message (\"Recent\"); null shows none."
3912
4953
  },
3913
4954
  {
3914
4955
  "name": "create",
@@ -4444,9 +5485,9 @@
4444
5485
  },
4445
5486
  {
4446
5487
  "name": "actionsLabel",
4447
- "type": "string",
4448
- "default": "'File actions'",
4449
- "description": "Accessible name for secondary actions."
5488
+ "type": "string|null",
5489
+ "default": "null",
5490
+ "description": "Accessible name for secondary actions; null reads the `fileItem.actions` message (\"File actions\")."
4450
5491
  },
4451
5492
  {
4452
5493
  "name": "locale",
@@ -4516,9 +5557,9 @@
4516
5557
  },
4517
5558
  {
4518
5559
  "name": "label",
4519
- "type": "string",
4520
- "default": "'Files'",
4521
- "description": "Accessible collection name."
5560
+ "type": "string|null",
5561
+ "default": "null",
5562
+ "description": "Accessible collection name; null reads the `fileList.label` message (\"Files\")."
4522
5563
  },
4523
5564
  {
4524
5565
  "name": "loading",
@@ -4534,15 +5575,15 @@
4534
5575
  },
4535
5576
  {
4536
5577
  "name": "loadingText",
4537
- "type": "string",
4538
- "default": "'Loading files'",
4539
- "description": "Loading status text."
5578
+ "type": "string|null",
5579
+ "default": null,
5580
+ "description": "Loading status text, by default the `fileList.loading` message (\"Loading files\"). Null shows none."
4540
5581
  },
4541
5582
  {
4542
5583
  "name": "emptyText",
4543
5584
  "type": "string|number|Node|Component|null",
4544
- "default": "'No files'",
4545
- "description": "Empty-state content."
5585
+ "default": null,
5586
+ "description": "Empty-state content, by default the `fileList.empty` message (\"No files\"). Null shows none."
4546
5587
  }
4547
5588
  ],
4548
5589
  "events": [
@@ -4991,9 +6032,9 @@
4991
6032
  },
4992
6033
  {
4993
6034
  "name": "emptyText",
4994
- "type": "string",
4995
- "default": "'Empty'",
4996
- "description": "Text shown in an empty column."
6035
+ "type": "string|null",
6036
+ "default": null,
6037
+ "description": "Text shown in an empty column, by default the `finder.noItems` message (\"Empty\"). Null shows none."
4997
6038
  },
4998
6039
  {
4999
6040
  "name": "msg",
@@ -5070,6 +6111,36 @@
5070
6111
  }
5071
6112
  ]
5072
6113
  },
6114
+ "Flag": {
6115
+ "options": [
6116
+ {
6117
+ "name": "kind",
6118
+ "type": "FlagKind",
6119
+ "default": "'auto'",
6120
+ "description": "Drawing; `src` implies `image`."
6121
+ },
6122
+ {
6123
+ "name": "src",
6124
+ "type": "string|null",
6125
+ "default": "null",
6126
+ "description": "Image URL. `{code}` in it is replaced by the lower-case region code and `{CODE}` by the upper-case one, so `'/flags/{code}.svg'` serves a whole flag set."
6127
+ },
6128
+ {
6129
+ "name": "text",
6130
+ "type": "string|null",
6131
+ "default": "null",
6132
+ "description": "Text of the code chip, by default the region code. A chip also stands in for a flag when there is no valid region, as for a language without a country."
6133
+ },
6134
+ {
6135
+ "name": "label",
6136
+ "type": "string|null",
6137
+ "default": "null",
6138
+ "description": "Accessible name. Without one the flag is decorative (`aria-hidden`) and must sit beside text that names the country or language."
6139
+ }
6140
+ ],
6141
+ "events": [],
6142
+ "methods": []
6143
+ },
5073
6144
  "Form": {
5074
6145
  "options": [
5075
6146
  {
@@ -5328,6 +6399,34 @@
5328
6399
  }
5329
6400
  ]
5330
6401
  },
6402
+ "InlineSplitter": {
6403
+ "options": [
6404
+ {
6405
+ "name": "maxLine",
6406
+ "type": "number",
6407
+ "default": "262144",
6408
+ "description": "Longest line inside a fence."
6409
+ }
6410
+ ],
6411
+ "events": [
6412
+ {
6413
+ "name": "text",
6414
+ "payload": null,
6415
+ "description": "Receives prose, as it arrives, unchanged."
6416
+ },
6417
+ {
6418
+ "name": "line",
6419
+ "payload": null,
6420
+ "description": "Receives each line inside a surface fence."
6421
+ },
6422
+ {
6423
+ "name": "error",
6424
+ "payload": null,
6425
+ "description": "Receives an over-long line inside a fence and a fence still open at `end()`."
6426
+ }
6427
+ ],
6428
+ "methods": []
6429
+ },
5331
6430
  "KanbanView": {
5332
6431
  "options": [
5333
6432
  {
@@ -5658,7 +6757,7 @@
5658
6757
  "name": "labels",
5659
6758
  "type": "Record<string,string>",
5660
6759
  "default": "{}",
5661
- "description": "Overrides for every visible and announced string."
6760
+ "description": "Per-instance overrides of the board's text. Each key is the part after `kanbanView.` in the message catalogue, where every visible and announced string lives, and a value may reorder or drop the named placeholders."
5662
6761
  },
5663
6762
  {
5664
6763
  "name": "columnOrder",
@@ -5704,9 +6803,9 @@
5704
6803
  },
5705
6804
  {
5706
6805
  "name": "label",
5707
- "type": "string",
5708
- "default": "'Kanban board'",
5709
- "description": "Accessible board label."
6806
+ "type": "string|null",
6807
+ "default": null,
6808
+ "description": "Accessible board label, by default the `kanbanView.label` message (\"Kanban board\"). Null leaves the board unnamed."
5710
6809
  }
5711
6810
  ],
5712
6811
  "events": [
@@ -6202,6 +7301,24 @@
6202
7301
  "events": [],
6203
7302
  "methods": []
6204
7303
  },
7304
+ "LineSplitter": {
7305
+ "options": [
7306
+ {
7307
+ "name": "maxLine",
7308
+ "type": "number",
7309
+ "default": "262144",
7310
+ "description": "Longest line, in characters, that is buffered. A longer one is reported once and dropped up to its end rather than held in memory."
7311
+ }
7312
+ ],
7313
+ "events": [
7314
+ {
7315
+ "name": "error",
7316
+ "payload": null,
7317
+ "description": "Receives an over-long line's report."
7318
+ }
7319
+ ],
7320
+ "methods": []
7321
+ },
6205
7322
  "ListToolbar": {
6206
7323
  "options": [
6207
7324
  {
@@ -6375,6 +7492,66 @@
6375
7492
  }
6376
7493
  ]
6377
7494
  },
7495
+ "LocaleSelect": {
7496
+ "options": [
7497
+ {
7498
+ "name": "locales",
7499
+ "type": "Array<string|LocaleItem>",
7500
+ "default": null,
7501
+ "description": "The locales to offer, in the order given. Tags are canonicalized (`'de_at'` → `'de-AT'`); an invalid tag is left out. Without it the picker offers a short list of widely used languages."
7502
+ },
7503
+ {
7504
+ "name": "preferred",
7505
+ "type": "Array<string|LocaleItem>",
7506
+ "default": "[]",
7507
+ "description": "Locales pinned above the list, kept through filtering — the application's own languages above a long list, say."
7508
+ },
7509
+ {
7510
+ "name": "preferredLabel",
7511
+ "type": "string|null",
7512
+ "default": "null",
7513
+ "description": "Heading above the pinned locales."
7514
+ },
7515
+ {
7516
+ "name": "displayLocale",
7517
+ "type": "string|null",
7518
+ "default": "null",
7519
+ "description": "The language the secondary name is written in. By default the component's `lang` option, then the library language (`setLanguage()`)."
7520
+ },
7521
+ {
7522
+ "name": "display",
7523
+ "type": "'both'|'native'|'localized'",
7524
+ "default": "'both'",
7525
+ "description": "`native` names each locale in its own language (\"Deutsch\"), `localized` in the display language (\"German\"), and `both` shows the native name with the localized one beneath it where the two differ — so a reader finds their language whichever language the interface is in."
7526
+ },
7527
+ {
7528
+ "name": "flags",
7529
+ "type": "FlagMode",
7530
+ "default": "'auto'",
7531
+ "description": "What stands before each locale: the flag of its region (`auto` draws flag emoji where the platform has them and a language chip where it does not; `emoji` forces the emoji), a language chip (`code`, the honest choice where a language is not a country), nothing (`none`), or a function returning the content."
7532
+ },
7533
+ {
7534
+ "name": "flagUrl",
7535
+ "type": "string|null",
7536
+ "default": "null",
7537
+ "description": "Flag image URL template, such as `'/flags/{code}.svg'`; `{code}` is the lower-case region, `{CODE}` the upper-case. Draws flags from the application's own flag set instead of emoji."
7538
+ },
7539
+ {
7540
+ "name": "flagRegions",
7541
+ "type": "Record<string, string|null>",
7542
+ "default": "{}",
7543
+ "description": "Flag region per tag or language, for a language whose likely region is not the one the application means: `{ en: 'GB' }`. A tag with a region of its own (`en-US`) keeps it unless it is listed here itself."
7544
+ },
7545
+ {
7546
+ "name": "sort",
7547
+ "type": "boolean",
7548
+ "default": "false",
7549
+ "description": "Orders the locales by label rather than as given."
7550
+ }
7551
+ ],
7552
+ "events": [],
7553
+ "methods": []
7554
+ },
6378
7555
  "MasterPanel": {
6379
7556
  "options": [
6380
7557
  {
@@ -7038,9 +8215,9 @@
7038
8215
  },
7039
8216
  {
7040
8217
  "name": "addLabel",
7041
- "type": "string",
7042
- "default": "'Add value'",
7043
- "description": "Add-row button text."
8218
+ "type": "string|null",
8219
+ "default": "null",
8220
+ "description": "Add-row button text; null reads the `multiValueEditor.add` message (\"Add value\")."
7044
8221
  },
7045
8222
  {
7046
8223
  "name": "reorder",
@@ -7252,7 +8429,7 @@
7252
8429
  "name": "locale",
7253
8430
  "type": "string|null",
7254
8431
  "default": "null",
7255
- "description": "Locale for formatting; defaults to the document locale."
8432
+ "description": "Locale for formatting; defaults to the active language."
7256
8433
  },
7257
8434
  {
7258
8435
  "name": "msg",
@@ -7784,26 +8961,81 @@
7784
8961
  "description": "Initial input value."
7785
8962
  },
7786
8963
  {
7787
- "name": "placeholder",
7788
- "type": "string",
7789
- "default": "''",
7790
- "description": "Input placeholder."
7791
- },
8964
+ "name": "placeholder",
8965
+ "type": "string",
8966
+ "default": "''",
8967
+ "description": "Input placeholder."
8968
+ },
8969
+ {
8970
+ "name": "okLabel",
8971
+ "type": "string",
8972
+ "default": "'OK'",
8973
+ "description": "Confirmation label."
8974
+ },
8975
+ {
8976
+ "name": "cancelLabel",
8977
+ "type": "string",
8978
+ "default": "'Cancel'",
8979
+ "description": "Cancellation label."
8980
+ }
8981
+ ],
8982
+ "events": [],
8983
+ "methods": []
8984
+ },
8985
+ "PromptStarters": {
8986
+ "options": [
8987
+ {
8988
+ "name": "items",
8989
+ "type": "PromptStarter[]",
8990
+ "default": "[]",
8991
+ "description": "The starters. An entry without `id`, `title` or `text` is left out, as is a repeated id; any other field on an item is handed back in `pick`."
8992
+ },
8993
+ {
8994
+ "name": "label",
8995
+ "type": "string|null",
8996
+ "default": "null",
8997
+ "description": "Accessible name of the group. Omitted resolves `promptStarters.label`, English `Suggestions`."
8998
+ },
8999
+ {
9000
+ "name": "columns",
9001
+ "type": "'auto'|1|2",
9002
+ "default": "'auto'",
9003
+ "description": "Columns of starters. `'auto'` is two, and one in a container narrower than 32rem."
9004
+ },
9005
+ {
9006
+ "name": "headingLevel",
9007
+ "type": "1|2|3|4|5|6|null",
9008
+ "default": "null",
9009
+ "description": "Shows `label` above the starters as a heading of this level, which then names the group. Null keeps the label for assistive technology only."
9010
+ },
9011
+ {
9012
+ "name": "msg",
9013
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
9014
+ "default": null,
9015
+ "description": "Localized messages."
9016
+ }
9017
+ ],
9018
+ "events": [
9019
+ {
9020
+ "name": "pick",
9021
+ "payload": "{item: PromptStarter}",
9022
+ "description": "Listener for a starter being picked."
9023
+ }
9024
+ ],
9025
+ "methods": [
7792
9026
  {
7793
- "name": "okLabel",
7794
- "type": "string",
7795
- "default": "'OK'",
7796
- "description": "Confirmation label."
9027
+ "name": "setItems",
9028
+ "signature": "setItems(items)",
9029
+ "returns": "this",
9030
+ "description": "Replaces the starters. The focus on a starter stays on the starter with the same `id`. Emits nothing."
7797
9031
  },
7798
9032
  {
7799
- "name": "cancelLabel",
7800
- "type": "string",
7801
- "default": "'Cancel'",
7802
- "description": "Cancellation label."
9033
+ "name": "destroy",
9034
+ "signature": "destroy()",
9035
+ "returns": "void",
9036
+ "description": "Removes what was drawn and stops listening."
7803
9037
  }
7804
- ],
7805
- "events": [],
7806
- "methods": []
9038
+ ]
7807
9039
  },
7808
9040
  "ProseAnchors": {
7809
9041
  "options": [
@@ -7815,21 +9047,21 @@
7815
9047
  },
7816
9048
  {
7817
9049
  "name": "label",
7818
- "type": "string",
7819
- "default": "'Copy link to %1'",
7820
- "description": "The link's accessible name; `%1` is the heading."
9050
+ "type": "string|null",
9051
+ "default": null,
9052
+ "description": "The link's accessible name; `%1` is the heading. By default the `prose.copyLinkTo` message (\"Copy link to %1\"). Null gives none."
7821
9053
  },
7822
9054
  {
7823
9055
  "name": "title",
7824
- "type": "string",
7825
- "default": "'Copy link'",
7826
- "description": "The link's tooltip."
9056
+ "type": "string|null",
9057
+ "default": null,
9058
+ "description": "The link's tooltip, by default the `prose.copyLink` message (\"Copy link\"). Null gives none."
7827
9059
  },
7828
9060
  {
7829
9061
  "name": "feedback",
7830
- "type": "string",
7831
- "default": "'Link copied'",
7832
- "description": "What the live region says after a copy."
9062
+ "type": "string|null",
9063
+ "default": null,
9064
+ "description": "What the live region says after a copy, by default the `prose.copied` message (\"Link copied\"). Null says nothing."
7833
9065
  },
7834
9066
  {
7835
9067
  "name": "feedbackDuration",
@@ -8093,9 +9325,9 @@
8093
9325
  },
8094
9326
  {
8095
9327
  "name": "label",
8096
- "type": "string",
8097
- "default": "'Rating'",
8098
- "description": "Accessible name of the group."
9328
+ "type": "string|null",
9329
+ "default": "null",
9330
+ "description": "Accessible name of the group; null reads the `rating.label` message (\"Rating\")."
8099
9331
  },
8100
9332
  {
8101
9333
  "name": "icon",
@@ -8587,6 +9819,299 @@
8587
9819
  }
8588
9820
  ]
8589
9821
  },
9822
+ "RenderBlocks": {
9823
+ "options": [
9824
+ {
9825
+ "name": "headingLevel",
9826
+ "type": "2|3|4|5",
9827
+ "default": "3",
9828
+ "description": "Element level of a level-2 `heading` block."
9829
+ },
9830
+ {
9831
+ "name": "msg",
9832
+ "type": "(key: string, ...args: unknown[]) => string",
9833
+ "default": null,
9834
+ "description": "Message lookup for the few words the blocks add (code copy, artifact kinds)."
9835
+ }
9836
+ ],
9837
+ "events": [],
9838
+ "methods": []
9839
+ },
9840
+ "RunStatus": {
9841
+ "options": [
9842
+ {
9843
+ "name": "state",
9844
+ "type": "RunState",
9845
+ "default": "'queued'",
9846
+ "description": "Where the run stands. Also the root's `data-state`. A `blocked` run is not over: it shows since when it is blocked, never a finished time."
9847
+ },
9848
+ {
9849
+ "name": "summary",
9850
+ "type": "string",
9851
+ "default": "''",
9852
+ "description": "One sentence on what is happening: \"Step 3 of 6 needs your approval.\" Text only."
9853
+ },
9854
+ {
9855
+ "name": "steps",
9856
+ "type": "RunSteps|null",
9857
+ "default": "null",
9858
+ "description": "Steps done out of the total, drawn as a progressbar."
9859
+ },
9860
+ {
9861
+ "name": "started",
9862
+ "type": "RunTime|null",
9863
+ "default": "null",
9864
+ "description": "When the run started."
9865
+ },
9866
+ {
9867
+ "name": "finished",
9868
+ "type": "RunTime|null",
9869
+ "default": "null",
9870
+ "description": "When it finished, failed, or was stopped. Shown once the run is over."
9871
+ },
9872
+ {
9873
+ "name": "workMs",
9874
+ "type": "number|null",
9875
+ "default": "null",
9876
+ "description": "How long the agent has worked, in milliseconds. Waiting for a person is not work. The row shows only when this is a number."
9877
+ },
9878
+ {
9879
+ "name": "waitingSince",
9880
+ "type": "RunTime|null",
9881
+ "default": "null",
9882
+ "description": "Since when the run has waited for a person, or been blocked. Shown as \"Waiting since\" while the state is `waiting` and \"Blocked since\" while it is `blocked`."
9883
+ },
9884
+ {
9885
+ "name": "tokens",
9886
+ "type": "RunTokens|null",
9887
+ "default": "null",
9888
+ "description": "Input and output tokens as `[in, out]`, or the total as one number."
9889
+ },
9890
+ {
9891
+ "name": "tokenBudget",
9892
+ "type": "number|null",
9893
+ "default": "null",
9894
+ "description": "The most tokens the run may use. With a budget the tokens are a meter, read in compact figures (\"22.8K of 60K tokens\"), that turns to the warning tone from 80% and to the danger tone at 100%. Without one they stay text."
9895
+ },
9896
+ {
9897
+ "name": "cost",
9898
+ "type": "RunCost|null",
9899
+ "default": "null",
9900
+ "description": "What the run has cost, against its budget."
9901
+ },
9902
+ {
9903
+ "name": "model",
9904
+ "type": "string|null",
9905
+ "default": "null",
9906
+ "description": "The model the agent runs on."
9907
+ },
9908
+ {
9909
+ "name": "actions",
9910
+ "type": "RunStatusAction[]",
9911
+ "default": "[]",
9912
+ "description": "Buttons under the summary."
9913
+ },
9914
+ {
9915
+ "name": "ticking",
9916
+ "type": "boolean",
9917
+ "default": "true",
9918
+ "description": "While the state is `running`, the working time counts on once a second from `workMs` and the moment of the last `update()`. One interval, which sleeps while the page is hidden."
9919
+ },
9920
+ {
9921
+ "name": "compact",
9922
+ "type": "boolean|'icon'",
9923
+ "default": "false",
9924
+ "description": "Draws only the state: `true` as a pill of glyph and word for a narrow header, `'icon'` as the glyph alone, its word visually hidden but still the accessible text, and shown as the pill's tooltip."
9925
+ },
9926
+ {
9927
+ "name": "now",
9928
+ "type": "(() => Date)|null",
9929
+ "default": "null",
9930
+ "description": "The clock: what decides whether a time is today (a time on another day shows its date too) and what the working time counts against while `ticking`. Null is real time. Fixed at construction."
9931
+ },
9932
+ {
9933
+ "name": "locale",
9934
+ "type": "string",
9935
+ "default": null,
9936
+ "description": "BCP 47 tag for numbers and amounts; defaults to the active language."
9937
+ },
9938
+ {
9939
+ "name": "msg",
9940
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
9941
+ "default": null,
9942
+ "description": "Localized messages: the state words (`agent.status.*`) and the `runStatus.*` labels."
9943
+ }
9944
+ ],
9945
+ "events": [
9946
+ {
9947
+ "name": "action",
9948
+ "payload": "{index: number, action: RunStatusAction}",
9949
+ "description": "Action listener."
9950
+ }
9951
+ ],
9952
+ "methods": [
9953
+ {
9954
+ "name": "update",
9955
+ "signature": "update(values)",
9956
+ "returns": "this",
9957
+ "description": "Merges new values and redraws. The working time carries on from where it stood unless the update brings a new `workMs`. Focus inside the panel stays where it was: an action row that did not change is kept as it is, and otherwise focus moves to the action at the same index (or the nearest one left), or to the panel itself when no action is left."
9958
+ },
9959
+ {
9960
+ "name": "destroy",
9961
+ "signature": "destroy()",
9962
+ "returns": "void",
9963
+ "description": "Stops the clock, removes what the component drew, and restores an enhanced target."
9964
+ }
9965
+ ]
9966
+ },
9967
+ "RunTrace": {
9968
+ "options": [
9969
+ {
9970
+ "name": "steps",
9971
+ "type": "TraceStep[]",
9972
+ "default": "[]",
9973
+ "description": "The steps the run took, in the order they started. A step with `retryOf` is drawn under the step it repeats. Model text is data: every string reaches the page as text."
9974
+ },
9975
+ {
9976
+ "name": "open",
9977
+ "type": "boolean",
9978
+ "default": "false",
9979
+ "description": "Whether the step list starts open under its summary."
9980
+ },
9981
+ {
9982
+ "name": "label",
9983
+ "type": "string|null",
9984
+ "default": "null",
9985
+ "description": "Text the summary reads instead of the computed \"Worked for …\" line — a plan's title, \"Plan · 5 of 6 done\". Any state but done still follows it as a word (\"· Running\"). `setLabel()` changes it."
9986
+ },
9987
+ {
9988
+ "name": "authors",
9989
+ "type": "Record<string, Author>",
9990
+ "default": "{}",
9991
+ "description": "Who the `actor` and `to` keys of the steps name; a hand-off draws both authors' avatars, round for a `person` and rounded squares otherwise. A key with no entry is shown as written."
9992
+ },
9993
+ {
9994
+ "name": "showArguments",
9995
+ "type": "boolean",
9996
+ "default": "true",
9997
+ "description": "Whether a step's disclosure shows the arguments its call was made with."
9998
+ },
9999
+ {
10000
+ "name": "maxResult",
10001
+ "type": "number",
10002
+ "default": "4000",
10003
+ "description": "Characters of a result shown before it is cut, with a \"Show all\" button for the rest. Zero or a non-finite value shows every result whole."
10004
+ },
10005
+ {
10006
+ "name": "summary",
10007
+ "type": "boolean",
10008
+ "default": "true",
10009
+ "description": "Whether the steps fold into a summary line. Without it the list always shows — for a run panel whose state is already told beside it."
10010
+ },
10011
+ {
10012
+ "name": "kindIcons",
10013
+ "type": "boolean|null",
10014
+ "default": "null",
10015
+ "description": "Whether each step leads with its kind's glyph. Without them a step shows only its status. `null` decides by the steps: a plan, where every step is a `task`, shows none; anything else shows them."
10016
+ },
10017
+ {
10018
+ "name": "selectable",
10019
+ "type": "boolean",
10020
+ "default": "false",
10021
+ "description": "Whether every step can be chosen: a row with nothing to open becomes a button, and a disclosure also reports the step as it opens. Both emit `select`."
10022
+ },
10023
+ {
10024
+ "name": "ticking",
10025
+ "type": "boolean",
10026
+ "default": "false",
10027
+ "description": "Whether a running step that has `at` shows how long it has run, counting once a second. One interval serves the whole trace; it runs only while such a step is on screen in the open list, and sleeps while the page is hidden."
10028
+ },
10029
+ {
10030
+ "name": "now",
10031
+ "type": "(() => Date)|null",
10032
+ "default": "null",
10033
+ "description": "The clock `ticking` counts against, for an application whose world is fixed on another date; real time when null."
10034
+ },
10035
+ {
10036
+ "name": "formatTime",
10037
+ "type": "((at: string) => string)|null",
10038
+ "default": "null",
10039
+ "description": "Writes a step's `at` for its meta line; \"10:31:05\" (the local ISO time as given) when null."
10040
+ },
10041
+ {
10042
+ "name": "icons",
10043
+ "type": "Partial<Record<TraceKind, string>>",
10044
+ "default": "{}",
10045
+ "description": "Icon names per step kind, over the built-in `STEP_ICONS`."
10046
+ },
10047
+ {
10048
+ "name": "msg",
10049
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
10050
+ "default": null,
10051
+ "description": "Localized messages: the `runTrace.*` keys and the `agent.status.*` words."
10052
+ }
10053
+ ],
10054
+ "events": [
10055
+ {
10056
+ "name": "toggle",
10057
+ "payload": "{id: string|null, open: boolean}",
10058
+ "description": "Disclosure listener."
10059
+ },
10060
+ {
10061
+ "name": "reveal",
10062
+ "payload": "{id: string}",
10063
+ "description": "Reveal listener."
10064
+ },
10065
+ {
10066
+ "name": "select",
10067
+ "payload": "{id: string}",
10068
+ "description": "Selection listener (`selectable` traces)."
10069
+ },
10070
+ {
10071
+ "name": "open",
10072
+ "payload": "{step: TraceStep, ref: ItemRef}",
10073
+ "description": "Listener for a step's links."
10074
+ }
10075
+ ],
10076
+ "methods": [
10077
+ {
10078
+ "name": "setLabel",
10079
+ "signature": "setLabel(label)",
10080
+ "returns": "this",
10081
+ "description": "Sets the text the summary reads instead of the computed line; null or an empty string goes back to \"Worked for …\". Any state but done still follows it as a word."
10082
+ },
10083
+ {
10084
+ "name": "setSteps",
10085
+ "signature": "setSteps(steps)",
10086
+ "returns": "this",
10087
+ "description": "Replaces every step. Open steps stay open, and focus on a step's row stays on that step."
10088
+ },
10089
+ {
10090
+ "name": "upsert",
10091
+ "signature": "upsert(step)",
10092
+ "returns": "this",
10093
+ "description": "Adds a step, or replaces the step with the same `id`. A replaced step is redrawn on its own, keeping its place, its open state, and the retries under it; a new step is appended, under the step it repeats when it has `retryOf`."
10094
+ },
10095
+ {
10096
+ "name": "expand",
10097
+ "signature": "expand([id])",
10098
+ "returns": "this",
10099
+ "description": "Opens the step list, and the disclosure of the step `id` when one is given."
10100
+ },
10101
+ {
10102
+ "name": "collapse",
10103
+ "signature": "collapse([id])",
10104
+ "returns": "this",
10105
+ "description": "Closes the step list, or only the disclosure of the step `id` when one is given."
10106
+ },
10107
+ {
10108
+ "name": "reveal",
10109
+ "signature": "reveal(id)",
10110
+ "returns": "this",
10111
+ "description": "Shows one step: opens the list and the step, scrolls it into view, puts focus on its row, and marks it with `data-state=\"revealed\"` for two seconds. Under reduced motion the scroll jumps. An unknown id does nothing."
10112
+ }
10113
+ ]
10114
+ },
8590
10115
  "Search": {
8591
10116
  "options": [
8592
10117
  {
@@ -8893,10 +10418,34 @@
8893
10418
  "description": "Disables user interaction and closes the panel."
8894
10419
  },
8895
10420
  {
8896
- "name": "focus",
8897
- "signature": "focus()",
8898
- "returns": "this",
8899
- "description": "Moves focus to the combobox input."
10421
+ "name": "focus",
10422
+ "signature": "focus()",
10423
+ "returns": "this",
10424
+ "description": "Moves focus to the combobox input."
10425
+ },
10426
+ {
10427
+ "name": "locale",
10428
+ "signature": "locale(target, [options])",
10429
+ "returns": "Select",
10430
+ "description": "Creates a locale Select with native/localized names, pinned choices, and optional flags. Values are canonical BCP 47 tags; initial values and `set()` accept underscores and any case."
10431
+ },
10432
+ {
10433
+ "name": "localeItems",
10434
+ "signature": "localeItems(locales, [options])",
10435
+ "returns": "ReturnType<typeof localeItems>",
10436
+ "description": "Builds locale items without the DOM, for lists and summaries using the same names."
10437
+ },
10438
+ {
10439
+ "name": "country",
10440
+ "signature": "country(target, [options])",
10441
+ "returns": "Select",
10442
+ "description": "Creates a country Select with localized names, pinned choices, and optional flags. Search includes the English name, ISO code, and descriptions; initial values and `set()` accept either case."
10443
+ },
10444
+ {
10445
+ "name": "countryItems",
10446
+ "signature": "countryItems([countries], [options])",
10447
+ "returns": "ReturnType<typeof countryItems>",
10448
+ "description": "Builds country items without the DOM, defaulting to the ISO country catalogue."
8900
10449
  },
8901
10450
  {
8902
10451
  "name": "priority",
@@ -9501,9 +11050,9 @@
9501
11050
  },
9502
11051
  {
9503
11052
  "name": "label",
9504
- "type": "string",
9505
- "default": "'Sort by'",
9506
- "description": "Accessible field label and direction-name prefix."
11053
+ "type": "string|null",
11054
+ "default": null,
11055
+ "description": "Accessible field label and direction-name prefix, by default the `sortControl.label` message (\"Sort by\"). Null gives neither."
9507
11056
  },
9508
11057
  {
9509
11058
  "name": "labels",
@@ -9564,6 +11113,67 @@
9564
11113
  }
9565
11114
  ]
9566
11115
  },
11116
+ "SourceList": {
11117
+ "options": [
11118
+ {
11119
+ "name": "sources",
11120
+ "type": "Source[]",
11121
+ "default": "[]",
11122
+ "description": "The sources, in the order an answer's `[n]` citations number them. Model text is data: every string reaches the page as text."
11123
+ },
11124
+ {
11125
+ "name": "label",
11126
+ "type": "string|null",
11127
+ "default": null,
11128
+ "description": "The visible label the list is named by, by default the `sourceList.label` message (\"Sources\"). Empty or null hides it and names the list with that message instead."
11129
+ },
11130
+ {
11131
+ "name": "layout",
11132
+ "type": "'chips'|'list'",
11133
+ "default": "'chips'",
11134
+ "description": "`'chips'` wraps short chips beside the label; `'list'` gives each source a full-width row with its title and site."
11135
+ },
11136
+ {
11137
+ "name": "numbered",
11138
+ "type": "boolean",
11139
+ "default": "true",
11140
+ "description": "Whether each source shows its number."
11141
+ },
11142
+ {
11143
+ "name": "icons",
11144
+ "type": "Partial<Record<SourceKind, string>>",
11145
+ "default": "{}",
11146
+ "description": "Icon names per source kind, over the built-in `SOURCE_ICONS`."
11147
+ },
11148
+ {
11149
+ "name": "msg",
11150
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
11151
+ "default": null,
11152
+ "description": "Localized messages."
11153
+ }
11154
+ ],
11155
+ "events": [
11156
+ {
11157
+ "name": "select",
11158
+ "payload": "{source: Source, n: number}",
11159
+ "description": "Activation listener; `preventDefault()` keeps a web source from opening."
11160
+ }
11161
+ ],
11162
+ "methods": [
11163
+ {
11164
+ "name": "setSources",
11165
+ "signature": "setSources(sources)",
11166
+ "returns": "this",
11167
+ "description": "Replaces every source. Focus on a source stays on the source with the same `id`."
11168
+ },
11169
+ {
11170
+ "name": "highlight",
11171
+ "signature": "highlight(n)",
11172
+ "returns": "this",
11173
+ "description": "Points at one source, as a citation `[n]` in the answer does: scrolls it into view, puts focus on it, and marks it with `data-state=\"highlighted\"` for two seconds. A number is the source's position, from 1; a string is its `id`. Anything else does nothing."
11174
+ }
11175
+ ]
11176
+ },
9567
11177
  "Spinner": {
9568
11178
  "options": [
9569
11179
  {
@@ -9664,9 +11274,9 @@
9664
11274
  },
9665
11275
  {
9666
11276
  "name": "label",
9667
- "type": "string",
9668
- "default": "'Resize panes'",
9669
- "description": "Accessible name of the divider."
11277
+ "type": "string|null",
11278
+ "default": "null",
11279
+ "description": "Accessible name of the divider; null reads the `splitView.resize` message (\"Resize panes\")."
9670
11280
  }
9671
11281
  ],
9672
11282
  "events": [
@@ -10110,6 +11720,201 @@
10110
11720
  }
10111
11721
  ]
10112
11722
  },
11723
+ "Surface": {
11724
+ "options": [
11725
+ {
11726
+ "name": "document",
11727
+ "type": "SurfaceDocument|Record<string, unknown>|null",
11728
+ "default": "null",
11729
+ "description": "A whole surface, as the `show_surface` and `ask_user` tools take it. Leave it out to stream with `apply()` or `write()`."
11730
+ },
11731
+ {
11732
+ "name": "policy",
11733
+ "type": "SurfacePolicy|null",
11734
+ "default": "null",
11735
+ "description": "What each action needs before it replies; every action is allowed when null. Nothing in a surface can lower what it decides."
11736
+ },
11737
+ {
11738
+ "name": "resolve",
11739
+ "type": "SurfaceResolve",
11740
+ "default": "{}",
11741
+ "description": "How records, links and assets are resolved."
11742
+ },
11743
+ {
11744
+ "name": "authors",
11745
+ "type": "Record<string, {name: string}>",
11746
+ "default": "{}",
11747
+ "description": "Who may compose a surface, by the key its `author` names; the byline shows the name, or the key when it is not listed."
11748
+ },
11749
+ {
11750
+ "name": "userInitiated",
11751
+ "type": "boolean",
11752
+ "default": "false",
11753
+ "description": "Whether the surface answers the person's latest message; only then may `openSurface()` honour a request for a sheet or a dialog."
11754
+ },
11755
+ {
11756
+ "name": "headingLevel",
11757
+ "type": "2|3|4|5",
11758
+ "default": "3",
11759
+ "description": "The element level of the surface's title; its `heading` nodes go one and two deeper."
11760
+ },
11761
+ {
11762
+ "name": "locale",
11763
+ "type": "string",
11764
+ "default": null,
11765
+ "description": "Locale for numbers and times."
11766
+ },
11767
+ {
11768
+ "name": "catalog",
11769
+ "type": "SurfaceCatalog",
11770
+ "default": "CATALOG",
11771
+ "description": "A catalog narrowed with `narrowCatalog()`; the full one by default. What lies outside it is refused as unknown."
11772
+ },
11773
+ {
11774
+ "name": "token",
11775
+ "type": "string|null",
11776
+ "default": "null",
11777
+ "description": "The application's opaque string, at most 512 characters, copied unchanged into every reply. A surface cannot set it."
11778
+ },
11779
+ {
11780
+ "name": "reply",
11781
+ "type": "SurfaceReply|null",
11782
+ "default": "null",
11783
+ "description": "A reply the surface already gave, for a surface restored from a stored conversation: it starts as its receipt and replies no more."
11784
+ },
11785
+ {
11786
+ "name": "labelledBy",
11787
+ "type": "string|null",
11788
+ "default": "null",
11789
+ "description": "The id of an element that already shows the title, such as a Dialog's; the surface then draws no title of its own and is labelled by it."
11790
+ },
11791
+ {
11792
+ "name": "chartAdapter",
11793
+ "type": "ChartAdapter|null",
11794
+ "default": "null",
11795
+ "description": "The engine that draws `chart` nodes; without one a chart shows its data table."
11796
+ },
11797
+ {
11798
+ "name": "msg",
11799
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
11800
+ "default": null,
11801
+ "description": "Localized messages."
11802
+ }
11803
+ ],
11804
+ "events": [
11805
+ {
11806
+ "name": "reply",
11807
+ "payload": "{reply: SurfaceReply}",
11808
+ "description": "Reply listener."
11809
+ },
11810
+ {
11811
+ "name": "error",
11812
+ "payload": "{errors: SurfaceError[]}",
11813
+ "description": "Error listener."
11814
+ },
11815
+ {
11816
+ "name": "change",
11817
+ "payload": "{name: string, value: unknown}",
11818
+ "description": "Input listener."
11819
+ },
11820
+ {
11821
+ "name": "ready",
11822
+ "payload": "Record<string, never>",
11823
+ "description": "First-render listener."
11824
+ },
11825
+ {
11826
+ "name": "end",
11827
+ "payload": "Record<string, never>",
11828
+ "description": "End-of-surface listener."
11829
+ }
11830
+ ],
11831
+ "methods": [
11832
+ {
11833
+ "name": "apply",
11834
+ "signature": "apply(op)",
11835
+ "returns": "this",
11836
+ "description": "Applies one operation, as parsed from its line. It is validated against the catalog first: what is invalid is dropped and reported through `error`, and only the valid rest is drawn. Operations for another surface, and any after the surface was answered, are ignored."
11837
+ },
11838
+ {
11839
+ "name": "write",
11840
+ "signature": "write(chunk)",
11841
+ "returns": "this",
11842
+ "description": "Takes a chunk of operation lines, as streamed: every complete line is parsed and applied."
11843
+ },
11844
+ {
11845
+ "name": "end",
11846
+ "signature": "end()",
11847
+ "returns": "this",
11848
+ "description": "Ends the stream: applies a last line without a line break. A surface whose `end` never arrived is reported and keeps its actions disabled; Cancel still replies."
11849
+ },
11850
+ {
11851
+ "name": "getValues",
11852
+ "signature": "getValues()",
11853
+ "returns": "Record<string, unknown>",
11854
+ "description": "The values of the visible inputs by name, as a reply would carry them: JSON, hidden inputs left out. A questionnaire's are `{answers, path}`."
11855
+ },
11856
+ {
11857
+ "name": "getErrors",
11858
+ "signature": "getErrors()",
11859
+ "returns": "SurfaceError[]",
11860
+ "description": "Every problem collected so far, in a shape an application can return to the model."
11861
+ },
11862
+ {
11863
+ "name": "cancel",
11864
+ "signature": "cancel([reason])",
11865
+ "returns": "this",
11866
+ "description": "Closes the surface unanswered: replies `cancel` (`dismiss` for a `show` surface)."
11867
+ },
11868
+ {
11869
+ "name": "supersede",
11870
+ "signature": "supersede()",
11871
+ "returns": "this",
11872
+ "description": "Ends the surface because a newer one takes its place: replies `dismiss` with the reason `superseded`."
11873
+ },
11874
+ {
11875
+ "name": "focus",
11876
+ "signature": "focus()",
11877
+ "returns": "this",
11878
+ "description": "Moves focus to the first control: the first input, else the first enabled action."
11879
+ },
11880
+ {
11881
+ "name": "toDocument",
11882
+ "signature": "toDocument()",
11883
+ "returns": "SurfaceDocument|null",
11884
+ "description": "The surface as it stands, as a document: what was validated, repairs applied and invalid parts dropped. `null` before it began."
11885
+ },
11886
+ {
11887
+ "name": "getReply",
11888
+ "signature": "getReply()",
11889
+ "returns": "SurfaceReply|null",
11890
+ "description": "The reply the surface gave, or `null` while it waits."
11891
+ },
11892
+ {
11893
+ "name": "destroy",
11894
+ "signature": "destroy()",
11895
+ "returns": "void",
11896
+ "description": "Destroys the surface. An unanswered surface replies `dismiss` first, with the reason `destroyed`, so a waiting agent never hangs."
11897
+ }
11898
+ ]
11899
+ },
11900
+ "SurfaceText": {
11901
+ "options": [
11902
+ {
11903
+ "name": "msg",
11904
+ "type": "(key: string, ...args: unknown[]) => string",
11905
+ "default": null,
11906
+ "description": "Resolves a message key; English by default (`SURFACE_MESSAGES`)."
11907
+ },
11908
+ {
11909
+ "name": "entities",
11910
+ "type": "Iterable<string>|null",
11911
+ "default": "null",
11912
+ "description": "The record entities the document may name, as the Surface's `resolve.entities`."
11913
+ }
11914
+ ],
11915
+ "events": [],
11916
+ "methods": []
11917
+ },
10113
11918
  "TabInsert": {
10114
11919
  "options": [
10115
11920
  {
@@ -10274,6 +12079,12 @@
10274
12079
  "default": "false",
10275
12080
  "description": "Number of rows to render at first, with a control that appends the next batch on demand. A result set an ERP query returns happily — tens of thousands of rows — costs more to lay out than anyone will ever scroll through."
10276
12081
  },
12082
+ {
12083
+ "name": "virtual",
12084
+ "type": "boolean",
12085
+ "default": "false",
12086
+ "description": "Windowed rendering: only the rows in view and one viewport of overscan above and below are in the DOM, with spacer rows keeping the scroll height. The table stays one grid over all of its rows, so this implies `interactive`, the header checkbox and Ctrl/Cmd+A take every row, drawn or not, and the row that has focus or is being edited stays drawn wherever it is. It needs a bounded scroll region: give it `height`, or the region stops at the height of the window. Every row takes the height of one measured row, rows of differing height are not supported, and column widths cannot follow content that is not drawn, so `auto` columns share the width evenly. Find-in-page does not see rows that are not drawn. Wins over `growing`."
12087
+ },
10277
12088
  {
10278
12089
  "name": "responsive",
10279
12090
  "type": "false|'sm'|'md'|'lg'|'xl'",
@@ -10689,6 +12500,12 @@
10689
12500
  "returns": "number",
10690
12501
  "description": "How many rows are currently rendered."
10691
12502
  },
12503
+ {
12504
+ "name": "reveal",
12505
+ "signature": "reveal(id)",
12506
+ "returns": "boolean",
12507
+ "description": "Scrolls a row into view. A windowed table draws it first, so a row that is not in the DOM can be reached by id; rows outside the data, in a collapsed branch, or held back by `growing` cannot."
12508
+ },
10692
12509
  {
10693
12510
  "name": "addEventListener",
10694
12511
  "signature": "addEventListener(type, listener, [options])",
@@ -11370,9 +13187,9 @@
11370
13187
  },
11371
13188
  {
11372
13189
  "name": "label",
11373
- "type": "string",
11374
- "default": "'Toolbar'",
11375
- "description": "Accessible name of the toolbar."
13190
+ "type": "string|null",
13191
+ "default": null,
13192
+ "description": "Accessible name of the toolbar, by default the `toolbar.label` message (\"Toolbar\"). Null gives none."
11376
13193
  },
11377
13194
  {
11378
13195
  "name": "overflow",
@@ -11382,9 +13199,9 @@
11382
13199
  },
11383
13200
  {
11384
13201
  "name": "overflowLabel",
11385
- "type": "string",
11386
- "default": "'More'",
11387
- "description": "Accessible name of the overflow menu trigger."
13202
+ "type": "string|null",
13203
+ "default": null,
13204
+ "description": "Accessible name of the overflow menu trigger, by default the `toolbar.more` message (\"More\"). Null gives none."
11388
13205
  },
11389
13206
  {
11390
13207
  "name": "dense",
@@ -11641,9 +13458,9 @@
11641
13458
  },
11642
13459
  {
11643
13460
  "name": "moreLabel",
11644
- "type": "string",
11645
- "default": "'More actions'",
11646
- "description": "Name of a row's overflow menu; every action name is followed by the row's name (\"More actions: Q3 plan\")."
13461
+ "type": "string|null",
13462
+ "default": "null",
13463
+ "description": "Name of a row's overflow menu; every action name is followed by the row's name (\"More actions: Q3 plan\"). Null reads the `tree.more` message."
11647
13464
  },
11648
13465
  {
11649
13466
  "name": "load",
@@ -11659,15 +13476,15 @@
11659
13476
  },
11660
13477
  {
11661
13478
  "name": "label",
11662
- "type": "string",
11663
- "default": "'Tree'",
11664
- "description": "Accessible name of the tree."
13479
+ "type": "string|null",
13480
+ "default": "null",
13481
+ "description": "Accessible name of the tree; null reads the `tree.label` message (\"Tree\")."
11665
13482
  },
11666
13483
  {
11667
13484
  "name": "emptyText",
11668
- "type": "string",
11669
- "default": "'Nothing to show'",
11670
- "description": "Text shown when the tree is empty."
13485
+ "type": "string|null",
13486
+ "default": null,
13487
+ "description": "Text shown when the tree is empty, by default the `tree.noItems` message (\"Nothing to show\"). Null shows none."
11671
13488
  },
11672
13489
  {
11673
13490
  "name": "height",
@@ -11855,6 +13672,68 @@
11855
13672
  "events": [],
11856
13673
  "methods": []
11857
13674
  },
13675
+ "UiMessageStream": {
13676
+ "options": [
13677
+ {
13678
+ "name": "runStatus",
13679
+ "type": "RunStatus|null",
13680
+ "default": "null",
13681
+ "description": "A run status to keep up to date."
13682
+ },
13683
+ {
13684
+ "name": "authors",
13685
+ "type": "Record<string, Author>",
13686
+ "default": "{}",
13687
+ "description": "Who writes; its first author who is not a person is the agent when `agent` is not given."
13688
+ },
13689
+ {
13690
+ "name": "agent",
13691
+ "type": "string|null",
13692
+ "default": "null",
13693
+ "description": "Author key of the assistant's output."
13694
+ },
13695
+ {
13696
+ "name": "tools",
13697
+ "type": "Record<string, (call: ToolCall) => ThreadItem|null>",
13698
+ "default": "{}",
13699
+ "description": "Tiles by tool name: the application's renderer for a tool's calls, called at each status change. Its item joins the thread as `tool:<toolCallId>`, and the call's step links to it."
13700
+ },
13701
+ {
13702
+ "name": "showReasoning",
13703
+ "type": "boolean",
13704
+ "default": "false",
13705
+ "description": "Shows the model's reasoning text. Without it the text is not kept, and the reasoning is one step that says how long it took."
13706
+ }
13707
+ ],
13708
+ "events": [
13709
+ {
13710
+ "name": "approval",
13711
+ "payload": null,
13712
+ "description": "The person decided. The application sends the answer with its next request."
13713
+ },
13714
+ {
13715
+ "name": "data",
13716
+ "payload": null,
13717
+ "description": "A `data-<name>` part. With an `id` it replaces the earlier value of that name and id. What went out here stays with the application: a `reset-step` takes back what was drawn, not what was delivered."
13718
+ },
13719
+ {
13720
+ "name": "metadata",
13721
+ "payload": null,
13722
+ "description": "Metadata of the message."
13723
+ },
13724
+ {
13725
+ "name": "unknown",
13726
+ "payload": null,
13727
+ "description": "A part the adapter does not draw."
13728
+ },
13729
+ {
13730
+ "name": "error",
13731
+ "payload": null,
13732
+ "description": "A part out of order, or a tile that failed."
13733
+ }
13734
+ ],
13735
+ "methods": []
13736
+ },
11858
13737
  "UploadTransport": {
11859
13738
  "options": [
11860
13739
  {
@@ -11897,6 +13776,18 @@
11897
13776
  "events": [],
11898
13777
  "methods": []
11899
13778
  },
13779
+ "Upsert": {
13780
+ "options": [
13781
+ {
13782
+ "name": "after",
13783
+ "type": "string|null",
13784
+ "default": "null",
13785
+ "description": "The id of the item to insert the new item right after; the end of the thread when null or unknown. An item already in the thread stays where it is."
13786
+ }
13787
+ ],
13788
+ "events": [],
13789
+ "methods": []
13790
+ },
11900
13791
  "ValueList": {
11901
13792
  "options": [
11902
13793
  {