@noldova/terminal.window 0.0.0-stage → 0.0.2

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 (166) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +38 -2
  3. package/package.json +69 -4
  4. package/src/api/index.d.ts +1850 -0
  5. package/src/api/index.js +40 -0
  6. package/src/api/index.js.map +1 -0
  7. package/src/app/components/terminal-pane/terminal-pane.component.js +451 -0
  8. package/src/app/components/terminal-pane/terminal-pane.component.js.map +1 -0
  9. package/src/app/components/terminal-panel/terminal-panel.component.js +108 -0
  10. package/src/app/components/terminal-panel/terminal-panel.component.js.map +1 -0
  11. package/src/app/components/terminal-session/terminal-session.component.js +115 -0
  12. package/src/app/components/terminal-session/terminal-session.component.js.map +1 -0
  13. package/src/app/enums/command-token-kind.js +19 -0
  14. package/src/app/enums/command-token-kind.js.map +1 -0
  15. package/src/app/enums/terminal-ended-by.js +13 -0
  16. package/src/app/enums/terminal-ended-by.js.map +1 -0
  17. package/src/app/exceptions/embedded-rows-refused.exception.js +22 -0
  18. package/src/app/exceptions/embedded-rows-refused.exception.js.map +1 -0
  19. package/src/app/exceptions/launch-argument-refused.exception.js +20 -0
  20. package/src/app/exceptions/launch-argument-refused.exception.js.map +1 -0
  21. package/src/app/exceptions/launch-folder-missing.exception.js +19 -0
  22. package/src/app/exceptions/launch-folder-missing.exception.js.map +1 -0
  23. package/src/app/exceptions/launch-part-inactive.exception.js +17 -0
  24. package/src/app/exceptions/launch-part-inactive.exception.js.map +1 -0
  25. package/src/app/exceptions/launch-rows-refused.exception.js +19 -0
  26. package/src/app/exceptions/launch-rows-refused.exception.js.map +1 -0
  27. package/src/app/exceptions/launch-rows-without-tab.exception.js +17 -0
  28. package/src/app/exceptions/launch-rows-without-tab.exception.js.map +1 -0
  29. package/src/app/exceptions/launch-title-refused.exception.js +19 -0
  30. package/src/app/exceptions/launch-title-refused.exception.js.map +1 -0
  31. package/src/app/exceptions/owners-provided.exception.js +16 -0
  32. package/src/app/exceptions/owners-provided.exception.js.map +1 -0
  33. package/src/app/exceptions/run-argument-refused.exception.js +20 -0
  34. package/src/app/exceptions/run-argument-refused.exception.js.map +1 -0
  35. package/src/app/exceptions/run-lines-refused.exception.js +20 -0
  36. package/src/app/exceptions/run-lines-refused.exception.js.map +1 -0
  37. package/src/app/exceptions/run-part-inactive.exception.js +17 -0
  38. package/src/app/exceptions/run-part-inactive.exception.js.map +1 -0
  39. package/src/app/exceptions/run-shell-kinds-missing.exception.js +19 -0
  40. package/src/app/exceptions/run-shell-kinds-missing.exception.js.map +1 -0
  41. package/src/app/exceptions/start-folder-provided.exception.js +16 -0
  42. package/src/app/exceptions/start-folder-provided.exception.js.map +1 -0
  43. package/src/app/exceptions/terminal-launch-refused.exception.js +15 -0
  44. package/src/app/exceptions/terminal-launch-refused.exception.js.map +1 -0
  45. package/src/app/exceptions/terminal-not-active.exception.js +16 -0
  46. package/src/app/exceptions/terminal-not-active.exception.js.map +1 -0
  47. package/src/app/exceptions/terminal-run-not-found.exception.js +20 -0
  48. package/src/app/exceptions/terminal-run-not-found.exception.js.map +1 -0
  49. package/src/app/exceptions/terminal-run-not-typed.exception.js +20 -0
  50. package/src/app/exceptions/terminal-run-not-typed.exception.js.map +1 -0
  51. package/src/app/exceptions/terminal-run-refused.exception.js +15 -0
  52. package/src/app/exceptions/terminal-run-refused.exception.js.map +1 -0
  53. package/src/app/exceptions/terminal-window.exception.js +15 -0
  54. package/src/app/exceptions/terminal-window.exception.js.map +1 -0
  55. package/src/app/interfaces/i-sized-pane.js +8 -0
  56. package/src/app/interfaces/i-sized-pane.js.map +1 -0
  57. package/src/app/interfaces/i-start-folder-provider.js +8 -0
  58. package/src/app/interfaces/i-start-folder-provider.js.map +1 -0
  59. package/src/app/interfaces/i-terminal-focus-target.js +8 -0
  60. package/src/app/interfaces/i-terminal-focus-target.js.map +1 -0
  61. package/src/app/interfaces/i-terminal-restart-target.js +8 -0
  62. package/src/app/interfaces/i-terminal-restart-target.js.map +1 -0
  63. package/src/app/interfaces/i-terminal-sink.js +8 -0
  64. package/src/app/interfaces/i-terminal-sink.js.map +1 -0
  65. package/src/app/models/command-color-run.js +23 -0
  66. package/src/app/models/command-color-run.js.map +1 -0
  67. package/src/app/models/command-color-span.js +39 -0
  68. package/src/app/models/command-color-span.js.map +1 -0
  69. package/src/app/models/command-colors.js +17 -0
  70. package/src/app/models/command-colors.js.map +1 -0
  71. package/src/app/models/command-continuation.js +16 -0
  72. package/src/app/models/command-continuation.js.map +1 -0
  73. package/src/app/models/command-token.js +18 -0
  74. package/src/app/models/command-token.js.map +1 -0
  75. package/src/app/models/ended-pane.js +20 -0
  76. package/src/app/models/ended-pane.js.map +1 -0
  77. package/src/app/models/launched-terminal.js +31 -0
  78. package/src/app/models/launched-terminal.js.map +1 -0
  79. package/src/app/models/stored-lines-window.js +66 -0
  80. package/src/app/models/stored-lines-window.js.map +1 -0
  81. package/src/app/models/terminal-appearance.js +20 -0
  82. package/src/app/models/terminal-appearance.js.map +1 -0
  83. package/src/app/models/terminal-dock-growth.js +15 -0
  84. package/src/app/models/terminal-dock-growth.js.map +1 -0
  85. package/src/app/models/terminal-end.js +16 -0
  86. package/src/app/models/terminal-end.js.map +1 -0
  87. package/src/app/models/terminal-launch.js +28 -0
  88. package/src/app/models/terminal-launch.js.map +1 -0
  89. package/src/app/models/terminal-new-arguments.js +46 -0
  90. package/src/app/models/terminal-new-arguments.js.map +1 -0
  91. package/src/app/models/terminal-run-end.js +16 -0
  92. package/src/app/models/terminal-run-end.js.map +1 -0
  93. package/src/app/models/terminal-run-target.js +17 -0
  94. package/src/app/models/terminal-run-target.js.map +1 -0
  95. package/src/app/models/terminal-run.js +20 -0
  96. package/src/app/models/terminal-run.js.map +1 -0
  97. package/src/app/models/terminal-tab-key.js +30 -0
  98. package/src/app/models/terminal-tab-key.js.map +1 -0
  99. package/src/app/models/terminal-tab-label.js +18 -0
  100. package/src/app/models/terminal-tab-label.js.map +1 -0
  101. package/src/app/services/command-coloring.js +259 -0
  102. package/src/app/services/command-coloring.js.map +1 -0
  103. package/src/app/services/command-line-tokens.js +267 -0
  104. package/src/app/services/command-line-tokens.js.map +1 -0
  105. package/src/app/services/command-suggestion.js +229 -0
  106. package/src/app/services/command-suggestion.js.map +1 -0
  107. package/src/app/services/completion-list.js +224 -0
  108. package/src/app/services/completion-list.js.map +1 -0
  109. package/src/app/services/embedded-terminal.js +99 -0
  110. package/src/app/services/embedded-terminal.js.map +1 -0
  111. package/src/app/services/key-router.js +33 -0
  112. package/src/app/services/key-router.js.map +1 -0
  113. package/src/app/services/link-policy.js +17 -0
  114. package/src/app/services/link-policy.js.map +1 -0
  115. package/src/app/services/pane-fitter.js +64 -0
  116. package/src/app/services/pane-fitter.js.map +1 -0
  117. package/src/app/services/pane-scrollbar.js +55 -0
  118. package/src/app/services/pane-scrollbar.js.map +1 -0
  119. package/src/app/services/paste-filter.js +14 -0
  120. package/src/app/services/paste-filter.js.map +1 -0
  121. package/src/app/services/renderer-switch.js +45 -0
  122. package/src/app/services/renderer-switch.js.map +1 -0
  123. package/src/app/services/session-sizing.js +61 -0
  124. package/src/app/services/session-sizing.js.map +1 -0
  125. package/src/app/services/terminal-connection.js +244 -0
  126. package/src/app/services/terminal-connection.js.map +1 -0
  127. package/src/app/services/terminal-dock-growths.js +27 -0
  128. package/src/app/services/terminal-dock-growths.js.map +1 -0
  129. package/src/app/services/terminal-focus.js +58 -0
  130. package/src/app/services/terminal-focus.js.map +1 -0
  131. package/src/app/services/terminal-launch-ends.js +23 -0
  132. package/src/app/services/terminal-launch-ends.js.map +1 -0
  133. package/src/app/services/terminal-launcher.js +143 -0
  134. package/src/app/services/terminal-launcher.js.map +1 -0
  135. package/src/app/services/terminal-line-encoder.js +45 -0
  136. package/src/app/services/terminal-line-encoder.js.map +1 -0
  137. package/src/app/services/terminal-owners.js +219 -0
  138. package/src/app/services/terminal-owners.js.map +1 -0
  139. package/src/app/services/terminal-pager.js +244 -0
  140. package/src/app/services/terminal-pager.js.map +1 -0
  141. package/src/app/services/terminal-part.js +21 -0
  142. package/src/app/services/terminal-part.js.map +1 -0
  143. package/src/app/services/terminal-restart-targets.js +28 -0
  144. package/src/app/services/terminal-restart-targets.js.map +1 -0
  145. package/src/app/services/terminal-run-ends.js +39 -0
  146. package/src/app/services/terminal-run-ends.js.map +1 -0
  147. package/src/app/services/terminal-run-notices.js +21 -0
  148. package/src/app/services/terminal-run-notices.js.map +1 -0
  149. package/src/app/services/terminal-runtime-client.js +231 -0
  150. package/src/app/services/terminal-runtime-client.js.map +1 -0
  151. package/src/app/services/terminal-shell-menu.js +48 -0
  152. package/src/app/services/terminal-shell-menu.js.map +1 -0
  153. package/src/app/services/terminal-start-folder.js +39 -0
  154. package/src/app/services/terminal-start-folder.js.map +1 -0
  155. package/src/app/services/terminal-theme-reader.js +93 -0
  156. package/src/app/services/terminal-theme-reader.js.map +1 -0
  157. package/src/app/services/terminal-window-part.js +164 -0
  158. package/src/app/services/terminal-window-part.js.map +1 -0
  159. package/src/app/services/url-link-provider.js +73 -0
  160. package/src/app/services/url-link-provider.js.map +1 -0
  161. package/src/app/types/ansi-color.js +8 -0
  162. package/src/app/types/ansi-color.js.map +1 -0
  163. package/src/app/types/ansi-key.js +8 -0
  164. package/src/app/types/ansi-key.js.map +1 -0
  165. package/src/resources.js +471 -0
  166. package/src/resources.js.map +1 -0
