@awebai/oats 0.67.1 → 0.68.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 (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
@@ -24,6 +24,7 @@ import { capabilitiesList, capabilitiesListed, capabilityDetail } from "./capabi
24
24
  import { spawn } from "./spawn.mjs";
25
25
  import { splitFits, splitRegions } from "./split.mjs";
26
26
  import { switcher } from "./switcher.mjs";
27
+ import { workspaceRows } from "./workspaces.mjs";
27
28
 
28
29
  /** The frame is drawn from this size up (docs/tui.md); the design size is 80x24. */
29
30
  export const MIN_SIZE = Object.freeze({ cols: 60, rows: 15 });
@@ -53,11 +54,6 @@ const LIST_LEAST = 3;
53
54
  const SOUL_WORD = "soul";
54
55
  /** What the title says in the workspace's place while the switcher is shown. */
55
56
  const WORKSPACES = "workspaces";
56
- /** The TUI's word before the one machine of a view that holds no deployment of this machine. */
57
- const ON = "on";
58
- /** The cells the workspace's name keeps (all of them, when it is shorter) before the title says
59
- * how many other machines it is on: under that the name comes first. */
60
- const NAME_MIN = 8;
61
57
 
62
58
  const BOLD = style({ bold: true });
63
59
  const DIM = style({ dim: true });
@@ -143,7 +139,11 @@ function openOf(m) {
143
139
  * layout first, because the model's window is as tall (`page`), and the sentences in its list as
144
140
  * wide, as this gives. The answer's `note` is the note's rows and `outcome` the line's: its
145
141
  * sentence and each text under it (what the viewer printed, what the kernel said) set as a reason
146
- * is, on as many rows as a reason may take; `above` is how many of those rows stand. `open` is the
142
+ * is, on as many rows as a reason may take; `above` is how many of those rows stand. A line that
143
+ * passes at the next key (`once`: the end of the list of workspaces) and takes one row stands
144
+ * instead in the empty row under what stands above (`passing`), so nothing moves while it shows:
145
+ * it takes no row of `above`, and `page` is a row shorter, so that empty row is always drawn. A
146
+ * list that fills the sidebar has no such row: it moves a row down, giving up its last. `open` is the
147
147
  * accordion's open view (null while the switcher is shown): the title, the three views' rows and
148
148
  * the rules between the sidebar's parts take what they need, what stands above gives way to keep
149
149
  * the list LIST_LEAST rows and the leader's, and `room` is what is left for the empty row under
@@ -153,7 +153,7 @@ function openOf(m) {
153
153
  * While a terminal is open (`terminal`) the sidebar keeps LIST_BESIDE cells at most, whether the
154
154
  * terminal or the detail stands beside it, so the agent's screen keeps one size; a name longer
155
155
  * than its row is cut there. */
156
- export function layout(notice, size, { note = null, ascii = false, outcome = null, terminal = false, open = "instances" } = {}) {
156
+ export function layout(notice, size, { note = null, ascii = false, outcome = null, terminal = false, open = "instances", list = 1 } = {}) {
157
157
  const wide = size.cols >= WIDE;
158
158
  const listCols = !wide ? size.cols : terminal ? LIST_BESIDE : clamp(Math.floor(size.cols * 0.48), 36, 60);
159
159
  const across = Math.max(1, listCols - 2 * MARGIN);
@@ -164,55 +164,34 @@ export function layout(notice, size, { note = null, ascii = false, outcome = nul
164
164
  ...partRows(outcome.said, across, reasonRows, { ascii }),
165
165
  ...outcome.under.flatMap((text) => shownLines(text, across, reasonRows, { ascii }).map((line) => [{ col: 0, text: line, width: across }])),
166
166
  ] : [];
167
+ const passing = outcome?.once === true && after.length === 1 ? after[0] : null;
167
168
  // The title, a row per view, and the rules: one before the cheat sheet, one between the open
168
169
  // view's list and the views after it, and one between the views before it and its heading.
169
170
  const at = VIEWS.findIndex((view) => view.id === open);
170
171
  const rules = 1 + (at < 0 ? 0 : (at > 0 ? 1 : 0) + (at < VIEWS.length - 1 ? 1 : 0));
171
- const fixed = 1 + VIEWS.length + rules;
172
- const said = (notice ? 1 + reason.length : 0) + noted.length + after.length;
172
+ const fixed = list + VIEWS.length + rules;
173
+ const standing = passing === null ? after : [];
174
+ const said = (notice ? 1 + reason.length : 0) + noted.length + standing.length;
173
175
  const above = Math.min(said, Math.max(0, size.rows - fixed - 1 - LIST_LEAST));
174
176
  const room = Math.max(0, size.rows - fixed - above);
175
- return { wide, listCols, reason, note: noted, outcome: after, above, open: at < 0 ? null : open, room, page: Math.max(1, room - 1), body: size.rows };
177
+ return { wide, listCols, reason, note: noted, outcome: standing, passing, above, open: at < 0 ? null : open, room, page: Math.max(1, room - 1 - (passing === null ? 0 : 1)), body: size.rows };
176
178
  }
177
179
  /** The layout the frame draws a model by. */
178
- const layoutOf = (m, size, given = {}) => layout(m.notice, size, { note: m.note, ascii: m.ascii, outcome: m.outcome, terminal: panelOpen(m), open: openOf(m), ...given });
179
-
180
- /** The title, from `col` on in `room` cells: the workspace's name and, when the view
181
- * holds other machines, what says so, in the TUI's words and dim:
182
- * `+N machine(s)` beside a deployment of this machine;
183
- * `on <machine>` the one machine of a view that holds no deployment of this machine (no
184
- * heading names it there);
185
- * `N machines` two or more of them and no deployment of this machine.
186
- * Whether a deployment is this machine's is the shared entries' word (the model's `here`), and
187
- * the machine's name is theirs. What stands after the name gives way before the name is cut
188
- * short of NAME_MIN cells, and a machine's name is cut before the workspace's. While the
189
- * switcher is shown no workspace is named: the title says what is listed instead. */
180
+ const layoutOf = (m, size, given = {}) => layout(m.notice, size, { note: m.note, ascii: m.ascii, outcome: m.outcome, terminal: panelOpen(m), open: openOf(m), list: listRows(m), ...given });
181
+ /** The rows the top of the sidebar takes: the list of workspaces' (views/workspaces.mjs), else the title's. */
182
+ const listRows = (m) => (m.workspaces ? Math.max(1, m.workspaces.lines.length + (m.workspaces.more > 0 ? 1 : 0)) : 1);
183
+
184
+ /** The title, from `col` on in `room` cells, where the list of workspaces does not stand (nothing
185
+ * is open, or the switcher is shown): the workspace's name, else what is listed. Its machines are
186
+ * the workspace's own pages' to say (the list of instances' sections). */
190
187
  function nameSpans(m, col, room) {
191
188
  if (room <= 0) return [];
192
189
  if (m.under === "switcher") return [{ col, text: lit(WORKSPACES), width: room }];
193
- const name = measured(m.workspace), alone = [{ col, text: name.text, width: room }];
194
- if (!(m.machines > 0)) return alone;
195
- const least = Math.min(name.width, NAME_MIN);
196
- // Two cells between the name and what follows it.
197
- const after = (width) => col + width + (width ? 2 : 0);
198
- if (!m.here && m.machine !== null) {
199
- const where = measured(m.machine), left = room - 2 - ON.length - 1;
200
- // The machine's name is cut first, down to the cells that still say something: the
201
- // workspace's name has what that leaves.
202
- const kept = Math.min(where.width, NAME_MIN);
203
- if (left - least < kept) return alone;
204
- const width = Math.min(name.width, left - kept), at = after(width);
205
- return [...(width ? [{ col, text: name.text, width }] : []), { col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.min(where.width, left - width) }];
206
- }
207
- const more = `${m.here ? "+" : ""}${m.machines} ${m.machines === 1 ? "machine" : "machines"}`;
208
- const left = room - 2 - more.length;
209
- if (left < least) return alone;
210
- const width = Math.min(name.width, left);
211
- return [...(width ? [{ col, text: name.text, width }] : []), { col: after(width), text: lit(more), style: DIM, width: more.length }];
190
+ return [{ col, text: measured(m.workspace).text, width: room }];
212
191
  }
213
192
 
214
- /** The title, the sidebar's first row: the workspace's name in bold and what the view holds of
215
- * other machines (nameSpans), or `workspaces` while the switcher is shown. */
193
+ /** The title, the sidebar's first row where the list does not stand: the workspace's name in bold,
194
+ * or `workspaces` while the switcher is shown (nameSpans). */
216
195
  function titleRow(m, cols) {
217
196
  return nameSpans(m, MARGIN, cols - 2 * MARGIN).map((span) => (span.style ? span : { ...span, style: BOLD }));
218
197
  }
@@ -281,17 +260,19 @@ function types(m) {
281
260
 
282
261
  /** THE CHEAT SHEET (docs/tui.md, "The cheat sheet"): the keys that apply now, one per row, the
283
262
  * leader first in every focus (`Ctrl+X commands`), then the palette, `help` and `quit` last. While
284
- * the leader waits for its key it is the leader's hint (leaderHints). While what is typed goes to
263
+ * the leader waits for its key it is the same: nothing is drawn for the wait, and the help lists
264
+ * the leader's table (views/help.mjs). While what is typed goes to
285
265
  * the agent the TUI reads the leader and the chords only: the leader then Esc gives the list the
286
266
  * focus, and the leader twice types the leader into the terminal; while the terminal confirms the
287
- * kitty keyboard protocol the chords lead there (docs/tui.md, "Chords"; chordHints), the leader's
288
- * hints after them, and the leader is the last given up; without it the leader's lead, and the
289
- * Alt+Shift arrows, the chords that come then, follow them (the first given up). In the palette
267
+ * kitty keyboard protocol, or in the Alt family, whose chords all come without it, the chords lead
268
+ * there (docs/tui.md, "Chords"; chordHints), the leader's hints after them, and the leader is the
269
+ * last given up; else the leader's lead, and the arrows, the chords that come then, follow them
270
+ * (the first given up). In the palette
290
271
  * (its group keys last, where the TUI has them, so the first given up: paletteGroups), the spawn prompt
291
272
  * (spawnHints), a confirmation, the filter field, the help and the switcher, how to work them: the
292
273
  * keys they read are their own, so they are the TUI's words, but for the confirmation's close key and the
293
274
  * field's clear, which are the user's. Else it is small: a view's list or its detail names what
294
- * Enter does now, and the rest stays the leader's hint's, the palette's and the help's. In the list
275
+ * Enter does now, and the rest stays the leader's, the palette's and the help's. In the list
295
276
  * of instances Enter is `open` while it would open the selected agent's terminal and `focus
296
277
  * terminal` on the row whose terminal is open; while another machine is asked first, the key that
297
278
  * gives the open up (`stop opening`) stands in its place. In the Souls view Enter is the detail
@@ -299,13 +280,14 @@ function types(m) {
299
280
  * and from it the marked soul. With the detail's focus the key that goes back to the list
300
281
  * (`Tab back`) comes before it, and `spawn` after it where it spawns (the list of instances, the
301
282
  * Souls view of a workspace of this machine), then in the Instances view `workspaces` (the
302
- * switcher). An action with no key (tui.json may unbind one) has no hint. The views have no
283
+ * list of workspaces' focus). With that focus: the open action's key opens, the up and down
284
+ * actions' move, the close action's goes back, and `workspaces` again is the switcher (`all
285
+ * workspaces`), each by its first key as tui.json binds it. An action with no key (tui.json may unbind one) has no hint. The views have no
303
286
  * hint: the accordion names their keys. When rows are short the sheet
304
287
  * gives up rows from its end (keptHints), down to the leader alone. */
305
288
  function cheatSheet(m) {
306
289
  const action = (id) => (m.actions ?? []).find((a) => a.id === id && a.keys.length);
307
290
  const hint = (id, label) => { const a = action(id); return a ? made(id, keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
308
- if (m.leader) return leaderHints(m);
309
291
  const led = (list) => [made("leader", leaderText(m), "commands"), ...list.filter(Boolean)];
310
292
  const soul = m.view === "souls" && m.souls ? m.souls : null;
311
293
  const capability = m.view === "capabilities" && m.capabilities ? m.capabilities : null;
@@ -315,7 +297,7 @@ function cheatSheet(m) {
315
297
  if (listing && m.terminal?.focus === "terminal" && !m.palette && !m.spawn) {
316
298
  const label = backKeyLabel(m.detachKey), list = keyLabel(LEADER.find((entry) => entry.does === "list").keys[0]);
317
299
  const leader = [made("list", keyText(`${label} ${list}`), "the list"), made("again", keyText(`${label} ${label}`), types(m))];
318
- return m.kitty ? [...chordHints(m), ...led(leader)] : [...led(leader), ...chordHints(m)];
300
+ return m.chordsLead ? [...chordHints(m), ...led(leader)] : [...led(leader), ...chordHints(m)];
319
301
  }
320
302
  if (m.palette) return led([own("run", "Enter", "run"), own("move", "Up/Down", "move"), own("close", "Esc", "close"), paletteGroups(m)]);
321
303
  if (m.spawn) return led(spawnHints(m.spawn, m.ascii));
@@ -330,6 +312,13 @@ function cheatSheet(m) {
330
312
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
331
313
  // Remove stands on a row of this computer's deployments list only, after the keys that move about.
332
314
  if (m.view === "switcher") return led([hint("palette"), ...["open", "filter", ...(m.filter?.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])]), ...(m.switcher?.removable ? ["remove"] : [])].map((id) => hint(id)), hint("help"), hint("quit")]);
315
+ // The list of workspaces with the focus: its keys, and `w` again for the switcher.
316
+ // The keys are the actions' as tui.json binds them: an action with no key has no hint.
317
+ if (listing && m.workspaces?.focused) {
318
+ const moves = [action("up"), action("down")].filter(Boolean);
319
+ const move = moves.length ? made("move", keyText(keysTogether(moves.map((a) => a.keys[0]))), "move") : null;
320
+ return led([hint("open", "open"), move, hint("close", "back"), hint("workspaces", "all workspaces"), hint("help"), hint("quit")]);
321
+ }
333
322
  // A view's list or its detail: a small sheet; the rest is the leader's, the palette's and the help's.
334
323
  const asking = listing && m.opening?.phase === "preflight";
335
324
  const enter = asking ? [hint("close", "stop opening")] : listing && m.onTerminal ? [hint("open", "focus terminal")] : listing && m.openable ? [hint("open")]
@@ -348,7 +337,7 @@ function paletteGroups(m) {
348
337
  return pair === null ? null : own("group", keysTogether(pair), "group");
349
338
  }
350
339
 
351
- /** The chords a terminal's cheat sheet names under the kitty keyboard protocol, in this order, a
340
+ /** The chords a terminal's cheat sheet names while they lead it (chordHints), in this order, a
352
341
  * pair as one hint, each with the TUI's word: what is reached most from a terminal. */
353
342
  const SHEET_CHORDS = Object.freeze([
354
343
  Object.freeze([["palette"], "palette"]),
@@ -358,9 +347,9 @@ const SHEET_CHORDS = Object.freeze([
358
347
  Object.freeze([["zoom"], "zoom"]),
359
348
  ]);
360
349
  /** The chord hints of a terminal's focus (docs/tui.md, "Chords"): those of SHEET_CHORDS read now
361
- * (the model's `chords`: tui.json may have taken a key; without the protocol the Alt+Shift
362
- * arrows alone), the tabs' only
363
- * with two tabs or more, as the leader's hint has them. A pair's keys share their modifiers:
350
+ * (the model's `chords`: tui.json may have taken a key; outside the Alt family, without the
351
+ * protocol, the arrows alone), the tabs' only
352
+ * with two tabs or more, as the leader's table has them. A pair's keys share their modifiers:
364
353
  * `Alt+Shift+Up/Down` (keysTogether). They stand in a block of their own (cheatRows). */
365
354
  function chordHints(m) {
366
355
  const keyOf = new Map((m.chords ?? []).map(([key, does]) => [does, key]));
@@ -377,41 +366,9 @@ function spawnHints(s, ascii) {
377
366
  : [...(s.enter ? [own("enter", "Enter", ownEllipsis(s.enter, ascii))] : []), own("next", "Tab", "next"), own("back", "Shift+Tab", "back"), own("esc", "Esc", "back")];
378
367
  }
379
368
 
380
- /** The leader's hint (docs/tui.md, "The leader"): the leader's key, then what each key after it
381
- * does, from actions.mjs LEADER, the views, the instances and the acts each one hint. The keys
382
- * that need a terminal are named only while one is open, the tabs' only with two or more, and the
383
- * split's only where they apply; while what is typed goes to the agent, the leader again, which
384
- * types it there. The last, the list's, is never given up. */
385
- function leaderHints(m) {
386
- const by = (does) => LEADER.find((entry) => entry.does === does);
387
- const one = (does) => { const entry = by(does); return own(does, keyLabel(entry.keys[0]), entry.label); };
388
- const keysOf = (list) => list.map((does) => keyLabel(by(does).keys[0])).join("/");
389
- const views = keysOf(["instances", "souls", "capabilities"]);
390
- const typing = m.terminal?.focus === "terminal" && m.view === "instances" && !m.palette && !m.spawn;
391
- return [
392
- made("leader", leaderText(m), "then"),
393
- own("palette", keyLabel(by("palette").keys[0]), "palette"),
394
- own("views", views === "1/2/3" ? "1-3" : views, "views"),
395
- own("instance", keysOf(["previous", "next"]), "instance"),
396
- ...(m.terminal ? [one("zoom"), one("close-terminal")] : []),
397
- // With two tabs or more, the keys that move between them.
398
- ...((m.tabs?.length ?? 0) > 1 ? [own("tabs", keysOf(["tab-previous", "tab-next"]), "tab")] : []),
399
- // The split's (docs/tui.md, "Splits"): to split while there is one group; with two, the next
400
- // group, and the move of the shown tab, or the close of the focused group while it is empty.
401
- ...(m.panelOpen && !m.split ? [own("split", keysOf(["split-right", "split-down"]), "split")] : []),
402
- ...(m.split ? [one("group-next"), ...(m.terminal ? [one("tab-move")] : [one("group-close")])] : []),
403
- own("acts", keysOf(["stop", "restart", "start", "retire"]), "acts"),
404
- one("filter"), one("workspaces"), one("help"),
405
- ...(typing ? [made("again", leaderText(m), types(m))] : []),
406
- one("list"),
407
- ];
408
- }
409
-
410
- /** The hints that stand in `count` rows: given up from the end, down to the leader alone (givenUp);
411
- * the leader's hint keeps its last, the list's, while it has two rows. */
412
- function keptHints(m, hints, count) {
369
+ /** The hints that stand in `count` rows: given up from the end, down to the leader alone (givenUp). */
370
+ function keptHints(hints, count) {
413
371
  if (count >= hints.length) return hints;
414
- if (m.leader && count >= 2) return [...hints.slice(0, count - 1), hints.at(-1)];
415
372
  let kept = hints;
416
373
  while (kept.length > Math.max(1, count)) kept = givenUp(kept);
417
374
  return kept;
@@ -445,16 +402,16 @@ function cheatRows(hints, cols) {
445
402
  });
446
403
  }
447
404
 
448
- /** The cheat sheet a title row carries (withKeys): without the kitty keyboard protocol the
449
- * Alt+Shift arrows follow the leader's hints in the sheet's rows, but a title row keeps to the
450
- * leader's; under it the chords lead there as in the rows. */
451
- const titleSheet = (m) => cheatSheet(m).filter((h) => m.kitty || h.block !== "chords");
405
+ /** The cheat sheet a title row carries (withKeys): where only some chords are read (no kitty
406
+ * keyboard protocol, a family other than Alt) the arrows follow the leader's hints in the sheet's
407
+ * rows, but a title row keeps to the leader's; where all are, the chords lead there as in the rows. */
408
+ const titleSheet = (m) => cheatSheet(m).filter((h) => m.chordsLead || h.block !== "chords");
452
409
 
453
410
  /** An overlay's or a detail page's first row on a narrow terminal, where it has the whole screen:
454
411
  * its essential keys (the cheat sheet's, but for the leader, the palette, help and quit) at the
455
412
  * right, dim, as many as fit after what the row holds, given up from the end. With `first`, the
456
413
  * first key always stands (a detail page's way back): what the row holds is cut to leave it room. */
457
- function withKeys(given, hints, cols, { skip = ["leader", "palette", "help", "quit"], last = false, first = false } = {}) {
414
+ function withKeys(given, hints, cols, { skip = ["leader", "palette", "help", "quit"], first = false } = {}) {
458
415
  const keys = hints.filter((h) => !skip.includes(h.id));
459
416
  const widthOf = (list) => list.reduce((sum, h) => sum + h.key.width + 1 + h.word.width, 0) + Math.max(0, list.length - 1) * GAP;
460
417
  const limit = first && keys.length ? cols - MARGIN - widthOf(keys.slice(0, 1)) - GAP : Infinity;
@@ -463,9 +420,8 @@ function withKeys(given, hints, cols, { skip = ["leader", "palette", "help", "qu
463
420
  // What the row holds ends where its text does: a span may be given more cells than its text takes.
464
421
  const end = row.reduce((most, span) => (span.text !== undefined ? Math.max(most, span.col + Math.min(span.width ?? Infinity, textWidth(textOf(span.text)))) : most), 0);
465
422
  let kept = keys;
466
- // Given up from the end, the leader last (givenUp); with `last`, the last is kept as long as one
467
- // other is (the leader's `Esc`).
468
- while (kept.length && end + GAP + widthOf(kept) > cols - MARGIN) kept = last && kept.length > 1 ? [...kept.slice(0, -2), kept.at(-1)] : givenUp(kept);
423
+ // Given up from the end, the leader last (givenUp).
424
+ while (kept.length && end + GAP + widthOf(kept) > cols - MARGIN) kept = givenUp(kept);
469
425
  const spans = [];
470
426
  let col = cols - MARGIN - widthOf(kept);
471
427
  for (const h of kept) {
@@ -486,7 +442,8 @@ function listOf(m, g) {
486
442
  }
487
443
 
488
444
  /** The sidebar (docs/tui.md, "What it shows") in `rows`, from column 0 in the sidebar's width:
489
- * the title; what stands under it (sayings); an empty row; the views, the open one's heading
445
+ * the title; what stands under it (sayings); an empty row, which a passing line takes (layout's
446
+ * `passing`); the views, the open one's heading
490
447
  * with its list (`list`, trailing empty rows left out) under it and a rule between the views
491
448
  * before it and its heading, and between its list and the views after it; a rule, then the
492
449
  * cheat sheet. It flows from the top. The list keeps its rows ahead of the cheat sheet: when both
@@ -496,12 +453,14 @@ function sidebar(m, g, rows, list) {
496
453
  const cols = g.listCols;
497
454
  let r = 0;
498
455
  const put = (spans) => { if (r < rows.length) rows[r] = spans; r += 1; };
499
- put(titleRow(m, cols));
456
+ if (m.workspaces) workspaceRows(m.workspaces, cols, { ascii: m.ascii, colour: m.colour }).forEach(put);
457
+ else put(titleRow(m, cols));
500
458
  sayings(m, g).forEach(put);
501
459
  let n = list.length;
502
460
  while (n > 0 && list[n - 1].length === 0) n -= 1;
503
461
  const hints = cheatSheet(m), room = g.room;
504
462
  const [empty, count, shownRows] = n + 1 + hints.length <= room ? [1, hints.length, n] : n + 2 <= room ? [1, room - 1 - n, n] : [0, 1, Math.min(n, room - 1)];
463
+ if (empty && g.passing) rows[r] = placed(g.passing, MARGIN);
505
464
  r += empty;
506
465
  const at = VIEWS.findIndex((view) => view.id === g.open);
507
466
  VIEWS.forEach((view, i) => {
@@ -512,7 +471,7 @@ function sidebar(m, g, rows, list) {
512
471
  if (i < VIEWS.length - 1) put(rule(cols, m.ascii));
513
472
  });
514
473
  put(rule(cols, m.ascii));
515
- cheatRows(keptHints(m, hints, count), cols).forEach(put);
474
+ cheatRows(keptHints(hints, count), cols).forEach(put);
516
475
  }
517
476
 
518
477
  /** The rule between the sidebar and the main area, over the whole height. */
@@ -597,7 +556,7 @@ function framed(m, size) {
597
556
  }
598
557
  // The help, under its top row (readRow).
599
558
  if (m.view === "help") {
600
- const drawn = help(m.actions, { cols: main.cols, rows: size.rows - 1 }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey, chords: m.chords ?? null, chordsLead: m.kitty === true, paletteKeys: m.paletteKeys ?? null, keys: m.keys ?? null });
559
+ const drawn = help(m.actions, { cols: main.cols, rows: size.rows - 1 }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey, chords: m.chords ?? null, chordsLead: m.chordsLead === true, paletteKeys: m.paletteKeys ?? null, keys: m.keys ?? null });
601
560
  overlay([readRow(m), ...drawn.rows]);
602
561
  return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: Math.max(1, size.rows - 1) };
603
562
  }
@@ -640,9 +599,9 @@ function framed(m, size) {
640
599
  if (paged) rows[0] = withKeys(rows[0], cheatSheet(m), cols, { first: true });
641
600
  }
642
601
  // Over the whole screen no cheat sheet is drawn: the terminal's title row, the TUI's own, carries
643
- // its keys at the right instead (the leader, then Esc for the list), and while the leader waits,
644
- // the leader's hint, as many as fit, its last (`Esc the list`) kept.
645
- if (zoomed) rows[area.title] = m.leader ? withKeys(rows[area.title], leaderHints(m), cols, { skip: [], last: true }) : withKeys(rows[area.title], titleSheet(m), cols, { skip: ["again"] });
602
+ // its keys at the right instead (the leader, then Esc for the list), the same while the leader
603
+ // waits.
604
+ if (zoomed) rows[area.title] = withKeys(rows[area.title], titleSheet(m), cols, { skip: ["again"] });
646
605
  // The focused group's terminal, when it shows one: the agent's cursor, where the agent has it,
647
606
  // while what is typed goes to the agent.
648
607
  const shownArea = area !== null && area.id !== null && m.terminal ? { title: area.title, top: area.top, col: area.col, cols: area.cols, rows: area.rows, whole: area.whole } : null;
@@ -745,9 +704,15 @@ const tabDivider = (ascii) => (ascii ? "|" : "\u2502");
745
704
  const SHOWN_SIDES = Object.freeze(["[", "]"]);
746
705
  /** A hidden tab's look: dim. Its activity mark is not: it is what a glance looks for. */
747
706
  const HIDDEN = DIM;
748
- /** The machine of the shown tab while what is typed goes to it: dim, in the tab's reverse video. */
707
+ /** The machine and the number of the shown tab while what is typed goes to it: dim, in the tab's
708
+ * reverse video. */
749
709
  const FOCUSED_DIM = style({ dim: true, reverse: true });
750
710
 
711
+ /** A tab's number at `index` in a strip of `count` tabs (docs/tui.md, "Tabs"): the N whose tab-N
712
+ * chord shows it (store.mjs TAB_PICKS). The first eight are 1 to 8, the last of nine or more is 9,
713
+ * and any other past the eighth has none (null). */
714
+ export const tabNumber = (index, count) => (index < 8 ? index + 1 : index === count - 1 ? 9 : null);
715
+
751
716
  /** THE TAB BAR (docs/tui.md, "Tabs"), the top row of a group's region whenever it shows a tab, one
752
717
  * or many, as a terminal's own tabs read: each tab in order, a dim `│` (`|` in ASCII) between two.
753
718
  * A tab is its agent's name with a cell on each side, `•` (`*` in ASCII) after the name of a hidden
@@ -755,19 +720,29 @@ const FOCUSED_DIM = style({ dim: true, reverse: true });
755
720
  * another machine's agent. The shown tab reads as the front one: `[` and `]` stand in its side
756
721
  * cells (a mark no style is needed for: it holds under NO_COLOR and in ASCII), its name is bold,
757
722
  * and the whole tab is in reverse video while what is typed goes to it; a hidden tab is dim.
723
+ * Each tab ends with its number in its group's strip (tabNumber), after a blank cell and before
724
+ * its closing side, dim (dim in the reverse video of the focused shown tab): a position, the same
725
+ * in every chord family, drawn while a chord shows the Nth tab (`numbers`, the model's
726
+ * `tabNumbers`: never on macOS, where none reaches the TUI). The numbers are drawn only while every tab fits
727
+ * whole with them, its name and its machine; else no tab has one, and the row is cut as follows.
758
728
  * What does not fit is cut in this order: the hidden tabs' machines, then their names, each to an
759
729
  * equal share of what the shown tab leaves with `…`, then the shown tab's machine, then the hidden
760
730
  * tabs farthest from the shown one are left out (each takes its divider with it). The shown tab's
761
731
  * name stays whole while the row can hold it, and is cut last. */
762
- function stripRow(given, area, { focused, ascii }) {
732
+ function stripRow(given, area, { focused, ascii, numbers = true }) {
763
733
  const mark = ascii ? "*" : ACTIVITY, dot = tabDot(ascii);
764
- const tabs = given.map((tab) => ({ ...tab, name: measured(tab.name), machine: tab.machine ? measured(tab.machine) : null, mark: !tab.shown && tab.activity === true }));
734
+ const tabs = given.map((tab, i) => ({ ...tab, name: measured(tab.name), machine: tab.machine ? measured(tab.machine) : null, mark: !tab.shown && tab.activity === true, number: tabNumber(i, given.length) }));
765
735
  const machineCells = (tab) => (tab.machine ? 3 + tab.machine.width : 0);
766
- const cellsOf = (tab, { machine, name = tab.name.width, dropped = false }) => (dropped ? 0 : 1 + name + (tab.mark ? 1 : 0) + (machine ? machineCells(tab) : 0) + 1);
736
+ // The numbers, while drawn: a blank cell and the digit.
737
+ let numbered = numbers;
738
+ const numberCells = (tab) => (numbered && tab.number !== null ? 2 : 0);
739
+ const cellsOf = (tab, { machine, name = tab.name.width, dropped = false }) => (dropped ? 0 : 1 + name + (tab.mark ? 1 : 0) + (machine ? machineCells(tab) : 0) + numberCells(tab) + 1);
767
740
  const plan = tabs.map((tab) => ({ machine: true, name: tab.name.width, dropped: false }));
768
741
  // Each drawn tab after the first has its divider before it.
769
742
  const total = () => tabs.reduce((sum, tab, i) => sum + cellsOf(tab, plan[i]), 0) + Math.max(0, plan.filter((p) => !p.dropped).length - 1);
770
743
  const fits = () => total() <= area.cols;
744
+ // The numbers go first and all together: every tab whole with them, or none has one.
745
+ if (!fits()) numbered = false;
771
746
  const shown = Math.max(0, tabs.findIndex((tab) => tab.shown));
772
747
  // The least a hidden tab is drawn in: a cell of its name (the cut mark), its mark, a cell each
773
748
  // side, and its divider.
@@ -820,6 +795,10 @@ function stripRow(given, area, { focused, ascii }) {
820
795
  put(null, 1, null);
821
796
  put(tab.machine.text, tab.machine.width, machineLook);
822
797
  }
798
+ if (numberCells(tab)) {
799
+ put(null, 1, null);
800
+ put(lit(String(tab.number)), 1, reversed ? FOCUSED_DIM : DIM);
801
+ }
823
802
  put(right, 1, look);
824
803
  });
825
804
  return row;
@@ -854,7 +833,7 @@ function regionRows(m, area) {
854
833
  const focused = area.focused && m.terminal?.focus === "terminal";
855
834
  // A model made by hand may name its terminal and no tabs: its one tab is that terminal.
856
835
  const tabs = group.tabs.length ? group.tabs : [{ name: m.terminal?.name, machine: m.terminal?.routed ? m.terminal.machine : null, shown: true, activity: false }];
857
- const title = stripRow(tabs, area, { focused, ascii: m.ascii });
836
+ const title = stripRow(tabs, area, { focused, ascii: m.ascii, numbers: m.tabNumbers !== false });
858
837
  const screenOf = area.focused ? m.screen : m.screens?.get(group.shown) ?? null;
859
838
  const lines = screenOf?.lines ?? [];
860
839
  const body = Array.from({ length: area.rows }, (_, r) => (lines[r] ?? [])
@@ -2,13 +2,14 @@
2
2
  // text. Pure: no IO, no clock, no escape byte. The keys are generated from the table the reducer
3
3
  // acts on, so the help names every key that does something and no key that does not; the marks
4
4
  // are the ones the list and the switcher draw (views/instances.mjs, views/switcher.mjs).
5
- import { LEADER, backKeyLabel, keyLabel, keysTogether } from "../actions.mjs";
5
+ import { LEADER, backKeyLabel, doesLabel, keyLabel, keysTogether } from "../actions.mjs";
6
6
  import { lit, ownEllipsis } from "../term/text.mjs";
7
7
  import { style } from "../term/style.mjs";
8
8
  import { NEEDS_INPUT, belowText, cutNote, marksOf, measured } from "./instances.mjs";
9
9
  import { windowOf } from "./scroll.mjs";
10
10
  import { SOUL_MARK } from "./souls.mjs";
11
11
  import { OPEN_MARK } from "./switcher.mjs";
12
+ import { WAITING_DOT } from "./workspaces.mjs";
12
13
 
13
14
  const TITLE = style({ bold: true });
14
15
  const KEYS = style({ bold: true });
@@ -148,55 +149,74 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
148
149
  });
149
150
 
150
151
  /** What the leader pressed again does, the last line of the leader's table. */
151
- export const LEADER_AGAIN = "the leader again: types it into the terminal that has the focus; with the list focused, closes the hint";
152
+ export const LEADER_AGAIN = "the leader again: types it into the terminal that has the focus; with the list focused, cancels the leader";
152
153
 
153
154
  /** THE CHORDS (docs/tui.md, "Chords"): the chords read now, the extras of the leader, which is the
154
- * key that always works. While the terminal confirms the kitty keyboard protocol they lead the
155
- * help, first of all; without it only the Alt+Shift arrows are read, listed after the leader's
156
- * section. What a
157
- * terminal may take first is said, and where the table of terminals is, as sentences the help
158
- * flows. */
155
+ * key that always works. While every chord bound is read (under the kitty keyboard protocol, or
156
+ * in the Alt family, whose keys need none) they lead the help, first of all; else only those with
157
+ * bytes of their own are read (the arrows of the other two families), listed after the leader's
158
+ * section. What a terminal may take first, how a program in a terminal still gets an Alt key the
159
+ * TUI takes, and where the tables are, as sentences the help flows. */
159
160
  export const CHORD_RULES = Object.freeze([
160
- "Your terminal may take some first: Windows Terminal takes Ctrl+Alt+1 to Ctrl+Alt+9 for its own tabs, and the Alt+Shift arrows while its panes are split.",
161
- "Terminals without the kitty keyboard protocol (GNOME Terminal and the other VTE terminals, Konsole before 26.08, WezTerm unless enable_kitty_keyboard is set) send only the Alt+Shift arrows.",
162
- "On a keyboard layout where AltGr is Ctrl+Alt (Windows), a Ctrl+Alt key that types a character types it.",
161
+ "Your terminal may take some first: GNOME Terminal and Konsole take Alt+1 to Alt+9 for their own tabs while they have two or more, and Ghostty when the tab changes; Windows Terminal takes the Alt and Alt+Shift arrows while its panes are split, and Ctrl+Alt+1 to Ctrl+Alt+9 for its own tabs.",
162
+ "A program in a terminal still gets an Alt key the TUI takes as Esc, then the key, where it reads Esc as Meta, as the shell does.",
163
+ "The Ctrl+Alt and Ctrl+Shift chords need the kitty keyboard protocol: terminals without it (GNOME Terminal and the other VTE terminals, Konsole before 26.08, WezTerm unless enable_kitty_keyboard is set) send only their arrows.",
164
+ "A key that types a character with AltGr types it.",
163
165
  "The leader works in every terminal.",
164
- "docs/tui.md, \"Chords\", has the table of terminals.",
166
+ "docs/tui.md, \"Chords\", has the tables of terminals and of what the Alt family takes.",
165
167
  ]);
166
- /** THE FAMILY (docs/tui.md, "Switch to Ctrl+Shift"): the sentences that lead the chords' section,
167
- * for `keys`, the model's `{ family, label, note }` (keys.json as lib/config.mjs loadKeys read it, and
168
+ /** THE CHORDS ON MACOS (docs/tui.md, "Chords on macOS"): Alt (Option) with an arrow alone, read
169
+ * where the terminal sends it as one (`CSI 1;3` and `CSI 1;4`), said Alt as the keys' labels are. What leads the chords' section
170
+ * there, and what follows its rows in place of CHORD_RULES. */
171
+ export const MAC_CHORD_LINE = "Shortcuts on macOS: Alt (Option) with an arrow, where your terminal sends it as one. Alt with a letter or a digit types a character, so none is a chord.";
172
+ export const MAC_CHORD_RULES = Object.freeze([
173
+ "Terminal.app, Ghostty and VS Code's terminal send Alt+Left and Alt+Right as the shell's word moves, Esc then b or f: there those chords do not come, and the shell moves by word.",
174
+ "Where the chord comes, the TUI takes it from the agent.",
175
+ "The leader works in every terminal.",
176
+ "docs/tui.md, \"Chords on macOS\", has the terminals and their settings.",
177
+ ]);
178
+ /** THE FAMILY (docs/tui.md, "Switch family"): the sentences that lead the chords' section, for
179
+ * `keys`, the model's `{ family, label, note }` (keys.json as lib/config.mjs loadKeys read it, and
168
180
  * the shared chordFamilyNote's line, or null), while the terminal confirms the kitty keyboard
169
- * protocol (`confirmed`) or not. Which family is bound: Ctrl+Alt, with how to switch; Ctrl+Shift,
170
- * from keys.json, and, without the protocol, that this terminal cannot send it, so the leader is
171
- * the way (the Alt+Shift arrows still come). Then the note, when the file was there and not taken.
172
- * No `keys` (a view drawn without a run): none. macOS has no chords, so no section and no line. */
181
+ * protocol (`confirmed`) or not. Which family is bound: Alt, the default, with how to switch;
182
+ * Ctrl+Alt or Ctrl+Shift, from keys.json, and, without the protocol, that this terminal cannot
183
+ * send it, so the leader is the way (their arrows still come). Then the note, when the file was
184
+ * there and not taken. No `keys` (a view drawn without a run): none. macOS (`keys.mac`) has no
185
+ * family: MAC_CHORD_LINE. */
173
186
  export function chordFamilyLines(keys, confirmed) {
174
187
  if (!keys) return [];
175
- const shift = "Ctrl+Shift";
176
- const said = keys.family !== "ctrl+shift"
177
- ? `Shortcuts: ${keys.label}. For ${shift} (foot, Alacritty), set "chords": "ctrl+shift" in keys.json and restart.`
178
- : confirmed ? `Shortcuts: ${shift}, from keys.json.`
179
- : `Shortcuts: ${shift}, from keys.json, but this terminal does not confirm the kitty keyboard protocol: use the leader.`;
188
+ if (keys.mac === true) return [MAC_CHORD_LINE];
189
+ const chosen = keys.family === "ctrl+alt" || keys.family === "ctrl+shift" ? keys.family : null;
190
+ const label = chosen === "ctrl+alt" ? "Ctrl+Alt" : chosen === "ctrl+shift" ? "Ctrl+Shift" : keys.label;
191
+ const said = chosen === null
192
+ ? `Shortcuts: ${label}. To leave Alt to the programs in your terminals, set "chords": "ctrl+alt" in keys.json (or "ctrl+shift", for foot and Alacritty) and restart.`
193
+ : confirmed ? `Shortcuts: ${label}, from keys.json.`
194
+ : `Shortcuts: ${label}, from keys.json, but this terminal does not confirm the kitty keyboard protocol: use the leader.`;
180
195
  return typeof keys.note === "string" ? [said, keys.note] : [said];
181
196
  }
182
197
 
183
198
  /** The chords listed on one row of their own, both keys first, their modifiers said once
184
- * (`Alt+Shift+Up/Down`, actions.mjs keysTogether, as the cheat sheet says them): the leader's Up
185
- * and Down, its Left and Right. The table's left column stays narrow enough for the help beside
186
- * the sidebar at 80 columns. */
187
- const CHORD_PAIRS = Object.freeze([Object.freeze(["previous", "next"]), Object.freeze(["tab-previous", "tab-next"])]);
199
+ * (`Alt+Shift+Up/Down`, actions.mjs keysTogether, as the cheat sheet says them): the instances,
200
+ * the workspaces (the leader's Up and Down), the tabs (its Left and Right) and the groups (its
201
+ * Shift+Tab and Tab). The table's left column stays narrow enough for the help beside the sidebar
202
+ * at 80 columns. */
203
+ const CHORD_PAIRS = Object.freeze([["previous", "next"], ["workspace-previous", "workspace-next"], ["tab-previous", "tab-next"], ["group-previous", "group-next"]].map((pair) => Object.freeze(pair)));
188
204
  /** The chords' own (actions.mjs CHORD_OWN), the Nth tab: one row for the nine, as the TUI's words. */
189
205
  const TAB_N = /^tab-([1-9])$/;
190
206
  const TABS_SAID = "the focused group's first to eighth tab, 9 its last";
207
+ /** Whether keysTogether says the keys' modifiers once (`Alt+Shift+Up/Down`), not each key whole. */
208
+ const sharesModifiers = (keys) => keysTogether(keys) !== keys.map(keyLabel).join("/");
191
209
  /** Two labels of the leader's table as one: `previous instance` and `next instance` are
192
210
  * `previous and next instance`. */
193
211
  function bothSaid(a, b) {
194
212
  const [x, y] = [words(a), words(b)];
195
213
  return x.length > 1 && x.at(-1) === y.at(-1) ? `${x.slice(0, -1).join(" ")} and ${y.join(" ")}` : `${a} and ${b}`;
196
214
  }
197
- /** The chords' rows: `chords` are `[key id, does]` in the table's order, each said as the leader's
198
- * table says its `does`, then `or <the leader> then <its key>` (`detachKey`'s label, when one is
199
- * given); a pair of CHORD_PAIRS on one row, and the nine tab-N on one, `Ctrl+Alt+1 … Ctrl+Alt+9`
215
+ /** The chords' rows: `chords` are `[key id, does]` in the table's order, each said by its label
216
+ * (the shared doesLabel: the leader's table's, else the chord's own), then, for one the leader's
217
+ * table has a key for, `or <the leader> then <its key>` (`detachKey`'s label, when one is given); a pair of CHORD_PAIRS on one row
218
+ * where its keys share their modifiers (`Alt+Shift+Up/Down`; Ctrl+Alt+Shift+A and Ctrl+Alt+A, which do not, a row each, so the
219
+ * keys' column stays narrow enough for the meanings beside it at 80 columns), and the nine tab-N on one, `Ctrl+Alt+1 … Ctrl+Alt+9`
200
220
  * (`...` in ASCII), which no leader's key does. The family's lines lead them (chordFamilyLines:
201
221
  * `keys`, under the protocol or not, `confirmed`). */
202
222
  function chordRows(chords, cols, detachKey, ascii, keys = null, confirmed = false) {
@@ -208,16 +228,16 @@ function chordRows(chords, cols, detachKey, ascii, keys = null, confirmed = fals
208
228
  const done = new Set(), rows = [];
209
229
  for (const [key, does] of chords) {
210
230
  if (done.has(does)) continue;
211
- const pair = CHORD_PAIRS.find((each) => each.includes(does) && each.every((one) => keyOf.has(one)));
231
+ const pair = CHORD_PAIRS.find((each) => each.includes(does) && each.every((one) => keyOf.has(one)) && sharesModifiers(each.map((one) => keyOf.get(one))));
212
232
  if (pair) {
213
233
  pair.forEach((one) => done.add(one));
214
- rows.push([keysTogether(pair.map((one) => keyOf.get(one))), `${bothSaid(by(pair[0]).label, by(pair[1]).label)}${then(pair)}`]);
234
+ rows.push([keysTogether(pair.map((one) => keyOf.get(one))), `${bothSaid(doesLabel(pair[0]), doesLabel(pair[1]))}${then(pair)}`]);
215
235
  } else if (TAB_N.test(does) && tabs.length === 9) {
216
236
  tabs.forEach(([, one]) => done.add(one));
217
237
  rows.push([ownEllipsis(`${keyLabel(tabs[0][0])} \u2026 ${keyLabel(tabs[8][0])}`, ascii), TABS_SAID]);
218
238
  } else {
219
239
  const n = TAB_N.exec(does)?.[1];
220
- rows.push([keyLabel(key), n === undefined ? `${by(does)?.label ?? does}${then([does])}` : n === "9" ? "the focused group's last tab" : `the focused group's tab ${n}`]);
240
+ rows.push([keyLabel(key), n === undefined ? `${doesLabel(does) ?? does}${then([does])}` : n === "9" ? "the focused group's last tab" : `the focused group's tab ${n}`]);
221
241
  }
222
242
  }
223
243
  return [
@@ -226,7 +246,7 @@ function chordRows(chords, cols, detachKey, ascii, keys = null, confirmed = fals
226
246
  ...sentences(chordFamilyLines(keys, confirmed), cols),
227
247
  ...sentences(["One keypress each, from every focus, a terminal's too: none reaches the agent."], cols),
228
248
  ...table(rows.map(([keys, said]) => [keyText(keys), words(said)]), cols, KEYS),
229
- ...sentences(CHORD_RULES, cols),
249
+ ...sentences(keys?.mac === true ? MAC_CHORD_RULES : CHORD_RULES, cols),
230
250
  ];
231
251
  }
232
252
 
@@ -271,7 +291,7 @@ function leaderRows(detachKey, cols) {
271
291
  ...table([...LEADER.map((entry) => [entry.keys.map(keyLabel).join(", "),
272
292
  words(entry.terminal ? `${entry.label}, while a terminal is open` : entry.label)]),
273
293
  // The leader again is the user's key, so it is not in the table: it types the leader into the
274
- // terminal that has the focus, and with the list focused only closes the hint.
294
+ // terminal that has the focus, and with the list focused only cancels the leader.
275
295
  [key, words(LEADER_AGAIN)]], cols, KEYS),
276
296
  ];
277
297
  }
@@ -331,10 +351,12 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null, chords =
331
351
  [marks.unknown, "state unknown"],
332
352
  [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
333
353
  ["+N", "N instances folded away below it"],
334
- [marks.waiting, `needs input, in reverse video: ${NEEDS_INPUT} where the whole name fits`],
354
+ [marks.waiting, `${NEEDS_INPUT}: in place of the state mark, in yellow and reverse video`],
335
355
  ["N", `N instances folded away below it need input: ${belowText("N")} where the whole name fits`],
336
356
  [marks.selected, "the selected row, and the pane the movement keys act on"],
337
357
  [OPEN_MARK, "among the workspaces: the one that is open"],
358
+ [ascii ? WAITING_DOT.ascii : WAITING_DOT.utf8, ascii ? "among the workspaces: an instance there needs input" : `among the workspaces, in yellow: an instance there needs input (${WAITING_DOT.ascii} without colour)`],
359
+ [`+N ${ascii ? WAITING_DOT.ascii : WAITING_DOT.utf8}`, "among the workspaces: N not shown, and an instance in one of them needs input"],
338
360
  [ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, "among the souls: a soul, in its colour"],
339
361
  ["!", "among the souls: a spawn of it here would be refused"],
340
362
  ].map(([mark, meaning]) => [mark, words(meaning)]), cols),