@awebai/oats 0.66.0 → 0.68.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 (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
@@ -8,7 +8,7 @@
8
8
  * a paste { paste } or { paste: "", truncated: true }
9
9
  * an answer { keyboard: flags }: the terminal's answer to the protocol's query (`CSI ? flags u`),
10
10
  * while the parser waits for one */
11
- import { confirmed, kittyId, kittyKey, legacyBytes, legacyParams } from "./kitty.mjs";
11
+ import { confirmed, kittyId, kittyKey, legacyBytes, legacyChord, legacyParams } from "./kitty.mjs";
12
12
 
13
13
  export const ESC_TIMEOUT_MS = 50;
14
14
  export const PASTE_LIMIT = 1024 * 1024;
@@ -43,7 +43,7 @@ const named = (name, ctrl = false, alt = false, shift = false) => ({ name, ctrl,
43
43
  const CTRL_PUNCTUATION = "\\]^_";
44
44
 
45
45
  /** The key of a C0 byte or DEL, or null for a byte that is no key (NUL). 0x1c..0x1f are Control
46
- * 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"). */
47
47
  function c0Key(b) {
48
48
  if (b === 0x0d || b === 0x0a) return named("enter");
49
49
  if (b === 0x09) return named("tab");
@@ -144,7 +144,17 @@ export function legacyEvents(bytes) {
144
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
145
  * after it are read as it says: with flag 1 under the protocol, else as before. Under the protocol
146
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 as its own key id (`ctrl+shift+k`). An answer
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
148
158
  * at any other time is dropped, as is a `u` key while not under the protocol. Under it a key in a
149
159
  * legacy shape has its modifier made xterm's (term/kitty.mjs legacyParams: the lock keys dropped),
150
160
  * and nothing is timed: a terminal under the protocol sends no lone ESC for a key, so an ESC, like
@@ -164,7 +174,7 @@ export function legacyEvents(bytes) {
164
174
  * giveUp() the answer is no longer awaited (none came in time): a late one is dropped, and
165
175
  * the events of what was kept for it are answered.
166
176
  * keyboard the protocol as it is now: null, "asking" or the confirmed flags. */
167
- export function createKeyParser({ now, keyboard = null, chords = NO_CHORDS, answerBy = null } = {}) {
177
+ export function createKeyParser({ now, keyboard = null, chords = NO_CHORDS, leader = null, answerBy = null } = {}) {
168
178
  if (typeof now !== "function") throw new TypeError("createKeyParser needs an injected clock: { now: () => milliseconds }");
169
179
  if (!(keyboard === null || keyboard === "asking" || confirmed(keyboard))) throw new TypeError("keyboard is null, \"asking\" or flags that hold flag 1");
170
180
  if (!(chords instanceof Map)) throw new TypeError("chords is a Map of key ids");
@@ -282,10 +292,16 @@ export function createKeyParser({ now, keyboard = null, chords = NO_CHORDS, answ
282
292
  const key = kb === null || kb === "asking" ? null : kittyKey(seq);
283
293
  if (key === null) { flush(); return; }
284
294
  const id = kittyId(key);
285
- if (id !== null && chords.has(id)) { emit(named(key.code === 9 ? "tab" : String.fromCharCode(key.code), true, key.alt, key.shift)); return; }
295
+ if (id !== null && chords.has(id)) { emit(named(String.fromCharCode(key.code), key.ctrl, key.alt, key.shift)); return; }
286
296
  const bytes = legacyBytes(key, kb);
287
297
  if (bytes === null) { flush(); return; }
288
- for (const event of legacyEvents(bytes)) emit(event);
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) or as a chord of the family in force (Ctrl+Alt+1 is ESC 1, as Alt+1) is its own key,
301
+ // which nothing binds: never the leader, nor that chord.
302
+ const as = id !== null && events.length === 1 ? keyId(events[0]) : null;
303
+ if (as !== null && ((leader !== null && as === leader) || (legacyChord(as) && chords.has(as)))) { emit(named(String.fromCharCode(key.code), key.ctrl, key.alt, key.shift)); return; }
304
+ for (const event of events) emit(event);
289
305
  };
290
306
 
291
307
  const endPaste = (truncated) => {
@@ -11,9 +11,13 @@
11
11
  * Backspace alone, the arrows, the function keys) keeps the bytes it has without it.
12
12
  *
13
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), which keep their own key id (`ctrl+shift+k`), and the exact
15
- * Alt and Esc above. What it types into an agent is those legacy bytes (`legacyBytes`), so the
16
- * agent's program gets what it gets without the protocol. */
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 family's
19
+ * chords need no exception: an Alt arrow's legacy sequence is its own, and Alt with a letter or a
20
+ * digit is ESC and the character (legacyChordText). */
17
21
 
18
22
  /** The flags pushed (`CSI > flags u`): 1, disambiguate the escape codes, and 4, report alternate
19
23
  * keys, so the shifted key a key with Shift makes on the person's layout comes with it. The
@@ -50,15 +54,50 @@ export function kittyKey(params) {
50
54
  }
51
55
  const scalar = (cp) => Number.isInteger(cp) && cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff);
52
56
 
53
- /** The key id a key held with Ctrl keeps under the protocol, the chords' spelling
54
- * (packages/client/keymap.mjs: `ctrl+shift+k`, `ctrl+tab`): Ctrl, Alt and Shift, in that order,
55
- * then a letter or Tab. Null for every other key: those are read as their legacy bytes are. */
57
+ /** The key id a chord keeps under the protocol, the chords' spelling (packages/client/keymap.mjs:
58
+ * `ctrl+alt+k`, `ctrl+alt+shift+e`, `ctrl+alt+1`, `ctrl+shift+k`): Ctrl and Alt held, and a base
59
+ * key (`code`, the key unshifted) that is an ASCII letter, with or without Shift, or a digit 1 to 9
60
+ * without it; or Ctrl and Shift held without Alt, and an ASCII letter (the Ctrl+Shift family:
61
+ * a digit with Shift is a shifted symbol, and no row has one). Null for every other key, which is
62
+ * read as its legacy bytes are: a key that types a character that is not ASCII (an AltGr
63
+ * composition on a layout where AltGr is Ctrl+Alt: `€`, `ą`) is never a chord, whatever its
64
+ * modifiers. An id is a chord only where the TUI binds it (term/keys.mjs and term/through.mjs look
65
+ * it up in their `chords`): an unbound Ctrl+Shift letter, every one under the default family, is
66
+ * read and typed as its legacy bytes, Ctrl and the letter, as before. */
56
67
  export function kittyId(key) {
57
68
  if (key === null || !key.ctrl) return null;
58
- const name = key.code === 9 ? "tab" : key.code >= 0x61 && key.code <= 0x7a ? String.fromCharCode(key.code) : null;
59
- return name === null ? null : `ctrl+${key.alt ? "alt+" : ""}${key.shift ? "shift+" : ""}${name}`;
69
+ const { code } = key, letter = code >= 0x61 && code <= 0x7a;
70
+ if (!key.alt) return letter && key.shift ? `ctrl+shift+${String.fromCharCode(code)}` : null;
71
+ if (letter) return `ctrl+alt+${key.shift ? "shift+" : ""}${String.fromCharCode(code)}`;
72
+ return code >= 0x31 && code <= 0x39 && !key.shift ? `ctrl+alt+${String.fromCharCode(code)}` : null;
60
73
  }
61
74
 
75
+ /** The arrow chords, whose key has a sequence of its own without the protocol and keeps it under
76
+ * it: Alt with an arrow, `CSI 1 ; 3 <final>` (xterm's modifier 3), and Alt+Shift with one,
77
+ * `CSI 1 ; 4 <final>`; key id -> the bytes after `CSI`. Ctrl+Alt+Shift with an arrow (`CSI 1 ; 8 A`)
78
+ * is another key, and no chord. */
79
+ export const LEGACY_CHORDS = Object.freeze({
80
+ __proto__: null,
81
+ "alt+up": "1;3A", "alt+down": "1;3B", "alt+right": "1;3C", "alt+left": "1;3D",
82
+ "alt+shift+up": "1;4A", "alt+shift+down": "1;4B", "alt+shift+right": "1;4C", "alt+shift+left": "1;4D",
83
+ });
84
+ /** Alt with an ASCII letter or digit, as the TUI spells it: `alt+k`, and `alt+E` for Alt+Shift+E,
85
+ * which a terminal sends as ESC and the capital (term/keys.mjs reads it so). */
86
+ const ALT_CHARACTER = /^alt\+([a-zA-Z0-9])$/;
87
+ /** The bytes after ESC that the chord key id `id` is without the protocol, as text, or null when it
88
+ * has none of its own: an arrow chord's `[` and its sequence (LEGACY_CHORDS), or the character of
89
+ * Alt with a letter or a digit. Every terminal sends these, with the protocol or without it (under
90
+ * it the protocol's event for Alt+K reads as its legacy bytes, ESC `k`), so they are read in the
91
+ * list (term/keys.mjs reads them as the key) and in a terminal (term/through.mjs) either way. A
92
+ * Ctrl+Alt or Ctrl+Shift chord has none: it is read from the protocol's event alone (kittyId). */
93
+ export function legacyChordText(id) {
94
+ if (typeof id !== "string") return null;
95
+ if (Object.hasOwn(LEGACY_CHORDS, id)) return `[${LEGACY_CHORDS[id]}`;
96
+ return ALT_CHARACTER.exec(id)?.[1] ?? null;
97
+ }
98
+ /** Whether the chord key id `id` is read without the protocol too (legacyChordText). */
99
+ export const legacyChord = (id) => legacyChordText(id) !== null;
100
+
62
101
  const ESC = 0x1b;
63
102
  /** The functional keys of the protocol's private-use range the TUI forwards: the keypad, as the key
64
103
  * each one is without the protocol. Every other code of that range (F13 and above, the media keys,
@@ -127,9 +166,10 @@ function shiftedText(key, flags) {
127
166
  * confirmed ones: with flag 4, Shift's character is the one the terminal reported.
128
167
  * Esc ESC; Enter CR; Tab TAB, with Shift `CSI Z`; Backspace DEL, with Ctrl BS; Space SP, with Ctrl
129
168
  * NUL; a character with Shift its shifted character, with Ctrl its C0 byte (ctrlByte); a keypad key
130
- * as the key it is; Alt puts ESC before any of these. The arrows, Home, End, Insert, Delete,
131
- * PageUp, PageDown and Begin are `CSI` forms with the modifier as their parameter (1 + Shift 1 +
132
- * Alt 2 + Ctrl 4), as xterm sends them. */
169
+ * as the key it is; Alt puts ESC before any of these, but for a character that is not ASCII with
170
+ * Ctrl and Alt both, AltGr's on a layout where AltGr is Ctrl+Alt: the character alone. The
171
+ * arrows, Home, End, Insert, Delete, PageUp, PageDown and Begin are `CSI` forms with the modifier
172
+ * as their parameter (1 + Shift 1 + Alt 2 + Ctrl 4), as xterm sends them. */
133
173
  export function legacyBytes(key, flags) {
134
174
  if (key === null) return null;
135
175
  let { code } = key;
@@ -154,6 +194,9 @@ export function legacyBytes(key, flags) {
154
194
  else if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return null;
155
195
  else {
156
196
  const text = shiftedText(key, flags);
197
+ // AltGr where it is Ctrl+Alt (Windows): a character that is not ASCII typed with both is the
198
+ // layout's character (`€`, `ą`), and a terminal without the protocol sends it alone.
199
+ if (key.ctrl && key.alt && code > 0x7f) return Uint8Array.from(utf8(text));
157
200
  const byte = key.ctrl ? ctrlByte(text) : null;
158
201
  bytes = byte === null ? utf8(text) : [byte];
159
202
  }
@@ -50,6 +50,9 @@ export function glyphs(env, { ascii = false } = {}) {
50
50
  * `rows[r]` is the spans of row r, drawn in order, a later one over an earlier one:
51
51
  * `{ col, text, style?, width? }`, `text` safe text, `width` the cells the span may take (default:
52
52
  * to the right edge); or a fill, `{ col, width, style? }`, `width` blank cells in that style.
53
+ * A text span with `after: true` follows the text span drawn just before it: it is drawn that
54
+ * many cells to the left of `col` as that span left blank of its width, because its text was cut
55
+ * or a character of it drew narrower than counted (a mark right after a name: views/workspaces.mjs).
53
56
  * `cells(rows, size)` answers the same frame as cells and writes nothing: `{ text, width, style }`
54
57
  * per cell, the second cell of a two-cell grapheme with `width: 0`. */
55
58
  export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {}) {
@@ -66,10 +69,14 @@ export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {})
66
69
  else if (line[x].width === 2) line[x + 1] = BLANK;
67
70
  line[x] = BLANK;
68
71
  }
69
- function place(line, span) {
70
- const { col, style = PLAIN } = span;
72
+ /** Draws one span on a line and answers the cells a text span left blank of its width (0 for
73
+ * a fill and for a span with no width), which the next span pulls back over when it is drawn
74
+ * `after` it. */
75
+ function place(line, span, left = 0) {
76
+ const { style = PLAIN } = span;
71
77
  if (!isStyle(style)) throw new TypeError("a span's style is a style value: make one with style()");
72
- if (!Number.isInteger(col) || col < 0) throw new RangeError("a span's column is a cell index from 0");
78
+ if (!Number.isInteger(span.col) || span.col < 0) throw new RangeError("a span's column is a cell index from 0");
79
+ const col = span.after === true ? Math.max(0, span.col - left) : span.col;
73
80
  const limit = span.width === undefined ? line.length : Math.min(line.length, col + span.width);
74
81
  // A fill: no text, a width. Blank cells in the span's style, which is how a bar is drawn
75
82
  // (a selected row in reverse video): text.mjs rightly makes no text of a run of spaces.
@@ -78,10 +85,10 @@ export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {})
78
85
  if (!Number.isInteger(span.width) || span.width < 0) throw new RangeError("a fill has a width in cells");
79
86
  const blank = cell(" ", 1, style);
80
87
  for (let x = col; x < limit; x++) { clear(line, x); line[x] = blank; }
81
- return;
88
+ return 0;
82
89
  }
83
90
  const source = textOf(span.text);
84
- if (col >= limit) return;
91
+ if (col >= limit) return 0;
85
92
  let drawn = cells(source);
86
93
  // A terminal that is not reading UTF-8 would show each byte of a character on its own.
87
94
  if (!utf8) drawn = drawn.map((g) => (PRINTABLE_ASCII.test(g.text) ? g : { text: "?", width: 1 }));
@@ -100,11 +107,13 @@ export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {})
100
107
  line[x] = cell(g.text, g.width, style);
101
108
  x += g.width;
102
109
  }
110
+ return span.width === undefined ? 0 : limit - x;
103
111
  }
104
112
  function layout(rows, size) {
105
113
  return Array.from({ length: size.rows }, (_, r) => {
106
114
  const line = Array.from({ length: size.cols }, () => BLANK);
107
- for (const span of rows[r] ?? []) place(line, span);
115
+ let left = 0;
116
+ for (const span of rows[r] ?? []) left = place(line, span, left);
108
117
  return line;
109
118
  });
110
119
  }
@@ -1,22 +1,24 @@
1
1
  // What is typed through to an agent's terminal (docs/tui.md, "Open an agent's terminal"). While
2
2
  // a terminal has the focus the TUI reads no keys: the bytes the outer terminal sends go to the
3
- // agent exactly as they came, and the scanner here looks for two things only, the back key's own
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). 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.
3
+ // agent exactly as they came, and the scanner here looks for three things only: the back key's own
4
+ // bytes (which take the focus back to the list), a bracketed paste (which goes to the agent as a
5
+ // paste, so a back key inside it is pasted, not taken) and the chords (docs/tui.md, "Chords"): the
6
+ // Alt family's (Alt with a letter, a digit or an arrow) and the Alt+Shift arrows in every state, and
7
+ // under the kitty keyboard protocol the Ctrl+Alt ones too (or, when keys.json chose that family, the
8
+ // Ctrl+Shift ones), every other key then typed as the bytes it sends without the protocol (see createThrough). Pure:
9
+ // no IO; the clock is injected.
8
10
  //
9
11
  // The back key is tui.json's `open.detachKey`. Its grammar is THE TUI'S OWN: the keys it can take
10
12
  // back from a terminal and name in the cheat sheet. It began as the kernel's `--detach-key` grammar
11
13
  // (lib/session-viewer.mjs) and keeps its set and its spelling, so a tui.json written for PR 4 means
12
14
  // the same key; it is not tied to the kernel's, which never sees this key any more.
13
15
  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";
16
+ import { confirmed, kittyId, kittyKey, legacyBytes, legacyChord, legacyChordText, legacySequence } from "./kitty.mjs";
15
17
 
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
18
+ /** How long bytes held only as a beginning of the back key (or of a chord's own bytes, see
19
+ * createThrough) wait for the rest of it, in milliseconds: the back key counts only as ONE
20
+ * keypress (a terminal writes a key's bytes at once; a split read of them comes within this), so
21
+ * Esc and then `o` typed as two keys reach the agent as they were typed, and never as M-o. Bytes that may begin a paste's start marker wait
20
22
  * the key parser's Esc timeout (ESC_TIMEOUT_MS) instead, as before. */
21
23
  export const BACK_KEY_SPLIT_MS = 10;
22
24
 
@@ -104,33 +106,55 @@ const decoder = () => new TextDecoder("utf-8", { fatal: false });
104
106
  * the agent's, and `rest` hands it on) or `{ chord: <does>, rest: <bytes> }` (a chord, the same).
105
107
  *
106
108
  * 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
109
+ * scanner reads every `CSI` sequence typed. A `u` key is a chord when its id (kittyId, a Ctrl+Alt or
110
+ * a Ctrl+Shift chord's) is one of `chords` (a Map of key id to the `does` it names), else the bytes it sends
111
+ * without the protocol (legacyBytes), which are the back key when they read as `leader` (the back
112
+ * key's key id, backKeyId) and the key has no id of its own (kittyId: Ctrl+Shift+X, whose legacy
113
+ * byte is Ctrl+X's, is typed, never the back key), with no timing: Alt+O is one sequence and Esc is another. Any other sequence is
111
114
  * the same, made legacy where the protocol changed it (legacySequence: the modifier, F1 to F4).
112
115
  * What is not a sequence goes to the agent as it came. Nothing is timed: a sequence a read ends
113
116
  * inside, or a lone ESC (which no key sends under the protocol), waits for the next read however
114
117
  * 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
118
+ * A Ctrl+Shift chord is read only so, from its event's Shift bit: a Ctrl+Shift letter that is not
119
+ * among `chords` (every one under the default family) is typed as Ctrl and the letter
120
+ * (`CSI 100;6u` is 0x04, the agent's Ctrl+D), and a C0 byte typed is never a chord.
121
+ * The legacy bytes are read as the key they are: a chord among `chords` with bytes of its own
122
+ * (term/kitty.mjs legacyChordText: Alt with a letter, a digit or an arrow, an Alt+Shift arrow) is
123
+ * the chord however the protocol reports the lock keys in its modifier (legacyParams: `CSI 1 ; 68 A`
124
+ * with Caps Lock is `CSI 1 ; 4 A`), and so is a keypad arrow whose legacy bytes are that sequence;
125
+ * Alt+K, `CSI 107 ; 3 u`, is ESC `k`.
126
+ * Without it (`keyboard` null or "asking") no `CSI u` key is read and no key is made legacy, and
127
+ * what follows holds. While
116
128
  * "asking", the answer may arrive split across reads, and over a slow link late: a read that ends
117
129
  * in what may begin it (ESC, `ESC [`, `ESC [ ?` and digits) is held until `answerBy` (the clock time
118
130
  * the run stops waiting for it), at least the key parser's Esc timeout. A later read that does not
119
131
  * go on with the answer comes after them: within BACK_KEY_SPLIT_MS joined to them as before (the
120
132
  * back key, a paste), later handed on after them, as a key of its own, so they never make the back
121
133
  * key with it. giveUp() hands on what is held for the answer.
122
- * A read is never held back from the agent but for a beginning of the back key's own bytes, or of
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
127
- * its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
134
+ * A Control back key's byte right after ESC in a read is Ctrl+Alt with that key (ESC 0x18 is
135
+ * Ctrl+Alt+X), as the key parser reads it: the agent's, never the back key.
136
+ * The chords among `chords` with bytes of their own (legacyChordText) are taken as the back key
137
+ * is: those bytes exactly (ESC `k` for Alt+K, ESC `E` for Alt+Shift+E, `CSI 1 ; 3 A` for Alt+Up,
138
+ * `CSI 1 ; 4 A` for Alt+Shift+Up, nothing but Alt, and Shift, in the modifier), with what came after
139
+ * it in the read handed on as the rest. The back key's bytes come first: a back key M-k is the
140
+ * back key, never the chord Alt+K.
141
+ * A read is never held back from the agent but for a beginning of the back key's own bytes or of
142
+ * such a chord's, or of a paste's start marker from its third byte: those wait for the next read,
143
+ * or until `timeoutAt()` (BACK_KEY_SPLIT_MS for a key's alone, the key parser's Esc timeout when
144
+ * they may begin a paste) hands them on as input, through `expire()` or the first read that comes
145
+ * later, which then never completes the key with them. A chord is one keypress, as the back key
146
+ * is: its bytes split across reads within BACK_KEY_SPLIT_MS are the chord, and split further apart
147
+ * they reach the agent as they came, so Esc and then `k` typed as two keys are the agent's (its
148
+ * program reads them as M-k: the way to a key the Alt family takes), and a key of the agent's that
149
+ * begins as one does (Esc, `ESC [ 1`) waits no longer than that for its sake. A paste is held until its end marker; one that reaches PASTE_LIMIT is dropped whole, and one whose end has not come
128
150
  * when a read arrives PASTE_PAUSE_MS after the one before is given to the agent as what it held,
129
151
  * and that read is scanned anew, as the key parser abandons a stalled paste. */
130
152
  export function createThrough({ sequences, now, keyboard = null, leader = null, chords = new Map(), answerBy = null }) {
131
153
  if (typeof now !== "function") throw new TypeError("createThrough needs an injected clock: { now: () => milliseconds }");
132
154
  if (!(keyboard === null || keyboard === "asking" || confirmed(keyboard))) throw new TypeError("keyboard is null, \"asking\" or flags that hold flag 1");
133
155
  const keys = sequences.map((seq) => Uint8Array.from(seq));
156
+ /** The chords with bytes of their own, `[bytes, does]` (legacyChordText), read without the protocol. */
157
+ const owned = [...chords].filter(([id]) => legacyChord(id)).map(([id, does]) => [escaped(legacyChordText(id)), does]);
134
158
  let kb = keyboard;
135
159
  /** The bytes held for the next read, since when, and how long they may wait: BACK_KEY_SPLIT_MS
136
160
  * when they are held only as a beginning of the back key, ESC_TIMEOUT_MS when they may begin a
@@ -212,17 +236,25 @@ export function createThrough({ sequences, now, keyboard = null, leader = null,
212
236
  kb = confirmed(answer.flags) ? answer.flags : null;
213
237
  return scan(out, data.subarray(answer.end));
214
238
  }
215
- const key = keys.find((seq) => seq[0] === b && at(data, i, seq));
239
+ // A Control back key right after ESC is Ctrl+Alt with it (ESC 0x18 is Ctrl+Alt+X), never the
240
+ // back key: it goes to the agent as it came, as the key parser reads it as ctrl+alt+x.
241
+ const key = keys.find((seq) => seq[0] === b && at(data, i, seq) && !(seq.length === 1 && i > 0 && data[i - 1] === ESC));
216
242
  if (key) {
217
243
  if (i > 0) out.push({ input: data.subarray(0, i) });
218
244
  out.push({ back: true, rest: data.subarray(i + key.length) });
219
245
  return;
220
246
  }
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.
247
+ const chord = b === ESC ? owned.find(([seq]) => at(data, i, seq)) : undefined;
248
+ if (chord) {
249
+ if (i > 0) out.push({ input: data.subarray(0, i) });
250
+ out.push({ chord: chord[1], rest: data.subarray(i + chord[0].length) });
251
+ return;
252
+ }
253
+ // The read ends on what may be the beginning of the back key, of a chord's own bytes, of a
254
+ // paste or of the answer awaited: held, as long as the longest that it may begin allows.
223
255
  const pasting = data.length - i >= PASTE_HELD_FROM && begins(data, i, PASTE_START);
224
256
  const answering = kb === "asking" && answerBegins(data, i);
225
- const keying = keys.some((seq) => begins(data, i, seq));
257
+ const keying = keys.some((seq) => begins(data, i, seq)) || owned.some(([seq]) => begins(data, i, seq));
226
258
  if (pasting || answering || keying) {
227
259
  if (i > 0) out.push({ input: data.subarray(0, i) });
228
260
  held = Uint8Array.from(data.subarray(i));
@@ -260,16 +292,22 @@ export function createThrough({ sequences, now, keyboard = null, leader = null,
260
292
  handOn(i);
261
293
  from = end;
262
294
  i = end - 1;
263
- let bytes;
295
+ let bytes, own = null;
264
296
  if (final === "u") {
265
297
  if (/^\?\d{1,3}$/.test(params)) continue; // the protocol's answer again: never the agent's
266
298
  const key = kittyKey(params), id = kittyId(key);
267
299
  if (id !== null && chords.has(id)) { out.push({ chord: chords.get(id), rest: data.subarray(end) }); return; }
300
+ own = id;
268
301
  bytes = legacyBytes(key, kb);
269
302
  } else bytes = legacySequence(params, final);
270
303
  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; }
304
+ // What the bytes read as without the protocol: the back key, or a chord with bytes of its own. A
305
+ // key with an id of its own (kittyId: Ctrl+Shift or Ctrl+Alt with a letter or a digit) is never
306
+ // either, though its legacy bytes may read as one (Ctrl+Shift+X is 0x18, as Ctrl+X; Ctrl+Alt+1
307
+ // is ESC 1, as Alt+1, which the Alt family binds): it types them.
308
+ const events = legacyEvents(bytes), id = events.length === 1 ? keyId(events[0]) : null;
309
+ if (id !== null && id === leader && own === null) { out.push({ back: true, rest: data.subarray(end) }); return; }
310
+ if (own === null && legacyChord(id) && chords.has(id)) { out.push({ chord: chords.get(id), rest: data.subarray(end) }); return; }
273
311
  out.push({ input: bytes });
274
312
  }
275
313
  handOn(data.length);