@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
@@ -2,11 +2,12 @@
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 { keyLabel } from "../actions.mjs";
6
- import { lit } from "../term/text.mjs";
5
+ import { LEADER, keyLabel } from "../actions.mjs";
6
+ import { lit, ownEllipsis } from "../term/text.mjs";
7
7
  import { style } from "../term/style.mjs";
8
8
  import { cutNote, marksOf, measured } from "./instances.mjs";
9
9
  import { windowOf } from "./scroll.mjs";
10
+ import { SOUL_MARK } from "./souls.mjs";
10
11
  import { OPEN_MARK } from "./switcher.mjs";
11
12
 
12
13
  const TITLE = style({ bold: true });
@@ -29,6 +30,12 @@ export function keyText(label) {
29
30
  * kernel's own usage, so the help cannot name a command that does not exist. A later version
30
31
  * removes a line when it adds the act. */
31
32
  export const NOT_YET = Object.freeze([
33
+ // The spawn prompt (n, N) spawns on this machine, with the launch the soul and this machine
34
+ // choose, and no task: the rest is the kernel's command's (run on that machine for another).
35
+ Object.freeze({ what: "spawn on another machine", command: "oats spawn <soul>" }),
36
+ Object.freeze({ what: "spawn with a harness, model or task", command: "oats spawn <soul>" }),
37
+ // The Capabilities view lists them and their facts: a capability's skills' text and its files are the kernel's command's.
38
+ Object.freeze({ what: "see a capability's skills and files", command: "oats capabilities show <name>" }),
32
39
  Object.freeze({ what: "open an agent in its own tmux window", command: "oats session attach --home <home>" }),
33
40
  Object.freeze({ what: "start with another harness or model", command: "oats session start --home <home>" }),
34
41
  Object.freeze({ what: "add a machine to this workspace", command: "oats server connect <id> --ssh <alias>" }),
@@ -42,13 +49,14 @@ export const NOT_YET = Object.freeze([
42
49
  export const MACHINES = Object.freeze([
43
50
  "A machine's rows are what it reported at the time on its heading (in a view of one machine, in the header).",
44
51
  "Nothing is kept on disk: a machine not reached in this run is listed by its own name.",
45
- "Souls and Capabilities, when they come, are this machine's.",
52
+ "Souls and Capabilities are this machine's.",
46
53
  ]);
47
- /** The views the frame names, and for the two that cannot be opened yet, what to run instead. */
54
+ /** The views the frame names, what each holds, and what to run for what a view does not do yet.
55
+ * The Souls view spawns an agent of the selected soul (n, N). */
48
56
  export const VIEWS = Object.freeze([
49
57
  Object.freeze({ name: "1 Instances", what: "the instances of the open workspace", commands: Object.freeze([]) }),
50
- Object.freeze({ name: "2 Souls", what: "not in this version", commands: Object.freeze(["oats souls", "oats spawn <soul>"]) }),
51
- Object.freeze({ name: "3 Capabilities", what: "not in this version", commands: Object.freeze(["oats capabilities"]) }),
58
+ Object.freeze({ name: "2 Souls", what: "the souls of the open workspace and their detail, i their instances, n an agent of the selected soul", commands: Object.freeze([]) }),
59
+ Object.freeze({ name: "3 Capabilities", what: "the capabilities of the open workspace and their detail, Enter on a soul that uses one shows it in Souls", commands: Object.freeze([]) }),
52
60
  ]);
53
61
 
54
62
  const words = (text) => text.split(" ");
@@ -86,14 +94,14 @@ function table(pairs, cols, look) {
86
94
  * does not restate the grammar). */
87
95
  export const OPEN_RULES = Object.freeze([
88
96
  "While the terminal has the focus every other key goes to the agent, Ctrl+C and Ctrl+Z too.",
89
- "One terminal is open at a time. It has no scrollback but the viewer's own, and no mouse.",
90
- "docs/tui.md has the keys that can be the back key.",
97
+ "Up to 4 terminals are open at a time, each a tab. They have no scrollback but the viewer's own, and no mouse.",
98
+ "docs/tui.md has the keys that can be the leader.",
91
99
  ]);
92
- /** The rows under the line of `open`, in `room` cells: the back key, which takes the focus from the
93
- * open terminal (tui.json's open.detachKey, text from outside), then OPEN_RULES, each sentence on
94
- * as many rows as it needs. */
100
+ /** The rows under the line of `open`, in `room` cells: the leader pressed twice, which takes the
101
+ * focus from the open terminal (tui.json's open.detachKey, text from outside), then OPEN_RULES,
102
+ * each sentence on as many rows as it needs. */
95
103
  function openRows(detachKey, room) {
96
- const key = keyText(detachKey), said = "takes the focus from the terminal back to the list; the agent keeps running.";
104
+ const key = keyText(`${detachKey} ${detachKey}`), said = "takes the focus from the terminal back to the list; the agent keeps running.";
97
105
  const first = flow(words(said), Math.max(1, room - key.width - 1));
98
106
  return [
99
107
  [{ col: 0, text: key.text, width: key.width }, { col: key.width + 1, text: lit(first[0]) }],
@@ -116,11 +124,44 @@ const sentences = (list, cols) => list.flatMap((sentence) => {
116
124
  return [first, ...flow(rest.flatMap(words), cols - 2 * INDENT - 2)].map((text, i) => [{ col: INDENT + (i ? 2 : 0), text: lit(text) }]);
117
125
  });
118
126
 
127
+ /** The leader's rows (docs/tui.md, "The leader"): its key, then the table of what each key after
128
+ * it does (actions.mjs LEADER), from every focus. */
129
+ function leaderRows(detachKey, cols) {
130
+ const key = keyText(detachKey);
131
+ // The sentence after the key on as many rows as it needs, its later rows under its first.
132
+ const at = INDENT + key.width + 1;
133
+ const lead = flow(words("then one of these keys, from every focus; a terminal too:"), Math.max(1, cols - INDENT - at));
134
+ return [
135
+ [{ col: INDENT, text: lit("The leader"), style: TITLE }],
136
+ [],
137
+ [{ col: INDENT, text: key.text, width: key.width, style: KEYS }, { col: at, text: lit(lead[0]) }],
138
+ ...lead.slice(1).map((text) => [{ col: at, text: lit(text) }]),
139
+ ...table(LEADER.map((entry) => [entry.keys.map(keyLabel).join(", "),
140
+ words(entry.does === "list" ? `${entry.label}; the leader again does the same` : entry.terminal ? `${entry.label}, while a terminal is open` : entry.label)]), cols, KEYS),
141
+ ];
142
+ }
143
+
144
+ /** The spawn prompt's keys (docs/tui.md, "Spawning an agent"): the prompt reads its keys itself, as
145
+ * the palette does, so they are fixed and the TUI's words. Each step's keys, then the paste guard. */
146
+ export const SPAWN_KEYS = Object.freeze([
147
+ Object.freeze(["Up, Down", "move in the soul picker; typing narrows it"]),
148
+ Object.freeze(["Enter", "pick the selected soul; a soul marked ! would be refused here and cannot be picked"]),
149
+ Object.freeze(["Esc", "close the soul picker"]),
150
+ Object.freeze(["Tab, Shift+Tab", "move the focus in the preview: Spawn, name, child of, then each fold"]),
151
+ Object.freeze(["Enter", "do what the footer names: on Spawn spawn, on name keep the name and read the preview again, on child of switch it, on a fold open or close it"]),
152
+ Object.freeze(["Esc", "from a field back to Spawn; from Spawn back to the picker, or to the list"]),
153
+ ]);
154
+ export const SPAWN_RULES = Object.freeze([
155
+ "Enter spawns only once the preview on the screen is the one for the choices shown, read after it was first drawn: a paste cannot spawn.",
156
+ ]);
157
+ const spawnRows = (cols) => [heading("The spawn prompt"), [], ...table(SPAWN_KEYS.map(([keys, said]) => [keys, words(said)]), cols, KEYS), ...sentences(SPAWN_RULES, cols)];
158
+
119
159
  /** Every row of the help for an area `cols` wide, before it is scrolled. Unbound actions are
120
160
  * listed as such: the table can be changed by the user's tui.json, and the help says what is so
121
161
  * now. An action that does one thing in each view has a line per view, its key on each; under
122
162
  * the line of opening an agent stand the back key (`detachKey`, tui.json's `open.detachKey`) and
123
- * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. */
163
+ * the rules of OPEN_RULES; under the line of the last act, ACT_RULES. After the leader's table,
164
+ * the spawn prompt's keys (SPAWN_KEYS, SPAWN_RULES). */
124
165
  export function helpRows(actions, ascii, cols = 100, detachKey = null) {
125
166
  const marks = marksOf(ascii);
126
167
  const closing = keyText(["close", "help"].map((id) => actions.find((action) => action.id === id)).filter((action) => action?.keys.length).map((action) => keyLabel(action.keys[0])).join(" or "));
@@ -133,6 +174,9 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
133
174
  return action.views.map(([view, said]) => [left, words(said), action.id === "open" && view === "instances" && detachKey !== null ? (room) => openRows(detachKey, room)
134
175
  : action.id === "restart" ? actRows : undefined]);
135
176
  }), cols, KEYS),
177
+ ...(detachKey !== null ? [[], ...leaderRows(detachKey, cols)] : []),
178
+ [],
179
+ ...spawnRows(cols),
136
180
  [],
137
181
  heading("Marks"),
138
182
  [],
@@ -141,12 +185,14 @@ export function helpRows(actions, ascii, cols = 100, detachKey = null) {
141
185
  [marks.stopped, "stopped"],
142
186
  [marks.shell, "stopped, with a shell left in its terminal"],
143
187
  [marks.unknown, "state unknown"],
144
- [marks.held, "held by a spawn or a retire that is not finished"],
145
- [`${marks.open} ${marks.closed}`, "has instances below it: shown, folded away"],
188
+ [marks.held, ownEllipsis("held by a spawn or a retire: under way (Retiring\u2026), failed or not finished", ascii)],
189
+ ["+N", "N instances folded away below it"],
146
190
  [marks.waiting, "needs input"],
147
191
  [`${marks.waiting}N`, "N instances folded away below it need input"],
148
192
  [marks.selected, "the selected row, and the pane the movement keys act on"],
149
193
  [OPEN_MARK, "among the workspaces: the one that is open"],
194
+ [ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8, "among the souls: a soul, in its colour"],
195
+ ["!", "among the souls: a spawn of it here would be refused"],
150
196
  ].map(([mark, meaning]) => [mark, words(meaning)]), cols),
151
197
  [],
152
198
  heading("Views"),
@@ -2,18 +2,21 @@
2
2
  // Every name, word and reason in it is text the TUI did not write and goes through shown(); the
3
3
  // marks and the few words around them are the TUI's own. Nothing is told by colour alone: each
4
4
  // state has a mark of its own shape, the selected row carries `>` as well as reverse video, and a
5
- // waiting row carries `!`. In a view of two or more deployments the list also holds a heading per
6
- // deployment and the sentences the model sets under one: a heading says in words what it is of.
5
+ // waiting row carries `!`. A row is quiet: its mark and its name, and a word only where the mark
6
+ // can't say it. Children stand under their parent by indentation alone; a folded row says how
7
+ // many it folds away, `+n`. In a view of two or more deployments the list also holds a heading
8
+ // per deployment and the sentences the model sets under one: a heading says in words what it is
9
+ // of.
7
10
  import { lit, shown, shownEnd, textOf } from "../term/text.mjs";
8
11
  import { style } from "../term/style.mjs";
9
12
  import { textWidth } from "../term/width.mjs";
10
13
 
11
14
  /** The marks, in UTF-8 and in ASCII (docs/tui.md lists them; the help view draws them from here).
12
15
  * The state marks are keyed by the word the shared home gives a row's state, with `shell` and
13
- * `held` beside them (lib/model.mjs says when). */
16
+ * `held` beside them (lib/model.mjs says when). A fold has no mark: a folded row shows `+n`. */
14
17
  export const MARKS = Object.freeze({
15
- utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", open: "▾", closed: "▸", selected: ">", waiting: "!" }),
16
- ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", open: "v", closed: ">", selected: ">", waiting: "!" }),
18
+ utf8: Object.freeze({ running: "●", stopped: "○", shell: "◌", unknown: "?", held: "◆", selected: ">", waiting: "!" }),
19
+ ascii: Object.freeze({ running: "*", stopped: "-", shell: "~", unknown: "?", held: "#", selected: ">", waiting: "!" }),
17
20
  });
18
21
  export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
19
22
 
@@ -21,9 +24,10 @@ export const marksOf = (ascii) => (ascii ? MARKS.ascii : MARKS.utf8);
21
24
  const INDENT = 2, LEVELS = 6;
22
25
  /** The cells kept at the right edge for the waiting mark: `!`, `!N`, `!NN`, `!99+`. */
23
26
  const WAITING = 4;
24
- /** A row's cells before its name: the selection mark, a gap, the disclosure mark, a gap, the
25
- * state mark, a gap. */
26
- const LEAD = 5;
27
+ /** A row's cells before its name: the selection mark, a gap, the state mark, a gap. */
28
+ const LEAD = 4;
29
+ /** The column of the state mark, before a row's indent. */
30
+ const MARK = 2;
27
31
 
28
32
  /** A heading starts here: at the margin the header and the footer keep, not at a row's indent. */
29
33
  const HEAD = 1;
@@ -32,15 +36,17 @@ const GAP = 2;
32
36
  /** The fewest cells a heading's short reason or its path is drawn in when it is cut: under them
33
37
  * it is left out, since a few cells of either say nothing. */
34
38
  const PART_MIN = 8;
35
- /** Where a sentence inside the list starts. The model wraps a sentence for a pane less this
36
- * indent and one cell (lib/model.mjs SENTENCE_INDENT, which a view cannot import): the same value. */
39
+ /** Where a sentence inside the list starts, and the line that says why no instance is listed or
40
+ * what is cut off. The model wraps a sentence for a pane less this indent and one cell
41
+ * (lib/model.mjs SENTENCE_INDENT, which a view cannot import): the same value. */
37
42
  const SENTENCE_INDENT = 3;
38
43
 
39
44
  const PLAIN = style();
40
45
  const BOLD = style({ bold: true });
41
46
  const DIM = style({ dim: true });
42
47
  const SELECTED = style({ reverse: true });
43
- const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
48
+ /** The look of each state mark: the Souls view draws an instance's mark in its detail as the list does. */
49
+ export const LOOK = Object.freeze({ running: style({ fg: "green" }), stopped: DIM, shell: DIM, unknown: style({ fg: "yellow" }), held: style({ fg: "magenta" }) });
44
50
  const WAITS = style({ fg: "yellow", bold: true });
45
51
  const WAITS_SELECTED = style({ reverse: true, bold: true });
46
52
 
@@ -59,20 +65,30 @@ export function measured(value) {
59
65
 
60
66
  const waitingText = (row) => (row.below > 99 ? "!99+" : row.below > 0 ? `!${row.below}` : row.waiting ? "!" : null);
61
67
 
62
- /** One instance's row in a pane `cols` wide: the marks, the name cut to what is left, the state
63
- * word in its column and the waiting mark at the edge. Every span has its width, so no text can
64
- * pass its column whatever the terminal thinks a character takes. */
68
+ /** One instance's row in a pane `cols` wide: the state mark, the name cut to what is left, on a
69
+ * folded row `+n` after the name, the row's word (when it has one) in the word column, and the
70
+ * waiting mark at the edge. A row with no word gives its name the word column's cells too. The
71
+ * name is cut before `+n` is: the count stays whole beside what is left of the name. Every span
72
+ * has its width, so no text can pass its column whatever the terminal thinks a character takes. */
65
73
  function instanceRow(row, cols, wordWidth, marks) {
66
74
  const look = (own) => (row.selected ? SELECTED : own);
67
75
  const at = Math.min(row.depth, LEVELS - 1) * INDENT;
76
+ const worded = wordWidth > 0 && row.word !== null && row.word !== undefined;
68
77
  const wordCol = Math.max(0, cols - WAITING - 1 - wordWidth);
69
- const nameCol = LEAD + at;
78
+ const nameCol = LEAD + at, nameEnd = worded ? wordCol - 2 : cols - WAITING - 1;
79
+ const fold = row.folded > 0 ? `+${row.folded}` : null;
70
80
  const spans = [];
71
81
  if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marks.selected), style: SELECTED, width: 1 });
72
- if (row.disclosure) spans.push({ col: 1 + at, text: lit(marks[row.disclosure]), style: look(PLAIN), width: 1 });
73
- spans.push({ col: 3 + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(LOOK[row.mark] ?? LOOK.unknown), width: 1 });
74
- if (wordCol - 2 > nameCol) spans.push({ col: nameCol, text: shown(row.name), style: look(PLAIN), width: wordCol - 2 - nameCol });
75
- if (wordWidth > 0) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordWidth });
82
+ spans.push({ col: MARK + at, text: lit(marks[row.mark] ?? marks.unknown), style: look(LOOK[row.mark] ?? LOOK.unknown), width: 1 });
83
+ if (nameEnd > nameCol) {
84
+ const name = measured(row.name);
85
+ // The count and the gap before it, when there is room for them and for a cell of the name.
86
+ const after = fold && nameEnd - nameCol > fold.length + 1 ? fold.length + 1 : 0;
87
+ const nameWidth = Math.min(name.width, nameEnd - nameCol - after);
88
+ spans.push({ col: nameCol, text: name.text, style: look(PLAIN), width: after ? nameWidth : nameEnd - nameCol });
89
+ if (after) spans.push({ col: nameCol + nameWidth + 1, text: lit(fold), style: look(DIM), width: fold.length });
90
+ }
91
+ if (worded) spans.push({ col: wordCol, text: shown(row.word), style: look(DIM), width: wordWidth });
76
92
  const waits = waitingText(row);
77
93
  if (waits) spans.push({ col: cols - waits.length, text: lit(waits), style: row.selected ? WAITS_SELECTED : WAITS, width: waits.length });
78
94
  return spans;
@@ -82,8 +98,10 @@ function instanceRow(row, cols, wordWidth, marks) {
82
98
  * live, the shared word for its state and the short reason; at the right edge the time a machine
83
99
  * reported its rows at. The state and the time always stand. When the row is too narrow for the
84
100
  * rest, the path is given up first, then the short reason, and then the label is cut: the full
85
- * reason is in the detail of each of its rows, and under the heading when it has none. */
86
- function headingRow({ label, path, state, short, readAt }, cols, ascii) {
101
+ * reason is in the detail of each of its rows, and under the heading when it has none. A short
102
+ * reason with no state word is drawn too: the Souls view's heading of a failed re-read has a
103
+ * sentence and no shared word for a state (views/souls.mjs). */
104
+ export function headingRow({ label, path, state, short, readAt }, cols, ascii) {
87
105
  const spans = [], edge = cols - 1;
88
106
  let limit = edge;
89
107
  if (readAt) {
@@ -91,7 +109,7 @@ function headingRow({ label, path, state, short, readAt }, cols, ascii) {
91
109
  spans.push({ col, text: lit(read), style: DIM, width: Math.max(0, Math.min(read.length, edge - col)) });
92
110
  limit = col - GAP;
93
111
  }
94
- const name = measured(label), word = state ? measured(state) : null, why = state && short ? measured(short) : null, where = path ? measured(path) : null;
112
+ const name = measured(label), word = state ? measured(state) : null, why = short ? measured(short) : null, where = path ? measured(path) : null;
95
113
  let room = limit - HEAD - (word ? GAP + word.width : 0);
96
114
  const nameWidth = Math.max(0, Math.min(name.width, room));
97
115
  room -= nameWidth;
@@ -122,16 +140,16 @@ export function instances(m, size) {
122
140
  const rows = Array.from({ length: size.rows }, () => []);
123
141
  if (size.rows < 1) return rows;
124
142
  const marks = marksOf(m.ascii);
125
- const aside = Math.max(0, size.cols - LEAD + 2), sentence = Math.max(0, size.cols - SENTENCE_INDENT - 1);
143
+ const aside = Math.max(0, size.cols - SENTENCE_INDENT), sentence = Math.max(0, size.cols - SENTENCE_INDENT - 1);
126
144
  m.list.forEach((item, i) => {
127
145
  if (!item || i >= size.rows) return;
128
146
  if (item.heading) rows[i] = headingRow(item.heading, size.cols, m.ascii);
129
147
  else if (item.line) rows[i] = [{ col: SENTENCE_INDENT, text: item.line, width: sentence }];
130
148
  else if (item.own) rows[i] = [{ col: SENTENCE_INDENT, text: lit(item.own), style: DIM, width: sentence }];
131
- else if (item.empty) rows[i] = [{ col: LEAD - 2, text: lit(EMPTY_TEXT[item.empty]), style: DIM, width: aside }];
149
+ else if (item.empty) rows[i] = [{ col: SENTENCE_INDENT, text: lit(EMPTY_TEXT[item.empty]), style: DIM, width: aside }];
132
150
  else rows[i] = instanceRow(item, size.cols, m.wordWidth, marks);
133
151
  });
134
152
  const note = cutNote(m.above, m.below);
135
- if (note) rows[size.rows - 1] = [{ col: LEAD - 2, text: lit(note), style: DIM, width: aside }];
153
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: aside }];
136
154
  return rows;
137
155
  }
@@ -0,0 +1,66 @@
1
+ // The palette (docs/tui.md, "The palette"): (model, area) -> rows of spans, over the whole body.
2
+ // Pure: no IO, no clock, no escape byte. One input over a list: the query on the first row, then
3
+ // the window of the rows lib/model.mjs paletteItems lists, the selected one in reverse with `>`.
4
+ // An instance's, a soul's or a capability's name, a machine, where a capability comes from and the
5
+ // query are text the TUI did not write and go through shown(); the labels of the views, the acts and the
6
+ // commands are the TUI's own. Nothing is told by colour alone: each row says in a word what kind it is.
7
+ import { lit, shown } from "../term/text.mjs";
8
+ import { style } from "../term/style.mjs";
9
+ import { cutNote, marksOf, measured } from "./instances.mjs";
10
+
11
+ /** The query's prompt, and the cells it takes with the gap after it. */
12
+ const PROMPT = ">", PROMPT_CELLS = 2;
13
+ /** The cells a row's text starts at: the selection mark, a gap, an instance's state mark, a gap. */
14
+ const LEAD = 4;
15
+ /** The word at a row's right edge that says what it is. */
16
+ const KINDS = Object.freeze({ instance: "instance", soul: "soul", capability: "capability", view: "view", act: "act", command: "command" });
17
+ /** The TUI's word before another machine's name. */
18
+ const ON = "on";
19
+
20
+ const BOLD = style({ bold: true });
21
+ const DIM = style({ dim: true });
22
+ const SELECTED = style({ reverse: true });
23
+ const PLAIN = style();
24
+
25
+ /** One row of the palette in `cols` cells. */
26
+ function itemRow(item, cols, marks) {
27
+ const look = (own) => (item.selected ? SELECTED : own);
28
+ const kind = KINDS[item.kind], kindCol = Math.max(LEAD, cols - kind.length);
29
+ const spans = [];
30
+ if (item.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(">"), style: SELECTED, width: 1 });
31
+ if (item.kind === "instance") spans.push({ col: 2, text: lit(marks[item.mark] ?? marks.unknown), style: look(PLAIN), width: 1 });
32
+ let col = LEAD;
33
+ const room = () => Math.max(0, kindCol - 2 - col);
34
+ const put = (text, width, own) => { const w = Math.min(width, room()); if (w > 0) spans.push({ col, text, style: look(own), width: w }); col += width + 1; };
35
+ if (item.kind === "instance" || item.kind === "soul") {
36
+ // A name is text from outside: an instance's or a soul's.
37
+ const name = measured(item.name);
38
+ put(name.text, name.width, PLAIN);
39
+ if (item.machine !== null && item.machine !== undefined) { put(lit(ON), ON.length, DIM); const where = measured(item.machine); put(where.text, where.width, DIM); }
40
+ } else if (item.kind === "capability") {
41
+ // A capability's name and, dim, where it comes from (its repository or package): text from outside.
42
+ const name = measured(item.name), where = measured(item.source);
43
+ put(name.text, name.width, PLAIN);
44
+ put(where.text, where.width, DIM);
45
+ } else {
46
+ put(lit(item.label), item.label.length, PLAIN);
47
+ if (item.kind === "act") { const name = measured(item.name); put(name.text, name.width, DIM); }
48
+ }
49
+ spans.push({ col: kindCol, text: lit(kind), style: look(DIM), width: Math.min(kind.length, cols - kindCol) });
50
+ return spans;
51
+ }
52
+
53
+ /** `{ rows, cursor }`: `size.rows` rows for an area `size.cols` wide, and the column the cursor
54
+ * stands at on the first row, after the query. The last row says what is cut off. */
55
+ export function palette(m, size) {
56
+ const rows = Array.from({ length: size.rows }, () => []);
57
+ const p = m.palette, query = measured(p.query);
58
+ const room = Math.max(0, size.cols - PROMPT_CELLS - 1);
59
+ if (size.rows > 0) rows[0] = [{ col: 0, text: lit(PROMPT), style: BOLD, width: PROMPT.length }, ...(query.width ? [{ col: PROMPT_CELLS, text: query.text, width: Math.min(query.width, room) }] : [])];
60
+ const marks = marksOf(m.ascii);
61
+ if (p.empty && size.rows > 1) rows[1] = [{ col: LEAD, text: lit("Nothing matches."), style: DIM, width: Math.max(0, size.cols - LEAD) }];
62
+ p.rows.forEach((item, i) => { if (1 + i < size.rows) rows[1 + i] = itemRow(item, size.cols, marks); });
63
+ const note = cutNote(p.above, p.below);
64
+ if (note && size.rows > 2) rows[size.rows - 1] = [{ col: LEAD, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEAD) }];
65
+ return { rows, cursor: PROMPT_CELLS + Math.min(query.width, room) };
66
+ }
@@ -0,0 +1,270 @@
1
+ // The Souls view: (model, pane) -> rows of spans, the list of the open workspace's souls and the
2
+ // selected soul's detail. Pure: no IO, no clock, no escape byte. A soul's name, its description,
3
+ // where it comes from, its harness facts, its teams and capabilities, the names of its instances
4
+ // and a failed read's sentence are text the TUI did not write and go through shown(); the marks,
5
+ // the labels and the few lines of SOULS_TEXT are the TUI's own. Nothing is told by colour alone:
6
+ // a soul's colour is drawn on a mark that is there without it, the selected row carries `>` as
7
+ // well as reverse video, a soul a spawn here would refuse carries `!` as well as being dim, and
8
+ // the refusal in the detail says "Can't spawn here" in words before its warning style.
9
+ import { keyLabel } from "../actions.mjs";
10
+ import { lit, shown, shownLines } from "../term/text.mjs";
11
+ import { COLORS, style } from "../term/style.mjs";
12
+ import { LOOK, cutNote, headingRow, marksOf, measured } from "./instances.mjs";
13
+ import { windowOf } from "./scroll.mjs";
14
+
15
+ /** The TUI's own lines in the Souls view. `retry` and `toInstances` stand after the key that does
16
+ * what they say (tui.json may rebind it), so the line names the key the user has: `r reads them
17
+ * again.`. `reading` ends in an ellipsis, drawn `...` in ASCII. */
18
+ export const SOULS_TEXT = Object.freeze({
19
+ reading: "Reading souls…",
20
+ none: "This workspace offers no souls. `oats souls` says why.",
21
+ nomatch: "No soul matches the filter.",
22
+ retry: "reads them again.",
23
+ noWorkspace: "Open a workspace of this machine to see its souls.",
24
+ toInstances: "shows them in the Instances view.",
25
+ });
26
+
27
+ /** A soul's colour (soul-colors.mjs's palette name) as one of the terminal's sixteen: the model
28
+ * maps a row's colour with it, and a name not here leaves the soul uncoloured. */
29
+ export const SOUL_COLOURS = Object.freeze({ sand: "yellow", sage: "green", slate: "blue", mauve: "magenta", clay: "red", olive: "cyan" });
30
+
31
+ /** A soul's mark, in UTF-8 and in ASCII, and the sign before a count of its instances. */
32
+ export const SOUL_MARK = Object.freeze({ utf8: "■", ascii: "#" });
33
+ export const COUNT_SIGN = Object.freeze({ utf8: "·", ascii: "x" });
34
+
35
+ /** The columns of a soul's row, as an instance's: the selection mark, a gap, the soul's mark, a gap. */
36
+ const MARK = 2, NAME = 4;
37
+ /** Where a line of the TUI's own and a failed read's sentence start in the list, as in the list
38
+ * of instances (views/instances.mjs SENTENCE_INDENT). */
39
+ const SENTENCE_INDENT = 3;
40
+ /** The detail's title and labels start here: the first cell holds the mark of the pane with the
41
+ * focus (views/detail.mjs). */
42
+ const LEFT = 2;
43
+ /** The values start here, as in the instance detail (views/detail.mjs): a label is a short word.
44
+ * A part with a longer name (the harness, the capabilities, the instances here) has its name on
45
+ * a row of its own and its values under it. */
46
+ const VALUE = LEFT + 9;
47
+ /** The parts of a section (the harness, the instances) are set in this far under its label. */
48
+ const INNER = LEFT + 2;
49
+ /** The fewest cells a harness value keeps beside its label: under them each value goes on the
50
+ * row under its label, so a long label ("Launch configuration") never squeezes its value. */
51
+ const VALUE_MIN = 16;
52
+ /** The most rows a wrapped value or sentence takes, and the description. */
53
+ const WRAP_ROWS = 6, DESCRIPTION_ROWS = 8;
54
+
55
+ const PLAIN = style();
56
+ const BOLD = style({ bold: true });
57
+ const DIM = style({ dim: true });
58
+ const SELECTED = style({ reverse: true });
59
+ /** The refusal's warning style: it says "Can't spawn here" too, so the colour is not alone. */
60
+ const WARN = style({ bold: true, fg: "yellow" });
61
+
62
+ const markOf = (ascii) => (ascii ? SOUL_MARK.ascii : SOUL_MARK.utf8);
63
+ const countText = (count, ascii) => `${ascii ? COUNT_SIGN.ascii : COUNT_SIGN.utf8}${count}`;
64
+ /** A line of the TUI's own as the screen draws it: the ellipsis is `...` in ASCII. */
65
+ const ownText = (text, ascii) => (ascii ? text.replace(/…/g, "...") : text);
66
+
67
+ /** The first key of the action `id` as the user has it, `{ text, width }`, or null when it has none. */
68
+ function keyOf(m, id) {
69
+ const action = (m.actions ?? []).find((a) => a.id === id && a.keys.length);
70
+ return action ? measured(keyLabel(action.keys[0])) : null;
71
+ }
72
+
73
+ /** Whether the list stands, beside the detail on a wide terminal: once the catalog was read (its
74
+ * rows, or none of them matching the filter), and over the rows a failed re-read kept. A body of
75
+ * one sentence (reading, a failed first read, an empty catalog, no workspace here) has the whole
76
+ * width instead. */
77
+ export function soulsListed(s) {
78
+ return Boolean(s) && s.local !== false && (s.heading != null || s.state === "rows" || s.state === "nomatch" || (s.list?.length ?? 0) > 0);
79
+ }
80
+
81
+ /** A line of the TUI's own on as many rows of `width` cells as it needs, broken at its spaces but
82
+ * never inside a command between backticks: a command cut in two cannot be typed. The Capabilities
83
+ * view sets its own lines with it too. */
84
+ export function ownLines(text, width) {
85
+ const words = text.match(/`[^`]*`[^\s`]*|\S+/g) ?? [];
86
+ return words.reduce((lines, word) => {
87
+ const last = lines.at(-1);
88
+ if (last !== undefined && last.length + 1 + word.length <= width) lines[lines.length - 1] = `${last} ${word}`;
89
+ else lines.push(word);
90
+ return lines;
91
+ }, []);
92
+ }
93
+
94
+ /** Units set on rows of `width` cells from column 0, `gap` cells between two: a unit is pieces
95
+ * (`{ text, width, style, glue }`) written together, one cell between two but before a glued one
96
+ * (a comma). A unit is never broken over two rows; one wider than a row is cut there. The
97
+ * Capabilities view flows what a capability provides with it. */
98
+ export function flowed(units, width, gap = 1) {
99
+ const unitWidth = (unit) => unit.reduce((sum, piece, i) => sum + piece.width + (i > 0 && !piece.glue ? 1 : 0), 0);
100
+ const rows = [];
101
+ let row = [], used = 0;
102
+ for (const unit of units) {
103
+ const w = unitWidth(unit);
104
+ if (row.length && used + gap + w > width) { rows.push(row); row = []; used = 0; }
105
+ let col = row.length ? used + gap : 0;
106
+ unit.forEach((piece, i) => {
107
+ if (i > 0 && !piece.glue) col += 1;
108
+ if (col < width && piece.width > 0) row.push({ col, text: piece.text, width: Math.min(piece.width, width - col), ...(piece.style ? { style: piece.style } : {}) });
109
+ col += piece.width;
110
+ });
111
+ used = Math.min(width, col);
112
+ }
113
+ if (row.length) rows.push(row);
114
+ return rows;
115
+ }
116
+
117
+ /** One soul's row in a pane `cols` wide: the selection mark, the soul's mark in its colour, its
118
+ * name, `!` when a spawn of it here would be refused, and a dim count of its instances here when
119
+ * it has any. The name is cut before the `!` and the count are: they stay whole beside what is
120
+ * left of it. A refused soul's row is dim. One cell is kept at the right edge. */
121
+ function soulRow(row, cols, ascii) {
122
+ const look = (own) => (row.selected ? SELECTED : own);
123
+ const quiet = row.refused ? DIM : PLAIN;
124
+ const colour = typeof row.color === "string" && COLORS.includes(row.color) ? row.color : null;
125
+ const spans = [];
126
+ if (row.selected) spans.push({ col: 0, width: cols, style: SELECTED }, { col: 0, text: lit(marksOf(ascii).selected), style: SELECTED, width: 1 });
127
+ spans.push({ col: MARK, text: lit(markOf(ascii)), style: look(colour ? style({ fg: colour, dim: row.refused === true }) : quiet), width: 1 });
128
+ const end = cols - 1;
129
+ if (end <= NAME) return spans;
130
+ const after = [...(row.refused ? [{ text: "!", style: quiet }] : []), ...(row.count > 0 ? [{ text: countText(row.count, ascii), style: DIM }] : [])];
131
+ const afterWidth = after.reduce((sum, part) => sum + 1 + part.text.length, 0);
132
+ const name = measured(row.name);
133
+ // What follows the name stands only when a cell of the name is left beside it.
134
+ const kept = end - NAME > afterWidth ? after : [];
135
+ const room = end - NAME - (kept.length ? afterWidth : 0);
136
+ const nameWidth = Math.min(name.width, room);
137
+ spans.push({ col: NAME, text: name.text, style: look(quiet), width: kept.length ? nameWidth : room });
138
+ let col = NAME + nameWidth;
139
+ for (const part of kept) { col += 1; spans.push({ col, text: lit(part.text), style: look(part.style), width: part.text.length }); col += part.text.length; }
140
+ return spans;
141
+ }
142
+
143
+ /** `size.rows` rows for the list pane, `size.cols` wide: the model's window of the souls (after
144
+ * the heading of a failed re-read, when there is one) and on the last row what is cut off; or the
145
+ * one body the catalog's state gives: reading, a failed first read (its sentence, then the key
146
+ * that reads again), an empty catalog, no soul matching the filter, no workspace of this machine. */
147
+ export function soulsList(m, size) {
148
+ const s = m.souls, ascii = m.ascii;
149
+ const rows = Array.from({ length: size.rows }, () => []);
150
+ if (size.rows < 1 || !s) return rows;
151
+ const width = Math.max(0, size.cols - SENTENCE_INDENT - 1);
152
+ /** A line of the TUI's own, dim, from row `at` on: the rows it took. */
153
+ const own = (text, at) => {
154
+ const lines = ownLines(ownText(text, ascii), width).slice(0, Math.max(0, size.rows - at));
155
+ lines.forEach((line, i) => { rows[at + i] = [{ col: SENTENCE_INDENT, text: lit(line), style: DIM, width }]; });
156
+ return lines.length;
157
+ };
158
+ if (s.local === false) { own(SOULS_TEXT.noWorkspace, 0); return rows; }
159
+ if (!soulsListed(s)) {
160
+ if (s.state === "failed") {
161
+ // The sentence from outside, whole where the rows allow, and under it the key that reads again.
162
+ const retry = keyOf(m, "refresh");
163
+ const lines = shownLines(s.failure, width, Math.max(1, size.rows - (retry ? 1 : 0)), { ascii });
164
+ lines.forEach((line, i) => { rows[i] = [{ col: SENTENCE_INDENT, text: line, width }]; });
165
+ if (retry && lines.length < size.rows) {
166
+ const at = lines.length, words = SENTENCE_INDENT + retry.width + 1;
167
+ rows[at] = [{ col: SENTENCE_INDENT, text: retry.text, style: BOLD, width: Math.min(retry.width, width) },
168
+ ...(words < size.cols - 1 ? [{ col: words, text: lit(SOULS_TEXT.retry), style: DIM, width: size.cols - 1 - words }] : [])];
169
+ }
170
+ } else own(s.state === "none" ? SOULS_TEXT.none : SOULS_TEXT.reading, 0);
171
+ return rows;
172
+ }
173
+ let at = 0;
174
+ if (s.heading) rows[at++] = headingRow(s.heading, size.cols, ascii);
175
+ if (s.state === "none" || s.state === "nomatch") own(SOULS_TEXT[s.state], at);
176
+ else s.list.forEach((row, i) => { if (at + i < size.rows) rows[at + i] = soulRow(row, size.cols, ascii); });
177
+ const note = cutNote(s.above ?? 0, s.below ?? 0);
178
+ if (note) rows[size.rows - 1] = [{ col: SENTENCE_INDENT, text: lit(note), style: DIM, width: Math.max(0, size.cols - SENTENCE_INDENT) }];
179
+ return rows;
180
+ }
181
+
182
+ /** Every row of the selected soul's detail for a pane `cols` wide, before it is scrolled: the name,
183
+ * a failed re-read's sentence (in the warning style; it says so in words) and the description; `from` and `works`; the refusal; the harness (each fact `label value`,
184
+ * its notes, a launch problem); the teams; the capabilities (one line, wrapped); and the instances
185
+ * here, with the key that shows them. A section with nothing to say is left out. */
186
+ export function soulDetailRows(m, cols) {
187
+ const d = m.souls?.detail;
188
+ if (!d) return [];
189
+ const ascii = m.ascii, wide = Math.max(0, cols - LEFT), room = Math.max(0, cols - VALUE), inner = Math.max(0, cols - INNER);
190
+ const rows = [[{ col: LEFT, text: shown(d.name), style: BOLD, width: wide }]];
191
+ const label = (text, col = LEFT) => ({ col, text: lit(text), style: DIM, width: Math.max(0, Math.min(text.length, cols - col)) });
192
+ /** Safe lines placed at `col`, each `width` cells, the first beside `first` (a label) when given. */
193
+ const lines = (list, col, width, look, first = null) => list.forEach((line, i) => rows.push([...(i === 0 && first ? [first] : []), { col, text: line, width, ...(look ? { style: look } : {}) }]));
194
+ /** A value from outside beside its label, wrapped under the value's column. */
195
+ const fact = (name, value) => {
196
+ if (room < 1) { rows.push([label(name)]); return; }
197
+ lines(shownLines(value, room, WRAP_ROWS, { ascii }), VALUE, room, null, label(name));
198
+ };
199
+ /** Units beside a label, flowed under the value's column. */
200
+ const flowFact = (name, units) => {
201
+ const set = room < 1 ? [] : flowed(units, room);
202
+ if (!set.length) { rows.push([label(name)]); return; }
203
+ set.forEach((spans, i) => rows.push([...(i === 0 ? [label(name)] : []), ...spans.map((span) => ({ ...span, col: span.col + VALUE }))]));
204
+ };
205
+
206
+ // A failed re-read's sentence, whole, under the name: the rows are the last read's.
207
+ if (d.failure) lines(shownLines(d.failure, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
208
+ lines(shownLines(d.description, wide, DESCRIPTION_ROWS, { ascii }), LEFT, wide);
209
+ if (d.from) fact("from", d.from);
210
+ if (d.works) fact("works", d.works);
211
+ if (d.refusal) lines(shownLines(d.refusal, wide, WRAP_ROWS, { ascii }), LEFT, wide, WARN);
212
+
213
+ const h = d.harness ?? { rows: [], notes: [], problem: null };
214
+ if (h.rows.length || h.notes.length || h.problem) {
215
+ rows.push([label("harness")]);
216
+ const names = h.rows.map(([name]) => measured(name));
217
+ const column = Math.max(0, ...names.map((name) => name.width));
218
+ const beside = inner - column - 2 >= VALUE_MIN;
219
+ h.rows.forEach(([, value], i) => {
220
+ const name = { col: INNER, text: names[i].text, style: DIM, width: Math.min(names[i].width, inner) };
221
+ if (beside) lines(shownLines(value, inner - column - 2, WRAP_ROWS, { ascii }), INNER + column + 2, inner - column - 2, null, name);
222
+ else { rows.push([name]); lines(shownLines(value, Math.max(0, inner - 2), WRAP_ROWS, { ascii }), INNER + 2, Math.max(0, inner - 2)); }
223
+ });
224
+ for (const note of h.notes) lines(shownLines(note, inner, WRAP_ROWS, { ascii }), INNER, inner, DIM);
225
+ if (h.problem) {
226
+ lines(shownLines(h.problem.lead, inner, WRAP_ROWS, { ascii }), INNER, inner, BOLD);
227
+ for (const line of h.problem.lines ?? []) lines(shownLines(line, inner, WRAP_ROWS, { ascii }), INNER, inner);
228
+ if (h.problem.code) {
229
+ const code = measured(h.problem.code);
230
+ rows.push([label("code", INNER), { col: INNER + 5, text: code.text, style: DIM, width: Math.max(0, Math.min(code.width, cols - INNER - 5)) }]);
231
+ }
232
+ }
233
+ }
234
+
235
+ // Each team its label, the default one marked so in the TUI's word; a comma after all but the last.
236
+ const comma = { text: lit(","), width: 1, glue: true };
237
+ if (d.teams?.length) flowFact("teams", d.teams.map((team, i, all) => [measured(team.label), ...(team.default ? [{ text: lit("(default)"), width: "(default)".length, style: DIM }] : []), ...(i < all.length - 1 ? [comma] : [])]));
238
+ if (d.capabilities?.length) {
239
+ rows.push([label("capabilities")]);
240
+ flowed(d.capabilities.map((id, i, all) => [measured(id), ...(i < all.length - 1 ? [comma] : [])]), inner).forEach((spans) => rows.push(spans.map((span) => ({ ...span, col: span.col + INNER }))));
241
+ }
242
+
243
+ const here = d.instances ?? { shown: [], more: 0 };
244
+ if (here.shown.length || here.more > 0) {
245
+ rows.push([label("instances here")]);
246
+ const marks = marksOf(ascii);
247
+ const units = [
248
+ ...here.shown.map((each) => [{ text: lit(marks[each.mark] ?? marks.unknown), width: 1, style: LOOK[each.mark] ?? LOOK.unknown }, measured(each.name)]),
249
+ ...(here.more > 0 ? [[{ text: lit(`+${here.more}`), width: `+${here.more}`.length, style: DIM }]] : []),
250
+ ];
251
+ flowed(units, inner, 2).forEach((spans) => rows.push(spans.map((span) => ({ ...span, col: span.col + INNER }))));
252
+ const key = keyOf(m, "soul-instances");
253
+ if (key && INNER + key.width + 1 < cols) rows.push([{ col: INNER, text: key.text, style: DIM, width: key.width }, { col: INNER + key.width + 1, text: lit(SOULS_TEXT.toInstances), style: DIM, width: cols - INNER - key.width - 1 }]);
254
+ }
255
+ return rows;
256
+ }
257
+
258
+ /** `{ rows, extent }`: `size.rows` rows of the detail for a pane `size.cols` wide, scrolled to the
259
+ * model's `detailTop`, and how many rows the whole detail has. The pane with the focus says so
260
+ * with `>` beside the title, never by an attribute alone (views/detail.mjs). */
261
+ export function soulDetail(m, size) {
262
+ const all = soulDetailRows(m, size.cols);
263
+ const rows = Array.from({ length: size.rows }, () => []);
264
+ const win = windowOf({ top: m.souls?.detailTop ?? 0, count: all.length, height: size.rows });
265
+ all.slice(win.top, win.top + win.size).forEach((spans, i) => { rows[i] = spans; });
266
+ const note = cutNote(win.above, win.below);
267
+ if (note && size.rows > 0) rows[size.rows - 1] = [{ col: LEFT, text: lit(note), style: DIM, width: Math.max(0, size.cols - LEFT) }];
268
+ if (m.souls?.focus === "detail" && size.rows > 0 && all.length) rows[0] = [{ col: 0, text: lit(">"), style: BOLD, width: 1 }, ...rows[0]];
269
+ return { rows, extent: all.length };
270
+ }