@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.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- 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 \ ] ^ _ (
|
|
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 (
|
|
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(
|
|
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
|
-
|
|
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)
|
|
15
|
-
*
|
|
16
|
-
*
|
|
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
|
|
54
|
-
*
|
|
55
|
-
*
|
|
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
|
|
59
|
-
|
|
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
|
|
131
|
-
*
|
|
132
|
-
*
|
|
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
|
-
|
|
70
|
-
|
|
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
|
-
|
|
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
|
|
4
|
-
// bytes (which take the focus back to the list)
|
|
5
|
-
//
|
|
6
|
-
// (
|
|
7
|
-
//
|
|
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
|
|
17
|
-
* milliseconds: the back key counts only as ONE
|
|
18
|
-
* once; a split read of them comes within this), so
|
|
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
|
|
108
|
-
* (a Map of key id to the `does` it names), else the bytes it sends
|
|
109
|
-
* (legacyBytes), which are the back key when they read as `leader` (the back
|
|
110
|
-
* backKeyId)
|
|
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
|
-
*
|
|
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
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
*
|
|
127
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
222
|
-
|
|
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
|
-
|
|
272
|
-
|
|
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);
|