@zeyos/zx 5.6.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 (215) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +73 -7
  3. package/bin/zx-css.js +328 -0
  4. package/dist/types/components/account-menu/account-menu.d.ts +4 -2
  5. package/dist/types/components/activity-list/activity-list.d.ts +14 -8
  6. package/dist/types/components/agent-thread/ag-ui.d.ts +340 -0
  7. package/dist/types/components/agent-thread/agent-thread.d.ts +142 -14
  8. package/dist/types/components/agent-thread/ui-message-stream.d.ts +401 -0
  9. package/dist/types/components/app-sidebar/app-sidebar.d.ts +14 -8
  10. package/dist/types/components/breadcrumb/breadcrumb.d.ts +3 -3
  11. package/dist/types/components/calendar/calendar-model.d.ts +9 -2
  12. package/dist/types/components/calendar/calendar.d.ts +12 -4
  13. package/dist/types/components/chart/chart.d.ts +25 -13
  14. package/dist/types/components/code-editor/code-editor.d.ts +7 -2
  15. package/dist/types/components/composer/composer.d.ts +206 -4
  16. package/dist/types/components/composer/queue.d.ts +76 -0
  17. package/dist/types/components/copy/copy-button.d.ts +6 -4
  18. package/dist/types/components/copy/copy-input.d.ts +10 -6
  19. package/dist/types/components/datebox/date-range-box.d.ts +33 -0
  20. package/dist/types/components/datebox/placeholder.d.ts +7 -0
  21. package/dist/types/components/dock/dock.d.ts +12 -3
  22. package/dist/types/components/entity-ref/entity-ref.d.ts +5 -3
  23. package/dist/types/components/field-upload/field-upload.d.ts +3 -2
  24. package/dist/types/components/file-item/file-item.d.ts +3 -2
  25. package/dist/types/components/file-list/file-list.d.ts +14 -8
  26. package/dist/types/components/filter/filter-model.d.ts +31 -1
  27. package/dist/types/components/filter/filter.d.ts +20 -2
  28. package/dist/types/components/finder/finder.d.ts +14 -6
  29. package/dist/types/components/flag/flag.d.ts +99 -0
  30. package/dist/types/components/grid/grid.d.ts +1 -1
  31. package/dist/types/components/kanban-view/kanban-view.d.ts +8 -66
  32. package/dist/types/components/launcher/launcher.d.ts +2 -0
  33. package/dist/types/components/multi-value-editor/multi-value-editor.d.ts +3 -2
  34. package/dist/types/components/number-field/number-field.d.ts +17 -6
  35. package/dist/types/components/prompt-starters/prompt-starters.d.ts +107 -0
  36. package/dist/types/components/prose/prose.d.ts +9 -6
  37. package/dist/types/components/questionnaire/conditions.d.ts +270 -0
  38. package/dist/types/components/questionnaire/items.d.ts +52 -30
  39. package/dist/types/components/questionnaire/questionnaire.d.ts +44 -4
  40. package/dist/types/components/rating/rating.d.ts +5 -3
  41. package/dist/types/components/select/country.d.ts +106 -0
  42. package/dist/types/components/select/field-adapter.d.ts +2 -1
  43. package/dist/types/components/select/locale.d.ts +102 -0
  44. package/dist/types/components/select/select.d.ts +41 -2
  45. package/dist/types/components/slider/slider.d.ts +1 -0
  46. package/dist/types/components/sort-control/sort-control.d.ts +7 -3
  47. package/dist/types/components/source-list/source-list.d.ts +7 -5
  48. package/dist/types/components/split-view/split-view.d.ts +5 -3
  49. package/dist/types/components/surface/catalog.d.ts +260 -0
  50. package/dist/types/components/surface/elicit.d.ts +81 -0
  51. package/dist/types/components/surface/mcp.d.ts +165 -0
  52. package/dist/types/components/surface/schema.d.ts +314 -0
  53. package/dist/types/components/surface/stream.d.ts +118 -0
  54. package/dist/types/components/surface/surface.d.ts +718 -0
  55. package/dist/types/components/surface/text.d.ts +277 -0
  56. package/dist/types/components/surface/validate.d.ts +339 -0
  57. package/dist/types/components/table/table.d.ts +55 -3
  58. package/dist/types/components/table/window.d.ts +203 -0
  59. package/dist/types/components/toolbar/toolbar.d.ts +10 -6
  60. package/dist/types/components/tooltip/tooltip.d.ts +2 -2
  61. package/dist/types/components/tree/tree.d.ts +20 -13
  62. package/dist/types/core/component.d.ts +10 -0
  63. package/dist/types/core/date.d.ts +8 -1
  64. package/dist/types/core/dom.d.ts +1 -0
  65. package/dist/types/core/http.d.ts +10 -0
  66. package/dist/types/core/i18n.d.ts +38 -0
  67. package/dist/types/core/messages.d.ts +344 -1
  68. package/dist/types/core/storage.d.ts +7 -2
  69. package/dist/types/elements/define.d.ts +21 -46
  70. package/dist/types/elements/definitions.d.ts +147 -0
  71. package/dist/types/elements/kit.d.ts +7 -0
  72. package/dist/types/elements/reflect.d.ts +6 -3
  73. package/dist/types/index.d.ts +10 -1
  74. package/dist/types/internal/date-locale.d.ts +7 -0
  75. package/dist/types/internal/json-patch.d.ts +146 -0
  76. package/dist/types/locales/de.d.ts +13 -0
  77. package/dist/types/locales/en.d.ts +2 -0
  78. package/dist/types/locales/index.d.ts +823 -0
  79. package/dist/types/zeyos/view.d.ts +8 -1
  80. package/dist/zx-zeyos.esm.js +16802 -15180
  81. package/dist/zx-zeyos.esm.min.js +5 -5
  82. package/dist/zx.core.css +1276 -0
  83. package/dist/zx.core.min.css +1 -0
  84. package/dist/zx.css +498 -134
  85. package/dist/zx.esm.js +40778 -29654
  86. package/dist/zx.esm.min.js +36 -23
  87. package/dist/zx.global.js +40778 -29654
  88. package/dist/zx.global.min.js +36 -23
  89. package/dist/zx.layered.css +17302 -0
  90. package/dist/zx.layered.min.css +1 -0
  91. package/dist/zx.min.css +1 -1
  92. package/docs/agent-catalog.json +12501 -0
  93. package/docs/agent-surfaces.md +340 -0
  94. package/docs/api.json +851 -121
  95. package/docs/llms.md +1018 -71
  96. package/docs/llms.txt +30 -9
  97. package/package.json +29 -6
  98. package/src/components/account-menu/account-menu.js +6 -3
  99. package/src/components/activity-item/activity-item.js +2 -1
  100. package/src/components/activity-list/activity-list.js +16 -10
  101. package/src/components/agent-thread/ag-ui.js +1439 -0
  102. package/src/components/agent-thread/agent-thread.js +359 -54
  103. package/src/components/agent-thread/ui-message-stream.js +1281 -0
  104. package/src/components/app-sidebar/app-sidebar.js +18 -8
  105. package/src/components/approval-card/approval-card.js +3 -2
  106. package/src/components/block-view/block-view.js +7 -6
  107. package/src/components/breadcrumb/breadcrumb.js +8 -5
  108. package/src/components/calendar/calendar-model.js +8 -2
  109. package/src/components/calendar/calendar.js +53 -18
  110. package/src/components/chart/chart.js +54 -23
  111. package/src/components/code-editor/code-editor.js +45 -8
  112. package/src/components/code-editor/field-adapter.js +1 -1
  113. package/src/components/composer/composer.css +80 -1
  114. package/src/components/composer/composer.js +390 -16
  115. package/src/components/composer/queue.js +78 -0
  116. package/src/components/context-menu/context-menu.js +12 -1
  117. package/src/components/copy/copy-button.js +9 -7
  118. package/src/components/copy/copy-input.js +10 -6
  119. package/src/components/date-picker/date-picker.js +2 -1
  120. package/src/components/date-picker/date-range-picker.js +8 -7
  121. package/src/components/datebox/date-range-box.js +3 -9
  122. package/src/components/datebox/datebox.js +18 -21
  123. package/src/components/datebox/placeholder.js +18 -0
  124. package/src/components/dialog/dialog.js +1 -1
  125. package/src/components/dock/dock.js +34 -13
  126. package/src/components/entity-ref/entity-ref.js +16 -5
  127. package/src/components/field-upload/field-upload.js +81 -38
  128. package/src/components/file-item/file-item.js +70 -40
  129. package/src/components/file-list/file-list.js +15 -9
  130. package/src/components/filter/filter-model.js +46 -8
  131. package/src/components/filter/filter.css +3 -3
  132. package/src/components/filter/filter.js +29 -10
  133. package/src/components/filter-panel/filter-panel.js +13 -5
  134. package/src/components/finder/finder.js +50 -26
  135. package/src/components/flag/flag.css +40 -0
  136. package/src/components/flag/flag.js +177 -0
  137. package/src/components/form/form.js +1 -1
  138. package/src/components/grid/grid.js +22 -8
  139. package/src/components/kanban-view/kanban-view.js +51 -81
  140. package/src/components/launcher/launcher.js +17 -2
  141. package/src/components/list-toolbar/list-toolbar.js +2 -1
  142. package/src/components/master-panel/master-panel.js +1 -1
  143. package/src/components/menu-button/menu-button.js +4 -0
  144. package/src/components/message/message.js +3 -0
  145. package/src/components/multi-value-editor/multi-value-editor.js +10 -9
  146. package/src/components/navigation-bar/navigation-bar.js +3 -3
  147. package/src/components/number-field/number-field.js +29 -13
  148. package/src/components/prompt-starters/prompt-starters.css +91 -0
  149. package/src/components/prompt-starters/prompt-starters.js +206 -0
  150. package/src/components/prose/prose.js +14 -10
  151. package/src/components/questionnaire/conditions.js +666 -0
  152. package/src/components/questionnaire/items.js +150 -41
  153. package/src/components/questionnaire/questionnaire.js +126 -32
  154. package/src/components/rating/rating.js +5 -4
  155. package/src/components/run-status/run-status.js +2 -2
  156. package/src/components/select/country.js +136 -0
  157. package/src/components/select/field-adapter.js +7 -2
  158. package/src/components/select/locale.js +219 -0
  159. package/src/components/select/select.css +20 -22
  160. package/src/components/select/select.js +94 -12
  161. package/src/components/sheet/sheet-stack.js +10 -1
  162. package/src/components/slider/slider.js +7 -2
  163. package/src/components/sort-control/sort-control.js +15 -5
  164. package/src/components/source-list/source-list.js +7 -4
  165. package/src/components/split-view/split-view.js +5 -3
  166. package/src/components/surface/catalog.js +1334 -0
  167. package/src/components/surface/elicit.js +107 -0
  168. package/src/components/surface/mcp.js +243 -0
  169. package/src/components/surface/schema.js +644 -0
  170. package/src/components/surface/stream.js +245 -0
  171. package/src/components/surface/surface.css +308 -0
  172. package/src/components/surface/surface.js +2291 -0
  173. package/src/components/surface/text.js +513 -0
  174. package/src/components/surface/validate.js +2218 -0
  175. package/src/components/tabbox/tabbox.js +9 -0
  176. package/src/components/table/table.css +63 -3
  177. package/src/components/table/table.js +167 -28
  178. package/src/components/table/window.js +317 -0
  179. package/src/components/toolbar/toolbar.js +12 -7
  180. package/src/components/tooltip/tooltip.css +2 -3
  181. package/src/components/tooltip/tooltip.js +32 -5
  182. package/src/components/tree/tree.js +53 -23
  183. package/src/core/component.js +25 -1
  184. package/src/core/date.js +62 -16
  185. package/src/core/dom.js +22 -2
  186. package/src/core/format.js +15 -13
  187. package/src/core/http.js +29 -20
  188. package/src/core/i18n.js +83 -10
  189. package/src/core/keyboard.js +79 -8
  190. package/src/core/messages.js +376 -2
  191. package/src/core/overlay-host.js +1 -0
  192. package/src/core/storage.js +59 -6
  193. package/src/elements/define.js +178 -130
  194. package/src/elements/definitions.js +229 -0
  195. package/src/elements/kit.js +444 -0
  196. package/src/elements/reflect.js +8 -3
  197. package/src/index.js +10 -1
  198. package/src/internal/date-locale.js +11 -0
  199. package/src/internal/json-patch.js +405 -0
  200. package/src/locales/de.js +911 -0
  201. package/src/locales/en.js +2 -0
  202. package/src/locales/index.js +7 -0
  203. package/src/zeyos/calendar.js +2 -1
  204. package/src/zeyos/form.js +2 -1
  205. package/src/zeyos/launcher.js +7 -6
  206. package/src/zeyos/module-bar.js +2 -1
  207. package/src/zeyos/schema.js +37 -23
  208. package/src/zeyos/select.js +4 -3
  209. package/src/zeyos/table.js +2 -13
  210. package/src/zeyos/view.js +57 -17
  211. package/styles/core.css +11 -0
  212. package/styles/tokens/semantic.css +1 -0
  213. package/styles/zeyos.css +2 -0
  214. package/styles/zx.css +4 -8
  215. package/styles/zx.layered.css +1 -0
