@awebai/oats 0.64.0 → 0.66.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +109 -11
  3. package/docs/desktop-cli-api.md +88 -5
  4. package/docs/desktop.md +14 -5
  5. package/docs/implementation.md +26 -3
  6. package/docs/integrations.md +1 -1
  7. package/docs/official-catalog.md +2 -2
  8. package/docs/packages.md +7 -7
  9. package/docs/release-notes/v0.65.0.md +187 -0
  10. package/docs/release-notes/v0.66.0.md +183 -0
  11. package/docs/servers.md +2 -2
  12. package/docs/tui.md +548 -249
  13. package/docs/upgrading.md +1 -1
  14. package/docs/workspaces.md +132 -1
  15. package/lib/core.mjs +14 -4
  16. package/lib/deployments.mjs +341 -0
  17. package/lib/resolved-deployment.mjs +37 -0
  18. package/lib/workspace.mjs +2 -0
  19. package/package-catalog.json +2 -2
  20. package/package.json +1 -1
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/deployment-label.mjs +2 -2
  23. package/packages/client/deployment-list-cli.mjs +98 -0
  24. package/packages/client/deployment-list.mjs +91 -0
  25. package/packages/client/keymap.mjs +133 -0
  26. package/packages/client/machine-contract.mjs +1 -5
  27. package/packages/client/own-codes.mjs +2 -0
  28. package/packages/client/panel-views.mjs +1 -1
  29. package/packages/client/workspace-admission.mjs +2 -1
  30. package/packages/record/bin/setup.mjs +10 -2
  31. package/packages/record/docs/capture-service.md +45 -6
  32. package/packages/record/lib/capture-service-install.mjs +6 -95
  33. package/packages/record/lib/capture-setup-write.mjs +233 -0
  34. package/packages/tui/README.md +10 -9
  35. package/packages/tui/lib/actions.mjs +89 -64
  36. package/packages/tui/lib/client.mjs +4 -1
  37. package/packages/tui/lib/config.mjs +184 -36
  38. package/packages/tui/lib/main.mjs +161 -40
  39. package/packages/tui/lib/model.mjs +73 -41
  40. package/packages/tui/lib/read.mjs +15 -45
  41. package/packages/tui/lib/store.mjs +174 -40
  42. package/packages/tui/lib/term/keys.mjs +135 -33
  43. package/packages/tui/lib/term/kitty.mjs +198 -0
  44. package/packages/tui/lib/term/through.mjs +160 -24
  45. package/packages/tui/lib/term/tty.mjs +43 -12
  46. package/packages/tui/lib/views/act.mjs +17 -13
  47. package/packages/tui/lib/views/frame.mjs +418 -421
  48. package/packages/tui/lib/views/help.mjs +90 -29
  49. package/packages/tui/lib/views/instances.mjs +38 -9
  50. package/packages/tui/lib/views/switcher.mjs +65 -21
  51. package/skills/oats-getting-started/SKILL.md +102 -32
@@ -2,13 +2,23 @@
2
2
  // a terminal has the focus the TUI reads no keys: the bytes the outer terminal sends go to the
3
3
  // agent exactly as they came, and the scanner here looks for two things only, the back key's own
4
4
  // bytes (which take the focus back to the list) and a bracketed paste (which goes to the agent as
5
- // a paste, so a back key inside it is pasted, not taken). Pure: no IO; the clock is injected.
5
+ // a paste, so a back key inside it is pasted, not taken). Under the kitty keyboard protocol
6
+ // (docs/tui.md, "Chords") it also takes the chords, and types every other key as the bytes it
7
+ // sends without the protocol (see createThrough). Pure: no IO; the clock is injected.
6
8
  //
7
9
  // The back key is tui.json's `open.detachKey`. Its grammar is THE TUI'S OWN: the keys it can take
8
- // back from a terminal and name in the footer. It began as the kernel's `--detach-key` grammar
10
+ // back from a terminal and name in the cheat sheet. It began as the kernel's `--detach-key` grammar
9
11
  // (lib/session-viewer.mjs) and keeps its set and its spelling, so a tui.json written for PR 4 means
10
12
  // the same key; it is not tied to the kernel's, which never sees this key any more.
