@linxiraos/pi-tui 1.4.7 → 1.4.10

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 (181) hide show
  1. package/CHANGELOG.md +154 -231
  2. package/README.md +7 -1
  3. package/dist/types/app-keybindings.d.ts +5 -0
  4. package/dist/types/charts/table-data.d.ts +4 -2
  5. package/dist/types/chat/bash-execution.d.ts +4 -1
  6. package/dist/types/chat/eval-execution.d.ts +2 -0
  7. package/dist/types/chat/execution-shared.d.ts +14 -8
  8. package/dist/types/chat/figure-markdown.d.ts +2 -0
  9. package/dist/types/chat/svg-figure.d.ts +5 -0
  10. package/dist/types/chat/table-chart.d.ts +2 -0
  11. package/dist/types/chat/transcript-render-helpers.d.ts +11 -3
  12. package/dist/types/chrome/dynamic-border.d.ts +6 -0
  13. package/dist/types/chrome/transcript-status.d.ts +2 -2
  14. package/dist/types/components/editor.d.ts +15 -6
  15. package/dist/types/components/image.d.ts +6 -0
  16. package/dist/types/components/loader.d.ts +2 -0
  17. package/dist/types/keybinding-matchers.d.ts +7 -0
  18. package/dist/types/native/describe.d.ts +4 -2
  19. package/dist/types/native/node.d.ts +2 -3
  20. package/dist/types/native/overlay.d.ts +42 -2
  21. package/dist/types/native/state.d.ts +4 -0
  22. package/dist/types/overlays/btw-history-panel.d.ts +15 -0
  23. package/dist/types/overlays/btw-history.d.ts +24 -0
  24. package/dist/types/overlays/btw-inject.d.ts +22 -0
  25. package/dist/types/overlays/btw-panel.d.ts +7 -0
  26. package/dist/types/overlays/hook-editor.d.ts +2 -0
  27. package/dist/types/overlays/jobs-panel.d.ts +4 -0
  28. package/dist/types/overlays/model-browser.d.ts +1 -1
  29. package/dist/types/overlays/session-selector.d.ts +11 -2
  30. package/dist/types/prompt/composer.d.ts +13 -5
  31. package/dist/types/render/render-utils.d.ts +23 -1
  32. package/dist/types/setup/scenes/language.d.ts +3 -0
  33. package/dist/types/setup/scenes/types.d.ts +5 -0
  34. package/dist/types/setup/setup-version.d.ts +1 -1
  35. package/dist/types/setup/wizard.d.ts +1 -1
  36. package/dist/types/status-line/startup.d.ts +0 -15
  37. package/dist/types/terminal-capabilities.d.ts +1 -1
  38. package/dist/types/theme/symbols.d.ts +3 -1
  39. package/dist/types/theme/theme-class.d.ts +1 -0
  40. package/dist/types/theme/theme.d.ts +1 -1
  41. package/dist/types/theme/tui-adapters.d.ts +2 -0
  42. package/dist/types/thinking.d.ts +8 -6
  43. package/dist/types/tools/ast-grep.d.ts +2 -0
  44. package/dist/types/tools/eval.d.ts +2 -0
  45. package/dist/types/tools/find.d.ts +1 -1
  46. package/dist/types/tools/grouped-file-output.d.ts +100 -19
  47. package/dist/types/tools/hashline-format.d.ts +5 -0
  48. package/dist/types/tools/native-view.d.ts +2 -0
  49. package/dist/types/tools/output-meta.d.ts +27 -0
  50. package/dist/types/tools/read.d.ts +14 -4
  51. package/dist/types/tools/task.d.ts +4 -3
  52. package/dist/types/tools/wait.d.ts +2 -0
  53. package/dist/types/tui.d.ts +12 -0
  54. package/dist/types/utils.d.ts +4 -0
  55. package/package.json +9 -9
  56. package/src/app-keybindings.d.ts +5 -0
  57. package/src/app-keybindings.ts +5 -0
  58. package/src/apps/git/git-tui.ts +10 -17
  59. package/src/apps/git/sidebar.ts +21 -35
  60. package/src/apps/ps-top.ts +4 -12
  61. package/src/charts/chart-plan.ts +0 -29
  62. package/src/charts/table-data.d.ts +4 -2
  63. package/src/charts/table-data.ts +55 -6
  64. package/src/chat/bash-execution.d.ts +4 -1
  65. package/src/chat/bash-execution.ts +20 -9
  66. package/src/chat/chat-transcript-builder.ts +5 -2
  67. package/src/chat/eval-execution.d.ts +2 -0
  68. package/src/chat/eval-execution.ts +14 -7
  69. package/src/chat/execution-shared.d.ts +14 -8
  70. package/src/chat/execution-shared.ts +39 -18
  71. package/src/chat/figure-markdown.d.ts +2 -0
  72. package/src/chat/figure-markdown.ts +6 -4
  73. package/src/chat/read-tool-group.ts +56 -36
  74. package/src/chat/svg-figure.d.ts +5 -0
  75. package/src/chat/svg-figure.ts +55 -16
  76. package/src/chat/table-chart.d.ts +2 -0
  77. package/src/chat/table-chart.ts +19 -2
  78. package/src/chat/transcript-render-helpers.d.ts +11 -3
  79. package/src/chat/transcript-render-helpers.ts +70 -22
  80. package/src/chrome/dynamic-border.d.ts +6 -0
  81. package/src/chrome/dynamic-border.ts +28 -2
  82. package/src/chrome/transcript-status.d.ts +2 -2
  83. package/src/chrome/transcript-status.ts +5 -3
  84. package/src/components/editor.d.ts +15 -6
  85. package/src/components/editor.ts +123 -24
  86. package/src/components/image.d.ts +6 -0
  87. package/src/components/image.ts +13 -0
  88. package/src/components/key-value-list.ts +9 -9
  89. package/src/components/loader.d.ts +2 -0
  90. package/src/components/loader.ts +7 -0
  91. package/src/components/section.ts +1 -9
  92. package/src/components/table.ts +1 -9
  93. package/src/keybinding-matchers.d.ts +7 -0
  94. package/src/keybinding-matchers.ts +13 -0
  95. package/src/native/backend.ts +7 -3
  96. package/src/native/describe.d.ts +4 -2
  97. package/src/native/describe.ts +9 -4
  98. package/src/native/node.d.ts +2 -3
  99. package/src/native/node.ts +2 -3
  100. package/src/native/overlay.d.ts +42 -2
  101. package/src/native/overlay.ts +124 -16
  102. package/src/native/state.d.ts +4 -0
  103. package/src/native/state.ts +25 -5
  104. package/src/overlays/btw-history-panel.ts +106 -14
  105. package/src/overlays/btw-history.ts +65 -0
  106. package/src/overlays/btw-inject.ts +91 -0
  107. package/src/overlays/btw-panel.ts +53 -12
  108. package/src/overlays/extensions/extension-dashboard.ts +7 -8
  109. package/src/overlays/hook-editor.ts +6 -0
  110. package/src/overlays/jobs-panel.ts +82 -22
  111. package/src/overlays/login-dialog.ts +8 -26
  112. package/src/overlays/model-browser.ts +69 -10
  113. package/src/overlays/session-selector.ts +25 -5
  114. package/src/overlays/settings-defs.ts +2 -2
  115. package/src/overlays/settings-selector.ts +113 -11
  116. package/src/overlays/tree-selector.ts +83 -27
  117. package/src/overlays/usage-dashboard.ts +4 -6
  118. package/src/prompt/composer.ts +17 -5
  119. package/src/render/code-cell.ts +1 -1
  120. package/src/render/file-list.ts +4 -7
  121. package/src/render/render-utils.d.ts +23 -1
  122. package/src/render/render-utils.ts +38 -6
  123. package/src/setup/scenes/glyph.ts +1 -1
  124. package/src/setup/scenes/language.ts +122 -0
  125. package/src/setup/scenes/types.ts +6 -0
  126. package/src/setup/setup-version.ts +1 -1
  127. package/src/setup/wizard.ts +2 -0
  128. package/src/status-line/startup.ts +36 -70
  129. package/src/terminal-capabilities.d.ts +1 -1
  130. package/src/terminal-capabilities.ts +5 -0
  131. package/src/theme/symbols.d.ts +3 -1
  132. package/src/theme/symbols.ts +16 -9
  133. package/src/theme/theme-class.d.ts +1 -0
  134. package/src/theme/theme-class.ts +15 -3
  135. package/src/theme/theme.d.ts +1 -1
  136. package/src/theme/theme.ts +1 -0
  137. package/src/theme/tui-adapters.d.ts +2 -0
  138. package/src/theme/tui-adapters.ts +8 -3
  139. package/src/thinking.d.ts +8 -6
  140. package/src/thinking.ts +17 -11
  141. package/src/tmux.ts +1 -0
  142. package/src/tools/agent-tree.ts +13 -11
  143. package/src/tools/ask.ts +24 -37
  144. package/src/tools/ast-edit.ts +48 -93
  145. package/src/tools/ast-grep.d.ts +2 -0
  146. package/src/tools/ast-grep.ts +31 -67
  147. package/src/tools/bash.ts +7 -0
  148. package/src/tools/default-renderer.ts +1 -1
  149. package/src/tools/edit.ts +50 -43
  150. package/src/tools/eval.d.ts +2 -0
  151. package/src/tools/eval.ts +2 -0
  152. package/src/tools/fetch.ts +2 -1
  153. package/src/tools/find.d.ts +1 -1
  154. package/src/tools/find.ts +13 -5
  155. package/src/tools/github.ts +14 -46
  156. package/src/tools/glob.ts +2 -1
  157. package/src/tools/grep.ts +47 -277
  158. package/src/tools/grouped-file-output.d.ts +100 -19
  159. package/src/tools/grouped-file-output.ts +414 -103
  160. package/src/tools/hashline-format.d.ts +5 -0
  161. package/src/tools/hashline-format.ts +5 -0
  162. package/src/tools/json-tree.ts +1 -5
  163. package/src/tools/lsp.ts +210 -32
  164. package/src/tools/native-view.d.ts +2 -0
  165. package/src/tools/native-view.ts +11 -5
  166. package/src/tools/output-meta.d.ts +27 -0
  167. package/src/tools/output-meta.ts +68 -4
  168. package/src/tools/proc-render.ts +3 -3
  169. package/src/tools/read.d.ts +14 -4
  170. package/src/tools/read.ts +20 -5
  171. package/src/tools/task.d.ts +4 -3
  172. package/src/tools/task.ts +41 -81
  173. package/src/tools/vibe.ts +4 -4
  174. package/src/tools/wait.d.ts +2 -0
  175. package/src/tools/wait.ts +8 -5
  176. package/src/tools/write.ts +17 -27
  177. package/src/tools/yield.ts +1 -1
  178. package/src/tui.d.ts +12 -0
  179. package/src/tui.ts +91 -9
  180. package/src/utils.d.ts +4 -0
  181. package/src/utils.ts +10 -0
