@awebai/oats 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +80 -8
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +18 -2
  5. package/docs/implementation.md +3 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/release-notes/v0.60.0.md +104 -0
  12. package/docs/servers.md +4 -1
  13. package/docs/souls-and-instances.md +21 -0
  14. package/docs/tui.md +753 -119
  15. package/docs/workspaces.md +2 -2
  16. package/lib/core.mjs +258 -57
  17. package/lib/read-ahead-worker.mjs +119 -0
  18. package/lib/read-ahead.mjs +115 -0
  19. package/lib/retire-state.mjs +33 -0
  20. package/lib/servers.mjs +9 -1
  21. package/lib/session-input.mjs +53 -26
  22. package/package-catalog.json +3 -3
  23. package/package.json +1 -1
  24. package/packages/client/capability-catalog.mjs +93 -0
  25. package/packages/client/capability-facts.mjs +59 -0
  26. package/packages/client/capability-rows.mjs +121 -0
  27. package/packages/client/catalog-messages.mjs +12 -0
  28. package/packages/client/cli-locator.mjs +2 -2
  29. package/packages/client/deployment-data.mjs +4 -0
  30. package/packages/client/deployment-panel.mjs +3 -0
  31. package/packages/client/instance-acts.mjs +23 -8
  32. package/packages/client/instance-presentation.mjs +3 -2
  33. package/packages/client/instance-tree.mjs +84 -39
  34. package/packages/client/lifecycle-confirmation.mjs +9 -3
  35. package/packages/client/remote-roster.mjs +4 -1
  36. package/packages/client/retire-in-flight.mjs +65 -0
  37. package/packages/client/retire-state.mjs +30 -0
  38. package/packages/client/soul-catalog.mjs +8 -0
  39. package/packages/client/soul-facts.mjs +7 -0
  40. package/packages/client/spawn-apply.mjs +13 -4
  41. package/packages/client/spawn-messages.mjs +8 -0
  42. package/packages/client/subsequence-score.mjs +15 -0
  43. package/packages/tui/README.md +23 -10
  44. package/packages/tui/lib/actions.mjs +63 -5
  45. package/packages/tui/lib/client.mjs +17 -1
  46. package/packages/tui/lib/config.mjs +7 -2
  47. package/packages/tui/lib/main.mjs +364 -82
  48. package/packages/tui/lib/model.mjs +614 -57
  49. package/packages/tui/lib/panel.mjs +436 -125
  50. package/packages/tui/lib/read.mjs +52 -26
  51. package/packages/tui/lib/store.mjs +1025 -65
  52. package/packages/tui/lib/term/keys.mjs +9 -2
  53. package/packages/tui/lib/term/text.mjs +4 -0
  54. package/packages/tui/lib/term/through.mjs +12 -1
  55. package/packages/tui/lib/views/capabilities.mjs +239 -0
  56. package/packages/tui/lib/views/frame.mjs +433 -99
  57. package/packages/tui/lib/views/help.mjs +61 -15
  58. package/packages/tui/lib/views/instances.mjs +43 -25
  59. package/packages/tui/lib/views/palette.mjs +66 -0
  60. package/packages/tui/lib/views/souls.mjs +270 -0
  61. package/packages/tui/lib/views/spawn.mjs +301 -0
  62. package/packages/tui/lib/views/split.mjs +29 -0
  63. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -1,16 +1,25 @@
1
1
  // The frame: (model, size) -> the rows of the whole screen. Pure: no IO, no clock, no escape
2
2
  // byte. It places the views: the header, the list of instances and the detail beside it (or as a
3
3
  // page of its own on a narrow terminal), an agent's open terminal in the detail's place (or over
4
- // the whole body, zoomed), the switcher of workspaces over the whole body, the help, and the
5
- // footer. The TUI's own words are lit(); everything else is shown(). Meaning never
6
- // rests on colour alone: what is dim or bold also says what it is in words or by a mark.
7
- import { keyLabel } from "../actions.mjs";
8
- import { lit, shown, shownLines } from "../term/text.mjs";
4
+ // the whole body, zoomed), the souls of the open workspace and a soul's detail in the same places,
5
+ // and its capabilities and a capability's detail there too,
6
+ // the switcher of workspaces over the whole body, the palette and the spawn prompt over the whole
7
+ // body too, the help, and the footer. The TUI's own words are lit(); everything else is shown().
8
+ // Meaning never rests on colour alone: what is dim or bold also says what it is in words or by a
9
+ // mark.
10
+ import { LEADER, keyLabel } from "../actions.mjs";
11
+ import { lit, ownEllipsis, shown, shownLines, textOf } from "../term/text.mjs";
9
12
  import { style } from "../term/style.mjs";
10
13
  import { act } from "./act.mjs";
11
14
  import { detail } from "./detail.mjs";
12
15
  import { help, keyText } from "./help.mjs";
13
16
  import { instances, measured } from "./instances.mjs";
17
+ import { textWidth } from "../term/width.mjs";
18
+ import { palette } from "./palette.mjs";
19
+ import { soulDetail, soulsList, soulsListed } from "./souls.mjs";
20
+ import { capabilitiesList, capabilitiesListed, capabilityDetail } from "./capabilities.mjs";
21
+ import { spawn } from "./spawn.mjs";
22
+ import { splitFits, splitRegions } from "./split.mjs";
14
23
  import { switcher } from "./switcher.mjs";
15
24
 
16
25
  /** The frame is drawn from this size up (docs/tui.md); the design size is 80x24. */
@@ -18,16 +27,17 @@ export const MIN_SIZE = Object.freeze({ cols: 60, rows: 15 });
18
27
  /** From this width up the detail stands beside the list; under it, it is a page of its own. */
19
28
  export const WIDE = 80;
