@linxiraos/pi-tui 1.4.11 → 1.4.12

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 (264) hide show
  1. package/CHANGELOG.md +33 -240
  2. package/README.md +4 -1
  3. package/THIRD-PARTY-NOTICES.txt +4 -5
  4. package/dist/types/apps/shell-visualizer.d.ts +24 -0
  5. package/dist/types/autocomplete.d.ts +20 -0
  6. package/dist/types/chat/cache-invalidation-marker.d.ts +15 -7
  7. package/dist/types/chat/chat-transcript-builder.d.ts +5 -3
  8. package/dist/types/chat/display-preferences.d.ts +2 -0
  9. package/dist/types/chat/extension-types.d.ts +72 -1
  10. package/dist/types/chat/image-loading.d.ts +2 -2
  11. package/dist/types/chat/messages.d.ts +2 -3
  12. package/dist/types/chat/read-tool-group.d.ts +15 -2
  13. package/dist/types/chat/skill-message.d.ts +1 -0
  14. package/dist/types/chat/spotlight.d.ts +203 -0
  15. package/dist/types/chat/tool-execution.d.ts +26 -5
  16. package/dist/types/chat/transcript-actions.d.ts +11 -0
  17. package/dist/types/chat/transcript-browser.d.ts +9 -0
  18. package/dist/types/chat/transcript-presentation.d.ts +164 -0
  19. package/dist/types/chat/ttsr-notification.d.ts +2 -0
  20. package/dist/types/chrome/message-frame.d.ts +2 -0
  21. package/dist/types/chrome/transcript-container.d.ts +27 -6
  22. package/dist/types/components/loader.d.ts +0 -2
  23. package/dist/types/components/markdown.d.ts +11 -1
  24. package/dist/types/components/settings-list.d.ts +12 -2
  25. package/dist/types/frame-rate.d.ts +18 -0
  26. package/dist/types/index.d.ts +3 -0
  27. package/dist/types/keybinding-matchers.d.ts +4 -1
  28. package/dist/types/kitty-graphics.d.ts +1 -1
  29. package/dist/types/motion-effects.d.ts +10 -0
  30. package/dist/types/native/encode.d.ts +2 -0
  31. package/dist/types/native/measure.d.ts +10 -0
  32. package/dist/types/native/overlay.d.ts +1 -1
  33. package/dist/types/native/quiet.d.ts +5 -0
  34. package/dist/types/native/reconcile.d.ts +6 -1
  35. package/dist/types/native/spans.d.ts +6 -0
  36. package/dist/types/native/state.d.ts +4 -0
  37. package/dist/types/overlays/agent-hub.d.ts +6 -0
  38. package/dist/types/overlays/link-browser.d.ts +55 -0
  39. package/dist/types/overlays/running-subagent-badge.d.ts +1 -4
  40. package/dist/types/overlays/spotlight-sheet.d.ts +36 -0
  41. package/dist/types/prompt/composer-attachments.d.ts +5 -2
  42. package/dist/types/prompt/composer-cache.d.ts +7 -2
  43. package/dist/types/prompt/composer.d.ts +6 -11
  44. package/dist/types/prompt/custom-editor.d.ts +8 -2
  45. package/dist/types/prompt/gradient-highlight.d.ts +2 -2
  46. package/dist/types/prompt/magic-keywords.d.ts +2 -0
  47. package/dist/types/prompt/model-mention-autocomplete.d.ts +9 -7
  48. package/dist/types/prompt/model-mention-syntax.d.ts +6 -0
  49. package/dist/types/prompt/prompt-action-autocomplete.d.ts +2 -1
  50. package/dist/types/prompt/welcome.d.ts +19 -0
  51. package/dist/types/render/extension-links.d.ts +0 -6
  52. package/dist/types/render/index.d.ts +1 -0
  53. package/dist/types/render/link-hints.d.ts +78 -0
  54. package/dist/types/render/render-utils.d.ts +0 -2
  55. package/dist/types/setup/scenes/types.d.ts +8 -0
  56. package/dist/types/setup/scenes/updates.d.ts +6 -0
  57. package/dist/types/setup/wizard.d.ts +7 -2
  58. package/dist/types/spinner-clock.d.ts +34 -0
  59. package/dist/types/status-line/component.d.ts +8 -4
  60. package/dist/types/status-line/host.d.ts +62 -0
  61. package/dist/types/status-line/index.d.ts +1 -0
  62. package/dist/types/status-line/prompt-cache.d.ts +14 -0
  63. package/dist/types/status-line/schema.d.ts +1 -1
  64. package/dist/types/status-line/startup.d.ts +6 -0
  65. package/dist/types/status-line/types.d.ts +8 -21
  66. package/dist/types/theme/schema.d.ts +28 -1
  67. package/dist/types/theme/symbols.d.ts +1 -1
  68. package/dist/types/theme/theme-class.d.ts +12 -2
  69. package/dist/types/theme/theme.d.ts +1 -1
  70. package/dist/types/theme/tui-adapters.d.ts +7 -0
  71. package/dist/types/thinking.d.ts +12 -0
  72. package/dist/types/tools/ask.d.ts +1 -1
  73. package/dist/types/tools/bash.d.ts +21 -0
  74. package/dist/types/tools/find.d.ts +9 -1
  75. package/dist/types/tools/grep.d.ts +2 -1
  76. package/dist/types/tools/grouped-file-output.d.ts +17 -0
  77. package/dist/types/tools/job-widget.d.ts +2 -2
  78. package/dist/types/tools/lsp.d.ts +4 -2
  79. package/dist/types/tools/native-view.d.ts +4 -0
  80. package/dist/types/tools/renderer.d.ts +9 -1
  81. package/dist/types/tools/shell-trace.d.ts +10 -0
  82. package/dist/types/tools/shell-viz-render.d.ts +6 -0
  83. package/dist/types/tools/shell-viz.d.ts +16 -0
  84. package/dist/types/tools/wait.d.ts +2 -2
  85. package/dist/types/tools/web-search-types.d.ts +1 -0
  86. package/dist/types/tools/write.d.ts +2 -0
  87. package/dist/types/tui.d.ts +15 -1
  88. package/package.json +15 -11
  89. package/src/apps/shell-visualizer.d.ts +24 -0
  90. package/src/apps/shell-visualizer.ts +167 -0
  91. package/src/autocomplete.d.ts +20 -0
  92. package/src/autocomplete.ts +14 -0
  93. package/src/chat/assistant-message.ts +11 -6
  94. package/src/chat/cache-invalidation-marker.d.ts +15 -7
  95. package/src/chat/cache-invalidation-marker.ts +18 -9
  96. package/src/chat/chat-transcript-builder.d.ts +5 -3
  97. package/src/chat/chat-transcript-builder.ts +16 -12
  98. package/src/chat/display-preferences.d.ts +2 -0
  99. package/src/chat/display-preferences.ts +3 -0
  100. package/src/chat/extension-types.d.ts +72 -1
  101. package/src/chat/extension-types.ts +74 -1
  102. package/src/chat/image-loading.d.ts +2 -2
  103. package/src/chat/image-loading.ts +2 -2
  104. package/src/chat/messages.d.ts +2 -3
  105. package/src/chat/messages.ts +3 -8
  106. package/src/chat/read-tool-group.d.ts +15 -2
  107. package/src/chat/read-tool-group.ts +201 -41
  108. package/src/chat/skill-message.d.ts +1 -0
  109. package/src/chat/skill-message.ts +4 -0
  110. package/src/chat/spotlight.d.ts +203 -0
  111. package/src/chat/spotlight.ts +460 -0
  112. package/src/chat/tool-execution.d.ts +26 -5
  113. package/src/chat/tool-execution.ts +360 -38
  114. package/src/chat/transcript-actions.d.ts +11 -0
  115. package/src/chat/transcript-actions.ts +13 -1
  116. package/src/chat/transcript-browser.d.ts +9 -0
  117. package/src/chat/transcript-browser.ts +18 -0
  118. package/src/chat/transcript-presentation.d.ts +164 -0
  119. package/src/chat/transcript-presentation.ts +642 -0
  120. package/src/chat/ttsr-notification.d.ts +25 -0
  121. package/src/chat/ttsr-notification.ts +5 -0
  122. package/src/chrome/message-frame.d.ts +2 -0
  123. package/src/chrome/message-frame.ts +7 -0
  124. package/src/chrome/message-notice.d.ts +58 -0
  125. package/src/chrome/transcript-container.d.ts +27 -6
  126. package/src/chrome/transcript-container.ts +317 -66
  127. package/src/components/editor.ts +25 -1
  128. package/src/components/loader.d.ts +0 -2
  129. package/src/components/loader.ts +30 -18
  130. package/src/components/markdown.d.ts +11 -1
  131. package/src/components/markdown.ts +41 -16
  132. package/src/components/settings-list.d.ts +12 -2
  133. package/src/components/settings-list.ts +29 -13
  134. package/src/frame-rate.d.ts +18 -0
  135. package/src/frame-rate.ts +36 -0
  136. package/src/hotkeys-markdown.ts +4 -1
  137. package/src/index.d.ts +3 -0
  138. package/src/index.ts +3 -0
  139. package/src/keybinding-matchers.d.ts +4 -1
  140. package/src/keybinding-matchers.ts +13 -12
  141. package/src/kitty-graphics.d.ts +1 -1
  142. package/src/kitty-graphics.ts +3 -2
  143. package/src/motion-effects.d.ts +10 -0
  144. package/src/motion-effects.ts +27 -0
  145. package/src/native/backend.ts +66 -7
  146. package/src/native/encode.d.ts +2 -0
  147. package/src/native/encode.ts +2 -0
  148. package/src/native/measure.d.ts +10 -0
  149. package/src/native/measure.ts +185 -0
  150. package/src/native/overlay.d.ts +1 -1
  151. package/src/native/overlay.ts +1 -1
  152. package/src/native/quiet.d.ts +5 -0
  153. package/src/native/quiet.ts +105 -0
  154. package/src/native/reconcile.d.ts +6 -1
  155. package/src/native/reconcile.ts +16 -10
  156. package/src/native/spans.d.ts +6 -0
  157. package/src/native/spans.ts +40 -0
  158. package/src/native/state.d.ts +4 -0
  159. package/src/native/state.ts +18 -0
  160. package/src/overlays/agent-hub.ts +15 -2
  161. package/src/overlays/ask-dialog.ts +1 -0
  162. package/src/overlays/btw-history-panel.ts +73 -6
  163. package/src/overlays/link-browser.ts +295 -0
  164. package/src/overlays/running-subagent-badge.ts +2 -9
  165. package/src/overlays/settings-defs.ts +1 -1
  166. package/src/overlays/settings-selector.ts +17 -3
  167. package/src/overlays/spotlight-sheet.ts +478 -0
  168. package/src/overlays/usage-dashboard.ts +6 -5
  169. package/src/prompt/composer-attachments.d.ts +5 -2
  170. package/src/prompt/composer-attachments.ts +6 -6
  171. package/src/prompt/composer-cache.ts +17 -16
  172. package/src/prompt/composer.ts +30 -123
  173. package/src/prompt/custom-editor.ts +17 -13
  174. package/src/prompt/gradient-highlight.d.ts +2 -2
  175. package/src/prompt/gradient-highlight.ts +5 -4
  176. package/src/prompt/magic-keywords.d.ts +2 -0
  177. package/src/prompt/magic-keywords.ts +4 -1
  178. package/src/prompt/model-mention-autocomplete.ts +73 -20
  179. package/src/prompt/model-mention-syntax.d.ts +6 -0
  180. package/src/prompt/model-mention-syntax.ts +9 -0
  181. package/src/prompt/prompt-action-autocomplete.ts +49 -33
  182. package/src/prompt/tips.txt +1 -0
  183. package/src/prompt/welcome.ts +104 -2
  184. package/src/render/extension-links.d.ts +0 -6
  185. package/src/render/extension-links.ts +0 -20
  186. package/src/render/index.d.ts +1 -0
  187. package/src/render/index.ts +1 -0
  188. package/src/render/link-hints.d.ts +78 -0
  189. package/src/render/link-hints.ts +299 -0
  190. package/src/render/render-utils.d.ts +0 -2
  191. package/src/render/render-utils.ts +0 -5
  192. package/src/setup/scenes/glyph.ts +1 -1
  193. package/src/setup/scenes/types.ts +8 -0
  194. package/src/setup/scenes/updates.ts +116 -0
  195. package/src/setup/wizard.ts +19 -8
  196. package/src/spinner-clock.d.ts +34 -0
  197. package/src/spinner-clock.ts +79 -0
  198. package/src/status-line/component.ts +145 -53
  199. package/src/status-line/host.ts +51 -0
  200. package/src/status-line/index.ts +1 -0
  201. package/src/status-line/presets.ts +3 -1
  202. package/src/status-line/prompt-cache.ts +154 -0
  203. package/src/status-line/schema.ts +1 -1
  204. package/src/status-line/segments.ts +33 -22
  205. package/src/status-line/startup.ts +22 -4
  206. package/src/status-line/types.ts +8 -22
  207. package/src/stdin-buffer.ts +89 -46
  208. package/src/terminal-capabilities.ts +3 -3
  209. package/src/terminal.ts +1 -8
  210. package/src/theme/loader.ts +3 -2
  211. package/src/theme/schema.d.ts +28 -1
  212. package/src/theme/schema.ts +30 -1
  213. package/src/theme/symbols.d.ts +1 -1
  214. package/src/theme/symbols.ts +15 -3
  215. package/src/theme/theme-class.d.ts +12 -2
  216. package/src/theme/theme-class.ts +23 -0
  217. package/src/theme/theme-schema.json +1 -1
  218. package/src/theme/theme.d.ts +1 -1
  219. package/src/theme/theme.ts +3 -7
  220. package/src/theme/tui-adapters.d.ts +7 -0
  221. package/src/theme/tui-adapters.ts +33 -1
  222. package/src/thinking.d.ts +12 -0
  223. package/src/thinking.ts +31 -0
  224. package/src/tools/ask.d.ts +1 -1
  225. package/src/tools/ask.ts +99 -38
  226. package/src/tools/ast-edit.ts +51 -32
  227. package/src/tools/ast-grep.ts +31 -19
  228. package/src/tools/bash.d.ts +21 -0
  229. package/src/tools/bash.ts +166 -24
  230. package/src/tools/find.d.ts +9 -1
  231. package/src/tools/find.ts +23 -2
  232. package/src/tools/grep.d.ts +2 -1
  233. package/src/tools/grep.ts +52 -36
  234. package/src/tools/grouped-file-output.d.ts +17 -0
  235. package/src/tools/grouped-file-output.ts +20 -2
  236. package/src/tools/job-widget.d.ts +2 -2
  237. package/src/tools/job-widget.ts +2 -2
  238. package/src/tools/lsp.d.ts +4 -2
  239. package/src/tools/lsp.ts +537 -642
  240. package/src/tools/native-view.d.ts +4 -0
  241. package/src/tools/native-view.ts +8 -2
  242. package/src/tools/renderer.d.ts +9 -1
  243. package/src/tools/renderer.ts +9 -1
  244. package/src/tools/shell-trace.d.ts +10 -0
  245. package/src/tools/shell-trace.ts +80 -0
  246. package/src/tools/shell-viz-render.d.ts +6 -0
  247. package/src/tools/shell-viz-render.ts +156 -0
  248. package/src/tools/shell-viz.d.ts +16 -0
  249. package/src/tools/shell-viz.ts +181 -0
  250. package/src/tools/streaming-output.ts +18 -8
  251. package/src/tools/wait.d.ts +2 -2
  252. package/src/tools/wait.ts +39 -34
  253. package/src/tools/web-search-types.d.ts +1 -0
  254. package/src/tools/web-search-types.ts +1 -0
  255. package/src/tools/write.d.ts +2 -0
  256. package/src/tools/write.ts +2 -0
  257. package/src/tui.d.ts +15 -1
  258. package/src/tui.ts +63 -6
  259. package/src/windows-input-mode.ts +7 -1
  260. package/dist/types/chat/collab-prompt-message.d.ts +0 -14
  261. package/dist/types/chrome/collab-qrcode.d.ts +0 -35
  262. package/src/chat/collab-prompt-message.d.ts +0 -14
  263. package/src/chat/collab-prompt-message.ts +0 -46
  264. package/src/chrome/collab-qrcode.ts +0 -99
