@awebai/oats 0.65.0 → 0.67.1

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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -1,11 +1,14 @@
1
1
  /** The key parser of `oats tui`: raw terminal input bytes in, key events out.
2
- * Pure: no IO, no timers, no imports; the only clock is the injected `now`.
3
- * It reads escape sequences and never writes one.
2
+ * Pure: no IO, no timers; the only clock is the injected `now`. Its one import is the reading of
3
+ * the kitty keyboard protocol (term/kitty.mjs). It reads escape sequences and never writes one.
4
4
  *
5
- * Events are plain objects of exactly three shapes:
5
+ * Events are plain objects of exactly four shapes:
6
6
  * a named key { name, ctrl, alt, shift }
7
7
  * a grapheme { text } or { text, alt: true }
8
- * a paste { paste } or { paste: "", truncated: true } */
8
+ * a paste { paste } or { paste: "", truncated: true }
9
+ * an answer { keyboard: flags }: the terminal's answer to the protocol's query (`CSI ? flags u`),
10
+ * while the parser waits for one */
11
+ import { confirmed, kittyId, kittyKey, legacyBytes, legacyParams } from "./kitty.mjs";
9
12
 
10
13
  export const ESC_TIMEOUT_MS = 50;
11
14
  export const PASTE_LIMIT = 1024 * 1024;