11
- import { ESC_TIMEOUT_MS, PASTE_LIMIT, PASTE_PAUSE_MS, createKeyParser, keyId } from "./keys.mjs";
13
+ import { ESC_TIMEOUT_MS, PASTE_LIMIT, PASTE_PAUSE_MS, createKeyParser, keyId, legacyEvents } from "./keys.mjs";
14
+ import { confirmed, kittyId, kittyKey, legacyBytes, legacySequence } from "./kitty.mjs";
15
+
16
+ /** How long bytes held only as a beginning of the back key wait for the rest of it, in
17
+ * milliseconds: the back key counts only as ONE keypress (a terminal writes a key's bytes at
18
+ * once; a split read of them comes within this), so Esc and then `o` typed as two keys reach the
19
+ * agent as they were typed, and never as M-o. Bytes that may begin a paste's start marker wait
20
+ * the key parser's Esc timeout (ESC_TIMEOUT_MS) instead, as before. */
21
+ export const BACK_KEY_SPLIT_MS = 10;
12
22
 
13
23
  /** The keys that can be the back key: Control with a letter other than h, i and m (Backspace on
14
24
  * some terminals, Tab, Enter), or one of \ ] ^ _; Meta with a lowercase letter or a digit; or F1
@@ -88,18 +98,44 @@ const decoder = () => new TextDecoder("utf-8", { fatal: false });
88
98
 
89
99
  /** A scanner of the bytes typed while a terminal has the focus. `feed(bytes)` answers events in
90
100
  * order: `{ input: <bytes> }` (for the agent, as typed), `{ paste: <text> }` (a bracketed paste,
91
- * unwrapped) and, at most once per feed and last, `{ back: true, rest: <bytes> }` (the back key:
92
- * what came after it in the same read is no longer the agent's, and `rest` hands it on).
101
+ * unwrapped), `{ keyboard: flags }` (the terminal's answer to the kitty keyboard protocol's query,
102
+ * while `keyboard` is "asking": never the agent's) and, at most once per feed and last,
103
+ * `{ back: true, rest: <bytes> }` (the back key: what came after it in the same read is no longer
104
+ * the agent's, and `rest` hands it on) or `{ chord: <does>, rest: <bytes> }` (a chord, the same).
105
+ *
106
+ * UNDER THE PROTOCOL (`keyboard` the confirmed flags, term/kitty.mjs; docs/tui.md, "Chords") the
107
+ * scanner reads every `CSI` sequence typed. A `u` key is a chord when its id is one of `chords`
108
+ * (a Map of key id to the `does` it names), else the bytes it sends without the protocol
109
+ * (legacyBytes), which are the back key when they read as `leader` (the back key's key id,
110
+ * backKeyId), with no timing: Alt+O is one sequence and Esc is another. Any other sequence is
111
+ * the same, made legacy where the protocol changed it (legacySequence: the modifier, F1 to F4).
112
+ * What is not a sequence goes to the agent as it came. Nothing is timed: a sequence a read ends
113
+ * inside, or a lone ESC (which no key sends under the protocol), waits for the next read however
114
+ * late it comes; one longer than SEQUENCE_HELD is no key and goes on as it came.
115
+ * Without it (`keyboard` null or "asking") nothing of that is read, and what follows holds. While
116
+ * "asking", the answer may arrive split across reads, and over a slow link late: a read that ends
117
+ * in what may begin it (ESC, `ESC [`, `ESC [ ?` and digits) is held until `answerBy` (the clock time
118
+ * the run stops waiting for it), at least the key parser's Esc timeout. A later read that does not
119
+ * go on with the answer comes after them: within BACK_KEY_SPLIT_MS joined to them as before (the
120
+ * back key, a paste), later handed on after them, as a key of its own, so they never make the back
121
+ * key with it. giveUp() hands on what is held for the answer.
93
122
  * A read is never held back from the agent but for a beginning of the back key's own bytes, or of
94
- * a paste's start marker from its third byte: those wait for the next read, or until `expire()`
95
- * past `timeoutAt()` (the key parser's Esc timeout) hands them on as input. A paste is held until
123
+ * a paste's start marker from its third byte: those wait for the next read, or until `timeoutAt()`
124
+ * (BACK_KEY_SPLIT_MS for the back key's alone, the key parser's Esc timeout when they may begin a
125
+ * paste) hands them on as input, through `expire()` or the first read that comes later, which
126
+ * then never completes the back key with them. A paste is held until
96
127
  * its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
97
128
  * when a read arrives PASTE_PAUSE_MS after the one before is given to the agent as what it held,
98
129
  * and that read is scanned anew, as the key parser abandons a stalled paste. */
