@zeyos/zx 5.5.0 → 5.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  3. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  4. package/dist/types/components/avatar/avatar.d.ts +91 -4
  5. package/dist/types/components/block-view/block-view.d.ts +205 -0
  6. package/dist/types/components/composer/composer.d.ts +736 -0
  7. package/dist/types/components/run-status/run-status.d.ts +393 -0
  8. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  9. package/dist/types/components/source-list/source-list.d.ts +177 -0
  10. package/dist/types/core/messages.d.ts +135 -0
  11. package/dist/types/index.d.ts +8 -0
  12. package/dist/types/internal/agent-model.d.ts +587 -0
  13. package/dist/types/internal/highlight.d.ts +24 -0
  14. package/dist/types/internal/presence-loop.d.ts +148 -0
  15. package/dist/zx-zeyos.esm.js +4648 -4513
  16. package/dist/zx-zeyos.esm.min.js +2 -2
  17. package/dist/zx.css +1927 -1
  18. package/dist/zx.esm.js +15769 -9194
  19. package/dist/zx.esm.min.js +27 -8
  20. package/dist/zx.global.js +15769 -9194
  21. package/dist/zx.global.min.js +27 -8
  22. package/dist/zx.min.css +1 -1
  23. package/docs/api.json +1166 -5
  24. package/docs/llms.md +455 -2
  25. package/docs/llms.txt +10 -1
  26. package/package.json +1 -1
  27. package/src/components/agent-thread/agent-thread.css +417 -0
  28. package/src/components/agent-thread/agent-thread.js +1365 -0
  29. package/src/components/approval-card/approval-card.css +289 -0
  30. package/src/components/approval-card/approval-card.js +1377 -0
  31. package/src/components/avatar/avatar.css +56 -1
  32. package/src/components/avatar/avatar.js +148 -26
  33. package/src/components/block-view/block-view.css +300 -0
  34. package/src/components/block-view/block-view.js +523 -0
  35. package/src/components/composer/composer.css +403 -0
  36. package/src/components/composer/composer.js +1441 -0
  37. package/src/components/run-status/run-status.css +208 -0
  38. package/src/components/run-status/run-status.js +782 -0
  39. package/src/components/run-trace/run-trace.css +443 -0
  40. package/src/components/run-trace/run-trace.js +1209 -0
  41. package/src/components/source-list/source-list.css +208 -0
  42. package/src/components/source-list/source-list.js +355 -0
  43. package/src/core/messages.js +143 -0
  44. package/src/index.js +8 -0
  45. package/src/internal/agent-model.js +488 -0
  46. package/src/internal/highlight.js +104 -0
  47. package/src/internal/presence-loop.js +343 -0
  48. package/styles/zx.css +7 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,62 @@ and friends remain the complete record.
8
8
 
9
9
  ## Unreleased
10
10
 
