@zeyos/zx 5.4.0 → 5.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (145) hide show
  1. package/CHANGELOG.md +136 -0
  2. package/README.md +23 -16
  3. package/dist/types/components/agent-thread/agent-thread.d.ts +583 -0
  4. package/dist/types/components/app-sidebar/app-sidebar.d.ts +33 -0
  5. package/dist/types/components/approval-card/approval-card.d.ts +596 -0
  6. package/dist/types/components/avatar/avatar.d.ts +91 -4
  7. package/dist/types/components/badge/badge.d.ts +5 -4
  8. package/dist/types/components/block-view/block-view.d.ts +205 -0
  9. package/dist/types/components/composer/composer.d.ts +736 -0
  10. package/dist/types/components/datebox/date-range-box.d.ts +15 -2
  11. package/dist/types/components/datebox/datebox.d.ts +37 -3
  12. package/dist/types/components/kbd/kbd.d.ts +41 -0
  13. package/dist/types/components/launcher/launcher.d.ts +4 -2
  14. package/dist/types/components/prose/prose.d.ts +69 -0
  15. package/dist/types/components/questionnaire/questionnaire.d.ts +0 -36
  16. package/dist/types/components/run-status/run-status.d.ts +393 -0
  17. package/dist/types/components/run-trace/run-trace.d.ts +624 -0
  18. package/dist/types/components/source-list/source-list.d.ts +177 -0
  19. package/dist/types/components/stat-tile/stat-tile.d.ts +20 -0
  20. package/dist/types/components/tag-picker/tag-picker.d.ts +11 -5
  21. package/dist/types/components/tree/tree.d.ts +44 -3
  22. package/dist/types/core/icons.d.ts +22 -1
  23. package/dist/types/core/messages.d.ts +135 -0
  24. package/dist/types/index.d.ts +12 -2
  25. package/dist/types/internal/agent-model.d.ts +587 -0
  26. package/dist/types/internal/app-rail.d.ts +10 -3
  27. package/dist/types/internal/highlight.d.ts +24 -0
  28. package/dist/types/internal/presence-loop.d.ts +148 -0
  29. package/dist/types/internal/row-actions.d.ts +151 -0
  30. package/dist/zx-zeyos.esm.js +4852 -4535
  31. package/dist/zx-zeyos.esm.min.js +4 -4
  32. package/dist/zx.css +3152 -434
  33. package/dist/zx.esm.js +13730 -6595
  34. package/dist/zx.esm.min.js +27 -8
  35. package/dist/zx.global.js +13730 -6595
  36. package/dist/zx.global.min.js +27 -8
  37. package/dist/zx.min.css +1 -1
  38. package/docs/api.json +1474 -205
  39. package/docs/llms.md +698 -39
  40. package/docs/llms.txt +12 -1
  41. package/package.json +1 -1
  42. package/src/components/account-menu/account-menu.js +2 -2
  43. package/src/components/agent-thread/agent-thread.css +417 -0
  44. package/src/components/agent-thread/agent-thread.js +1365 -0
  45. package/src/components/app-rail/app-rail.css +11 -11
  46. package/src/components/app-sidebar/app-sidebar.css +90 -17
  47. package/src/components/app-sidebar/app-sidebar.js +120 -12
  48. package/src/components/approval-card/approval-card.css +289 -0
  49. package/src/components/approval-card/approval-card.js +1377 -0
  50. package/src/components/avatar/avatar.css +56 -1
  51. package/src/components/avatar/avatar.js +148 -26
  52. package/src/components/badge/badge.css +33 -20
  53. package/src/components/badge/badge.js +5 -4
  54. package/src/components/block-view/block-view.css +300 -0
  55. package/src/components/block-view/block-view.js +523 -0
  56. package/src/components/breadcrumb/breadcrumb.css +28 -3
  57. package/src/components/breadcrumb/breadcrumb.js +2 -2
  58. package/src/components/button/button.css +24 -13
  59. package/src/components/button/button.js +20 -2
  60. package/src/components/calendar/calendar.css +14 -4
  61. package/src/components/card-view/card-view.js +2 -2
  62. package/src/components/chart/chart.js +20 -5
  63. package/src/components/check-button/check-button.css +11 -3
  64. package/src/components/check-button/check-button.js +3 -3
  65. package/src/components/composer/composer.css +403 -0
  66. package/src/components/composer/composer.js +1441 -0
  67. package/src/components/context-menu/context-menu.css +7 -1
  68. package/src/components/date-picker/date-picker.css +6 -0
  69. package/src/components/date-picker/date-picker.js +5 -5
  70. package/src/components/date-picker/date-range-picker.css +6 -0
  71. package/src/components/date-picker/date-range-picker.js +3 -3
  72. package/src/components/date-picker/month-picker.js +3 -3
  73. package/src/components/date-picker/time-picker.css +6 -0
  74. package/src/components/datebox/date-range-box.js +30 -6
  75. package/src/components/datebox/datebox.js +44 -7
  76. package/src/components/dialog/dialog.css +0 -1
  77. package/src/components/dialog/dialog.js +2 -1
  78. package/src/components/dock/dock.js +2 -2
  79. package/src/components/dropdown/dropdown.css +2 -1
  80. package/src/components/entity-ref/entity-ref.css +8 -1
  81. package/src/components/file-item/file-item.css +1 -1
  82. package/src/components/finder/finder.js +2 -2
  83. package/src/components/groupbox/groupbox.js +2 -2
  84. package/src/components/kanban-view/kanban-view.css +8 -4
  85. package/src/components/kanban-view/kanban-view.js +3 -3
  86. package/src/components/kbd/kbd.css +64 -0
  87. package/src/components/kbd/kbd.js +121 -0
  88. package/src/components/launcher/launcher.css +30 -25
  89. package/src/components/launcher/launcher.js +15 -21
  90. package/src/components/list-toolbar/list-toolbar.css +7 -1
  91. package/src/components/menu-button/menu-button.css +9 -2
  92. package/src/components/message/message.js +2 -2
  93. package/src/components/module-bar/module-bar.css +11 -1
  94. package/src/components/multi-value-editor/multi-value-editor.js +4 -4
  95. package/src/components/navigation-bar/navigation-bar.css +3 -2
  96. package/src/components/pagination/pagination.js +2 -2
  97. package/src/components/panel/panel.js +2 -2
  98. package/src/components/prose/prose.css +53 -0
  99. package/src/components/prose/prose.js +152 -0
  100. package/src/components/questionnaire/questionnaire.css +7 -17
  101. package/src/components/questionnaire/questionnaire.js +16 -1
  102. package/src/components/rating/rating.css +3 -1
  103. package/src/components/run-status/run-status.css +208 -0
  104. package/src/components/run-status/run-status.js +782 -0
  105. package/src/components/run-trace/run-trace.css +443 -0
  106. package/src/components/run-trace/run-trace.js +1209 -0
  107. package/src/components/search/search.js +2 -2
  108. package/src/components/select/glyphs.js +3 -3
  109. package/src/components/select/select.css +35 -7
  110. package/src/components/select/select.js +4 -4
  111. package/src/components/source-list/source-list.css +208 -0
  112. package/src/components/source-list/source-list.js +355 -0
  113. package/src/components/stat-tile/stat-tile.css +56 -2
  114. package/src/components/stat-tile/stat-tile.js +25 -2
  115. package/src/components/stepper/stepper.css +2 -1
  116. package/src/components/stepper/stepper.js +3 -3
  117. package/src/components/tabbox/tabbox.css +2 -2
  118. package/src/components/tabbox/tabbox.js +2 -2
  119. package/src/components/table/table.css +52 -16
  120. package/src/components/table/table.js +7 -5
  121. package/src/components/tag-picker/tag-picker.css +56 -43
  122. package/src/components/tag-picker/tag-picker.js +21 -16
  123. package/src/components/tree/tree.css +44 -0
  124. package/src/components/tree/tree.js +97 -9
  125. package/src/components/value-list/value-list.css +25 -4
  126. package/src/components/value-list/value-list.js +2 -1
  127. package/src/components/view/record-view.js +3 -3
  128. package/src/components/view-settings/view-settings.css +2 -1
  129. package/src/components/workspace-switcher/workspace-switcher.js +3 -3
  130. package/src/core/icons.js +34 -3
  131. package/src/core/messages.js +143 -0
  132. package/src/elements/define.js +1 -0
  133. package/src/index.js +12 -2
  134. package/src/internal/agent-model.js +488 -0
  135. package/src/internal/app-rail.js +5 -1
  136. package/src/internal/highlight.js +104 -0
  137. package/src/internal/presence-loop.js +343 -0
  138. package/src/internal/row-actions.js +203 -0
  139. package/styles/base.css +26 -1
  140. package/styles/prose.css +306 -0
  141. package/styles/tokens/dark.css +97 -120
  142. package/styles/tokens/global.css +24 -9
  143. package/styles/tokens/semantic.css +464 -184
  144. package/styles/tokens/themes.css +9 -0
  145. package/styles/zx.css +10 -0
package/docs/api.json CHANGED
@@ -360,6 +360,240 @@
360
360
  }
361
361
  ]
362
362
  },