@@ -3,12 +3,54 @@ import { ApprovalCard } from '../approval-card/approval-card.js';
3
3
  import { BlockView } from '../block-view/block-view.js';
4
4
  import { RunTrace } from '../run-trace/run-trace.js';
5
5
  import { SourceList } from '../source-list/source-list.js';
6
+ import { Surface } from '../surface/surface.js';
6
7
  export type ThreadItem = import('../../internal/agent-model.js').ThreadItem;
7
8
  export type Author = import('../../internal/agent-model.js').Author;
8
9
  export type Source = import('../../internal/agent-model.js').Source;
9
10
  export type Block = import('../../internal/agent-model.js').Block;
10
11
  export type EmptyStateOptions = import('../empty-state/empty-state.js').EmptyStateOptions;
11
12
  export type AnswerAction = 'copy' | 'regenerate' | 'branch' | 'rate';
13
+ export type SurfaceOptions = import('../surface/surface.js').SurfaceOptions;
14
+ export type SurfaceReply = import('../surface/text.js').SurfaceReply;
15
+ export type PlaceholderItem = {
16
+ id: string;
17
+ type: 'zx-placeholder';
18
+ at?: string;
19
+ author?: string;
20
+ /**
21
+ * Skeleton lines.
22
+ */
23
+ lines?: number;
24
+ };
25
+ export type UpsertOptions = {
26
+ /**
27
+ * The id of the item to insert the new item right after;
28
+ * the end of the thread when null or unknown. An item already in the thread stays where it is.
29
+ */
30
+ after?: string | null;
31
+ };
32
+ export type SurfaceItem = {
33
+ id: string;
34
+ type: 'surface';
35
+ at?: string;
36
+ author?: string;
37
+ /**
38
+ * The whole surface.
39
+ */
40
+ document?: import('../surface/validate.js').SurfaceDocument | null;
41
+ /**
42
+ * The application's token, copied into the reply.
43
+ */
44
+ token?: string | null;
45
+ /**
46
+ * A narrowed catalog.
47
+ */
48
+ catalog?: import('../surface/catalog.js').SurfaceCatalog;
49
+ /**
50
+ * The reply it gave; the surface is drawn as its receipt.
51
+ */
52
+ reply?: SurfaceReply | null;
53
+ };
12
54
  export type ThreadRenderContext = {
13
55
  /**
14
56
  * The thread drawing the item.
@@ -101,6 +143,12 @@ export type AgentThreadOptions = {
101
143
  * Locale for times.
102
144
  */
103
145
  locale?: string;
146
+ /**
147
+ * Options
148
+ * handed to every Surface the thread draws: the application's `policy`, `resolve`, `chartAdapter`
149
+ * and `msg`. Its authors, heading level and locale are the thread's unless given here.
150
+ */
151
+ surfaceOptions?: Omit<SurfaceOptions, 'document' | 'token' | 'catalog' | 'reply'>;
104
152
  /**
105
153
  * Localized messages.
106
154
  */
@@ -113,6 +161,13 @@ export type AgentThreadOptions = {
113
161
  action: string;
114
162
  value?: unknown;
115
163
  }>) => void;