11
+ ## 5.6.0 — 2026-11-03
12
+
13
+ Agents: a conversation with AI agents drawn from plain JSON — streamed answers, the steps a run
14
+ took, the approvals that hold it, the message box, and where the run stands — as library
15
+ components instead of layout code. The application owns the transport and the state; model text is
16
+ never HTML; whether an action needs confirmation is always the application's decision.
17
+
18
+ ### Added
19
+
20
+ - **AgentThread** — a conversation as an APG feed (PageDown/PageUp between items, Ctrl+End and
21
+ Ctrl+Home out of it): the person's messages, agents' answers as they stream, run traces,
22
+ approvals and one-line notices, from items `{id, type, author, …}` an agent can produce and an
23
+ application can store. `upsert()`, `patch()`, `appendText()` and `appendBlock()` feed it;
24
+ finished text is never redrawn. Answers carry sources, inline steps, versions with a pager, and
25
+ copy, regenerate, branch and rate actions; the person's messages can offer edit and copy;
26
+ notices can carry an action; any item can link to the application's records (`refs`, `open`
27
+ event); `@name` mentions are marked. One polite status says when an agent starts, answers, needs
28
+ approval or is stopped — streamed text is never read aloud as it arrives. While the reader is at
29
+ the end, new output keeps it in view; scrolled up, "Jump to latest" appears.
30
+ `AgentThread.register(type, render)` draws an application's own item types.
31
+ - **BlockView** / **`renderBlocks()`** — an answer drawn block by block inside `.zx-prose`:
32
+ paragraphs, headings, lists, quotes, code (coloured for js, ts, json, sql, python, shell and css;
33
+ `lines: true` numbers and wraps it), tables, figures, callouts and artifact cards. The inline
34
+ grammar is `**bold**`, `` `code` `` and `[n]` citations, nothing else. `appendText()` streams
35
+ into the last paragraph; a marker split across two chunks resolves when its close arrives.
36
+ `blocksToMarkdown()` and `blocksToText()` export an answer.
37
+ - **RunTrace** — what a run did: tool calls with their arguments and results, retries under the
38
+ call they repeat, hand-offs between agents, plan tasks, a person's requests and decisions,
39
+ per-step links, a live clock on the running step, and a one-line summary ("Worked for 41 s ·
40
+ 5 tool calls · 1 retry") that a plan can replace with its own title.
41
+ - **ApprovalCard** — a request that holds a run until a person answers: details and a preview,
42
+ Approve, Edit (a form from `fields`) and Reject (with a reason) on A, E and R while it has
43
+ focus, an optional typed confirmation, and an answered state that stays as the record. Only the
44
+ values the person changed are listed as edited; `update()` changes a waiting request in place.
45
+ - **SourceList** — the sources an answer cites, each with a card of its title, place and passage; a
46
+ source that names a tool call reveals it. Nothing remote is ever loaded to draw one.
47
+ - **Composer** — the message box: Enter or Mod+Enter sends, `@` mentions, `/` commands through the
48
+ Launcher, attachments by button, paste or drop, context chips, extra tool buttons (plain,
49
+ toggles or disclosures), a draft that survives a reload, and a Send button that becomes Stop
50
+ while the agent works. `update()` changes its label, placeholder, hint and note in place.
51
+ - **RunStatus** — where a run stands: state as glyph and word, a summary, a steps progressbar,
52
+ started / working time / waiting or blocked since / finished, and token and cost meters that warn
53
+ from 80% of a budget. `compact` draws the state alone as a pill for a narrow header.
54
+ - **Avatar** `activity` (idle, thinking, working, needs you, blocked, offline) — a dot that differs
55
+ in shape as well as tone, named in the accessible name — with `animate` joining one shared
56
+ presence animation that runs only on screen, sleeps while the page is hidden and rests under
57
+ reduced motion, and `phase` to keep two avatars of one agent out of step.
58
+ - The run states gain `blocked`; documentation gains an **Agents** chapter and component group.
59
+
60
+ ### Changed
61
+
62
+ - The **ai-chat**, **agent-chat** and **agent-workspace** layouts are built from these components,
63
+ so each is a reference for wiring them; their own stylesheets shrank from about 4,000 lines to
64
+ under 1,500.
65
+ - Documentation site: navigation levels are told apart by size, weight and colour together.
66
+
11
67
  ## 5.5.0 — 2026-11-03
12
68
 
13
69
  Calm and precise: a reading register beside the interface one, one row rhythm, navigation that
@@ -0,0 +1,583 @@
1
+ import { Component } from '../../core/component.js';
2
+ import { ApprovalCard } from '../approval-card/approval-card.js';
3
+ import { BlockView } from '../block-view/block-view.js';
4
+ import { RunTrace } from '../run-trace/run-trace.js';
5
+ import { SourceList } from '../source-list/source-list.js';
6
+ export type ThreadItem = import('../../internal/agent-model.js').ThreadItem;
7
+ export type Author = import('../../internal/agent-model.js').Author;
8
+ export type Source = import('../../internal/agent-model.js').Source;
9
+ export type Block = import('../../internal/agent-model.js').Block;
10
+ export type EmptyStateOptions = import('../empty-state/empty-state.js').EmptyStateOptions;
11
+ export type AnswerAction = 'copy' | 'regenerate' | 'branch' | 'rate';
12
+ export type ThreadRenderContext = {
13
+ /**
14
+ * The thread drawing the item.
15
+ */
16
+ thread: AgentThread;
17
+ /**
18
+ * The item's author, resolved from `authors`.
19
+ */
20
+ author: Author | null;
21
+ /**
22
+ * Hands a component to the thread, which
23
+ * destroys it with the item.
24
+ */
25
+ own: <T extends Component>(component: T) => T;
26
+ };
27
+ export type ThreadItemRenderer = (item: ThreadItem, context: ThreadRenderContext) => Node | null;
28
+ export type AgentThreadOptions = {
29
+ /**
30
+ * The conversation, oldest first.
31
+ */
32
+ items?: ThreadItem[];
33
+ /**
34
+ * Who wrote the items and took the steps, by key.
35
+ * An item without an `author` is the person's own (`user`) or the first agent's (anything else).
36
+ */
37
+ authors?: Record<string, Author>;
38
+ /**
39
+ * Author key of the person reading; their items read as "You".
40
+ */
41
+ me?: string;
42
+ /**
43
+ * Accessible name of the feed; "Conversation" when null.
44
+ */
45
+ label?: string | null;
46
+ /**
47
+ * Heading level inside answers and cards.
48
+ */
49
+ headingLevel?: 2 | 3 | 4 | 5;
50
+ /**
51
+ * Shown while there are no items.
52
+ */
53
+ emptyState?: EmptyStateOptions | null;
54
+ /**
55
+ * Keep the end in view while new output arrives, as long
56
+ * as the reader is at the end; otherwise offer "Jump to latest" and leave them where they are.
57
+ */
58
+ followOutput?: boolean;
59
+ /**
60
+ * The element that scrolls; the nearest scrolling
61
+ * ancestor (or the thread itself) when null.
62
+ */
63
+ scroller?: Element | null;
64
+ /**
65
+ * Actions under each
66
+ * finished answer; `regenerate` only under the latest one.
67
+ */
68
+ answerActions?: AnswerAction[];
69
+ /**
70
+ * Glyph
71
+ * names for the answer and message actions.
72
+ */
73
+ icons?: Partial<Record<'regenerate' | 'branch' | 'rateUp' | 'rateDown' | 'edit', string>>;
74
+ /**
75
+ * Actions on the person's own messages, shown
76
+ * while the message is pointed at or holds focus (always on a touch screen): `edit` asks the
77
+ * application to put the message back in the composer, `copy` copies its text.
78
+ */
79
+ userActions?: Array<'edit' | 'copy'>;
80
+ /**
81
+ * Glyph names for trace step kinds, handed to
82
+ * every `RunTrace` the thread draws.
83
+ */
84
+ traceIcons?: Record<string, string>;
85
+ /**
86
+ * Glyph names for source kinds, handed to every
87
+ * `SourceList` the thread draws.
88
+ */
89
+ sourceIcons?: Record<string, string>;
90
+ /**
91
+ * The clock "today" is measured against in cards and
92
+ * traces, for an application whose world runs on fixed dates; the real clock when null.
93
+ */
94
+ now?: (() => Date) | null;
95
+ /**
96
+ * Formats an item's `at`; the local
97
+ * clock time when null.
98
+ */
99
+ formatTime?: ((at: string) => string) | null;
100
+ /**
101
+ * Locale for times.
102
+ */
103
+ locale?: string;
104
+ /**
105
+ * Localized messages.
106
+ */
107
+ msg?: Record<string, string> | Record<string, Record<string, string>>;
108
+ /**
109
+ * Answer action listener.
110
+ */
111
+ onaction?: (event: CustomEvent<{
112
+ item: ThreadItem;
113
+ action: string;
114
+ value?: unknown;
115
+ }>) => void;
116
+ /**
117
+ * Approval listener.
118
+ */
119
+ onapprove?: (event: CustomEvent<{
120
+ item: ThreadItem;
121
+ values: Record<string, unknown>;
122
+ }>) => void;
123
+ /**
124
+ * Edit listener.
125
+ */
126
+ onedit?: (event: CustomEvent<{
127
+ item: ThreadItem;
128
+ values: Record<string, unknown>;
129
+ }>) => void;
130
+ /**
131
+ * Rejection listener.
132
+ */
133
+ onreject?: (event: CustomEvent<{
134
+ item: ThreadItem;
135
+ reason: string;
136
+ }>) => void;
137
+ /**
138
+ * Citation listener.
139
+ */
140
+ oncite?: (event: CustomEvent<{
141
+ item: ThreadItem;
142
+ n: number;
143
+ source: Source | null;
144
+ }>) => void;
145
+ /**
146
+ * Artifact listener.
147
+ */
148
+ onartifact?: (event: CustomEvent<{
149
+ item: ThreadItem;
150
+ id: string;
151
+ }>) => void;
152
+ /**
153
+ * Reveal listener.
154
+ */
155
+ onreveal?: (event: CustomEvent<{
156
+ target: string;
157
+ }>) => void;
158
+ /**
159
+ * Link listener.
160
+ */
161
+ onopen?: (event: CustomEvent<{
162
+ item: ThreadItem;
163
+ ref: import('../../internal/agent-model.js').ItemRef;
164
+ }>) => void;
165
+ };
166
+ export type ThreadEntry = {
167
+ /**
168
+ * The item as last given.
169
+ */
170
+ item: ThreadItem;
171
+ /**
172
+ * Its article.
173
+ */
174
+ article: HTMLElement;
175
+ /**
176
+ * Components drawn for it.
177
+ */
178
+ owned: Component[];
179
+ /**
180
+ * An answer's text.
181
+ */
182
+ view: BlockView | null;
183
+ /**
184
+ * A trace's steps.
185
+ */
186
+ trace: RunTrace | null;
187
+ /**
188
+ * An answer's sources.
189
+ */
190
+ sources: SourceList | null;
191
+ /**
192
+ * An approval.
193
+ */
194
+ card: ApprovalCard | null;
195
+ };
196
+ /**
197
+ * A conversation with one or more agents: the person's messages, the agents' answers as they
198
+ * stream, the steps a run took, the approvals that hold it, and one-line notices — drawn from the
199
+ * plain-JSON items of the agent model. The thread owns no transport and no state beyond what it
200
+ * is given: the application feeds it (`upsert`, `patch`, `appendText`) and acts on what it emits.
201
+ *
202
+ * It follows the APG feed pattern: each item is an article in a `role="feed"`, PageDown and
203
+ * PageUp move between articles, and Ctrl+End / Ctrl+Home leave the feed. Streamed text is never
204
+ * read aloud as it arrives; one polite status says when an agent starts, answers, needs
205
+ * approval, or is stopped.
206
+ *
207
+ * @fires AgentThread#action
208
+ * @fires AgentThread#approve
209
+ * @fires AgentThread#edit
210
+ * @fires AgentThread#reject
211
+ * @fires AgentThread#cite
212
+ * @fires AgentThread#artifact
213
+ * @fires AgentThread#reveal
214
+ * @fires AgentThread#open
215
+ * @extends {Component<AgentThreadOptions>}
216
+ */
217
+ export declare class AgentThread extends Component<AgentThreadOptions> {
218
+ #private;
219
+ _original: import("../../core/dom.js").TargetSnapshot;
220
+ _id: string;
221
+ /** @type {Map<string, ThreadEntry>} */
222
+ _entries: Map<string, ThreadEntry>;
223
+ /** @type {string[]} */
224
+ _order: string[];
225
+ _announceTimer: number;
226
+ /** @type {Element|null} */
227
+ _scrollHost: Element | null;
228
+ /** @type {string|null} */
229
+ _latestAnswer: string | null;
230
+ /** @type {Map<string, {expanded?: boolean|null, controls?: string|null}>} Artifact open states, for answers drawn later. */
231
+ _artifacts: Map<string, {
232
+ expanded?: boolean | null;
233
+ controls?: string | null;
234
+ }>;
235
+ _feed: HTMLElement;
236
+ _empty: HTMLElement;
237
+ _latestButton: HTMLButtonElement;
238
+ _status: HTMLElement;
239
+ _destroyed: boolean;
240
+ static cssName: string;
241
+ /** @type {Readonly<AgentThreadOptions>} */
242
+ static defaults: Readonly<AgentThreadOptions>;
243
+ /**
244
+ * Registers how items of another type are drawn — an application's own, or a surface. A
245
+ * built-in type cannot be replaced.
246
+ * @param {string} type Item type.
247
+ * @param {ThreadItemRenderer} render Draws the item's content.
248
+ * @returns {typeof AgentThread}
249
+ */
250
+ static register(type: string, render: ThreadItemRenderer): typeof AgentThread;
251
+ /**
252
+ * Reports whether a type has a registered renderer.
253
+ * @param {string} type
254
+ * @returns {boolean}
255
+ */
256
+ static has(type: string): boolean;
257
+ /** @returns {HTMLElement} */
258
+ render(): HTMLElement;
259
+ /**
260
+ * Replaces the conversation.
261
+ * @param {ThreadItem[]} items
262
+ * @returns {this}
263
+ */
264
+ setItems(items: ThreadItem[]): this;
265
+ /**
266
+ * Adds an item, or replaces the item with the same id where it stands.
267
+ * @param {ThreadItem} item
268
+ * @returns {this}
269
+ */
270
+ upsert(item: ThreadItem): this;
271
+ /**
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.
275
+ * @param {string} id
276
+ * @param {Record<string, unknown>} partial
277
+ * @returns {this}
278
+ */
279
+ patch(id: string, partial: Record<string, unknown>): this;
280
+ /**
281
+ * Streams text into an answer, creating it when the id is new. Only the answer's last
282
+ * paragraph is redrawn.
283
+ * @param {string} id
284
+ * @param {string} text
285
+ * @returns {this}
286
+ */
287
+ appendText(id: string, text: string): this;
288
+ /**
289
+ * Adds a whole block to an answer — a figures block, a table, code — after what it already
290
+ * shows, without redrawing the rest of the answer. Creates the answer when the id is new.
291
+ * @param {string} id
292
+ * @param {Block} block
293
+ * @returns {this}
294
+ */
295
+ appendBlock(id: string, block: Block): this;
296
+ /**
297
+ * Says something through the thread's polite status — an outcome the thread cannot see itself,
298
+ * such as "Reminders sent". Said once; the same words said twice are heard twice.
299
+ * @param {string} text
300
+ * @returns {this}
301
+ */
302
+ announce(text: string): this;
303
+ /**
304
+ * Removes an item.
305
+ * @param {string} id
306
+ * @returns {this}
307
+ */
308
+ remove(id: string): this;
309
+ /**
310
+ * An item as it stands, an answer's streamed text included.
311
+ * @param {string} id
312
+ * @returns {ThreadItem|null}
313
+ */
314
+ get(id: string): ThreadItem | null;
315
+ /** @returns {ThreadItem[]} Every item, in order, as it stands. */
316
+ getItems(): ThreadItem[];
317
+ /**
318
+ * The main component drawn for an item: an answer's BlockView, a trace's RunTrace, an
319
+ * approval's ApprovalCard.
320
+ * @param {string} id
321
+ * @returns {Component|null}
322
+ */
323
+ getComponent(id: string): Component | null;
324
+ /**
325
+ * 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.
327
+ * @param {string} target
328
+ * @returns {boolean} Whether the target was found.
329
+ */
330
+ reveal(target: string): boolean;
331
+ /**
332
+ * Reflects whether an artifact is open somewhere — an inspector, a drawer — on every card that
333
+ * names it, in every answer. See `BlockView#setArtifactState()`.
334
+ * @param {string} id Artifact id.
335
+ * @param {{expanded?: boolean|null, controls?: string|null}} state
336
+ * @returns {this}
337
+ */
338
+ setArtifactState(id: string, state: {
339
+ expanded?: boolean | null;
340
+ controls?: string | null;
341
+ }): this;
342
+ /**
343
+ * Scrolls to the end of the conversation.
344
+ * @returns {this}
345
+ */
346
+ scrollToEnd(): this;
347
+ /** @returns {void} */
348
+ destroy(): void;
349
+ /**
350
+ * @private
351
+ * @param {ThreadItem} item
352
+ * @param {{announce?: boolean}} [options]
353
+ * @returns {void}
354
+ */
355
+ private _add;
356
+ /**
357
+ * @private
358
+ * @param {string} id
359
+ * @param {ThreadItem} item
360
+ * @returns {void}
361
+ */
362
+ private _replace;
363
+ /** @private @param {string} id @returns {void} */
364
+ private _drop;
365
+ /**
366
+ * Regenerate belongs to the latest answer only: when another answer becomes the latest, both
367
+ * answers' actions are redrawn.
368
+ * @private
369
+ * @returns {void}
370
+ */
371
+ private _syncLatest;
372
+ /** @private @returns {string|null} The id of the last answer in the thread. */
373
+ private _latestAnswerId;
374
+ /**
375
+ * Redraws an answer's action row alone, leaving its sources as they are.
376
+ * @private
377
+ * @param {ThreadEntry} entry
378
+ * @returns {void}
379
+ */
380
+ private _redrawActions;
381
+ /**
382
+ * Draws one item into its article.
383
+ * @private
384
+ * @param {ThreadItem} item
385
+ * @returns {ThreadEntry}
386
+ */
387
+ private _build;
388
+ /**
389
+ * A RunTrace the thread owns: its authors, glyphs, and clock.
390
+ * @private
391
+ * @param {import('../../internal/agent-model.js').TraceStep[]} steps
392
+ * @param {{open?: boolean, label?: string|null}} [options]
393
+ * @returns {RunTrace}
394
+ */
395
+ private _trace;
396
+ /**
397
+ * Keeps a child's bubbling `zx-<type>` events inside the thread for the types the thread
398
+ * re-emits itself, so a listener on the thread's root hears each of them once.
399
+ * @private
400
+ * @param {Component} child
401
+ * @param {string[]} types
402
+ * @returns {void}
403
+ */
404
+ private _contain;
405
+ /**
406
+ * Links from an item to the application's own things, after its content.
407
+ * @private
408
+ * @param {unknown} refs
409
+ * @returns {HTMLElement|null}
410
+ */
411
+ private _refs;
412
+ /**
413
+ * Edit and copy on the person's own message, shown while it is pointed at or holds focus.
414
+ * @private
415
+ * @param {Extract<ThreadItem, {type: 'user'}>} user
416
+ * @returns {HTMLElement|null}
417
+ */
418
+ private _userActions;
419
+ /**
420
+ * @private
421
+ * @param {ThreadEntry} entry
422
+ * @param {HTMLElement} body
423
+ * @param {<T extends Component>(component: T) => T} own
424
+ * @returns {void}
425
+ */
426
+ private _buildAnswer;
427
+ /**
428
+ * While an answer is on its way and nothing of it has arrived, a quiet line says who is
429
+ * writing; it goes as soon as the first words do.
430
+ * @private
431
+ * @param {ThreadEntry} entry
432
+ * @returns {void}
433
+ */
434
+ private _syncWriting;
435
+ /**
436
+ * Draws an answer's sources and actions, which show only once it is finished.
437
+ * @private
438
+ * @param {ThreadEntry} entry
439
+ * @param {<T extends Component>(component: T) => T} [own]
440
+ * @returns {void}
441
+ */
442
+ private _redrawAnswerFooter;
443
+ /**
444
+ * @private
445
+ * @param {ThreadEntry} entry
446
+ * @returns {HTMLElement|null}
447
+ */
448
+ private _answerActions;
449
+ /**
450
+ * @private
451
+ * @param {ThreadEntry} entry
452
+ * @param {HTMLElement} body
453
+ * @param {<T extends Component>(component: T) => T} own
454
+ * @returns {void}
455
+ */
456
+ private _buildApproval;
457
+ /**
458
+ * The author's avatar, beside the byline and the content. Decorative: the byline names them.
459
+ * @private
460
+ * @param {ThreadItem} item
461
+ * @param {<T extends Component>(component: T) => T} own
462
+ * @returns {HTMLElement|null}
463
+ */
464
+ private _avatar;
465
+ /**
466
+ * @private
467
+ * @param {ThreadItem} item
468
+ * @param {string} id
469
+ * @returns {HTMLElement}
470
+ */
471
+ private _byline;
472
+ /**
473
+ * @private
474
+ * @param {Array<{name: string, size?: number}>} files
475
+ * @returns {HTMLElement}
476
+ */
477
+ private _files;
478
+ /** @private @param {ThreadItem} item @returns {boolean} */
479
+ private _isMine;
480
+ /** @private @param {ThreadItem} item @returns {Author|null} */
481
+ private _author;
482
+ /** @private @param {ThreadItem} item @returns {string} */
483
+ private _authorName;
484
+ /** @private @param {unknown} at @returns {string} */
485
+ private _time;
486
+ /** @private @param {Extract<ThreadItem, {type: 'answer'}>} answer @returns {number} */
487
+ private _versionIndex;
488
+ /**
489
+ * The blocks, sources, and steps an answer shows: its chosen version's when it has several.
490
+ * @private
491
+ * @param {Extract<ThreadItem, {type: 'answer'}>} answer
492
+ * @returns {{blocks: Block[], sources: Source[], steps: import('../../internal/agent-model.js').TraceStep[],
493
+ * stopped: boolean, rating: 'up'|'down'|null, at: string|undefined}}
494
+ */
495
+ private _version;
496
+ /**
497
+ * A consecutive item by the same author reads as one turn: its byline is still there for a
498
+ * screen reader, but not drawn again.
499
+ * @private
500
+ * @param {string} id
501
+ * @returns {void}
502
+ */
503
+ private _syncContinuation;
504
+ /** @private @returns {void} */
505
+ private _syncPositions;
506
+ /** @private @returns {void} */
507
+ private _syncEmpty;
508
+ /** @private @param {ThreadItem} item @returns {void} */
509
+ private _announceItem;
510
+ /**
511
+ * Says a milestone once. The region is cleared first so the same words said twice are heard
512
+ * twice.
513
+ * @private
514
+ * @param {string} text
515
+ * @returns {void}
516
+ */
517
+ private _announce;
518
+ /** @private @returns {Element|null} */
519
+ private _scroller;
520
+ /** @private @returns {boolean} */
521
+ private _atEnd;
522
+ /**
523
+ * Runs a change and keeps the end in view if the reader was reading it.
524
+ * @private
525
+ * @param {() => void} change
526
+ * @returns {void}
527
+ */
528
+ private _follow;
529
+ /** @private @returns {HTMLElement|null} */
530
+ private _lastArticle;
531
+ /** @private @param {MouseEvent} event @returns {void} */
532
+ private _onClick;
533
+ /**
534
+ * 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.
536
+ * @private
537
+ * @param {KeyboardEvent} event
538
+ * @returns {void}
539
+ */
540
+ private _onFeedKey;
541
+ }
542
+ /**
543
+ * Action payload: under an answer `copy`, `regenerate`, `branch`, `rate` (`value` up, down, or
544
+ * null), or `version` (`value` the version index; preventable, like `rate`); on the person's own
545
+ * message `edit` (copying needs no event); on a notice, the id of its `action`.
546
+ * @event AgentThread#action
547
+ * @type {CustomEvent<{item: ThreadItem, action: string, value?: unknown}>}
548
+ */
549
+ /**
550
+ * An approval was approved; preventable, which keeps the card pending.
551
+ * @event AgentThread#approve
552
+ * @type {CustomEvent<{item: ThreadItem, values: Record<string, unknown>}>}
553
+ */
554
+ /**
555
+ * An approval's values were edited; preventable.
556
+ * @event AgentThread#edit
557
+ * @type {CustomEvent<{item: ThreadItem, values: Record<string, unknown>}>}
558
+ */
559
+ /**
560
+ * An approval was rejected; preventable, which keeps the card pending.
561
+ * @event AgentThread#reject
562
+ * @type {CustomEvent<{item: ThreadItem, reason: string}>}
563
+ */
564
+ /**
565
+ * A citation was activated; preventable, which skips highlighting the source.
566
+ * @event AgentThread#cite
567
+ * @type {CustomEvent<{item: ThreadItem, n: number, source: Source|null}>}
568
+ */
569
+ /**
570
+ * An artifact card was activated.
571
+ * @event AgentThread#artifact
572
+ * @type {CustomEvent<{item: ThreadItem, id: string}>}
573
+ */
574
+ /**
575
+ * Something was brought into view by `reveal()`.
576
+ * @event AgentThread#reveal
577
+ * @type {CustomEvent<{target: string}>}
578
+ */
579
+ /**
580
+ * A link was activated: one of an item's `refs`, or of a trace step's (then `step` names it).
581
+ * @event AgentThread#open
582
+ * @type {CustomEvent<{item: ThreadItem, ref: import('../../internal/agent-model.js').ItemRef, step?: import('../../internal/agent-model.js').TraceStep}>}
583
+ */