99
- export function createThrough({ sequences, now }) {
130
+ export function createThrough({ sequences, now, keyboard = null, leader = null, chords = new Map(), answerBy = null }) {
100
131
  if (typeof now !== "function") throw new TypeError("createThrough needs an injected clock: { now: () => milliseconds }");
132
+ if (!(keyboard === null || keyboard === "asking" || confirmed(keyboard))) throw new TypeError("keyboard is null, \"asking\" or flags that hold flag 1");
101
133
  const keys = sequences.map((seq) => Uint8Array.from(seq));
102
- let held = new Uint8Array(0), heldAt = 0;
134
+ let kb = keyboard;
135
+ /** The bytes held for the next read, since when, and how long they may wait: BACK_KEY_SPLIT_MS
136
+ * when they are held only as a beginning of the back key, ESC_TIMEOUT_MS when they may begin a
137
+ * paste's start marker (or its rest, see PASTE_HELD_FROM). */
138
+ let held = new Uint8Array(0), heldAt = 0, heldFor = ESC_TIMEOUT_MS, answerHeld = false;
103
139
  /** The paste being read: its content so far (null when none; only the tail that may begin the
104
140
  * end marker once it went past the limit), and whether it did. */
105
141
  let paste = null, over = false, lastFeed = 0;
@@ -157,6 +193,7 @@ export function createThrough({ sequences, now }) {
157
193
  }
158
194
 
159
195
  function scan(out, data) {
196
+ if (confirmed(kb)) return scanKitty(out, data);
160
197
  for (let i = 0; i < data.length; i++) {
161
198
  const b = data[i];
162
199
  if (b === ESC && at(data, i, PASTE_START)) {
@@ -166,27 +203,99 @@ export function createThrough({ sequences, now }) {
166
203
  if (paste !== null) return; // the paste goes on in the next read
167
204
  return scan(out, rest);
168
205
  }
206
+ // The protocol's answer, while it is awaited: the TUI's, never the agent's, and what follows
207
+ // it is read as it says.
208
+ const answer = kb === "asking" && b === ESC ? answerAt(data, i) : null;
209
+ if (answer !== null) {
210
+ if (i > 0) out.push({ input: data.subarray(0, i) });
211
+ out.push({ keyboard: answer.flags });
212
+ kb = confirmed(answer.flags) ? answer.flags : null;
213
+ return scan(out, data.subarray(answer.end));
214
+ }
169
215
  const key = keys.find((seq) => seq[0] === b && at(data, i, seq));
170
216
  if (key) {
171
217
  if (i > 0) out.push({ input: data.subarray(0, i) });
172
218
  out.push({ back: true, rest: data.subarray(i + key.length) });
173
219
  return;
174
220
  }
175
- // The read ends on what may be the beginning of the back key or of a paste: held.
176
- if (keys.some((seq) => begins(data, i, seq)) || (data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START))) {
221
+ // The read ends on what may be the beginning of the back key, of a paste or of the answer
222
+ // awaited: held, as long as the longest that it may begin allows.
223
+ const pasting = data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START);
224
+ const answering = kb === "asking" && answerBegins(data, i);
225
+ const keying = keys.some((seq) => begins(data, i, seq));
226
+ if (pasting || answering || keying) {
177
227
  if (i > 0) out.push({ input: data.subarray(0, i) });
178
228
  held = Uint8Array.from(data.subarray(i));
179
229
  heldAt = now();
230
+ const asked = answerBy !== null ? Math.max(ESC_TIMEOUT_MS, answerBy - heldAt) : data.length - i < 3 ? BACK_KEY_SPLIT_MS : ESC_TIMEOUT_MS;
231
+ heldFor = Math.max(pasting ? ESC_TIMEOUT_MS : 0, answering ? asked : 0, keying ? BACK_KEY_SPLIT_MS : 0);
232
+ answerHeld = answering;
180
233
  return;
181
234
  }
182
235
  }
183
236
  if (data.length) out.push({ input: data });
184
237
  }
185
238
 
239
+ /** Under the protocol (see above): every sequence read, the rest handed on as it came. */
240
+ function scanKitty(out, data) {
241
+ let from = 0;
242
+ const handOn = (to) => { if (to > from) out.push({ input: data.subarray(from, to) }); from = to; };
243
+ const hold = (i) => { handOn(i); held = Uint8Array.from(data.subarray(i)); heldAt = now(); heldFor = Infinity; from = data.length; };
244
+ for (let i = 0; i < data.length; i++) {
245
+ if (data[i] !== ESC) continue;
246
+ if (at(data, i, PASTE_START)) {
247
+ handOn(i);
248
+ paste = new Uint8Array(0); over = false;
249
+ const rest = inPaste(out, data.subarray(i + PASTE_START.length));
250
+ if (paste !== null) return; // the paste goes on in the next read
251
+ return scan(out, rest);
252
+ }
253
+ if (i + 1 === data.length) return hold(i);
254
+ if (data[i + 1] !== 0x5b) continue; // ESC and not `[`: no key of the protocol's, as it came
255
+ let j = i + 2;
256
+ while (j < data.length && data[j] >= 0x20 && data[j] <= 0x3f) j++;
257
+ if (j === data.length) { if (j - i <= SEQUENCE_HELD) return hold(i); continue; }
258
+ if (data[j] < 0x40 || data[j] > 0x7e) continue; // no sequence: as it came
259
+ const params = String.fromCharCode(...data.subarray(i + 2, j)), final = String.fromCharCode(data[j]), end = j + 1;
260
+ handOn(i);
261
+ from = end;
262
+ i = end - 1;
263
+ let bytes;
264
+ if (final === "u") {
265
+ if (/^\?\d{1,3}$/.test(params)) continue; // the protocol's answer again: never the agent's
266
+ const key = kittyKey(params), id = kittyId(key);
267
+ if (id !== null && chords.has(id)) { out.push({ chord: chords.get(id), rest: data.subarray(end) }); return; }
268
+ bytes = legacyBytes(key, kb);
269
+ } else bytes = legacySequence(params, final);
270
+ if (bytes === null) continue; // a key that sends nothing without the protocol: nothing
271
+ const events = leader === null ? [] : legacyEvents(bytes);
272
+ if (events.length === 1 && keyId(events[0]) === leader) { out.push({ back: true, rest: data.subarray(end) }); return; }
273
+ out.push({ input: bytes });
274
+ }
275
+ handOn(data.length);
276
+ }
277
+
278
+ /** The held bytes, once they waited as long as they may at `t`: handed on as input, as one event
279
+ * of their own (and noted, so a paste they begin is still raw), or nothing. */
280
+ function lapse(t) {
281
+ if (!held.length || t < heldAt + heldFor) return [];
282
+ const out = [{ input: held }];
283
+ held = new Uint8Array(0);
284
+ answerHeld = false;
285
+ forwarded = handedOn(out);
286
+ return out;
287
+ }
288
+
186
289
  return {
187
290
  feed(bytes) {
188
291
  if (!(bytes instanceof Uint8Array)) throw new TypeError("feed expects bytes (a Uint8Array)");
189
- const out = [], t = now();
292
+ const t = now();
293
+ // Bytes held for the answer that this read does not go on with, past the one-keypress window:
294
+ // their wait is over.
295
+ if (held.length && answerHeld && t >= heldAt + BACK_KEY_SPLIT_MS && !answerGoesOn(join(held, bytes))) heldFor = 0;
296
+ // Held bytes whose wait is over are the agent's before this read is looked at, whether or not
297
+ // expire() ran: a read that comes later never completes the back key with them (one keypress).
298
+ const late = lapse(t), out = [];
190
299
  let data = bytes;
191
300
  const soon = t - lastFeed < PASTE_PAUSE_MS;
192
301
  if (paste !== null && !soon) endPaste(out, paste);
@@ -195,30 +304,57 @@ export function createThrough({ sequences, now }) {
195
304
  lastFeed = t;
196
305
  if (paste !== null) {
197
306
  data = inPaste(out, data);
198
- if (paste !== null) return out;
307
+ if (paste !== null) return out; // nothing was held: a paste and held bytes never meet
199
308
  }
200
- if (held.length) { data = join(held, data); held = new Uint8Array(0); }
309
+ if (held.length) { data = join(held, data); held = new Uint8Array(0); answerHeld = false; }
201
310
  // The rest of a start marker whose first bytes the last read handed on: the paste is raw.
202
311
  // A beginning of that rest waits for the next read, as a held key does.
203
312
  if (raw === null && forwarded > 0 && soon) {
204
313
  const rest = PASTE_START.subarray(forwarded);
205
314
  if (at(data, 0, rest)) raw = { tail: new Uint8Array(0) };
206
- else if (begins(data, 0, rest)) { held = Uint8Array.from(data); heldAt = t; return out; }
315
+ else if (begins(data, 0, rest)) { held = Uint8Array.from(data); heldAt = t; heldFor = ESC_TIMEOUT_MS; return [...late, ...out]; }
207
316
  }
208
317
  forwarded = 0;
209
318
  if (raw !== null) data = inRaw(out, data);
210
319
  if (raw === null && data.length) scan(out, data);
211
- forwarded = handedOn(out);
320
+ // Under the protocol a paste's start marker is held whole: no paste is ever passed on raw.
321
+ forwarded = confirmed(kb) ? (handedOn(out), 0) : handedOn(out);
212
322
  // Events are handed out as copies: the caller may keep them past the next read.
213
- return out.map((event) => (event.input ? { input: Uint8Array.from(event.input) } : event.rest ? { back: true, rest: Uint8Array.from(event.rest) } : event));
323
+ return [...late, ...out].map((event) => (event.input ? { input: Uint8Array.from(event.input) } : event.rest ? { ...event, rest: Uint8Array.from(event.rest) } : event));
214
324
  },
215
- expire() {
216
- if (!held.length || now() < heldAt + ESC_TIMEOUT_MS) return [];
217
- const out = [{ input: held }];
218
- held = new Uint8Array(0);
219
- forwarded = handedOn(out);
220
- return out;
325
+ expire() { return lapse(now()); },
326
+ timeoutAt() { return held.length && Number.isFinite(heldFor) ? heldAt + heldFor : null; },
327
+ /** The answer is no longer awaited (none came in time): a late one goes on as it came, and what
328
+ * was held for it is handed on (the events answered). */
329
+ giveUp() {
330
+ if (kb === "asking") kb = null;
331
+ if (!answerHeld) return [];
332
+ heldFor = 0;
333
+ return lapse(now()).map((event) => ({ input: Uint8Array.from(event.input) }));
221
334
  },
222
- timeoutAt() { return held.length ? heldAt + ESC_TIMEOUT_MS : null; },
223
335
  };
224
336
  }
337
+
338
+ /** The most bytes of a `CSI` sequence held for its end under the protocol; a longer one is no key,
339
+ * and goes on as it came. */
340
+ const SEQUENCE_HELD = 64;
341
+ /** Whether `data` from `i` to its end may begin the protocol's answer `CSI ? flags u`: ESC, `ESC [`,
342
+ * or `ESC [ ?` and digits, short of the `u`. */
343
+ function answerBegins(data, i) {
344
+ const left = data.length - i;
345
+ if (left < 1 || left > 6 || data[i] !== ESC) return false;
346
+ if (left >= 2 && data[i + 1] !== 0x5b) return false;
347
+ if (left >= 3 && data[i + 2] !== 0x3f) return false;
348
+ for (let j = i + 3; j < data.length; j++) if (data[j] < 0x30 || data[j] > 0x39) return false;
349
+ return true;
350
+ }
351
+ /** Whether `data` begins with the answer, whole or begun. */
352
+ const answerGoesOn = (data) => answerAt(data, 0) !== null || answerBegins(data, 0);
353
+ /** The protocol's answer `CSI ? flags u` whole at `i`: `{ flags, end }`, or null. */
354
+ function answerAt(data, i) {
355
+ if (data[i + 1] !== 0x5b || data[i + 2] !== 0x3f) return null;
356
+ let j = i + 3;
357
+ while (j < data.length && j - i < 7 && data[j] >= 0x30 && data[j] <= 0x39) j++;
358
+ if (j === i + 3 || data[j] !== 0x75) return null;
359
+ return { flags: Number(String.fromCharCode(...data.subarray(i + 3, j))), end: j + 1 };
360
+ }
@@ -1,12 +1,14 @@
1
1
  // The guard: everything the TUI changes in the terminal, and the promise that it is put back.
2
- // With term/screen.mjs it is the only module that produces an ESC byte. docs/tui.md lists the
3
- // changes for operators; ENTER and LEAVE below are that list, and nothing else is ever switched on:
4
- // no mouse or focus reporting, no keyboard protocol, no keypad or cursor-key mode, no title, no
5
- // clipboard, no bell, no query that expects a reply.
2
+ // With term/screen.mjs it is the only module that writes an ESC byte to the terminal. docs/tui.md
3
+ // lists the changes for operators; ENTER and LEAVE below are that list, with the kitty keyboard
4
+ // protocol (PUSH, QUERY, POP), and nothing else is ever switched on: no mouse or focus reporting, no
5
+ // keypad or cursor-key mode, no title, no clipboard, no bell, and no query but the protocol's.
6
6
  //
7
7
  // Handing the terminal to someone else (the shell at a suspend) is leave() and enter(), and only
8
8
  // that pair. An agent's terminal is never handed the terminal: the TUI draws it (lib/panel.mjs).
9
9
 
10
+ import { KEYBOARD_FLAGS } from "./kitty.mjs";
11
+
10
12
  const mode = (number, on) => `\x1b[?${number}${on ? "h" : "l"}`;
11
13
  /** After raw mode: the alternate screen, the cursor hidden, autowrap off, bracketed paste on.
12
14
  * Autowrap is off so no row wraps where the terminal and width.mjs disagree about a character (a
@@ -15,6 +17,13 @@ const mode = (number, on) => `\x1b[?${number}${on ? "h" : "l"}`;
15
17
  export const ENTER = mode(1049, true) + mode(25, false) + mode(7, false) + mode(2004, true);
16
18
  /** The reverse, with the style reset; then raw mode off. */
17
19
  export const LEAVE = mode(2004, false) + mode(7, true) + "\x1b[0m" + mode(25, true) + mode(1049, false);
20
+ /** The kitty keyboard protocol (term/kitty.mjs; docs/tui.md, "Chords"): pushed with the flags the TUI
21
+ * asks for, on the alternate screen (a terminal keeps one stack of flags per screen), and asked
22
+ * about; popped before the alternate screen is left, on every way out, at a suspend, and before any
23
+ * other program is given the terminal. A terminal that does not know it ignores all three. */
24
+ export const PUSH = `\x1b[>${KEYBOARD_FLAGS}u`;
25
+ export const QUERY = "\x1b[?u";
26
+ export const POP = "\x1b[<u";
18
27
 
19
28
  /** 128 + the signal's number, as a shell reports a process the signal ended. */
20
29
  export const SIGNAL_STATUS = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129, SIGQUIT: 131 });
@@ -28,8 +37,11 @@ export function isTerminal({ stdin, stdout, env }) {
28
37
  return stdin.isTTY === true && stdout.isTTY === true && typeof env.TERM === "string" && env.TERM !== "" && env.TERM !== "dumb";
29
38
  }
30
39
 
31
- /** The guard of one run. `frame()` answers the bytes of the newest frame when it is time to write
32
- * one; `onInput(bytes)`, `onResize()` and `onRedraw()` (the screen must be drawn in full: after a
40
+ /** The guard of one run. `keyboard` true asks for the kitty keyboard protocol: PUSH and QUERY after
41
+ * ENTER; then `keyboardAnswered(true)` keeps it (it is pushed again after every LEAVE and ENTER),
42
+ * and `keyboardAnswered(false)` (an answer without flag 1, or none in time) pops it and never
43
+ * pushes it again. While pushed, every LEAVE is written after POP. `frame()` answers the bytes of
44
+ * the newest frame when it is time to write one; `onInput(bytes)`, `onResize()` and `onRedraw()` (the screen must be drawn in full: after a
33
45
  * suspend, after SIGCONT) are the events. `done` resolves once, with `{ status, error }`, after the
34
46
  * terminal is restored and every listener is removed.
35
47
  * Three more, for whoever started work that outlives a frame (the reads of lib/read.mjs), each
@@ -37,8 +49,15 @@ export function isTerminal({ stdin, stdout, env }) {
37
49
  * the terminal is handed back and before the signal; `onResume(asked)` when it runs again, `asked`
38
50
  * true after its own suspend and false when it was stopped and continued from outside; `onEnd()`
39
51
  * once on every way out, after the terminal is restored and before `done` resolves. */
40
- export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onRedraw, onStop = null, onResume = null, onEnd = null, setTimer = setTimeout, clearTimer = clearTimeout }) {
52
+ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onRedraw, onStop = null, onResume = null, onEnd = null, keyboard = false, setTimer = setTimeout, clearTimer = clearTimeout }) {
41
53
  let entered = false, raw = false, modes = false;
54
+ /** The protocol: "asking" until the terminal answered, "on" once it did with flag 1, "off" without
55
+ * it; and whether it is pushed now. */
56
+ let kb = keyboard ? "asking" : "off", pushed = false;
57
+ /** What is written after ENTER: the protocol pushed, and asked about while no answer came. */
58
+ const pushing = () => (kb === "off" ? "" : kb === "asking" ? PUSH + QUERY : PUSH);
59
+ /** What is written before LEAVE: the protocol popped, when it is pushed. */
60
+ const popping = () => { if (!pushed) return ""; pushed = false; return POP; };
42
61
  let suspended = false, stopTimer = null;
43
62
  let over = false, blocked = false, stale = false;
44
63
  let settle;
@@ -57,15 +76,24 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
57
76
  stdin.setRawMode(true);
58
77
  if (!entered) return; // left while entering: nothing more is switched on
59
78
  modes = true;
60
- stdout.write(ENTER);
79
+ const push = pushing();
80
+ pushed = push !== "";
81
+ stdout.write(ENTER + push);
61
82
  }