@@ -0,0 +1,203 @@
1
+ import type { TspPropNode, TspTone } from "@linxiraos/pi-wire";
2
+ import type { NativeNode, NativeUiEvent } from "../native/node";
3
+ import type { Component } from "../tui";
4
+ /** Original lines a result's heat and the sheet cover; later lines are shown in neither. */
5
+ export declare const SPOTLIGHT_VIEW_LINES = 5000;
6
+ /** The original of a result whose text shaping changed. */
7
+ export interface SpotlightOriginal {
8
+ /** Session artifact holding the original text (`artifact://N`). */
9
+ url: string;
10
+ /** Its line count. */
11
+ lines: number;
12
+ /** Line number of its first line: a `read` window's first file line, else 1. */
13
+ start: number;
14
+ /** The file a `read` showed (picks the sheet's grammar). */
15
+ path?: string;
16
+ /**
17
+ * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): Spotlight's score as
18
+ * `0`–`9` relative to the result's hottest line, `-` for a line it never scored. Lines past the end are unscored.
19
+ */
20
+ heat: string;
21
+ /** Runs of original lines the model was shown verbatim, `[first, last]` 1-based positions in the original. */
22
+ kept: [number, number][];
23
+ /**
24
+ * One {@link SpotlightReason} character per original line, over the span {@link heat} covers: why shaping showed or
25
+ * hid the line. Absent on traces written before it.
26
+ */
27
+ why?: string;
28
+ /** How the step that cut by rank chose its lines; absent when no step ranked them. */
29
+ rank?: SpotlightRank;
30
+ /**
31
+ * One entry per line of the text the model saw (of a held-out result: the text it would have seen): the original
32
+ * line it shows (1-based position in the original), the `[first, last]` run a marker stands for, or null for a line
33
+ * of its own (a shaping note).
34
+ */
35
+ map?: (number | [number, number] | null)[];
36
+ /** A held-out result's would-be text, the cut the model was not shown (`artifact://N`). */
37
+ shapedUrl?: string;
38
+ }
39
+ /**
40
+ * Why shaping showed or hid one original line ({@link SpotlightOriginal.why}). Shown: `a` won on its score, `s`
41
+ * structure kept regardless of score (head and tail lines, signatures, headings, table headers), `n` named by the
42
+ * intent or the conversation, `c` context (a neighbour of a chosen line, or a lone gap filled). Hidden: `b` ranked
43
+ * below the cutoff or past the budget, `r` seen in an earlier call, `f` folded by structure (an outline body, a doc
44
+ * section, test-run noise, dump rows). `-` unknown.
45
+ */
46
+ export type SpotlightReason = "a" | "s" | "n" | "c" | "b" | "r" | "f" | "-";
47
+ /** Whether a {@link SpotlightReason} shows the line. */
48
+ export declare function reasonShows(reason: SpotlightReason): boolean;
49
+ /** The reason for original line `i` (0-based), or undefined past the trace or without one. */
50
+ export declare function reasonAt(why: string | undefined, i: number): SpotlightReason | undefined;
51
+ /**
52
+ * The ranking of the step that cut by rank ({@link SpotlightOriginal.rank}): a line's score is the sum of its parts,
53
+ * and the step kept the best lines while its budget lasted.
54
+ */
55
+ export interface SpotlightRank {
56
+ /**
57
+ * The parts a score adds up, in order, each in [0, 1] (shaping writes one; older traces may carry two, the ranks of
58
+ * `Spotlight` and of `word overlap`).
59
+ */
60
+ parts: string[];
61
+ /** The highest score a line can reach. */
62
+ max: number;
63
+ /** Per part, its value on every original line over the span {@link SpotlightOriginal.heat} covers ({@link encodeRankPart}). */
64
+ values: string[];
65
+ /** The lowest score the step kept on rank. */
66
+ cutoff: number;
67
+ /** Characters the step could show, and how many it showed; absent for a step with no character budget. */
68
+ budget?: number;
69
+ used?: number;
70
+ /** The last line kept on rank (1-based position in the original) and the characters it cost. */
71
+ last?: {
72
+ line: number;
73
+ chars: number;
74
+ };
75
+ }
76
+ /** One {@link SpotlightRank.values} entry: two base-36 digits per line, each value relative to `max`. */
77
+ export declare function encodeRankPart(values: readonly number[], max: number): string;
78
+ /** The value of original line `i` (0-based) in an {@link encodeRankPart} string; 0 past its end. */
79
+ export declare function rankPartAt(encoded: string, i: number, max: number): number;
80
+ /**
81
+ * What a result's Spotlight requests sent besides the output lines they ranked (`POST /v1/spotlight`): the agent's
82
+ * state at the call, the command that produced the output, the question its lines were ranked under, and the model.
83
+ */
84
+ export interface SpotlightRequestParams {
85
+ /** The user's first message of the session. */
86
+ task: string;
87
+ /** Up to three earlier bash commands of the session, oldest first. */
88
+ commands: string[];
89
+ /** The agent's text before the call. */
90
+ said: string;
91
+ /** The call's intent argument. */
92
+ intent: string;
93
+ /** The command, code or `read <path>` that produced the output. */
94
+ source: string;
95
+ /** The probe the lines were ranked under: Spotlight scores each line's relevance to the agent's current call. */
96
+ probe: string;
97
+ model: string;
98
+ thinking: string;
99
+ }
100
+ /** `details.spotlight`: one tool result as shaping left it. */
101
+ export interface SpotlightDetails {
102
+ tool: string;
103
+ /** The shaping steps that ran (`outline`, `window`, …; `none` for a passthrough). */
104
+ steps: string[];
105
+ inChars: number;
106
+ outChars: number;
107
+ /** o200k tokens of the original and of the text the model saw. */
108
+ inTokens: number;
109
+ outTokens: number;
110
+ /**
111
+ * Size of the plain (unshaped) result for the same call (a spilled output's capped text, a read's page), notices
112
+ * included. Absent on traces written before pi recorded it.
113
+ */
114
+ plainChars?: number;
115
+ plainTokens?: number;
116
+ /**
117
+ * `plainTokens - outTokens` for a changed (or held-out) result, else 0: negative for a column-cap cut longer than
118
+ * the preview it replaced. On older traces `inTokens - outTokens`.
119
+ */
120
+ savedTokens: number;
121
+ /** The score-free coin skipped Spotlight: the result was shaped by the no-score rules. Absent otherwise. */
122
+ scoreFree?: boolean;
123
+ /**
124
+ * The cut saved too few tokens against the plain result to apply, so the model got the plain text (`steps` ends
125
+ * with `plain-cap`, the out sizes are the plain text's): the would-be cut's size. Absent otherwise.
126
+ */
127
+ cappedChars?: number;
128
+ cappedTokens?: number;
129
+ /**
130
+ * Shaping would have changed the text, but the result was held out at random: the model saw the plain result. The
131
+ * sizes, steps and {@link original} describe the would-be cut. Absent otherwise.
132
+ */
133
+ holdout?: boolean;
134
+ /**
135
+ * Transcripts from before the edit gate was removed: the gate kept a read pi guessed the agent would edit whole, and
136
+ * the model got the plain page. Like {@link holdout}, the sizes, steps and {@link original} describe the would-be
137
+ * cut, but `savedTokens` is 0. pi no longer writes it.
138
+ */
139
+ gated?: boolean;
140
+ /** Present only when shaping changed the text, or would have ({@link holdout}, {@link gated}). */
141
+ original?: SpotlightOriginal;
142
+ /** Present with {@link original} when Spotlight ranked the result's lines. */
143
+ request?: SpotlightRequestParams;
144
+ }
145
+ /**
146
+ * Tokens the shaped text saves against the plain result (negative: it costs more), or against the original on
147
+ * traces without {@link SpotlightDetails.plainTokens}.
148
+ */
149
+ export declare function spotlightSaving(spotlight: SpotlightDetails): number;
150
+ /** The trace a result's details carry, or undefined when the experiment did not shape it. */
151
+ export declare function spotlightDetails(details: unknown): SpotlightDetails | undefined;
152
+ /** The {@link SpotlightOriginal.heat} of per-line scores: each relative to the best, in ten steps. */
153
+ export declare function encodeHeat(scores: readonly (number | null)[]): string;
154
+ /** The heat of original line `i` (0-based) in [0, 1], or undefined when Spotlight never scored it. */
155
+ export declare function heatAt(heat: string, i: number): number | undefined;
156
+ /** {@link SpotlightOriginal.kept} of a per-line kept mask. */
157
+ export declare function keptRanges(kept: readonly boolean[]): [number, number][];
158
+ /** Whether original line `i` (0-based) scored hot: a heat digit of {@link HOT_DIGIT} or more. */
159
+ export declare function spotlightHot(heat: string, i: number): boolean;
160
+ /**
161
+ * The tone the sheet and the notice give original line `i` (0-based): why shaping showed it (`accent` score,
162
+ * `neutral` structure, `user` named, `info` context), `error` for a hidden line that scored hot; undefined for any
163
+ * other hidden line and for a line without a reason.
164
+ */
165
+ export declare function spotlightTone(original: SpotlightOriginal, i: number): TspTone | undefined;
166
+ /**
167
+ * The hover card of a changed result's notice: its heat as at most {@link NOTICE_BARS} bars (each the hottest of its
168
+ * lines, tinted by the most notable reason among them), then how many lines the model was shown, or of a held-out
169
+ * result would have been.
170
+ */
171
+ export declare function spotlightNoticeCard(original: SpotlightOriginal, heldOut?: boolean): TspPropNode;
172
+ /**
173
+ * The notice row under one tool card (role `zeta.tool.spotlight`, key `spotlight:<toolCallId>`): muted for a
174
+ * passthrough (its star alone, named by its tooltip) and for a held-out result, accent for a changed result
175
+ * ({@link noticeSpans}). One with an original (changed or held out) has a hover card charting its heat
176
+ * ({@link spotlightNoticeCard}) and a click that opens its sheet through the host's transcript actions. A native
177
+ * transcript block of its own, placed right after its card ({@link Component.nativeTrailers}), so it shows while the
178
+ * card is collapsed; nothing in the terminal rows.
179
+ */
180
+ export declare class SpotlightNotice implements Component {
181
+ #private;
182
+ constructor(toolCallId: string, spotlight: SpotlightDetails, reduced: string);
183
+ update(spotlight: SpotlightDetails, reduced: string): void;
184
+ /** Hidden with its card (tool activity hidden). */
185
+ setHidden(hidden: boolean): void;
186
+ describe(): NativeNode;
187
+ /** Never mounted in the terminal rows. */
188
+ render(): readonly string[];
189
+ invalidate(): void;
190
+ handleNativeEvent(event: NativeUiEvent): void;
191
+ }
192
+ /** The notices of one transcript block's calls, in the order the calls first reported a trace. */
193
+ export declare class SpotlightNotices {
194
+ #private;
195
+ /** Records call `toolCallId`'s final result; true when a notice appeared or went. */
196
+ set(toolCallId: string, details: unknown, reduced: string): boolean;
197
+ setHidden(hidden: boolean): void;
198
+ /**
199
+ * The notice blocks, the same array while none came or went; `shown` drops the notices of calls a
200
+ * transcript presenter hides (a fresh array then).
201
+ */
202
+ list(shown?: (toolCallId: string) => boolean): readonly Component[];
203
+ }
@@ -0,0 +1,460 @@
1
+ /**
2
+ * The Spotlight experiment's trace on a tool result (`details.spotlight`, written by the coding agent's shaping
3
+ * hooks and persisted with the message): what shaping did to the model-facing text, and, when it changed
4
+ * it, where the original is and how Spotlight scored and kept its lines. A native transcript draws it as a notice
5
+ * row under the tool card ({@link SpotlightNotice}); a click on a "saved" or "held out" notice opens the sheet.
6
+ */
7
+ import { formatNumber, isRecord } from "@linxiraos/pi-utils";
8
+ import type { TspPropNode, TspSpan, TspTone } from "@linxiraos/pi-wire";
9
+ import { col, node, propNode, span, text } from "../native/describe";
10
+ import type { NativeNode, NativeUiEvent } from "../native/node";
11
+ import type { Component } from "../tui";
12
+ import { hasTranscriptActions, runTranscriptAction } from "./transcript-actions";
13
+
14
+ /** Original lines a result's heat and the sheet cover; later lines are shown in neither. */
15
+ export const SPOTLIGHT_VIEW_LINES = 5_000;
16
+
17
+ /** The original of a result whose text shaping changed. */
18
+ export interface SpotlightOriginal {
19
+ /** Session artifact holding the original text (`artifact://N`). */
20
+ url: string;
21
+ /** Its line count. */
22
+ lines: number;
23
+ /** Line number of its first line: a `read` window's first file line, else 1. */
24
+ start: number;
25
+ /** The file a `read` showed (picks the sheet's grammar). */
26
+ path?: string;
27
+ /**
28
+ * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): Spotlight's score as
29
+ * `0`–`9` relative to the result's hottest line, `-` for a line it never scored. Lines past the end are unscored.
30
+ */
31
+ heat: string;
32
+ /** Runs of original lines the model was shown verbatim, `[first, last]` 1-based positions in the original. */
33
+ kept: [number, number][];
34
+ /**
35
+ * One {@link SpotlightReason} character per original line, over the span {@link heat} covers: why shaping showed or
36
+ * hid the line. Absent on traces written before it.
37
+ */
38
+ why?: string;
39
+ /** How the step that cut by rank chose its lines; absent when no step ranked them. */
40
+ rank?: SpotlightRank;
41
+ /**
42
+ * One entry per line of the text the model saw (of a held-out result: the text it would have seen): the original
43
+ * line it shows (1-based position in the original), the `[first, last]` run a marker stands for, or null for a line
44
+ * of its own (a shaping note).
45
+ */
46
+ map?: (number | [number, number] | null)[];
47
+ /** A held-out result's would-be text, the cut the model was not shown (`artifact://N`). */
48
+ shapedUrl?: string;
49
+ }
50
+
51
+ /**
52
+ * Why shaping showed or hid one original line ({@link SpotlightOriginal.why}). Shown: `a` won on its score, `s`
53
+ * structure kept regardless of score (head and tail lines, signatures, headings, table headers), `n` named by the
54
+ * intent or the conversation, `c` context (a neighbour of a chosen line, or a lone gap filled). Hidden: `b` ranked
55
+ * below the cutoff or past the budget, `r` seen in an earlier call, `f` folded by structure (an outline body, a doc
56
+ * section, test-run noise, dump rows). `-` unknown.
57
+ */
58
+ export type SpotlightReason = "a" | "s" | "n" | "c" | "b" | "r" | "f" | "-";
59
+
60
+ /** Whether a {@link SpotlightReason} shows the line. */
61
+ export function reasonShows(reason: SpotlightReason): boolean {
62
+ return reason === "a" || reason === "s" || reason === "n" || reason === "c";
63
+ }
64
+
65
+ /** The reason for original line `i` (0-based), or undefined past the trace or without one. */
66
+ export function reasonAt(why: string | undefined, i: number): SpotlightReason | undefined {
67
+ const c = why?.[i];
68
+ return c !== undefined && "asncbrf-".includes(c) ? (c as SpotlightReason) : undefined;
69
+ }
70
+
71
+ /**
72
+ * The ranking of the step that cut by rank ({@link SpotlightOriginal.rank}): a line's score is the sum of its parts,
73
+ * and the step kept the best lines while its budget lasted.
74
+ */
75
+ export interface SpotlightRank {
76
+ /**
77
+ * The parts a score adds up, in order, each in [0, 1] (shaping writes one; older traces may carry two, the ranks of
78
+ * `Spotlight` and of `word overlap`).
79
+ */
80
+ parts: string[];
81
+ /** The highest score a line can reach. */
82
+ max: number;
83
+ /** Per part, its value on every original line over the span {@link SpotlightOriginal.heat} covers ({@link encodeRankPart}). */
84
+ values: string[];
85
+ /** The lowest score the step kept on rank. */
86
+ cutoff: number;
87
+ /** Characters the step could show, and how many it showed; absent for a step with no character budget. */
88
+ budget?: number;
89
+ used?: number;
90
+ /** The last line kept on rank (1-based position in the original) and the characters it cost. */
91
+ last?: { line: number; chars: number };
92
+ }
93
+
94
+ /** Levels of one {@link encodeRankPart} value: two base-36 digits. */
95
+ const RANK_LEVELS = 36 * 36 - 1;
96
+
97
+ /** One {@link SpotlightRank.values} entry: two base-36 digits per line, each value relative to `max`. */
98
+ export function encodeRankPart(values: readonly number[], max: number): string {
99
+ const n = Math.min(values.length, SPOTLIGHT_VIEW_LINES);
100
+ let out = "";
101
+ for (let i = 0; i < n; i++) {
102
+ const level = max > 0 ? Math.round(Math.min(1, Math.max(0, values[i] / max)) * RANK_LEVELS) : 0;
103
+ out += level.toString(36).padStart(2, "0");
104
+ }
105
+ return out;
106
+ }
107
+
108
+ /** The value of original line `i` (0-based) in an {@link encodeRankPart} string; 0 past its end. */
109
+ export function rankPartAt(encoded: string, i: number, max: number): number {
110
+ const level = Number.parseInt(encoded.slice(2 * i, 2 * i + 2), 36);
111
+ return Number.isNaN(level) ? 0 : (level / RANK_LEVELS) * max;
112
+ }
113
+
114
+ /**
115
+ * What a result's Spotlight requests sent besides the output lines they ranked (`POST /v1/spotlight`): the agent's
116
+ * state at the call, the command that produced the output, the question its lines were ranked under, and the model.
117
+ */
118
+ export interface SpotlightRequestParams {
119
+ /** The user's first message of the session. */
120
+ task: string;
121
+ /** Up to three earlier bash commands of the session, oldest first. */
122
+ commands: string[];
123
+ /** The agent's text before the call. */
124
+ said: string;
125
+ /** The call's intent argument. */
126
+ intent: string;
127
+ /** The command, code or `read <path>` that produced the output. */
128
+ source: string;
129
+ /** The probe the lines were ranked under: Spotlight scores each line's relevance to the agent's current call. */
130
+ probe: string;
131
+ model: string;
132
+ thinking: string;
133
+ }
134
+
135
+ /** `details.spotlight`: one tool result as shaping left it. */
136
+ export interface SpotlightDetails {
137
+ tool: string;
138
+ /** The shaping steps that ran (`outline`, `window`, …; `none` for a passthrough). */
139
+ steps: string[];
140
+ inChars: number;
141
+ outChars: number;
142
+ /** o200k tokens of the original and of the text the model saw. */
143
+ inTokens: number;
144
+ outTokens: number;
145
+ /**
146
+ * Size of the plain (unshaped) result for the same call (a spilled output's capped text, a read's page), notices
147
+ * included. Absent on traces written before pi recorded it.
148
+ */
149
+ plainChars?: number;
150
+ plainTokens?: number;
151
+ /**
152
+ * `plainTokens - outTokens` for a changed (or held-out) result, else 0: negative for a column-cap cut longer than
153
+ * the preview it replaced. On older traces `inTokens - outTokens`.
154
+ */
155
+ savedTokens: number;
156
+ /** The score-free coin skipped Spotlight: the result was shaped by the no-score rules. Absent otherwise. */
157
+ scoreFree?: boolean;
158
+ /**
159
+ * The cut saved too few tokens against the plain result to apply, so the model got the plain text (`steps` ends
160
+ * with `plain-cap`, the out sizes are the plain text's): the would-be cut's size. Absent otherwise.
161
+ */
162
+ cappedChars?: number;
163
+ cappedTokens?: number;
164
+ /**
165
+ * Shaping would have changed the text, but the result was held out at random: the model saw the plain result. The
166
+ * sizes, steps and {@link original} describe the would-be cut. Absent otherwise.
167
+ */
168
+ holdout?: boolean;
169
+ /**
170
+ * Transcripts from before the edit gate was removed: the gate kept a read pi guessed the agent would edit whole, and
171
+ * the model got the plain page. Like {@link holdout}, the sizes, steps and {@link original} describe the would-be
172
+ * cut, but `savedTokens` is 0. pi no longer writes it.
173
+ */
174
+ gated?: boolean;
175
+ /** Present only when shaping changed the text, or would have ({@link holdout}, {@link gated}). */
176
+ original?: SpotlightOriginal;
177
+ /** Present with {@link original} when Spotlight ranked the result's lines. */
178
+ request?: SpotlightRequestParams;
179
+ }
180
+
181
+ /**
182
+ * Tokens the shaped text saves against the plain result (negative: it costs more), or against the original on
183
+ * traces without {@link SpotlightDetails.plainTokens}.
184
+ */
185
+ export function spotlightSaving(spotlight: SpotlightDetails): number {
186
+ return spotlight.plainTokens === undefined ? spotlight.savedTokens : spotlight.plainTokens - spotlight.outTokens;
187
+ }
188
+
189
+ /** The trace a result's details carry, or undefined when the experiment did not shape it. */
190
+ export function spotlightDetails(details: unknown): SpotlightDetails | undefined {
191
+ if (!isRecord(details) || !isRecord(details.spotlight)) return undefined;
192
+ const s = details.spotlight;
193
+ if (typeof s.tool !== "string" || typeof s.savedTokens !== "number") return undefined;
194
+ return s as unknown as SpotlightDetails;
195
+ }
196
+
197
+ /** The {@link SpotlightOriginal.heat} of per-line scores: each relative to the best, in ten steps. */
198
+ export function encodeHeat(scores: readonly (number | null)[]): string {
199
+ const n = Math.min(scores.length, SPOTLIGHT_VIEW_LINES);
200
+ let top = 0;
201
+ for (let i = 0; i < n; i++) top = Math.max(top, scores[i] ?? 0);
202
+ let out = "";
203
+ for (let i = 0; i < n; i++) {
204
+ const s = scores[i];
205
+ out += s === null || s === undefined ? "-" : String(top > 0 ? Math.round((Math.max(0, s) / top) * 9) : 0);
206
+ }
207
+ return out.replace(/-+$/, "");
208
+ }
209
+
210
+ /** The heat of original line `i` (0-based) in [0, 1], or undefined when Spotlight never scored it. */
211
+ export function heatAt(heat: string, i: number): number | undefined {
212
+ const c = heat.charCodeAt(i);
213
+ return c >= 48 && c <= 57 ? (c - 48) / 9 : undefined;
214
+ }
215
+
216
+ /** {@link SpotlightOriginal.kept} of a per-line kept mask. */
217
+ export function keptRanges(kept: readonly boolean[]): [number, number][] {
218
+ const out: [number, number][] = [];
219
+ for (let i = 0; i < kept.length; i++) {
220
+ if (!kept[i]) continue;
221
+ let j = i;
222
+ while (j + 1 < kept.length && kept[j + 1]) j++;
223
+ out.push([i + 1, j + 1]);
224
+ i = j;
225
+ }
226
+ return out;
227
+ }
228
+
229
+ /** Heat digit from which a line counts as hot: a hidden one was cut though hot. */
230
+ const HOT_DIGIT = 6;
231
+
232
+ /** Whether original line `i` (0-based) scored hot: a heat digit of {@link HOT_DIGIT} or more. */
233
+ export function spotlightHot(heat: string, i: number): boolean {
234
+ const c = heat.charCodeAt(i);
235
+ return c >= 48 + HOT_DIGIT && c <= 57;
236
+ }
237
+
238
+ /** The tone of each reason that shows a line. */
239
+ const SHOWN_TONES: Record<"a" | "s" | "n" | "c", TspTone> = { a: "accent", s: "neutral", n: "user", c: "info" };
240
+
241
+ /**
242
+ * The tone the sheet and the notice give original line `i` (0-based): why shaping showed it (`accent` score,
243
+ * `neutral` structure, `user` named, `info` context), `error` for a hidden line that scored hot; undefined for any
244
+ * other hidden line and for a line without a reason.
245
+ */
246
+ export function spotlightTone(original: SpotlightOriginal, i: number): TspTone | undefined {
247
+ const reason = reasonAt(original.why, i);
248
+ if (reason === undefined || reason === "-") return undefined;
249
+ if (reasonShows(reason)) return SHOWN_TONES[reason as keyof typeof SHOWN_TONES];
250
+ return spotlightHot(original.heat, i) ? "error" : undefined;
251
+ }
252
+
253
+ /** At most this many bars in the notice card's chart; a longer result's lines share bars. */
254
+ const NOTICE_BARS = 120;
255
+
256
+ /** Tones a notice card bar takes from its lines, the most notable first (`muted`: a plain hidden line). */
257
+ const NOTICE_TONES: readonly TspTone[] = ["error", "accent", "user", "info", "neutral", "muted"];
258
+
259
+ /** The notice card's tone for original line `i` (0-based): {@link spotlightTone}, `muted` for a plain hidden line. */
260
+ function noticeTone(original: SpotlightOriginal, i: number): TspTone | undefined {
261
+ const tone = spotlightTone(original, i);
262
+ if (tone !== undefined) return tone;
263
+ const reason = reasonAt(original.why, i);
264
+ return reason !== undefined && reason !== "-" && !reasonShows(reason) ? "muted" : undefined;
265
+ }
266
+
267
+ /**
268
+ * The hover card of a changed result's notice: its heat as at most {@link NOTICE_BARS} bars (each the hottest of its
269
+ * lines, tinted by the most notable reason among them), then how many lines the model was shown, or of a held-out
270
+ * result would have been.
271
+ */
272
+ export function spotlightNoticeCard(original: SpotlightOriginal, heldOut = false): TspPropNode {
273
+ const lines = original.heat.length;
274
+ const bars = Math.min(NOTICE_BARS, lines);
275
+ const series: { value: number; tone?: TspTone }[] = [];
276
+ for (let bar = 0; bar < bars; bar++) {
277
+ const end = Math.floor(((bar + 1) * lines) / bars);
278
+ let value = 0;
279
+ let best = NOTICE_TONES.length;
280
+ for (let i = Math.floor((bar * lines) / bars); i < end; i++) {
281
+ value = Math.max(value, heatAt(original.heat, i) ?? 0);
282
+ const tone = noticeTone(original, i);
283
+ if (tone !== undefined) best = Math.min(best, NOTICE_TONES.indexOf(tone));
284
+ }
285
+ series.push(best < NOTICE_TONES.length ? { value, tone: NOTICE_TONES[best] } : { value });
286
+ }
287
+ const kept = original.kept.reduce((sum, [from, to]) => sum + to - from + 1, 0);
288
+ let scored = 0;
289
+ let hot = 0;
290
+ for (let i = 0; i < (original.why?.length ?? 0); i++) {
291
+ if (reasonAt(original.why, i) === "a") scored++;
292
+ else if (spotlightTone(original, i) === "error") hot++;
293
+ }
294
+ const facts = [
295
+ `${heldOut ? "would keep" : "kept"} ${kept.toLocaleString("en-US")} of ${original.lines.toLocaleString("en-US")} lines`,
296
+ ];
297
+ if (scored > 0) facts.push(`${scored.toLocaleString("en-US")} by score`);
298
+ if (hot > 0) facts.push(`${hot.toLocaleString("en-US")} cut though hot`);
299
+ return propNode(
300
+ col(
301
+ [
302
+ node("chart", { kind: "bars", size: "sm", min: 0, max: 1, series }),
303
+ text([span(facts.join(" · "), "muted")]),
304
+ ],
305
+ { gap: "xs" },
306
+ ),
307
+ );
308
+ }
309
+
310
+ /** The notice's star when the model saw the original (passthrough, held out): Nerd Font `md-star_off_outline`. */
311
+ const STAR_OFF = "\u{f155b}";
312
+ /** The notice's star when shaping changed what the model saw: Nerd Font `fa-star`. */
313
+ const STAR = "\uf005";
314
+ /** {@link STAR} past {@link SHOOTING_STAR_TOKENS} saved: Nerd Font `md-star_shooting_outline`. */
315
+ const SHOOTING_STAR = "\u{f1742}";
316
+ /** Tokens saved past which the lit star shoots. */
317
+ const SHOOTING_STAR_TOKENS = 10_000;
318
+
319
+ /**
320
+ * The notice's spans: Spotlight's star, then what shaping did to the result. A passthrough is the star alone. A
321
+ * changed result's star is lit and pulses (Tern twinkles it), a shooting star past {@link SHOOTING_STAR_TOKENS} saved.
322
+ */
323
+ function noticeSpans(spotlight: SpotlightDetails): TspSpan[] {
324
+ const saving = spotlightSaving(spotlight);
325
+ if (spotlight.holdout || spotlight.gated) {
326
+ const why = spotlight.gated ? "kept whole for editing" : "held out";
327
+ return [span(STAR_OFF, "icon"), span(`spotlight: ${why} · would save ${formatNumber(Math.max(0, saving))} toks`)];
328
+ }
329
+ if (!spotlight.original) return [span(STAR_OFF, "icon")];
330
+ const star = saving > SHOOTING_STAR_TOKENS ? SHOOTING_STAR : STAR;
331
+ return [
332
+ span(star, "icon", { fx: "pulse" }),
333
+ span(
334
+ saving > 0
335
+ ? `spotlight: saved ${formatNumber(saving)} toks`
336
+ : `spotlight: reshaped, +${formatNumber(-saving)} toks`,
337
+ ),
338
+ ];
339
+ }
340
+
341
+ /**
342
+ * The notice row under one tool card (role `zeta.tool.spotlight`, key `spotlight:<toolCallId>`): muted for a
343
+ * passthrough (its star alone, named by its tooltip) and for a held-out result, accent for a changed result
344
+ * ({@link noticeSpans}). One with an original (changed or held out) has a hover card charting its heat
345
+ * ({@link spotlightNoticeCard}) and a click that opens its sheet through the host's transcript actions. A native
346
+ * transcript block of its own, placed right after its card ({@link Component.nativeTrailers}), so it shows while the
347
+ * card is collapsed; nothing in the terminal rows.
348
+ */
349
+ export class SpotlightNotice implements Component {
350
+ readonly #toolCallId: string;
351
+ #spotlight: SpotlightDetails;
352
+ #reduced: string;
353
+ #hidden = false;
354
+ #native: NativeNode | undefined;
355
+
356
+ constructor(toolCallId: string, spotlight: SpotlightDetails, reduced: string) {
357
+ this.#toolCallId = toolCallId;
358
+ this.#spotlight = spotlight;
359
+ this.#reduced = reduced;
360
+ }
361
+
362
+ update(spotlight: SpotlightDetails, reduced: string): void {
363
+ if (spotlight === this.#spotlight && reduced === this.#reduced) return;
364
+ this.#spotlight = spotlight;
365
+ this.#reduced = reduced;
366
+ this.#native = undefined;
367
+ }
368
+
369
+ /** Hidden with its card (tool activity hidden). */
370
+ setHidden(hidden: boolean): void {
371
+ if (hidden === this.#hidden) return;
372
+ this.#hidden = hidden;
373
+ this.#native = undefined;
374
+ }
375
+
376
+ describe(): NativeNode {
377
+ if (this.#native) return this.#native;
378
+ const original = this.#spotlight.original;
379
+ this.#native = node("text", {
380
+ role: "zeta.tool.spotlight",
381
+ key: `spotlight:${this.#toolCallId}`,
382
+ tone: original && !this.#spotlight.holdout && !this.#spotlight.gated ? "accent" : "muted",
383
+ spans: noticeSpans(this.#spotlight),
384
+ ...(original
385
+ ? {
386
+ hovercard: spotlightNoticeCard(
387
+ original,
388
+ this.#spotlight.holdout === true || this.#spotlight.gated === true,
389
+ ),
390
+ }
391
+ : { title: "Spotlight: passthrough", aria: "Spotlight: passthrough" }),
392
+ ...(original && hasTranscriptActions() ? { actions: { click: "spotlight" } } : {}),
393
+ ...(this.#hidden ? { hidden: true } : {}),
394
+ });
395
+ return this.#native;
396
+ }
397
+
398
+ /** Never mounted in the terminal rows. */
399
+ render(): readonly string[] {
400
+ return [];
401
+ }
402
+
403
+ invalidate(): void {
404
+ this.#native = undefined;
405
+ }
406
+
407
+ handleNativeEvent(event: NativeUiEvent): void {
408
+ if (event.type !== "action" || event.act !== "spotlight" || !this.#spotlight.original) return;
409
+ runTranscriptAction({
410
+ act: "spotlight",
411
+ toolCallId: this.#toolCallId,
412
+ spotlight: this.#spotlight,
413
+ reduced: this.#reduced,
414
+ });
415
+ }
416
+ }
417
+
418
+ /** The notices of one transcript block's calls, in the order the calls first reported a trace. */
419
+ export class SpotlightNotices {
420
+ readonly #byCall = new Map<string, SpotlightNotice>();
421
+ #list: readonly SpotlightNotice[] = [];
422
+ #hidden = false;
423
+
424
+ /** Records call `toolCallId`'s final result; true when a notice appeared or went. */
425
+ set(toolCallId: string, details: unknown, reduced: string): boolean {
426
+ const spotlight = spotlightDetails(details);
427
+ const existing = this.#byCall.get(toolCallId);
428
+ if (!spotlight) {
429
+ if (!existing) return false;
430
+ this.#byCall.delete(toolCallId);
431
+ this.#list = [...this.#byCall.values()];
432
+ return true;
433
+ }
434
+ if (existing) {
435
+ existing.update(spotlight, reduced);
436
+ return false;
437
+ }
438
+ const notice = new SpotlightNotice(toolCallId, spotlight, reduced);
439
+ notice.setHidden(this.#hidden);
440
+ this.#byCall.set(toolCallId, notice);
441
+ this.#list = [...this.#byCall.values()];
442
+ return true;
443
+ }
444
+
445
+ setHidden(hidden: boolean): void {
446
+ this.#hidden = hidden;
447
+ for (const notice of this.#list) notice.setHidden(hidden);
448
+ }
449
+
450
+ /**
451
+ * The notice blocks, the same array while none came or went; `shown` drops the notices of calls a
452
+ * transcript presenter hides (a fresh array then).
453
+ */
454
+ list(shown?: (toolCallId: string) => boolean): readonly Component[] {
455
+ if (!shown) return this.#list;
456
+ const kept: SpotlightNotice[] = [];
457
+ for (const [toolCallId, notice] of this.#byCall) if (shown(toolCallId)) kept.push(notice);
458
+ return kept.length === this.#list.length ? this.#list : kept;
459
+ }
460
+ }