@linxiraos/pi-tui 1.4.11 → 1.4.13

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 (265) hide show
  1. package/CHANGELOG.md +30 -233
  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/hotkeys-markdown.d.ts +2 -0
  27. package/dist/types/index.d.ts +3 -0
  28. package/dist/types/keybinding-matchers.d.ts +4 -1
  29. package/dist/types/kitty-graphics.d.ts +1 -1
  30. package/dist/types/motion-effects.d.ts +10 -0
  31. package/dist/types/native/encode.d.ts +2 -0
  32. package/dist/types/native/measure.d.ts +10 -0
  33. package/dist/types/native/overlay.d.ts +1 -1
  34. package/dist/types/native/quiet.d.ts +5 -0
  35. package/dist/types/native/reconcile.d.ts +6 -1
  36. package/dist/types/native/spans.d.ts +6 -0
  37. package/dist/types/native/state.d.ts +4 -0
  38. package/dist/types/overlays/agent-hub.d.ts +6 -0
  39. package/dist/types/overlays/link-browser.d.ts +55 -0
  40. package/dist/types/overlays/running-subagent-badge.d.ts +1 -4
  41. package/dist/types/overlays/spotlight-sheet.d.ts +36 -0
  42. package/dist/types/prompt/composer-attachments.d.ts +5 -2
  43. package/dist/types/prompt/composer-cache.d.ts +7 -2
  44. package/dist/types/prompt/composer.d.ts +6 -11
  45. package/dist/types/prompt/custom-editor.d.ts +8 -2
  46. package/dist/types/prompt/gradient-highlight.d.ts +2 -2
  47. package/dist/types/prompt/magic-keywords.d.ts +2 -0
  48. package/dist/types/prompt/model-mention-autocomplete.d.ts +9 -7
  49. package/dist/types/prompt/model-mention-syntax.d.ts +6 -0
  50. package/dist/types/prompt/prompt-action-autocomplete.d.ts +2 -1
  51. package/dist/types/prompt/welcome.d.ts +19 -0
  52. package/dist/types/render/extension-links.d.ts +0 -6
  53. package/dist/types/render/index.d.ts +1 -0
  54. package/dist/types/render/link-hints.d.ts +78 -0
  55. package/dist/types/render/render-utils.d.ts +0 -2
  56. package/dist/types/setup/scenes/types.d.ts +8 -0
  57. package/dist/types/setup/scenes/updates.d.ts +6 -0
  58. package/dist/types/setup/wizard.d.ts +7 -2
  59. package/dist/types/spinner-clock.d.ts +34 -0
  60. package/dist/types/status-line/component.d.ts +8 -4
  61. package/dist/types/status-line/host.d.ts +62 -0
  62. package/dist/types/status-line/index.d.ts +1 -0
  63. package/dist/types/status-line/prompt-cache.d.ts +14 -0
  64. package/dist/types/status-line/schema.d.ts +1 -1
  65. package/dist/types/status-line/startup.d.ts +6 -0
  66. package/dist/types/status-line/types.d.ts +8 -21
  67. package/dist/types/theme/schema.d.ts +28 -1
  68. package/dist/types/theme/symbols.d.ts +1 -1
  69. package/dist/types/theme/theme-class.d.ts +12 -2
  70. package/dist/types/theme/theme.d.ts +1 -1
  71. package/dist/types/theme/tui-adapters.d.ts +7 -0
  72. package/dist/types/thinking.d.ts +12 -0
  73. package/dist/types/tools/ask.d.ts +1 -1
  74. package/dist/types/tools/bash.d.ts +21 -0
  75. package/dist/types/tools/find.d.ts +9 -1
  76. package/dist/types/tools/grep.d.ts +2 -1
  77. package/dist/types/tools/grouped-file-output.d.ts +17 -0
  78. package/dist/types/tools/job-widget.d.ts +2 -2
  79. package/dist/types/tools/lsp.d.ts +4 -2
  80. package/dist/types/tools/native-view.d.ts +4 -0
  81. package/dist/types/tools/renderer.d.ts +9 -1
  82. package/dist/types/tools/shell-trace.d.ts +10 -0
  83. package/dist/types/tools/shell-viz-render.d.ts +6 -0
  84. package/dist/types/tools/shell-viz.d.ts +16 -0
  85. package/dist/types/tools/wait.d.ts +2 -2
  86. package/dist/types/tools/web-search-types.d.ts +1 -0
  87. package/dist/types/tools/write.d.ts +2 -0
  88. package/dist/types/tui.d.ts +15 -1
  89. package/package.json +15 -11
  90. package/src/apps/shell-visualizer.d.ts +24 -0
  91. package/src/apps/shell-visualizer.ts +167 -0
  92. package/src/autocomplete.d.ts +20 -0
  93. package/src/autocomplete.ts +14 -0
  94. package/src/chat/assistant-message.ts +11 -6
  95. package/src/chat/cache-invalidation-marker.d.ts +15 -7
  96. package/src/chat/cache-invalidation-marker.ts +18 -9
  97. package/src/chat/chat-transcript-builder.d.ts +5 -3
  98. package/src/chat/chat-transcript-builder.ts +16 -12
  99. package/src/chat/display-preferences.d.ts +2 -0
  100. package/src/chat/display-preferences.ts +3 -0
  101. package/src/chat/extension-types.d.ts +72 -1
  102. package/src/chat/extension-types.ts +74 -1
  103. package/src/chat/image-loading.d.ts +2 -2
  104. package/src/chat/image-loading.ts +2 -2
  105. package/src/chat/messages.d.ts +2 -3
  106. package/src/chat/messages.ts +3 -8
  107. package/src/chat/read-tool-group.d.ts +15 -2
  108. package/src/chat/read-tool-group.ts +201 -41
  109. package/src/chat/skill-message.d.ts +1 -0
  110. package/src/chat/skill-message.ts +4 -0
  111. package/src/chat/spotlight.d.ts +203 -0
  112. package/src/chat/spotlight.ts +460 -0
  113. package/src/chat/tool-execution.d.ts +26 -5
  114. package/src/chat/tool-execution.ts +360 -38
  115. package/src/chat/transcript-actions.d.ts +11 -0
  116. package/src/chat/transcript-actions.ts +13 -1
  117. package/src/chat/transcript-browser.d.ts +9 -0
  118. package/src/chat/transcript-browser.ts +18 -0
  119. package/src/chat/transcript-presentation.d.ts +164 -0
  120. package/src/chat/transcript-presentation.ts +642 -0
  121. package/src/chat/ttsr-notification.d.ts +25 -0
  122. package/src/chat/ttsr-notification.ts +5 -0
  123. package/src/chrome/message-frame.d.ts +2 -0
  124. package/src/chrome/message-frame.ts +7 -0
  125. package/src/chrome/message-notice.d.ts +58 -0
  126. package/src/chrome/transcript-container.d.ts +27 -6
  127. package/src/chrome/transcript-container.ts +317 -66
  128. package/src/components/editor.ts +25 -1
  129. package/src/components/loader.d.ts +0 -2
  130. package/src/components/loader.ts +30 -18
  131. package/src/components/markdown.d.ts +11 -1
  132. package/src/components/markdown.ts +41 -16
  133. package/src/components/settings-list.d.ts +12 -2
  134. package/src/components/settings-list.ts +29 -13
  135. package/src/frame-rate.d.ts +18 -0
  136. package/src/frame-rate.ts +36 -0
  137. package/src/hotkeys-markdown.ts +9 -2
  138. package/src/index.d.ts +3 -0
  139. package/src/index.ts +3 -0
  140. package/src/keybinding-matchers.d.ts +4 -1
  141. package/src/keybinding-matchers.ts +13 -12
  142. package/src/kitty-graphics.d.ts +1 -1
  143. package/src/kitty-graphics.ts +3 -2
  144. package/src/motion-effects.d.ts +10 -0
  145. package/src/motion-effects.ts +27 -0
  146. package/src/native/backend.ts +66 -7
  147. package/src/native/encode.d.ts +2 -0
  148. package/src/native/encode.ts +2 -0
  149. package/src/native/measure.d.ts +10 -0
  150. package/src/native/measure.ts +185 -0
  151. package/src/native/overlay.d.ts +1 -1
  152. package/src/native/overlay.ts +1 -1
  153. package/src/native/quiet.d.ts +5 -0
  154. package/src/native/quiet.ts +105 -0
  155. package/src/native/reconcile.d.ts +6 -1
  156. package/src/native/reconcile.ts +16 -10
  157. package/src/native/spans.d.ts +6 -0
  158. package/src/native/spans.ts +40 -0
  159. package/src/native/state.d.ts +4 -0
  160. package/src/native/state.ts +18 -0
  161. package/src/overlays/agent-hub.ts +15 -2
  162. package/src/overlays/ask-dialog.ts +1 -0
  163. package/src/overlays/btw-history-panel.ts +73 -6
  164. package/src/overlays/link-browser.ts +295 -0
  165. package/src/overlays/running-subagent-badge.ts +2 -9
  166. package/src/overlays/settings-defs.ts +1 -1
  167. package/src/overlays/settings-selector.ts +17 -3
  168. package/src/overlays/spotlight-sheet.ts +478 -0
  169. package/src/overlays/usage-dashboard.ts +6 -5
  170. package/src/prompt/composer-attachments.d.ts +5 -2
  171. package/src/prompt/composer-attachments.ts +6 -6
  172. package/src/prompt/composer-cache.ts +17 -16
  173. package/src/prompt/composer.ts +30 -123
  174. package/src/prompt/custom-editor.ts +17 -13
  175. package/src/prompt/gradient-highlight.d.ts +2 -2
  176. package/src/prompt/gradient-highlight.ts +5 -4
  177. package/src/prompt/magic-keywords.d.ts +2 -0
  178. package/src/prompt/magic-keywords.ts +4 -1
  179. package/src/prompt/model-mention-autocomplete.ts +73 -20
  180. package/src/prompt/model-mention-syntax.d.ts +6 -0
  181. package/src/prompt/model-mention-syntax.ts +9 -0
  182. package/src/prompt/prompt-action-autocomplete.ts +49 -33
  183. package/src/prompt/tips.txt +1 -0
  184. package/src/prompt/welcome.ts +104 -2
  185. package/src/render/extension-links.d.ts +0 -6
  186. package/src/render/extension-links.ts +0 -20
  187. package/src/render/index.d.ts +1 -0
  188. package/src/render/index.ts +1 -0
  189. package/src/render/link-hints.d.ts +78 -0
  190. package/src/render/link-hints.ts +299 -0
  191. package/src/render/render-utils.d.ts +0 -2
  192. package/src/render/render-utils.ts +0 -5
  193. package/src/setup/scenes/glyph.ts +1 -1
  194. package/src/setup/scenes/types.ts +8 -0
  195. package/src/setup/scenes/updates.ts +116 -0
  196. package/src/setup/wizard.ts +19 -8
  197. package/src/spinner-clock.d.ts +34 -0
  198. package/src/spinner-clock.ts +79 -0
  199. package/src/status-line/component.ts +145 -53
  200. package/src/status-line/host.ts +51 -0
  201. package/src/status-line/index.ts +1 -0
  202. package/src/status-line/presets.ts +3 -1
  203. package/src/status-line/prompt-cache.ts +154 -0
  204. package/src/status-line/schema.ts +1 -1
  205. package/src/status-line/segments.ts +33 -22
  206. package/src/status-line/startup.ts +22 -4
  207. package/src/status-line/types.ts +8 -22
  208. package/src/stdin-buffer.ts +89 -46
  209. package/src/terminal-capabilities.ts +3 -3
  210. package/src/terminal.ts +1 -8
  211. package/src/theme/loader.ts +3 -2
  212. package/src/theme/schema.d.ts +28 -1
  213. package/src/theme/schema.ts +30 -1
  214. package/src/theme/symbols.d.ts +1 -1
  215. package/src/theme/symbols.ts +15 -3
  216. package/src/theme/theme-class.d.ts +12 -2
  217. package/src/theme/theme-class.ts +23 -0
  218. package/src/theme/theme-schema.json +1 -1
  219. package/src/theme/theme.d.ts +1 -1
  220. package/src/theme/theme.ts +3 -7
  221. package/src/theme/tui-adapters.d.ts +7 -0
  222. package/src/theme/tui-adapters.ts +33 -1
  223. package/src/thinking.d.ts +12 -0
  224. package/src/thinking.ts +31 -0
  225. package/src/tools/ask.d.ts +1 -1
  226. package/src/tools/ask.ts +99 -38
  227. package/src/tools/ast-edit.ts +51 -32
  228. package/src/tools/ast-grep.ts +31 -19
  229. package/src/tools/bash.d.ts +21 -0
  230. package/src/tools/bash.ts +166 -24
  231. package/src/tools/find.d.ts +9 -1
  232. package/src/tools/find.ts +23 -2
  233. package/src/tools/grep.d.ts +2 -1
  234. package/src/tools/grep.ts +52 -36
  235. package/src/tools/grouped-file-output.d.ts +17 -0
  236. package/src/tools/grouped-file-output.ts +20 -2
  237. package/src/tools/job-widget.d.ts +2 -2
  238. package/src/tools/job-widget.ts +2 -2
  239. package/src/tools/lsp.d.ts +4 -2
  240. package/src/tools/lsp.ts +537 -642
  241. package/src/tools/native-view.d.ts +4 -0
  242. package/src/tools/native-view.ts +8 -2
  243. package/src/tools/renderer.d.ts +9 -1
  244. package/src/tools/renderer.ts +9 -1
  245. package/src/tools/shell-trace.d.ts +10 -0
  246. package/src/tools/shell-trace.ts +80 -0
  247. package/src/tools/shell-viz-render.d.ts +6 -0
  248. package/src/tools/shell-viz-render.ts +156 -0
  249. package/src/tools/shell-viz.d.ts +16 -0
  250. package/src/tools/shell-viz.ts +181 -0
  251. package/src/tools/streaming-output.ts +18 -8
  252. package/src/tools/wait.d.ts +2 -2
  253. package/src/tools/wait.ts +39 -34
  254. package/src/tools/web-search-types.d.ts +1 -0
  255. package/src/tools/web-search-types.ts +1 -0
  256. package/src/tools/write.d.ts +2 -0
  257. package/src/tools/write.ts +2 -0
  258. package/src/tui.d.ts +15 -1
  259. package/src/tui.ts +63 -6
  260. package/src/windows-input-mode.ts +7 -1
  261. package/dist/types/chat/collab-prompt-message.d.ts +0 -14
  262. package/dist/types/chrome/collab-qrcode.d.ts +0 -35
  263. package/src/chat/collab-prompt-message.d.ts +0 -14
  264. package/src/chat/collab-prompt-message.ts +0 -46
  265. package/src/chrome/collab-qrcode.ts +0 -99