62
83
  /** Put the terminal back. Idempotent; never throws. */
63
84
  function leave() {
64
85
  if (!entered) return;
65
86
  entered = false;
66
- if (modes) { modes = false; quietly(() => stdout.write(LEAVE)); }
87
+ if (modes) { modes = false; const pop = popping(); quietly(() => stdout.write(pop + LEAVE)); }
67
88
  if (raw) { raw = false; quietly(() => stdin.setRawMode(false)); }
68
89
  }
90
+ /** The terminal's answer to the protocol's query, or none in time (`false`): kept, or popped and
91
+ * never pushed again in this run. An answer after either is not taken. */
92
+ function keyboardAnswered(on) {
93
+ if (kb !== "asking" || over) return;
94
+ kb = on ? "on" : "off";
95
+ if (!on && entered) { const pop = popping(); if (pop) quietly(() => stdout.write(pop)); }
96
+ }
69
97
 
70
98
  /** The end of the run, by any way out: restore, stop listening, report once. */
71
99
  function finish(status, error) {
@@ -133,11 +161,14 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
133
161
  * write. Entering the alternate screen also saves the cursor, and a terminal that is still on
134
162
  * it may take a second entry as a new save, over the shell's position: the prompt would then
135
163
  * land on the wrong row at the end. Leaving first puts back the cursor the first entry saved,
136
- * so the second saves the same one. On a terminal that was reset, the leave changes nothing. */
164
+ * so the second saves the same one. On a terminal that was reset, the leave changes nothing.
165
+ * The kitty keyboard protocol goes with the modes: popped before LEAVE, pushed again after ENTER. */
137
166
  function reassert() {
138
167
  if (!entered || over) return;
139
168
  quietly(() => { stdin.setRawMode(false); stdin.setRawMode(true); });
140
- quietly(() => stdout.write(LEAVE + ENTER));
169
+ const pop = popping(), push = pushing();
170
+ pushed = push !== "";
171
+ quietly(() => stdout.write(pop + LEAVE + ENTER + push));
141
172
  attempt(onRedraw);
142
173
  }
143
174
  /** SIGCONT. After our own suspend: come back. Otherwise the process was stopped and continued
@@ -180,5 +211,5 @@ export function createGuard({ stdin, stdout, proc, frame, onInput, onResize, onR
180
211
  /** The terminal's size now; 80x24 when the terminal does not say. */
181
212
  const size = () => ({ cols: Number.isInteger(stdout.columns) && stdout.columns > 0 ? stdout.columns : 80, rows: Number.isInteger(stdout.rows) && stdout.rows > 0 ? stdout.rows : 24 });
182
213
 
183
- return { start, enter, leave, finish, suspend, reassert, attempt, draw, size, done, get entered() { return entered; } };
214
+ return { start, enter, leave, finish, suspend, reassert, attempt, draw, size, done, keyboardAnswered, get entered() { return entered; }, get keyboard() { return kb; } };
184
215
  }
