@awebai/oats 0.56.0 → 0.57.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
// An agent's terminal, as cells: what `tmux capture-pane -e -N` captured (the text `-p` prints), turned into the
|
|
2
|
+
// screen's spans (term/screen.mjs). Pure: no IO.
|
|
3
|
+
//
|
|
4
|
+
// The capture is text the TUI did not write, from a program that may write anything, so nothing
|
|
5
|
+
// of it reaches the screen as it came. The characters are kept, measured by width.mjs, and set
|
|
6
|
+
// at the column each one takes; of the escape sequences only SGR is read, as a state machine
|
|
7
|
+
// over an allowlist, and the style of a cell is built from that state by style.mjs's
|
|
8
|
+
// agentStyle(). Every other sequence, every control character and every bidi control is
|
|
9
|
+
// dropped, and what is left becomes safe text through text.mjs's cellText(), which refuses
|
|
10
|
+
// anything this module should have dropped.
|
|
11
|
+
//
|
|
12
|
+
// How tmux writes a capture with `-e` (measured on tmux 3.7c): each row is the pane's cells from
|
|
13
|
+
// column 0 and ends at "\n"; a wide character is written once, the next character two cells on;
|
|
14
|
+
// a run of cells a tab left is one "\t"; an attribute is written where it changes from the cell
|
|
15
|
+
// before, ACROSS rows (a row that goes on in the style the last one ended in starts with no SGR
|
|
16
|
+
// at all), so the SGR state is carried from row to row and starts plain at the first row; and a
|
|
17
|
+
// hyperlink is an OSC 8, which is dropped with the rest.
|
|
18
|
+
import { cells } from "./width.mjs";
|
|
19
|
+
import { cellText } from "./text.mjs";
|
|
20
|
+
import { agentStyle, blankShows } from "./style.mjs";
|
|
21
|
+
|
|
22
|
+
/** Tab stops are every 8 columns: tmux writes a tab's cells as one "\t" and does not say how
|
|
23
|
+
* many there were, and a program that set its own stops is the rare case. Each row is set on its
|
|
24
|
+
* own, so a stop guessed wrong moves only the rest of that row. A tab moves to the stop and paints
|
|
25
|
+
* nothing: the cells it passes are blank. */
|
|
26
|
+
const TAB = 8;
|
|
27
|
+
/** A run of characters that are written as they are: no control (C0, DEL, C1) and no bidi
|
|
28
|
+
* control. Sticky, so each run is matched where the scan stands. */
|
|
29
|
+
const TEXT_RUN = /[^\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]+/y;
|
|
30
|
+
|
|
31
|
+
// ── The SGR state ────────────────────────────────────────────────────────────────────────────────
|
|
32
|
+
|
|
33
|
+
/** The state with nothing set. A state is a plain object this module alone changes; agentStyle()
|
|
34
|
+
* interns the style made from it. */
|
|
35
|
+
const fresh = () => ({ bold: false, dim: false, italic: false, underline: false, blink: false, reverse: false, invisible: false, strikethrough: false, fg: null, bg: null });
|
|
36
|
+
/** Single parameters that set or clear attributes, and what each does to the state. */
|
|
37
|
+
const SIMPLE = new Map([
|
|
38
|
+
[1, { bold: true }], [2, { dim: true }], [3, { italic: true }], [4, { underline: true }],
|
|
39
|
+
[5, { blink: true }], [6, { blink: true }], [7, { reverse: true }], [8, { invisible: true }], [9, { strikethrough: true }],
|
|
40
|
+
[21, { bold: false }], [22, { bold: false, dim: false }], [23, { italic: false }], [24, { underline: false }],
|
|
41
|
+
[25, { blink: false }], [27, { reverse: false }], [28, { invisible: false }], [29, { strikethrough: false }],
|
|
42
|
+
[39, { fg: null }], [49, { bg: null }],
|
|
43
|
+
]);
|
|
44
|
+
/** A parameter as a number: decimal digits only, at most three of them (no value this module
|
|
45
|
+
* keeps is larger), else null. An empty parameter is 0, as ECMA-48 has it. */
|
|
46
|
+
function number(text) {
|
|
47
|
+
if (text === "") return 0;
|
|
48
|
+
return /^\d{1,3}$/.test(text) ? Number(text) : null;
|
|
49
|
+
}
|
|
50
|
+
const byte = (text) => { const n = text === undefined ? null : number(text); return n !== null && n < 256 ? n : null; };
|
|
51
|
+
/** The colour an extended form names: `5;n` or `2;r;g;b`, as the list of what follows 38 or 48.
|
|
52
|
+
* Null when malformed or out of range. */
|
|
53
|
+
function extended(kind, values) {
|
|
54
|
+
if (kind === 5 && values.length === 1) { const n = byte(values[0]); return n === null ? null : { index: n }; }
|
|
55
|
+
if (kind === 2 && values.length === 3) { const rgb = values.map(byte); return rgb.includes(null) ? null : { rgb }; }
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Applies the parameters of one SGR (`ESC [ <params> m`, the params as written) to the state.
|
|
60
|
+
* An allowlist: a parameter not named here is dropped and the rest still apply. An extended
|
|
61
|
+
* colour (38, 48, and 58 which is dropped) consumes what its selector claims, 5 one value and 2
|
|
62
|
+
* three, even when a value is missing or out of range, so a malformed colour is dropped and
|
|
63
|
+
* never read as attributes; a selector that is neither leaves the rest of the list unreadable,
|
|
64
|
+
* and the rest is dropped. The colon forms (4:n, 38:5:n, 38:2::r:g:b, 38:2:r:g:b) are one parameter each. */
|
|
65
|
+
function applySgr(state, params) {
|
|
66
|
+
const list = params.split(";");
|
|
67
|
+
for (let i = 0; i < list.length; i++) {
|
|
68
|
+
const p = list[i];
|
|
69
|
+
if (p.includes(":")) { colon(state, p.split(":")); continue; }
|
|
70
|
+
const n = number(p);
|
|
71
|
+
if (n === null) continue;
|
|
72
|
+
if (n === 0) Object.assign(state, fresh());
|
|
73
|
+
else if (SIMPLE.has(n)) Object.assign(state, SIMPLE.get(n));
|
|
74
|
+
else if (n >= 30 && n <= 37) state.fg = { ansi: n - 30 };
|
|
75
|
+
else if (n >= 90 && n <= 97) state.fg = { ansi: n - 90 + 8 };
|
|
76
|
+
else if (n >= 40 && n <= 47) state.bg = { ansi: n - 40 };
|
|
77
|
+
else if (n >= 100 && n <= 107) state.bg = { ansi: n - 100 + 8 };
|
|
78
|
+
else if (n === 38 || n === 48 || n === 58) {
|
|
79
|
+
const kind = number(list[i + 1] ?? "x");
|
|
80
|
+
const claims = kind === 5 ? 1 : kind === 2 ? 3 : null;
|
|
81
|
+
if (claims === null) return;
|
|
82
|
+
// 58, the underline's colour, is read as the other two are only to be dropped whole: its
|
|
83
|
+
// values are not attributes (tmux writes it as 58;5;n, and its 5 is not a blink).
|
|
84
|
+
const colour = n === 58 ? null : extended(kind, list.slice(i + 2, i + 2 + claims));
|
|
85
|
+
if (colour) state[n === 38 ? "fg" : "bg"] = colour;
|
|
86
|
+
i += 1 + claims;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
/** One colon parameter: 4:n (0 off, 1 to 5 an underline of some kind, which is kept as on), or an
|
|
91
|
+
* extended colour 38:5:n, 38:2:r:g:b or 38:2:<colour space>:r:g:b (and 48). Anything else, the
|
|
92
|
+
* underline colour 58 among them, is dropped. */
|
|
93
|
+
function colon(state, sub) {
|
|
94
|
+
if (sub[0] === "4" && sub.length === 2) {
|
|
95
|
+
const n = number(sub[1]);
|
|
96
|
+
if (n !== null && n <= 5) state.underline = n !== 0;
|
|
97
|
+
return;
|
|
98
|
+
}
|
|
99
|
+
if (sub[0] !== "38" && sub[0] !== "48") return;
|
|
100
|
+
const kind = number(sub[1] ?? "x");
|
|
101
|
+
let values = sub.slice(2);
|
|
102
|
+
if (kind === 2 && values.length === 4 && /^\d*$/.test(values[0])) values = values.slice(1);
|
|
103
|
+
const colour = extended(kind, values);
|
|
104
|
+
if (colour) state[sub[0] === "38" ? "fg" : "bg"] = colour;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// ── Sequences ────────────────────────────────────────────────────────────────────────────────────
|
|
108
|
+
|
|
109
|
+
/** Where a control string (OSC, DCS, SOS, PM, APC) that starts at `from` ends: past its BEL (OSC
|
|
110
|
+
* only), its ST (`ESC \` or U+009C), or before an ESC that starts something else. -1 when the row
|
|
111
|
+
* ends first: the string is cut, and the rest of the row with it. */
|
|
112
|
+
function stringEnd(row, from, bel) {
|
|
113
|
+
for (let i = from; i < row.length; i++) {
|
|
114
|
+
const c = row.charCodeAt(i);
|
|
115
|
+
if ((bel && c === 0x07) || c === 0x9c) return i + 1;
|
|
116
|
+
if (c === 0x1b) return row[i + 1] === "\\" ? i + 2 : i;
|
|
117
|
+
}
|
|
118
|
+
return -1;
|
|
119
|
+
}
|
|
120
|
+
/** Where a CSI whose parameters start at `from` ends, and its parameters and final byte:
|
|
121
|
+
* `{ end, params, final }`, with `final` null when a byte outside a CSI stops it (the sequence
|
|
122
|
+
* ends before that byte, which is read again). `end` -1 when the row ends first. */
|
|
123
|
+
function csiEnd(row, from) {
|
|
124
|
+
let i = from;
|
|
125
|
+
while (i < row.length && row.charCodeAt(i) >= 0x30 && row.charCodeAt(i) <= 0x3f) i++;
|
|
126
|
+
const params = row.slice(from, i);
|
|
127
|
+
let intermediate = false;
|
|
128
|
+
while (i < row.length && row.charCodeAt(i) >= 0x20 && row.charCodeAt(i) <= 0x2f) { i++; intermediate = true; }
|
|
129
|
+
if (i >= row.length) return { end: -1 };
|
|
130
|
+
const c = row.charCodeAt(i);
|
|
131
|
+
if (c >= 0x40 && c <= 0x7e) return { end: i + 1, params, final: intermediate ? null : row[i] };
|
|
132
|
+
return { end: i, params, final: null };
|
|
133
|
+
}
|
|
134
|
+
/** Whether the parameters are an SGR's: a CSI with final `m` and no private marker (`<`, `=`, `>`,
|
|
135
|
+
* `?`: `CSI > 4;1 m` sets a keyboard mode, not a style). */
|
|
136
|
+
const isSgr = (final, params) => final === "m" && /^[0-9:;]*$/.test(params);
|
|
137
|
+
|
|
138
|
+
// ── Rows ─────────────────────────────────────────────────────────────────────────────────────────
|
|
139
|
+
|
|
140
|
+
/** One row of the capture as spans, from the SGR `state` it starts in, which it leaves as the row
|
|
141
|
+
* ended so the next row goes on from it. Past `cols` no character is kept, but the SGRs are
|
|
142
|
+
* still read: the next row may start in the style this one ended in. */
|
|
143
|
+
function captureRow(row, cols, state) {
|
|
144
|
+
const placed = [];
|
|
145
|
+
let col = 0, full = cols <= 0;
|
|
146
|
+
let look = agentStyle(state), pending = "";
|
|
147
|
+
/** Sets what was read in the current style, grapheme by grapheme, from the running column. */
|
|
148
|
+
function flush() {
|
|
149
|
+
if (pending === "") return;
|
|
150
|
+
const text = pending;
|
|
151
|
+
pending = "";
|
|
152
|
+
if (full) return;
|
|
153
|
+
for (const g of cells(text)) {
|
|
154
|
+
// A wide grapheme that would cross the edge is dropped, and so is everything after it: the
|
|
155
|
+
// terminal set the next one two cells on, past the edge too.
|
|
156
|
+
if (col + g.width > cols) { full = true; return; }
|
|
157
|
+
placed.push({ col, text: g.text, width: g.width, style: look });
|
|
158
|
+
col += g.width;
|
|
159
|
+
}
|
|
160
|
+
if (col >= cols) full = true;
|
|
161
|
+
}
|
|
162
|
+
/** After an SGR: the same style goes on in the same run, so graphemes split by an SGR that
|
|
163
|
+
* changed nothing are measured together, as the screen will measure them. */
|
|
164
|
+
function restyle() {
|
|
165
|
+
if (full) return;
|
|
166
|
+
const next = agentStyle(state);
|
|
167
|
+
if (next !== look) { flush(); look = next; }
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
for (let i = 0; i < row.length;) {
|
|
171
|
+
TEXT_RUN.lastIndex = i;
|
|
172
|
+
const run = TEXT_RUN.exec(row);
|
|
173
|
+
if (run) {
|
|
174
|
+
if (!full) pending += run[0];
|
|
175
|
+
i += run[0].length;
|
|
176
|
+
continue;
|
|
177
|
+
}
|
|
178
|
+
const c = row.charCodeAt(i);
|
|
179
|
+
if (c === 0x09) {
|
|
180
|
+
flush();
|
|
181
|
+
if (!full) { col = Math.min(col + TAB - (col % TAB), cols); full = col >= cols; }
|
|
182
|
+
i++;
|
|
183
|
+
continue;
|
|
184
|
+
}
|
|
185
|
+
if (c === 0x1b || c === 0x9b || c === 0x9d || c === 0x90 || c === 0x98 || c === 0x9e || c === 0x9f) {
|
|
186
|
+
const eight = c !== 0x1b;
|
|
187
|
+
const kind = eight ? String.fromCharCode(c - 0x40) : row[i + 1];
|
|
188
|
+
const body = eight ? i + 1 : i + 2;
|
|
189
|
+
// An ESC that ends the row: the sequence it began is cut, and dropped.
|
|
190
|
+
if (kind === undefined) break;
|
|
191
|
+
if (kind === "[") {
|
|
192
|
+
const { end, params, final } = csiEnd(row, body);
|
|
193
|
+
if (end < 0) break;
|
|
194
|
+
// Only the 7-bit SGR is read: the 8-bit CSI (U+009B) is dropped whole, its style too.
|
|
195
|
+
if (!eight && isSgr(final, params)) { applySgr(state, params); restyle(); }
|
|
196
|
+
i = end;
|
|
197
|
+
} else if (kind === "]" || kind === "P" || kind === "X" || kind === "^" || kind === "_") {
|
|
198
|
+
const end = stringEnd(row, body, kind === "]");
|
|
199
|
+
if (end < 0) break;
|
|
200
|
+
i = end;
|
|
201
|
+
} else {
|
|
202
|
+
// ESC with intermediates and a final (ESC ( B), or ESC and one final byte; an ESC before
|
|
203
|
+
// anything else is dropped alone and what follows it is read again.
|
|
204
|
+
let j = i + 1;
|
|
205
|
+
while (j < row.length && row.charCodeAt(j) >= 0x20 && row.charCodeAt(j) <= 0x2f) j++;
|
|
206
|
+
if (j >= row.length) break;
|
|
207
|
+
const f = row.charCodeAt(j);
|
|
208
|
+
i = f >= 0x30 && f <= 0x7e ? j + 1 : j > i + 1 ? j : i + 1;
|
|
209
|
+
}
|
|
210
|
+
continue;
|
|
211
|
+
}
|
|
212
|
+
// Every other control character, and a bidi control: dropped.
|
|
213
|
+
i++;
|
|
214
|
+
}
|
|
215
|
+
flush();
|
|
216
|
+
return spans(placed);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** The placed graphemes as spans: consecutive graphemes of one style, with no gap a tab left
|
|
220
|
+
* between them, are one span. Spaces in a style that shows nothing on a blank are left to the
|
|
221
|
+
* screen's own blank cells, so such a span never starts or ends with one, and a run of nothing
|
|
222
|
+
* else makes no span. */
|
|
223
|
+
function spans(placed) {
|
|
224
|
+
const out = [];
|
|
225
|
+
let open = null;
|
|
226
|
+
for (const g of placed) {
|
|
227
|
+
if (open && open.style === g.style && open.end === g.col) { open.graphemes.push(g); open.end += g.width; continue; }
|
|
228
|
+
open = { style: g.style, graphemes: [g], end: g.col + g.width };
|
|
229
|
+
out.push(open);
|
|
230
|
+
}
|
|
231
|
+
const result = [];
|
|
232
|
+
for (const { style, graphemes } of out) {
|
|
233
|
+
let first = 0, last = graphemes.length;
|
|
234
|
+
if (!blankShows(style)) {
|
|
235
|
+
while (first < last && graphemes[first].text === " ") first++;
|
|
236
|
+
while (last > first && graphemes[last - 1].text === " ") last--;
|
|
237
|
+
}
|
|
238
|
+
if (first === last) continue;
|
|
239
|
+
const kept = graphemes.slice(first, last);
|
|
240
|
+
const width = kept.reduce((sum, g) => sum + g.width, 0);
|
|
241
|
+
result.push(Object.freeze({ col: kept[0].col, text: cellText(kept.map((g) => g.text).join("")), style, width }));
|
|
242
|
+
}
|
|
243
|
+
return Object.freeze(result);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/** The rows of a capture-pane answer (`tmux capture-pane -e -N`, as `-p` prints it) as the screen's spans, for a
|
|
247
|
+
* panel of `cols` by `rows` cells: exactly `rows` rows, the first ones of the capture, each an
|
|
248
|
+
* array of `{ col, text, style, width }` with `col` from 0 inside the panel, `text` safe text
|
|
249
|
+
* (cellText), `style` an agent style (or PLAIN) and `width` the cells it takes. A row holds at
|
|
250
|
+
* most `cols` cells: what is past the edge is dropped, never wrapped. A capture with fewer rows
|
|
251
|
+
* gives empty rows after them; the newline that ends the last row is not a row of its own. */
|
|
252
|
+
export function captureRows(text, { cols, rows }) {
|
|
253
|
+
if (typeof text !== "string") throw new TypeError("a capture is the text tmux answered");
|
|
254
|
+
if (!Number.isInteger(cols) || cols < 0 || !Number.isInteger(rows) || rows < 0) throw new RangeError("a panel's size is a number of cells");
|
|
255
|
+
const lines = text.split("\n");
|
|
256
|
+
if (text.endsWith("\n")) lines.pop();
|
|
257
|
+
const state = fresh(), out = [];
|
|
258
|
+
for (let r = 0; r < rows; r++) out.push(r < lines.length ? captureRow(lines[r], cols, state) : Object.freeze([]));
|
|
259
|
+
return Object.freeze(out);
|
|
260
|
+
}
|
|
@@ -1,28 +1,38 @@
|
|
|
1
1
|
// The screen: a buffer of cells and the bytes that turn the previous frame into the next one.
|
|
2
2
|
// With term/tty.mjs it is the only module that produces an ESC byte, and what it writes is a closed
|
|
3
|
-
// list: a position
|
|
4
|
-
//
|
|
3
|
+
// list: a position (CSI row;col H); an erase (CSI K, CSI 2J); an SGR it builds itself, a reset and
|
|
4
|
+
// the parameters style.mjs answers for a style value, of either kind (CSI 0;...m); the
|
|
5
|
+
// synchronized-output pair around each frame (CSI ?2026h, CSI ?2026l); and the cursor shown or
|
|
6
|
+
// hidden (CSI ?25h, CSI ?25l). Text reaches it as safe text only (term/text.mjs); a string is
|
|
7
|
+
// refused.
|
|
5
8
|
//
|
|
6
9
|
// The rules a width disagreement cannot break (docs/tui.md): every row write starts with an
|
|
7
10
|
// absolute position and is erased to its end, so a character the terminal draws wider or narrower
|
|
8
11
|
// than width.mjs counts moves nothing outside its own row; nothing is written past the last column.
|
|
12
|
+
//
|
|
13
|
+
// Each frame that writes anything is one synchronized update (DEC mode 2026): the terminal shows
|
|
14
|
+
// it whole or not yet, never half drawn. The mode is set at the start of the frame and reset at its
|
|
15
|
+
// end, so no frame leaves it set; a terminal that does not know the mode ignores both. The cursor
|
|
16
|
+
// is placed after every row, since each row write moves it.
|
|
9
17
|
import { cells } from "./width.mjs";
|
|
10
18
|
import { textOf } from "./text.mjs";
|
|
11
|
-
import { PLAIN, isStyle, sgr } from "./style.mjs";
|
|
19
|
+
import { PLAIN, blankShows, isStyle, sgr } from "./style.mjs";
|
|
12
20
|
|
|
13
21
|
const CSI = "\x1b[";
|
|
14
22
|
const RESET = `${CSI}0m`;
|
|
15
23
|
const CLEAR = `${CSI}2J`;
|
|
16
24
|
const ERASE_TO_END = `${CSI}K`;
|
|
17
25
|
const position = (row, col) => `${CSI}${row + 1};${col + 1}H`;
|
|
26
|
+
const SYNC_BEGIN = `${CSI}?2026h`;
|
|
27
|
+
const SYNC_END = `${CSI}?2026l`;
|
|
28
|
+
const CURSOR_SHOW = `${CSI}?25h`;
|
|
29
|
+
const CURSOR_HIDE = `${CSI}?25l`;
|
|
18
30
|
|
|
19
31
|
const cell = (text, width, style) => Object.freeze({ text, width, style });
|
|
20
32
|
const BLANK = cell(" ", 1, PLAIN);
|
|
21
33
|
/** The second cell of a two-cell grapheme: it holds nothing to write. */
|
|
22
34
|
const TAIL = cell("", 0, PLAIN);
|
|
23
35
|
const PRINTABLE_ASCII = /^[\x20-\x7e]$/;
|
|
24
|
-
/** A cell that shows nothing: a space in a style that draws nothing on a space. */
|
|
25
|
-
const shows = (c) => c.text !== " " || c.style.underline || c.style.reverse;
|
|
26
36
|
|
|
27
37
|
/** What the locale and `--ascii` decide: `utf8`, whether the terminal is told to read UTF-8
|
|
28
38
|
* (LC_ALL, else LC_CTYPE, else LANG names it), and `ascii`, whether the TUI's own marks and rules
|
|
@@ -33,7 +43,10 @@ export function glyphs(env, { ascii = false } = {}) {
|
|
|
33
43
|
return { utf8, ascii: ascii || !utf8 };
|
|
34
44
|
}
|
|
35
45
|
|
|
36
|
-
/** A screen. `render(rows, size, { full })` answers the bytes for one frame and remembers
|
|
46
|
+
/** A screen. `render(rows, size, { full, cursor })` answers the bytes for one frame and remembers
|
|
47
|
+
* it: "" when nothing changed, else one synchronized update. `cursor` is null (hidden, as the
|
|
48
|
+
* TUI keeps it) or `{ row, col }`, a cell of the frame from 0, where the cursor is left shown; one
|
|
49
|
+
* outside the size is hidden. `full` draws the frame whole and states the cursor again.
|
|
37
50
|
* `rows[r]` is the spans of row r, drawn in order, a later one over an earlier one:
|
|
38
51
|
* `{ col, text, style?, width? }`, `text` safe text, `width` the cells the span may take (default:
|
|
39
52
|
* to the right edge); or a fill, `{ col, width, style? }`, `width` blank cells in that style.
|
|
@@ -42,6 +55,10 @@ export function glyphs(env, { ascii = false } = {}) {
|
|
|
42
55
|
export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {}) {
|
|
43
56
|
const mark = cells(ascii ? "..." : "\u2026");
|
|
44
57
|
let previous = null;
|
|
58
|
+
/** The cursor the last frame left: null hidden, else `{ row, col }` shown there. */
|
|
59
|
+
let cursorShown = null;
|
|
60
|
+
/** A cell that shows: anything but a space, or a space in a style that paints it. */
|
|
61
|
+
const shows = (c) => c.text !== " " || blankShows(c.style, { color });
|
|
45
62
|
|
|
46
63
|
/** Overwriting one half of a two-cell grapheme blanks the other half. */
|
|
47
64
|
function clear(line, x) {
|
|
@@ -114,7 +131,16 @@ export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {})
|
|
|
114
131
|
return end < line.length ? out + ERASE_TO_END : out;
|
|
115
132
|
}
|
|
116
133
|
|
|
117
|
-
|
|
134
|
+
/** Where the frame leaves the cursor: null hidden, else a cell inside the size. */
|
|
135
|
+
function cursorOf(cursor, size) {
|
|
136
|
+
if (cursor === null || cursor === undefined) return null;
|
|
137
|
+
if (typeof cursor !== "object" || !Number.isInteger(cursor.row) || !Number.isInteger(cursor.col)) throw new TypeError("a cursor is null or { row, col }, a cell index from 0");
|
|
138
|
+
const { row, col } = cursor;
|
|
139
|
+
return row >= 0 && col >= 0 && row < size.rows && col < size.cols ? { row, col } : null;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function render(rows, size, { full = false, cursor = null } = {}) {
|
|
143
|
+
const wanted = cursorOf(cursor, size);
|
|
118
144
|
const lines = layout(rows, size);
|
|
119
145
|
const redraw = full || !previous || previous.cols !== size.cols || previous.rows !== size.rows;
|
|
120
146
|
let out = redraw ? RESET + CLEAR : "";
|
|
@@ -127,8 +153,18 @@ export function createScreen({ utf8 = true, ascii = !utf8, color = true } = {})
|
|
|
127
153
|
// as sure as the width table, so nothing in it is addressed by column.
|
|
128
154
|
out += writeRow(r, line, asciiOnly(line) && asciiOnly(old) ? changed : 0);
|
|
129
155
|
}
|
|
156
|
+
// The cursor after every row: a row write leaves it at the row's end, so a shown cursor is
|
|
157
|
+
// placed again whenever a row was written, and a redraw shows it again (the guard's ENTER, at
|
|
158
|
+
// a start, a resume or a Ctrl+L, hides it). A hidden one is hidden only when this screen had
|
|
159
|
+
// shown it: hiding it is the guard's, and a frame adds no mode the guard did not switch.
|
|
160
|
+
if (wanted) {
|
|
161
|
+
const moved = out !== "" || !cursorShown || cursorShown.row !== wanted.row || cursorShown.col !== wanted.col;
|
|
162
|
+
if (moved) out += position(wanted.row, wanted.col);
|
|
163
|
+
if (redraw || !cursorShown) out += CURSOR_SHOW;
|
|
164
|
+
} else if (cursorShown) out += CURSOR_HIDE;
|
|
130
165
|
previous = { cols: size.cols, rows: size.rows, lines };
|
|
131
|
-
|
|
166
|
+
cursorShown = wanted;
|
|
167
|
+
return out === "" ? "" : SYNC_BEGIN + out + SYNC_END;
|
|
132
168
|
}
|
|
133
169
|
return { render, cells: layout };
|
|
134
170
|
}
|
|
@@ -1,6 +1,13 @@
|
|
|
1
|
-
// Style values,
|
|
2
|
-
//
|
|
3
|
-
//
|
|
1
|
+
// Style values, of two kinds. This module holds SGR parameters as numbers; the screen is what writes
|
|
2
|
+
// the sequence, and a value only this module made is one it writes.
|
|
3
|
+
//
|
|
4
|
+
// The TUI's own: the terminal's sixteen colours and four attributes (docs/tui.md), `style()`. No
|
|
5
|
+
// background, no 256-colour or RGB value, so the user's theme stays the theme.
|
|
6
|
+
// The agent's own: what an agent's terminal set, read from its capture by term/capture.mjs and
|
|
7
|
+
// drawn only in the terminal panel, `agentStyle()`. Those colours are the agent's, not the TUI's,
|
|
8
|
+
// so this kind has a background and 256-colour and RGB values. It is still a closed set built
|
|
9
|
+
// from a state of named fields: nothing of the agent's sequence text is kept, only the numbers
|
|
10
|
+
// this module writes back for it.
|
|
4
11
|
|
|
5
12
|
const FOREGROUND = Object.freeze({
|
|
6
13
|
black: 30, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36, white: 37,
|
|
@@ -23,7 +30,7 @@ export function style(spec = {}) {
|
|
|
23
30
|
const id = [...attributes, spec.fg ?? ""].join(",");
|
|
24
31
|
if (!made.has(id)) {
|
|
25
32
|
const value = Object.freeze({ fg: spec.fg ?? null, ...Object.fromEntries(ATTRIBUTES.map((name) => [name, attributes.includes(name)])) });
|
|
26
|
-
parameters.set(value, Object.freeze({ attributes: attributes.map((name) => ATTRIBUTE[name]), colour: spec.fg === undefined ? [] : [FOREGROUND[spec.fg]] }));
|
|
33
|
+
parameters.set(value, Object.freeze({ attributes: attributes.map((name) => ATTRIBUTE[name]), colour: spec.fg === undefined ? [] : [FOREGROUND[spec.fg]], background: false }));
|
|
27
34
|
made.set(id, value);
|
|
28
35
|
}
|
|
29
36
|
return made.get(id);
|
|
@@ -31,13 +38,78 @@ export function style(spec = {}) {
|
|
|
31
38
|
export const PLAIN = style();
|
|
32
39
|
export const isStyle = (value) => parameters.has(value);
|
|
33
40
|
|
|
34
|
-
|
|
35
|
-
|
|
41
|
+
// ── The agent's own ──────────────────────────────────────────────────────────────────────────────
|
|
42
|
+
|
|
43
|
+
/** The attributes an agent's style keeps, in the order their parameters are written. Each is on
|
|
44
|
+
* or off: an underline's kind (curly, dotted) is not kept, so 4:3 is written back as 4. */
|
|
45
|
+
const AGENT_ATTRIBUTE = Object.freeze({ bold: 1, dim: 2, italic: 3, underline: 4, blink: 5, reverse: 7, invisible: 8, strikethrough: 9 });
|
|
46
|
+
export const AGENT_ATTRIBUTES = Object.freeze(Object.keys(AGENT_ATTRIBUTE));
|
|
47
|
+
const AGENT_KEYS = Object.freeze([...AGENT_ATTRIBUTES, "fg", "bg"]);
|
|
48
|
+
/** The agent's styles are interned apart and only so many are kept, the least recently made or
|
|
49
|
+
* asked for going first: an agent that writes a gradient in RGB names a new style per cell, and
|
|
50
|
+
* what the TUI keeps must not grow with what an agent writes. One that was let go and is asked
|
|
51
|
+
* for again is a new value, which costs the screen one rewrite of the rows it is in. */
|
|
52
|
+
export const AGENT_STYLES_KEPT = 4096;
|
|
53
|
+
const agentMade = new Map();
|
|
54
|
+
|
|
55
|
+
const isByte = (n) => Number.isInteger(n) && n >= 0 && n < 256;
|
|
56
|
+
/** A colour of an agent's style, checked and frozen: `null` (the terminal's default), `{ ansi: n }`
|
|
57
|
+
* one of the sixteen (0 to 15), `{ index: n }` one of 256, or `{ rgb: [r, g, b] }`. Anything else
|
|
58
|
+
* is refused: the parameters written for it are built from these numbers alone. */
|
|
59
|
+
function agentColour(colour) {
|
|
60
|
+
if (colour === undefined || colour === null) return null;
|
|
61
|
+
const keys = typeof colour === "object" ? Object.keys(colour) : [];
|
|
62
|
+
if (keys.length === 1 && keys[0] === "ansi" && Number.isInteger(colour.ansi) && colour.ansi >= 0 && colour.ansi <= 15) return Object.freeze({ ansi: colour.ansi });
|
|
63
|
+
if (keys.length === 1 && keys[0] === "index" && isByte(colour.index)) return Object.freeze({ index: colour.index });
|
|
64
|
+
if (keys.length === 1 && keys[0] === "rgb" && Array.isArray(colour.rgb) && colour.rgb.length === 3 && colour.rgb.every(isByte)) return Object.freeze({ rgb: Object.freeze([...colour.rgb]) });
|
|
65
|
+
throw new TypeError("an agent style's colour is null, { ansi: 0-15 }, { index: 0-255 } or { rgb: [r, g, b] } of 0-255");
|
|
66
|
+
}
|
|
67
|
+
const colourId = (colour) => (colour === null ? "" : "ansi" in colour ? `a${colour.ansi}` : "index" in colour ? `i${colour.index}` : `r${colour.rgb.join(".")}`);
|
|
68
|
+
/** The parameters of a colour: `base` is 30 for the foreground and 40 for the background, so the
|
|
69
|
+
* sixteen are base..base+7 and base+60..base+67, and the extended forms base+8 then 5;n or 2;r;g;b. */
|
|
70
|
+
function colourParameters(colour, base) {
|
|
71
|
+
if (colour === null) return [];
|
|
72
|
+
if ("ansi" in colour) return [colour.ansi < 8 ? base + colour.ansi : base + 60 + colour.ansi - 8];
|
|
73
|
+
if ("index" in colour) return [base + 8, 5, colour.index];
|
|
74
|
+
return [base + 8, 2, ...colour.rgb];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The style an agent's terminal set: `agentStyle({ bold: true, fg: { index: 208 }, bg: { rgb: [1, 2, 3] } })`,
|
|
78
|
+
* each attribute of AGENT_ATTRIBUTES true or absent, `fg` and `bg` a colour or null. Interned as
|
|
79
|
+
* style() is, so an equal state is the same value (of the AGENT_STYLES_KEPT last asked for). The state with nothing set is PLAIN, which the
|
|
80
|
+
* two kinds share: an agent's blank cell and the TUI's are one cell to the screen. */
|
|
81
|
+
export function agentStyle(state = {}) {
|
|
82
|
+
if (state === null || typeof state !== "object") throw new TypeError("an agent style is made from a state object");
|
|
83
|
+
for (const key of Object.keys(state)) if (!AGENT_KEYS.includes(key)) throw new TypeError(`unknown agent style key ${key}`);
|
|
84
|
+
const attributes = AGENT_ATTRIBUTES.filter((name) => state[name] === true);
|
|
85
|
+
const fg = agentColour(state.fg), bg = agentColour(state.bg);
|
|
86
|
+
if (attributes.length === 0 && fg === null && bg === null) return PLAIN;
|
|
87
|
+
const id = `${attributes.join(",")}|${colourId(fg)}|${colourId(bg)}`;
|
|
88
|
+
let value = agentMade.get(id);
|
|
89
|
+
if (value) { agentMade.delete(id); agentMade.set(id, value); return value; }
|
|
90
|
+
value = Object.freeze({ agent: true, ...Object.fromEntries(AGENT_ATTRIBUTES.map((name) => [name, attributes.includes(name)])), fg, bg });
|
|
91
|
+
parameters.set(value, Object.freeze({ attributes: attributes.map((name) => AGENT_ATTRIBUTE[name]), colour: [...colourParameters(fg, 30), ...colourParameters(bg, 40)], background: bg !== null }));
|
|
92
|
+
agentMade.set(id, value);
|
|
93
|
+
if (agentMade.size > AGENT_STYLES_KEPT) agentMade.delete(agentMade.keys().next().value);
|
|
94
|
+
return value;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** The SGR parameters of a style, attributes first and then the colours, foreground before
|
|
98
|
+
* background. Without `color` every colour is dropped and the attributes stay. */
|
|
36
99
|
export function sgr(value, { color = true } = {}) {
|
|
37
100
|
const own = parameters.get(value);
|
|
38
101
|
if (!own) throw new TypeError("not a style value: make one with style()");
|
|
39
102
|
return color ? [...own.attributes, ...own.colour] : [...own.attributes];
|
|
40
103
|
}
|
|
41
104
|
|
|
105
|
+
/** Whether a blank cell in this style shows: a space draws nothing of its own, so it shows only by
|
|
106
|
+
* what the style paints across the whole cell, an underline, reverse video, a strikethrough or a
|
|
107
|
+
* background. Without `color` a background is not written, so a space with only one shows nothing. */
|
|
108
|
+
export function blankShows(value, { color = true } = {}) {
|
|
109
|
+
const own = parameters.get(value);
|
|
110
|
+
if (!own) throw new TypeError("not a style value: make one with style()");
|
|
111
|
+
return value.underline || value.reverse || value.strikethrough === true || (color && own.background);
|
|
112
|
+
}
|
|
113
|
+
|
|
42
114
|
/** NO_COLOR (no-color.org): set and not empty switches colour off. */
|
|
43
115
|
export const colorEnabled = (env) => !(typeof env.NO_COLOR === "string" && env.NO_COLOR !== "");
|
|
@@ -1,10 +1,17 @@
|
|
|
1
1
|
// Safe text: the only thing the screen draws. A terminal acts on what is written to it, so the
|
|
2
2
|
// screen takes strings from nobody: it takes values only this module can make (docs/tui.md,
|
|
3
|
-
// awebai/oats#855 section 3.9). There are
|
|
4
|
-
// lit(string)
|
|
5
|
-
// shown(value)
|
|
3
|
+
// awebai/oats#855 section 3.9). There are three ways in, and no fourth:
|
|
4
|
+
// lit(string) the TUI's own words;
|
|
5
|
+
// shown(value) text the TUI did not write, through the shared display filter;
|
|
6
|
+
// cellText(string) the cells of an agent's terminal, which term/capture.mjs has already
|
|
7
|
+
// filtered, drawn only in the terminal panel.
|
|
6
8
|
// A safe value is for display only: nothing compares it, selects by it or passes it to a command.
|
|
7
9
|
//
|
|
10
|
+
// The third exists because the display filter is right for a line and wrong for a terminal's
|
|
11
|
+
// cells: it folds runs of spaces and trims, and a terminal's spaces are its layout. cellText()
|
|
12
|
+
// keeps the spaces and refuses, rather than filters: every character it would have to take out
|
|
13
|
+
// is one capture.mjs drops first, so a refusal is a bug there, never text to repair here.
|
|
14
|
+
//
|
|
8
15
|
// Every view meets this: the filter folds a run of spaces into one and trims both ends, so lit()
|
|
9
16
|
// refuses a string with two spaces together or a space at an end. A row is therefore spans placed
|
|
10
17
|
// by column (`{ col, text, style }`), never one padded string: the gap between two spans is the
|
|
@@ -99,11 +106,24 @@ export function shownLines(value, width, max, { ascii = false } = {}) {
|
|
|
99
106
|
return rows.map((row) => make(joined(row)));
|
|
100
107
|
}
|
|
101
108
|
|
|
109
|
+
/** What cellText() refuses: the C0 controls (ESC among them), DEL, the C1 controls, and the bidi
|
|
110
|
+
* controls (U+061C, U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069), which would let a row
|
|
111
|
+
* reorder what is drawn in it. */
|
|
112
|
+
const NOT_A_CELL = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/;
|
|
113
|
+
|
|
114
|
+
/** The text of an agent's terminal cells, as term/capture.mjs read them from a capture: spaces
|
|
115
|
+
* kept as they are. It throws on any character capture.mjs drops, and its message never repeats
|
|
116
|
+
* the string. For capture.mjs alone; any other text goes through lit() or shown(). */
|
|
117
|
+
export function cellText(string) {
|
|
118
|
+
if (typeof string !== "string" || NOT_A_CELL.test(string)) throw new TypeError("cellText() takes an agent's cells as term/capture.mjs filtered them: no control or bidi character");
|
|
119
|
+
return make(string);
|
|
120
|
+
}
|
|
121
|
+
|
|
102
122
|
export const isSafeText = (value) => TEXT.has(value);
|
|
103
123
|
|
|
104
124
|
/** The string of a safe value, for the screen (and the tests that read a row). A raw string and a
|
|
105
125
|
* forged object are refused. */
|
|
106
126
|
export function textOf(value) {
|
|
107
|
-
if (!TEXT.has(value)) throw new TypeError("the screen draws safe text only: lit() for the TUI's own words, shown() for anything else");
|
|
127
|
+
if (!TEXT.has(value)) throw new TypeError("the screen draws safe text only: lit() for the TUI's own words, shown() for anything else, cellText() for an agent's cells");
|
|
108
128
|
return TEXT.get(value);
|
|
109
129
|
}
|