363
+ "AgentThread": {
364
+ "options": [
365
+ {
366
+ "name": "items",
367
+ "type": "ThreadItem[]",
368
+ "default": "[]",
369
+ "description": "The conversation, oldest first."
370
+ },
371
+ {
372
+ "name": "authors",
373
+ "type": "Record<string, Author>",
374
+ "default": "{}",
375
+ "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)."
376
+ },
377
+ {
378
+ "name": "me",
379
+ "type": "string",
380
+ "default": "'me'",
381
+ "description": "Author key of the person reading; their items read as \"You\"."
382
+ },
383
+ {
384
+ "name": "label",
385
+ "type": "string|null",
386
+ "default": "null",
387
+ "description": "Accessible name of the feed; \"Conversation\" when null."
388
+ },
389
+ {
390
+ "name": "headingLevel",
391
+ "type": "2|3|4|5",
392
+ "default": "3",
393
+ "description": "Heading level inside answers and cards."
394
+ },
395
+ {
396
+ "name": "emptyState",
397
+ "type": "EmptyStateOptions|null",
398
+ "default": "null",
399
+ "description": "Shown while there are no items."
400
+ },
401
+ {
402
+ "name": "followOutput",
403
+ "type": "boolean",
404
+ "default": "true",
405
+ "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."
406
+ },
407
+ {
408
+ "name": "scroller",
409
+ "type": "Element|null",
410
+ "default": "null",
411
+ "description": "The element that scrolls; the nearest scrolling ancestor (or the thread itself) when null."
412
+ },
413
+ {
414
+ "name": "answerActions",
415
+ "type": "AnswerAction[]",
416
+ "default": "['copy','regenerate','branch']",
417
+ "description": "Actions under each finished answer; `regenerate` only under the latest one."
418
+ },
419
+ {
420
+ "name": "icons",
421
+ "type": "Partial<Record<'regenerate'|'branch'|'rateUp'|'rateDown'|'edit', string>>",
422
+ "default": null,
423
+ "description": "Glyph names for the answer and message actions."
424
+ },
425
+ {
426
+ "name": "userActions",
427
+ "type": "Array<'edit'|'copy'>",
428
+ "default": "[]",
429
+ "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."
430
+ },
431
+ {
432
+ "name": "traceIcons",
433
+ "type": "Record<string, string>",
434
+ "default": "{}",
435
+ "description": "Glyph names for trace step kinds, handed to every `RunTrace` the thread draws."
436
+ },
437
+ {
438
+ "name": "sourceIcons",
439
+ "type": "Record<string, string>",
440
+ "default": "{}",
441
+ "description": "Glyph names for source kinds, handed to every `SourceList` the thread draws."
442
+ },
443
+ {
444
+ "name": "now",
445
+ "type": "(() => Date)|null",
446
+ "default": "null",
447
+ "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."
448
+ },
449
+ {
450
+ "name": "formatTime",
451
+ "type": "((at: string) => string)|null",
452
+ "default": "null",
453
+ "description": "Formats an item's `at`; the local clock time when null."
454
+ },
455
+ {
456
+ "name": "locale",
457
+ "type": "string",
458
+ "default": null,
459
+ "description": "Locale for times."
460
+ },
461
+ {
462
+ "name": "msg",
463
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
464
+ "default": null,
465
+ "description": "Localized messages."
466
+ }
467
+ ],
468
+ "events": [
469
+ {
470
+ "name": "action",
471
+ "payload": "{item: ThreadItem, action: string, value?: unknown}",
472
+ "description": "Answer action listener."
473
+ },
474
+ {
475
+ "name": "approve",
476
+ "payload": "{item: ThreadItem, values: Record<string, unknown>}",
477
+ "description": "Approval listener."
478
+ },
479
+ {
480
+ "name": "edit",
481
+ "payload": "{item: ThreadItem, values: Record<string, unknown>}",
482
+ "description": "Edit listener."
483
+ },
484
+ {
485
+ "name": "reject",
486
+ "payload": "{item: ThreadItem, reason: string}",
487
+ "description": "Rejection listener."
488
+ },
489
+ {
490
+ "name": "cite",
491
+ "payload": "{item: ThreadItem, n: number, source: Source|null}",
492
+ "description": "Citation listener."
493
+ },
494
+ {
495
+ "name": "artifact",
496
+ "payload": "{item: ThreadItem, id: string}",
497
+ "description": "Artifact listener."
498
+ },
499
+ {
500
+ "name": "reveal",
501
+ "payload": "{target: string}",
502
+ "description": "Reveal listener."
503
+ },
504
+ {
505
+ "name": "open",
506
+ "payload": "{item: ThreadItem, ref: import('../../internal/agent-model.js').ItemRef}",
507
+ "description": "Link listener."
508
+ }
509
+ ],
510
+ "methods": [
511
+ {
512
+ "name": "register",
513
+ "signature": "register(type, render)",
514
+ "returns": "typeof AgentThread",
515
+ "description": "Registers how items of another type are drawn — an application's own, or a surface. A built-in type cannot be replaced."
516
+ },
517
+ {
518
+ "name": "has",
519
+ "signature": "has(type)",
520
+ "returns": "boolean",
521
+ "description": "Reports whether a type has a registered renderer."
522
+ },
523
+ {
524
+ "name": "setItems",
525
+ "signature": "setItems(items)",
526
+ "returns": "this",
527
+ "description": "Replaces the conversation."
528
+ },
529
+ {
530
+ "name": "upsert",
531
+ "signature": "upsert(item)",
532
+ "returns": "this",
533
+ "description": "Adds an item, or replaces the item with the same id where it stands."
534
+ },
535
+ {
536
+ "name": "patch",
537
+ "signature": "patch(id, partial)",
538
+ "returns": "this",
539
+ "description": "Changes part of an item. The common changes are made in place — an answer finishing or stopping, a trace's steps, an approval's status — so focus and selection inside the item survive; anything else redraws the item."
540
+ },
541
+ {
542
+ "name": "appendText",
543
+ "signature": "appendText(id, text)",
544
+ "returns": "this",
545
+ "description": "Streams text into an answer, creating it when the id is new. Only the answer's last paragraph is redrawn."
546
+ },
547
+ {
548
+ "name": "appendBlock",
549
+ "signature": "appendBlock(id, block)",
550
+ "returns": "this",
551
+ "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."
552
+ },
553
+ {
554
+ "name": "announce",
555
+ "signature": "announce(text)",
556
+ "returns": "this",
557
+ "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."
558
+ },
559
+ {
560
+ "name": "remove",
561
+ "signature": "remove(id)",
562
+ "returns": "this",
563
+ "description": "Removes an item."
564
+ },
565
+ {
566
+ "name": "get",
567
+ "signature": "get(id)",
568
+ "returns": "ThreadItem|null",
569
+ "description": "An item as it stands, an answer's streamed text included."
570
+ },
571
+ {
572
+ "name": "getComponent",
573
+ "signature": "getComponent(id)",
574
+ "returns": "Component|null",
575
+ "description": "The main component drawn for an item: an answer's BlockView, a trace's RunTrace, an approval's ApprovalCard."
576
+ },
577
+ {
578
+ "name": "reveal",
579
+ "signature": "reveal(target)",
580
+ "returns": "boolean",
581
+ "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."
582
+ },
583
+ {
584
+ "name": "setArtifactState",
585
+ "signature": "setArtifactState(id, state)",
586
+ "returns": "this",
587
+ "description": "Reflects whether an artifact is open somewhere — an inspector, a drawer — on every card that names it, in every answer. See `BlockView#setArtifactState()`."
588
+ },
589
+ {
590
+ "name": "scrollToEnd",
591
+ "signature": "scrollToEnd()",
592
+ "returns": "this",
593
+ "description": "Scrolls to the end of the conversation."
594
+ }
595
+ ]
596
+ },
363
597
  "Alert": {
364
598
  "options": [
365
599
  {
@@ -555,6 +789,12 @@
555
789
  "default": "'Applications'",
556
790
  "description": "Navigation accessible label."
557
791
  },
792
+ {
793
+ "name": "moreLabel",
794
+ "type": "string",
795
+ "default": "'More actions'",
796
+ "description": "Name of a destination's overflow menu when its `actions` fold; every action name is followed by the destination's label."
797
+ },
558
798
  {
559
799
  "name": "header",
560
800
  "type": "Node|string|number|{toElement: () => Node|null}|null",
@@ -813,6 +1053,173 @@
813
1053
  "events": [],
814
1054
  "methods": []
815
1055
  },
1056
+ "ApprovalCard": {
1057
+ "options": [
1058
+ {
1059
+ "name": "title",
1060
+ "type": "string",
1061
+ "default": "''",
1062
+ "description": "What the agent wants to do, as a question: \"Send 3 payment reminders?\"."
1063
+ },
1064
+ {
1065
+ "name": "description",
1066
+ "type": "string",
1067
+ "default": "''",
1068
+ "description": "One line under the title: what follows from approving."
1069
+ },
1070
+ {
1071
+ "name": "icon",
1072
+ "type": "string|null",
1073
+ "default": "null",
1074
+ "description": "Icon name for the tile beside the title; none when null."
1075
+ },
1076
+ {
1077
+ "name": "tone",
1078
+ "type": "ApprovalTone",
1079
+ "default": "'blue'",
1080
+ "description": "Categorical tone of the icon tile."
1081
+ },
1082
+ {
1083
+ "name": "headingLevel",
1084
+ "type": "2|3|4|5|6",
1085
+ "default": "3",
1086
+ "description": "Element level of the title heading."
1087
+ },
1088
+ {
1089
+ "name": "status",
1090
+ "type": "ApprovalStatus",
1091
+ "default": "'pending'",
1092
+ "description": "Where the request stands."
1093
+ },
1094
+ {
1095
+ "name": "details",
1096
+ "type": "Node|Block[]|null",
1097
+ "default": "null",
1098
+ "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."
1099
+ },
1100
+ {
1101
+ "name": "preview",
1102
+ "type": "ApprovalPreview|null",
1103
+ "default": "null",
1104
+ "description": "What the request produces, behind a disclosure."
1105
+ },
1106
+ {
1107
+ "name": "fields",
1108
+ "type": "Record<string, FieldOptions>|null",
1109
+ "default": "null",
1110
+ "description": "The Edit form, keyed by value name. No fields, no Edit."
1111
+ },
1112
+ {
1113
+ "name": "values",
1114
+ "type": "Record<string, unknown>",
1115
+ "default": "{}",
1116
+ "description": "The values the request carries; the Edit form starts from them and `approve` reports them."
1117
+ },
1118
+ {
1119
+ "name": "confirmText",
1120
+ "type": "string|null",
1121
+ "default": "null",
1122
+ "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."
1123
+ },
1124
+ {
1125
+ "name": "reason",
1126
+ "type": "ApprovalReasonMode",
1127
+ "default": "'optional'",
1128
+ "description": "Whether Reject asks why."
1129
+ },
1130
+ {
1131
+ "name": "edited",
1132
+ "type": "boolean",
1133
+ "default": "false",
1134
+ "description": "Whether the values were already edited, for a request restored from a record. Without `editedKeys` every field is listed under \"Edited by you\"."
1135
+ },
1136
+ {
1137
+ "name": "editedKeys",
1138
+ "type": "string[]|null",
1139
+ "default": "null",
1140
+ "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."
1141
+ },
1142
+ {
1143
+ "name": "rejectReason",
1144
+ "type": "string|null",
1145
+ "default": "null",
1146
+ "description": "The reason a rejected request was given, for a request restored from a record."
1147
+ },
1148
+ {
1149
+ "name": "answeredBy",
1150
+ "type": "string|null",
1151
+ "default": "null",
1152
+ "description": "Who answers, as the verdict names them; the message `approvalCard.you` (\"you\") when null."
1153
+ },
1154
+ {
1155
+ "name": "answeredAt",
1156
+ "type": "string|Date|null",
1157
+ "default": "null",
1158
+ "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."
1159
+ },
1160
+ {
1161
+ "name": "now",
1162
+ "type": "(() => Date)|null",
1163
+ "default": "null",
1164
+ "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."
1165
+ },
1166
+ {
1167
+ "name": "keys",
1168
+ "type": "boolean",
1169
+ "default": "true",
1170
+ "description": "Whether A, E, and R act while focus is inside the pending card. `handleKey()` works either way."
1171
+ },
1172
+ {
1173
+ "name": "msg",
1174
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1175
+ "default": null,
1176
+ "description": "Localized messages."
1177
+ }
1178
+ ],
1179
+ "events": [
1180
+ {
1181
+ "name": "approve",
1182
+ "payload": "{values: Record<string, unknown>}",
1183
+ "description": "Approve listener."
1184
+ },
1185
+ {
1186
+ "name": "edit",
1187
+ "payload": "{values, changed, editedKeys}",
1188
+ "description": "Edit listener."
1189
+ },
1190
+ {
1191
+ "name": "reject",
1192
+ "payload": "{reason: string}",
1193
+ "description": "Reject listener."
1194
+ }
1195
+ ],
1196
+ "methods": [
1197
+ {
1198
+ "name": "update",
1199
+ "signature": "update([partial])",
1200
+ "returns": "this",
1201
+ "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."
1202
+ },
1203
+ {
1204
+ "name": "setStatus",
1205
+ "signature": "setStatus(status, [answer])",
1206
+ "returns": "this",
1207
+ "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."
1208
+ },
1209
+ {
1210
+ "name": "focus",
1211
+ "signature": "focus([options])",
1212
+ "returns": "this",
1213
+ "description": "Moves focus to the card, so a thread can bring the reader to a request when a run starts waiting on it."
1214
+ },
1215
+ {
1216
+ "name": "handleKey",
1217
+ "signature": "handleKey(event)",
1218
+ "returns": "boolean",
1219
+ "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."
1220
+ }
1221
+ ]
1222
+ },
816
1223
  "Aspect": {
817
1224
  "options": [
818
1225
  {
@@ -934,22 +1341,52 @@
934
1341
  "name": "status",
935
1342
  "type": "'online'|'away'|'busy'|'offline'|null",
936
1343
  "default": "null",
937
- "description": "Optional presence state."
1344
+ "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."
938
1345
  },
939
1346
  {
940
1347
  "name": "statusLabel",
941
1348
  "type": "string|null",
942
1349
  "default": "null",
943
1350
  "description": "Text alternative for the presence state."
944
- }
945
- ],
946
- "events": [],
1351
+ },
1352
+ {
1353
+ "name": "activity",
1354
+ "type": "AgentActivity|null",
1355
+ "default": "null",
1356
+ "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`."
1357
+ },
1358
+ {
1359
+ "name": "activityLabel",
1360
+ "type": "string|null",
1361
+ "default": "null",
1362
+ "description": "The activity's word, when the default (\"Working\", \"Needs you\", …) is not the one to show."
1363
+ },
1364
+ {
1365
+ "name": "animate",
1366
+ "type": "boolean",
1367
+ "default": "false",
1368
+ "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."
1369
+ },
1370
+ {
1371
+ "name": "phase",
1372
+ "type": "number|null",
1373
+ "default": "null",
1374
+ "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."
1375
+ },
1376
+ {
1377
+ "name": "msg",
1378
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1379
+ "default": null,
1380
+ "description": "Localized messages: the activity words, `agent.activity.<activity>`."
1381
+ }
1382
+ ],
1383
+ "events": [],
947
1384
  "methods": [
948
1385
  {
949
1386
  "name": "set",
950
1387
  "signature": "set(values)",
951
1388
  "returns": "this",
952
- "description": "Replaces avatar identity and presentation values."
1389
+ "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."
953
1390
  },
954
1391
  {
955
1392
  "name": "setStatus",
@@ -957,6 +1394,12 @@
957
1394
  "returns": "this",
958
1395
  "description": "Sets the presence state and its text alternative."
959
1396
  },
1397
+ {
1398
+ "name": "setActivity",
1399
+ "signature": "setActivity(activity, [label])",
1400
+ "returns": "this",
1401
+ "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."
1402
+ },
960
1403
  {
961
1404
  "name": "hasImage",
962
1405
  "signature": "hasImage()",
@@ -995,7 +1438,7 @@
995
1438
  "name": "tone",
996
1439
  "type": "BadgeTone|null",
997
1440
  "default": "null",
998
- "description": "Categorical colour — a project, a label, a module — from the tone palette rather than the status set, so a tag never reads as a warning. When set it decides the colour and `kind` is ignored for it; `variant` still applies. Unknown names are ignored."
1441
+ "description": "Categorical colour — a project, a label, a module — from the tone palette rather than the status set, so a tag never reads as a warning. When set it decides the colour and the shape — a tag's small corners instead of a status pill — and `kind` is ignored for it; `variant` still applies. Unknown names are ignored."
999
1442
  },
1000
1443
  {
1001
1444
  "name": "variant",
@@ -1097,6 +1540,107 @@
1097
1540
  ],
1098
1541
  "methods": []
1099
1542
  },
1543
+ "BlockView": {
1544
+ "options": [
1545
+ {
1546
+ "name": "blocks",
1547
+ "type": "Block[]",
1548
+ "default": "[]",
1549
+ "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."
1550
+ },
1551
+ {
1552
+ "name": "headingLevel",
1553
+ "type": "2|3|4|5",
1554
+ "default": "3",
1555
+ "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."
1556
+ },
1557
+ {
1558
+ "name": "size",
1559
+ "type": "'sm'|'md'",
1560
+ "default": "'sm'",
1561
+ "description": "Prose size: `'sm'` sets the answer at the interface size, for a conversation; `'md'` at the reading size, for a document."
1562
+ },
1563
+ {
1564
+ "name": "streaming",
1565
+ "type": "boolean",
1566
+ "default": "false",
1567
+ "description": "Whether more is still being written. The last block stays open to `appendText()`, and the root is busy until `end()` or `stop()`."
1568
+ },
1569
+ {
1570
+ "name": "sources",
1571
+ "type": "Source[]|null",
1572
+ "default": "null",
1573
+ "description": "The sources citations point at; their titles name the citation buttons."
1574
+ },
1575
+ {
1576
+ "name": "msg",
1577
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
1578
+ "default": null,
1579
+ "description": "Localized messages."
1580
+ }
1581
+ ],
1582
+ "events": [
1583
+ {
1584
+ "name": "cite",
1585
+ "payload": "{n: number, source: Source|null}",
1586
+ "description": "Citation listener."
1587
+ },
1588
+ {
1589
+ "name": "artifact",
1590
+ "payload": "{id: string}",
1591
+ "description": "Artifact listener."
1592
+ },
1593
+ {
1594
+ "name": "end",
1595
+ "payload": "Record<string, never>",
1596
+ "description": "End-of-stream listener."
1597
+ }
1598
+ ],
1599
+ "methods": [
1600
+ {
1601
+ "name": "setBlocks",
1602
+ "signature": "setBlocks(blocks, [options])",
1603
+ "returns": "this",
1604
+ "description": "Replaces every block, clearing a stopped state."
1605
+ },
1606
+ {
1607
+ "name": "append",
1608
+ "signature": "append(block)",
1609
+ "returns": "this",
1610
+ "description": "Adds a block after the last one. The blocks before it are left as they are."
1611
+ },
1612
+ {
1613
+ "name": "appendText",
1614
+ "signature": "appendText(text)",
1615
+ "returns": "this",
1616
+ "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."
1617
+ },
1618
+ {
1619
+ "name": "end",
1620
+ "signature": "end()",
1621
+ "returns": "this",
1622
+ "description": "Marks the answer finished."
1623
+ },
1624
+ {
1625
+ "name": "stop",
1626
+ "signature": "stop()",
1627
+ "returns": "this",
1628
+ "description": "Marks the answer stopped where it is, with a line saying so."
1629
+ },
1630
+ {
1631
+ "name": "setSources",
1632
+ "signature": "setSources(sources)",
1633
+ "returns": "this",
1634
+ "description": "Sets the sources citations point at."
1635
+ },
1636
+ {
1637
+ "name": "setArtifactState",
1638
+ "signature": "setArtifactState(id, state)",
1639
+ "returns": "this",
1640
+ "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."
1641
+ }
1642
+ ]
1643
+ },
1100
1644
  "Breadcrumb": {
1101
1645
  "options": [
1102
1646
  {
@@ -2458,132 +3002,401 @@
2458
3002
  }
2459
3003
  ]
2460
3004
  },
2461
- "Confirm": {
3005
+ "Composer": {
2462
3006
  "options": [
2463
3007
  {
2464
- "name": "title",
3008
+ "name": "label",
3009
+ "type": "string|null",
3010
+ "default": "null",
3011
+ "description": "Accessible name of the text and of the group around it. Omitted resolves `composer.label`, English `Message`."
3012
+ },
3013
+ {
3014
+ "name": "placeholder",
2465
3015
  "type": "string",
2466
3016
  "default": "''",
2467
- "description": "Confirmation title."
3017
+ "description": "Placeholder of the text."
2468
3018
  },
2469
3019
  {
2470
- "name": "message",
2471
- "type": "Node|string|number|null",
3020
+ "name": "value",
3021
+ "type": "string",
2472
3022
  "default": "''",
2473
- "description": "Confirmation message."
3023
+ "description": "Initial text. Without it, a saved draft is restored."
2474
3024
  },
2475
3025
  {
2476
- "name": "okLabel",
2477
- "type": "string",
2478
- "default": "'OK'",
2479
- "description": "Confirmation label."
3026
+ "name": "submitKey",
3027
+ "type": "'enter'|'mod+enter'",
3028
+ "default": "'enter'",
3029
+ "description": "`'enter'`: Enter sends and Shift+Enter breaks the line. `'mod+enter'`: Cmd+Enter (Ctrl+Enter elsewhere) sends and Enter breaks the line."
2480
3030
  },
2481
3031
  {
2482
- "name": "cancelLabel",
2483
- "type": "string",
2484
- "default": "'Cancel'",
2485
- "description": "Cancellation label."
3032
+ "name": "busy",
3033
+ "type": "boolean",
3034
+ "default": "false",
3035
+ "description": "Whether an agent is working: Send becomes Stop."
2486
3036
  },
2487
3037
  {
2488
- "name": "danger",
3038
+ "name": "disabled",
2489
3039
  "type": "boolean",
2490
3040
  "default": "false",
2491
- "description": "Whether the confirmation action is dangerous."
3041
+ "description": "Whether the composer takes no input."
2492
3042
  },
2493
3043
  {
2494
- "name": "confirmText",
3044
+ "name": "attachments",
3045
+ "type": "boolean",
3046
+ "default": "false",
3047
+ "description": "Whether files can be attached: an Attach button, paste, and drop."
3048
+ },
3049
+ {
3050
+ "name": "accept",
3051
+ "type": "string",
3052
+ "default": "''",
3053
+ "description": "File types accepted, in the `<input type=\"file\">` syntax (`'image/*,.pdf'`). Empty accepts every file."
3054
+ },
3055
+ {
3056
+ "name": "maxFiles",
3057
+ "type": "number",
3058
+ "default": "10",
3059
+ "description": "Most files one message carries."
3060
+ },
3061
+ {
3062
+ "name": "mentions",
3063
+ "type": "MentionSource|null",
3064
+ "default": "null",
3065
+ "description": "Enables `@` mentions."
3066
+ },
3067
+ {
3068
+ "name": "commands",
3069
+ "type": "LauncherItem[]|null",
3070
+ "default": "null",
3071
+ "description": "Commands opened by `/` on an empty text, in a Launcher; an item with `items` opens a page of further commands."
3072
+ },
3073
+ {
3074
+ "name": "context",
3075
+ "type": "ContextChip[]",
3076
+ "default": "[]",
3077
+ "description": "Initial context chips."
3078
+ },
3079
+ {
3080
+ "name": "hint",
3081
+ "type": "string",
3082
+ "default": "''",
3083
+ "description": "Quiet text in the bar beside Send."
3084
+ },
3085
+ {
3086
+ "name": "note",
3087
+ "type": "string",
3088
+ "default": "''",
3089
+ "description": "Quiet line under the composer."
3090
+ },
3091
+ {
3092
+ "name": "draftKey",
2495
3093
  "type": "string|null",
2496
3094
  "default": "null",
2497
- "description": "Text the reader must type before the confirm button enables — the name of what is about to be deleted, say. The dialog adds an input labelled \"Type <confirmText> to confirm\" (message `dialog.typeToConfirm`, `%1` standing for the text), focuses it, and enables the confirm button, and Enter, only while its value matches exactly, ignoring surrounding spaces."
2498
- }
2499
- ],
2500
- "events": [],
2501
- "methods": []
2502
- },
2503
- "ContextMenu": {
2504
- "options": [
3095
+ "description": "Key the unsent text is kept under (through `storage()`), restored on create and cleared on send."
3096
+ },
2505
3097
  {
2506
- "name": "items",
2507
- "type": "ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])",
3098
+ "name": "minRows",
3099
+ "type": "number",
3100
+ "default": "1",
3101
+ "description": "Rows the text never shrinks below, even when empty. Capped at `maxRows`."
3102
+ },
3103
+ {
3104
+ "name": "maxRows",
3105
+ "type": "number",
3106
+ "default": "10",
3107
+ "description": "Rows the text grows to before it scrolls."
3108
+ },
3109
+ {
3110
+ "name": "icons",
3111
+ "type": "{attach?: string, commands?: string}",
3112
+ "default": "{}",
3113
+ "description": "Glyph names for the Attach and Commands buttons (a paperclip, a book) where the application registered its own."
3114
+ },
3115
+ {
3116
+ "name": "tools",
3117
+ "type": "ComposerTool[]",
2508
3118
  "default": "[]",
2509
- "description": "Menu items and `'-'` separators, or a function returning them for the element the menu is opening on — which is how a row menu disables the actions that row does not allow. Returning an empty array cancels the opening."
3119
+ "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."
2510
3120
  },
2511
3121
  {
2512
- "name": "selector",
3122
+ "name": "sendLabel",
2513
3123
  "type": "string|null",
2514
3124
  "default": "null",
2515
- "description": "Restricts the menu to descendants matching this selector, and reports the matched element as the context of the selection. A table passes `'tbody tr'` here to get a per-row menu from one listener."
3125
+ "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."
3126
+ },
3127
+ {
3128
+ "name": "msg",
3129
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
3130
+ "default": null,
3131
+ "description": "Localized messages."
2516
3132
  }
2517
3133
  ],
2518
3134
  "events": [
2519
3135
  {
2520
- "name": "select",
2521
- "payload": "{value: unknown, item: MenuItem, context: Element|null}",
2522
- "description": "Selection listener."
3136
+ "name": "send",
3137
+ "payload": "{text, files, mentions, context}",
3138
+ "description": "Preventable send listener."
2523
3139
  },
2524
3140
  {
2525
- "name": "open",
2526
- "payload": "{context: Element|null}",
2527
- "description": "Open listener."
3141
+ "name": "stop",
3142
+ "payload": "Record<string, never>",
3143
+ "description": "Stop listener."
2528
3144
  },
2529
3145
  {
2530
- "name": "close",
3146
+ "name": "input",
3147
+ "payload": "{text: string}",
3148
+ "description": "Text listener."
3149
+ },
3150
+ {
3151
+ "name": "attach",
3152
+ "payload": "{files: File[]}",
3153
+ "description": "Preventable attach listener."
3154
+ },
3155
+ {
3156
+ "name": "remove",
3157
+ "payload": "{kind, id, file, chip}",
3158
+ "description": "Chip removal listener."
3159
+ },
3160
+ {
3161
+ "name": "mention",
3162
+ "payload": "{item: MentionItem}",
3163
+ "description": "Mention listener."
3164
+ },
3165
+ {
3166
+ "name": "command",
3167
+ "payload": "{item: LauncherItem}",
3168
+ "description": "Command listener."
3169
+ },
3170
+ {
3171
+ "name": "tool",
3172
+ "payload": "{id, tool}",
3173
+ "description": "Tool listener."
3174
+ },
3175
+ {
3176
+ "name": "historyprevious",
2531
3177
  "payload": "Record<string, never>",
2532
- "description": "Close listener."
3178
+ "description": "Listener for ArrowUp on an empty text."
2533
3179
  }
2534
3180
  ],
2535
3181
  "methods": [
2536
3182
  {
2537
- "name": "setItems",
2538
- "signature": "setItems(items)",
3183
+ "name": "focus",
3184
+ "signature": "focus()",
2539
3185
  "returns": "this",
2540
- "description": "Replaces the menu items."
3186
+ "description": "Focuses the text."
2541
3187
  },
2542
3188
  {
2543
- "name": "openAt",
2544
- "signature": "openAt(x, y, [context])",
3189
+ "name": "setValue",
3190
+ "signature": "setValue(text)",
2545
3191
  "returns": "this",
2546
- "description": "Opens the menu at a point in viewport coordinates."
3192
+ "description": "Replaces the text, keeps the draft in step, and puts the caret at the end. Emits nothing."
2547
3193
  },
2548
3194
  {
2549
- "name": "openAtElement",
2550
- "signature": "openAtElement(element)",
3195
+ "name": "insertText",
3196
+ "signature": "insertText(text)",
2551
3197
  "returns": "this",
2552
- "description": "Opens the menu against an element's box, which is where a keyboard invocation puts it."
3198
+ "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."
2553
3199
  },
2554
3200
  {
2555
- "name": "close",
2556
- "signature": "close()",
3201
+ "name": "clear",
3202
+ "signature": "clear()",
2557
3203
  "returns": "this",
2558
- "description": "Closes the menu."
3204
+ "description": "Empties the text, the attachments and the draft. Context chips stay. Emits nothing."
2559
3205
  },
2560
3206
  {
2561
- "name": "isOpen",
2562
- "signature": "isOpen()",
2563
- "returns": "boolean",
2564
- "description": "Reports whether the menu is open."
3207
+ "name": "setBusy",
3208
+ "signature": "setBusy(busy)",
3209
+ "returns": "this",
3210
+ "description": "Shows Stop in place of Send while an agent works; Escape in the text then emits `stop`."
2565
3211
  },
2566
3212
  {
2567
- "name": "getContext",
2568
- "signature": "getContext()",
2569
- "returns": "Element|null",
2570
- "description": "The element the open menu applies to — the `selector` match under the pointer, or the target."
3213
+ "name": "setHint",
3214
+ "signature": "setHint(text)",
3215
+ "returns": "this",
3216
+ "description": "Changes the quiet text in the bar beside Send — what Enter does now, or why sending waits. An empty text hides it."
2571
3217
  },
2572
3218
  {
2573
- "name": "destroy",
2574
- "signature": "destroy()",
2575
- "returns": "void",
2576
- "description": "Detaches the menu and removes its anchor."
2577
- }
2578
- ]
2579
- },
2580
- "CopyButton": {
2581
- "options": [
3219
+ "name": "setNote",
3220
+ "signature": "setNote(text)",
3221
+ "returns": "this",
3222
+ "description": "Changes the line under the composer, which also describes the text box. An empty text hides it."
3223
+ },
2582
3224
  {
2583
- "name": "text",
2584
- "type": "string|(() => string)",
2585
- "default": "''",
2586
- "description": "Text to copy, or a function returning it — a function is what a button beside a live value wants, so the copy is never stale."
3225
+ "name": "setDisabled",
3226
+ "signature": "setDisabled(disabled)",
3227
+ "returns": "this",
3228
+ "description": "Turns input on or off."
3229
+ },
3230
+ {
3231
+ "name": "update",
3232
+ "signature": "update([partial])",
3233
+ "returns": "this",
3234
+ "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."
3235
+ },
3236
+ {
3237
+ "name": "setTools",
3238
+ "signature": "setTools(tools)",
3239
+ "returns": "this",
3240
+ "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."
3241
+ },
3242
+ {
3243
+ "name": "setToolPressed",
3244
+ "signature": "setToolPressed(id, pressed)",
3245
+ "returns": "this",
3246
+ "description": "Presses or releases a tool, which makes it a toggle if it was a plain button. Emits nothing."
3247
+ },
3248
+ {
3249
+ "name": "addFiles",
3250
+ "signature": "addFiles(files)",
3251
+ "returns": "this",
3252
+ "description": "Attaches files, as far as `accept` and `maxFiles` allow. Emits `attach` with the files taken."
3253
+ },
3254
+ {
3255
+ "name": "addContext",
3256
+ "signature": "addContext(chip)",
3257
+ "returns": "this",
3258
+ "description": "Adds a context chip, or replaces the chip with the same id. Emits nothing."
3259
+ },
3260
+ {
3261
+ "name": "removeContext",
3262
+ "signature": "removeContext(id)",
3263
+ "returns": "this",
3264
+ "description": "Removes a context chip. Emits nothing."
3265
+ },
3266
+ {
3267
+ "name": "destroy",
3268
+ "signature": "destroy()",
3269
+ "returns": "void",
3270
+ "description": "Removes what the composer drew and the launcher it opened, and stops listening."
3271
+ }
3272
+ ]
3273
+ },
3274
+ "Confirm": {
3275
+ "options": [
3276
+ {
3277
+ "name": "title",
3278
+ "type": "string",
3279
+ "default": "''",
3280
+ "description": "Confirmation title."
3281
+ },
3282
+ {
3283
+ "name": "message",
3284
+ "type": "Node|string|number|null",
3285
+ "default": "''",
3286
+ "description": "Confirmation message."
3287
+ },
3288
+ {
3289
+ "name": "okLabel",
3290
+ "type": "string",
3291
+ "default": "'OK'",
3292
+ "description": "Confirmation label."
3293
+ },
3294
+ {
3295
+ "name": "cancelLabel",
3296
+ "type": "string",
3297
+ "default": "'Cancel'",
3298
+ "description": "Cancellation label."
3299
+ },
3300
+ {
3301
+ "name": "danger",
3302
+ "type": "boolean",
3303
+ "default": "false",
3304
+ "description": "Whether the confirmation action is dangerous."
3305
+ },
3306
+ {
3307
+ "name": "confirmText",
3308
+ "type": "string|null",
3309
+ "default": "null",
3310
+ "description": "Text the reader must type before the confirm button enables — the name of what is about to be deleted, say. The dialog adds an input labelled \"Type <confirmText> to confirm\" (message `dialog.typeToConfirm`, `%1` standing for the text), focuses it, and enables the confirm button, and Enter, only while its value matches exactly, ignoring surrounding spaces."
3311
+ }
3312
+ ],
3313
+ "events": [],
3314
+ "methods": []
3315
+ },
3316
+ "ContextMenu": {
3317
+ "options": [
3318
+ {
3319
+ "name": "items",
3320
+ "type": "ContextMenuEntry[]|((context: Element|null) => ContextMenuEntry[])",
3321
+ "default": "[]",
3322
+ "description": "Menu items and `'-'` separators, or a function returning them for the element the menu is opening on — which is how a row menu disables the actions that row does not allow. Returning an empty array cancels the opening."
3323
+ },
3324
+ {
3325
+ "name": "selector",
3326
+ "type": "string|null",
3327
+ "default": "null",
3328
+ "description": "Restricts the menu to descendants matching this selector, and reports the matched element as the context of the selection. A table passes `'tbody tr'` here to get a per-row menu from one listener."
3329
+ }
3330
+ ],
3331
+ "events": [
3332
+ {
3333
+ "name": "select",
3334
+ "payload": "{value: unknown, item: MenuItem, context: Element|null}",
3335
+ "description": "Selection listener."
3336
+ },
3337
+ {
3338
+ "name": "open",
3339
+ "payload": "{context: Element|null}",
3340
+ "description": "Open listener."
3341
+ },
3342
+ {
3343
+ "name": "close",
3344
+ "payload": "Record<string, never>",
3345
+ "description": "Close listener."
3346
+ }
3347
+ ],
3348
+ "methods": [
3349
+ {
3350
+ "name": "setItems",
3351
+ "signature": "setItems(items)",
3352
+ "returns": "this",
3353
+ "description": "Replaces the menu items."
3354
+ },
3355
+ {
3356
+ "name": "openAt",
3357
+ "signature": "openAt(x, y, [context])",
3358
+ "returns": "this",
3359
+ "description": "Opens the menu at a point in viewport coordinates."
3360
+ },
3361
+ {
3362
+ "name": "openAtElement",
3363
+ "signature": "openAtElement(element)",
3364
+ "returns": "this",
3365
+ "description": "Opens the menu against an element's box, which is where a keyboard invocation puts it."
3366
+ },
3367
+ {
3368
+ "name": "close",
3369
+ "signature": "close()",
3370
+ "returns": "this",
3371
+ "description": "Closes the menu."
3372
+ },
3373
+ {
3374
+ "name": "isOpen",
3375
+ "signature": "isOpen()",
3376
+ "returns": "boolean",
3377
+ "description": "Reports whether the menu is open."
3378
+ },
3379
+ {
3380
+ "name": "getContext",
3381
+ "signature": "getContext()",
3382
+ "returns": "Element|null",
3383
+ "description": "The element the open menu applies to — the `selector` match under the pointer, or the target."
3384
+ },
3385
+ {
3386
+ "name": "destroy",
3387
+ "signature": "destroy()",
3388
+ "returns": "void",
3389
+ "description": "Detaches the menu and removes its anchor."
3390
+ }
3391
+ ]
3392
+ },
3393
+ "CopyButton": {
3394
+ "options": [
3395
+ {
3396
+ "name": "text",
3397
+ "type": "string|(() => string)",
3398
+ "default": "''",
3399
+ "description": "Text to copy, or a function returning it — a function is what a button beside a live value wants, so the copy is never stale."
2587
3400
  },
2588
3401
  {
2589
3402
  "name": "label",
@@ -2873,7 +3686,13 @@
2873
3686
  "name": "format",
2874
3687
  "type": "string",
2875
3688
  "default": "'%d.%m.%Y'",
2876
- "description": "Kernel date format used for both endpoints."
3689
+ "description": "Kernel date format the reader types for both endpoints, shown while the field has focus. Numeric tokens only, since it is parsed."
3690
+ },
3691
+ {
3692
+ "name": "displayFormat",
3693
+ "type": "string|null",
3694
+ "default": "null",
3695
+ "description": "Format both endpoints are shown in while the field does not have focus. It is never parsed, so it may use any `formatDate()` token, month and weekday names included. Null shows `format`."
2877
3696
  },
2878
3697
  {
2879
3698
  "name": "separator",
@@ -3170,7 +3989,13 @@
3170
3989
  "name": "format",
3171
3990
  "type": "string",
3172
3991
  "default": "'%d.%m.%Y'",
3173
- "description": "Kernel date format."
3992
+ "description": "Kernel date format the reader types, shown while the field has focus. Numeric tokens only (`%d %e %m %Y %y %H %M %S`), since it is parsed."
3993
+ },
3994
+ {
3995
+ "name": "displayFormat",
3996
+ "type": "string|null",
3997
+ "default": "null",
3998
+ "description": "Format the field shows while it does not have focus, so a date reads as the rest of the screen writes dates. It is never parsed, so it may use any `formatDate()` token, month and weekday names included. Null shows `format`."
3174
3999
  },
3175
4000
  {
3176
4001
  "name": "time",
@@ -5912,6 +6737,24 @@
5912
6737
  }
5913
6738
  ]
5914
6739
  },