@@ -1,7 +1,7 @@
1
1
  // The act view: one confirmation of a stop, a retire, a start or a restart, over the list of
2
2
  // instances (as the help is). Pure: no IO, no clock, no escape byte. (model, area) -> rows.
3
3
  // The content (lib/model.mjs actView) scrolls when it is taller than the area; the buttons keep
4
- // the area's last row. The TUI's own words are lit(); every shared sentence, the kernel's lines,
4
+ // the area's last rows. The TUI's own words are lit(); every shared sentence, the kernel's lines,
5
5
  // a name and a path go through shown(). Meaning never rests on colour alone: the button with the
6
6
  // focus is drawn between `>` and `<` as well as in reverse.
7
7
  import { EMPTY, lit, shown, shownLines, textOf } from "../term/text.mjs";
@@ -55,31 +55,35 @@ export function actRows(m, cols) {
55
55
  return rows.map((spans) => spans.map((span) => ({ ...span, col: span.col + LEFT })));
56
56
  }
57
57
 
58
- /** The buttons, one per offer of the confirmation and in its order, on one row; the one with the
59
- * focus between `>` and `<`. */
60
- function buttonRow(buttons, cols) {
61
- const spans = [];
62
- let col = LEFT;
58
+ /** The buttons, one per offer of the confirmation and in its order, the one with the focus between
59
+ * `>` and `<`: on one row when they fit, else on as many as they need, a button never split and
60
+ * never left out (the area beside the sidebar can be narrow, and every offer, the one with the
61
+ * focus among them, must be seen). A label wider than a row is cut there. */
62
+ function buttonRows(buttons, cols) {
63
+ const rows = [];
64
+ let row = [], col = LEFT;
63
65
  for (const button of buttons) {
64
66
  const label = button.focused ? `> ${button.label} <` : `[ ${button.label} ]`;
65
- if (col + label.length > cols) break;
66
- spans.push({ col, text: lit(label), width: label.length, ...(button.focused ? { style: FOCUSED } : {}) });
67
+ if (row.length && col + label.length > cols) { rows.push(row); row = []; col = LEFT; }
68
+ row.push({ col, text: lit(label), width: Math.max(0, Math.min(label.length, cols - col)), ...(button.focused ? { style: FOCUSED } : {}) });
67
69
  col += label.length + GAP;
68
70
  }
69
- return spans;
71
+ if (row.length) rows.push(row);
72
+ return rows;
70
73
  }
71
74
 
72
75
  /** `{ rows, extent, room }`: `size.rows` rows for an area `size.cols` wide: the content scrolled
73
- * to the confirmation's `top`, then an empty row and the buttons on the last row. `extent` and
74
- * `room` are the content's, for the store's scroll. */
76
+ * to the confirmation's `top`, then an empty row and the buttons on the last rows (buttonRows).
77
+ * `extent` and `room` are the content's, for the store's scroll. */
75
78
  export function act(m, size) {
76
79
  const rows = Array.from({ length: size.rows }, () => []);
77
- const room = Math.max(0, size.rows - 2);
80
+ const buttons = buttonRows(m.act.buttons, size.cols).slice(-Math.max(0, size.rows - 1));
81
+ const room = Math.max(0, size.rows - 1 - buttons.length);
78
82
  const all = actRows(m, size.cols);
79
83
  const win = windowOf({ top: m.act.top ?? 0, count: all.length, height: room });
80
84
  all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
81
85
  const note = cutNote(win.above, win.below);
82
86
  if (note && room > 0) rows[room - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
83
- if (size.rows > 0) rows[size.rows - 1] = buttonRow(m.act.buttons, size.cols);
87
+ buttons.forEach((spans, i) => { rows[size.rows - buttons.length + i] = spans; });
84
88
  return { rows, extent: all.length, room: Math.max(1, room) };
85
89
  }