20
29
  /** The views, the header's second row: navigation, so no count and no digit stands against a name
21
- * (the help and the footer name the digits). The open one is drawn in reverse; the two that
22
- * cannot be opened yet are dim, and their key says what to run instead. */
23
- const VIEWS = Object.freeze([Object.freeze({ name: "Instances", open: true }), Object.freeze({ name: "Souls", open: false }), Object.freeze({ name: "Capabilities", open: false })]);
30
+ * (the help, the leader's hint and the palette name the keys). The open one is drawn in reverse. */
31
+ const VIEWS = Object.freeze([Object.freeze({ id: "instances", name: "Instances" }), Object.freeze({ id: "souls", name: "Souls" }), Object.freeze({ id: "capabilities", name: "Capabilities" })]);
24
32
  /** The cells between two views' names: each name has one cell on each side of it (the reverse bar
25
33
  * of the open one), and one between. */
26
34
  const VIEW_GAP = 1;
27
35
  const GAP = 3;
28
36
  /** The least width of a terminal beside the list: under it the terminal has the whole body. */
29
37
  export const PANEL_MIN = 40;
30
- /** One cell of margin on each side of the header and the footer. */
38
+ /** The most cells the list keeps beside an open terminal: the agent's screen has the rest. */
39
+ export const LIST_BESIDE = 30;
40
+ /** One cell of margin on each side of the header. The footer has none: its keys start at column 0. */
31
41
  const MARGIN = 1;
32
42
  /** The longest run one lit() holds with room to spare: the display filter bounds a line, and a
33
43
  * terminal can be wider than that bound. */
@@ -36,6 +46,8 @@ const RUN = 500;
36
46
  const REASON_ROWS = 4;
37
47
  /** The rows a deployment's note may take above the list. */
38
48
  const NOTE_ROWS = 2;
49
+ /** The TUI's word before the soul a kept filter of the instances is by. */
50
+ const SOUL_WORD = "soul";
39
51
  /** The cells a kept filter takes in the footer. */
40
52
  const FILTER_COLS = 24;
41
53
  /** What the header holds in the workspace's place while the switcher is shown. */
@@ -73,8 +85,9 @@ function rule(cols, ascii, joint = null) {
73
85
  /** A sentence made of parts (lib/model.mjs OPEN_WORDS): the TUI's own words (`{ own }`) and text
74
86
  * from outside (`{ shown }`, a name), each made safe on its own, so no word of the TUI's is ever
75
87
  * filtered with a name and no name is ever taken for the TUI's. Set on at most `max` rows of at
76
- * most `width` cells, broken at the spaces of the TUI's words; a name and what is written against
77
- * it (a full stop) are never broken apart, and a name wider than a row is cut there. Answers rows
88
+ * most `width` cells, broken at the spaces of the TUI's words but for those of a `{ own, whole }`
89
+ * part (a command: cut in two, it cannot be typed); a name or a whole part and what is written
90
+ * against it (a full stop) are never broken apart, and one wider than a row is cut there. Answers rows
78
91
  * of spans from column 0; when more was left, the last row ends in the cut mark. */
79
92
  export function partRows(parts, width, max, { ascii = false } = {}) {
80
93
  if (width < 1 || max < 1) return [];
@@ -83,7 +96,8 @@ export function partRows(parts, width, max, { ascii = false } = {}) {
83
96
  let glue = false;
84
97
  const put = (piece) => { if (glue && units.length) units.at(-1).push(piece); else units.push([piece]); glue = true; };
85
98
  for (const part of parts) {
86
- if (part.own !== undefined) part.own.split(" ").forEach((word, i) => { if (i > 0) glue = false; if (word) put({ text: lit(word), width: word.length }); });
99
+ if (part.own !== undefined && part.whole) { const own = ownEllipsis(part.own, ascii); put({ text: lit(own), width: own.length }); }
100
+ else if (part.own !== undefined) ownEllipsis(part.own, ascii).split(" ").forEach((word, i) => { if (i > 0) glue = false; if (word) put({ text: lit(word), width: word.length }); });
87
101
  else { const m = measured(part.shown); if (m.width > 0) put(m); }
88
102
  }
89
103
  const unitWidth = (unit) => unit.reduce((sum, piece) => sum + piece.width, 0);
@@ -118,11 +132,14 @@ export function partRows(parts, width, max, { ascii = false } = {}) {
118
132
  * the layout first, because the model's window is as tall, and the sentences in its list as wide,
119
133
  * as the list pane this gives. The answer's `note` is the note's rows and `outcome` the line's:
120
134
  * its sentence and each text under it (what the viewer printed, what the kernel said) set as a
121
- * reason is, on as many rows as a reason may take. */
122
- export function layout(notice, size, { observed = true, note = null, ascii = false, outcome = null } = {}) {
123
- const body = { top: 3, rows: Math.max(0, size.rows - 5) };
135
+ * reason is, on as many rows as a reason may take. While a terminal is open (`terminal`) the
136
+ * list keeps LIST_BESIDE cells at most, whether the terminal or the detail stands beside it, so
137
+ * the agent's screen keeps one size; a name longer than its row is cut there. */
138
+ export function layout(notice, size, { observed = true, note = null, ascii = false, outcome = null, terminal = false } = {}) {
139
+ // The header's two rows and the rule under them, then the body down to the footer's one row.
140
+ const body = { top: 3, rows: Math.max(0, size.rows - 4) };
124
141
  const wide = size.cols >= WIDE;
125
- const listCols = wide ? clamp(Math.floor(size.cols * 0.48), 36, 60) : size.cols;
142
+ const listCols = !wide ? size.cols : terminal ? LIST_BESIDE : clamp(Math.floor(size.cols * 0.48), 36, 60);
126
143
  const across = Math.max(1, size.cols - 2 * MARGIN);
127
144
  const reasonRows = clamp(Math.floor(body.rows / 4), 1, REASON_ROWS);
128
145
  const reason = notice ? shownLines(notice.reason, across, reasonRows, { ascii }) : [];
@@ -172,12 +189,16 @@ function nameSpans(m, col, room) {
172
189
  return [...(width ? [{ col, text: name.text, width }] : []), { col: after(width), text: lit(more), style: DIM, width: more.length }];
173
190
  }
174
191
 
175
- /** The header's counts, right aligned, each a number and a word. When they do not all fit, the
176
- * ones from the shared count are given up from the end, never the two the TUI adds. */
192
+ /** The cells of the header's first row the counts never take: the workspace's name keeps at
193
+ * least NAME_KEPT of them (cut, with the cut mark), and the two after it. */
194
+ const NAME_KEPT = 4;
195
+ /** The header's counts, right aligned, each a number and a word. When they do not all fit beside
196
+ * the least of the workspace's name (NAME_KEPT), the ones from the shared count are given up from
197
+ * the end, never the two the TUI adds. */
177
198
  function countSpans(counts, cols) {
178
199
  const texts = counts.map((count) => ({ ...count, text: `${count.n} ${count.word}` }));
179
200
  const width = (list) => list.reduce((sum, c) => sum + c.text.length, 0) + Math.max(0, list.length - 1) * 2;
180
- const room = cols - 2 * MARGIN - "oats".length - 2;
201
+ const room = cols - 2 * MARGIN - NAME_KEPT - 2;
181
202
  let kept = texts;
182
203
  while (width(kept) > room && kept.some((c) => c.shared)) kept = kept.filter((c, i) => i !== kept.findLastIndex((k) => k.shared));
183
204
  const spans = [];
@@ -186,34 +207,58 @@ function countSpans(counts, cols) {
186
207
  return { spans, start: cols - MARGIN - width(kept) };
187
208
  }
188
209
 
189
- /** The footer: the filter field while it is open; else the actions that apply now, read from the
190
- * effective table, as many as fit, `help` and `quit` last and always: their room is set aside
191
- * first, and a kept filter and the other hints take what is left. The hints stand in the order
210
+ /** The footer, one row from column 0 (docs/tui.md, "The footer"). While the leader waits, its
211
+ * hint (leaderHint). Else, in every focus, first the leader (`C-\ commands`), then: the filter
212
+ * field while it is open; else the actions that apply now, read from the
213
+ * effective table, as many as fit, `help` and `quit` last and always (unless the two do not fit
214
+ * whole after the leader: then `help` goes, then `quit`): their room is set aside first, and a
215
+ * kept filter and the other hints take what is left. The hints stand in the order
192
216
  * given, and when they do not all fit they are given up in an order of their own (`keep`, the
193
217
  * first kept longest), so a hint can stand first and still be given up before another: in the
194
- * list of instances the acts go first (`restart`, `start`, `retire`, then `stop`), then the views
195
- * (one hint for the three, `1-3 views`), then `workspaces`, `refresh`, the key that clears a
196
- * kept filter, `detail`, the open terminal's `close-terminal` and `zoom`, `open` and last `filter`
197
- * (`filter` before `open` while a filter is kept: its own `/` stands in the footer then). A row
198
- * too narrow for the whole of a hint drops it.
218
+ * list of instances the acts go first (`restart`, `start`, `retire`, then `stop`), then
219
+ * `workspaces`, `refresh`, the key that clears a
220
+ * kept filter, the keys that show the tab before and after (`[/] tab`, with two tabs or more in
221
+ * the focused group), `detail`, the open terminal's `close-terminal` and `zoom`, `open` and last `filter`
222
+ * (`filter` before `open` while a filter is kept: its own `/` stands in the footer then); in the
223
+ * Souls view `workspaces`, `refresh`, `filter`, `close`, then `i` and last Enter, and in the
224
+ * Capabilities view the same without `i`. A row
225
+ * too narrow for the whole of a hint drops it. The views have no hint: the header names them.
226
+ * The palette's footer says how to work it: Enter, Up/Down and Esc; the spawn prompt's, how to
227
+ * work its step (spawnHints).
199
228
  * `open` stands first while Enter would open the selected agent's terminal, or (`focus terminal`)
200
229
  * go to the one open on the selected row; while another machine is asked first, the key that
201
230
  * gives the open up stands in its place. With a terminal open, `zoom` and `close-terminal` follow
202
231
  * it; then the acts whose key opens a confirmation for the selected row now (the model's
203
- * `actable`). While the terminal has the focus the TUI reads no key but the back key, and the
204
- * footer names that alone (tui.json's `open.detachKey`, text from outside). In a confirmation the
205
- * buttons are on the screen, and the footer says how to work them: the close key with the close
232
+ * `actable`, which leaves out a secondary act: Retire while a retire runs). While the terminal
233
+ * has the focus the TUI reads no key but the leader, and the footer names it, and the leader
234
+ * twice, which gives the focus back to the list (tui.json's `open.detachKey`, text from
235
+ * outside). In a confirmation the buttons are on the screen, and the footer says how to work
236
+ * them: the close key with the close
206
237
  * button's label, the keys that move, Enter, and `quit`. The switcher has a filter of its own,
207
238
  * drawn as the list's. A key's label is the user's (views/help.mjs keyText); everything is placed
208
239
  * by cells. */
209
240
  function footer(m, cols) {
210
241
  const action = (id) => m.actions.find((a) => a.id === id && a.keys.length);
242
+ // The Souls view has a filter of its own, drawn as the list's; and with a soul selected, what
243
+ // Enter does (from the list it shows the detail, from the detail the soul's instances) stands
244
+ // first, as `open` does in the list, so a kept filter leaves it its room.
245
+ const soul = m.view === "souls" && m.souls ? m.souls : null;
246
+ // The Capabilities view's the same way: from the list Enter shows the detail, and from the detail
247
+ // the marked soul of "Used by" in the Souls view (no hint while none is marked).
248
+ const capability = m.view === "capabilities" && m.capabilities ? m.capabilities : null;
249
+ const filter = soul ? soul.filter : capability ? capability.filter : m.filter;
250
+ // A filter is kept by its text, or in the list of instances by a soul (the Souls view's `i`):
251
+ // drawn `soul <name>` where the text's `/` stands.
252
+ const bySoul = !soul && m.view === "instances" && filter.soul && !filter.query ? filter.soul : null;
253
+ const filtered = Boolean(filter.query) || bySoul !== null;
211
254
  /** A hint: a key and what it does, the TUI's word or safe text with its width. */
212
255
  const made = (key, word) => {
213
256
  const said = typeof word === "string" ? { text: lit(word), width: word.length } : word;
214
257
  return { key, word: said, width: key.width + 1 + said.width };
215
258
  };
216
259
  const hint = (id, label) => { const a = action(id); return a ? made(keyText(keyLabel(a.keys[0])), label ?? a.label) : null; };
260
+ /** `[/] tab`: the keys of `tab-previous` and `tab-next`, while both have one. */
261
+ const tabsHint = () => { const [before, after] = [action("tab-previous"), action("tab-next")]; return before && after ? made(keyText(`${keyLabel(before.keys[0])}/${keyLabel(after.keys[0])}`), "tab") : null; };
217
262
  /** The hints that are no one action's: made below. */
218
263
  const hintOf = {};
219
264
  const edge = cols - MARGIN; // nothing stands at or past it
@@ -225,20 +270,37 @@ function footer(m, cols) {
225
270
  const span = (hints) => hints.reduce((sum, h) => sum + h.width, 0) + Math.max(0, hints.length - 1) * GAP;
226
271
  // A word is drawn as one span, unless it was made of spans already.
227
272
  const spansOf = (h) => ({ ...h, word: { ...h.word, spans: h.word.spans ?? [{ col: 0, text: h.word.text, width: h.word.width }] } });
273
+ /** A hint of keys that are no action's (a key name the TUI writes, like `Enter`). */
274
+ const own = (keys, word) => spansOf(made({ text: lit(keys), width: keys.length }, word));
228
275
 
229
- // While what is typed goes to the agent the TUI takes one key, the back key, and the footer
230
- // names it alone (tui.json's open.detachKey, text from outside), in every such frame: before
231
- // anything else the footer could show.
232
- const listing = m.view !== "help" && m.view !== "switcher";
233
- if (listing && m.terminal?.focus === "terminal") {
234
- const key = keyText(m.detachKey), word = "back to the list";
235
- return [{ col: MARGIN, text: key.text, width: Math.max(0, Math.min(key.width, edge - MARGIN)) },
236
- { col: MARGIN + key.width + 1, text: lit(word), width: Math.max(0, Math.min(word.length, edge - MARGIN - key.width - 1)) }].filter((s) => s.width > 0);
276
+ // While the leader waits for its key, the row is its hint (docs/tui.md, "The leader").
277
+ if (m.leader) return leaderHint(m, edge, put, own);
278
+ // The leader stands first in every focus (tui.json's open.detachKey, text from outside): from
279
+ // it, every action is reached.
280
+ const lead = spansOf(made(keyText(m.detachKey), "commands"));
281
+ const start = lead.width + GAP;
282
+ const led = (spans) => [...put(lead, FOOT), ...spans];
283
+ // While what is typed goes to the agent the TUI takes one key, the leader, and the footer names
284
+ // it and the leader twice, which takes the focus back to the list.
285
+ // The list of instances: what Enter opens, the open terminal's keys and the acts are its own
286
+ // (Souls and Capabilities have none of them, the help and the switcher neither: the Souls view's
287
+ // Enter is its own, below).
288
+ const listing = !["help", "switcher", "souls", "capabilities"].includes(m.view);
289
+ if (listing && m.terminal?.focus === "terminal" && !m.palette && !m.spawn) {
290
+ const twice = keyText(`${m.detachKey} ${m.detachKey}`);
291
+ return led(start + twice.width + 1 + "back to the list".length <= edge ? put(spansOf(made(twice, "back to the list")), start) : []);
237
292
  }
238
- if (m.view !== "help" && m.filter.editing) {
293
+ if (m.palette) {
294
+ const hints = [own("Enter", "run"), own("Up/Down", "move"), own("Esc", "close")], spans = [];
295
+ let col = start;
296
+ for (const h of hints) { if (col + h.width > edge) break; spans.push(...put(h, col)); col += h.width + GAP; }
297
+ return led(spans);
298
+ }
299
+ if (m.spawn) return led(spawnHints(m.spawn, start, edge, put, own, m.ascii));
300
+ if (m.view !== "help" && filter.editing) {
239
301
  const hints = [made({ text: lit("Enter"), width: "Enter".length }, "keep"), hint("close", "clear")].filter(Boolean).map(spansOf);
240
- const spans = [{ col: MARGIN, text: lit("/"), style: BOLD, width: 1 }, { col: MARGIN + 1, text: shown(m.filter.query), width: Math.max(0, edge - span(hints) - GAP - MARGIN - 1) }];
241
- let col = Math.max(MARGIN + 2, edge - span(hints));
302
+ const spans = [...put(lead, FOOT), { col: start, text: lit("/"), style: BOLD, width: 1 }, { col: start + 1, text: shown(filter.query), width: Math.max(0, edge - span(hints) - GAP - start - 1) }];
303
+ let col = Math.max(start + 2, edge - span(hints));
242
304
  for (const h of hints) { spans.push(...put(h, col, { style: DIM })); col += h.width + GAP; }
243
305
  return spans;
244
306
  }
@@ -253,40 +315,53 @@ function footer(m, cols) {
253
315
  const quit = hint("quit");
254
316
  const all = [...hints, ...(quit ? [spansOf(quit)] : [])];
255
317
  const spans = [];
256
- let col = MARGIN;
318
+ let col = start;
257
319
  for (const h of all) { if (col + h.width > edge) break; spans.push(...put(h, col)); col += h.width + GAP; }
258
- return spans;
320
+ return led(spans);
259
321
  }
260
322
  // While another machine is asked first, Esc gives the open up, and that is all it does: the
261
323
  // hint stands where `open` stood, is kept as long, and `close` is not listed beside it.
262
324
  const asking = listing && m.opening?.phase === "preflight";
263
325
  // An action with no key (tui.json may unbind one) has no hint: nothing stands first then. On the
264
326
  // row whose terminal is open, Enter goes to it.
265
- const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.onTerminal ? [["open", hint("open", "focus terminal")]] : listing && m.openable ? [["open", hint("open")]] : []).filter(([, h]) => h);
266
- // With a terminal open, the keys that zoom it and close it stand after `open`, kept as long.
267
- const terminal = listing && m.terminal ? [["zoom", hint("zoom")], ["close-terminal", hint("close-terminal")]].filter(([, h]) => h) : [];
327
+ const first = (asking ? [["open", hint("close", "stop opening")]] : listing && m.onTerminal ? [["open", hint("open", "focus terminal")]] : listing && m.openable ? [["open", hint("open")]]
328
+ : soul?.detail ? [["open", hint("open", soul.focus === "detail" ? "instances" : "detail")]]
329
+ : capability?.detail ? (capability.focus !== "detail" ? [["open", hint("open", "detail")]] : capability.mark >= 0 ? [["open", hint("open", "soul")]] : []) : []).filter(([, h]) => h);
330
+ // With a terminal open, the keys that zoom it and close it stand after `open`, kept as long;
331
+ // with two tabs or more in the focused group, then the keys that show the tab before and after.
332
+ const terminal = listing && m.terminal ? [["zoom", hint("zoom")], ["close-terminal", hint("close-terminal")], ...((m.tabs?.length ?? 0) > 1 ? [["tabs", tabsHint()]] : [])].filter(([, h]) => h) : [];
268
333
  // The acts the selected row offers now stand after those, and are the first given up.
269
334
  const acts = listing && !asking ? (m.actable ?? []).map((verb) => [verb, hint(verb)]).filter(([, h]) => h) : [];
270
335
  const ACTS = ["stop", "retire", "start", "restart"];
271
- // The three views are one hint, `views`, named by their keys: `1-3` while they are the digits
272
- // in order, else each key (tui.json may rebind one), and a view with no key left out. The
273
- // header shows which views there are; the help names each key.
274
- const viewKeys = ["instances", "souls", "capabilities"].map((id) => action(id)).filter(Boolean).map((a) => keyLabel(a.keys[0]));
275
- const views = viewKeys.length === 0 ? null : made(keyText(viewKeys.join("") === "123" ? "1-3" : viewKeys.join("/")), "views");
276
- hintOf.views = views;
277
- const VIEW_KEYS = ["views"];
336
+ // The views have no hint: the header names them, and the leader's hint and the help their keys.
337
+ const VIEW_KEYS = [];
278
338
  const [ids, keep] = m.view === "help" ? [["close"], ["close"]]
339
+ // The Souls view: after Enter, `i` shows the selected soul's instances, then the filter, a
340
+ // read again, Esc and the workspaces. They are given up from the end of `keep`: the workspaces
341
+ // first, then `refresh`, `filter` and `close`; `i` and Enter last. With no workspace of this
342
+ // machine there is nothing to filter or read: Esc and the workspaces only. No spawn hint: the
343
+ // help names n and N.
344
+ : soul ? (soul.local === false ? [["close", "workspaces"], ["close", "workspaces"]]
345
+ : [[...(soul.detail ? ["soul-instances"] : []), "filter", "refresh", "close", "workspaces"], ["open", "soul-instances", "close", "filter", "refresh", "workspaces"]])
346
+ // The Capabilities view: the filter, a read again, Esc and the workspaces, given up from the
347
+ // workspaces on; Enter last. With no workspace of this machine, Esc and the workspaces only.
348
+ : capability ? (capability.local === false ? [["close", "workspaces"], ["close", "workspaces"]]
349
+ : [["filter", "refresh", "close", "workspaces"], ["open", "close", "filter", "refresh", "workspaces"]])
279
350
  // Esc closes the switcher only onto a view, and there is none before a workspace is opened.
280
351
  // A kept filter puts `close` before `refresh`, as in the list: the key that clears it is the hint to keep.
281
352
  : m.view === "switcher" ? [["open", "filter", ...(m.filter.query ? ["close", "refresh"] : ["refresh", ...(m.open ? ["close"] : [])])], null]
282
- : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "close", "refresh", ...ACTS]]
353
+ : m.focus === "detail" ? [["detail", "close", "refresh"], ["open", "zoom", "close-terminal", "detail", "tabs", "close", "refresh", ...ACTS]]
283
354
  // A kept filter shows its own `/` beside the hints: then `open` outlives the `/ filter` hint.
284
- : [["filter", "detail", ...(m.filter.query ? ["close"] : []), "refresh", "workspaces", ...VIEW_KEYS], [...(m.filter.query ? ["open", "zoom", "close-terminal", "filter"] : ["filter", "open", "zoom", "close-terminal"]), "detail", "close", "refresh", "workspaces", ...VIEW_KEYS, ...ACTS]];
355
+ : [["filter", "detail", ...(filtered ? ["close"] : []), "refresh", "workspaces", ...VIEW_KEYS], [...(filtered ? ["open", "zoom", "close-terminal", "filter"] : ["filter", "open", "zoom", "close-terminal"]), "detail", "tabs", "close", "refresh", "workspaces", ...VIEW_KEYS, ...ACTS]];
285
356
  const hints = [...first, ...terminal, ...acts, ...ids.filter((id) => !(asking && id === "close")).map((id) => [id, id in hintOf ? hintOf[id] : hint(id)])].filter(([, h]) => h).map(([id, h]) => [id, spansOf(h)]);
286
- const last = ["help", "quit"].map((id) => hint(id)).filter(Boolean).map(spansOf);
287
- const spans = [];
288
- let col = MARGIN;
289
- if (m.view !== "help" && m.filter.query) {
357
+ // `help` and `quit` stand last, and always but in one case: when the two do not fit whole
358
+ // after the leader (keys tui.json made long), `help` is given up, then `quit`. The leader
359
+ // reaches the help too, and a hint is never cut.
360
+ let last = ["help", "quit"].map((id) => hint(id)).filter(Boolean).map(spansOf);
361
+ while (last.length && start + span(last) > edge) last = last.slice(1);
362
+ const spans = put(lead, FOOT);
363
+ let col = start;
364
+ if (m.view !== "help" && filtered) {
290
365
  // The kept filter has a place of its own width, so the hints stand where they always do;
291
366
  // it gives way, down to nothing, before `help` and `quit` do, and before the hint that
292
367
  // stands first while Enter would open an agent (or Esc gives an open up).
@@ -294,9 +369,12 @@ function footer(m, cols) {
294
369
  // cannot stand takes no room from the filter.
295
370
  const firstFits = first.length > 0 && col + first[0][1].width + GAP + span(last) <= edge;
296
371
  const held = firstFits ? first[0][1].width + GAP : 0;
297
- const slot = Math.min(FILTER_COLS - GAP, edge - MARGIN - span(last) - (last.length ? GAP : 0) - held);
298
- if (slot >= 2) {
299
- spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(m.filter.query), style: BOLD, width: slot - 1 });
372
+ const slot = Math.min(FILTER_COLS - GAP, edge - col - span(last) - (last.length ? GAP : 0) - held);
373
+ if (bySoul && slot >= SOUL_WORD.length + 2) {
374
+ spans.push({ col, text: lit(SOUL_WORD), style: BOLD, width: SOUL_WORD.length }, { col: col + SOUL_WORD.length + 1, text: shown(bySoul.name), style: BOLD, width: slot - SOUL_WORD.length - 1 });
375
+ col += slot + GAP;
376
+ } else if (!bySoul && slot >= 2) {
377
+ spans.push({ col, text: lit("/"), style: BOLD, width: 1 }, { col: col + 1, text: shown(filter.query), style: BOLD, width: slot - 1 });
300
378
  col += slot + GAP;
301
379
  }
302
380
  }
@@ -313,6 +391,60 @@ function footer(m, cols) {
313
391
  return spans;
314
392
  }
315
393
 
394
+ /** The footer's first column. */
395
+ const FOOT = 0;
396
+ /** The spawn prompt's hints after the leader (docs/tui.md, "Spawning an agent"): the keys the
397
+ * prompt reads are its own, as the palette's are, so they are the TUI's words. The picker: Enter
398
+ * picks, Up/Down move, Esc closes. The preview: Enter and what it does at the focus (the model's
399
+ * `enter`; none while Enter does nothing), Tab and Shift+Tab move the focus, Esc goes back. A hint
400
+ * that does not fit whole is given up, in an order of its own: in the preview Shift+Tab first,
401
+ * then Tab, then Esc, Enter last; in the picker from the end, as the palette's. */
402
+ function spawnHints(s, start, edge, put, own, ascii) {
403
+ const hints = s.step === "picker" ? [own("Enter", "pick"), own("Up/Down", "move"), own("Esc", "close")]
404
+ : [...(s.enter ? [own("Enter", ownEllipsis(s.enter, ascii))] : []), own("Tab", "next"), own("Shift+Tab", "back"), own("Esc", "back")];
405
+ // The least kept first: Shift+Tab, Tab, Esc, then Enter.
406
+ const order = s.step === "picker" ? [...hints].reverse() : [hints.at(-2), hints.at(-3), hints.at(-1), ...(s.enter ? [hints[0]] : [])];
407
+ let kept = hints;
408
+ const width = (list) => list.reduce((sum, h) => sum + h.width, 0) + Math.max(0, list.length - 1) * GAP;
409
+ for (const least of order) { if (start + width(kept) <= edge) break; kept = kept.filter((h) => h !== least); }
410
+ const spans = [];
411
+ let col = start;
412
+ for (const h of kept) { spans.push(...put(h, col)); col += h.width + GAP; }
413
+ return spans;
414
+ }
415
+ /** The leader's hint (docs/tui.md, "The leader"): the leader's key, then what each key after it
416
+ * does, from actions.mjs LEADER, the views, the instances and the acts each one hint. The keys
417
+ * that need a terminal are named only while one is open, the tabs' only with two or more, and the
418
+ * split's only where they apply.
419
+ * Hints are given up from the end until the rest fit, the last, the list's, never. */
420
+ function leaderHint(m, edge, put, own) {
421
+ const by = (does) => LEADER.find((entry) => entry.does === does);
422
+ const one = (does) => { const entry = by(does); return own(keyLabel(entry.keys[0]), entry.label); };
423
+ const keysOf = (list) => list.map((does) => keyLabel(by(does).keys[0])).join("/");
424
+ const hints = [
425
+ own(keyLabel(by("palette").keys[0]), "palette"),
426
+ own(keysOf(["instances", "souls", "capabilities"]) === "1/2/3" ? "1-3" : keysOf(["instances", "souls", "capabilities"]), "views"),
427
+ own(keysOf(["previous", "next"]), "instance"),
428
+ ...(m.terminal ? [one("zoom"), one("close-terminal")] : []),
429
+ // With two tabs or more, the keys that move between them.
430
+ ...((m.tabs?.length ?? 0) > 1 ? [own(keysOf(["tab-previous", "tab-next"]), "tab")] : []),
431
+ // The split's (docs/tui.md, "Splits"): to split while there is one group; with two, the next
432
+ // group, and the move of the shown tab, or the close of the focused group while it is empty.
433
+ ...(m.panelOpen && !m.split ? [own(keysOf(["split-right", "split-down"]), "split")] : []),
434
+ ...(m.split ? [one("group-next"), ...(m.terminal ? [one("tab-move")] : [one("group-close")])] : []),
435
+ own(keysOf(["stop", "restart", "start", "retire"]), "acts"),
436
+ one("filter"), one("workspaces"), one("help"),
437
+ ];
438
+ const last = one("list"), key = keyText(m.detachKey);
439
+ const width = (list) => list.reduce((sum, h) => sum + h.width + GAP, 0);
440
+ let kept = hints;
441
+ while (kept.length && key.width + GAP + width(kept) + last.width > edge) kept = kept.slice(0, -1);
442
+ const spans = [{ col: FOOT, text: key.text, style: BOLD, width: Math.min(key.width, edge) }];
443
+ let col = key.width + GAP;
444
+ for (const h of [...kept, last]) { if (col + h.width > edge) break; spans.push(...put(h, col)); col += h.width + GAP; }
445
+ return spans;
446
+ }
447
+
316
448
  /** Shift a pane's rows to its place on the screen. */
317
449
  const placed = (spans, col) => spans.map((span) => ({ ...span, col: span.col + col }));
318
450
 
@@ -320,38 +452,60 @@ const placed = (spans, col) => spans.map((span) => ({ ...span, col: span.col + c
320
452
  * pane (of the whole body, for the switcher); `extent` and `room` are how many rows the other
321
453
  * scrolling pane (the help, else the detail) holds and shows. The main loop hands the three back
322
454
  * with the next key, so the store scrolls by what is on the screen without holding a size. */
455
+ /** The frame for model `m` at `size`: its rows, the paging the store scrolls by, the cursor, and
456
+ * for the loop (lib/main.mjs fitPanel) `regions`, each group of the panel this frame draws, empty
457
+ * when it draws none (another view, an overlay, a screen too small). */
323
458
  export function frame(m, size) {
459
+ const made = framed(m, size);
460
+ return made.regions ? made : { ...made, regions: [] };
461
+ }
462
+ function framed(m, size) {
324
463
  if (tooSmall(size)) return { rows: tooSmallRows(size), page: 1, extent: 0, room: 1 };
325
464
  const rows = Array.from({ length: size.rows }, () => []);
326
- const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome });
465
+ const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome, terminal: panelOpen(m) });
327
466
  const { cols } = size;
328
467
  // The switcher is no view of the three: while it is shown, or is under the help, none is current.
329
468
  const listing = m.under === "switcher";
330
469
 
331
470
  const counts = countSpans(m.counts, cols);
332
- const nameCol = MARGIN + "oats".length + 2;
333
- rows[0] = [{ col: MARGIN, text: lit("oats"), style: BOLD }, ...nameSpans(m, nameCol, counts.start - 2 - nameCol), ...counts.spans];
471
+ // The header starts with the workspace's name: no title before it.
472
+ rows[0] = [...nameSpans(m, MARGIN, counts.start - 2 - MARGIN), ...counts.spans];
334
473
  let col = MARGIN;
335
474
  for (const view of VIEWS) {
336
- // The Instances view is the open one but while the switcher is shown: then none is.
337
- const look = !view.open ? DIM : listing ? null : REVERSE;
338
- if (look === REVERSE) rows[1].push({ col, width: view.name.length + 2, style: REVERSE });
339
- rows[1].push({ col: col + 1, text: lit(view.name), ...(look ? { style: look } : {}), width: view.name.length });
475
+ // The open view is in reverse; while the switcher is shown none is open.
476
+ const open = view.id === m.under;
477
+ if (open) rows[1].push({ col, width: view.name.length + 2, style: REVERSE });
478
+ rows[1].push({ col: col + 1, text: lit(view.name), ...(open ? { style: REVERSE } : {}), width: view.name.length });
340
479
  col += view.name.length + 2 + VIEW_GAP;
341
480
  }
342
481
  if (m.readAt) { const read = `read ${m.readAt}`; rows[1].push({ col: cols - MARGIN - read.length, text: lit(read), style: DIM, width: read.length }); }
343
482
  rows[size.rows - 1] = footer(m, cols);
344
483
 
484
+ // The palette over the whole body, whatever is under it.
485
+ if (m.palette) {
486
+ rows[2] = rule(cols, m.ascii);
487
+ const drawn = palette(m, { cols, rows: g.body.rows });
488
+ drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
489
+ return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1, cursor: { row: g.body.top, col: drawn.cursor } };
490
+ }
491
+ // The spawn prompt in the same place (the palette wins if both are ever set). `extent` and `room`
492
+ // are its preview's, which the store scrolls as it scrolls a confirmation; `drawnTop` the
493
+ // row its window was drawn from, which the loop gives the store once the frame is written; `armed` says the ready
494
+ // Spawn button is drawn, which the loop tells the store once the frame is written.
495
+ if (m.spawn) {
496
+ rows[2] = rule(cols, m.ascii);
497
+ const drawn = spawn(m, { cols, rows: g.body.rows });
498
+ drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
499
+ return { rows, page: Math.max(1, g.body.rows), extent: drawn.extent, room: drawn.room, ...(drawn.top !== undefined ? { drawnTop: drawn.top } : {}), cursor: drawn.cursor ? { row: g.body.top + drawn.cursor.row, col: drawn.cursor.col } : null, ...(drawn.armed ? { armed: true } : {}) };
500
+ }
345
501
  if (m.view === "act" && m.act) {
346
502
  rows[2] = rule(cols, m.ascii);
347
- rows[size.rows - 2] = rule(cols, m.ascii);
348
503
  const drawn = act(m, { cols, rows: g.body.rows });
349
504
  drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
350
505
  return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: drawn.room };
351
506
  }
352
507
  if (m.view === "help") {
353
508
  rows[2] = rule(cols, m.ascii);
354
- rows[size.rows - 2] = rule(cols, m.ascii);
355
509
  const drawn = help(m.actions, { cols, rows: g.body.rows }, { top: m.helpTop, ascii: m.ascii, detachKey: m.detachKey });
356
510
  drawn.rows.forEach((spans, i) => { rows[g.body.top + i] = spans; });
357
511
  return { rows, page: Math.max(1, g.page), extent: drawn.extent, room: g.body.rows };
@@ -361,7 +515,6 @@ export function frame(m, size) {
361
515
  // Nothing beside it scrolls on its own.
362
516
  if (listing) {
363
517
  rows[2] = rule(cols, m.ascii);
364
- rows[size.rows - 2] = rule(cols, m.ascii);
365
518
  switcher(m, { cols, rows: g.body.rows }).forEach((spans, i) => { rows[g.body.top + i] = spans; });
366
519
  return { rows, page: Math.max(1, g.body.rows), extent: 0, room: 1 };
367
520
  }
@@ -378,6 +531,8 @@ export function frame(m, size) {
378
531
  for (const line of g.note) said.push([{ col: MARGIN, text: line, width: cols - 2 * MARGIN }]);
379
532
  for (const spans of g.outcome) said.push(placed(spans, MARGIN));
380
533
  said.slice(0, g.above).forEach((spans, i) => { rows[g.body.top + i] = spans; });
534
+ if (m.view === "souls" && m.souls) return soulsFrame(m, size, g, rows);
535
+ if (m.view === "capabilities" && m.capabilities) return capabilitiesFrame(m, size, g, rows);
381
536
  const area = terminalAt(m, size, g);
382
537
  const zoomed = area !== null && area.whole;
383
538
  const paged = !zoomed && !g.wide && m.focus === "detail" && m.detail;
@@ -388,8 +543,7 @@ export function frame(m, size) {
388
543
  // The rule that opens the panes: the one under the header, or the one under the reason and the note.
389
544
  const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
390
545
  rows[2] = rule(cols, m.ascii, opening === 2 ? joint : null);
391
- if (opening !== 2 && opening < size.rows - 2) rows[opening] = rule(cols, m.ascii, joint);
392
- rows[size.rows - 2] = rule(cols, m.ascii, joint && { ...joint, up: true });
546
+ if (opening !== 2 && opening < size.rows - 1) rows[opening] = rule(cols, m.ascii, joint);
393
547
 
394
548
  const pane = { cols: g.wide ? g.listCols : cols, rows: g.panes.rows };
395
549
  let extent = 0;
@@ -397,56 +551,236 @@ export function frame(m, size) {
397
551
  const bar = split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : [];
398
552
  if (area !== null) {
399
553
  for (let i = 0; i < g.panes.rows; i++) rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar];
400
- terminalRows(m, area).forEach((spans, i) => { rows[area.title + i] = [...rows[area.title + i], ...spans]; });
554
+ for (const region of area.regions) regionRows(m, region).forEach((spans, i) => { rows[region.title + i] = [...rows[region.title + i], ...spans]; });
555
+ // The rule between two groups: a column side by side, a row one above the other.
556
+ const p = area.panel, r = area.rule;
557
+ if (r?.col !== undefined) for (let i = 0; i <= p.rows; i++) rows[p.title + i] = [...rows[p.title + i], { col: r.col, text: lit(m.ascii ? "|" : "\u2502"), style: DIM, width: 1 }];
558
+ // Beside the list, the row meets the list's bar there: a joint (`├`, `+` in ASCII).
559
+ if (r?.row !== undefined) rows[r.row] = [...rows[r.row], ...(split && p.col === g.listCols + 1 ? [{ col: g.listCols, text: lit(m.ascii ? "+" : "\u251c"), style: DIM, width: 1 }] : []), { col: p.col, text: lit((m.ascii ? "-" : "\u2500").repeat(p.cols)), style: DIM, width: p.cols }];
401
560
  } else if (split || paged) {
402
561
  const at = paged ? MARGIN : g.listCols + 2;
403
562
  const drawn = detail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
404
563
  extent = drawn.extent;
405
564
  drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar, ...placed(spans, at)]; });
406
565
  }
407
- // The agent's cursor, where the agent has it, while what is typed goes to the agent.
408
- const agent = area !== null && m.terminal.focus === "terminal" ? m.screen?.cursor : null;
409
- const cursor = agent?.visible && agent.y < area.rows && agent.x < area.cols ? { row: area.top + agent.y, col: area.col + agent.x } : null;
410
- return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows), terminal: area, cursor };
566
+ // The focused group's terminal, when it shows one: the agent's cursor, where the agent has it,
567
+ // while what is typed goes to the agent.
568
+ 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;
569
+ const agent = shownArea !== null && m.terminal.focus === "terminal" ? m.screen?.cursor : null;
570
+ const cursor = agent?.visible && agent.y < shownArea.rows && agent.x < shownArea.cols ? { row: shownArea.top + agent.y, col: shownArea.col + agent.x } : null;
571
+ // The regions the loop gives the panel (lib/main.mjs): each group drawn, its shown tab's id and
572
+ // its size; and the panel's room as the terminal's focus would give it, for a split's size.
573
+ const regions = area === null ? [] : area.regions.map(({ group, id, focused, cols: c, rows: r }) => ({ group, id, focused, cols: c, rows: r }));
574
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows), terminal: shownArea, cursor, regions };
575
+ }
576
+
577
+ /** The Souls view in the panes of the list (views/souls.mjs), under the header and what stands
578
+ * above the panes: the souls in the list's place and width, and beside them, past the panes'
579
+ * rule, the selected soul's detail; under WIDE columns the list alone, and the detail in its
580
+ * place while it has the focus. A body of one sentence (reading, a failed first read, an empty
581
+ * catalog, no workspace of this machine) has the whole width, with no pane beside it. */
582
+ function soulsFrame(m, size, g, rows) {
583
+ const { cols } = size, s = m.souls;
584
+ const paged = !g.wide && s.focus === "detail" && Boolean(s.detail);
585
+ const split = g.wide && g.panes.rows > 0 && soulsListed(s);
586
+ const joint = split ? { col: g.listCols } : null;
587
+ const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
588
+ rows[2] = rule(cols, m.ascii, opening === 2 ? joint : null);
589
+ if (opening !== 2 && opening < size.rows - 1) rows[opening] = rule(cols, m.ascii, joint);
590
+ if (!paged) soulsList(m, { cols: split ? g.listCols : cols, rows: g.panes.rows }).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
591
+ let extent = 0;
592
+ if (split || paged) {
593
+ const at = paged ? MARGIN : g.listCols + 2;
594
+ const bar = split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : [];
595
+ const drawn = soulDetail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
596
+ extent = drawn.extent;
597
+ drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar, ...placed(spans, at)]; });
598
+ }
599
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows) };
600
+ }
601
+
602
+ /** The Capabilities view in the panes of the list (views/capabilities.mjs), as the Souls view: the
603
+ * capabilities in the list's place and width, and beside them the selected capability's detail;
604
+ * under WIDE columns the list alone, and the detail in its place while it has the focus. A body of
605
+ * one sentence has the whole width. `capabilitiesTop` is the row the detail was drawn from, which
606
+ * the loop gives the store once the frame is written (it keeps the marked soul in sight). */
607
+ function capabilitiesFrame(m, size, g, rows) {
608
+ const { cols } = size, c = m.capabilities;
609
+ const paged = !g.wide && c.focus === "detail" && Boolean(c.detail);
610
+ const split = g.wide && g.panes.rows > 0 && capabilitiesListed(c);
611
+ const joint = split ? { col: g.listCols } : null;
612
+ const opening = m.observed && g.above > 0 ? g.panes.top - 1 : 2;
613
+ rows[2] = rule(cols, m.ascii, opening === 2 ? joint : null);
614
+ if (opening !== 2 && opening < size.rows - 1) rows[opening] = rule(cols, m.ascii, joint);
615
+ if (!paged) capabilitiesList(m, { cols: split ? g.listCols : cols, rows: g.panes.rows }).forEach((spans, i) => { rows[g.panes.top + i] = spans; });
616
+ let extent = 0, top;
617
+ if (split || paged) {
618
+ const at = paged ? MARGIN : g.listCols + 2;
619
+ const bar = split ? [{ col: g.listCols, text: lit(m.ascii ? "|" : "│"), style: DIM, width: 1 }] : [];
620
+ const drawn = capabilityDetail(m, { cols: Math.max(0, cols - at - MARGIN), rows: g.panes.rows });
621
+ extent = drawn.extent;
622
+ top = drawn.top;
623
+ drawn.rows.forEach((spans, i) => { rows[g.panes.top + i] = [...rows[g.panes.top + i], ...bar, ...placed(spans, at)]; });
624
+ }
625
+ return { rows, page: Math.max(1, g.page), extent, room: Math.max(1, g.panes.rows), ...(top !== undefined ? { capabilitiesTop: top } : {}) };
411
626
  }