package/src/tools/wait.ts CHANGED
@@ -144,8 +144,8 @@ export interface CoordinationDetails {
144
144
  from?: string;
145
145
  to?: string;
146
146
  receipts?: IrcDeliveryReceipt[];
147
- /** Message consumed by `wait`. */
148
- waited?: IrcMessage | null;
147
+ /** Messages consumed by `wait`, oldest first. */
148
+ waited?: IrcMessage[];
149
149
  jobs?: JobSnapshot[];
150
150
  cancelled?: { id: string; status: CancelStatus }[];
151
151
  /** Running subagents not represented by a job row in this result. */
@@ -846,27 +846,30 @@ function describeJobsResult(
846
846
  };
847
847
  }
848
848
 
849
- /** Received-message view: sender head, terminal-clocked age, markdown body. */
850
- function describeMessage(
851
- from: string,
852
- ts: number | undefined,
853
- bodyText: string,
854
- meta: readonly string[],
855
- ): NativeToolView {
856
- const head: TspSpan[] = [span(`IRC ← ${plainText(from)}`, "toolTitle strong")];
857
- for (const part of meta) head.push(span(` ${part}`, "muted"));
849
+ /** One received message: sender (when the card holds several), terminal-clocked age, markdown body. */
850
+ function describeMessage(msg: IrcMessage, single: boolean): NativeNode[] {
851
+ const sender = single
852
+ ? []
853
+ : [text([span(plainText(msg.from), "toolTitle strong"), ...(msg.replyTo ? [span(" reply", "muted")] : [])])];
854
+ const age = msg.ts
855
+ ? [text([span("received", "dim")]), elapsed(Date.now() - msg.ts), text([span("ago", "dim")])]
856
+ : [];
857
+ const head = [...sender, ...age];
858
+ return compact([head.length > 0 ? row(head, { gap: "xs" }) : undefined, msg.body.trim() ? md(msg.body) : undefined]);
859
+ }
860
+
861
+ /** Received-messages view: senders head, then each message oldest first. */
862
+ function describeMessages(messages: readonly IrcMessage[]): NativeToolView {
863
+ const single = messages.length === 1;
864
+ const senders = [...new Set(messages.map(msg => plainText(msg.from)))];
865
+ const head: TspSpan[] = [span(`IRC ← ${senders.join(", ")}`, "toolTitle strong")];
866
+ if (!single) head.push(span(` ${messages.length} messages`, "muted"));
867
+ else if (messages[0]?.replyTo) head.push(span(" reply", "muted"));
858
868
  return {
859
869
  head,
860
870
  tone: "info",
861
- preview: { lines: BODY_LINES_COLLAPSED + 1 },
862
- body: compact([
863
- ts
864
- ? row([text([span("received", "dim")]), elapsed(Date.now() - ts), text([span("ago", "dim")])], {
865
- gap: "xs",
866
- })
867
- : undefined,
868
- bodyText.trim() ? md(bodyText) : undefined,
869
- ]),
871
+ preview: { lines: (BODY_LINES_COLLAPSED + 1) * messages.length },
872
+ body: messages.flatMap(msg => describeMessage(msg, single)),
870
873
  };
871
874
  }
872
875
 
@@ -898,8 +901,8 @@ export const waitToolRenderer = {
898
901
  };
899
902
  }