164
+ /**
165
+ * Surface reply listener.
166
+ */
167
+ onreply?: (event: CustomEvent<{
168
+ item: ThreadItem;
169
+ reply: SurfaceReply;
170
+ }>) => void;
116
171
  /**
117
172
  * Approval listener.
118
173
  */
@@ -192,6 +247,10 @@ export type ThreadEntry = {
192
247
  * An approval.
193
248
  */
194
249
  card: ApprovalCard | null;
250
+ /**
251
+ * A surface.
252
+ */
253
+ surface?: Surface | null;
195
254
  };
196
255
  /**
197
256
  * A conversation with one or more agents: the person's messages, the agents' answers as they
@@ -212,6 +271,7 @@ export type ThreadEntry = {
212
271
  * @fires AgentThread#artifact
213
272
  * @fires AgentThread#reveal
214
273
  * @fires AgentThread#open
274
+ * @fires AgentThread#reply
215
275
  * @extends {Component<AgentThreadOptions>}
216
276
  */
217
277
  export declare class AgentThread extends Component<AgentThreadOptions> {
@@ -223,8 +283,12 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
223
283
  /** @type {string[]} */
224
284
  _order: string[];
225
285
  _announceTimer: number;
286
+ _askingPerson: boolean;
226
287
  /** @type {Element|null} */
227
288
  _scrollHost: Element | null;
289
+ /** @type {EventTarget|null} */
290
+ _scrollTarget: EventTarget | null;
291
+ _onScroll: () => void;
228
292
  /** @type {string|null} */
229
293
  _latestAnswer: string | null;
230
294
  /** @type {Map<string, {expanded?: boolean|null, controls?: string|null}>} Artifact open states, for answers drawn later. */
@@ -232,6 +296,8 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
232
296
  expanded?: boolean | null;
233
297
  controls?: string | null;
234
298
  }>;