6740
+ "Kbd": {
6741
+ "options": [
6742
+ {
6743
+ "name": "size",
6744
+ "type": "'md'|'sm'",
6745
+ "default": "'md'",
6746
+ "description": "Keycap size; `sm` sits inside a button or a menu row."
6747
+ },
6748
+ {
6749
+ "name": "tone",
6750
+ "type": "'neutral'|'inherit'",
6751
+ "default": "'neutral'",
6752
+ "description": "`inherit` draws the keycaps in the surrounding ink — on a solid primary button, a dark toast — instead of the neutral surface keycap."
6753
+ }
6754
+ ],
6755
+ "events": [],
6756
+ "methods": []
6757
+ },
5915
6758
  "Launcher": {
5916
6759
  "options": [
5917
6760
  {
@@ -7769,6 +8612,54 @@
7769
8612
  "events": [],
7770
8613
  "methods": []
7771
8614
  },
8615
+ "ProseAnchors": {
8616
+ "options": [
8617
+ {
8618
+ "name": "selector",
8619
+ "type": "string",
8620
+ "default": "'h2[id], h3[id], h4[id]'",
8621
+ "description": "The headings that get a link, inside a `.zx-prose` under the root. A heading without an `id` has nothing to link to and is skipped."
8622
+ },
8623
+ {
8624
+ "name": "label",
8625
+ "type": "string",
8626
+ "default": "'Copy link to %1'",
8627
+ "description": "The link's accessible name; `%1` is the heading."
8628
+ },
8629
+ {
8630
+ "name": "title",
8631
+ "type": "string",
8632
+ "default": "'Copy link'",
8633
+ "description": "The link's tooltip."
8634
+ },
8635
+ {
8636
+ "name": "feedback",
8637
+ "type": "string",
8638
+ "default": "'Link copied'",
8639
+ "description": "What the live region says after a copy."
8640
+ },
8641
+ {
8642
+ "name": "feedbackDuration",
8643
+ "type": "number",
8644
+ "default": "2000",
8645
+ "description": "Milliseconds the tick and the message stay."
8646
+ },
8647
+ {
8648
+ "name": "href",
8649
+ "type": "(id: string) => string",
8650
+ "default": null,
8651
+ "description": "The address copied for a heading id. Defaults to the current address with its hash replaced (`sectionHref(location.href, id)`)."
8652
+ }
8653
+ ],
8654
+ "events": [
8655
+ {
8656
+ "name": "copy",
8657
+ "payload": null,
8658
+ "description": "Called with the address and whether the clipboard took it."
8659
+ }
8660
+ ],
8661
+ "methods": []
8662
+ },
7772
8663
  "Questionnaire": {
7773
8664
  "options": [
7774
8665
  {
@@ -8312,194 +9203,487 @@
8312
9203
  "description": ""
8313
9204
  },
8314
9205
  {
8315
- "name": "sortchange",
8316
- "payload": "{id:string|null,dir:ViewSortDirection|null}",
8317
- "description": ""
9206
+ "name": "sortchange",
9207
+ "payload": "{id:string|null,dir:ViewSortDirection|null}",
9208
+ "description": ""
9209
+ },
9210
+ {
9211
+ "name": "fieldvisibilitychange",
9212
+ "payload": "{visible:string[],hidden:string[]}",
9213
+ "description": ""
9214
+ },
9215
+ {
9216
+ "name": "fieldorderchange",
9217
+ "payload": "{order:string[]}",
9218
+ "description": ""
9219
+ },
9220
+ {
9221
+ "name": "statechange",
9222
+ "payload": "{state:RecordViewState,reason:string}",
9223
+ "description": ""
9224
+ }
9225
+ ],
9226
+ "methods": [
9227
+ {
9228
+ "name": "destroy",
9229
+ "signature": "destroy()",
9230
+ "returns": "void",
9231
+ "description": "Cleans up a directly instantiated base view and restores an enhanced target."
9232
+ },
9233
+ {
9234
+ "name": "setData",
9235
+ "signature": "setData(records)",
9236
+ "returns": "this",
9237
+ "description": "Replaces every record and clears selections whose ids disappeared."
9238
+ },
9239
+ {
9240
+ "name": "addData",
9241
+ "signature": "addData(records)",
9242
+ "returns": "this",
9243
+ "description": "Appends records without mutating the supplied array."
9244
+ },
9245
+ {
9246
+ "name": "updateRecord",
9247
+ "signature": "updateRecord(id, record)",
9248
+ "returns": "this",
9249
+ "description": "Replaces the record currently identified by `id`."
9250
+ },
9251
+ {
9252
+ "name": "removeRecord",
9253
+ "signature": "removeRecord(id)",
9254
+ "returns": "this",
9255
+ "description": "Removes one record by id."
9256
+ },
9257
+ {
9258
+ "name": "getRecord",
9259
+ "signature": "getRecord(id)",
9260
+ "returns": "ViewRecord|null",
9261
+ "description": "Returns a record by id."
9262
+ },
9263
+ {
9264
+ "name": "getData",
9265
+ "signature": "getData()",
9266
+ "returns": "ViewRecord[]",
9267
+ "description": "Returns a shallow copy in current display order."
9268
+ },
9269
+ {
9270
+ "name": "setFields",
9271
+ "signature": "setFields(fields)",
9272
+ "returns": "this",
9273
+ "description": "Replaces field descriptors while reconciling order, visibility, and sort by stable id."
9274
+ },
9275
+ {
9276
+ "name": "getFields",
9277
+ "signature": "getFields()",
9278
+ "returns": "ViewField[]",
9279
+ "description": "Returns cloned field descriptors in configured order."
9280
+ },
9281
+ {
9282
+ "name": "getVisibleFields",
9283
+ "signature": "getVisibleFields()",
9284
+ "returns": "ViewField[]",
9285
+ "description": "Returns visible cloned descriptors in configured order."
9286
+ },
9287
+ {
9288
+ "name": "getHiddenFields",
9289
+ "signature": "getHiddenFields()",
9290
+ "returns": "string[]",
9291
+ "description": "Returns hidden field ids in configured order."
9292
+ },
9293
+ {
9294
+ "name": "getFieldOrder",
9295
+ "signature": "getFieldOrder()",
9296
+ "returns": "string[]",
9297
+ "description": "Returns the complete field id order."
9298
+ },
9299
+ {
9300
+ "name": "getFieldControls",
9301
+ "signature": "getFieldControls()",
9302
+ "returns": "HTMLElement|null",
9303
+ "description": "Returns the element that lets a reader show, hide, and reorder this view's fields: the shared field chooser, or — for a `TableView` with `fieldControls: true` — the column chooser of its composed `Table`. Null when the view renders none (`fieldControls: false`). The element stays owned by the view: move it with {@link RecordView#mountFieldControls} rather than appending it elsewhere yourself, so `destroy()` can still find and remove it."
9304
+ },
9305
+ {
9306
+ "name": "mountFieldControls",
9307
+ "signature": "mountFieldControls(target)",
9308
+ "returns": "HTMLElement|null",
9309
+ "description": "Moves the view's field chooser into a host element — a list toolbar, a pane header — or, with `null`, back to where the view first rendered it. It keeps driving this view wherever it sits, and `destroy()` removes it from the host. `ListToolbar.bind()` calls this for every record view, which is how its field chooser ends up in the bar."
9310
+ },
9311
+ {
9312
+ "name": "setFieldVisible",
9313
+ "signature": "setFieldVisible(id, [visible], [options])",
9314
+ "returns": "this",
9315
+ "description": "Shows or hides one field. The final visible field cannot be hidden."
9316
+ },
9317
+ {
9318
+ "name": "toggleField",
9319
+ "signature": "toggleField(id, [options])",
9320
+ "returns": "this",
9321
+ "description": "Toggles one field."
9322
+ },
9323
+ {
9324
+ "name": "moveField",
9325
+ "signature": "moveField(id, targetId, [position], [options])",
9326
+ "returns": "this",
9327
+ "description": "Moves one field relative to another."
9328
+ },
9329
+ {
9330
+ "name": "setFieldOrder",
9331
+ "signature": "setFieldOrder(order, [options])",
9332
+ "returns": "this",
9333
+ "description": "Reconciles a preferred field order with every current field."
9334
+ },
9335
+ {
9336
+ "name": "setSort",
9337
+ "signature": "setSort(id, [dir], [options])",
9338
+ "returns": "this",
9339
+ "description": "Changes or clears the active sort."
9340
+ },
9341
+ {
9342
+ "name": "getSort",
9343
+ "signature": "getSort()",
9344
+ "returns": "ViewSort|null",
9345
+ "description": "Returns a copy of the active sort."
9346
+ },
9347
+ {
9348
+ "name": "getSelection",
9349
+ "signature": "getSelection()",
9350
+ "returns": "ViewRecord[]",
9351
+ "description": "Returns selected records in display order."
9352
+ },
9353
+ {
9354
+ "name": "getSelectionIds",
9355
+ "signature": "getSelectionIds()",
9356
+ "returns": "unknown[]",
9357
+ "description": "Returns selected record ids in display order."
9358
+ },
9359
+ {
9360
+ "name": "setSelection",
9361
+ "signature": "setSelection(ids, [options])",
9362
+ "returns": "this",
9363
+ "description": "Replaces selection from record ids."
9364
+ },
9365
+ {
9366
+ "name": "clearSelection",
9367
+ "signature": "clearSelection([options])",
9368
+ "returns": "this",
9369
+ "description": "Clears selection."
9370
+ },
9371
+ {
9372
+ "name": "toggleSelection",
9373
+ "signature": "toggleSelection(id, [options])",
9374
+ "returns": "this",
9375
+ "description": "Toggles a record selection, with optional multi-select range behavior."
9376
+ },
9377
+ {
9378
+ "name": "setLoading",
9379
+ "signature": "setLoading([loading])",
9380
+ "returns": "this",
9381
+ "description": "Marks the whole view busy without imposing a loading presentation."
9382
+ },
9383
+ {
9384
+ "name": "getViewState",
9385
+ "signature": "getViewState()",
9386
+ "returns": "RecordViewState",
9387
+ "description": "Returns JSON-safe, persistence-neutral view configuration."
9388
+ },
9389
+ {
9390
+ "name": "setViewState",
9391
+ "signature": "setViewState(state, [options])",
9392
+ "returns": "this",
9393
+ "description": "Restores common configuration. Unknown fields are ignored and newly introduced fields append."
9394
+ }
9395
+ ]
9396
+ },
9397
+ "RenderBlocks": {
9398
+ "options": [
9399
+ {
9400
+ "name": "headingLevel",
9401
+ "type": "2|3|4|5",
9402
+ "default": "3",
9403
+ "description": "Element level of a level-2 `heading` block."
9404
+ },
9405
+ {
9406
+ "name": "msg",
9407
+ "type": "(key: string, ...args: unknown[]) => string",
9408
+ "default": null,
9409
+ "description": "Message lookup for the few words the blocks add (code copy, artifact kinds)."
9410
+ }
9411
+ ],
9412
+ "events": [],
9413
+ "methods": []
9414
+ },
9415
+ "RunStatus": {
9416
+ "options": [
9417
+ {
9418
+ "name": "state",
9419
+ "type": "RunState",
9420
+ "default": "'queued'",
9421
+ "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."
9422
+ },
9423
+ {
9424
+ "name": "summary",
9425
+ "type": "string",
9426
+ "default": "''",
9427
+ "description": "One sentence on what is happening: \"Step 3 of 6 needs your approval.\" Text only."
9428
+ },
9429
+ {
9430
+ "name": "steps",
9431
+ "type": "RunSteps|null",
9432
+ "default": "null",
9433
+ "description": "Steps done out of the total, drawn as a progressbar."
9434
+ },
9435
+ {
9436
+ "name": "started",
9437
+ "type": "RunTime|null",
9438
+ "default": "null",
9439
+ "description": "When the run started."
9440
+ },
9441
+ {
9442
+ "name": "finished",
9443
+ "type": "RunTime|null",
9444
+ "default": "null",
9445
+ "description": "When it finished, failed, or was stopped. Shown once the run is over."
9446
+ },
9447
+ {
9448
+ "name": "workMs",
9449
+ "type": "number|null",
9450
+ "default": "null",
9451
+ "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."
9452
+ },
9453
+ {
9454
+ "name": "waitingSince",
9455
+ "type": "RunTime|null",
9456
+ "default": "null",
9457
+ "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`."
9458
+ },
9459
+ {
9460
+ "name": "tokens",
9461
+ "type": "RunTokens|null",
9462
+ "default": "null",
9463
+ "description": "Input and output tokens as `[in, out]`, or the total as one number."
9464
+ },
9465
+ {
9466
+ "name": "tokenBudget",
9467
+ "type": "number|null",
9468
+ "default": "null",
9469
+ "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."
9470
+ },
9471
+ {
9472
+ "name": "cost",
9473
+ "type": "RunCost|null",
9474
+ "default": "null",
9475
+ "description": "What the run has cost, against its budget."
9476
+ },
9477
+ {
9478
+ "name": "model",
9479
+ "type": "string|null",
9480
+ "default": "null",
9481
+ "description": "The model the agent runs on."
9482
+ },
9483
+ {
9484
+ "name": "actions",
9485
+ "type": "RunStatusAction[]",
9486
+ "default": "[]",
9487
+ "description": "Buttons under the summary."
9488
+ },
9489
+ {
9490
+ "name": "ticking",
9491
+ "type": "boolean",
9492
+ "default": "true",
9493
+ "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."
9494
+ },
9495
+ {
9496
+ "name": "compact",
9497
+ "type": "boolean|'icon'",
9498
+ "default": "false",
9499
+ "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."
8318
9500
  },
8319
9501
  {
8320
- "name": "fieldvisibilitychange",
8321
- "payload": "{visible:string[],hidden:string[]}",
8322
- "description": ""
9502
+ "name": "now",
9503
+ "type": "(() => Date)|null",
9504
+ "default": "null",
9505
+ "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."
8323
9506
  },
8324
9507
  {
8325
- "name": "fieldorderchange",
8326
- "payload": "{order:string[]}",
8327
- "description": ""
9508
+ "name": "locale",
9509
+ "type": "string",
9510
+ "default": null,
9511
+ "description": "BCP 47 tag for numbers and amounts; defaults to the active language."
8328
9512
  },
8329
9513
  {
8330
- "name": "statechange",
8331
- "payload": "{state:RecordViewState,reason:string}",
8332
- "description": ""
9514
+ "name": "msg",
9515
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
9516
+ "default": null,
9517
+ "description": "Localized messages: the state words (`agent.status.*`) and the `runStatus.*` labels."
8333
9518
  }
8334
9519
  ],
8335
- "methods": [
8336
- {
8337
- "name": "destroy",
8338
- "signature": "destroy()",
8339
- "returns": "void",
8340
- "description": "Cleans up a directly instantiated base view and restores an enhanced target."
8341
- },
9520
+ "events": [
8342
9521
  {
8343
- "name": "setData",
8344
- "signature": "setData(records)",
8345
- "returns": "this",
8346
- "description": "Replaces every record and clears selections whose ids disappeared."
8347
- },
9522
+ "name": "action",
9523
+ "payload": "{index: number, action: RunStatusAction}",
9524
+ "description": "Action listener."
9525
+ }
9526
+ ],
9527
+ "methods": [
8348
9528
  {
8349
- "name": "addData",
8350
- "signature": "addData(records)",
9529
+ "name": "update",
9530
+ "signature": "update(values)",
8351
9531
  "returns": "this",
8352
- "description": "Appends records without mutating the supplied array."
9532
+ "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."
8353
9533
  },
8354
9534
  {
8355
- "name": "updateRecord",
8356
- "signature": "updateRecord(id, record)",
8357
- "returns": "this",
8358
- "description": "Replaces the record currently identified by `id`."
8359
- },
9535
+ "name": "destroy",
9536
+ "signature": "destroy()",
9537
+ "returns": "void",
9538
+ "description": "Stops the clock, removes what the component drew, and restores an enhanced target."
9539
+ }
9540
+ ]
9541
+ },
9542
+ "RunTrace": {
9543
+ "options": [
8360
9544
  {
8361
- "name": "removeRecord",
8362
- "signature": "removeRecord(id)",
8363
- "returns": "this",
8364
- "description": "Removes one record by id."
9545
+ "name": "steps",
9546
+ "type": "TraceStep[]",
9547
+ "default": "[]",
9548
+ "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."
8365
9549
  },
8366
9550
  {
8367
- "name": "getRecord",
8368
- "signature": "getRecord(id)",
8369
- "returns": "ViewRecord|null",
8370
- "description": "Returns a record by id."
9551
+ "name": "open",
9552
+ "type": "boolean",
9553
+ "default": "false",
9554
+ "description": "Whether the step list starts open under its summary."
8371
9555
  },
8372
9556
  {
8373
- "name": "getData",
8374
- "signature": "getData()",
8375
- "returns": "ViewRecord[]",
8376
- "description": "Returns a shallow copy in current display order."
9557
+ "name": "label",
9558
+ "type": "string|null",
9559
+ "default": "null",
9560
+ "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."
8377
9561
  },
8378
9562
  {
8379
- "name": "setFields",
8380
- "signature": "setFields(fields)",
8381
- "returns": "this",
8382
- "description": "Replaces field descriptors while reconciling order, visibility, and sort by stable id."
9563
+ "name": "authors",
9564
+ "type": "Record<string, Author>",
9565
+ "default": "{}",
9566
+ "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."
8383
9567
  },
8384
9568
  {
8385
- "name": "getFields",
8386
- "signature": "getFields()",
8387
- "returns": "ViewField[]",
8388
- "description": "Returns cloned field descriptors in configured order."
9569
+ "name": "showArguments",
9570
+ "type": "boolean",
9571
+ "default": "true",
9572
+ "description": "Whether a step's disclosure shows the arguments its call was made with."
8389
9573
  },
8390
9574
  {
8391
- "name": "getVisibleFields",
8392
- "signature": "getVisibleFields()",
8393
- "returns": "ViewField[]",
8394
- "description": "Returns visible cloned descriptors in configured order."
9575
+ "name": "maxResult",
9576
+ "type": "number",
9577
+ "default": "4000",
9578
+ "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."
8395
9579
  },
8396
9580
  {
8397
- "name": "getHiddenFields",
8398
- "signature": "getHiddenFields()",
8399
- "returns": "string[]",
8400
- "description": "Returns hidden field ids in configured order."
9581
+ "name": "summary",
9582
+ "type": "boolean",
9583
+ "default": "true",
9584
+ "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."
8401
9585
  },
8402
9586
  {
8403
- "name": "getFieldOrder",
8404
- "signature": "getFieldOrder()",
8405
- "returns": "string[]",
8406
- "description": "Returns the complete field id order."
9587
+ "name": "kindIcons",
9588
+ "type": "boolean|null",
9589
+ "default": "null",
9590
+ "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."
8407
9591
  },
8408
9592
  {
8409
- "name": "getFieldControls",
8410
- "signature": "getFieldControls()",
8411
- "returns": "HTMLElement|null",
8412
- "description": "Returns the element that lets a reader show, hide, and reorder this view's fields: the shared field chooser, or — for a `TableView` with `fieldControls: true` — the column chooser of its composed `Table`. Null when the view renders none (`fieldControls: false`). The element stays owned by the view: move it with {@link RecordView#mountFieldControls} rather than appending it elsewhere yourself, so `destroy()` can still find and remove it."
9593
+ "name": "selectable",
9594
+ "type": "boolean",
9595
+ "default": "false",
9596
+ "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`."
8413
9597
  },
8414
9598
  {
8415
- "name": "mountFieldControls",
8416
- "signature": "mountFieldControls(target)",
8417
- "returns": "HTMLElement|null",
8418
- "description": "Moves the view's field chooser into a host element — a list toolbar, a pane header — or, with `null`, back to where the view first rendered it. It keeps driving this view wherever it sits, and `destroy()` removes it from the host. `ListToolbar.bind()` calls this for every record view, which is how its field chooser ends up in the bar."
9599
+ "name": "ticking",
9600
+ "type": "boolean",
9601
+ "default": "false",
9602
+ "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."
8419
9603
  },
8420
9604
  {
8421
- "name": "setFieldVisible",
8422
- "signature": "setFieldVisible(id, [visible], [options])",
8423
- "returns": "this",
8424
- "description": "Shows or hides one field. The final visible field cannot be hidden."
9605
+ "name": "now",
9606
+ "type": "(() => Date)|null",
9607
+ "default": "null",
9608
+ "description": "The clock `ticking` counts against, for an application whose world is fixed on another date; real time when null."
8425
9609
  },
8426
9610
  {
8427
- "name": "toggleField",
8428
- "signature": "toggleField(id, [options])",
8429
- "returns": "this",
8430
- "description": "Toggles one field."
9611
+ "name": "formatTime",
9612
+ "type": "((at: string) => string)|null",
9613
+ "default": "null",
9614
+ "description": "Writes a step's `at` for its meta line; \"10:31:05\" (the local ISO time as given) when null."
8431
9615
  },
8432
9616
  {
8433
- "name": "moveField",
8434
- "signature": "moveField(id, targetId, [position], [options])",
8435
- "returns": "this",
8436
- "description": "Moves one field relative to another."
9617
+ "name": "icons",
9618
+ "type": "Partial<Record<TraceKind, string>>",
9619
+ "default": "{}",
9620
+ "description": "Icon names per step kind, over the built-in `STEP_ICONS`."
8437
9621
  },
8438
9622
  {
8439
- "name": "setFieldOrder",
8440
- "signature": "setFieldOrder(order, [options])",
8441
- "returns": "this",
8442
- "description": "Reconciles a preferred field order with every current field."
8443
- },
9623
+ "name": "msg",
9624
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
9625
+ "default": null,
9626
+ "description": "Localized messages: the `runTrace.*` keys and the `agent.status.*` words."
9627
+ }
9628
+ ],
9629
+ "events": [
8444
9630
  {
8445
- "name": "setSort",
8446
- "signature": "setSort(id, [dir], [options])",
8447
- "returns": "this",
8448
- "description": "Changes or clears the active sort."
9631
+ "name": "toggle",
9632
+ "payload": "{id: string|null, open: boolean}",
9633
+ "description": "Disclosure listener."
8449
9634
  },
8450
9635
  {
8451
- "name": "getSort",
8452
- "signature": "getSort()",
8453
- "returns": "ViewSort|null",
8454
- "description": "Returns a copy of the active sort."
9636
+ "name": "reveal",
9637
+ "payload": "{id: string}",
9638
+ "description": "Reveal listener."
8455
9639
  },
8456
9640
  {
8457
- "name": "getSelection",
8458
- "signature": "getSelection()",
8459
- "returns": "ViewRecord[]",
8460
- "description": "Returns selected records in display order."
9641
+ "name": "select",
9642
+ "payload": "{id: string}",
9643
+ "description": "Selection listener (`selectable` traces)."
8461
9644
  },
8462
9645
  {
8463
- "name": "getSelectionIds",
8464
- "signature": "getSelectionIds()",
8465
- "returns": "unknown[]",
8466
- "description": "Returns selected record ids in display order."
8467
- },
9646
+ "name": "open",
9647
+ "payload": "{step: TraceStep, ref: ItemRef}",
9648
+ "description": "Listener for a step's links."
9649
+ }
9650
+ ],
9651
+ "methods": [
8468
9652
  {
8469
- "name": "setSelection",
8470
- "signature": "setSelection(ids, [options])",
9653
+ "name": "setLabel",
9654
+ "signature": "setLabel(label)",
8471
9655
  "returns": "this",
8472
- "description": "Replaces selection from record ids."
9656
+ "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."
8473
9657
  },
8474
9658
  {
8475
- "name": "clearSelection",
8476
- "signature": "clearSelection([options])",
9659
+ "name": "setSteps",
9660
+ "signature": "setSteps(steps)",
8477
9661
  "returns": "this",
8478
- "description": "Clears selection."
9662
+ "description": "Replaces every step. Open steps stay open, and focus on a step's row stays on that step."
8479
9663
  },
8480
9664
  {
8481
- "name": "toggleSelection",
8482
- "signature": "toggleSelection(id, [options])",
9665
+ "name": "upsert",
9666
+ "signature": "upsert(step)",
8483
9667
  "returns": "this",
8484
- "description": "Toggles a record selection, with optional multi-select range behavior."
9668
+ "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`."
8485
9669
  },
8486
9670
  {
8487
- "name": "setLoading",
8488
- "signature": "setLoading([loading])",
9671
+ "name": "expand",
9672
+ "signature": "expand([id])",
8489
9673
  "returns": "this",
8490
- "description": "Marks the whole view busy without imposing a loading presentation."
9674
+ "description": "Opens the step list, and the disclosure of the step `id` when one is given."
8491
9675
  },
8492
9676
  {
8493
- "name": "getViewState",
8494
- "signature": "getViewState()",
8495
- "returns": "RecordViewState",
8496
- "description": "Returns JSON-safe, persistence-neutral view configuration."
9677
+ "name": "collapse",
9678
+ "signature": "collapse([id])",
9679
+ "returns": "this",
9680
+ "description": "Closes the step list, or only the disclosure of the step `id` when one is given."
8497
9681
  },
8498
9682
  {
8499
- "name": "setViewState",
8500
- "signature": "setViewState(state, [options])",
9683
+ "name": "reveal",
9684
+ "signature": "reveal(id)",
8501
9685
  "returns": "this",
8502
- "description": "Restores common configuration. Unknown fields are ignored and newly introduced fields append."
9686
+ "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."
8503
9687
  }
8504
9688
  ]