412
627
 
413
628
  /** Where the open terminal stands for a model and a size, or null while it is not shown (no
414
629
  * terminal; another view over the body; the detail in its place; the list's focus on a terminal
415
- * too narrow for it beside the list). `{ title, top, col, cols, rows, whole }`: `title` is the row
416
- * that names the agent, and the agent's screen is `rows` rows of `cols` cells from (`top`, `col`)
417
- * (the size the panel gives the viewer). With the terminal's focus it has the whole body when it is
630
+ * too narrow for it beside the list). `{ title, top, col, cols, rows, whole }`, the focused
631
+ * group's: `title` is the row that names the agent, and the agent's screen is `rows` rows of
632
+ * `cols` cells from (`top`, `col`) (the size the panel gives the viewer); with `panel` the whole
633
+ * panel's place, `regions` each group drawn (`group`, `id` its shown tab's or null, `focused`),
634
+ * and `rule` between two (views/split.mjs). With the terminal's focus it has the whole body when it is
418
635
  * zoomed, under WIDE columns, and when the side beside the list would be under PANEL_MIN cells
419
636
  * (`whole`); else it stands beside the list, edge to edge, in the detail's place. */
420
637
  export function terminalArea(m, size) {
421
638
  if (tooSmall(size)) return null;
422
- return terminalAt(m, size, layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome }));
639
+ return terminalAt(m, size, layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome, terminal: panelOpen(m) }));
640
+ }
641
+ /** Where the panel stands as the Instances view gives it with the terminal's focus, whatever this
642
+ * frame draws (an overlay, another view, the list's focus): `{ panel, focused }`, the panel's
643
+ * room with its strip row counted (what a split is measured against: lib/store.mjs
644
+ * splitRefused) and the focused group's screen (`{ cols, rows }`, what a viewer opened now starts
645
+ * at), or null on a screen too small. */
646
+ export function panelPlace(m, size) {
647
+ if (tooSmall(size)) return null;
648
+ const g = layout(m.notice, size, { observed: m.observed, note: m.note, ascii: m.ascii, outcome: m.outcome, terminal: true });
649
+ const area = terminalAt({ ...m, view: "instances", under: "instances", palette: null, spawn: null, panelOpen: true, terminal: { ...(m.terminal ?? {}), focus: "terminal" } }, size, g);
650
+ return { panel: panelRoom(size, g), focused: area === null ? null : { cols: area.cols, rows: area.rows } };
651
+ }
652
+ /** Whether the panel stands: a tab is open (a model made by hand may name only its terminal). */
653
+ const panelOpen = (m) => Boolean(m.panelOpen) || Boolean(m.terminal);
654
+ /** The panel's groups, or one made of the terminal for a model that names no groups. */
655
+ const groupsIn = (m) => m.groups ?? [{ tabs: m.tabs ?? [], shown: m.terminal?.id ?? null }];
656
+ /** The panel's size as the terminal's focus would give it, its strip row counted: what a split
657
+ * is measured against (lib/store.mjs splitRefused). */
658
+ function panelRoom(size, g) {
659
+ const side = size.cols - g.listCols - 1;
660
+ return { cols: !g.wide || side < PANEL_MIN ? size.cols : side, rows: g.panes.rows };
423
661
  }
