@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.
- package/README.md +11 -5
- package/bin/oats.mjs +74 -20
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +222 -10
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +16 -6
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.66.0.md +183 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +5 -4
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +658 -143
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +9 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/deployments.mjs +21 -5
- package/lib/instance-color.mjs +58 -0
- 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 +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- 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 +3 -1
- 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 +99 -11
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/machine-contract.mjs +1 -5
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +9 -8
- package/packages/tui/lib/actions.mjs +108 -64
- package/packages/tui/lib/client.mjs +8 -3
- package/packages/tui/lib/config.mjs +208 -26
- package/packages/tui/lib/main.mjs +91 -20
- package/packages/tui/lib/model.mjs +167 -61
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +156 -47
- package/packages/tui/lib/term/keys.mjs +150 -34
- package/packages/tui/lib/term/kitty.mjs +223 -0
- package/packages/tui/lib/term/through.mjs +174 -27
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +143 -21
- package/packages/tui/lib/views/instances.mjs +59 -20
- 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/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
|
|
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
|
|
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 \ ] ^ _ (
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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() <
|
|
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
|
|
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
|
|
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
|
+
}
|