900
903
  const waited = details?.waited;
901
- if (!waited) return describeJobsResult(result, options.isPartial);
902
- return describeMessage(waited.from, waited.ts, waited.body, waited.replyTo ? ["reply"] : []);
904
+ if (!waited?.length) return describeJobsResult(result, options.isPartial);
905
+ return describeMessages(waited);
903
906
  });
904
907
  },
905
908
  renderResult(
@@ -919,21 +922,23 @@ export const waitToolRenderer = {
919
922
  );
920
923
  }
921
924
  const waited = result.details?.waited;
922
- if (!waited) return jobsRenderResult(result, options, uiTheme);
925
+ if (!waited?.length) return jobsRenderResult(result, options, uiTheme);
923
926
  return createCachedComponent(
924
927
  () => options.expanded,
925
928
  (width, expanded) =>
926
- [
927
- renderStatusLine(
928
- {
929
- iconOverride: ircGlyph(uiTheme),
930
- title: `IRC ${uiTheme.nav.back} ${replaceTabs(waited.from)}`,
931
- meta: [messageAge(waited.ts), ...(waited.replyTo ? ["reply"] : [])],
932
- },
933
- uiTheme,
934
- ),
935
- ...bodyLines(waited.body, expanded, uiTheme, { indent: " " }),
936
- ].map(line => truncateToWidth(line, width, Ellipsis.Unicode)),
929
+ waited
930
+ .flatMap(msg => [
931
+ renderStatusLine(
932
+ {
933
+ iconOverride: ircGlyph(uiTheme),
934
+ title: `IRC ${uiTheme.nav.back} ${replaceTabs(msg.from)}`,
935
+ meta: [messageAge(msg.ts), ...(msg.replyTo ? ["reply"] : [])],
936
+ },
937
+ uiTheme,
938
+ ),
939
+ ...bodyLines(msg.body, expanded, uiTheme, { indent: " " }),
940
+ ])
941
+ .map(line => truncateToWidth(line, width, Ellipsis.Unicode)),
937
942
  );