424
662
  function terminalAt(m, size, g) {
425
663
  const t = m.terminal;
426
- if (!t || m.view !== "instances" || m.under === "switcher" || g.panes.rows < 2) return null;
664
+ if (!panelOpen(m) || m.view !== "instances" || m.under === "switcher" || m.palette || m.spawn || g.panes.rows < 2) return null;
665
+ const focus = t?.focus ?? "list", zoom = Boolean(t?.zoom);
427
666
  const side = size.cols - g.listCols - 1;
428
667
  const narrow = !g.wide || side < PANEL_MIN;
429
- const whole = t.focus === "terminal" && (t.zoom || narrow);
668
+ const whole = focus === "terminal" && (zoom || narrow);
430
669
  // From the list's focus it stands beside the list, unless the detail stands there or there is no room.
431
- if (t.focus !== "terminal" && (m.focus === "detail" || narrow)) return null;
670
+ if (focus !== "terminal" && (m.focus === "detail" || narrow)) return null;
432
671
  const col = whole ? 0 : g.listCols + 1;
433
- return { title: g.panes.top, top: g.panes.top + 1, col, cols: whole ? size.cols : side, rows: g.panes.rows - 1, whole };
672
+ const panel = { title: g.panes.top, top: g.panes.top + 1, col, cols: whole ? size.cols : side, rows: g.panes.rows - 1 };
673
+ // Both groups while the panel holds them and nothing is zoomed; else the focused one alone, the
674
+ // other kept (Settled 3 of T3).
675
+ const groups = groupsIn(m), focused = m.group ?? 0;
676
+ const both = Boolean(m.split) && !zoom && groups.length === 2 && splitFits(m.split, { cols: panel.cols, rows: panel.rows + 1 });
677
+ const [first, second, rule] = both ? splitRegions(panel, m.split) : [panel, null, null];
678
+ const regions = (both ? [{ ...first, group: 0 }, { ...second, group: 1 }] : [{ ...panel, group: focused }])
679
+ .map((r) => ({ ...r, id: groups[r.group]?.shown ?? null, focused: r.group === focused, whole }));
680
+ return { ...regions.find((r) => r.focused), panel, regions, rule };
681
+ }
682
+
683
+ /** A hidden tab's mark for output since it was last shown (docs/tui.md, "Tabs"). */
684
+ const ACTIVITY = "\u2022";
685
+
686
+ /** The tab strip (docs/tui.md, "Tabs"), the panel's top row with two tabs or more: each tab in
687
+ * order as ` name ` (and ` on machine`, dim, for another machine's agent), the shown one bold, in
688
+ * reverse while what is typed goes to it, a hidden one plain with `•` after its name when its
689
+ * agent wrote since it was shown. What does not fit is cut in this order: the hidden tabs'
690
+ * machines, then their names, each to an equal share of what the shown tab leaves with `…`, then
691
+ * the shown tab's machine, then the hidden tabs farthest from the shown one are left out. The
692
+ * shown tab's name stays whole while the row can hold it. */
693
+ function stripRow(given, area, { focused, ascii }) {
694
+ const mark = ascii ? "*" : ACTIVITY;
695
+ const tabs = given.map((tab) => ({ ...tab, name: measured(tab.name), machine: tab.machine === null ? null : measured(tab.machine), mark: !tab.shown && tab.activity }));
696
+ const machineCells = (tab) => (tab.machine ? 1 + ON.length + 1 + tab.machine.width : 0);
697
+ const cellsOf = (tab, { machine, name = tab.name.width, dropped = false }) => (dropped ? 0 : 1 + name + (tab.mark ? 1 : 0) + (machine ? machineCells(tab) : 0) + 1);
698
+ const total = (plan) => tabs.reduce((sum, tab, i) => sum + cellsOf(tab, plan[i]), 0);
699
+ const plan = tabs.map((tab) => ({ machine: true, name: tab.name.width, dropped: false }));
700
+ const fits = () => total(plan) <= area.cols;
701
+ const shown = tabs.findIndex((tab) => tab.shown);
702
+ // The least a hidden tab is drawn in: a cell of its name (the cut mark), its mark, a cell each side.
703
+ const least = (tab) => 3 + (tab.mark ? 1 : 0);
704
+ // The shown tab's cells are taken first; the hidden ones share the rest equally. Those that do
705
+ // not get even their least are left out, the farthest from the shown tab first.
706
+ const share = () => {
707
+ let left = area.cols - cellsOf(tabs[shown], plan[shown]);
708
+ const near = tabs.map((tab, i) => i).filter((i) => i !== shown).sort((a, b) => Math.abs(a - shown) - Math.abs(b - shown) || a - b);
709
+ const kept = [];
710
+ for (const i of near) { plan[i].dropped = left - least(tabs[i]) < 0; if (!plan[i].dropped) { kept.push(i); left -= least(tabs[i]); } }
711
+ const room = area.cols - cellsOf(tabs[shown], plan[shown]), each = Math.floor(room / Math.max(1, kept.length));
712
+ for (const i of kept) plan[i].name = Math.max(1, Math.min(tabs[i].name.width, each - 2 - (tabs[i].mark ? 1 : 0)));
713
+ while (!fits() && kept.length) plan[kept.pop()].dropped = true;
714
+ };
715
+ if (!fits()) tabs.forEach((tab, i) => { if (i !== shown) plan[i].machine = false; });
716
+ if (!fits()) share();
717
+ if (plan.some((p) => p.dropped) && plan[shown].machine && tabs[shown].machine) { plan[shown].machine = false; plan.forEach((p) => { p.dropped = false; }); share(); }
718
+ const row = [];
719
+ let col = area.col;
720
+ const end = area.col + area.cols;
721
+ tabs.forEach((tab, i) => {
722
+ if (col >= end || plan[i].dropped) return;
723
+ const p = plan[i], width = Math.min(cellsOf(tab, p), end - col);
724
+ const style = tab.shown ? (focused ? FOCUSED : BOLD) : null;
725
+ const name = p.name < tab.name.width ? shownLines(textOf(tab.name.text), p.name, 1, { ascii })[0] ?? lit("") : tab.name.text;
726
+ const nameWidth = Math.min(p.name, textWidth(textOf(name)), end - col - 1);
727
+ // In reverse, as T1's title: the name with a cell on each side; its machine stays dim.
728
+ if (tab.shown && focused) row.push({ col, width: Math.min(nameWidth + 2, end - col), style: FOCUSED });
729
+ if (nameWidth > 0) row.push({ col: col + 1, text: name, width: nameWidth, ...(style ? { style } : {}) });
730
+ let at = col + 1 + nameWidth;
731
+ if (tab.mark && at < end) { row.push({ col: at, text: lit(mark), width: 1 }); at += 1; }
732
+ if (p.machine && tab.machine && at + 1 + ON.length + 1 < end) {
733
+ row.push({ col: at + 1, text: lit(ON), style: DIM, width: ON.length });
734
+ row.push({ col: at + 2 + ON.length, text: tab.machine.text, style: DIM, width: Math.max(0, Math.min(tab.machine.width, end - (at + 2 + ON.length))) });
735
+ }
736
+ col += width;
737
+ });
738
+ return row;
434
739
  }