299
+ /** @type {WeakSet<Surface>} Surfaces answered elsewhere, whose going is no reply. */
300
+ _answeredElsewhere: WeakSet<Surface>;
235
301
  _feed: HTMLElement;
236
302
  _empty: HTMLElement;
237
303
  _latestButton: HTMLButtonElement;
@@ -241,15 +307,17 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
241
307
  /** @type {Readonly<AgentThreadOptions>} */
242
308
  static defaults: Readonly<AgentThreadOptions>;
243
309
  /**
244
- * Registers how items of another type are drawn — an application's own, or a surface. A
245
- * built-in type cannot be replaced.
310
+ * Registers how items of another type are drawn. An application's own renderer for `surface`
311
+ * replaces the library's drawing of that type; the types the library always draws cannot be
312
+ * replaced.
246
313
  * @param {string} type Item type.
247
314
  * @param {ThreadItemRenderer} render Draws the item's content.
248
315
  * @returns {typeof AgentThread}
249
316
  */
250
317
  static register(type: string, render: ThreadItemRenderer): typeof AgentThread;
251
318
  /**
252
- * Reports whether a type has a registered renderer.
319
+ * Reports whether a type has a registered renderer. `surface` answers false until an
320
+ * application registers its own, so a guarded `register()` still takes effect.
253
321
  * @param {string} type
254
322
  * @returns {boolean}
255
323
  */
@@ -257,21 +325,25 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
257
325
  /** @returns {HTMLElement} */
258
326
  render(): HTMLElement;
259
327
  /**
260
- * Replaces the conversation.
328
+ * Replaces the conversation. Everything is dropped and then drawn anew, except a surface already
329
+ * drawn, which stays so that one still matching keeps answering.
261
330
  * @param {ThreadItem[]} items
262
331
  * @returns {this}
263
332
  */
264
333
  setItems(items: ThreadItem[]): this;
265
334
  /**
266
- * Adds an item, or replaces the item with the same id where it stands.
335
+ * Adds an item, or replaces the item with the same id where it stands. A new item goes at the
336
+ * end, or right after the item `options.after` names.
267
337
  * @param {ThreadItem} item
338
+ * @param {UpsertOptions} [options]
268
339
  * @returns {this}
269
340
  */
