@awebai/oats 0.66.0 → 0.67.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
@@ -9,10 +9,10 @@
9
9
  // removed, and nothing here decides what a failed read means or which view a deployment is in.
10
10
  // Selection is an identity (the shared `instanceId`), never an index, so it survives every read;
11
11
  // the rows it moves among are the model's, in drawn order.
12
- import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys } from "./actions.mjs";
13
- import { collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
12
+ import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
13
+ import { CHORDS, chordFamilyFrom, collapseKey, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
14
  import { defaultDetachKey } from "./config.mjs";
15
- import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, LIST_WORDS } from "./model.mjs";
15
+ import { BUTTON_ORDER, SPAWN_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, workspaceOf, LIST_WORDS } from "./model.mjs";
16
16
  import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
17
17
  import { windowOf } from "./views/scroll.mjs";
18
18
  import { SPLIT_MIN, splitFits } from "./views/split.mjs";
@@ -57,6 +57,10 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
57
57
  * (awebai/oats#1390): `rows`, the shared reader's `{ path, name, state }` in the kernel's order, of
58
58
  * the last read that answered, and `failure`, the reason (`{ code, message }`) the last read failed
59
59
  * with, or null once one answered. The switcher offers the rows this run does not serve.
60
+ * `identities`: what the identity reads learned of the rows of that list (lib/main.mjs), path ->
61
+ * `{ ok: true, workspace }` or `{ ok: false, reason }` (deployment-identity.mjs), the last answer for
62
+ * each, kept for the run: the switcher matches a listed deployment to its workspace by it, and a
63
+ * deployment opened from there is in its workspace's view before its first read (lib/model.mjs heldOf).
60
64
  * `opening`: the agent of another machine whose terminal is being opened, or null:
61
65
  * `{ id, phase: "preflight", name, machine, routed }` while that machine is asked whether its
62
66
  * session is there; `name`, `machine` and `routed` are the row's as it was when Enter was
@@ -78,14 +82,20 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
78
82
  * focus: see `drawsOutcome`), held until one is; or null.
79
83
  * It is the add of the deployment the run started in, refused.
80
84
  * `detachKey`: tui.json's `open.detachKey`, the leader (docs/tui.md, "The leader"; without one,
81
- * `platform`'s default, config.mjs defaultDetachKey), and `leaderKey` the key id it is read as
85
+ * the default, C-x on every platform: config.mjs defaultDetachKey), and `leaderKey` the key id it is read as
82
86
  * where the TUI reads keys (term/through.mjs backKeyId).
83
87
  * `leader`: `{ read, waiting }` from the leader's read on, or null (see `leading`).
84
88
  * `keyboard`: the flags the terminal confirmed for the kitty keyboard protocol (lib/main.mjs, the
85
89
  * event `{ keyboard }`), or null while it has not; `chords`: the chords of `platform`, key id ->