938
943
  },
939
944
  } satisfies ToolRenderer<object, CoordinationDetails>;
@@ -20,6 +20,7 @@ export declare const SEARCH_PROVIDER_LABELS: {
20
20
  readonly zai: "Z.AI";
21
21
  readonly exa: "Exa";
22
22
  readonly tinyfish: "TinyFish";
23
+ readonly keenable: "Keenable";
23
24
  readonly jina: "Jina";
24
25
  readonly kagi: "Kagi";
25
26
  readonly tavily: "Tavily";
@@ -21,6 +21,7 @@ export const SEARCH_PROVIDER_LABELS = {
21
21
  zai: "Z.AI",
22
22
  exa: "Exa",
23
23
  tinyfish: "TinyFish",
24
+ keenable: "Keenable",
24
25
  jina: "Jina",
25
26
  kagi: "Kagi",
26
27
  tavily: "Tavily",
@@ -22,6 +22,8 @@ export interface WriteToolDetails {
22
22
  message?: CoordinationDetails;
23
23
  proc?: ProcWriteDetails;
24
24
  cfg?: CfgWriteDetails;
25
+ /** Set when the write touched no files: a peer message, a reply, or a background-work cancellation. */
26
+ touchesNoFiles?: boolean;
25
27
  }
26
28
  interface WriteRenderArgs {
27
29
  path?: unknown;
@@ -83,6 +83,8 @@ export interface WriteToolDetails {
83
83
  message?: CoordinationDetails;
84
84
  proc?: ProcWriteDetails;
85
85
  cfg?: CfgWriteDetails;
86
+ /** Set when the write touched no files: a peer message, a reply, or a background-work cancellation. */
87
+ touchesNoFiles?: boolean;
86
88
  }
87
89
 
88
90
  interface WriteRenderArgs {
package/src/tui.d.ts CHANGED
@@ -129,7 +129,9 @@ export interface Component {
129
129
  * an overlay: the sheet's `role` (Tern styles `zeta.overlay.*` roles as
130
130
  * glass sheets, so the component's own root must not draw a second frame),
131
131
  * `head` spans for the sheet's title row, and `size`/`anchor` overriding
132
- * the ones derived from the overlay options.
132
+ * the ones derived from the overlay options. `size` is a width class: on a
133
+ * narrow pane the backend fills it only when the described content is tall
134
+ * (see `NativeBackend`).
133
135
  */
134
136
  nativeOverlay?: {
135
137
  role?: string;
@@ -153,6 +155,12 @@ export interface Component {
153
155
  describeScreen?(cx: DescribeContext): NativeScreen;
154
156
  /** User actions on nodes this component described (toggle, select, activate, custom). */
155
157
  handleNativeEvent?(event: NativeUiEvent): void;
158
+ /**
159
+ * Native transcript blocks drawn right after this one as siblings (a `TranscriptContainer` child only): notes
160
+ * about the block that must show while it is collapsed, such as a tool card's Spotlight notice. The terminal
161
+ * rows never show them. Return the same array while unchanged.
162
+ */
163
+ nativeTrailers?(): readonly Component[];
156
164
  /**
157
165
  * Pure preflight for focused input that must precede TUI-wide input listeners
158
166
  * and debug shortcuts. A true result routes the event to this component first.
@@ -343,6 +351,12 @@ export declare class Container implements Component {
343
351
  render(width: number): readonly string[];
344
352
  describe(_cx: DescribeContext): NativeNode | null;
345
353
  }
354
+ /**
355
+ * `component`'s own native description, or `null` when it draws as rendered rows: it has no
356
+ * `describe`, answers `null`, or is a Container subclass that paints its own rows but inherits the
357
+ * plain column description, which would lose that rendering.
358
+ */
359
+ export declare function ownDescription(component: Component, cx: DescribeContext): NativeNode | null;
346
360
  /**
347
361
  * Merge runs of byte-adjacent SGR sequences (`CSI [0-9;:]* m`) into one. Only
348
362
  * CSI-SGR sequences are touched; text, cursor moves, OSC, hyperlinks and image
package/src/tui.ts CHANGED
@@ -54,6 +54,7 @@ import { onTerminalBackgroundFallbackChange } from "./theme/theme";
54
54
  import { compositeLineAt } from "./render/composite";
55
55
  import { stripExtensionLinkMarkers } from "./render/extension-links";
56
56
  import { tmuxMultiplexer } from "./multiplexers/tmux";
57
+ import { minFrameIntervalMs } from "./frame-rate";
57
58
  import {
58
59
  Ellipsis,
59
60
  getWidthConfigEpoch,
@@ -292,7 +293,9 @@ export interface Component {
292
293
  * an overlay: the sheet's `role` (Tern styles `zeta.overlay.*` roles as
293
294
  * glass sheets, so the component's own root must not draw a second frame),
294
295
  * `head` spans for the sheet's title row, and `size`/`anchor` overriding
295
- * the ones derived from the overlay options.
296
+ * the ones derived from the overlay options. `size` is a width class: on a
297
+ * narrow pane the backend fills it only when the described content is tall
298
+ * (see `NativeBackend`).
296
299
  */
297
300
  nativeOverlay?: {
298
301
  role?: string;
@@ -320,6 +323,13 @@ export interface Component {
320
323
  /** User actions on nodes this component described (toggle, select, activate, custom). */
321
324
  handleNativeEvent?(event: NativeUiEvent): void;
322
325
 
326
+ /**
327
+ * Native transcript blocks drawn right after this one as siblings (a `TranscriptContainer` child only): notes
328
+ * about the block that must show while it is collapsed, such as a tool card's Spotlight notice. The terminal
329
+ * rows never show them. Return the same array while unchanged.
330
+ */
331
+ nativeTrailers?(): readonly Component[];
332
+
323
333
  /**
324
334
  * Pure preflight for focused input that must precede TUI-wide input listeners
325
335
  * and debug shortcuts. A true result routes the event to this component first.
@@ -679,6 +689,18 @@ export class Container implements Component {
679
689
  }
680
690
  }
681
691
 
692
+ /**
693
+ * `component`'s own native description, or `null` when it draws as rendered rows: it has no
694
+ * `describe`, answers `null`, or is a Container subclass that paints its own rows but inherits the
695
+ * plain column description, which would lose that rendering.
696
+ */
697
+ export function ownDescription(component: Component, cx: DescribeContext): NativeNode | null {
698
+ const describe = component.describe;
699
+ if (describe === undefined) return null;
700
+ if (describe === Container.prototype.describe && component.render !== Container.prototype.render) return null;
701
+ return describe.call(component, cx);
702
+ }
703
+
682
704
  interface HardwareCursorState {
683
705
  row: number;
684
706
  col: number;
@@ -990,12 +1012,22 @@ export class TUI extends Container {
990
1012
  * `#scheduleRender` to inflate the next render delay proportionally so a
991
1013
  * spike of slow frames (large transcript diffs, huge assistant text wrap,
992
1014
  * component-tree walks) does not busy-loop the CPU: the throttle would
993
- * otherwise collapse to zero once `elapsed >= MIN_RENDER_INTERVAL_MS` and
1015
+ * otherwise collapse to zero once `elapsed` passes the frame interval and
994
1016
  * fire the next frame immediately (see #4145).
995
1017
  */
996
1018
  #lastFrameCostMs = 0;
997
- static readonly #MIN_RENDER_INTERVAL_MS = 1000 / 30;
998
- static readonly #INPUT_RENDER_GRACE_MS = TUI.#MIN_RENDER_INTERVAL_MS;
1019
+ /**
1020
+ * Cadence of frames a keystroke is waiting on. Pinned at the historical 30 fps regardless of
1021
+ * the `tui.maxFps` ceiling (see {@link minFrameIntervalMs}): the ceiling exists to quiet panes
1022
+ * nobody is typing in, and the one being typed in must echo within a frame.
1023
+ */
1024
+ static readonly #INPUT_FRAME_INTERVAL_MS = 1000 / 30;
1025
+ static readonly #INPUT_RENDER_GRACE_MS = TUI.#INPUT_FRAME_INTERVAL_MS;
1026
+ /**
1027
+ * Set when the pending render was requested by terminal input, so `#scheduleRender` paces it
1028
+ * at `#INPUT_FRAME_INTERVAL_MS` instead of the ceiling; cleared when that frame paints.
1029
+ */
1030
+ #inputRenderPending = false;
999
1031
  /**
1000
1032
  * Cap on the adaptive floor derived from `#lastFrameCostMs`. Bounds the UI
1001
1033
  * responsiveness at ~5 fps under sustained heavy renders — anything slower
@@ -1484,6 +1516,11 @@ export class TUI extends Container {
1484
1516
  const index = this.overlayStack.indexOf(entry);
1485
1517
  if (index !== -1) {
1486
1518
  this.overlayStack.splice(index, 1);
1519
+ // Overlays opened over this one return focus to where it would have.
1520
+ for (const other of this.overlayStack) {
1521
+ if (other.preFocus && isOverlayFocusTarget(component, other.preFocus))
1522
+ other.preFocus = entry.preFocus;
1523
+ }
1487
1524
  // Restore focus if this overlay or one of its owned targets had focus
1488
1525
  if (isOverlayFocusTarget(component, this.#focusedComponent)) {
1489
1526
  this.setFocus(this.#getKeyHolderOverlay()?.component ?? entry.preFocus);
@@ -2942,6 +2979,16 @@ export class TUI extends Container {
2942
2979
  });
2943
2980
  return;
2944
2981
  }
2982
+ // A render while a keystroke's latch is set rides the fixed input cadence: an animation frame
2983
+ // parked further out under the `tui.maxFps` ceiling is replaced by one the keystroke can ride.
2984
+ // Input listeners (scroll wheel, toggles) and focused components alike request through here.
2985
+ if (this.#inputRenderPending && this.#renderTimer && !this.#nativeLive) {
2986
+ this.#renderTimer.cancel();
2987
+ this.#renderTimer = undefined;
2988
+ this.#renderRequested = true;
2989
+ this.#scheduleRender();
2990
+ return;
2991
+ }
2945
2992
  this.#requestOrdinaryRender();
2946
2993
  }
2947
2994
 
@@ -3046,7 +3093,12 @@ export class TUI extends Container {
3046
3093
  }
3047
3094
  const now = this.#renderScheduler.now();
3048
3095
  const elapsed = now - this.#lastRenderAt;
3049
- const cadenceDelay = Math.max(0, TUI.#MIN_RENDER_INTERVAL_MS - elapsed);
3096
+ // Animation and content frames land no closer than the `tui.maxFps` ceiling allows; a frame
3097
+ // a keystroke is waiting on keeps the fixed input cadence.
3098
+ const frameIntervalMs = this.#inputRenderPending
3099
+ ? Math.min(TUI.#INPUT_FRAME_INTERVAL_MS, minFrameIntervalMs())
3100
+ : minFrameIntervalMs();
3101
+ const cadenceDelay = Math.max(0, frameIntervalMs - elapsed);
3050
3102
  // Adaptive backpressure — target ~50% render duty cycle: the next frame
3051
3103
  // starts no sooner than `last_frame_end + last_frame_cost`, i.e.
3052
3104
  // `last_frame_start + 2 × last_frame_cost`. So `elapsed` (which counts
@@ -3069,6 +3121,7 @@ export class TUI extends Container {
3069
3121
  */
3070
3122
  #executeRender(): void {
3071
3123
  if (this.#deferRenderForOutputBacklog()) return;
3124
+ this.#inputRenderPending = false;
3072
3125
  const start = this.#renderScheduler.now();
3073
3126
  this.#lastRenderAt = start;
3074
3127
  this.#doRender();
@@ -3139,6 +3192,11 @@ export class TUI extends Container {
3139
3192
  data = data.slice(0, searchFrom + match.index) + data.slice(searchFrom + match.index + match[0].length);
3140
3193
  }
3141
3194
  if (data.length === 0) return;
3195
+ // Every keystroke arms the input latch before any consumer runs, so whichever consumer
3196
+ // requests the paint — an input listener or the focused component — it is paced at the input
3197
+ // cadence, not the ceiling. Input that triggers no render leaves the latch for the next frame
3198
+ // to consume at the 30 fps floor once; harmless.
3199
+ this.#inputRenderPending = true;
3142
3200
 
3143
3201
  if (
3144
3202
  this.#heldInput !== undefined &&
@@ -3163,7 +3221,6 @@ export class TUI extends Container {
3163
3221
  this.setFocus(focusedOverlay.preFocus);
3164
3222
  }
3165
3223
  }
3166
-
3167
3224
  // Ctrl+C/Esc use app-level double-press windows. Give those gestures one
3168
3225
  // frame to drain queued input before an ordinary repaint; delaying every
3169
3226
  // key would make idle navigation pay a full frame of latency.
@@ -39,6 +39,7 @@ const VK_RETURN = 0x0d;
39
39
  const VK_MENU = 0x12;
40
40
  const VK_ESCAPE = 0x1b;
41
41
  const VK_SPACE = 0x20;
42
+ const VK_J = 0x4a;
42
43
  const VK_PACKET = 0xe7;
43
44
 
44
45
  /** Keys encoded as fixed bytes that can still carry text a pending dead key composed. */
@@ -191,8 +192,13 @@ function encodeKey(record: KeyRecord): string | null {
191
192
 
192
193
  const base = baseCodepointForVk(vk);
193
194
  if (ctrl) {
195
+ // Windows Terminal / ConPTY report Ctrl+J as VK_J with Uc=LF. Returning the
196
+ // raw LF would make the editor treat it as Enter, so keep the key identity.
197
+ // Only J is special-cased: `ctrl+j` is a default `tui.input.newLine` binding,
198
+ // while Ctrl+M/I (CR/Tab) already decode to the keys their C0 bytes represent.
199
+ const ctrlJ = !alt && vk === VK_J && uc === 0x0a;
194
200
  // Ctrl+Shift+letter collapses onto Ctrl+letter in legacy bytes; keep it distinct.
195
- if ((shift || uc === 0) && base !== 0) return `\x1b[${base};${mod}u`;
201
+ if ((shift || uc === 0 || ctrlJ) && base !== 0) return `\x1b[${base};${mod}u`;
196
202
  if (uc === 0) return null;
197
203
  return alt ? `\x1b${text}` : text;
198
204
  }
@@ -1,14 +0,0 @@
1
- import { Container } from "../tui.js";
2
- import type { CollabPromptDetails } from "./messages.js";
3
- import type { CustomMessage } from "./messages.js";
4
- import type { NativeNode } from "../native/node.js";
5
- /**
6
- * Renders a collab guest prompt on every participant's transcript: a
7
- * user-message-styled bubble prefixed with the author's name.
8
- */
9
- export declare class CollabPromptMessageComponent extends Container {
10
- #private;
11
- constructor(message: CustomMessage<CollabPromptDetails>);
12
- /** A user-toned card headed by the guest's name, with the prompt as markdown. */
13
- describe(): NativeNode;
14
- }
@@ -1,35 +0,0 @@
1
- import type { Component } from "../tui.js";
2
- import type { AnimationFrame, TranscriptPresentationTarget } from "./transcript-container.js";
3
- import type { DescribeContext, NativeNode } from "../native/node.js";
4
- /** Scheme-less display form of a collab browser deep link, OSC-8 linked. */
5
- export declare function collabBrowserLink(webLink: string, label?: string): string;
6
- /**
7
- * One-shot transcript block that prints a collab browser-join URL as a
8
- * scannable QR code. The symbol is encoded once at construction (byte mode,
9
- * EC level M) and rendered as ANSI half-blocks; on terminals too narrow for
10
- * the symbol it degrades to a one-line hint that includes the URL.
11
- *
12
- * The transcript viewport can also clip a live block to a single row under
13
- * pressure (many short settled blocks — typical when thinking is a one-line
14
- * summary rather than a tall trace). The QR's first/last rows are a white
15
- * quiet zone, so a 1-row clip looks like an empty white line. When the
16
- * allocated height cannot fit the full symbol, degrade to the same hint.
17
- * The sibling `/collab` status heading can also collapse to its first row
18
- * under that pressure, so the hint must carry the URL itself — "use the
19
- * URL above" is not reachable.
20
- */
21
- export declare class CollabQrCodeComponent implements Component, TranscriptPresentationTarget {
22
- #private;
23
- readonly url: string;
24
- constructor(url: string);
25
- setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void;
26
- render(width: number): readonly string[];
27
- /**
28
- * The symbol as an unwrapped monospace block plus the join link. Glyphs are
29
- * drawn in the terminal's foreground, so on a dark appearance the light
30
- * modules are inked to keep the dark-on-light symbol scanners expect.
31
- */
32
- describe(cx: DescribeContext): NativeNode;
33
- /** Survives emergency 1-row transcript pressure when this block is otherwise hidden. */
34
- renderTranscriptBlockEmergencyRow(width: number): string;
35
- }
@@ -1,14 +0,0 @@
1
- import { Container } from "../tui";
2
- import type { CollabPromptDetails } from "./messages";
3
- import type { CustomMessage } from "./messages";
4
- import type { NativeNode } from "../native/node";
5
- /**
6
- * Renders a collab guest prompt on every participant's transcript: a
7
- * user-message-styled bubble prefixed with the author's name.
8
- */
9
- export declare class CollabPromptMessageComponent extends Container {
10
- #private;
11
- constructor(message: CustomMessage<CollabPromptDetails>);
12
- /** A user-toned card headed by the guest's name, with the prompt as markdown. */
13
- describe(): NativeNode;
14
- }
@@ -1,46 +0,0 @@
1
- import type { TextContent } from "@linxiraos/pi-ai";
2
- import { Container } from "../tui";
3
- import { Markdown } from "../components/markdown";
4
- import { Text } from "../components/text";
5
- import type { CollabPromptDetails } from "./messages";
6
- import type { CustomMessage } from "./messages";
7
- import { getMarkdownTheme, theme } from "../theme";
8
- import { card, md, span } from "../native/describe";
9
- import type { NativeNode } from "../native/node";
10
-
11
- /**
12
- * Renders a collab guest prompt on every participant's transcript: a
13
- * user-message-styled bubble prefixed with the author's name.
14
- */
15
- export class CollabPromptMessageComponent extends Container {
16
- readonly #native: NativeNode;
17
-
18
- constructor(message: CustomMessage<CollabPromptDetails>) {
19
- super();
20
- const from = message.details?.from?.trim() || "guest";
21
- const authorText = new Text(theme.fg("accent", `\x1b[1m«${from}»\x1b[22m ›`), 1, 0);
22
- authorText.setIgnoreTight(true);
23
- this.addChild(authorText);
24
- const text =
25
- typeof message.content === "string"
26
- ? message.content
27
- : message.content
28
- .filter((content): content is TextContent => content.type === "text")
29
- .map(content => content.text)
30
- .join("");
31
- const markdown = new Markdown(text, 1, 1, getMarkdownTheme(), {
32
- bgColor: (value: string) => theme.bg("userMessageBg", value),
33
- color: (value: string) => theme.fgOnBg("userMessageText", "userMessageBg", value),
34
- });
35
- markdown.setIgnoreTight(true);
36
- this.addChild(markdown);
37
- this.#native = card({ role: "zeta.user.collab", tone: "user", head: [span(`«${from}» ›`, "accent strong")] }, [
38
- md(text),
39
- ]);
40
- }
41
-
42
- /** A user-toned card headed by the guest's name, with the prompt as markdown. */
43
- override describe(): NativeNode {
44
- return this.#native;
45
- }
46
- }
@@ -1,99 +0,0 @@
1
- import type { Component } from "../tui";
2
- import { Ellipsis, truncateToWidth, visibleWidth } from "../utils";
3
- import type { AnimationFrame, TranscriptPresentationTarget } from "./transcript-container";
4
- import { fgOrPlain } from "../theme/theme";
5
- import { urlHyperlinkAlways } from "../render/index";
6
- import { QrCode, renderQrHalfBlocks, renderQrText } from "./qrcode";
7
- import type { DescribeContext, NativeNode } from "../native/node";
8
- import { code, col, text } from "../native/describe";
9
-
10
- /** Scheme-less display form of a collab browser deep link, OSC-8 linked. */
11
- export function collabBrowserLink(webLink: string, label?: string): string {
12
- const schemeLess = webLink.replace(/^https?:\/\//, "");
13
- const display = fgOrPlain("accent", `\x1b[4m${label ?? schemeLess}\x1b[24m`);
14
- const linked = urlHyperlinkAlways(webLink, display);
15
- // Without OSC-8 support, keep the literal URL at the visible prefix.
16
- return label !== undefined && linked === display ? fgOrPlain("accent", `\x1b[4m${schemeLess}\x1b[24m`) : linked;
17
- }
18
-
19
- /**
20
- * One-shot transcript block that prints a collab browser-join URL as a
21
- * scannable QR code. The symbol is encoded once at construction (byte mode,
22
- * EC level M) and rendered as ANSI half-blocks; on terminals too narrow for
23
- * the symbol it degrades to a one-line hint that includes the URL.
24
- *
25
- * The transcript viewport can also clip a live block to a single row under
26
- * pressure (many short settled blocks — typical when thinking is a one-line
27
- * summary rather than a tall trace). The QR's first/last rows are a white
28
- * quiet zone, so a 1-row clip looks like an empty white line. When the
29
- * allocated height cannot fit the full symbol, degrade to the same hint.
30
- * The sibling `/collab` status heading can also collapse to its first row
31
- * under that pressure, so the hint must carry the URL itself — "use the
32
- * URL above" is not reachable.
33
- */
34
- export class CollabQrCodeComponent implements Component, TranscriptPresentationTarget {
35
- readonly #qr: QrCode;
36
- readonly #lines: readonly string[];
37
- readonly #minWidth: number;
38
- #allocatedRows = Number.POSITIVE_INFINITY;
39
- /** Native description per appearance: the polarity follows the terminal's foreground. */
40
- #native: { dark: boolean; node: NativeNode } | undefined;
41
-
42
- constructor(readonly url: string) {
43
- this.#qr = QrCode.encodeText(url, "M");
44
- const rows = renderQrHalfBlocks(this.#qr);
45
- this.#lines = rows.map(row => ` ${row}`);
46
- this.#minWidth = rows.reduce((max, row) => Math.max(max, visibleWidth(row)), 0) + 1;
47
- }
48
-
49
- setTranscriptAllocation(rows: number, _frame?: AnimationFrame): void {
50
- this.#allocatedRows = Number.isFinite(rows) ? Math.max(0, Math.trunc(rows)) : Number.POSITIVE_INFINITY;
51
- }
52
-
53
- render(width: number): readonly string[] {
54
- if (width < this.#minWidth) {
55
- return [this.#hiddenHint(`terminal width ${width}; need ${this.#minWidth}`, width)];
56
- }
57
- if (this.#allocatedRows < this.#lines.length) {
58
- return [this.#hiddenHint(`viewport height ${this.#allocatedRows}; need ${this.#lines.length}`, width)];
59
- }
60
- return this.#lines;
61
- }
62
-
63
- /**
64
- * The symbol as an unwrapped monospace block plus the join link. Glyphs are
65
- * drawn in the terminal's foreground, so on a dark appearance the light
66
- * modules are inked to keep the dark-on-light symbol scanners expect.
67
- */
68
- describe(cx: DescribeContext): NativeNode {
69
- if (this.#native?.dark === cx.dark) return this.#native.node;
70
- const qr = renderQrText(this.#qr, cx.dark).join("\n");
71
- const node = col(
72
- [
73
- text([{ t: this.url.replace(/^https?:\/\//, ""), s: "accent link", href: this.url }], { wrap: "none" }),
74
- code(qr, { lang: "text", wrap: false }),
75
- ],
76
- { role: "zeta.collab.qrcode" },
77
- );
78
- this.#native = { dark: cx.dark, node };
79
- return node;
80
- }
81
-
82
- /** Survives emergency 1-row transcript pressure when this block is otherwise hidden. */
83
- renderTranscriptBlockEmergencyRow(width: number): string {
84
- return this.#hiddenHint(
85
- Number.isFinite(this.#allocatedRows)
86
- ? `viewport height ${this.#allocatedRows}; need ${this.#lines.length}`
87
- : "transcript pressure",
88
- width,
89
- );
90
- }
91
-
92
- #hiddenHint(reason: string, width: number): string {
93
- return truncateToWidth(
94
- `${collabBrowserLink(this.url, "Join")} ${fgOrPlain("warning", `QR code hidden: ${reason}.`)}`,
95
- width,
96
- Ellipsis.Omit,
97
- );
98
- }
99
- }