@@ -71,6 +71,8 @@ export declare class Loader extends Text {
71
71
  stop(): void;
72
72
  /** Lifecycle teardown: stop the animation timer. Idempotent. */
73
73
  dispose(): void;
74
+ /** The current spinner frame and message as one styled line, for hosts that set it into their own chrome. */
75
+ inlineText(): string;
74
76
  /** Install a lazy right-docked suffix for the spinner row (e.g. a styled
75
77
  * session title). Re-evaluated every paint; dropped when the row leaves
76
78
  * less than a two-cell gap. */
@@ -325,6 +325,13 @@ export class Loader extends Text {
325
325
  dispose() {
326
326
  this.stop();
327
327
  }
328
+
329
+ /** The current spinner frame and message as one styled line, for hosts that set it into their own chrome. */
330
+ inlineText(): string {
331
+ const spinner = this.spinnerColorFn(this.#frames[this.#currentFrame]);
332
+ return `${spinner} ${this.messageColorFn(this.#resolveMessage())}`;
333
+ }
334
+
328
335
  /** Install a lazy right-docked suffix for the spinner row (e.g. a styled
329
336
  * session title). Re-evaluated every paint; dropped when the row leaves
330
337
  * less than a two-cell gap. */
@@ -2,20 +2,12 @@ import { compactText, rowsText, styledSpans } from "../native/spans";
2
2
  import { node } from "../native/describe";
3
3
  import type { DescribeContext, NativeNode } from "../native/node";
4
4
  import type { Component } from "../tui";
5
- import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
5
+ import { Ellipsis, finiteWidth, getWidthConfigEpoch, singleLine, truncateToWidth, visibleWidth } from "../utils";
6
6
 
7
7
  function isComponent(body: Component | readonly string[]): body is Component {
8
8
  return !Array.isArray(body);
9
9
  }
10
10
 
11
- function finiteWidth(width: number): number {
12
- return Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : 0;
13
- }
14
-
15
- function singleLine(text: string): string {
16
- return replaceTabs(text).replace(/[\r\n]+/g, " ");
17
- }
18
-
19
11
  function fillCells(glyph: string, width: number): string {
20
12
  const cleanGlyph = singleLine(glyph);
21
13
  const glyphWidth = visibleWidth(cleanGlyph);
@@ -3,7 +3,7 @@ import { compactText, styleSpans } from "../native/spans";
3
3
  import { node } from "../native/describe";
4
4
  import type { DescribeContext, NativeNode } from "../native/node";
5
5
  import type { Component } from "../tui";
6
- import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
6
+ import { Ellipsis, finiteWidth, getWidthConfigEpoch, singleLine, truncateToWidth, visibleWidth } from "../utils";
7
7
 
8
8
  /** One table cell. Styling is applied after alignment so padding shares the cell style. */
9
9
  export interface TableCell {
@@ -29,14 +29,6 @@ export interface TableOptions {
29
29
  readonly fit?: boolean;
30
30
  }
31
31
 
32
- function finiteWidth(width: number, fallback = 0): number {
33
- return Number.isFinite(width) ? Math.max(0, Math.trunc(width)) : fallback;
34
- }
35
-
36
- function singleLine(text: string): string {
37
- return replaceTabs(text).replace(/[\r\n]+/g, " ");
38
- }
39
-
40
32
  function fitWidths(columns: readonly TableColumn[], maxWidth: number, gapWidth: number): number[] {
41
33
  const widths = columns.map(column => finiteWidth(column.width));
42
34
  let overflow = widths.reduce((sum, width) => sum + width, 0) + Math.max(0, columns.length - 1) * gapWidth - maxWidth;
@@ -42,3 +42,10 @@ export declare function matchesAppFollowUp(data: string): boolean;
42
42
  export declare function appApproveKeys(): readonly KeyId[];
43
43
  /** Match the tool-approval key, recognizing modifier-tagged LF as Ctrl+Enter like {@link matchesAppFollowUp}. */
44
44
  export declare function matchesAppApprove(data: string): boolean;
45
+ /**
46
+ * Effective /btw inject key (Alt+I by default). No fallback: it sends text into the main
47
+ * session, so a user who unbinds it gets no key at all.
48
+ */
49
+ export declare function appBtwInjectKey(): KeyId | undefined;
50
+ /** Match the key that sends a /btw answer's steering prompt to the main session. */
51
+ export declare function matchesAppBtwInject(data: string): boolean;
@@ -120,3 +120,16 @@ export function appApproveKeys(): readonly KeyId[] {
120
120
  export function matchesAppApprove(data: string): boolean {
121
121
  return matchesEffectiveKeys(data, appApproveKeys());
122
122
  }
123
+
124
+ /**
125
+ * Effective /btw inject key (Alt+I by default). No fallback: it sends text into the main
126
+ * session, so a user who unbinds it gets no key at all.
127
+ */
128
+ export function appBtwInjectKey(): KeyId | undefined {
129
+ return getKeybindings().getKeys("app.btw.inject")[0];
130
+ }
131
+
132
+ /** Match the key that sends a /btw answer's steering prompt to the main session. */
133
+ export function matchesAppBtwInject(data: string): boolean {
134
+ return getKeybindings().matches(data, "app.btw.inject");
135
+ }
@@ -48,7 +48,7 @@ import { encodeTspJson, encodeTspMessage, type TspHello, TspReader, splitTspMess
48
48
  import type { DescribeContext, NativeChild, NativeNode, NativeSurface, NativeUiEvent } from "./node";
49
49
  import { NARROW_SHEET_COLS } from "./overlay";
50
50
  import { nativeComponentId, Reconciler } from "./reconcile";
51
- import { setNativeRendering } from "./state";
51
+ import { setNativeButtons, setNativeRendering } from "./state";
52
52
 
53
53
  /** A visible TUI overlay, bottom to top. */
54
54
  export interface NativeOverlay {
@@ -199,9 +199,10 @@ function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
199
199
  * Kinds newer than some Tern builds that answer `TERM_PROGRAM=tern`: used only
200
200
  * once the real `hello` lists them, so the optimistic start never emits a node
201
201
  * an older terminal cannot draw (`media`: files Tern loads by path; `json`:
202
- * raw JSON values Tern draws as its own tree).
202
+ * raw JSON values Tern draws as its own tree; `button`: omp's buttons, which
203
+ * older builds get as role-styled rows).
203
204
  */
204
- const UNASSUMED_KINDS: Partial<Record<TspKind, true>> = { media: true, json: true };
205
+ const UNASSUMED_KINDS: Partial<Record<TspKind, true>> = { media: true, json: true, button: true };
205
206
 
206
207
  /**
207
208
  * The reply a v1 terminal is assumed to give before its real `hello` arrives
@@ -380,6 +381,7 @@ export class NativeBackend {
380
381
  this.#close(this.#inline, keep);
381
382
  this.#inline.doc?.close();
382
383
  setNativeRendering(false);
384
+ setNativeButtons(false);
383
385
  this.#useNerdSymbols(false);
384
386
  this.#clearStallTimer();
385
387
  // Replies no longer reach the backend: forget the queries outright.
@@ -539,6 +541,8 @@ export class NativeBackend {
539
541
  this.#limit = hello.apc !== undefined && hello.apc > 0 ? hello.apc : TSP_DEFAULT_APC_LIMIT;
540
542
  this.#credits = hello.credits !== undefined && hello.credits > 0 ? hello.credits : TSP_DEFAULT_CREDITS;
541
543
  this.#cx = new NativeContext(hello, hello.cols ?? this.#cx.cols);
544
+ // A changed vocabulary re-describes every component (`confirm`).
545
+ setNativeButtons(this.#cx.supports("button"));
542
546
  this.#sawResize = false;
543
547
  }
544
548
 
@@ -56,7 +56,9 @@ export declare function list(items: readonly NativeChild[], p?: TspProps<"list">
56
56
  /** Terminal-clocked elapsed counter: `age` ms already elapsed; `stopped` freezes it there. */
57
57
  export declare function elapsed(age: number, stopped?: boolean): NativeNode;
58
58
  /**
59
- * Keycap for one key id (`"ctrl+o"` → keys `["ctrl", "o"]`); the terminal
60
- * draws platform glyphs. A literal `+` key survives (`"+"`, `"ctrl++"`).
59
+ * The key names of one key id (`"ctrl+o"` → `["ctrl", "o"]`), as `kbd` and
60
+ * `button` `keys` take them. A literal `+` key survives (`"+"`, `"ctrl++"`).
61
61
  */
62
+ export declare function keyNames(key: string): string[];
63
+ /** Keycap for one key id ({@link keyNames}); the terminal draws platform glyphs. */
62
64
  export declare function kbd(key: string, nodeKey?: string): NativeNode;
@@ -132,10 +132,15 @@ export function elapsed(age: number, stopped?: boolean): NativeNode {
132
132
  }
133
133
 
134
134
  /**
135
- * Keycap for one key id (`"ctrl+o"` → keys `["ctrl", "o"]`); the terminal
136
- * draws platform glyphs. A literal `+` key survives (`"+"`, `"ctrl++"`).
135
+ * The key names of one key id (`"ctrl+o"` → `["ctrl", "o"]`), as `kbd` and
136
+ * `button` `keys` take them. A literal `+` key survives (`"+"`, `"ctrl++"`).
137
137
  */
138
- export function kbd(key: string, nodeKey?: string): NativeNode {
138
+ export function keyNames(key: string): string[] {
139
139
  const keys = key === "+" ? ["+"] : key.endsWith("++") ? [...key.slice(0, -2).split("+"), "+"] : key.split("+");
140
- return node("kbd", { keys: keys.filter(part => part.length > 0) }, undefined, nodeKey);
140
+ return keys.filter(part => part.length > 0);
141
+ }
142
+
143
+ /** Keycap for one key id ({@link keyNames}); the terminal draws platform glyphs. */
144
+ export function kbd(key: string, nodeKey?: string): NativeNode {
145
+ return node("kbd", { keys: keyNames(key) }, undefined, nodeKey);
141
146
  }
@@ -10,9 +10,8 @@
10
10
  * reference contract as `render()`). A component without `describe` becomes a
11
11
  * `rows` fallback node rendered through `render(cx.cols)`.
12
12
  *
13
- * See `packages/wire/src/tsp.ts` for the wire vocabulary and
14
- * the Tern SDK's Surface Protocol reference (`docs/sdk/src/protocol` in the
15
- * Stencil repository, https://docs.stencil.so/tern/protocol/) for the spec.
13
+ * See `packages/wire/src/tsp.ts` for the wire vocabulary; the normative spec is
14
+ * the Tern Surface Protocol.
16
15
  */
17
16
  import type { TspEvent, TspKind, TspProps, TspScrollBy, TspSpan } from "@linxiraos/pi-wire";
18
17
  import type { Component } from "../tui";
@@ -10,9 +10,8 @@
10
10
  * reference contract as `render()`). A component without `describe` becomes a
11
11
  * `rows` fallback node rendered through `render(cx.cols)`.
12
12
  *
13
- * See `packages/wire/src/tsp.ts` for the wire vocabulary and
14
- * the Tern SDK's Surface Protocol reference (`docs/sdk/src/protocol` in the
15
- * Stencil repository, https://docs.stencil.so/tern/protocol/) for the spec.
13
+ * See `packages/wire/src/tsp.ts` for the wire vocabulary; the normative spec is
14
+ * the Tern Surface Protocol.
16
15
  */
17
16
  import type { TspEvent, TspKind, TspProps, TspScrollBy, TspSpan } from "@linxiraos/pi-wire";
18
17
  import type { Component } from "../tui";
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Overlay chrome for `describe()`: root cards, key-hint footers, selectable
3
- * lists and annotation callouts.
2
+ * Overlay chrome for `describe()`: root cards, key-hint footers, buttons and
3
+ * segmented controls, selectable lists and annotation callouts.
4
4
  *
5
5
  * The overlay frame itself (glass, ring, placement) is the terminal's: the
6
6
  * engine wraps every overlay-stack component in an `overlay` node. An overlay
@@ -53,11 +53,23 @@ export interface ActionButtonOptions {
53
53
  readonly title?: string;
54
54
  /** Target of an `open` action (URL or `file://` path). */
55
55
  readonly href?: string;
56
+ /** Why the action can't run now: the button dims and a click sends nothing. */
57
+ readonly disabled?: string;
58
+ /** The button's work is running: a spinner leads the label. */
59
+ readonly busy?: boolean;
60
+ /** Icon beside the label (before it on a `button` node, after it on a row). */
61
+ readonly icon?: string;
56
62
  }
57
63
  /**
58
64
  * A native button (role `zeta.btn`): a label plus an optional keycap. A click
59
65
  * sends `act` back as an `action` event (or runs a terminal-local `open`/`copy`),
60
66
  * which the component routes to the same code path as the key.
67
+ *
68
+ * A terminal that draws the `button` kind ({@link nativeButtons}) gets one
69
+ * (tone `accent` → variant `primary`, `error` → `danger`, `disabled` with its
70
+ * reason as the tooltip); older ones get the row their stylesheets draw by
71
+ * role. Both keep the role and tone the omp sheets' context rules key on; a
72
+ * disabled button's tone is `muted`.
61
73
  */
62
74
  export declare function actionButton(label: string, act: string, options?: ActionButtonOptions): NativeNode;
63
75
  /**
@@ -65,6 +77,34 @@ export declare function actionButton(label: string, act: string, options?: Actio
65
77
  * `act` (default `close`), which the component routes to its Esc path.
66
78
  */
67
79
  export declare function escCloseButton(act?: string, key?: string): NativeNode;
80
+ /** Options of an {@link iconButton}. */
81
+ export interface IconButtonOptions {
82
+ /** Sibling identity key; unkeyed buttons take their position. */
83
+ readonly key?: string;
84
+ /** Accessible name; defaults to the title. */
85
+ readonly aria?: string;
86
+ /** A toggle that is on (role `zeta.app.ibtn.set`). */
87
+ readonly on?: boolean;
88
+ }
89
+ /**
90
+ * A quiet icon-only button (role `zeta.app.ibtn`, the kit's icon button) for an
91
+ * app head or toolbar: a `button` node where the terminal draws one
92
+ * ({@link nativeButtons}), else an `icon` with a click action.
93
+ */
94
+ export declare function iconButton(name: string, act: string, title: string, options?: IconButtonOptions): NativeNode;
95
+ /**
96
+ * A quiet text button (role `zeta.app.qbtn`, the kit's quiet button) for a
97
+ * section head or toolbar, keyed by its action: a small quiet `button` where
98
+ * the terminal draws one ({@link nativeButtons}), else a row.
99
+ */
100
+ export declare function quietButton(label: string, act: string, title: string): NativeNode;
101
+ /**
102
+ * A segmented control: `tabs` drawn as a well with a raised thumb on the
103
+ * active tab. A terminal that draws the `button` kind ({@link nativeButtons})
104
+ * draws `variant: "segmented"` too; older ones restyle the tabs by role
105
+ * (`zeta.app.seg`) or parent.
106
+ */
107
+ export declare function segmentedTabs(p: TspProps<"tabs">, key: string): NativeNode;
68
108
  /** A row of {@link actionButton}s (role `zeta.actions`); `null` entries become the spacer that end-aligns what follows. */
69
109
  export declare function actionBar(buttons: readonly (NativeNode | null)[], key?: string): NativeNode;
70
110
  /** Spans of an annotation callout: a dim `label:` then the note. */
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Overlay chrome for `describe()`: root cards, key-hint footers, selectable
3
- * lists and annotation callouts.
2
+ * Overlay chrome for `describe()`: root cards, key-hint footers, buttons and
3
+ * segmented controls, selectable lists and annotation callouts.
4
4
  *
5
5
  * The overlay frame itself (glass, ring, placement) is the terminal's: the
6
6
  * engine wraps every overlay-stack component in an `overlay` node. An overlay
@@ -9,8 +9,9 @@
9
9
  import type { TspProps, TspSpan, TspText } from "@linxiraos/pi-wire";
10
10
  import { formatTooltipKey, type KeyName } from "../key-hint-format";
11
11
  import { getKeybindings, type Keybinding } from "../keybindings";
12
- import { card, kbd, list, node, row, span, text } from "./describe";
12
+ import { card, kbd, keyNames, list, node, row, span, text } from "./describe";
13
13
  import type { NativeChild, NativeNode } from "./node";
14
+ import { nativeButtons } from "./state";
14
15
 
15
16
  /** Below this many columns a centered sheet fills the pane instead of floating with margins. */
16
17
  export const NARROW_SHEET_COLS = 100;
@@ -96,29 +97,68 @@ export interface ActionButtonOptions {
96
97
  readonly title?: string;
97
98
  /** Target of an `open` action (URL or `file://` path). */
98
99
  readonly href?: string;
100
+ /** Why the action can't run now: the button dims and a click sends nothing. */
101
+ readonly disabled?: string;
102
+ /** The button's work is running: a spinner leads the label. */
103
+ readonly busy?: boolean;
104
+ /** Icon beside the label (before it on a `button` node, after it on a row). */
105
+ readonly icon?: string;
99
106
  }
100
107
 
101
108
  /**
102
109
  * A native button (role `zeta.btn`): a label plus an optional keycap. A click
103
110
  * sends `act` back as an `action` event (or runs a terminal-local `open`/`copy`),
104
111
  * which the component routes to the same code path as the key.
112
+ *
113
+ * A terminal that draws the `button` kind ({@link nativeButtons}) gets one
114
+ * (tone `accent` → variant `primary`, `error` → `danger`, `disabled` with its
115
+ * reason as the tooltip); older ones get the row their stylesheets draw by
116
+ * role. Both keep the role and tone the omp sheets' context rules key on; a
117
+ * disabled button's tone is `muted`.
105
118
  */
106
119
  export function actionButton(label: string, act: string, options: ActionButtonOptions = {}): NativeNode {
107
- const children: NativeChild[] = [text(label)];
108
- if (options.keys) children.push(kbd(options.keys));
120
+ const { keys, href, disabled, busy, icon } = options;
121
+ const title = options.title ?? (keys ? `${label} ${formatTooltipKey(keys)}` : label);
122
+ const tone = disabled === undefined ? options.tone : "muted";
123
+ const key = options.key ?? act;
124
+ if (nativeButtons()) {
125
+ return node(
126
+ "button",
127
+ {
128
+ role: "zeta.btn",
129
+ text: label,
130
+ actions: { click: act },
131
+ title,
132
+ ...(keys ? { keys: keyNames(keys) } : {}),
133
+ ...(icon ? { icon } : {}),
134
+ ...(tone === "accent" ? { variant: "primary" } : tone === "error" ? { variant: "danger" } : {}),
135
+ ...(tone ? { tone } : {}),
136
+ ...(disabled !== undefined ? { disabled: disabled || true } : {}),
137
+ ...(busy ? { busy } : {}),
138
+ ...(href ? { href } : {}),
139
+ },
140
+ undefined,
141
+ key,
142
+ );
143
+ }
144
+ const children: NativeChild[] = [];
145
+ if (busy) children.push(node("spinner", { style: "dots" }));
146
+ children.push(text(label));
147
+ if (icon) children.push(node("icon", { name: icon }, undefined, "icon"));
148
+ if (keys) children.push(kbd(keys));
109
149
  return node(
110
150
  "row",
111
151
  {
112
152
  role: "zeta.btn",
113
153
  gap: "xs",
114
154
  align: "center",
115
- actions: { click: act },
116
- title: options.title ?? (options.keys ? `${label} ${formatTooltipKey(options.keys)}` : label),
117
- ...(options.tone ? { tone: options.tone } : {}),
118
- ...(options.href ? { href: options.href } : {}),
155
+ ...(disabled === undefined ? { actions: { click: act } } : {}),
156
+ title,
157
+ ...(tone ? { tone } : {}),
158
+ ...(href ? { href } : {}),
119
159
  },
120
160
  children,
121
- options.key ?? act,
161
+ key,
122
162
  );
123
163
  }
124
164
 
@@ -127,12 +167,80 @@ export function actionButton(label: string, act: string, options: ActionButtonOp
127
167
  * `act` (default `close`), which the component routes to its Esc path.
128
168
  */
129
169
  export function escCloseButton(act = "close", key = "esc-close"): NativeNode {
130
- return node(
131
- "row",
132
- { role: "zeta.btn", align: "center", actions: { click: act }, title: `Close ${formatTooltipKey("escape")}` },
133
- [kbd("escape")],
134
- key,
135
- );
170
+ const title = `Close ${formatTooltipKey("escape")}`;
171
+ if (nativeButtons()) {
172
+ return node(
173
+ "button",
174
+ { role: "zeta.btn", keys: ["escape"], actions: { click: act }, title, aria: "Close" },
175
+ undefined,
176
+ key,
177
+ );
178
+ }
179
+ return node("row", { role: "zeta.btn", align: "center", actions: { click: act }, title }, [kbd("escape")], key);
180
+ }
181
+
182
+ /** Options of an {@link iconButton}. */
183
+ export interface IconButtonOptions {
184
+ /** Sibling identity key; unkeyed buttons take their position. */
185
+ readonly key?: string;
186
+ /** Accessible name; defaults to the title. */
187
+ readonly aria?: string;
188
+ /** A toggle that is on (role `zeta.app.ibtn.set`). */
189
+ readonly on?: boolean;
190
+ }
191
+
192
+ /**
193
+ * A quiet icon-only button (role `zeta.app.ibtn`, the kit's icon button) for an
194
+ * app head or toolbar: a `button` node where the terminal draws one
195
+ * ({@link nativeButtons}), else an `icon` with a click action.
196
+ */
197
+ export function iconButton(name: string, act: string, title: string, options: IconButtonOptions = {}): NativeNode {
198
+ const role = options.on ? "zeta.app.ibtn.set" : "zeta.app.ibtn";
199
+ const aria = options.aria ?? title;
200
+ if (nativeButtons()) {
201
+ return node(
202
+ "button",
203
+ {
204
+ role,
205
+ variant: "quiet",
206
+ icon: name,
207
+ title,
208
+ aria,
209
+ actions: { click: act },
210
+ ...(options.on ? { on: true } : {}),
211
+ },
212
+ undefined,
213
+ options.key,
214
+ );
215
+ }
216
+ return node("icon", { name, role, title, aria, actions: { click: act } }, undefined, options.key);
217
+ }
218
+
219
+ /**
220
+ * A quiet text button (role `zeta.app.qbtn`, the kit's quiet button) for a
221
+ * section head or toolbar, keyed by its action: a small quiet `button` where
222
+ * the terminal draws one ({@link nativeButtons}), else a row.
223
+ */
224
+ export function quietButton(label: string, act: string, title: string): NativeNode {
225
+ if (nativeButtons()) {
226
+ return node(
227
+ "button",
228
+ { role: "zeta.app.qbtn", variant: "quiet", size: "sm", text: label, actions: { click: act }, title },
229
+ undefined,
230
+ act,
231
+ );
232
+ }
233
+ return node("row", { role: "zeta.app.qbtn", actions: { click: act }, title }, [text(label)], act);
234
+ }
235
+
236
+ /**
237
+ * A segmented control: `tabs` drawn as a well with a raised thumb on the
238
+ * active tab. A terminal that draws the `button` kind ({@link nativeButtons})
239
+ * draws `variant: "segmented"` too; older ones restyle the tabs by role
240
+ * (`zeta.app.seg`) or parent.
241
+ */
242
+ export function segmentedTabs(p: TspProps<"tabs">, key: string): NativeNode {
243
+ return node("tabs", nativeButtons() ? { ...p, variant: "segmented" } : p, undefined, key);
136
244
  }
137
245
 
138
246
  /** A row of {@link actionButton}s (role `zeta.actions`); `null` entries become the spacer that end-aligns what follows. */
@@ -2,5 +2,9 @@
2
2
  export declare function isNativeRendering(): boolean;
3
3
  /** Called by the native backend on surface open and close. */
4
4
  export declare function setNativeRendering(on: boolean): void;
5
+ /** Whether omp's buttons go out as `button` nodes (see {@link setNativeButtons}). */
6
+ export declare function nativeButtons(): boolean;
7
+ /** Called by the native backend when it adopts a `hello` reply and when it stops. */
8
+ export declare function setNativeButtons(on: boolean): void;
5
9
  /** Call `listener` whenever native rendering starts or stops; returns the unsubscribe. */
6
10
  export declare function onNativeRenderingChange(listener: (on: boolean) => void): () => void;
@@ -1,10 +1,11 @@
1
1
  /**
2
- * Process-wide flag: a Tern Surface Protocol backend is rendering.
2
+ * Process-wide native rendering state, set only by the native backend.
3
3
  *
4
- * Components that animate by re-rendering on a timer (spinners, shimmer,
5
- * thinking frames, countdowns) check it and skip scheduling, because the
6
- * terminal clocks motion from the described nodes. Set only by the native
7
- * backend when a surface opens and cleared when it closes.
4
+ * Whether a Tern Surface Protocol backend is rendering: components that
5
+ * animate by re-rendering on a timer (spinners, shimmer, thinking frames,
6
+ * countdowns) check it and skip scheduling, because the terminal clocks
7
+ * motion from the described nodes. Set when a surface opens and cleared when
8
+ * it closes.
8
9
  */
9
10
  let active = false;
10
11
  const listeners = new Set<(on: boolean) => void>();
@@ -21,6 +22,25 @@ export function setNativeRendering(on: boolean): void {
21
22
  for (const listener of listeners) listener(on);
22
23
  }
23
24
 
25
+ /**
26
+ * Whether the live terminal draws the `button` kind (its `hello` lists it),
27
+ * and with it `tabs` `variant: "segmented"`. The button builders
28
+ * (`native/overlay.ts`) read it; older Terns get the `row` buttons they style
29
+ * by role. Set only by the native backend from the `hello` it adopts; false
30
+ * while no surface is live.
31
+ */
32
+ let buttons = false;
33
+
34
+ /** Whether omp's buttons go out as `button` nodes (see {@link setNativeButtons}). */
35
+ export function nativeButtons(): boolean {
36
+ return buttons;
37
+ }
38
+
39
+ /** Called by the native backend when it adopts a `hello` reply and when it stops. */
40
+ export function setNativeButtons(on: boolean): void {
41
+ buttons = on;
42
+ }
43
+
24
44
  /** Call `listener` whenever native rendering starts or stops; returns the unsubscribe. */
25
45
  export function onNativeRenderingChange(listener: (on: boolean) => void): () => void {
26
46
  listeners.add(listener);