86
- * `does` (actions.mjs chordKeys), read only while `keyboard` is not null (see `leading`).
87
- * `palette`: the palette while it is open (see `paletteOpened`), or null. `recent`: the ids of
88
- * the instances opened in this run, the latest first.
90
+ * `does` (actions.mjs chordKeys), in the family keys.json chose, every one read while `keyboard`
91
+ * is not null, and the Alt+Shift arrows alone while it is null (actions.mjs chordsRead; see
92
+ * `leading`). `keysRead`: what keys.json said at the start (lib/config.mjs loadKeys, the shared
93
+ * reader's frozen `{ family, why }`; no file when none is given): the family `chords` are bound
94
+ * in, and why it is the default when the file did not choose it. The help names both.
95
+ * `palette`: the palette while it is open (see `paletteOpened`), or null; `paletteKeys` its own
96
+ * keys on `platform`, key id -> `does` (actions.mjs paletteKeys: none on macOS), which win over
97
+ * every other key while it is open. `recent`: the ids of the instances opened in this run, the
98
+ * latest first.
89
99
  * `act`: the confirmation open in the act view (see `actOpened`), or null; `acted` counts the
90
100
  * confirmations opened in this run, so an answer for one that was closed is told apart.
91
101
  * `starting`: id -> `{ verb, since }` of this run's starts and restarts whose child is still
@@ -103,7 +113,7 @@ const NO_CAPABILITIES = Object.freeze({ wanted: false, held: new Map(), selected
103
113
  * agentsRoot, agent, reads, words }`, until its row is opened or two reads did not show it;
104
114
  * `previews` the number of the last preview read asked in the run, so that an answer to a prompt
105
115
  * already closed is never taken by the next one. */
106
- export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform = process.platform, detachKey = defaultDetachKey(platform) }) {
116
+ export function initialState({ deployment = null, cli, home, entry = null, actions = ACTIONS, ascii = false, platform = process.platform, detachKey = defaultDetachKey(platform), keysRead = NO_KEYS_FILE }) {
107
117
  return Object.freeze({
108
118
  view: deployment === null ? "switcher" : "instances", back: deployment === null ? "switcher" : "instances",
109
119
  ctxs: Object.freeze(deployment === null ? [] : [deployment]), open: deployment,
@@ -112,15 +122,17 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
112
122
  memory: new Map(), notes: new Map(), collecting: false, cli, home,
113
123
  selected: null, collapsed: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(),
114
124
  switcher: NO_SWITCHER,
115
- listed: NO_LIST,
125
+ listed: NO_LIST, identities: new Map(),
116
126
  helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
117
- leaderKey: backKeyId(detachKey), leader: null, keyboard: null, chords: chordKeys(platform === "darwin", actions), palette: null, recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
127
+ leaderKey: backKeyId(detachKey), leader: null, keyboard: null, keysRead, chords: chordKeys(platform === "darwin", actions, CHORDS, keysRead.family), palette: null, paletteKeys: paletteKeys(platform === "darwin"), recent: Object.freeze([]), souls: NO_SOULS, capabilities: NO_CAPABILITIES,
118
128
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
119
129
  notice: null,
120
130
  });
121
131
  }
122
132
 
123
133
  const next = (state, changes) => Object.freeze({ ...state, ...changes });
134
+ /** keys.json's answer when the run read none (a test's state): no file, the default family. */
135
+ const NO_KEYS_FILE = chordFamilyFrom(null);
124
136
 
125
137
  /** The switcher's own: the filter, the selection and the scroll; `line`, what it says above its rows
126
138
  * of what happened (lib/model.mjs SWITCHER_LINES: "gone", or the answer of a Remove); `refused`,
@@ -198,7 +210,7 @@ function settled(state, taken) {
198
210
  const places = new Map(taken.places); places.delete(taken.open);
199
211
  // A confirmation open over that view is closed with it: what it sent goes on.
200
212
  const dismiss = taken.act !== null ? { dismiss: taken.act.n } : {};
201
- return { state: toSwitcher(next(taken, { open: null, places, selected: null, top: 0, loose: false, detailTop: 0, focus: "list", filter: NO_FILTER, back: "switcher", act: null }), "gone"), effect: { list: true, ...dismiss } };
213
+ return { state: toSwitcher(next(taken, { open: null, places, selected: null, top: 0, loose: false, detailTop: 0, focus: "list", filter: NO_FILTER, back: "switcher", act: null }), "gone"), effect: { list: true, identify: true, ...dismiss } };
202
214
  }
203
215
  const before = roster(state);
204
216
  const unknown = new Set([...taken.unread.values()].flatMap((ids) => [...ids]));
@@ -255,6 +267,50 @@ function admitted(state, { admitted: id, at }) {
255
267
  return opened(joined, id);
256
268
  }
257
269
 
270
+ /** The deployments of a workspace picked in the switcher that were on this computer's list and not served
271
+ * (lib/main.mjs asked each whether it is a deployment now): `admitted` are served from now on, pending
272
+ * until their first read, which the identity read already placed in their workspace's view; then the
273
+ * workspace opens on the first of `opens` (its deployments, this machine's first) that is served or is
274
+ * another machine's (the workspace already open stays open, its place and tabs kept). A folder refused is not served; when nothing of the workspace can be opened the
275
+ * switcher stays, and the list is read again, so its rows say what the folders are now. */
276
+ function joinedHeard(state, { admitted: ids, opens, at }) {
277
+ const added = ids.filter((id) => !state.ctxs.includes(id));
278
+ const entries = new Map(state.entries);
279
+ for (const id of added) entries.set(id, pendingEntry(null, at));
280
+ const joined = added.length ? next(state, { ctxs: Object.freeze([...state.ctxs, ...added]), entries }) : state;
281
+ const target = opens.find((id) => joined.ctxs.includes(id) || !id.startsWith("/")) ?? null;
282
+ if (target === null) return { state: joined, effect: { list: true } };
283
+ // The workspace already open (from another machine's deployment) stays where its list was, and keeps its tabs (reduceStep).
284
+ const same = state.open !== null && workspaceOf(joined, target) === workspaceOf(state, state.open);
285
+ const shown = opened(joined, target);
286
+ return { state: same ? next(shown, { selected: state.selected, top: state.top, detailTop: state.detailTop }) : shown, effect: { refresh: { live: true } } };
287
+ }
288
+
289
+ /** The deployments a choice of the switcher stands for: a workspace's, a listed row's path, an unmatched
290
+ * view's primary (lib/model.mjs switcher). */
291
+ const choiceDeployments = (item) => item.opens ?? [item.path ?? item.primary].filter(Boolean);
292
+
293
+ /** The switcher's selection after `after` changed its rows: kept while its choice is listed; else on the
294
+ * choice that now holds a deployment the selected one stood for (a listed row whose workspace a read
295
+ * learned is in that workspace's row from then on, and back on its own row when a later answer takes
296
+ * that away), so Enter opens what was selected. */
297
+ function reselected(before, after) {
298
+ const was = switcher(before);
299
+ if (was.selected === null) return after;
300
+ const now = switcher(after);
301
+ if (now.keys.includes(was.selected)) return after;
302
+ const ids = choiceDeployments(was.items.find((item) => item.key === was.selected));
303
+ const found = now.items.find((item) => item.key !== undefined && choiceDeployments(item).some((id) => ids.includes(id)));
304
+ return found ? next(after, { switcher: Object.freeze({ ...after.switcher, selected: found.key, loose: false }) }) : after;
305
+ }
306
+
307
+ /** What an identity read learned of a deployment of this computer's list (lib/main.mjs): kept for the run,
308
+ * the last answer for each path; an answer replaces the one before it. The switcher's selection
309
+ * follows the deployment it stood on (`reselected`). */
310
+ function identityHeard(state, { path, read }) {
311
+ return { state: reselected(state, next(state, { identities: new Map(state.identities).set(path, read) })), effect: null };
312
+ }
313
+
258
314
  /** The filter's text changed. */
259
315
  function queried(state, query) {
260
316
  if (query === state.filter.query) return state;
@@ -506,7 +562,7 @@ function switched(state, action, page, event) {
506
562
  // The rows of the pane the choices have: the lines above them take theirs, and the filter
507
563
  // field one while it is shown (lib/model.mjs switcherHeight).
508
564
  const count = s.items.length, height = switcherHeight(state, page, event.area);
509
- const drawn = windowOf({ top: sw.top, count, height, keep: sw.loose ? -1 : s.items.findIndex((item) => item.key !== undefined && item.key === s.selected) }).top;
565
+ const drawn = switcherWindow(s.items, sw.loose ? null : s.selected, { top: sw.top, height }).top;
510
566
  const from = Math.max(0, s.keys.indexOf(s.selected));
511
567
  const key = s.keys.length ? s.keys[Math.min(Math.max(0, moved(action, from, s.keys.length, page)), s.keys.length - 1)] : null;
512
568
  // No choice to go to in that direction (the first, the last, or none at all): the rows
@@ -515,15 +571,18 @@ function switched(state, action, page, event) {
515
571
  const top = windowOf({ top: moved(action, drawn, count, height), count, height }).top;
516
572
  return top === drawn ? stay : { state: put({ top, loose: true }), effect: null };
517
573
  }
518
- const at = s.items.findIndex((item) => item.key === key);
519
- // The headings above the first choice come into the pane with it, and what stands under the last one.
520
- const top = windowOf({ top: key === s.keys[0] ? 0 : key === s.keys.at(-1) ? count : drawn, count, height, keep: at }).top;
574
+ // The headings above the first choice come into the pane with it, and what stands under the last one;
575
+ // a workspace's indicator lines come in with it while they fit (lib/model.mjs switcherWindow).
576
+ const top = switcherWindow(s.items, key, { top: key === s.keys[0] ? 0 : key === s.keys.at(-1) ? count : drawn, height }).top;
521
577
  return { state: put({ selected: key, top, loose: false }), effect: null };
522
578
  }
523
579
  case "open": {
524
580
  const item = s.items.find((each) => each.key !== undefined && each.key === s.selected);
525
581
  if (!item) return stay;
526
582
  if (item.path !== undefined) return item.state === "ok" ? { state: put({ refused: null }), effect: { admit: item.path } } : stay;
583
+ // A workspace with deployments of this computer's list that this run does not serve: each is asked
584
+ // whether it is a deployment now, and served from then on (`joinedHeard`), before the workspace opens.
585
+ if (item.join?.length) return { state: put({ refused: null }), effect: { join: Object.freeze({ paths: item.join, opens: item.opens }) } };
527
586
  return item.primary === null ? stay : { state: opened(state, item.primary), effect: { refresh: { live: true } } };
528
587
  }
529
588
  case "remove": {
@@ -575,7 +634,10 @@ function removedHeard(state, { name, ok, reason = null }) {
575
634
  * (one outcome of the roster read), `{ collecting }`, `{ retiring: <Set of instanceIds> }` (this
576
635
  * run's retires in flight now), `{ listed: { rows } | { failure } }` (this computer's deployments
577
636
  * list read, or why it was not), `{ admitted: <deployment>, at }` and `{ refused: <path> }` (what a
578
- * picked row turned out to be), `{ removed: { path, name, ok, reason } }` (a Remove's answer) and
637
+ * picked row turned out to be), `{ joined: { admitted, opens }, at }` (which listed deployments of a
638
+ * workspace picked in the switcher are deployments now, and the ones it may open, in order),
639
+ * `{ identity: { path, read } }` (what an identity read answered of a row of the list),
640
+ * `{ removed: { path, name, ok, reason } }` (a Remove's answer) and
579
641
  * `{ notListed: <reason> }` (the deployment the run started in was not added to the list).
580
642
  * Opening an agent gives five more: `{ prepared: { id, error? } }` (the preflight of another
581
643
  * machine's agent ended: `error` is what the shared prepareRemoteTerm threw), `{ given: true }`
@@ -587,8 +649,10 @@ function removedHeard(state, { name, ok, reason = null }) {
587
649
  * `rest`: more bytes came after it in the same read).
588
650
  * An effect is something only the loop can do: "quit", "suspend", "redraw", or an object with
589
651
  * any of `refresh: { live }` (read now), `list: true` (read this computer's deployments list
590
- * again), `remove: { path, name }` (remove that row from it), `admit: <path>` (ask whether a picked
591
- * row is a deployment), `close: <id>` (close the open
652
+ * again; with `identify: true`, then read the identities of its rows this run does not serve),
653
+ * `remove: { path, name }` (remove that row from it), `admit: <path>` (ask whether a picked
654
+ * row is a deployment), `join: { paths, opens }` (ask that of each of a picked workspace's listed
655
+ * deployments, then answer `joined`), `close: <id>` (close the open
592
656
  * terminal; when an `open` comes with it, before that open), `open: <decision>` (open the agent's
593
657
  * terminal: the model's openDecision, with its target), `panel: <id>` (the preflight is over:
594
658
  * start the viewer it prepared in the panel) and `abandon: true` (give the preflight up); or null.
@@ -630,8 +694,11 @@ function reduceStep(state, event, keymap) {
630
694
  if (state.outcome !== null && typeof event.key === "string" && keymap.has(event.key)) state = next(state, { outcome: null });
631
695
  let step = reduced(state, event, keymap);
632
696
  // The tabs are the open workspace's: whatever opened another (or left it, gone), they all close,
633
- // and the split with them.
634
- if (step.state.open !== state.open && (step.state.tabs.length || step.state.split !== null)) {
697
+ // and the split with them. Another deployment of the same workspace opened (its deployment of this
698
+ // machine, once served, in place of another machine's) keeps them.
699
+ const moved = step.state.open !== state.open && (step.state.tabs.length || step.state.split !== null);
700
+ const was = moved && step.state.open !== null ? workspaceOf(state, state.open) : null;
701
+ if (moved && (was === null || workspaceOf(step.state, step.state.open) !== was)) {
635
702
  const ids = step.state.tabs.map((tab) => tab.id);
636
703
  step = { state: next(step.state, { tabs: Object.freeze([]), terminal: null, ...NO_SPLIT }), effect: ids.length ? both(step.effect, { close: ids }) : step.effect };
637
704
  }
@@ -740,17 +807,27 @@ function ungrouped(state, g, focus) {
740
807
  return showTab(one, left, { focus, zoom: false });
741
808
  }
742
809
 
743
- /** The tab before or after the shown one (`step` -1 or 1) in the focused group shown, without
744
- * wrapping and never into the other group: at either end
745
- * nothing moves, nor while a tab is still starting (it is the shown one until the panel has its
746
- * window). The focus stays where it was, and so does the zoom. */
747
- function tabStepped(state, step, { focus = state.terminal?.focus ?? "list", zoom = state.terminal?.zoom ?? false } = {}) {
810
+ /** The tab of the focused group that `pick` names, shown: `pick(count, at)` answers its place
811
+ * among the group's `count` tabs, `at` the shown one's. Never into the other group, and nothing
812
+ * moves when there is no such tab, when it is the shown one, or while a tab is still starting (it
813
+ * is the shown one until the panel has its window). The focus stays where it was, and so does
814
+ * the zoom. */
815
+ function tabPicked(state, pick, { focus = state.terminal?.focus ?? "list", zoom = state.terminal?.zoom ?? false } = {}) {
748
816
  const t = state.terminal;
749
817
  if (t === null || state.tabs.some((tab) => tab.status === "starting")) return { state, effect: null };
750
- const mine = inGroup(state, state.group), at = mine.findIndex((tab) => tab.id === t.id) + step;
751
- if (at < 0 || at >= mine.length) return { state, effect: null };
752
- return showTab(state, mine[at].id, { focus, zoom });
753
- }
818
+ const mine = inGroup(state, state.group), from = mine.findIndex((tab) => tab.id === t.id), to = pick(mine.length, from);
819
+ if (!(to >= 0 && to < mine.length) || to === from) return { state, effect: null };
820
+ return showTab(state, mine[to].id, { focus, zoom });
821
+ }
822
+ /** The tab each of these `does` shows (tabPicked): `tab-previous` and `tab-next` (the leader's Left
823
+ * and Right, the list's keys) the one before or after the shown one, without wrapping, and the
824
+ * chords' `tab-1` to `tab-8` (actions.mjs CHORD_OWN) the Nth, `tab-9` the last. */
825
+ const TAB_PICKS = Object.freeze({
826
+ __proto__: null,
827
+ "tab-previous": (count, at) => at - 1,
828
+ "tab-next": (count, at) => at + 1,
829
+ ...Object.fromEntries(Array.from({ length: 9 }, (_, i) => [`tab-${i + 1}`, i === 8 ? (count) => count - 1 : () => i])),
830
+ });
754
831
 
755
832
  /** The preflight of another machine's agent ended. Given up meanwhile (Esc, a suspend, a second
756
833
  * open): dropped. Failed: the line that says so, unless it is the person's own giving up. Else
@@ -1030,9 +1107,10 @@ function leading(state, event, keymap) {
1030
1107
  if (l !== null && l.waiting && !sameRead(l, event)) return twice(next(state, { leader: leaderAt(event.read, false) }));
1031
1108
  return { state: next(state, { leader: leaderAt(event.read, event.rest !== true) }), effect: null };
1032
1109
  }
1033
- // A chord typed in a terminal (term/through.mjs): the leader then its key, at once.
1110
+ // A chord typed in a terminal (term/through.mjs): the leader then its key, at once. Only one
1111
+ // that is read now (chordsRead): the scanner takes no other.
1034
1112
  if (event.chord !== undefined) {
1035
- if (state.keyboard === null || state.terminal?.focus !== "terminal") return { state, effect: null };
1113
+ if (state.terminal?.focus !== "terminal" || ![...chordsRead(state.chords, state.keyboard !== null).values()].includes(event.chord)) return { state, effect: null };
1036
1114
  return led(l === null ? state : next(state, { leader: null }), event.chord, event, keymap);
1037
1115
  }
1038
1116
  if (typeof event.key !== "string" && !("paste" in event)) return { pass: state };
@@ -1045,10 +1123,15 @@ function leading(state, event, keymap) {
1045
1123
  }
1046
1124
  const plain = l === null ? state : next(state, { leader: null });
1047
1125
  if (event.key === state.leaderKey) return { state: next(plain, { leader: leaderAt(event.read, true) }), effect: null };
1048
- // THE CHORDS (docs/tui.md, "Chords"): while the terminal confirms the kitty keyboard protocol, a
1049
- // chord does what the leader then its key does, from whatever was open. While the leader waits it
1050
- // is a key not in the leader's table (above): it cancels the leader and is dropped.
1051
- const chord = state.keyboard === null || typeof event.key !== "string" ? undefined : state.chords.get(event.key);
1126
+ // THE PALETTE'S OWN KEYS (docs/tui.md, "The palette"): while it is open they are its, before any
1127
+ // chord (Alt+Shift+Down and Up are the chords `next` and `previous` too): inPalette reads them.
1128
+ // A chord typed in a terminal (`{ chord }`, above) never comes then: the terminal has no focus.
1129
+ if (state.palette !== null && typeof event.key === "string" && state.paletteKeys.has(event.key)) return { pass: plain };
1130
+ // THE CHORDS (docs/tui.md, "Chords"): a chord does what the leader then its key does, from
1131
+ // whatever was open: every one while the terminal confirms the kitty keyboard protocol, the
1132
+ // Alt+Shift arrows without it too (chordsRead). While the leader waits it is a key not in the
1133
+ // leader's table (above): it cancels the leader and is dropped.
1134
+ const chord = typeof event.key !== "string" ? undefined : chordsRead(state.chords, state.keyboard !== null).get(event.key);
1052
1135
  if (chord !== undefined) return led(plain, chord, event, keymap);
1053
1136
  return { pass: plain };
1054
1137
  }
@@ -1056,7 +1139,7 @@ function leading(state, event, keymap) {
1056
1139
  /** The leader twice (`state` is after it, its hint closed). While the open terminal has the focus,
1057
1140
  * which it keeps, the leader's own key goes to the agent: the effect `{ input: <bytes> }`, the
1058
1141
  * bytes a terminal sends for the back key (term/through.mjs backKeySequences, its first form:
1059
- * ESC o for M-o, 0x1c for C-\\), which the loop types into the focused tab as it types what
1142
+ * 0x18 for C-x, the default; ESC o for M-o), which the loop types into the focused tab as it types what
1060
1143
  * passes through (lib/main.mjs), so an agent that reads that key still gets it. From any other
1061
1144
  * focus it does nothing else: the list is reached with the leader then Esc (LEADER). */
1062
1145
  function twice(state) {
@@ -1092,12 +1175,14 @@ function toInstances(state) {
1092
1175
  return { state: next(s, { view: "instances", back: "instances", switcher: Object.freeze({ ...s.switcher, line: null, refused: null, removing: null }) }), effect: settled.effect };
1093
1176
  }
1094
1177
 
1095
- /** What the leader's key does (LEADER's `does`), from wherever the focus was. From the terminal's
1096
- * focus the acts are the open terminal's instance's and give the focus back when their
1178
+ /** What the leader's key does (LEADER's `does`), or a chord (actions.mjs chordKeys: the same
1179
+ * `does`, and the chords' own `tab-1` to `tab-9`), from wherever the focus was. From the
1180
+ * terminal's focus the acts are the open terminal's instance's and give the focus back when their
1097
1181
  * confirmation closes, zoom zooms it in or out, and the palette gives it back when it is closed;
1098
- * Up and Down go from the open terminal's instance. Every other key first gives the focus to
1099
- * the list, then does what its action does there; the terminal's keys and the acts first go to
1100
- * the Instances view, from any view (toInstances). */
1182
+ * Up and Down go from the open terminal's instance; the tabs' (Left, Right, tab-N) keep the focus
1183
+ * where it was. Every other key first gives the focus to the list, then does what its action does
1184
+ * there; the terminal's keys and the acts first go to the Instances view, from any view
1185
+ * (toInstances). */
1101
1186
  function led(state, does, event, keymap) {
1102
1187
  const stay = { state, effect: null }, t = state.terminal;
1103
1188
  const inTerminal = t?.focus === "terminal" && state.view === "instances";
@@ -1114,13 +1199,14 @@ function led(state, does, event, keymap) {
1114
1199
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1115
1200
  }
1116
1201
  // The tabs, from any focus: the one shown next keeps the focus and the zoom it had.
1117
- if (does === "tab-previous" || does === "tab-next") {
1118
- // At either end, or while a tab starts, nothing at all: not even the settling, which would
1119
- // take the focus from the terminal.
1120
- if (tabStepped(state, does === "tab-previous" ? -1 : 1).effect === null) return stay;
1202
+ const pick = TAB_PICKS[does];
1203
+ if (pick !== undefined) {
1204
+ // At either end, with no such tab, on the shown one or while a tab starts, nothing at all: not
1205
+ // even the settling, which would take the focus from the terminal.
1206
+ if (tabPicked(state, pick).effect === null) return stay;
1121
1207
  const settledState = toInstances(state);
1122
1208
  if (settledState.state.view !== "instances") return stay;
1123
- const step = tabStepped(settledState.state, does === "tab-previous" ? -1 : 1, { focus: inTerminal ? "terminal" : "list", zoom: inTerminal && t.zoom });
1209
+ const step = tabPicked(settledState.state, pick, { focus: inTerminal ? "terminal" : "list", zoom: inTerminal && t.zoom });
1124
1210
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1125
1211
  }
1126
1212
  // The split's keys, from any focus: nothing at all when they do not apply (splitRefused).
@@ -1151,7 +1237,8 @@ function led(state, does, event, keymap) {
1151
1237
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1152
1238
  }
1153
1239
  const settledState = toList(state);
1154
- const { key, text, ...rest } = event;
1240
+ // The action alone: neither the key nor a chord that ran it is read again.
1241
+ const { key, text, chord, ...rest } = event;
1155
1242
  const step = reduced(settledState.state, { ...rest, action: does }, keymap);
1156
1243
  return { state: step.state, effect: both(settledState.effect, step.effect) };
1157
1244
  }
@@ -1197,9 +1284,12 @@ function paletteClosed(state) {
1197
1284
  /** The keys that move the palette's selection: named keys only, so every letter is the query's. */
1198
1285
  const PALETTE_MOVES = Object.freeze({ up: "up", down: "down", pageup: "page-up", pagedown: "page-down" });
1199
1286
  /** A key or a paste while the palette is open. Text and a paste's first line go to the query,
1200
- * Backspace takes a grapheme off it, Up and Down (and PageUp, PageDown) move among its rows,
1201
- * Enter runs the selected row, Esc (or its own key again) closes it; quit, suspend and redraw keep
1202
- * their actions. Every other key does nothing. */
1287
+ * Backspace takes a grapheme off it, Up and Down (and PageUp, PageDown) move among its rows that
1288
+ * can be selected (a group's label row is passed over), its own keys (`paletteKeys`, read before
1289
+ * every other key, a key a tui.json binds to an action too) to the first row of the next group or
1290
+ * of the one before, wrapping (model.mjs paletteStep), Enter runs the selected row, Esc (or its
1291
+ * own key again) closes it; quit, suspend and redraw keep their actions. Every other key does
1292
+ * nothing. */
1203
1293
  function inPalette(state, event, keymap) {
1204
1294
  const p = state.palette, stay = { state, effect: null };
1205
1295
  const put = (changes) => next(state, { palette: Object.freeze({ ...p, ...changes }) });
@@ -1208,10 +1298,12 @@ function inPalette(state, event, keymap) {
1208
1298
  if (typeof event.text === "string") return query(typed(p.query, event.text, { key: true }));
1209
1299
  const action = keymap.get(event.key);
1210
1300
  if (event.key === "backspace") return query([...GRAPHEMES.segment(p.query)].map((g) => g.segment).slice(0, -1).join(""));
1301
+ const group = state.paletteKeys.get(event.key);
1302
+ if (group !== undefined) { const to = paletteStep(paletteItems(state), group); return to === null ? stay : { state: put({ selected: to }), effect: null }; }
1211
1303
  if (event.key === "escape" || action === "close" || action === "palette") return { state: paletteClosed(state), effect: null };
1212
1304
  if (action === "quit" || action === "suspend" || action === "redraw") return { state, effect: action };
1213
1305
  const list = paletteItems(state);
1214
- const keys = list.items.map((item) => item.key);
1306
+ const keys = list.items.filter((item) => item.kind !== "group").map((item) => item.key);
1215
1307
  if (Object.hasOwn(PALETTE_MOVES, event.key)) {
1216
1308
  if (!keys.length) return stay;
1217
1309
  const page = Math.max(1, (Number.isInteger(event.page) ? event.page : 1) - 1);
@@ -1280,6 +1372,8 @@ function reduced(state, event, keymap) {
1280
1372
  // Held while nothing may draw such a line (the switcher, the help): it is said once a view that does is shown.
1281
1373
  if (event.notListed !== undefined) return { state: next(state, { notice: Object.freeze({ said: LIST_WORDS.notAdded(event.notListed?.message ?? ""), under: Object.freeze([]) }) }), effect: null };
1282
1374
  if (event.admitted !== undefined) return { state: admitted(state, event), effect: { refresh: { live: true } } };
1375
+ if (event.joined !== undefined) return joinedHeard(state, { ...event.joined, at: event.at });
1376
+ if (event.identity !== undefined) return identityHeard(state, event.identity);
1283
1377
  if (event.refused !== undefined) return { state: next(state, { switcher: Object.freeze({ ...state.switcher, refused: event.refused }) }), effect: null };
1284
1378
  if (event.souls !== undefined) return soulsHeard(state, event.souls);
1285
1379
  if (event.capabilities !== undefined) return capabilitiesHeard(state, event.capabilities);
@@ -1319,9 +1413,9 @@ function reduced(state, event, keymap) {
1319
1413
  case "quit": case "suspend": case "redraw": return { state, effect: action };
1320
1414
  // In the switcher this computer's deployments list is read again too.
1321
1415
  // In the Souls view it reads the souls again, and nothing else; in the Capabilities view, the capabilities.
1322
- case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : state.view === "capabilities" ? inCapabilities(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { list: true } : {}) } };
1416
+ case "refresh": return state.view === "souls" ? inSouls(state, action, event, page, scrolled) : state.view === "capabilities" ? inCapabilities(state, action, event, page, scrolled) : { state, effect: { refresh: { live: true }, ...((state.view === "help" ? state.back : state.view) === "switcher" ? { list: true, identify: true } : {}) } };
1323
1417
  case "help": return { state: next(state, state.view === "help" ? { view: state.back } : { view: "help", back: state.view, helpTop: 0 }), effect: null };
1324
- case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true } };
1418
+ case "workspaces": return state.view === "switcher" ? stay : { state: toSwitcher(next(state, { back: "switcher" })), effect: { list: true, identify: true } };
1325
1419
  case "palette": return { state: paletteOpened(state, event, "list"), effect: null };
1326
1420
  // Souls and Capabilities are views of this machine, whatever workspace is open, or none.
1327
1421
  case "souls": return soulsShown(state);
@@ -1353,7 +1447,7 @@ function reduced(state, event, keymap) {
1353
1447
  case "filter": return { state: rehomed(roster(state), next(state, { focus: "list", filter: Object.freeze({ editing: true, query: state.filter.query }) })), effect: null };
1354
1448
  case "open": return at < 0 ? stay : openAgent(state, r.items[at].row);
1355
1449
  case "zoom": case "close-terminal": return terminalKey(state, action);
1356
- case "tab-previous": case "tab-next": return tabStepped(state, action === "tab-previous" ? -1 : 1);
1450
+ case "tab-previous": case "tab-next": return tabPicked(state, TAB_PICKS[action]);
1357
1451
  case "split-right": case "split-down": case "group-next": case "tab-move": case "group-close": {
1358
1452
  const refused = splitRefused(state, action, event.panel);
1359
1453
  return refused === true ? { state, effect: null } : refused !== null ? { state: next(state, { outcome: refused }), effect: null } : splitKey(state, action, false);
@@ -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,14 @@ 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) 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);
289
303
  };
290
304
 
291
305
  const endPaste = (truncated) => {
@@ -11,9 +11,12 @@
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+Shift
19
+ * arrow chords need no exception: their legacy sequence is their own (LEGACY_CHORDS). */
17
20
 
18
21
  /** The flags pushed (`CSI > flags u`): 1, disambiguate the escape codes, and 4, report alternate
19
22
  * keys, so the shifted key a key with Shift makes on the person's layout comes with it. The
@@ -50,15 +53,33 @@ export function kittyKey(params) {
50
53
  }
51
54
  const scalar = (cp) => Number.isInteger(cp) && cp > 0 && cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff);
52
55
 
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. */
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. */
56
66
  export function kittyId(key) {
57
67
  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}`;
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;
60
72
  }
61
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
+
62
83
  const ESC = 0x1b;
63
84
  /** The functional keys of the protocol's private-use range the TUI forwards: the keypad, as the key
64
85
  * each one is without the protocol. Every other code of that range (F13 and above, the media keys,
@@ -127,9 +148,10 @@ function shiftedText(key, flags) {
127
148
  * confirmed ones: with flag 4, Shift's character is the one the terminal reported.
128
149
  * Esc ESC; Enter CR; Tab TAB, with Shift `CSI Z`; Backspace DEL, with Ctrl BS; Space SP, with Ctrl
129
150
  * 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. */
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. */
133
155
  export function legacyBytes(key, flags) {
134
156
  if (key === null) return null;
135
157
  let { code } = key;
@@ -154,6 +176,9 @@ export function legacyBytes(key, flags) {
154
176
  else if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) return null;
155
177
  else {
156
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));
157
182
  const byte = key.ctrl ? ctrlByte(text) : null;
158
183
  bytes = byte === null ? utf8(text) : [byte];
159
184
  }