270
- upsert(item: ThreadItem): this;
341
+ upsert(item: ThreadItem, options?: UpsertOptions): this;
271
342
  /**
272
- * Changes part of an item. The common changes are made in place — an answer finishing or
273
- * stopping, a trace's steps, an approval's status — so focus and selection inside the item
274
- * survive; anything else redraws the item.
343
+ * Changes part of an item. The common changes are made in place — an answer finishing, stopping
344
+ * or writing on, a trace's steps, an approval's status — so what the reader opened, and focus and
345
+ * selection where the blocks stay, survive; anything else redraws the item. Metadata patches
346
+ * retain an answer's live blocks; explicit `blocks` or `versions` remain authoritative.
275
347
  * @param {string} id
276
348
  * @param {Record<string, unknown>} partial
277
349
  * @returns {this}
@@ -301,7 +373,8 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
301
373
  */
302
374
  announce(text: string): this;
303
375
  /**
304
- * Removes an item.
376
+ * Removes an item. Focus inside it moves to the item above, or the one below when it was the
377
+ * first, so that a keyboard user is not thrown back to the top of the page.
305
378
  * @param {string} id
306
379
  * @returns {this}
307
380
  */
@@ -321,9 +394,17 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
321
394
  * @returns {Component|null}
322
395
  */
323
396
  getComponent(id: string): Component | null;
397
+ /**
398
+ * The Surface drawn for a `surface` item, to stream its operations into with `apply()` or
399
+ * `write()`.
400
+ * @param {string} id
401
+ * @returns {Surface|null}
402
+ */
403
+ surface(id: string): Surface | null;
324
404
  /**
325
405
  * Brings something into view and moves focus to it: `item:<id>` an item, `step:<id>` a trace
326
- * step (in whichever trace holds it), `source:<n>` a source of the latest answer that has one.
406
+ * step (in whichever trace holds it), `source:<n>` a source of the latest answer that has one,
407
+ * `source:<n>:<id>` a source in the list of the answer `id`.
327
408
  * @param {string} target
328
409
  * @returns {boolean} Whether the target was found.
329
410
  */
@@ -349,7 +430,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
349
430
  /**
350
431
  * @private
351
432
  * @param {ThreadItem} item
352
- * @param {{announce?: boolean}} [options]
433
+ * @param {{announce?: boolean, after?: string|null}} [options]
353
434
  * @returns {void}
354
435
  */
355
436
  private _add;
@@ -360,6 +441,14 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
360
441
  * @returns {void}
361
442
  */
362
443
  private _replace;
444
+ /**
445
+ * Puts the feed in the order given, moving only what stands elsewhere. Anything a listener added
446
+ * meanwhile stays, after what was asked for.
447
+ * @private
448
+ * @param {string[]} ids
449
+ * @returns {void}
450
+ */
451
+ private _arrange;
363
452
  /** @private @param {string} id @returns {void} */
364
453
  private _drop;
365
454
  /**
@@ -382,6 +471,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
382
471
  * Draws one item into its article.
383
472
  * @private
384
473
  * @param {ThreadItem} item
474
+ * @param {Surface|null} [surface=null] A surface to keep rather than draw anew.
385
475
  * @returns {ThreadEntry}
386
476
  */
387
477
  private _build;
@@ -454,6 +544,16 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
454
544
  * @returns {void}
455
545
  */
456
546
  private _buildApproval;
547
+ /**
548
+ * A surface item: the Surface, its reply re-emitted as the thread's `reply` and kept on the item.
549
+ * @private
550
+ * @param {ThreadEntry} entry
551
+ * @param {HTMLElement} body
552
+ * @param {<T extends Component>(component: T) => T} own
553
+ * @param {Surface|null} kept A surface carried over from the item's earlier drawing.
554
+ * @returns {void}
555
+ */
556
+ private _buildSurface;
457
557
  /**
458
558
  * The author's avatar, beside the byline and the content. Decorative: the byline names them.
459
559
  * @private
@@ -485,6 +585,25 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
485
585
  private _time;
486
586
  /** @private @param {Extract<ThreadItem, {type: 'answer'}>} answer @returns {number} */
487
587
  private _versionIndex;
588
+ /**
589
+ * An answer with versions shows its chosen version, so what changes in it belongs there too: the
590
+ * item's own fields are only what it would show without them.
591
+ * @private
592
+ * @template {ThreadItem} T
593
+ * @param {T} item
594
+ * @param {Record<string, unknown>} partial What changed.
595
+ * @returns {T}
596
+ */
597
+ private _intoVersion;
598
+ /**
599
+ * Streamed text lives in the view, so an answer drawn anew from the same versions takes it along
600
+ * into the version it was streamed into.
601
+ * @private
602
+ * @param {ThreadEntry} old
603
+ * @param {ThreadItem} item
604
+ * @returns {ThreadItem}
605
+ */
606
+ private _keepStreamed;
488
607
  /**
489
608
  * The blocks, sources, and steps an answer shows: its chosen version's when it has several.
490
609
  * @private
@@ -509,9 +628,11 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
509
628
  private _announceItem;
510
629
  /**
511
630
  * Says a milestone once. The region is cleared first so the same words said twice are heard
512
- * twice.
631
+ * twice. Words still waiting to be said give way only to words that must be heard: what asks
632
+ * something of the person is not overtaken by what has just finished.
513
633
  * @private
514
634
  * @param {string} text
635
+ * @param {boolean} [urgent=false] Whether it must be heard.
515
636
  * @returns {void}
516
637
  */