8505
9689
  },
@@ -9480,6 +10664,67 @@
9480
10664
  }
9481
10665
  ]
9482
10666
  },
10667
+ "SourceList": {
10668
+ "options": [
10669
+ {
10670
+ "name": "sources",
10671
+ "type": "Source[]",
10672
+ "default": "[]",
10673
+ "description": "The sources, in the order an answer's `[n]` citations number them. Model text is data: every string reaches the page as text."
10674
+ },
10675
+ {
10676
+ "name": "label",
10677
+ "type": "string",
10678
+ "default": "'Sources'",
10679
+ "description": "The visible label the list is named by. Empty hides it and names the list with the `sourceList.label` message instead."
10680
+ },
10681
+ {
10682
+ "name": "layout",
10683
+ "type": "'chips'|'list'",
10684
+ "default": "'chips'",
10685
+ "description": "`'chips'` wraps short chips beside the label; `'list'` gives each source a full-width row with its title and site."
10686
+ },
10687
+ {
10688
+ "name": "numbered",
10689
+ "type": "boolean",
10690
+ "default": "true",
10691
+ "description": "Whether each source shows its number."
10692
+ },
10693
+ {
10694
+ "name": "icons",
10695
+ "type": "Partial<Record<SourceKind, string>>",
10696
+ "default": "{}",
10697
+ "description": "Icon names per source kind, over the built-in `SOURCE_ICONS`."
10698
+ },
10699
+ {
10700
+ "name": "msg",
10701
+ "type": "Record<string, string>|Record<string, Record<string, string>>",
10702
+ "default": null,
10703
+ "description": "Localized messages."
10704
+ }
10705
+ ],
10706
+ "events": [
10707
+ {
10708
+ "name": "select",
10709
+ "payload": "{source: Source, n: number}",
10710
+ "description": "Activation listener; `preventDefault()` keeps a web source from opening."
10711
+ }
10712
+ ],
10713
+ "methods": [
10714
+ {
10715
+ "name": "setSources",
10716
+ "signature": "setSources(sources)",
10717
+ "returns": "this",
10718
+ "description": "Replaces every source. Focus on a source stays on the source with the same `id`."
10719
+ },
10720
+ {
10721
+ "name": "highlight",
10722
+ "signature": "highlight(n)",
10723
+ "returns": "this",
10724
+ "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."
10725
+ }
10726
+ ]
10727
+ },
9483
10728
  "Spinner": {
9484
10729
  "options": [
9485
10730
  {
@@ -9810,6 +11055,18 @@
9810
11055
  "default": "'neutral'",
9811
11056
  "description": "Semantic intent. It tints the sparkline and never the value, which stays at full text contrast whatever intent a record carries."
9812
11057
  },
11058
+ {
11059
+ "name": "variant",
11060
+ "type": "StatTileVariant",
11061
+ "default": "'default'",
11062
+ "description": "`'default'` is a framed tile on its own surface, for a figure that stands among other content (a dashboard). `'plain'` drops the frame, the fill and the padding and sets the figure a size smaller, for a row of figures on a page (a record's amounts under its title). Reflected as `data-variant` on the root."
11063
+ },
11064
+ {
11065
+ "name": "emphasis",
11066
+ "type": "boolean",
11067
+ "default": "false",
11068
+ "description": "The figure leads its row: in a plain row it is set at the display size while the others stay smaller, on a framed tile one step above the display size. Give it to one tile per row. Reflected as `data-emphasis=\"true\"`."
11069
+ },
9813
11070
  {
9814
11071
  "name": "href",
9815
11072
  "type": "string|null",
@@ -10811,7 +12068,7 @@
10811
12068
  "name": "toneKey",
10812
12069
  "type": "TagValueReader",
10813
12070
  "default": "'tone'",
10814
- "description": "Optional item tone property or reader: a categorical tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`). A toned tag takes the palette's fill and ink, as a Badge with that `tone` does; a tone wins over a colour, and unknown names are ignored."
12071
+ "description": "Optional item tone property or reader: a categorical tone name from the Badge palette (`blue`, `teal`, `green`, `amber`, `orange`, `red`, `pink`, `violet`, `slate`). Every tag is built by `badge()`, so a toned tag is the Badge with that `tone` — the same shape, size, fill and ink it has in a list row or a record header; a tone wins over a colour, and unknown names are ignored."
10815
12072
  },
10816
12073
  {
10817
12074
  "name": "searchKeys",
@@ -11537,6 +12794,18 @@
11537
12794
  "default": "null",
11538
12795
  "description": "Label renderer."
11539
12796
  },
12797
+ {
12798
+ "name": "rowActions",
12799
+ "type": "((node: TreeNode) => Array<RowAction|Node>)|null",
12800
+ "default": "null",
12801
+ "description": "A row's actions: `{icon, label, onSelect(node), disabled?, danger?}` descriptors, or nodes placed as given. They rest out of sight and show while the row is pointed at, focused or selected; one or two show as icon buttons, more fold after the first into a \"More actions\" menu. Every descriptor is also in the row's context menu, and the focused row's actions follow it in the Tab order."
12802
+ },
12803
+ {
12804
+ "name": "moreLabel",
12805
+ "type": "string",
12806
+ "default": "'More actions'",
12807
+ "description": "Name of a row's overflow menu; every action name is followed by the row's name (\"More actions: Q3 plan\")."
12808
+ },
11540
12809
  {
11541
12810
  "name": "load",
11542
12811
  "type": "((node: TreeNode) => Promise<TreeNode[]>|TreeNode[])|null",