435
740
 
436
741
  /** The open terminal's rows from its title row: the agent's name (and its machine, when it is
437
- * another's), in reverse while what is typed goes to it, then the agent's screen as the last
438
- * capture made it (lib/panel.mjs, term/capture.mjs: spans of the agent's own text and styles), each
439
- * row placed at the terminal's first column and kept inside its cells. */
440
- function terminalRows(m, area) {
441
- const t = m.terminal, focused = t.focus === "terminal";
442
- const name = measured(t.name), title = [];
443
- if (focused) title.push({ col: area.col, width: Math.min(area.cols, name.width + 2), style: FOCUSED });
444
- title.push({ col: area.col + 1, text: name.text, style: focused ? FOCUSED : BOLD, width: Math.max(0, Math.min(name.width, area.cols - 2)) });
445
- if (t.routed && t.machine !== null) {
446
- const where = measured(t.machine), at = area.col + name.width + 3;
447
- if (at + ON.length + 1 < area.col + area.cols) title.push({ col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.max(0, area.col + area.cols - (at + ON.length + 1)) });
742
+ * another's), in reverse while what is typed goes to it (with two tabs or more, the tab strip:
743
+ * stripRow), then the shown agent's screen as the last capture made it (lib/panel.mjs,
744
+ * term/capture.mjs: spans of the agent's own text and styles), each row placed at the terminal's
745
+ * first column and kept inside its cells. */
746
+ /** What an empty group shows (docs/tui.md, "Splits"), under an empty strip row: that Enter on an
747
+ * agent in the list opens it here, in reverse while it is the focused group, then the leader's
748
+ * keys for the groups. */
749
+ const EMPTY_HINT = "Enter on an agent opens it here";
750
+ function emptyRows(m, area) {
751
+ const end = area.col + area.cols, at = area.col + 1;
752
+ const hint = [{ col: at, text: lit(EMPTY_HINT), width: Math.max(0, Math.min(EMPTY_HINT.length, end - at - 1)), ...(area.focused ? { style: FOCUSED } : {}) }];
753
+ const leader = keyText(m.detachKey), keys = [];
754
+ let col = at;
755
+ for (const does of ["group-next", "group-close"]) {
756
+ const entry = LEADER.find((each) => each.does === does), key = keyLabel(entry.keys[0]), word = entry.label;
757
+ const after = col + leader.width + 1, at2 = after + key.length + 1;
758
+ if (at2 + word.length > end - 1) break;
759
+ keys.push({ col, text: leader.text, style: BOLD, width: leader.width }, { col: after, text: lit(key), style: BOLD, width: key.length }, { col: at2, text: lit(word), style: DIM, width: word.length });
760
+ col = at2 + word.length + GAP;
761
+ }
762
+ return [[], hint, keys];
763
+ }
764
+ function regionRows(m, area) {
765
+ const group = groupsIn(m)[area.group] ?? { tabs: [], shown: null };
766
+ if (group.shown === null) return emptyRows(m, area);
767
+ // The focused group's shown tab is in reverse while what is typed goes to it; the other group's
768
+ // is bold, never in reverse, so one terminal at a time reads as focused (T3).
769
+ const focused = area.focused && m.terminal?.focus === "terminal";
770
+ const tab = group.tabs.find((each) => each.shown) ?? { name: m.terminal?.name, machine: m.terminal?.routed ? m.terminal.machine : null };
771
+ const name = measured(tab.name);
772
+ let title = [];
773
+ if (group.tabs.length > 1) title = stripRow(group.tabs, area, { focused, ascii: m.ascii });
774
+ else {
775
+ if (focused) title.push({ col: area.col, width: Math.min(area.cols, name.width + 2), style: FOCUSED });
776
+ title.push({ col: area.col + 1, text: name.text, style: focused ? FOCUSED : BOLD, width: Math.max(0, Math.min(name.width, area.cols - 2)) });
777
+ if (tab.machine) {
778
+ const where = measured(tab.machine), at = area.col + name.width + 3;
779
+ if (at + ON.length + 1 < area.col + area.cols) title.push({ col: at, text: lit(ON), style: DIM, width: ON.length }, { col: at + ON.length + 1, text: where.text, style: DIM, width: Math.max(0, area.col + area.cols - (at + ON.length + 1)) });
780
+ }
448
781
  }
449
- const lines = m.screen?.lines ?? [];
782
+ const screenOf = area.focused ? m.screen : m.screens?.get(group.shown) ?? null;
783
+ const lines = screenOf?.lines ?? [];
450
784
  const body = Array.from({ length: area.rows }, (_, r) => (lines[r] ?? [])
451
785
  .filter((span) => span.col < area.cols)
452
786
  .map((span) => ({ ...span, col: area.col + span.col, width: Math.min(span.width ?? area.cols, area.cols - span.col) })));