@@ -0,0 +1,1850 @@
1
+ /**
2
+ * @license
3
+ * Copyright (c) Noldova.
4
+ *
5
+ * This source code is licensed under the license found in the
6
+ * LICENSE file in the root directory of this source tree.
7
+ */
8
+
9
+ import type { EnvironmentInjector, Signal } from "@angular/core";
10
+ import type { IWindowPart, IWindowPartContext } from "@noldova/desktop.window";
11
+ import type { Exception, ExceptionOptions } from "@noldova/context.exceptions";
12
+ import type { TerminalRunBusy, TerminalRunOutcome, TerminalRunOutput, TerminalShellKind } from "@noldova/terminal.protocol";
13
+
14
+ /**
15
+ * The kinds of shell, re-exported from `@noldova/terminal.protocol`: `PowerShell`, `CommandPrompt`, `Bash`, `Zsh`, `Fish`, `Wsl` and
16
+ * `Other`. {@link TerminalOwners.runAsync} takes a list of them.
17
+ */
18
+ export { TerminalShellKind } from "@noldova/terminal.protocol";
19
+
20
+ /**
21
+ * What became of a run's commands, re-exported from `@noldova/terminal.protocol`: `Typed`, or why they weren't typed, `Input`, `Tab`,
22
+ * `Ended`, `Busy`, or `NoShell` when no shell of the run's kinds is installed, so nothing opened. {@link TerminalRunNotTypedException}
23
+ * carries the reasons but `NoShell`, for which {@link RunShellKindsMissingException} is thrown instead.
24
+ */
25
+ export { TerminalRunOutcome } from "@noldova/terminal.protocol";
26
+
27
+ /**
28
+ * What a run into a given terminal does while that terminal's shell is busy, re-exported from `@noldova/terminal.protocol`: `Refuse` or
29
+ * `Interrupt`. A {@link TerminalRunTarget} carries it.
30
+ */
31
+ export { TerminalRunBusy } from "@noldova/terminal.protocol";
32
+
33
+ /**
34
+ * A run's output with its colors, its last lines and how many earlier ones were cut, re-exported from `@noldova/terminal.protocol`.
35
+ * {@link TerminalOwners.readRunOutputAsync} gives it.
36
+ */
37
+ export { TerminalRunOutput } from "@noldova/terminal.protocol";
38
+
39
+ /**
40
+ * A line of a run's output: its text, whether it continues the line before, and its runs of color and style, re-exported from
41
+ * `@noldova/terminal.protocol`.
42
+ */
43
+ export { TerminalLine } from "@noldova/terminal.protocol";
44
+
45
+ /**
46
+ * A run of a line's text in one color and style, re-exported from `@noldova/terminal.protocol`; its colors are read with
47
+ * {@link TerminalOwners.defaultColor} and {@link TerminalOwners.rgbColor}.
48
+ */
49
+ export { TerminalTextRun } from "@noldova/terminal.protocol";
50
+
51
+ /**
52
+ * The style flags of a line's text run, whose sum is the run's style, re-exported from `@noldova/terminal.protocol`: `Bold`, `Dim`,
53
+ * `Italic`, `Underline`, `Blink`, `Inverse`, `Invisible`, `Strikethrough` and `Overline`.
54
+ */
55
+ export { TerminalTextStyle } from "@noldova/terminal.protocol";
56
+
57
+ /**
58
+ * The terminal module's window part, which Noldova Desktop's window activates.
59
+ *
60
+ * @remarks
61
+ * Activation registers the bottom panel `terminal.panel`, the bottom view `terminal.session` with a tab for each instance, a session's id, and
62
+ * the command `terminal.new`, which opens a terminal in a new tab: in the `folder` and with the `shellId` its arguments give, else in the app's
63
+ * {@link TerminalStartFolder} with the default shell, in the `tabGroup` it gives, else where Noldova Desktop chooses, for the `owner` it gives, else
64
+ * without one, or with `takesNewOwner: true` for the app's new owner ({@link TerminalOwners}); its key is Ctrl+Shift+\`, and the View menu has it. The command `terminal.toggle`, Toggle Terminal, on Ctrl+\` (Control on macOS), shows the terminal used last and gives it the
65
+ * focus, else opens one, and from a terminal gives the focus back to where it was and hides the terminal's dock. The default shell is the
66
+ * `terminal.defaultShell` setting's while the runtime finds it, else the runtime's. Every tab row that holds a terminal tab shows + and a menu of
67
+ * the shells, which open a terminal in that group: the default shell's row runs `terminal.new` and shows its key, and the others run
68
+ * `terminal.newWithShell`, which has no key and stays out of command search; + takes the app's new owner, and the rows open a terminal without
69
+ * one. The tab menu of a terminal tab, but an agent's, and of the panel offers Restart, the command
70
+ * `terminal.restartShell`, which starts its shell again in place. A terminal tab is renamed in place, as Noldova Desktop edits a renamable tab's
71
+ * title, by a double-click, F2 or its own tab-menu Rename: Enter keeps the name, for its tabs in every window and across runs, Escape
72
+ * cancels, and an empty title takes it away. The panel shows a terminal of its own, which no tab shows: the one the runtime lists as
73
+ * the panel's, or the default shell it opens the first time it shows. xterm and the pane load with the first panel or tab that shows.
74
+ * Closing a tab ends its terminal, unless an agent's session owns it; activation reopens a tab for each of the person's terminals the runtime
75
+ * still has, but the panel's, so a reload keeps them. Before that it has the runtime open again, once a run, the terminals the last run left
76
+ * open, so a new start of the app keeps them too.
77
+ * After the runtime starts again, the part has it open the last run's terminals again first, and every pane attaches again from a snapshot;
78
+ * a pane whose terminal is gone keeps its last screen with a Restart action.
79
+ * @example
80
+ * ```ts
81
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
82
+ * import { windowPart } from "@noldova/terminal/window";
83
+ *
84
+ * export async function activateTerminalAsync(context: IWindowPartContext): Promise<void> {
85
+ * await windowPart.activateAsync(context);
86
+ * }
87
+ * ```
88
+ */
89
+ export declare const windowPart: IWindowPart;
90
+
91
+ /**
92
+ * The base of every exception the window part throws, which a caller can catch to handle any of them.
93
+ *
94
+ * @example
95
+ * ```ts
96
+ * import { TerminalNotActiveException, TerminalWindowException } from "@noldova/terminal/window";
97
+ *
98
+ * console.log(new TerminalNotActiveException() instanceof TerminalWindowException);
99
+ * ```
100
+ */
101
+ export declare class TerminalWindowException extends Exception {
102
+ /**
103
+ * `"TerminalWindowException"`, which a subclass replaces with its own.
104
+ */
105
+ public override readonly name: string;
106
+
107
+ /**
108
+ * Creates the exception.
109
+ *
110
+ * @param message The reason.
111
+ * @param options The options, such as the error that caused this one.
112
+ *
113
+ * @example
114
+ * ```ts
115
+ * import { ExceptionOptions } from "@noldova/context.exceptions";
116
+ * import { TerminalWindowException } from "@noldova/terminal/window";
117
+ *
118
+ * const cause = new Error("The runtime closed.");
119
+ * console.log(new TerminalWindowException("The window failed.", new ExceptionOptions(cause)).cause === cause);
120
+ * ```
121
+ */
122
+ public constructor(message: string, options?: ExceptionOptions);
123
+ }
124
+
125
+ /**
126
+ * Thrown when a window that already has a start folder provider is given another.
127
+ *
128
+ * @example
129
+ * ```ts
130
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
131
+ * import { StartFolderProvidedException, TerminalStartFolder } from "@noldova/terminal/window";
132
+ *
133
+ * export function provideHomeFolder(context: IWindowPartContext): void {
134
+ * try {
135
+ * TerminalStartFolder.provide(context, () => null);
136
+ * }
137
+ * catch (error) {
138
+ * console.log(error instanceof StartFolderProvidedException);
139
+ * }
140
+ * }
141
+ * ```
142
+ */
143
+ export declare class StartFolderProvidedException extends TerminalWindowException {
144
+ /**
145
+ * `"StartFolderProvidedException"`.
146
+ */
147
+ public override readonly name: string;
148
+
149
+ /**
150
+ * Creates the exception, whose message says to remove the first provider before providing another.
151
+ *
152
+ * @example
153
+ * ```ts
154
+ * import { StartFolderProvidedException } from "@noldova/terminal/window";
155
+ *
156
+ * console.log(new StartFolderProvidedException().message);
157
+ * ```
158
+ */
159
+ public constructor();
160
+ }
161
+
162
+ /**
163
+ * The folder an app starts new terminals in. The terminal asks for it each time it opens a terminal without a folder of its own, such as the
164
+ * panel's first terminal and `terminal.new` without a `folder` argument.
165
+ *
166
+ * @remarks
167
+ * The home folder stands in when no app provides a folder, the provider gives `null`, or it gives a folder that is blank, relative or longer
168
+ * than the protocol's `Resources.maximumPathLength`, which the providing app's log says. A folder that no longer exists opens the terminal in
169
+ * the home folder too, which the module's log and the terminal's first line say.
170
+ */
171
+ export declare class TerminalStartFolder {
172
+ /**
173
+ * Provides the window's start folder.
174
+ *
175
+ * @param context The providing app part's context, whose log says when its folder is refused.
176
+ * @param folder Gives the folder, an absolute path, or `null` for the home folder; it is called at each open.
177
+ * @returns A function that removes the provider.
178
+ * @throws {@link StartFolderProvidedException} Synchronously, when the window already has a provider.
179
+ *
180
+ * @example
181
+ * ```ts
182
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
183
+ * import { TerminalStartFolder } from "@noldova/terminal/window";
184
+ *
185
+ * export function provideProjectFolder(context: IWindowPartContext, project: { readonly folder: string | null }): () => void {
186
+ * const unregister: () => void = TerminalStartFolder.provide(context, () => project.folder);
187
+ * return unregister;
188
+ * }
189
+ * ```
190
+ */
191
+ public static provide(context: IWindowPartContext, folder: () => string | null): () => void;
192
+
193
+ /**
194
+ * Reads the start folder as the next terminal would open in it.
195
+ *
196
+ * @returns The provided folder, or `null` for the home folder.
197
+ *
198
+ * @example
199
+ * ```ts
200
+ * import { TerminalStartFolder } from "@noldova/terminal/window";
201
+ *
202
+ * console.log(TerminalStartFolder.read());
203
+ * ```
204
+ */
205
+ public static read(): string | null;
206
+ }
207
+
208
+ /**
209
+ * Thrown when a window that already has an owners provider is given another.
210
+ *
211
+ * @example
212
+ * ```ts
213
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
214
+ * import { OwnersProvidedException, TerminalOwners } from "@noldova/terminal/window";
215
+ *
216
+ * export function provideNoOwner(context: IWindowPartContext): void {
217
+ * try {
218
+ * TerminalOwners.provide(context, () => null);
219
+ * }
220
+ * catch (error) {
221
+ * console.log(error instanceof OwnersProvidedException);
222
+ * }
223
+ * }
224
+ * ```
225
+ */
226
+ export declare class OwnersProvidedException extends TerminalWindowException {
227
+ /**
228
+ * `"OwnersProvidedException"`.
229
+ */
230
+ public override readonly name: string;
231
+
232
+ /**
233
+ * Creates the exception, whose message says to remove the first provider before providing another.
234
+ *
235
+ * @example
236
+ * ```ts
237
+ * import { OwnersProvidedException } from "@noldova/terminal/window";
238
+ *
239
+ * console.log(new OwnersProvidedException().message);
240
+ * ```
241
+ */
242
+ public constructor();
243
+ }
244
+
245
+ /**
246
+ * What an app ties a window's terminals to, such as its chats: an owner, a string of 1 to 256 UTF-16 code units the app chooses, which
247
+ * Terminal only compares.
248
+ *
249
+ * @remarks
250
+ * The window shows the terminals without an owner and one owner's at a time. Another owner's terminals have no tab: their shells keep running
251
+ * and the runtime keeps their output, and their tabs open again when their owner shows. The window starts with no owner shown, so after a
252
+ * reload the app shows its current owner again. The panel's terminal never has an owner.
253
+ */
254
+ export declare class TerminalOwners {
255
+ private constructor();
256
+
257
+ /**
258
+ * The longest commands {@link TerminalOwners.runAsync} takes, `16384` UTF-16 code units.
259
+ */
260
+ public static readonly maximumCommandLength: number;
261
+
262
+ /**
263
+ * The most lines {@link TerminalOwners.readRunOutputAsync} gives when not asked for fewer or more, `2000`.
264
+ */
265
+ public static readonly defaultRunLines: number;
266
+
267
+ /**
268
+ * The most lines {@link TerminalOwners.readRunOutputAsync} gives, `5000`.
269
+ */
270
+ public static readonly maximumRunLines: number;
271
+
272
+ /**
273
+ * The color of an output line's text run that stands for the terminal's default foreground or background, `-1`; another color is a palette
274
+ * index from `0` to `255`, or an RGB color.
275
+ */
276
+ public static readonly defaultColor: number;
277
+
278
+ /**
279
+ * The offset of an RGB color in an output line's text run, `16777216` (`0x1000000`): a color `rgbColor + 0xRRGGBB` stands for that RGB
280
+ * color.
281
+ */
282
+ public static readonly rgbColor: number;
283
+
284
+ /**
285
+ * The owner whose terminals the window shows, or `null`.
286
+ */
287
+ public static get shown(): string | null;
288
+
289
+ /**
290
+ * Provides the window's owners.
291
+ *
292
+ * @param context The providing app part's context, which makes the owners' requests and whose log says when its new owner is refused; the
293
+ * tabs open and close through Terminal's own window part, since a part may open and close only its own module's views.
294
+ * @param newOwner Gives the owner that a terminal from Terminal's + and Toggle Terminal's first open takes, or `null` for none; it is called
295
+ * at each open. A blank or over-long owner, or one it throws for, opens a terminal without an owner. The shell menu's rows, Ctrl+Shift+\`
296
+ * and the View menu open a terminal without an owner, whatever it gives.
297
+ * @returns The window's owners.
298
+ * @throws {@link OwnersProvidedException} Synchronously, when the window already has a provider.
299
+ *
300
+ * @example
301
+ * ```ts
302
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
303
+ * import { TerminalOwners } from "@noldova/terminal/window";
304
+ *
305
+ * export function provideChatOwners(context: IWindowPartContext, chat: { readonly id: string }): TerminalOwners {
306
+ * const owners = TerminalOwners.provide(context, () => `example.chat/${chat.id}`);
307
+ * return owners;
308
+ * }
309
+ * ```
310
+ */
311
+ public static provide(context: IWindowPartContext, newOwner: () => string | null): TerminalOwners;
312
+
313
+ /**
314
+ * Reads the new owner as the next terminal from Terminal's own entries would take it.
315
+ *
316
+ * @returns The provided owner, or `null` for none.
317
+ *
318
+ * @example
319
+ * ```ts
320
+ * import { TerminalOwners } from "@noldova/terminal/window";
321
+ *
322
+ * console.log(TerminalOwners.readNewOwner());
323
+ * ```
324
+ */
325
+ public static readNewOwner(): string | null;
326
+
327
+ /**
328
+ * Checks commands as {@link TerminalOwners.runAsync} does, so an app can offer Run only for commands it takes.
329
+ *
330
+ * @param command The commands.
331
+ * @returns `true` when they aren't blank, have at most {@link TerminalOwners.maximumCommandLength} UTF-16 code units, hold no control
332
+ * character but line feeds, carriage returns before line feeds, and tabs, and no format or default-ignorable character outside an emoji,
333
+ * such as a bidirectional mark, a zero-width character or a variation selector, which would make them read differently from what runs.
334
+ * A tab may still keep them from being typed, into a shell without bracketed paste ({@link TerminalRunNotTypedException}).
335
+ *
336
+ * @example
337
+ * ```ts
338
+ * import { TerminalOwners } from "@noldova/terminal/window";
339
+ *
340
+ * console.log(TerminalOwners.canRun("npm install\nnpm test"));
341
+ * ```
342
+ */
343
+ public static canRun(command: string): boolean;
344
+
345
+ /**
346
+ * Shows the owner's terminals in this window, in the order they opened, and hides every other owner's. While Terminal's window part isn't
347
+ * active, or once it stops during the show, it only sets the owner, whose tabs open as the part activates.
348
+ *
349
+ * @param owner The owner, or `null` to hide every owned terminal.
350
+ * @returns A promise that resolves once the tabs have opened and closed; the shows run in the order asked, and one that rejects leaves the
351
+ * window as it was.
352
+ * @throws `ArgumentException` Synchronously, when the owner is blank or too long.
353
+ *
354
+ * @example
355
+ * ```ts
356
+ * import type { TerminalOwners } from "@noldova/terminal/window";
357
+ *
358
+ * export async function showChatAsync(owners: TerminalOwners, chat: { readonly id: string }): Promise<void> {
359
+ * await owners.showAsync(`example.chat/${chat.id}`);
360
+ * }
361
+ * ```
362
+ */
363
+ public showAsync(owner: string | null): Promise<void>;
364
+
365
+ /**
366
+ * Ends every terminal of the owner, in every window, as closing its tab does, and forgets them for the next run; each window closes their
367
+ * tabs.
368
+ *
369
+ * @param owner The owner.
370
+ * @returns A promise that resolves once the runtime has ended them; it rejects with an `ArgumentException` when the owner is blank or too
371
+ * long.
372
+ *
373
+ * @example
374
+ * ```ts
375
+ * import type { TerminalOwners } from "@noldova/terminal/window";
376
+ *
377
+ * export async function closeChatAsync(owners: TerminalOwners, chat: { readonly id: string }): Promise<void> {
378
+ * await owners.closeAsync(`example.chat/${chat.id}`);
379
+ * }
380
+ * ```
381
+ */
382
+ public closeAsync(owner: string): Promise<void>;
383
+
384
+ /**
385
+ * Runs commands the person asked to run, such as a chat's shell code block, in a terminal of the owner, as pasting them there and pressing
386
+ * Enter would.
387
+ *
388
+ * @remarks
389
+ * The runtime types them into the owner's newest terminal that is free: a person's terminal, not an agent's, whose shell is running, has the
390
+ * shell integration, is of one of the kinds, and is at its prompt with nothing typed after it and no keys within the last second. A shell
391
+ * without the integration, such as Command Prompt, can't be told free, so each run there opens a new terminal. With no free terminal, it
392
+ * opens one for the owner in the folder, with the window's default shell when it is of the kinds or none are given, else the first installed
393
+ * shell of the kinds, and types them once the shell is ready; with no shell of the kinds installed, nothing opens or is typed, since a shell
394
+ * of another kind would read them differently. Their line breaks are typed as Enter inside a bracketed paste when the shell asked for one,
395
+ * so several lines run as their paste would, and Enter follows once; blank lines at their start and line breaks at their end are dropped,
396
+ * so the first command stays on the prompt's line. Terminal never logs them.
397
+ * While the window shows the owner, the terminal's tab shows and its pane takes the focus, as a new terminal's does; a terminal of another
398
+ * owner gets its tab when that owner shows, so the app shows the owner first.
399
+ *
400
+ * @param owner The owner: not blank, at most 256 UTF-16 code units.
401
+ * @param command The commands, as {@link TerminalOwners.canRun} checks them.
402
+ * @param folder The absolute folder a new terminal starts in, or `null` for the app's {@link TerminalStartFolder}, else the person's home
403
+ * folder, which also stands in for a folder that no longer exists.
404
+ * @param shellKinds The kinds of shell that may run them, such as Bash and Zsh for a `bash` block; an empty list means any.
405
+ * @returns A promise of the terminal's session id, once the runtime has typed the commands, onto an empty prompt line with nothing typed
406
+ * since it picked the terminal, and the tab has opened; a new terminal's tab opens first, and the commands go in once its pane gave the
407
+ * terminal its size, so they draw at the pane's width.
408
+ * @throws {@link TerminalRunRefusedException} As the promise's rejection, never synchronously, before anything opens or is typed, when
409
+ * Terminal's window part isn't active, or the owner, the commands, the folder or a kind is refused, or for `shellKinds` when no shell of the
410
+ * kinds is installed, with a message that names them, such as "The commands weren't run, and nothing opened: no shell of the kinds they need
411
+ * is installed (Bash or Zsh)."
412
+ * @throws {@link TerminalRunNotTypedException} As the promise's rejection, once the tab has opened, when the runtime picked or opened a
413
+ * terminal but didn't type the commands; the promise rejects with what the runtime rejects with when it fails the run otherwise.
414
+ *
415
+ * @example
416
+ * ```ts
417
+ * import { TerminalOwners, TerminalShellKind } from "@noldova/terminal/window";
418
+ *
419
+ * export async function runBlockAsync(owners: TerminalOwners, chat: { readonly id: string; readonly folder: string | null },
420
+ * block: { readonly text: string }): Promise<void> {
421
+ * const owner = `example.chat/${chat.id}`;
422
+ * await owners.showAsync(owner);
423
+ * if (TerminalOwners.canRun(block.text))
424
+ * await owners.runAsync(owner, block.text, chat.folder, [TerminalShellKind.Bash, TerminalShellKind.Zsh]);
425
+ * }
426
+ * ```
427
+ */
428
+ public runAsync(owner: string, command: string, folder: string | null, shellKinds: readonly TerminalShellKind[]): Promise<string>;
429
+
430
+ /**
431
+ * Runs commands as {@link TerminalOwners.runAsync} does, or into one given terminal, and gives the run, whose output
432
+ * {@link TerminalOwners.readRunOutputAsync} reads; `runAsync` is this with no target, giving the run's session id.
433
+ *
434
+ * @remarks
435
+ * With a target, the commands go only into that terminal, which must be a person's terminal of the owner, of one of the kinds, that the
436
+ * window reaches, such as one an app shows with {@link EmbeddedTerminal} under the commands; no tab opens or shows, since the app shows the
437
+ * terminal itself, and the folder isn't used. For any other target, as for one that ended, closed or restarted, the run fails as `Ended`,
438
+ * alike, so the app runs the commands in a new terminal. While the target's shell is busy, running a command or with text on its prompt line, or
439
+ * always for a shell without the shell integration, which can't be told free, a run whose target says `Refuse` types nothing and fails as
440
+ * `Busy`; one that says `Interrupt` waits up to two seconds for a command to start, sends it Ctrl+C, waits up to two seconds more for the
441
+ * shell to be back at an empty prompt, then types, else fails as `Busy`; a line that doesn't start gets no Ctrl+C. A run that comes while another run into the target is still starting types nothing and fails as `Busy` too.
442
+ *
443
+ * With `shown`, no tab opens or takes the focus for the run's terminal, whether the run picks a free one, opens a new one or is given a
444
+ * target, and none opens later as the owner shows, since the app shows the terminal in its own pane; the terminal stays in the window's list
445
+ * and the agents' tools, and its tab opens only when the person opens it. `shown` gets the terminal's session ID before anything is typed:
446
+ * the app attaches its pane then, and a new terminal waits for that pane's first fit, however long it takes, before the commands are typed
447
+ * at its size; it starts at 80 columns at once when the window closes or detaches the pane first. A window's runs with `shown` start one at a time.
448
+ *
449
+ * @param owner The owner: not blank, at most 256 UTF-16 code units.
450
+ * @param command The commands, as {@link TerminalOwners.canRun} checks them.
451
+ * @param folder The absolute folder a new terminal starts in, or `null`, as {@link TerminalOwners.runAsync} takes it.
452
+ * @param shellKinds The kinds of shell that may run them; an empty list means any.
453
+ * @param target The terminal the commands go into, and what a busy one gets, or `null` for the runtime's choice, as
454
+ * {@link TerminalOwners.runAsync} makes it.
455
+ * @param shown Called once with the terminal's session ID before the commands are typed, for a run without a tab, or `null`, the default,
456
+ * for a run whose terminal's tab opens as {@link TerminalOwners.runAsync} opens it.
457
+ * @returns A promise of the run, once the runtime has typed the commands and, without a target or `shown`, the tab has opened.
458
+ * @throws {@link TerminalRunRefusedException} As the promise's rejection, never synchronously, before anything opens or is typed, as
459
+ * {@link TerminalOwners.runAsync} rejects with it, or for `sessionId` or `whenBusy` when the target's own fields are refused.
460
+ * @throws {@link TerminalRunNotTypedException} As the promise's rejection, when the runtime picked, opened or was given a terminal but didn't
461
+ * type the commands, with
462
+ * the reason `Busy` for a busy target, and `Ended` for a target that isn't a person's terminal of the owner, of one of the kinds, that the
463
+ * window reaches; the promise rejects with what the runtime rejects with when it fails the run otherwise.
464
+ *
465
+ * @example
466
+ * ```ts
467
+ * import { TerminalRunBusy, TerminalRunTarget, type TerminalOwners } from "@noldova/terminal/window";
468
+ *
469
+ * export async function runTestsAsync(owners: TerminalOwners, chat: { readonly id: string }, sessionId: string): Promise<void> {
470
+ * const target = new TerminalRunTarget(sessionId, TerminalRunBusy.Interrupt);
471
+ * const run = await owners.startRunAsync(`example.chat/${chat.id}`, "npm test", null, [], target);
472
+ * console.log(run.runId);
473
+ * }
474
+ * ```
475
+ */
476
+ public startRunAsync(owner: string, command: string, folder: string | null, shellKinds: readonly TerminalShellKind[],
477
+ target: TerminalRunTarget | null, shown?: ((sessionId: string) => void) | null): Promise<TerminalRun>;
478
+
479
+ /**
480
+ * Reads a run's output with its colors, such as to show it or hand it on after the person ran a block.
481
+ *
482
+ * @remarks
483
+ * The output holds the run's lines from the prompt where its commands were typed up to the prompt where the next run into the same terminal
484
+ * typed, or up to the cursor's line for the terminal's latest run, so the commands the person typed in between are in it. It gives the last
485
+ * of them, at most the number asked, each from a line's start, never the rest of a wrapped line, and `cutLines` counts the earlier lines it
486
+ * left out: those over the limit, and those the terminal no longer holds, such as lines past what it keeps of its scrollback or ones the
487
+ * shell erased, as `clear` does. Only a person's terminals' runs are read, and no agent tool reads them.
488
+ *
489
+ * @param run The run, from {@link TerminalOwners.startRunAsync}.
490
+ * @param maximumLines The most lines: a whole number from `1` to {@link TerminalOwners.maximumRunLines};
491
+ * {@link TerminalOwners.defaultRunLines} when left out.
492
+ * @returns A promise of the output.
493
+ * @throws {@link RunLinesRefusedException} As the promise's rejection, never synchronously, when the number of lines isn't a whole number in
494
+ * its range, before anything is asked.
495
+ * @throws {@link TerminalRunNotFoundException} As the promise's rejection, when the run's ids can't name a run, before anything is asked, or
496
+ * when the runtime can't give the run: its terminal never had it or no longer keeps it, as it keeps its latest 100 runs, its shell ended or
497
+ * restarted, or the runtime no longer has its terminal, such as after it started again; the promise rejects with what the runtime rejects
498
+ * with when it fails the read otherwise.
499
+ *
500
+ * @example
501
+ * ```ts
502
+ * import { TerminalRunNotFoundException, type TerminalLine, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
503
+ *
504
+ * export async function logOutputAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
505
+ * try {
506
+ * const output = await owners.readRunOutputAsync(run, 200);
507
+ * console.log(output.lines.map((t: TerminalLine) => t.text).join("\n"), output.cutLines);
508
+ * }
509
+ * catch (error) {
510
+ * console.log(error instanceof TerminalRunNotFoundException);
511
+ * }
512
+ * }
513
+ * ```
514
+ */
515
+ public readRunOutputAsync(run: TerminalRun, maximumLines?: number): Promise<TerminalRunOutput>;
516
+
517
+ /**
518
+ * Hides every owned terminal and removes the provider, so another can be provided; it does nothing once removed.
519
+ *
520
+ * @returns A promise that resolves once the tabs have closed.
521
+ *
522
+ * @example
523
+ * ```ts
524
+ * import type { TerminalOwners } from "@noldova/terminal/window";
525
+ *
526
+ * export async function removeOwnersAsync(owners: TerminalOwners): Promise<void> {
527
+ * await owners.removeAsync();
528
+ * }
529
+ * ```
530
+ */
531
+ public removeAsync(): Promise<void>;
532
+ }
533
+
534
+ /**
535
+ * The base of the exceptions {@link TerminalOwners.runAsync} and {@link TerminalOwners.startRunAsync} throw when they refuse a run, before
536
+ * anything opened or was typed, which a caller catches to handle any refusal; each refusal is its own subclass.
537
+ *
538
+ * @example
539
+ * ```ts
540
+ * import { TerminalRunRefusedException, type TerminalOwners } from "@noldova/terminal/window";
541
+ *
542
+ * export async function runInRelativeFolderAsync(owners: TerminalOwners): Promise<void> {
543
+ * try {
544
+ * await owners.runAsync("example.chat/42", "ls", "work", []);
545
+ * }
546
+ * catch (error) {
547
+ * console.log(error instanceof TerminalRunRefusedException && error.parameter);
548
+ * }
549
+ * }
550
+ * ```
551
+ */
552
+ export declare abstract class TerminalRunRefusedException extends TerminalWindowException {
553
+ /**
554
+ * `"TerminalRunRefusedException"`, which a subclass replaces with its own.
555
+ */
556
+ public override readonly name: string;
557
+
558
+ /**
559
+ * The refused field: `owner`, `command`, `folder`, a kind such as `shellKinds.1`, `sessionId` or `whenBusy` for a target's refused
560
+ * field, `shellKinds` when no shell of the kinds is installed, or `context` while the terminal's window part isn't active. The exception
561
+ * never carries the commands.
562
+ */
563
+ public abstract readonly parameter: string;
564
+
565
+ /**
566
+ * Creates the exception, for a subclass.
567
+ *
568
+ * @param message The message, which says that nothing ran or opened, and why.
569
+ * @param options The options, such as the error that caused this one.
570
+ */
571
+ protected constructor(message: string, options?: ExceptionOptions);
572
+ }
573
+
574
+ /**
575
+ * Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} is called while Terminal's window part isn't active in
576
+ * the window, before anything opened or was typed.
577
+ *
578
+ * @example
579
+ * ```ts
580
+ * import { RunPartInactiveException, type TerminalOwners } from "@noldova/terminal/window";
581
+ *
582
+ * export async function runListAsync(owners: TerminalOwners): Promise<void> {
583
+ * try {
584
+ * await owners.runAsync("example.chat/42", "ls", null, []);
585
+ * }
586
+ * catch (error) {
587
+ * console.log(error instanceof RunPartInactiveException);
588
+ * }
589
+ * }
590
+ * ```
591
+ */
592
+ export declare class RunPartInactiveException extends TerminalRunRefusedException {
593
+ /**
594
+ * `"RunPartInactiveException"`.
595
+ */
596
+ public override readonly name: string;
597
+
598
+ /**
599
+ * `"context"`.
600
+ */
601
+ public override readonly parameter: string;
602
+
603
+ /**
604
+ * Creates the exception, whose message says that nothing ran or opened, since the terminal's window part isn't active in the window.
605
+ *
606
+ * @example
607
+ * ```ts
608
+ * import { RunPartInactiveException } from "@noldova/terminal/window";
609
+ *
610
+ * console.log(new RunPartInactiveException().message);
611
+ * ```
612
+ */
613
+ public constructor();
614
+ }
615
+
616
+ /**
617
+ * Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} refuses one of its arguments, such as a blank owner, a
618
+ * command with a control character or a relative folder, before anything opened or was typed.
619
+ *
620
+ * @example
621
+ * ```ts
622
+ * import { RunArgumentRefusedException, type TerminalOwners } from "@noldova/terminal/window";
623
+ *
624
+ * export async function runInRelativeFolderAsync(owners: TerminalOwners): Promise<void> {
625
+ * try {
626
+ * await owners.runAsync("example.chat/42", "ls", "work", []);
627
+ * }
628
+ * catch (error) {
629
+ * console.log(error instanceof RunArgumentRefusedException && error.parameter);
630
+ * }
631
+ * }
632
+ * ```
633
+ */
634
+ export declare class RunArgumentRefusedException extends TerminalRunRefusedException {
635
+ /**
636
+ * `"RunArgumentRefusedException"`.
637
+ */
638
+ public override readonly name: string;
639
+
640
+ /**
641
+ * The refused field: `owner`, `command`, `folder`, a kind such as `shellKinds.1`, or `sessionId` or `whenBusy` for a target's refused field.
642
+ */
643
+ public override readonly parameter: string;
644
+
645
+ /**
646
+ * Why the field is refused, such as "Expected a string that is not blank."; it never holds the commands.
647
+ */
648
+ public readonly reason: string;
649
+
650
+ /**
651
+ * Creates the exception, whose message says that nothing ran or opened, and gives the reason.
652
+ *
653
+ * @param parameterName The refused field.
654
+ * @param reason Why it is refused.
655
+ *
656
+ * @example
657
+ * ```ts
658
+ * import { RunArgumentRefusedException } from "@noldova/terminal/window";
659
+ *
660
+ * console.log(new RunArgumentRefusedException("owner", "Expected a string that is not blank.").message);
661
+ * ```
662
+ */
663
+ public constructor(parameterName: string, reason: string);
664
+ }
665
+
666
+ /**
667
+ * Thrown when {@link TerminalOwners.runAsync} or {@link TerminalOwners.startRunAsync} finds no installed shell of the run's kinds, so nothing
668
+ * opened and nothing was typed, since a shell of another kind would read the commands differently.
669
+ *
670
+ * @example
671
+ * ```ts
672
+ * import { RunShellKindsMissingException, TerminalShellKind, type TerminalOwners } from "@noldova/terminal/window";
673
+ *
674
+ * export async function runInBashAsync(owners: TerminalOwners): Promise<void> {
675
+ * try {
676
+ * await owners.runAsync("example.chat/42", "ls", null, [TerminalShellKind.Bash, TerminalShellKind.Zsh]);
677
+ * }
678
+ * catch (error) {
679
+ * if (error instanceof RunShellKindsMissingException)
680
+ * console.log(error.message);
681
+ * }
682
+ * }
683
+ * ```
684
+ */
685
+ export declare class RunShellKindsMissingException extends TerminalRunRefusedException {
686
+ /**
687
+ * `"RunShellKindsMissingException"`.
688
+ */
689
+ public override readonly name: string;
690
+
691
+ /**
692
+ * `"shellKinds"`.
693
+ */
694
+ public override readonly parameter: string;
695
+
696
+ /**
697
+ * The kinds of shell the run needs, none of which is installed.
698
+ */
699
+ public readonly shellKinds: readonly TerminalShellKind[];
700
+
701
+ /**
702
+ * Creates the exception, whose message names the kinds, such as "The commands weren't run, and nothing opened: no shell of the kinds they
703
+ * need is installed (Bash or Zsh)."
704
+ *
705
+ * @param shellKinds The kinds of shell the run needs.
706
+ *
707
+ * @example
708
+ * ```ts
709
+ * import { RunShellKindsMissingException, TerminalShellKind } from "@noldova/terminal/window";
710
+ *
711
+ * console.log(new RunShellKindsMissingException([TerminalShellKind.Bash, TerminalShellKind.Zsh]).message);
712
+ * ```
713
+ */
714
+ public constructor(shellKinds: readonly TerminalShellKind[]);
715
+ }
716
+
717
+ /**
718
+ * Thrown by {@link TerminalOwners.readRunOutputAsync} when the number of lines isn't a whole number from 1 to
719
+ * {@link TerminalOwners.maximumRunLines}, before anything is asked.
720
+ *
721
+ * @example
722
+ * ```ts
723
+ * import { RunLinesRefusedException, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
724
+ *
725
+ * export async function readNoLinesAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
726
+ * try {
727
+ * await owners.readRunOutputAsync(run, 0);
728
+ * }
729
+ * catch (error) {
730
+ * console.log(error instanceof RunLinesRefusedException && error.lines);
731
+ * }
732
+ * }
733
+ * ```
734
+ */
735
+ export declare class RunLinesRefusedException extends TerminalWindowException {
736
+ /**
737
+ * `"RunLinesRefusedException"`.
738
+ */
739
+ public override readonly name: string;
740
+
741
+ /**
742
+ * The number of lines asked for.
743
+ */
744
+ public readonly lines: number;
745
+
746
+ /**
747
+ * The most lines a read takes.
748
+ */
749
+ public readonly maximum: number;
750
+
751
+ /**
752
+ * Creates the exception, whose message gives the range and the number asked for.
753
+ *
754
+ * @param lines The number of lines asked for.
755
+ * @param maximum The most lines a read takes.
756
+ *
757
+ * @example
758
+ * ```ts
759
+ * import { RunLinesRefusedException, TerminalOwners } from "@noldova/terminal/window";
760
+ *
761
+ * console.log(new RunLinesRefusedException(0, TerminalOwners.maximumRunLines).message);
762
+ * ```
763
+ */
764
+ public constructor(lines: number, maximum: number);
765
+ }
766
+
767
+ /**
768
+ * Thrown by {@link TerminalOwners.runAsync} and {@link TerminalOwners.startRunAsync} when the runtime picked or opened a terminal, whose tab
769
+ * shows, or was given one, but didn't type the commands into it. An app can log it by its name and reason, and the person may run the
770
+ * commands again.
771
+ *
772
+ * @example
773
+ * ```ts
774
+ * import { TerminalRunNotTypedException, TerminalRunOutcome, type TerminalOwners } from "@noldova/terminal/window";
775
+ *
776
+ * export async function runTestsAsync(owners: TerminalOwners): Promise<void> {
777
+ * try {
778
+ * await owners.runAsync("example.chat/42", "npm test", null, []);
779
+ * }
780
+ * catch (error) {
781
+ * console.log(error instanceof TerminalRunNotTypedException && error.reason === TerminalRunOutcome.Input);
782
+ * }
783
+ * }
784
+ * ```
785
+ */
786
+ export declare class TerminalRunNotTypedException extends TerminalWindowException {
787
+ /**
788
+ * `"TerminalRunNotTypedException"`.
789
+ */
790
+ public override readonly name: string;
791
+
792
+ /**
793
+ * The terminal's session, whose tab shows while the window shows its owner, unless the run had a target.
794
+ */
795
+ public readonly sessionId: string;
796
+
797
+ /**
798
+ * Why nothing was typed: `Input` when the person typed in the terminal after the run picked it, or its prompt line held text, `Tab` when the
799
+ * commands hold a tab and the shell hasn't turned bracketed paste on, so it would take the tab as completion, or `Ended` when the terminal
800
+ * ended, closed or restarted first, or `Busy` when a run's target was busy and stayed so, or another run into it was still starting. Never
801
+ * `Typed`.
802
+ */
803
+ public readonly reason: TerminalRunOutcome;
804
+
805
+ /**
806
+ * Creates the exception, whose message names the terminal and why nothing was typed, and never holds the commands.
807
+ *
808
+ * @param sessionId The terminal's session.
809
+ * @param reason Why nothing was typed.
810
+ *
811
+ * @example
812
+ * ```ts
813
+ * import { TerminalRunNotTypedException, TerminalRunOutcome } from "@noldova/terminal/window";
814
+ *
815
+ * console.log(new TerminalRunNotTypedException("session-1", TerminalRunOutcome.Busy).message);
816
+ * ```
817
+ */
818
+ public constructor(sessionId: string, reason: TerminalRunOutcome);
819
+ }
820
+
821
+ /**
822
+ * A run an app started with {@link TerminalOwners.startRunAsync}: the terminal its commands went into, the run's own id, which reads its
823
+ * output, and its end.
824
+ *
825
+ * @example
826
+ * ```ts
827
+ * import type { TerminalOwners } from "@noldova/terminal/window";
828
+ *
829
+ * export async function runTestsAsync(owners: TerminalOwners): Promise<void> {
830
+ * const run = await owners.startRunAsync("example.chat/42", "npm test", null, [], null);
831
+ * const end = await run.ended;
832
+ * const output = await owners.readRunOutputAsync(run);
833
+ * console.log(run.sessionId, end.endedBy, end.exitCode, output.lines.length);
834
+ * }
835
+ * ```
836
+ */
837
+ export declare class TerminalRun {
838
+ /**
839
+ * The session of the terminal the commands went into.
840
+ */
841
+ public readonly sessionId: string;
842
+
843
+ /**
844
+ * The run's id, which {@link TerminalOwners.readRunOutputAsync} reads the output by.
845
+ */
846
+ public readonly runId: string;
847
+
848
+ /**
849
+ * Resolves once, when the run's commands have ended, and never rejects; a later run into the same terminal doesn't change it.
850
+ *
851
+ * - `"Command"` when the shell marked the end of the run's last command, with that command's exit code, or `null` when the shell gave none,
852
+ * as bash doesn't for a subshell such as `(exit 3)`. A run of several lines ends with its last line's command. A Ctrl+C, from
853
+ * {@link TerminalRunBusy.Interrupt} or from the person, ends a command like any other, with the code the shell gives.
854
+ * - `"NoIntegration"` when the shell has no integration to mark a command's end, such as Command Prompt, fish or WSL: it has already resolved
855
+ * when {@link TerminalOwners.startRunAsync} resolves, so a run in such a shell never looks running. A new terminal's shell that marked
856
+ * nothing within 10 seconds, such as one whose profile takes that long to load, counts as having none: the run is typed then and ends this
857
+ * way, though its commands may still run.
858
+ * - `"TerminalEnded"` when the terminal's shell exited or restarted, the terminal closed, or the runtime started again, before the end.
859
+ *
860
+ * A run's `ended` has resolved before a later run this window starts into the same terminal resolves {@link TerminalOwners.startRunAsync},
861
+ * whichever {@link TerminalRunBusy} it took, since the runtime ends a run still waiting before it types the next one; a run that waits with no
862
+ * end mark, as for a command that goes on over several lines in a shell that takes no bracketed paste, such as macOS's bash 3.2, then ends as
863
+ * `"Command"` with the last code the shell marked for it, or `null`.
864
+ *
865
+ * @example
866
+ * ```ts
867
+ * import type { TerminalOwners, TerminalRunTarget } from "@noldova/terminal/window";
868
+ *
869
+ * export async function logTestsEndAsync(owners: TerminalOwners, chat: { readonly id: string },
870
+ * target: TerminalRunTarget | null): Promise<void> {
871
+ * const run = await owners.startRunAsync(`example.chat/${chat.id}`, "npm test", null, [], target);
872
+ * const end = await run.ended;
873
+ * console.log(end.endedBy === "Command" ? `exited with ${end.exitCode}` : end.endedBy);
874
+ * }
875
+ * ```
876
+ */
877
+ public readonly ended: Promise<TerminalRunEnd>;
878
+
879
+ /**
880
+ * Creates the run, as {@link TerminalOwners.startRunAsync} does; an app keeps the one it is given.
881
+ *
882
+ * @param sessionId The terminal's session.
883
+ * @param runId The run's id.
884
+ * @param ended The run's end, for {@link TerminalRun.ended}; {@link TerminalOwners.startRunAsync} gives it, and a run made without one
885
+ * resolves `"TerminalEnded"` at once.
886
+ *
887
+ * @example
888
+ * ```ts
889
+ * import { TerminalRun, TerminalRunEnd } from "@noldova/terminal/window";
890
+ *
891
+ * console.log(new TerminalRun("session-1", "run-1", Promise.resolve(new TerminalRunEnd("Command", 0))).runId);
892
+ * ```
893
+ */
894
+ public constructor(sessionId: string, runId: string, ended?: Promise<TerminalRunEnd>);
895
+ }
896
+
897
+ /**
898
+ * How a run's commands ended, which {@link TerminalRun.ended} gives.
899
+ *
900
+ * @example
901
+ * ```ts
902
+ * import type { TerminalRunEnd } from "@noldova/terminal/window";
903
+ *
904
+ * function describe(end: TerminalRunEnd): string {
905
+ * return end.endedBy === "Command" ? `exited with ${end.exitCode}` : end.endedBy;
906
+ * }
907
+ * ```
908
+ */
909
+ export declare class TerminalRunEnd {
910
+ /**
911
+ * `"Command"` when the shell marked the end of the run's last command, `"NoIntegration"` when the shell has no integration to mark it, or
912
+ * `"TerminalEnded"` when the terminal's shell exited or restarted, the terminal closed, or the runtime started again first.
913
+ */
914
+ public readonly endedBy: "Command" | "NoIntegration" | "TerminalEnded";
915
+
916
+ /**
917
+ * The last command's exit code, or `null` unless `endedBy` is `"Command"`, and for a command the shell gave no code.
918
+ */
919
+ public readonly exitCode: number | null;
920
+
921
+ /**
922
+ * Creates the end.
923
+ *
924
+ * @param endedBy How the run's commands ended.
925
+ * @param exitCode The last command's exit code, or `null`.
926
+ *
927
+ * @example
928
+ * ```ts
929
+ * import { TerminalRunEnd } from "@noldova/terminal/window";
930
+ *
931
+ * console.log(new TerminalRunEnd("TerminalEnded", null).endedBy);
932
+ * ```
933
+ */
934
+ public constructor(endedBy: "Command" | "NoIntegration" | "TerminalEnded", exitCode: number | null);
935
+ }
936
+
937
+ /**
938
+ * The terminal a run goes into, a person's terminal of the run's owner, such as the one an app shows under the commands with
939
+ * {@link EmbeddedTerminal}, and what the run does while that terminal's shell is busy.
940
+ *
941
+ * @example
942
+ * ```ts
943
+ * import { TerminalRunBusy, TerminalRunTarget, type TerminalOwners } from "@noldova/terminal/window";
944
+ *
945
+ * export async function runTestsInAsync(owners: TerminalOwners, sessionId: string): Promise<void> {
946
+ * const target = new TerminalRunTarget(sessionId, TerminalRunBusy.Interrupt);
947
+ * await owners.startRunAsync("example.chat/42", "npm test", null, [], target);
948
+ * }
949
+ * ```
950
+ */
951
+ export declare class TerminalRunTarget {
952
+ /**
953
+ * The terminal's session.
954
+ */
955
+ public readonly sessionId: string;
956
+
957
+ /**
958
+ * What the run does while the terminal's shell is busy: `Refuse` types nothing, and `Interrupt` sends Ctrl+C to a command that starts within
959
+ * two seconds and types once the shell is back at an empty prompt within two seconds more; either fails the run as `Busy` when it types
960
+ * nothing.
961
+ */
962
+ public readonly whenBusy: TerminalRunBusy;
963
+
964
+ /**
965
+ * Creates the target.
966
+ *
967
+ * @param sessionId The terminal's session, which {@link TerminalOwners.startRunAsync} checks.
968
+ * @param whenBusy What the run does while the shell is busy; `Refuse` when left out.
969
+ *
970
+ * @example
971
+ * ```ts
972
+ * import { TerminalRunBusy, TerminalRunTarget } from "@noldova/terminal/window";
973
+ *
974
+ * console.log(new TerminalRunTarget("session-1", TerminalRunBusy.Interrupt).whenBusy);
975
+ * ```
976
+ */
977
+ public constructor(sessionId: string, whenBusy?: TerminalRunBusy);
978
+ }
979
+
980
+ /**
981
+ * Thrown by {@link TerminalOwners.readRunOutputAsync} when the runtime can't give a run's output: its terminal never had the run or no
982
+ * longer keeps it, its shell ended or restarted, or the runtime no longer has its terminal, such as after it started again.
983
+ *
984
+ * @example
985
+ * ```ts
986
+ * import { TerminalRunNotFoundException, type TerminalOwners, type TerminalRun } from "@noldova/terminal/window";
987
+ *
988
+ * export async function readOutputAsync(owners: TerminalOwners, run: TerminalRun): Promise<void> {
989
+ * try {
990
+ * await owners.readRunOutputAsync(run);
991
+ * }
992
+ * catch (error) {
993
+ * console.log(error instanceof TerminalRunNotFoundException && error.runId);
994
+ * }
995
+ * }
996
+ * ```
997
+ */
998
+ export declare class TerminalRunNotFoundException extends TerminalWindowException {
999
+ /**
1000
+ * `"TerminalRunNotFoundException"`.
1001
+ */
1002
+ public override readonly name: string;
1003
+
1004
+ /**
1005
+ * The session of the run's terminal.
1006
+ */
1007
+ public readonly sessionId: string;
1008
+
1009
+ /**
1010
+ * The run's id.
1011
+ */
1012
+ public readonly runId: string;
1013
+
1014
+ /**
1015
+ * Creates the exception, whose message names the terminal and the run.
1016
+ *
1017
+ * @param sessionId The session of the run's terminal.
1018
+ * @param runId The run's id.
1019
+ *
1020
+ * @example
1021
+ * ```ts
1022
+ * import { TerminalRunNotFoundException } from "@noldova/terminal/window";
1023
+ *
1024
+ * console.log(new TerminalRunNotFoundException("session-1", "run-1").message);
1025
+ * ```
1026
+ */
1027
+ public constructor(sessionId: string, runId: string);
1028
+ }
1029
+
1030
+ /**
1031
+ * What an app asks of a terminal it launches with {@link TerminalLauncher.openAsync}, which checks it.
1032
+ *
1033
+ * @example
1034
+ * ```ts
1035
+ * import { TerminalLaunch } from "@noldova/terminal/window";
1036
+ *
1037
+ * const launch = new TerminalLaunch("/work/project", { AGENT_HOME: "/work/agent" }, "Run `agent login` to sign in.", "Sign in");
1038
+ * ```
1039
+ */
1040
+ export declare class TerminalLaunch {
1041
+ /**
1042
+ * The folder the shell starts in, an absolute path, or `null` for the app's {@link TerminalStartFolder}, else the home folder.
1043
+ */
1044
+ public readonly folder: string | null;
1045
+
1046
+ /**
1047
+ * The variables laid over the shell's environment, by name.
1048
+ */
1049
+ public readonly environment: Readonly<Record<string, string>>;
1050
+
1051
+ /**
1052
+ * The lines shown above the shell's first output, or `null` for none.
1053
+ */
1054
+ public readonly notice: string | null;
1055
+
1056
+ /**
1057
+ * The tab's title, or `null` for the shell's name.
1058
+ */
1059
+ public readonly title: string | null;
1060
+
1061
+ /**
1062
+ * The command typed into the shell and entered once the shell is ready, as if the person typed it, or `null` for none.
1063
+ */
1064
+ public readonly command: string | null;
1065
+
1066
+ /**
1067
+ * Whether the terminal gets a tab in the Terminals panel; `false` for one the app shows only in its own page, with {@link EmbeddedTerminal.open}.
1068
+ */
1069
+ public readonly opensTab: boolean;
1070
+
1071
+ /**
1072
+ * The rows the terminal's tab shows at least while the terminal is open, or `null` for none: as the tab first shows in the bottom dock, the
1073
+ * dock grows, as far as the window allows, until the terminal ends or closes, when the dock goes back to its size unless the person resized it
1074
+ * meanwhile. A tab in a side dock, whose growth would widen it, or among the documents grows nothing.
1075
+ */
1076
+ public readonly minimumRows: number | null;
1077
+
1078
+ /**
1079
+ * The kinds of shell the terminal may run, or none for any: with kinds, it runs the Default shell setting's shell when that is of them, else the
1080
+ * runtime's default when it is, else the first installed shell of them, as {@link TerminalOwners.runAsync} picks one. An app whose program the
1081
+ * person installed on the host asks for the host's own shells, such as PowerShell and Command Prompt on Windows, so a WSL distribution set as
1082
+ * the Default shell doesn't run its sign-in.
1083
+ */
1084
+ public readonly shellKinds: readonly TerminalShellKind[];
1085
+
1086
+ /**
1087
+ * Creates the launch, which {@link TerminalLauncher.openAsync} checks rather than the constructor.
1088
+ *
1089
+ * @param folder The starting folder: an absolute path of at most 4,096 UTF-16 code units, or `null` for the start folder.
1090
+ * @param environment The variables: at most 256, each with a portable name (a letter or `_`, then letters, digits or `_`) of at most 256
1091
+ * UTF-16 code units, none of `TERM`, `COLORTERM`, `ZDOTDIR` or a name starting with `NOLDOVA_TERMINAL_`, in any case, no two whose names
1092
+ * differ only in case, each value at most 32,767 UTF-16 code units without a null character, and at most 131,072 UTF-16 code units of names
1093
+ * and values in all; none when left out.
1094
+ * @param notice The notice: `null`, or not blank and at most 4,096 UTF-16 code units, whose line breaks start new lines; `null` when left out.
1095
+ * @param title The tab's title: `null`, or not blank and at most 200 UTF-16 code units; `null` when left out.
1096
+ * @param command The command: `null`, or one line, not blank, of at most 16,384 UTF-16 code units, with no line break, tab or other control
1097
+ * character, since the runtime enters it; `null` when left out. The runtime types it once the shell shows its first prompt, or, for a shell
1098
+ * without Terminal's integration, once its first output has settled for half a second, waiting at most 10 seconds either way; the shell
1099
+ * runs it as the person's own command, so the app passes only commands it means the person to run.
1100
+ * @param opensTab Whether the terminal gets a tab: `false` for a terminal the app shows only in its own page, by passing the launched
1101
+ * terminal's session to {@link EmbeddedTerminal.open}, so the person doesn't see it twice; it runs and ends as a tabbed one does, and the app
1102
+ * ends it with {@link LaunchedTerminal.closeAsync}. `true` when left out.
1103
+ * @param minimumRows The rows the tab shows at least: `null`, or a whole number from 1 to 100, for a program that draws more rows than a short
1104
+ * dock shows, such as a sign-in's list; `null` when left out, and `null` for a launch without a tab.
1105
+ * @param shellKinds The kinds of shell the terminal may run, each one of {@link TerminalShellKind}'s, or none for any; none when left out. With
1106
+ * none of them installed, {@link TerminalLauncher.openAsync} opens nothing and rejects with Noldova Desktop's request error, as for any
1107
+ * failure of the launch in the runtime, not with a {@link TerminalLaunchRefusedException}, since the runtime finds that out.
1108
+ *
1109
+ * @example
1110
+ * ```ts
1111
+ * import { TerminalLaunch } from "@noldova/terminal/window";
1112
+ *
1113
+ * console.log(new TerminalLaunch(null).environment);
1114
+ * ```
1115
+ */
1116
+ public constructor(folder: string | null, environment?: Readonly<Record<string, string>>, notice?: string | null, title?: string | null,
1117
+ command?: string | null, opensTab?: boolean, minimumRows?: number | null, shellKinds?: readonly TerminalShellKind[]);
1118
+ }
1119
+
1120
+ /**
1121
+ * How a launched terminal's shell ended.
1122
+ *
1123
+ * @example
1124
+ * ```ts
1125
+ * import type { TerminalEnd } from "@noldova/terminal/window";
1126
+ *
1127
+ * function describe(end: TerminalEnd): string {
1128
+ * return end.endedBy === "Exit" ? `exited with ${end.exitCode}` : end.endedBy;
1129
+ * }
1130
+ * ```
1131
+ */
1132
+ export declare class TerminalEnd {
1133
+ /**
1134
+ * `"Exit"` when the shell exited by itself, `"Close"` when its terminal closed, or when a Restart ended its shell but couldn't start a new
1135
+ * one, or `"Detach"` when the window stopped hearing of it, since the runtime started again and opens no launched terminal again.
1136
+ */
1137
+ public readonly endedBy: "Exit" | "Close" | "Detach";
1138
+
1139
+ /**
1140
+ * The shell's exit code, or `null` when it has none, as for a `"Detach"`.
1141
+ */
1142
+ public readonly exitCode: number | null;
1143
+
1144
+ /**
1145
+ * Creates the end.
1146
+ *
1147
+ * @param endedBy How the shell ended.
1148
+ * @param exitCode The exit code, or `null`.
1149
+ *
1150
+ * @example
1151
+ * ```ts
1152
+ * import { TerminalEnd } from "@noldova/terminal/window";
1153
+ *
1154
+ * console.log(new TerminalEnd("Exit", 0).exitCode);
1155
+ * ```
1156
+ */
1157
+ public constructor(endedBy: "Exit" | "Close" | "Detach", exitCode: number | null);
1158
+ }
1159
+
1160
+ /**
1161
+ * A terminal {@link TerminalLauncher.openAsync} opened.
1162
+ *
1163
+ * @example
1164
+ * ```ts
1165
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1166
+ * import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1167
+ *
1168
+ * export async function launchShellAsync(context: IWindowPartContext): Promise<void> {
1169
+ * const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null));
1170
+ * console.log(launched.sessionId, (await launched.ended).endedBy);
1171
+ * }
1172
+ * ```
1173
+ */
1174
+ export declare class LaunchedTerminal {
1175
+ /**
1176
+ * The terminal's session.
1177
+ */
1178
+ public readonly sessionId: string;
1179
+
1180
+ /**
1181
+ * Resolves once, at the terminal's end, and never rejects. A Restart of a running shell doesn't end it, since the tab stays and the new
1182
+ * shell takes the same variables; a Restart after the shell exited starts it again, but `ended` has already resolved.
1183
+ */
1184
+ public readonly ended: Promise<TerminalEnd>;
1185
+
1186
+ /**
1187
+ * Resolves once, when the launch's own command ({@link TerminalLaunch.command}) ends while the terminal stays open, with that command's exit
1188
+ * code, and never rejects; commands the person types after it don't count. It resolves `null` when the launch has no command, when the
1189
+ * terminal ends first, when the shell has no integration (Command Prompt, fish, WSL) or never took the command, when the person typed into the
1190
+ * terminal before the command went in, when a Restart comes first, or
1191
+ * when the shell gave no code or marked no end for it, as bash doesn't for a subshell such as `(exit 3)`.
1192
+ *
1193
+ * @example
1194
+ * ```ts
1195
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1196
+ * import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1197
+ *
1198
+ * export async function signInAsync(context: IWindowPartContext): Promise<void> {
1199
+ * const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, "Sign in", "tool auth login"));
1200
+ * if (await launched.commandEnded === 0)
1201
+ * await launched.closeAsync();
1202
+ * }
1203
+ * ```
1204
+ */
1205
+ public readonly commandEnded: Promise<number | null>;
1206
+
1207
+ /**
1208
+ * Creates the launched terminal.
1209
+ *
1210
+ * @param sessionId The terminal's session.
1211
+ * @param ended The terminal's end.
1212
+ * @param closeTabAsync Ends the terminal as closing its tab does, for {@link LaunchedTerminal.closeAsync}; {@link TerminalLauncher.openAsync} gives
1213
+ * it, and a terminal made without one closes nothing.
1214
+ * @param commandEnded The launch's command's exit code, for {@link LaunchedTerminal.commandEnded}; {@link TerminalLauncher.openAsync} gives it,
1215
+ * and a terminal made without one resolves `null` at its end.
1216
+ *
1217
+ * @example
1218
+ * ```ts
1219
+ * import { LaunchedTerminal, TerminalEnd } from "@noldova/terminal/window";
1220
+ *
1221
+ * console.log(new LaunchedTerminal("session-1", Promise.resolve(new TerminalEnd("Exit", 0))).sessionId);
1222
+ * ```
1223
+ */
1224
+ public constructor(sessionId: string, ended: Promise<TerminalEnd>, closeTabAsync?: () => Promise<void>, commandEnded?: Promise<number | null>);
1225
+
1226
+ /**
1227
+ * Ends the terminal as closing its tab does: its tab, when it has one, closes and its shell ends, so {@link LaunchedTerminal.ended} resolves
1228
+ * `"Close"`, as when the app stops what the terminal was for. A terminal launched without a tab ends through the runtime alone.
1229
+ *
1230
+ * @returns A promise that resolves once any tab has closed and the runtime has ended the terminal; for a terminal that already ended, at once,
1231
+ * doing nothing; a close asked while one is under way is that close. A terminal the runtime no longer has, as when the person closed its
1232
+ * tab meanwhile, counts as closed. It rejects with what the runtime rejects with when it fails the close of a terminal it still has.
1233
+ *
1234
+ * @example
1235
+ * ```ts
1236
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1237
+ * import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1238
+ *
1239
+ * export async function closeSignInAsync(context: IWindowPartContext): Promise<void> {
1240
+ * const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, "Sign in", "agent login"));
1241
+ * await launched.closeAsync();
1242
+ * console.log((await launched.ended).endedBy);
1243
+ * }
1244
+ * ```
1245
+ */
1246
+ public closeAsync(): Promise<void>;
1247
+ }
1248
+
1249
+ /**
1250
+ * The base of the exceptions {@link TerminalLauncher.openAsync} throws when it refuses a launch, before anything opens, which a caller
1251
+ * catches to handle any refusal; each refusal is its own subclass.
1252
+ *
1253
+ * @example
1254
+ * ```ts
1255
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1256
+ * import { TerminalLaunch, TerminalLauncher, TerminalLaunchRefusedException } from "@noldova/terminal/window";
1257
+ *
1258
+ * export async function launchWithTermAsync(context: IWindowPartContext): Promise<void> {
1259
+ * try {
1260
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch(null, { TERM: "dumb" }));
1261
+ * }
1262
+ * catch (error) {
1263
+ * console.log(error instanceof TerminalLaunchRefusedException && error.parameter);
1264
+ * }
1265
+ * }
1266
+ * ```
1267
+ */
1268
+ export declare abstract class TerminalLaunchRefusedException extends TerminalWindowException {
1269
+ /**
1270
+ * `"TerminalLaunchRefusedException"`, which a subclass replaces with its own.
1271
+ */
1272
+ public override readonly name: string;
1273
+
1274
+ /**
1275
+ * The refused field: `folder`, `environment`, a variable such as `environment.TERM`, `notice`, `title`, `command`, `minimumRows`, a kind
1276
+ * such as `shellKinds.0`, or `context` while the terminal's window part isn't active. The exception never carries a variable's value.
1277
+ */
1278
+ public abstract readonly parameter: string;
1279
+
1280
+ /**
1281
+ * Creates the exception, for a subclass.
1282
+ *
1283
+ * @param message The message, which says that nothing opened, and why.
1284
+ * @param options The options, such as the error that caused this one.
1285
+ */
1286
+ protected constructor(message: string, options?: ExceptionOptions);
1287
+ }
1288
+
1289
+ /**
1290
+ * Thrown by {@link TerminalLauncher.openAsync} while Terminal's window part isn't active in the window, before anything opens.
1291
+ *
1292
+ * @example
1293
+ * ```ts
1294
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1295
+ * import { LaunchPartInactiveException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1296
+ *
1297
+ * export async function launchInWorkAsync(context: IWindowPartContext): Promise<void> {
1298
+ * try {
1299
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch("/work"));
1300
+ * }
1301
+ * catch (error) {
1302
+ * console.log(error instanceof LaunchPartInactiveException);
1303
+ * }
1304
+ * }
1305
+ * ```
1306
+ */
1307
+ export declare class LaunchPartInactiveException extends TerminalLaunchRefusedException {
1308
+ /**
1309
+ * `"LaunchPartInactiveException"`.
1310
+ */
1311
+ public override readonly name: string;
1312
+
1313
+ /**
1314
+ * `"context"`.
1315
+ */
1316
+ public override readonly parameter: string;
1317
+
1318
+ /**
1319
+ * Creates the exception, whose message says that nothing opened, since the terminal's window part isn't active in the window.
1320
+ *
1321
+ * @example
1322
+ * ```ts
1323
+ * import { LaunchPartInactiveException } from "@noldova/terminal/window";
1324
+ *
1325
+ * console.log(new LaunchPartInactiveException().message);
1326
+ * ```
1327
+ */
1328
+ public constructor();
1329
+ }
1330
+
1331
+ /**
1332
+ * Thrown by {@link TerminalLauncher.openAsync} when the launch's folder doesn't exist, which it never replaces with another, before anything
1333
+ * opens.
1334
+ *
1335
+ * @example
1336
+ * ```ts
1337
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1338
+ * import { LaunchFolderMissingException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1339
+ *
1340
+ * export async function launchInGoneFolderAsync(context: IWindowPartContext): Promise<void> {
1341
+ * try {
1342
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch("/work/gone"));
1343
+ * }
1344
+ * catch (error) {
1345
+ * console.log(error instanceof LaunchFolderMissingException && error.folder);
1346
+ * }
1347
+ * }
1348
+ * ```
1349
+ */
1350
+ export declare class LaunchFolderMissingException extends TerminalLaunchRefusedException {
1351
+ /**
1352
+ * `"LaunchFolderMissingException"`.
1353
+ */
1354
+ public override readonly name: string;
1355
+
1356
+ /**
1357
+ * `"folder"`.
1358
+ */
1359
+ public override readonly parameter: string;
1360
+
1361
+ /**
1362
+ * The folder that doesn't exist.
1363
+ */
1364
+ public readonly folder: string;
1365
+
1366
+ /**
1367
+ * Creates the exception, whose message says that nothing opened and names the folder.
1368
+ *
1369
+ * @param folder The folder that doesn't exist.
1370
+ *
1371
+ * @example
1372
+ * ```ts
1373
+ * import { LaunchFolderMissingException } from "@noldova/terminal/window";
1374
+ *
1375
+ * console.log(new LaunchFolderMissingException("/work/gone").message);
1376
+ * ```
1377
+ */
1378
+ public constructor(folder: string);
1379
+ }
1380
+
1381
+ /**
1382
+ * Thrown by {@link TerminalLauncher.openAsync} when the launch's title is blank or longer than its limit, before anything opens.
1383
+ *
1384
+ * @example
1385
+ * ```ts
1386
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1387
+ * import { LaunchTitleRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1388
+ *
1389
+ * export async function launchWithBlankTitleAsync(context: IWindowPartContext): Promise<void> {
1390
+ * try {
1391
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, " "));
1392
+ * }
1393
+ * catch (error) {
1394
+ * console.log(error instanceof LaunchTitleRefusedException && error.maximumLength);
1395
+ * }
1396
+ * }
1397
+ * ```
1398
+ */
1399
+ export declare class LaunchTitleRefusedException extends TerminalLaunchRefusedException {
1400
+ /**
1401
+ * `"LaunchTitleRefusedException"`.
1402
+ */
1403
+ public override readonly name: string;
1404
+
1405
+ /**
1406
+ * `"title"`.
1407
+ */
1408
+ public override readonly parameter: string;
1409
+
1410
+ /**
1411
+ * The most characters a title has, `200`.
1412
+ */
1413
+ public readonly maximumLength: number;
1414
+
1415
+ /**
1416
+ * Creates the exception, whose message says that nothing opened and gives the title's rule.
1417
+ *
1418
+ * @param maximumLength The most characters a title has.
1419
+ *
1420
+ * @example
1421
+ * ```ts
1422
+ * import { LaunchTitleRefusedException } from "@noldova/terminal/window";
1423
+ *
1424
+ * console.log(new LaunchTitleRefusedException(200).message);
1425
+ * ```
1426
+ */
1427
+ public constructor(maximumLength: number);
1428
+ }
1429
+
1430
+ /**
1431
+ * Thrown by {@link TerminalLauncher.openAsync} when the launch's minimum rows aren't a whole number from 1 to their limit, before anything
1432
+ * opens.
1433
+ *
1434
+ * @example
1435
+ * ```ts
1436
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1437
+ * import { LaunchRowsRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1438
+ *
1439
+ * export async function launchWithNoRowsAsync(context: IWindowPartContext): Promise<void> {
1440
+ * try {
1441
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, null, null, true, 0));
1442
+ * }
1443
+ * catch (error) {
1444
+ * console.log(error instanceof LaunchRowsRefusedException && error.maximum);
1445
+ * }
1446
+ * }
1447
+ * ```
1448
+ */
1449
+ export declare class LaunchRowsRefusedException extends TerminalLaunchRefusedException {
1450
+ /**
1451
+ * `"LaunchRowsRefusedException"`.
1452
+ */
1453
+ public override readonly name: string;
1454
+
1455
+ /**
1456
+ * `"minimumRows"`.
1457
+ */
1458
+ public override readonly parameter: string;
1459
+
1460
+ /**
1461
+ * The most minimum rows a launch asks for, `100`.
1462
+ */
1463
+ public readonly maximum: number;
1464
+
1465
+ /**
1466
+ * Creates the exception, whose message says that nothing opened and gives the rows' range.
1467
+ *
1468
+ * @param maximum The most minimum rows a launch asks for.
1469
+ *
1470
+ * @example
1471
+ * ```ts
1472
+ * import { LaunchRowsRefusedException } from "@noldova/terminal/window";
1473
+ *
1474
+ * console.log(new LaunchRowsRefusedException(100).message);
1475
+ * ```
1476
+ */
1477
+ public constructor(maximum: number);
1478
+ }
1479
+
1480
+ /**
1481
+ * Thrown by {@link TerminalLauncher.openAsync} when a launch without a tab asks for minimum rows, which only its tab takes; an embedded
1482
+ * terminal takes its rows from {@link EmbeddedTerminal.open}.
1483
+ *
1484
+ * @example
1485
+ * ```ts
1486
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1487
+ * import { LaunchRowsWithoutTabException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1488
+ *
1489
+ * export async function launchRowsWithoutTabAsync(context: IWindowPartContext): Promise<void> {
1490
+ * try {
1491
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch(null, {}, null, null, null, false, 10));
1492
+ * }
1493
+ * catch (error) {
1494
+ * console.log(error instanceof LaunchRowsWithoutTabException);
1495
+ * }
1496
+ * }
1497
+ * ```
1498
+ */
1499
+ export declare class LaunchRowsWithoutTabException extends TerminalLaunchRefusedException {
1500
+ /**
1501
+ * `"LaunchRowsWithoutTabException"`.
1502
+ */
1503
+ public override readonly name: string;
1504
+
1505
+ /**
1506
+ * `"minimumRows"`.
1507
+ */
1508
+ public override readonly parameter: string;
1509
+
1510
+ /**
1511
+ * Creates the exception, whose message says that nothing opened, since minimum rows need the launch's tab.
1512
+ *
1513
+ * @example
1514
+ * ```ts
1515
+ * import { LaunchRowsWithoutTabException } from "@noldova/terminal/window";
1516
+ *
1517
+ * console.log(new LaunchRowsWithoutTabException().message);
1518
+ * ```
1519
+ */
1520
+ public constructor();
1521
+ }
1522
+
1523
+ /**
1524
+ * Thrown by {@link TerminalLauncher.openAsync} when it refuses one of the launch's fields under the rules of {@link TerminalLaunch}'s
1525
+ * constructor, such as a relative folder, a variable's name or the command, before anything opens.
1526
+ *
1527
+ * @example
1528
+ * ```ts
1529
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1530
+ * import { LaunchArgumentRefusedException, TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1531
+ *
1532
+ * export async function launchInRelativeFolderAsync(context: IWindowPartContext): Promise<void> {
1533
+ * try {
1534
+ * await TerminalLauncher.openAsync(context, new TerminalLaunch("work"));
1535
+ * }
1536
+ * catch (error) {
1537
+ * console.log(error instanceof LaunchArgumentRefusedException && error.parameter);
1538
+ * }
1539
+ * }
1540
+ * ```
1541
+ */
1542
+ export declare class LaunchArgumentRefusedException extends TerminalLaunchRefusedException {
1543
+ /**
1544
+ * `"LaunchArgumentRefusedException"`.
1545
+ */
1546
+ public override readonly name: string;
1547
+
1548
+ /**
1549
+ * The refused field: `folder`, `environment`, a variable such as `environment.TERM`, `notice`, `command`, or a kind such as `shellKinds.0`.
1550
+ */
1551
+ public override readonly parameter: string;
1552
+
1553
+ /**
1554
+ * Why the field is refused, such as "Expected an absolute path."; it never holds a variable's value.
1555
+ */
1556
+ public readonly reason: string;
1557
+
1558
+ /**
1559
+ * Creates the exception, whose message says that nothing opened, and gives the reason.
1560
+ *
1561
+ * @param parameterName The refused field.
1562
+ * @param reason Why it is refused.
1563
+ *
1564
+ * @example
1565
+ * ```ts
1566
+ * import { LaunchArgumentRefusedException } from "@noldova/terminal/window";
1567
+ *
1568
+ * console.log(new LaunchArgumentRefusedException("folder", "Expected an absolute path.").message);
1569
+ * ```
1570
+ */
1571
+ public constructor(parameterName: string, reason: string);
1572
+ }
1573
+
1574
+ /**
1575
+ * Opens terminals for an app: a terminal with the app's variables laid over the shell's environment and its notice shown above the shell's
1576
+ * first output, in a tab like the person's own or, when the launch asks for no tab, only in the app's own page, that tells the app when its
1577
+ * shell ends.
1578
+ *
1579
+ * @remarks
1580
+ * Nothing runs without the person: the notice says what to run, and nothing is typed into the shell. A launched terminal has no owner, isn't
1581
+ * the panel's, and isn't kept for the next run. The variables lie over the environment the shell starts from, under the shell integration's
1582
+ * own; on Windows a variable replaces the one whose name matches in any case. Their values are never logged, saved or restored: the runtime
1583
+ * holds them in memory only while the terminal is open, so that a Restart from its tab starts the shell with them again. The title is the
1584
+ * tab's, and isn't stored either, so after a reload the tab shows the shell's name. A terminal launched without a tab has none in any window,
1585
+ * even after a reload, and ends when the window that launched it closes or reloads, or when the app's connection closes; the app closes it with
1586
+ * {@link LaunchedTerminal.closeAsync} once it no longer shows it.
1587
+ */
1588
+ export declare class TerminalLauncher {
1589
+ /**
1590
+ * Launches a terminal and opens its tab, unless the launch asks for none.
1591
+ *
1592
+ * @param context The calling app part's context, which makes the request; the app's module depends on the terminal module.
1593
+ * @param request The launch.
1594
+ * @returns A promise of the launched terminal, once its tab has opened, or with no tab when the launch asks for none or Terminal's window
1595
+ * part stopped while the runtime launched it.
1596
+ * @throws {@link TerminalLaunchRefusedException} Before anything opens, when the launch breaks a rule of {@link TerminalLaunch}'s
1597
+ * constructor, its folder no longer exists, which it never replaces with another, or the terminal's window part isn't active; the promise
1598
+ * rejects with what the runtime rejects with when it fails the launch.
1599
+ *
1600
+ * @example
1601
+ * ```ts
1602
+ * import type { IWindowPartContext } from "@noldova/desktop.window";
1603
+ * import { TerminalLaunch, TerminalLauncher } from "@noldova/terminal/window";
1604
+ *
1605
+ * export async function launchSignInAsync(context: IWindowPartContext): Promise<void> {
1606
+ * const launched = await TerminalLauncher.openAsync(context, new TerminalLaunch("/work/project", { AGENT_HOME: "/work/agent" },
1607
+ * "Run `agent login` to sign in.", "Sign in"));
1608
+ * const end = await launched.ended;
1609
+ * console.log(end.endedBy, end.exitCode);
1610
+ * }
1611
+ * ```
1612
+ */
1613
+ public static openAsync(context: IWindowPartContext, request: TerminalLaunch): Promise<LaunchedTerminal>;
1614
+ }
1615
+
1616
+ /**
1617
+ * Thrown by {@link EmbeddedTerminal.open} and {@link EmbeddedTerminal.setMaximumRows} for rows that aren't a whole number from 1 to 1,000.
1618
+ *
1619
+ * @example
1620
+ * ```ts
1621
+ * import type { EnvironmentInjector } from "@angular/core";
1622
+ * import { EmbeddedRowsRefusedException, EmbeddedTerminal } from "@noldova/terminal/window";
1623
+ *
1624
+ * export function openWithNoRows(sessionId: string, environmentInjector: EnvironmentInjector): void {
1625
+ * try {
1626
+ * EmbeddedTerminal.open(sessionId, environmentInjector, 0);
1627
+ * }
1628
+ * catch (error) {
1629
+ * console.log(error instanceof EmbeddedRowsRefusedException && error.rows);
1630
+ * }
1631
+ * }
1632
+ * ```
1633
+ */
1634
+ export declare class EmbeddedRowsRefusedException extends TerminalWindowException {
1635
+ /**
1636
+ * `"EmbeddedRowsRefusedException"`.
1637
+ */
1638
+ public override readonly name: string;
1639
+
1640
+ /**
1641
+ * The rows asked for.
1642
+ */
1643
+ public readonly rows: number;
1644
+
1645
+ /**
1646
+ * The fewest rows an embedded terminal takes, `1`.
1647
+ */
1648
+ public readonly minimum: number;
1649
+
1650
+ /**
1651
+ * The most rows an embedded terminal takes, `1000`.
1652
+ */
1653
+ public readonly maximum: number;
1654
+
1655
+ /**
1656
+ * Creates the exception, whose message gives the range and the rows asked for.
1657
+ *
1658
+ * @param rows The rows asked for.
1659
+ * @param minimum The fewest rows an embedded terminal takes.
1660
+ * @param maximum The most rows an embedded terminal takes.
1661
+ *
1662
+ * @example
1663
+ * ```ts
1664
+ * import { EmbeddedRowsRefusedException } from "@noldova/terminal/window";
1665
+ *
1666
+ * console.log(new EmbeddedRowsRefusedException(0, 1, 1000).message);
1667
+ * ```
1668
+ */
1669
+ public constructor(rows: number, minimum: number, maximum: number);
1670
+ }
1671
+
1672
+ /**
1673
+ * Thrown by {@link EmbeddedTerminal.open} while Terminal's window part isn't active in the window.
1674
+ *
1675
+ * @example
1676
+ * ```ts
1677
+ * import type { EnvironmentInjector } from "@angular/core";
1678
+ * import { EmbeddedTerminal, TerminalNotActiveException } from "@noldova/terminal/window";
1679
+ *
1680
+ * export function openEmbedded(sessionId: string, environmentInjector: EnvironmentInjector): void {
1681
+ * try {
1682
+ * EmbeddedTerminal.open(sessionId, environmentInjector, 15);
1683
+ * }
1684
+ * catch (error) {
1685
+ * console.log(error instanceof TerminalNotActiveException);
1686
+ * }
1687
+ * }
1688
+ * ```
1689
+ */
1690
+ export declare class TerminalNotActiveException extends TerminalWindowException {
1691
+ /**
1692
+ * `"TerminalNotActiveException"`.
1693
+ */
1694
+ public override readonly name: string;
1695
+
1696
+ /**
1697
+ * Creates the exception, whose message says that Terminal isn't active in the window.
1698
+ *
1699
+ * @example
1700
+ * ```ts
1701
+ * import { TerminalNotActiveException } from "@noldova/terminal/window";
1702
+ *
1703
+ * console.log(new TerminalNotActiveException().message);
1704
+ * ```
1705
+ */
1706
+ public constructor();
1707
+ }
1708
+
1709
+ /**
1710
+ * A live terminal session an app shows in its own page, such as under the code block whose commands ran in it: Terminal's own pane, with its
1711
+ * keys, links, look and snapshot, in an element the app places and may move between hosts without the session reopening.
1712
+ *
1713
+ * @remarks
1714
+ * Its shell gets the element's width in columns and the rows the app asks for, while the element is only as tall as the rows drawn so far,
1715
+ * from the screen's top to the cursor's row, up to those rows; past them its terminal scrolls. A shell has one size, so within a window the
1716
+ * session's shown pane the person focused last sizes it, else the shown pane opened last, the element or a terminal tab or panel of the
1717
+ * session, so the element opening leaves the size with a pane the person has focused until {@link EmbeddedTerminal.focus}; the others draw at that size,
1718
+ * clipped or with blank space, and the element shows the last rows drawn when more are drawn than it shows. It never takes the focus as it
1719
+ * opens. Disposing of it detaches it from the session, which stays open.
1720
+ */
1721
+ export declare class EmbeddedTerminal {
1722
+ /**
1723
+ * The element the app places in its page.
1724
+ */
1725
+ public readonly element: HTMLElement;
1726
+
1727
+ /**
1728
+ * The rows the element shows, from 1 up to the rows the app asked for, all of them while a full-screen program has the alternate screen.
1729
+ */
1730
+ public readonly rows: Signal<number>;
1731
+
1732
+ /**
1733
+ * Whether a full-screen program, such as an editor or a pager, has the alternate screen.
1734
+ */
1735
+ public readonly isFullScreen: Signal<boolean>;
1736
+
1737
+ /**
1738
+ * Whether the session's shell ended; the element then keeps its last screen and takes no typing.
1739
+ */
1740
+ public readonly hasEnded: Signal<boolean>;
1741
+
1742
+ /**
1743
+ * A row's height in CSS pixels, 0 until the pane has shown; it follows the pane as it draws or resizes, such as when the font size changes.
1744
+ * The element is taller than its rows by its inset, so an app counts the rows its page has room for with this rather than the element's
1745
+ * height.
1746
+ *
1747
+ * @example
1748
+ * ```ts
1749
+ * import type { EmbeddedTerminal } from "@noldova/terminal/window";
1750
+ *
1751
+ * export function fitRows(embedded: EmbeddedTerminal, historyHeight: number): void {
1752
+ * const height = embedded.rowHeight();
1753
+ * if (height > 0)
1754
+ * embedded.setMaximumRows(Math.max(1, Math.min(15, Math.floor(historyHeight / 2 / height))));
1755
+ * }
1756
+ * ```
1757
+ */
1758
+ public readonly rowHeight: Signal<number>;
1759
+
1760
+ private constructor();
1761
+
1762
+ /**
1763
+ * Opens a pane of the session in a new element, shown.
1764
+ *
1765
+ * @param sessionId The session, such as the one {@link TerminalOwners.runAsync} gives.
1766
+ * @param injector The app's environment injector, which gives the window's services, such as its clipboard.
1767
+ * @param maximumRows The rows the shell gets, a whole number from 1 to 1,000.
1768
+ * @returns The embedded terminal, whose element the app places.
1769
+ * @throws {@link TerminalNotActiveException} While Terminal's window part isn't active in the window.
1770
+ * @throws {@link EmbeddedRowsRefusedException} For rows outside 1 to 1,000, or not a whole number.
1771
+ *
1772
+ * @example
1773
+ * ```ts
1774
+ * import type { EnvironmentInjector } from "@angular/core";
1775
+ * import { EmbeddedTerminal } from "@noldova/terminal/window";
1776
+ *
1777
+ * export function showEmbedded(sessionId: string, environmentInjector: EnvironmentInjector, host: HTMLElement): EmbeddedTerminal {
1778
+ * const embedded = EmbeddedTerminal.open(sessionId, environmentInjector, 15);
1779
+ * host.append(embedded.element);
1780
+ * embedded.focus();
1781
+ * return embedded;
1782
+ * }
1783
+ * ```
1784
+ */
1785
+ public static open(sessionId: string, injector: EnvironmentInjector, maximumRows: number): EmbeddedTerminal;
1786
+
1787
+ /**
1788
+ * Gives its shell other rows, such as when the app's page changes height; fewer rows than are drawn shrink the element, and its terminal
1789
+ * scrolls inside.
1790
+ *
1791
+ * @param rows The rows the shell gets, a whole number from 1 to 1,000.
1792
+ * @throws {@link EmbeddedRowsRefusedException} For rows outside 1 to 1,000, or not a whole number; the shell keeps its rows.
1793
+ *
1794
+ * @example
1795
+ * ```ts
1796
+ * import type { EmbeddedTerminal } from "@noldova/terminal/window";
1797
+ *
1798
+ * export function fitToHistory(embedded: EmbeddedTerminal, historyRows: number): void {
1799
+ * embedded.setMaximumRows(Math.min(15, Math.floor(historyRows / 2)));
1800
+ * }
1801
+ * ```
1802
+ */
1803
+ public setMaximumRows(rows: number): void;
1804
+
1805
+ /**
1806
+ * Stops or starts its drawing, such as while the app keeps the element out of its page; a hidden element leaves sizing the shell to another
1807
+ * shown pane of the session, while one taken out of the page and not hidden still counts as shown.
1808
+ *
1809
+ * @param shown Whether it draws.
1810
+ *
1811
+ * @example
1812
+ * ```ts
1813
+ * import type { EmbeddedTerminal } from "@noldova/terminal/window";
1814
+ *
1815
+ * export function followPageVisibility(embedded: EmbeddedTerminal): void {
1816
+ * embedded.setShown(!document.hidden);
1817
+ * }
1818
+ * ```
1819
+ */
1820
+ public setShown(shown: boolean): void;
1821
+
1822
+ /**
1823
+ * Moves the focus into its terminal, so the person's keys reach the shell; one hidden or still loading takes it once it shows with its
1824
+ * terminal.
1825
+ *
1826
+ * @example
1827
+ * ```ts
1828
+ * import type { EmbeddedTerminal } from "@noldova/terminal/window";
1829
+ *
1830
+ * export function focusOnRun(embedded: EmbeddedTerminal, runButton: HTMLButtonElement): void {
1831
+ * runButton.addEventListener("click", () => embedded.focus());
1832
+ * }
1833
+ * ```
1834
+ */
1835
+ public focus(): void;
1836
+
1837
+ /**
1838
+ * Detaches it from the session, which stays open, and removes its element from the page.
1839
+ *
1840
+ * @example
1841
+ * ```ts
1842
+ * import type { EmbeddedTerminal } from "@noldova/terminal/window";
1843
+ *
1844
+ * export function removeEmbedded(embedded: EmbeddedTerminal): void {
1845
+ * embedded.dispose();
1846
+ * }
1847
+ * ```
1848
+ */
1849
+ public dispose(): void;
1850
+ }