517
638
  private _announce;
@@ -532,7 +653,7 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
532
653
  private _onClick;
533
654
  /**
534
655
  * APG feed keys: PageDown and PageUp move between articles; Ctrl+End and Ctrl+Home move focus
535
- * past the end or before the start of the feed.
656
+ * past the end or before the start of the feed. A control inside an item keeps them.
536
657
  * @private
537
658
  * @param {KeyboardEvent} event
538
659
  * @returns {void}
@@ -581,3 +702,10 @@ export declare class AgentThread extends Component<AgentThreadOptions> {
581
702
  * @event AgentThread#open
582
703
  * @type {CustomEvent<{item: ThreadItem, ref: import('../../internal/agent-model.js').ItemRef, step?: import('../../internal/agent-model.js').TraceStep}>}
583
704
  */
705
+ /**
706
+ * A surface in the thread replied: its one reply, with the item as it now stands. Also sent when
707
+ * an unanswered surface is superseded by a new one under the same id, removed, or destroyed with
708
+ * the thread.
709
+ * @event AgentThread#reply
710
+ * @type {CustomEvent<{item: ThreadItem, reply: SurfaceReply}>}
711
+ */
@@ -0,0 +1,401 @@
1
+ export type AgentThread = import('./agent-thread.js').AgentThread;
2
+ export type BlockView = import('../block-view/block-view.js').BlockView;
3
+ export type RunStatus = import('../run-status/run-status.js').RunStatus;
4
+ export type Author = import('../../internal/agent-model.js').Author;
5
+ export type Block = import('../../internal/agent-model.js').Block;
6
+ export type RunState = import('../../internal/agent-model.js').RunState;
7
+ export type Source = import('../../internal/agent-model.js').Source;
8
+ export type ThreadItem = import('../../internal/agent-model.js').ThreadItem;
9
+ export type TraceStep = import('../../internal/agent-model.js').TraceStep;
10
+ /** @typedef {import('./agent-thread.js').AgentThread} AgentThread */
11
+ /** @typedef {import('../block-view/block-view.js').BlockView} BlockView */
12
+ /** @typedef {import('../run-status/run-status.js').RunStatus} RunStatus */
13
+ /** @typedef {import('../../internal/agent-model.js').Author} Author */
14
+ /** @typedef {import('../../internal/agent-model.js').Block} Block */
15
+ /** @typedef {import('../../internal/agent-model.js').RunState} RunState */
16
+ /** @typedef {import('../../internal/agent-model.js').Source} Source */
17
+ /** @typedef {import('../../internal/agent-model.js').ThreadItem} ThreadItem */
18
+ /** @typedef {import('../../internal/agent-model.js').TraceStep} TraceStep */
19
+ /**
20
+ * The version of the UI message stream this adapter implements: the value of the response header
21
+ * `x-vercel-ai-ui-message-stream`.
22
+ */
23
+ export declare const UI_MESSAGE_STREAM_VERSION = "v1";
24
+ export type UiMessagePart = {
25
+ type: string;
26
+ [key: string]: any;
27
+ };
28
+ export type ToolCall = {
29
+ /**
30
+ * The tool call id.
31
+ */
32
+ id: string;
33
+ /**
34
+ * The tool's name.
35
+ */
36
+ name: string;
37
+ /**
38
+ * The input once it is complete; `null` before.
39
+ */
40
+ args: unknown;
41
+ /**
42
+ * The input as text; empty until it is complete when it was not
43
+ * streamed.
44
+ */
45
+ argsText: string;
46
+ /**
47
+ * What the tool returned.
48
+ */
49
+ result?: unknown;
50
+ /**
51
+ * Why the call failed.
52
+ */
53
+ error?: string;
54
+ /**
55
+ * `queued` while the input arrives, `waiting` for an approval, `running`
56
+ * until the result, then `done`, `failed`, `skipped` when it was denied, or `stopped`.
57
+ */
58
+ status: RunState;
59
+ };
60
+ export type UiMessageStreamOptions = {
61
+ /**
62
+ * A run status to keep up to date.
63
+ */
64
+ runStatus?: RunStatus | null;
65
+ /**
66
+ * Who writes; its first author who is not a person
67
+ * is the agent when `agent` is not given.
68
+ */
69
+ authors?: Record<string, Author>;
70
+ /**
71
+ * Author key of the assistant's output.
72
+ */
73
+ agent?: string | null;
74
+ /**
75
+ * Tiles by tool name: the
76
+ * application's renderer for a tool's calls, called at each status change. Its item joins the
77
+ * thread as `tool:<toolCallId>`, and the call's step links to it.
78
+ */
79
+ tools?: Record<string, (call: ToolCall) => ThreadItem | null>;
80
+ /**
81
+ * The
82
+ * person decided. The application sends the answer with its next request.
83
+ */
84
+ onapproval?: (approvalId: string, approved: boolean, reason?: string) => void;
85
+ /**
86
+ * A `data-<name>` part. With
87
+ * an `id` it replaces the earlier value of that name and id. What went out here stays with the
88
+ * application: a `reset-step` takes back what was drawn, not what was delivered.
89
+ */
90
+ ondata?: (name: string, data: unknown, id?: string) => void;
91
+ /**
92
+ * Metadata of the message.
93
+ */
94
+ onmetadata?: (metadata: unknown) => void;
95
+ /**
96
+ * A part the adapter does not draw.
97
+ */
98
+ onunknown?: (part: UiMessagePart) => void;
99
+ /**
100
+ * A part out of order, or a tile that failed.
101
+ */
102
+ onerror?: (error: Error) => void;
103
+ /**
104
+ * Shows the model's reasoning text. Without it the text
105
+ * is not kept, and the reasoning is one step that says how long it took.
106
+ */
107
+ showReasoning?: boolean;
108
+ };
109
+ export type UiMessageStreamConnection = {
110
+ /**
111
+ * Takes the next part of the stream.
112
+ */
113
+ handle: (part: UiMessagePart) => void;
114
+ /**
115
+ * Says that the stream is about to be fed again from
116
+ * the `start` of the response it was reading, after a reconnect that returns the whole response:
117
+ * only the application knows that it reconnected. What that response drew goes, so that the replay
118
+ * rebuilds it, with nothing doubled and nothing reported. What earlier responses of the message drew
119
+ * stays, because a response is all a replay sends, and a decision stands. Without `messageId`, the
120
+ * message being read. A message this connection does not know is left alone.
121
+ */
122
+ replay: (messageId?: string) => void;
123
+ /**
124
+ * Stops listening. An answer still open is stopped, a pending
125
+ * approval expires, because no decision could reach the application any more, and a call still
126
+ * going is stopped, because nothing can settle it.
127
+ */
128
+ destroy: () => void;
129
+ };
130
+ export type MessageState = {
131
+ /**
132
+ * The message id, which is also its first answer item's.
133
+ */
134
+ id: string;
135
+ /**
136
+ * The answer items that hold it, in thread order: the message id, then
137
+ * `<id>#2`, `<id>#3`. What it says next goes to the last.
138
+ */
139
+ pieces: string[];
140
+ /**
141
+ * Whether its last piece is streaming.
142
+ */
143
+ writing: boolean;
144
+ /**
145
+ * The message's steps, which its first piece shows.
146
+ */
147
+ steps: TraceStep[];
148
+ /**
149
+ * The message's sources.
150
+ */
151
+ sources: Source[];
152
+ /**
153
+ * The piece that lists them.
154
+ */
155
+ listed: string;
156
+ /**
157
+ * Text blocks not ended yet. An ended block's id is free again.
158
+ */
159
+ texts: Set<unknown>;
160
+ /**
161
+ * The open block whose words are going out; null when none is.
162
+ */
163
+ speaking: unknown;
164
+ /**
165
+ * What other open blocks said
166
+ * meanwhile, by block, in the order they began. Answers can only be written at their end, so blocks
167
+ * that stream side by side go out one after the other.
168
+ */
169
+ held: Map<unknown, {
170
+ text: string;
171
+ ended: boolean;
172
+ }>;
173
+ /**
174
+ * Whether the last piece ends in text a new block has to be set apart
175
+ * from.
176
+ */
177
+ hasText: boolean;
178
+ /**
179
+ * Whether the next text starts a new paragraph.
180
+ */
181
+ gap: boolean;
182
+ /**
183
+ * Whether the first piece has steps on screen.
184
+ */
185
+ drawn: boolean;
186
+ /**
187
+ * Whether the run reported an error.
188
+ */
189
+ failed: boolean;
190
+ /**
191
+ * Whether it finished or was stopped.
192
+ */
193
+ closed: boolean;
194
+ /**
195
+ * Whether its `start` is still to come: a part created it ahead of its
196
+ * `start`, or a replay is about to send it again.
197
+ */
198
+ implied: boolean;
199
+ /**
200
+ * Whether its latest response is being sent again.
201
+ */
202
+ replaying: boolean;
203
+ /**
204
+ * Whether the response that resumed it has written nothing yet.
205
+ */
206
+ quiet: boolean;
207
+ /**
208
+ * Counts what it wrote, so that a step can tell it wrote nothing.
209
+ */
210
+ writes: number;
211
+ /**
212
+ * Its reasoning.
213
+ */
214
+ thinking: ThinkingState | null;
215
+ /**
216
+ * The calls it began, in order.
217
+ */
218
+ calls: CallState[];
219
+ /**
220
+ * The error notices drawn while it was open, in order.
221
+ */
222
+ notices: string[];
223
+ /**
224
+ * Where its current step began.
225
+ */
226
+ mark: StepMark;
227
+ /**
228
+ * Where its latest response began.
229
+ */
230
+ response: StepMark;
231
+ };
232
+ export type StepMark = {
233
+ /**
234
+ * When it was taken, among the connection's marks.
235
+ */
236
+ at: number;
237
+ /**
238
+ * How many calls the message had begun.
239
+ */
240
+ calls: number;
241
+ /**
242
+ * How many notices it had drawn.
243
+ */
244
+ notices: number;
245
+ /**
246
+ * How many pieces the message had.
247
+ */
248
+ pieces: number;
249
+ /**
250
+ * What its last piece showed.
251
+ */
252
+ blocks: Block[];
253
+ /**
254
+ * How many sources it had.
255
+ */
256
+ sources: number;
257
+ /**
258
+ * Its reasoning so far, if it had any.
259
+ */
260
+ thought: {
261
+ ms: number;
262
+ text: string;
263
+ } | null;
264
+ /**
265
+ * Where its text
266
+ * stood.
267
+ */
268
+ state: Pick<MessageState, 'writing' | 'hasText' | 'gap' | 'failed' | 'quiet'>;
269
+ /**
270
+ * What it had written.
271
+ */
272
+ writes: number;
273
+ };
274
+ export type ThinkingState = {
275
+ /**
276
+ * The one step all the message's reasoning shares.
277
+ */
278
+ step: TraceStep;
279
+ /**
280
+ * Reasoning blocks not ended yet.
281
+ */
282
+ open: Set<unknown>;
283
+ /**
284
+ * When the running stretch began.
285
+ */
286
+ since: number | null;
287
+ /**
288
+ * Time spent in finished stretches.
289
+ */
290
+ ms: number;
291
+ /**
292
+ * The reasoning text; only with `showReasoning`.
293
+ */
294
+ text: string;
295
+ };
296
+ export type CallState = {
297
+ /**
298
+ * The tool call id.
299
+ */
300
+ id: string;
301
+ /**
302
+ * The tool's name.
303
+ */
304
+ name: string;
305
+ /**
306
+ * The message it belongs to, also from a later response.
307
+ */
308
+ message: MessageState;
309
+ /**
310
+ * Where it stands.
311
+ */
312
+ status: RunState;
313
+ /**
314
+ * The complete input.
315
+ */
316
+ args: unknown;
317
+ /**
318
+ * The input text so far.
319
+ */
320
+ argsText: string;
321
+ /**
322
+ * The output.
323
+ */
324
+ result?: unknown;
325
+ /**
326
+ * The error text.
327
+ */
328
+ error?: string;
329
+ /**
330
+ * When it began running.
331
+ */
332
+ since: number | null;
333
+ /**
334
+ * Its step.
335
+ */
336
+ step: TraceStep;
337
+ /**
338
+ * The tile's item id, once drawn.
339
+ */
340
+ tile: string | null;
341
+ };
342
+ export type ApprovalState = {
343
+ /**
344
+ * The approval id.
345
+ */
346
+ id: string;
347
+ /**
348
+ * The call it holds.
349
+ */
350
+ call: CallState;
351
+ /**
352
+ * The message being read when it was drawn.
353
+ */
354
+ by: MessageState | null;
355
+ /**
356
+ * How many marks had been taken when it was drawn.
357
+ */
358
+ at: number;
359
+ /**
360
+ * Whether nothing can be decided any more.
361
+ */
362
+ settled: boolean;
363
+ };
364
+ export type Decision = {
365
+ /**
366
+ * Whether it was approved.
367
+ */
368
+ approved: boolean;
369
+ /**
370
+ * Why it was rejected.
371
+ */
372
+ reason?: string;
373
+ /**
374
+ * When, as the card says it.
375
+ */
376
+ at?: string;
377
+ };
378
+ /**
379
+ * Draws an AI SDK UI message stream in an AgentThread: text, reasoning, tool calls and their
380
+ * approvals, sources, and files. The application owns the request, the event source, retries, and
381
+ * authentication; it strips the `data: ` framing and the `[DONE]` sentinel and hands each parsed
382
+ * part to `handle()`, so the adapter runs with any transport and without a network.
383
+ *
384
+ * Keep one connection for the whole conversation: an approval's answer goes out with the
385
+ * application's next request, and the response to it continues the same message. A `start` for an
386
+ * answer the connection did not draw, restored with the conversation, takes it over, and nothing in
387
+ * the thread is overwritten: a `start` naming any other item opens an answer of its own.
388
+ *
389
+ * The thread stays in stream order. What a message says after a card, a tile, or another item it
390
+ * cannot write above continues in a new answer `<messageId>#<n>`, counting from 2, which the thread
391
+ * draws as the same turn. A `reset-step` takes back what the step drew, whichever answers it reached.
392
+ *
393
+ * Model output is data. Nothing is approved without the person, reasoning text stays out of the
394
+ * page unless asked for, a source only ever links to `https:`, and no address is fetched to draw
395
+ * anything: a file part shows its name and type, never its content.
396
+ *
397
+ * @param {AgentThread} thread The thread to draw in.
398
+ * @param {UiMessageStreamOptions} [options]
399
+ * @returns {UiMessageStreamConnection}
400
+ */
401
+ export declare function connectUiMessageStream(thread: AgentThread, options?: UiMessageStreamOptions): UiMessageStreamConnection;