@@ -31,6 +34,7 @@ const TILDE_KEYS = Object.freeze({
31
34
  /** The Linux console sends F1..F5 as `ESC [ [ A` .. `ESC [ [ E`. */
32
35
  const LINUX_KEYS = Object.freeze({ __proto__: null, A: "f1", B: "f2", C: "f3", D: "f4", E: "f5" });
33
36
  const KEY_PARAMS = /^\d*(?:;\d*)?$/;
37
+ const NO_CHORDS = new Map();
34
38
  const GRAPHEMES = new Intl.Segmenter("en", { granularity: "grapheme" });
35
39
 
36
40
  const named = (name, ctrl = false, alt = false, shift = false) => ({ name, ctrl, alt, shift });
@@ -39,7 +43,7 @@ const named = (name, ctrl = false, alt = false, shift = false) => ({ name, ctrl,
39
43
  const CTRL_PUNCTUATION = "\\]^_";
40
44
 
41
45
  /** The key of a C0 byte or DEL, or null for a byte that is no key (NUL). 0x1c..0x1f are Control
42
- * with \ ] ^ _ (the leader, `C-\` by default, is one of them: docs/tui.md, "The leader"). */
46
+ * with \ ] ^ _ (`C-\`, a leader tui.json can name, is one of them: docs/tui.md, "The leader"). */
43
47
  function c0Key(b) {
44
48
  if (b === 0x0d || b === 0x0a) return named("enter");
45
49
  if (b === 0x09) return named("tab");
@@ -121,16 +125,66 @@ function decodeLenient(bytes, length) {
121
125
  return text + String.fromCodePoint.apply(null, points);
122
126
  }
123
127
 
128
+ /** The events a key's legacy bytes read as, whole: a fresh parser without the protocol, the Esc of a
129
+ * lone ESC taken at once (the bytes are one key, nothing follows them). */
130
+ export function legacyEvents(bytes) {
131
+ let t = 0;
132
+ const parser = createKeyParser({ now: () => t });
133
+ const events = parser.feed(bytes);
134
+ t = Infinity;
135
+ return [...events, ...parser.expire()];
136
+ }
137
+
124
138
  /** `now` is the injected clock in milliseconds; the parser reads it once per
125
139
  * `feed` and once per `expire`, and nowhere else.
126
140
  *
141
+ * `keyboard` is the kitty keyboard protocol (docs/tui.md, "Chords"): null, the default, without it;
142
+ * "asking" while the terminal's answer to the query is awaited; or the flags it answered once they
143
+ * hold flag 1. `chords` are the key ids the TUI binds as chords (packages/client/keymap.mjs CHORDS):
144
+ * a Map of key id to what it does, of which only the ids are read here. While asking, the answer `CSI ? flags u` is the event `{ keyboard: flags }`, and the bytes
145
+ * after it are read as it says: with flag 1 under the protocol, else as before. Under the protocol
146
+ * a `CSI … u` key is read as its legacy bytes are (term/kitty.mjs legacyBytes, legacyEvents above),
147
+ * so Ctrl+Shift+C is Ctrl+C as without it, and a chord of `chords` as its own key id (term/kitty.mjs
148
+ * kittyId): a Ctrl+Alt one (`ctrl+alt+k`), which without the protocol is ESC and a C0 byte
149
+ * (`ctrl+alt+k` too, here, which the store binds only under the protocol), and a Ctrl+Shift one
150
+ * (`ctrl+shift+k`, bound only when keys.json chose that family), which is read from the protocol's
151
+ * event alone: without it, and as a legacy byte under it, Ctrl+Shift+K is Ctrl+K, and Ctrl+Shift+D
152
+ * and Ctrl+Shift+M are Ctrl+D and Enter. A Ctrl+Shift letter that is not among `chords` reads as its
153
+ * legacy bytes, as before, but the one whose legacy bytes read as `leader` (the leader's key id,
154
+ * null for none): Ctrl+Shift+X under the protocol is `ctrl+shift+x`, which nothing binds, and never
155
+ * the leader Ctrl+X. A character that is not ASCII is never a chord:
156
+ * AltGr's `€`, as text or as a `CSI … u` of its own, reads as that text. An Alt+Shift arrow chord is
157
+ * read by its legacy sequence (`CSI 1 ; 4 A`) in every state. An answer
158
+ * at any other time is dropped, as is a `u` key while not under the protocol. Under it a key in a
159
+ * legacy shape has its modifier made xterm's (term/kitty.mjs legacyParams: the lock keys dropped),
160
+ * and nothing is timed: a terminal under the protocol sends no lone ESC for a key, so an ESC, like
161
+ * any sequence begun, waits for what follows it however late that comes, and Esc is its own
162
+ * sequence.
163
+ * While asking, the answer may come split across reads, and over a slow link late: with `answerBy`
164
+ * (the clock time the run stops waiting for it) an ESC that a later read follows with `[` is kept as
165
+ * its possible beginning (a `candidate`) up to then. What turns out not to be the answer is read as
166
+ * it was typed: the Esc key, then `[` and the rest as text. A late ESC that `[` does not follow is
167
+ * the Esc key, as before, and so a lone ESC is, at `answerBy` at the latest.
168
+ *
127
169
  * feed(bytes) the events of these bytes, in order. Text is never held back:
128
170
  * a complete character is emitted by the feed that completes it.
129
171
  * expire() call when the clock reaches timeoutAt(): the Esc key, if a lone
130
172
  * ESC has waited ESC_TIMEOUT_MS; else nothing.
131
- * timeoutAt() the clock time at which expire() is due, or null. */
132
- export function createKeyParser({ now } = {}) {
173
+ * timeoutAt() the clock time at which expire() is due, or null.
174
+ * giveUp() the answer is no longer awaited (none came in time): a late one is dropped, and
175
+ * the events of what was kept for it are answered.
176
+ * keyboard the protocol as it is now: null, "asking" or the confirmed flags. */
177
+ export function createKeyParser({ now, keyboard = null, chords = NO_CHORDS, leader = null, answerBy = null } = {}) {
133
178
  if (typeof now !== "function") throw new TypeError("createKeyParser needs an injected clock: { now: () => milliseconds }");
179
+ if (!(keyboard === null || keyboard === "asking" || confirmed(keyboard))) throw new TypeError("keyboard is null, \"asking\" or flags that hold flag 1");
180
+ if (!(chords instanceof Map)) throw new TypeError("chords is a Map of key ids");
181
+ let kb = keyboard;
182
+ /** An ESC kept past its timeout as the possible beginning of the answer, and the CSI it began. */
183
+ let candidate = false;
184
+ const asking = () => kb === "asking" && answerBy !== null;
185
+ /** When a lone ESC is the Esc key: after ESC_TIMEOUT_MS, and while the answer is awaited not
186
+ * before `answerBy` (a later read decides it sooner, see feed). */
187
+ const escDue = () => (asking() ? Math.max(escAt + ESC_TIMEOUT_MS, answerBy) : escAt + ESC_TIMEOUT_MS);
134
188
  const utf8 = utf8Decoder();
135
189
  let state = GROUND, out = [], feedAt = 0, lastFeedAt = 0;
136
190
  let run = ""; // consecutive printable code points of this feed, not yet cut into graphemes
@@ -189,6 +243,12 @@ export function createKeyParser({ now } = {}) {
189
243
  /** Inside a CSI, an SS3 or the Linux console form. A control byte is dropped and
190
244
  * the sequence goes on, an ESC starts over, a byte >= 0x80 aborts and is dropped. */
191
245
  const inSequence = (b) => {
246
+ // A candidate goes on only as the answer does: `?`, at most three digits, `u`.
247
+ if (candidate) {
248
+ const goesOn = seq === "" ? b === 0x3f : b === 0x75 ? /^\?\d{1,3}$/.test(seq) : b >= 0x30 && b <= 0x39 && /^\?\d{0,2}$/.test(seq);
249
+ if (!goesOn) { replay(); step(b); return; }
250
+ if (b === 0x75) candidate = false;
251
+ }
192
252
  if (b === ESC) { startEscape(); return; }
193
253
  if (b < 0x20 || b === 0x7f) return;
194
254
  if (b >= 0x80) { state = GROUND; return; }
@@ -206,10 +266,42 @@ export function createKeyParser({ now } = {}) {
206
266
  else if (seq === "" && final === "[") state = LINUX;
207
267
  else if (seq === "" && final === "M") { state = MOUSE; mouse = 3; } // X10 mouse report: 3 raw bytes follow
208
268
  else if (seq === "200" && final === "~") state = PASTE;
209
- else key = csiKey(seq, final);
269
+ else if (final === "u") { kittyEvents(seq); return; }
270
+ else key = csiKey(confirmed(kb) ? legacyParams(seq, final) : seq, final);
210
271
  if (key) emit(key);
211
272
  };
212
273
 
274
+ /** A candidate that is not the answer, as it was typed: the Esc key, then `[` and what followed. */
275
+ const replay = () => {
276
+ const typed = `[${seq ?? ""}`;
277
+ candidate = false; state = GROUND;
278
+ emit(named("escape"));
279
+ for (const c of typed) ground(c.charCodeAt(0));
280
+ };
281
+
282
+ /** A `CSI … u`: the protocol's answer while it is awaited, or a key under the protocol. */
283
+ const kittyEvents = (seq) => {
284
+ const answer = seq === null ? null : /^\?(\d{1,3})$/.exec(seq);
285
+ if (answer) {
286
+ if (kb !== "asking") { flush(); return; }
287
+ const flags = Number(answer[1]);
288
+ kb = confirmed(flags) ? flags : null;
289
+ emit({ keyboard: flags });
290
+ return;
291
+ }
292
+ const key = kb === null || kb === "asking" ? null : kittyKey(seq);
293
+ if (key === null) { flush(); return; }
294
+ const id = kittyId(key);
295
+ if (id !== null && chords.has(id)) { emit(named(String.fromCharCode(key.code), key.ctrl, key.alt, key.shift)); return; }
296
+ const bytes = legacyBytes(key, kb);
297
+ if (bytes === null) { flush(); return; }
298
+ const events = legacyEvents(bytes);
299
+ // A key with an id of its own whose legacy bytes read as the leader (Ctrl+Shift+X is 0x18, as
300
+ // Ctrl+X) is its own key, which nothing binds: never the leader.
301
+ if (id !== null && leader !== null && events.length === 1 && keyId(events[0]) === leader) { emit(named(String.fromCharCode(key.code), key.ctrl, key.alt, key.shift)); return; }
302
+ for (const event of events) emit(event);
303
+ };
304
+
213
305
  const endPaste = (truncated) => {
214
306
  emit(truncated ? { paste: "", truncated: true } : { paste: decodeLenient(held, size) });
215
307
  held = null; size = 0; over = false; matched = 0;
@@ -266,37 +358,46 @@ export function createKeyParser({ now } = {}) {
266
358
  if (state === PASTE && feedAt - lastFeedAt >= PASTE_PAUSE_MS) endPaste(true);
267
359
  };
268
360
 
361
+ /** One byte, in whatever state the parser is (a paste's content is read by inPaste). */
362
+ function step(b) {
363
+ switch (state) {
364
+ case GROUND: ground(b); break;
365
+ case ESCAPE: afterEscape(b); break;
366
+ case MOUSE:
367
+ if (b === ESC) startEscape();
368
+ else if (--mouse === 0) state = GROUND;
369
+ break;
370
+ case STRING: // swallowed as it streams, never held
371
+ if (b === ESC) state = STRING_ESC;
372
+ else if (bel && b === 0x07) state = GROUND;
373
+ break;
374
+ case STRING_ESC:
375
+ // `ESC \` is ST and ends the string. An ESC before anything else abandons
376
+ // the string and starts a new sequence, as in a CSI: the next key that
377
+ // sends an ESC recovers from a string whose end never arrives.
378
+ if (b === 0x5c) state = GROUND;
379
+ else if (b !== ESC) afterEscape(b);
380
+ break;
381
+ default: inSequence(b);
382
+ }
383
+ }
384
+
269
385
  return {
270
386
  feed(bytes) {
271
387
  if (!(bytes instanceof Uint8Array)) throw new TypeError("feed expects bytes (a Uint8Array)");
272
388
  feedAt = now();
273
- // A lone ESC that already waited its time is the Esc key; these bytes start fresh.
274
- if (state === ESCAPE && feedAt >= escAt + ESC_TIMEOUT_MS) { state = GROUND; emit(named("escape")); }
389
+ // A lone ESC that already waited its time is the Esc key; these bytes start fresh. Under the
390
+ // protocol nothing is timed. While the answer is awaited, one these bytes follow with `[` may
391
+ // begin it: kept, as a candidate.
392
+ if (state === ESCAPE && !confirmed(kb) && feedAt >= escAt + ESC_TIMEOUT_MS) {
393
+ if (asking() && feedAt < answerBy && bytes[0] === 0x5b) candidate = true;
394
+ else { state = GROUND; emit(named("escape")); }
395
+ }
275
396
  abandonStalledPaste();
276
397
  lastFeedAt = feedAt;
277
398
  for (let i = 0; i < bytes.length; i++) {
278
399
  if (state === PASTE) { i = inPaste(bytes, i) - 1; continue; }
279
- const b = bytes[i];
280
- switch (state) {
281
- case GROUND: ground(b); break;
282
- case ESCAPE: afterEscape(b); break;
283
- case MOUSE:
284
- if (b === ESC) startEscape();
285
- else if (--mouse === 0) state = GROUND;
286
- break;
287
- case STRING: // swallowed as it streams, never held
288
- if (b === ESC) state = STRING_ESC;
289
- else if (bel && b === 0x07) state = GROUND;
290
- break;
291
- case STRING_ESC:
292
- // `ESC \` is ST and ends the string. An ESC before anything else abandons
293
- // the string and starts a new sequence, as in a CSI: the next key that
294
- // sends an ESC recovers from a string whose end never arrives.
295
- if (b === 0x5c) state = GROUND;
296
- else if (b !== ESC) afterEscape(b);
297
- break;
298
- default: inSequence(b);
299
- }
400
+ step(bytes[i]);
300
401
  }
301
402
  flush();
302
403
  const events = out;
@@ -304,14 +405,29 @@ export function createKeyParser({ now } = {}) {
304
405
  return events;
305
406
  },
306
407
  expire() {
307
- if (state !== ESCAPE || now() < escAt + ESC_TIMEOUT_MS) return [];
408
+ if (state !== ESCAPE || confirmed(kb) || now() < escDue()) return [];
308
409
  state = GROUND;
309
410
  return [named("escape")];
310
411
  },
311
- /** Only a lone ESC has a deadline. Every other incomplete sequence waits for its end. */
412
+ /** Only a lone ESC has a deadline, and none under the protocol. Every other incomplete sequence
413
+ * waits for its end. */
312
414
  timeoutAt() {
313
- return state === ESCAPE ? escAt + ESC_TIMEOUT_MS : null;
415
+ return state === ESCAPE && !confirmed(kb) ? escDue() : null;
416
+ },
417
+ giveUp() {
418
+ if (kb !== "asking") return [];
419
+ kb = null;
420
+ if (candidate) replay();
421
+ else if (state === ESCAPE && now() >= escAt + ESC_TIMEOUT_MS) { state = GROUND; emit(named("escape")); }
422
+ // An answer begun in one read whose end never came: no key sends `CSI ?`, so it is dropped,
423
+ // and the next key is read afresh.
424
+ else if (state === CSI && seq !== null && /^\?\d{0,3}$/.test(seq)) state = GROUND;
425
+ flush();
426
+ const events = out;
427
+ out = [];
428
+ return events;
314
429
  },
430
+ get keyboard() { return kb; },
315
431
  };
316
432
  }
317
433
 
@@ -0,0 +1,223 @@
1
+ /** The kitty keyboard protocol, as `oats tui` reads it (docs/tui.md, "Chords"): the flags it asks
2
+ * for, a `CSI … u` key read, and the bytes the same key sends without the protocol. Pure: no IO,
3
+ * no state, no imports, no global; as the key parser's one import it is held to the parser's rule
4
+ * (packages/tui/test/keys.test.mjs). The guard (term/tty.mjs) pushes, queries and pops the
5
+ * protocol; the key parser (term/keys.mjs) and the scanner of what is typed into a terminal
6
+ * (term/through.mjs) read what comes back with these.
7
+ *
8
+ * Under the protocol a terminal sends Esc, and every key held with Ctrl or Alt, as
9
+ * `CSI code[:shifted[:base]] [; mods] u`: one sequence, never an ESC alone, so Alt+O and Esc then
10
+ * `o` are told apart exactly. Everything else (text, Shift and a character, Enter, Tab and
11
+ * Backspace alone, the arrows, the function keys) keeps the bytes it has without it.
12
+ *
13
+ * What the TUI reads is what the legacy bytes of a key read as, with two exceptions: the chords
14
+ * (packages/client/keymap.mjs CHORDS) of Ctrl+Alt, and of Ctrl+Shift when keys.json chose that
15
+ * family, which keep their own key id (`ctrl+alt+k`, `ctrl+shift+k`, kittyId), and the exact Alt
16
+ * and Esc above. A Ctrl+Shift chord is read only from this event, whose Shift bit is its own: its
17
+ * legacy bytes are Ctrl's alone (Ctrl+Shift+D is 0x04, EOF), and no legacy byte is ever one. What it types into an agent is those legacy bytes
18
+ * (`legacyBytes`), so the agent's program gets what it gets without the protocol. The Alt+Shift
19
+ * arrow chords need no exception: their legacy sequence is their own (LEGACY_CHORDS). */
20
+
21
+ /** The flags pushed (`CSI > flags u`): 1, disambiguate the escape codes, and 4, report alternate
22
+ * keys, so the shifted key a key with Shift makes on the person's layout comes with it. The
23
+ * maintainer's decision of 2026-10-19; set it to 1 and flag 4 is never asked for: the US table
24
+ * below is then the only way to the shifted key. No other flag (2, 8, 16) is ever asked for. */
25
+ export const KEYBOARD_FLAGS = 1 | 4;
26
+ /** The flag the TUI needs confirmed to read the protocol at all, and the one that makes the shifted
27
+ * key exact. */
28
+ export const DISAMBIGUATE = 1, ALTERNATE_KEYS = 4;
29
+
30
+ /** Whether the flags a terminal confirmed (its `CSI ? flags u` answer) let the TUI read the
31
+ * protocol: the answer must hold flag 1. Any other answer is as no answer. */
32
+ export const confirmed = (flags) => Number.isInteger(flags) && (flags & DISAMBIGUATE) !== 0;
33
+
34
+ /** `code[:shifted[:base]][;mods]`: the parameters of a `CSI … u` key under flags 1 and 4. Flag 4
35
+ * puts the subfields on every key, so they are taken on every one; the base-layout key (the
36
+ * third) is read and ignored. No event type, no text: flags 2 and 16 are never asked for. */
37
+ const PARAMS = /^(\d{1,7})(?::(\d{0,7})(?::\d{0,7})?)?(?:;(\d{1,3}))?$/;
38
+ /** The modifier bits after the 1 is taken away: Shift, Alt, Ctrl. Super, Hyper, Meta and the lock
39
+ * bits are dropped: a terminal sends a key held with them as it sends the key without them. */
40
+ const SHIFT = 1, ALT = 2, CTRL = 4;
41
+
42
+ /** A `CSI … u` key's parameters (the bytes between `CSI` and `u`) as `{ code, shifted, shift, alt,
43
+ * ctrl }`, or null when they are no key: a reply (`?flags`), an event type or a text field, a
44
+ * modifier outside 1..256, a code that is no Unicode scalar. `shifted` is the alternate key flag 4
45
+ * reports, or null when it is absent or empty. */
46
+ export function kittyKey(params) {
47
+ const match = typeof params === "string" ? PARAMS.exec(params) : null;
48
+ if (!match) return null;
49
+ const code = Number(match[1]), shifted = match[2] ? Number(match[2]) : null, m = match[3] === undefined ? 1 : Number(match[3]);
50
+ if (!scalar(code) || (shifted !== null && !scalar(shifted)) || !(m >= 1 && m <= 256)) return null;
51
+ const bits = m - 1;
52
+ return { code, shifted, shift: (bits & SHIFT) !== 0, alt: (bits & ALT) !== 0, ctrl: (bits & CTRL) !== 0 };
53
+ }
54
+ const scalar = (cp) => Number.isInteger(cp) && cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff);
55
+
56
+ /** The key id a chord keeps under the protocol, the chords' spelling (packages/client/keymap.mjs:
57
+ * `ctrl+alt+k`, `ctrl+alt+shift+e`, `ctrl+alt+1`, `ctrl+shift+k`): Ctrl and Alt held, and a base
58
+ * key (`code`, the key unshifted) that is an ASCII letter, with or without Shift, or a digit 1 to 9
59
+ * without it; or Ctrl and Shift held without Alt, and an ASCII letter (the Ctrl+Shift family:
60
+ * a digit with Shift is a shifted symbol, and no row has one). Null for every other key, which is
61
+ * read as its legacy bytes are: a key that types a character that is not ASCII (an AltGr
62
+ * composition on a layout where AltGr is Ctrl+Alt: `€`, `ą`) is never a chord, whatever its
63
+ * modifiers. An id is a chord only where the TUI binds it (term/keys.mjs and term/through.mjs look
64
+ * it up in their `chords`): an unbound Ctrl+Shift letter, every one under the default family, is
65
+ * read and typed as its legacy bytes, Ctrl and the letter, as before. */
66
+ export function kittyId(key) {
67
+ if (key === null || !key.ctrl) return null;
68
+ const { code } = key, letter = code >= 0x61 && code <= 0x7a;
69
+ if (!key.alt) return letter && key.shift ? `ctrl+shift+${String.fromCharCode(code)}` : null;
70
+ if (letter) return `ctrl+alt+${key.shift ? "shift+" : ""}${String.fromCharCode(code)}`;
71
+ return code >= 0x31 && code <= 0x39 && !key.shift ? `ctrl+alt+${String.fromCharCode(code)}` : null;
72
+ }
73
+
74
+ /** The chords whose key has a sequence of its own without the protocol, and keeps it under it:
75
+ * Alt+Shift with an arrow, `CSI 1 ; 4 <final>` (xterm's modifier 4, Alt and Shift), key id -> final.
76
+ * They are read with the protocol or without it, in the list (term/keys.mjs reads the sequence as
77
+ * the key) and in a terminal (term/through.mjs). Ctrl+Alt+Shift with an arrow (`CSI 1 ; 8 A`) is
78
+ * another key, and no chord. */
79
+ export const LEGACY_CHORDS = Object.freeze({ __proto__: null, "alt+shift+up": "A", "alt+shift+down": "B", "alt+shift+right": "C", "alt+shift+left": "D" });
80
+ /** Whether the chord key id `id` is read without the protocol too (LEGACY_CHORDS). */
81
+ export const legacyChord = (id) => typeof id === "string" && Object.hasOwn(LEGACY_CHORDS, id);
82
+
83
+ const ESC = 0x1b;
84
+ /** The functional keys of the protocol's private-use range the TUI forwards: the keypad, as the key
85
+ * each one is without the protocol. Every other code of that range (F13 and above, the media keys,
86
+ * the lock and modifier keys, Menu) is a key a legacy terminal sends no bytes of its own for, or the
87
+ * TUI reads as no key: nothing. */
88
+ const KEYPAD = Object.freeze({
89
+ __proto__: null,
90
+ 57399: "0", 57400: "1", 57401: "2", 57402: "3", 57403: "4", 57404: "5", 57405: "6", 57406: "7", 57407: "8", 57408: "9",
91
+ 57409: ".", 57410: "/", 57411: "*", 57412: "-", 57413: "+", 57414: "enter", 57415: "=", 57416: ",",
92
+ 57417: "left", 57418: "right", 57419: "up", 57420: "down", 57421: "pageup", 57422: "pagedown",
93
+ 57423: "home", 57424: "end", 57425: "insert", 57426: "delete", 57427: "begin",
94
+ });
95
+ const PRIVATE_FIRST = 57344, PRIVATE_LAST = 63743;
96
+ /** The legacy form of a named key: `CSI <final>` / `CSI 1 ; m <final>`, or `CSI n ~` / `CSI n ; m ~`. */
97
+ const LETTER = Object.freeze({ __proto__: null, up: "A", down: "B", right: "C", left: "D", home: "H", end: "F", begin: "E" });
98
+ const TILDE = Object.freeze({ __proto__: null, insert: 2, delete: 3, pageup: 5, pagedown: 6 });
99
+
100
+ /** Shift on the 21 keys of the US layout that are not letters: the character it makes there. Only
101
+ * where flag 4 is not confirmed (the terminal answered flag 1 alone), and then it is the one limit
102
+ * of the rule that what is typed into an agent is the bytes of the same key without the protocol:
103
+ * on another layout Shift makes another character (docs/tui.md, "Chords"). */
104
+ export const US_SHIFTED = Object.freeze({
105
+ __proto__: null,
106
+ "`": "~", 1: "!", 2: "@", 3: "#", 4: "$", 5: "%", 6: "^", 7: "&", 8: "*", 9: "(", 0: ")",
107
+ "-": "_", "=": "+", "[": "{", "]": "}", "\\": "|", ";": ":", "'": "\"", ",": "<", ".": ">", "/": "?",
108
+ });
109
+
110
+ /** Ctrl with a character, as a legacy terminal sends it: the letters and `@ [ \ ] ^ _` (and `?`,
111
+ * `~`, Space, and the digits 2 to 8, which a terminal maps as xterm does) as their C0 byte or DEL;
112
+ * every other character as itself. */
113
+ function ctrlByte(ch) {
114
+ const c = ch.codePointAt(0);
115
+ if ((c >= 0x61 && c <= 0x7a) || (c >= 0x40 && c <= 0x5f)) return c & 0x1f;
116
+ const mapped = { " ": 0, 2: 0, 3: 0x1b, 4: 0x1c, 5: 0x1d, 6: 0x1e, 7: 0x1f, 8: 0x7f, "/": 0x1f, "?": 0x7f, "~": 0x1e }[ch];
117
+ return mapped ?? null;
118
+ }
119
+
120
+ /** A string's UTF-8 bytes. Its code points are Unicode scalars (kittyKey), so no surrogate is met. */
121
+ function utf8(text) {
122
+ const bytes = [];
123
+ for (const ch of text) {
124
+ const c = ch.codePointAt(0);
125
+ if (c < 0x80) bytes.push(c);
126
+ else if (c < 0x800) bytes.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f));
127
+ else if (c < 0x10000) bytes.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
128
+ else bytes.push(0xf0 | (c >> 18), 0x80 | ((c >> 12) & 0x3f), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
129
+ }
130
+ return bytes;
131
+ }
132
+ const csi = (rest) => [ESC, 0x5b, ...Array.from(rest, (c) => c.charCodeAt(0))];
133
+
134
+ /** The character Shift makes on `code`: the alternate key flag 4 reported (only while Shift is held:
135
+ * `shifted` is read only then), else a letter's capital, else, with flag 4 not confirmed, the US
136
+ * layout's (US_SHIFTED), else the character itself. */
137
+ function shiftedText(key, flags) {
138
+ const ch = String.fromCodePoint(key.code);
139
+ if (!key.shift) return ch;
140
+ if (key.shifted !== null && (flags & ALTERNATE_KEYS) !== 0) return String.fromCodePoint(key.shifted);
141
+ const upper = ch.toUpperCase();
142
+ if (upper !== ch && [...upper].length === 1) return upper;
143
+ return (flags & ALTERNATE_KEYS) === 0 ? US_SHIFTED[ch] ?? ch : ch;
144
+ }
145
+
146
+ /** The bytes the key `key` (kittyKey's) sends WITHOUT the protocol, the legacy encoding of xterm and
147
+ * of the terminals that follow it, as a Uint8Array; null for a key that sends none. `flags` are the
148
+ * confirmed ones: with flag 4, Shift's character is the one the terminal reported.
149
+ * Esc ESC; Enter CR; Tab TAB, with Shift `CSI Z`; Backspace DEL, with Ctrl BS; Space SP, with Ctrl
150
+ * NUL; a character with Shift its shifted character, with Ctrl its C0 byte (ctrlByte); a keypad key
151
+ * as the key it is; Alt puts ESC before any of these, but for a character that is not ASCII with
152
+ * Ctrl and Alt both, AltGr's on a layout where AltGr is Ctrl+Alt: the character alone. The
153
+ * arrows, Home, End, Insert, Delete, PageUp, PageDown and Begin are `CSI` forms with the modifier
154
+ * as their parameter (1 + Shift 1 + Alt 2 + Ctrl 4), as xterm sends them. */
155
+ export function legacyBytes(key, flags) {
156
+ if (key === null) return null;
157
+ let { code } = key;
158
+ if (code >= PRIVATE_FIRST && code <= PRIVATE_LAST) {
159
+ const pad = KEYPAD[code];
160
+ if (pad === undefined) return null;
161
+ if (pad === "enter") code = 13;
162
+ else if (pad.length === 1) code = pad.codePointAt(0);
163
+ else {
164
+ const m = 1 + (key.shift ? SHIFT : 0) + (key.alt ? ALT : 0) + (key.ctrl ? CTRL : 0);
165
+ const bytes = pad in LETTER ? csi(m === 1 ? LETTER[pad] : `1;${m}${LETTER[pad]}`) : csi(m === 1 ? `${TILDE[pad]}~` : `${TILDE[pad]};${m}~`);
166
+ return Uint8Array.from(bytes);
167
+ }
168
+ key = { ...key, code, shifted: null, shift: false, ctrl: false }; // the keypad's own character, which Shift and Ctrl leave as it is
169
+ }
170
+ let bytes;
171
+ if (code === 27) bytes = [ESC];
172
+ else if (code === 13) bytes = [0x0d];
173
+ else if (code === 9) bytes = key.shift ? csi("Z") : [0x09];
174
+ else if (code === 127 || code === 8) bytes = [key.ctrl ? 0x08 : 0x7f];
175
+ else if (code === 32) bytes = [key.ctrl ? 0x00 : 0x20];
176
+ else if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return null;
177
+ else {
178
+ const text = shiftedText(key, flags);
179
+ // AltGr where it is Ctrl+Alt (Windows): a character that is not ASCII typed with both is the
180
+ // layout's character (`€`, `ą`), and a terminal without the protocol sends it alone.
181
+ if (key.ctrl && key.alt && code > 0x7f) return Uint8Array.from(utf8(text));
182
+ const byte = key.ctrl ? ctrlByte(text) : null;
183
+ bytes = byte === null ? utf8(text) : [byte];
184
+ }
185
+ return Uint8Array.from(key.alt ? [ESC, ...bytes] : bytes);
186
+ }
187
+
188
+ /** The finals of the keys a terminal sends in the legacy shapes under the protocol: `CSI 1 ; m X`
189
+ * (the arrows, Home, End, Begin, F1 to F4) and `CSI n ; m ~`. Not `R`: under the protocol F3 is
190
+ * `CSI 13 ~`, and `CSI row ; col R` is a cursor report, which stays no key. */
191
+ const KEY_FINALS = "ABCDEFHPQS~";
192
+ /** The parameters of such a key with the protocol's modifier made xterm's: the protocol reports the
193
+ * lock keys and Super, Hyper and Meta in the modifier (Up with Caps Lock is `CSI 1 ; 65 A`), where
194
+ * a terminal without it sends the key as it is without them (`CSI A`). Shift, Alt and Ctrl stay;
195
+ * a modifier of none is left out, with the `1` before a letter (`CSI 1 ; 69 A` is `CSI 1 ; 5 A`,
196
+ * `CSI 15 ; 65 ~` is `CSI 15 ~`). Every other sequence's parameters are answered as they are. */
197
+ export function legacyParams(params, final) {
198
+ const match = typeof params === "string" && final.length === 1 && KEY_FINALS.includes(final) ? /^(\d*);(\d{1,3})$/.exec(params) : null;
199
+ if (!match) return params;
200
+ const m = Number(match[2]);
201
+ if (!(m >= 1 && m <= 256)) return params;
202
+ const bits = (m - 1) & (SHIFT | ALT | CTRL);
203
+ if (bits !== 0) return `${match[1]};${bits + 1}`;
204
+ if (final === "~") return match[1];
205
+ return match[1] === "" || match[1] === "1" ? "" : params;
206
+ }
207
+
208
+ /** A complete `CSI` sequence other than a `u` key, as a terminal sends it under the protocol, made
209
+ * the bytes it is without it: its modifier made xterm's (legacyParams); F1, F2 and F4 unmodified
210
+ * come as `CSI P`, `CSI Q`, `CSI S` (legacy `SS3 P`, `SS3 Q`, `SS3 S`), and F3 as `CSI 13 ~` (legacy
211
+ * `SS3 R`, and `CSI 1 ; m R` with a modifier). Every other sequence is the same bytes. `params` are
212
+ * the bytes between `CSI` and `final`. */
213
+ export function legacySequence(given, final) {
214
+ const params = legacyParams(given, final);
215
+ const ss3 = (letter) => Uint8Array.of(ESC, 0x4f, letter.charCodeAt(0));
216
+ if ((params === "" || params === "1" || params === "1;1") && "PQS".includes(final) && final !== "") return ss3(final);
217
+ if (final === "~") {
218
+ if (params === "13" || params === "13;1") return ss3("R");
219
+ const modified = /^13;(\d{1,3})$/.exec(params);
220
+ if (modified) return Uint8Array.from(csi(`1;${modified[1]}R`));
221
+ }
222
+ return Uint8Array.from(csi(`${params}${final}`));
223
+ }