aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoruser <user@clank>2026-09-22 15:12:02 +0200
committeruser <user@clank>2026-09-22 15:12:02 +0200
commit720aa48e249c0c962e8f73372ceded6092414a6e (patch)
treedb713dc86f1333dab0f509e633077384005562c3 /docs
parentsidebar: air inside it, the way panes have padding (tab_bar_padding) (diff)
downloadslosh-720aa48e249c0c962e8f73372ceded6092414a6e.tar.gz
slosh-720aa48e249c0c962e8f73372ceded6092414a6e.tar.xz
slosh-720aa48e249c0c962e8f73372ceded6092414a6e.zip
osc 5577: `busy`, and a sidebar that shows it (busy_mark)
A status is a line of text, and a line of text cannot say whether it is still true. "building 3/7" reads exactly the same while it builds and ten minutes after it stopped, which is the one thing somebody reading it from another tab wants to know -- and the only workaround available to a program was to write the answer into the words and keep rewriting them. So `busy`: printf '\033]5577;1;status;make test\033\\' printf '\033]5577;1;busy;1\033\\' ... printf '\033]5577;1;busy;0\033\\' A flag of its own rather than a field of `status`, because a status is the *whole* payload after the verb -- `status;a;b;c` has always been the text "a;b;c" -- so anything added to that line would change what every existing sender means, including the five pi extensions D1 promises byte compatibility to. Orthogonal, so a program can leave one line up and toggle the other; anything but 0/false/no/off is on; `clear` takes both; and a pane whose program has gone is never busy, whatever it last claimed, because a spinner turning under a dead tab is a lie you keep looking at. In a sidebar the row turns `tab_status_busy` -- the theme's accent, derived like the other status colours, so no theme needs a line -- and takes a spinner in the column `tab_bar_padding` was already holding blank, so nothing reflows when a program starts or stops working. `busy_mark` is the frames, separated by spaces: one frame is a static mark and costs nothing, several make it turn, and only then does the session keep a frame clock -- via the same `animating` flag an animated shader uses, so the cost lands only while such a row is actually composed, and `""` drops the mark entirely and leaves the colour to say it. The frame is a pure function of the clock, like every other pulse here, so two clients attached to one session show the same one. `panes` now reports `status` and `busy`, which is the scriptable half of the same fact: what a pane says about itself, without reading its screen.
Diffstat (limited to 'docs')
-rw-r--r--docs/config.md2
-rw-r--r--docs/panes.md11
-rw-r--r--docs/scripting.md13
-rw-r--r--docs/slosh.512
4 files changed, 37 insertions, 1 deletions
diff --git a/docs/config.md b/docs/config.md
index dba0dd2..a821a8d 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -134,7 +134,7 @@ whatever the file says.
| group | what is in it |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| geometry | `gap` `gap_aspect` `padding` `compact` `rounded` `title_align` `title_inset` `min_pane` `min_split` |
-| chrome | `status_bar` `status_line` `status_pad` `tab_bar_side` `tab_bar_index` `tab_bar_width` `tab_bar_padding` `tab_bar_pad` `tab_gap` `tab_bar_status` `tab_bar_status_lines` `tab_bar_chrome` `hints` `version_banner` `pane_buttons` `bell_indicator` `newtab_button` `newtab_pad` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark`) |
+| chrome | `status_bar` `status_line` `status_pad` `tab_bar_side` `tab_bar_index` `tab_bar_width` `tab_bar_padding` `tab_bar_pad` `tab_gap` `tab_bar_status` `tab_bar_status_lines` `tab_bar_chrome` `hints` `version_banner` `pane_buttons` `bell_indicator` `newtab_button` `newtab_pad` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark` `busy_mark` `busy_ms`) |
| behaviour | `focus_follows_mouse` `ctrl_d_exits` `scroll_lines` `scrollback` `scrollback_bytes` `toast_ms` `splash_ms` `hover_delay_ms` `double_click_ms` `word_separators` `anim_ms` `modal_scrim` `dim_unfocused` `float_shadow` `keep_dead` `in_band_shaders` `multi_attach` `attach_indicator` `size_follows` `shell` `editor` |
| projects | `project_roots` `project_layout` (see [workspaces](workspaces.md)) |
| colour | `theme { }` |
diff --git a/docs/panes.md b/docs/panes.md
index 7018fc8..0af41ce 100644
--- a/docs/panes.md
+++ b/docs/panes.md
@@ -98,6 +98,17 @@ way: **the statuses give way before the tabs do**, because the list is how you
navigate and a status is only an annotation on it — a talkative pane must not
be able to cost you a tab you can click.
+**A pane can say its status is still happening**, and the sidebar says so back:
+`busy` over OSC 5577 turns that row `tab_status_busy` and puts a spinner
+(`busy_mark`) in the column the padding holds blank — so `make test` running and
+`make test` finished, which are the same words, stop looking the same from
+another tab. Nothing moves when it flips, since the mark takes a column that
+was already there; `tab_bar_padding 0 2` gives it a gutter of its own. One frame
+in `busy_mark` is a static mark and costs nothing, several make it turn, and the
+session only keeps a frame clock while such a row is actually on screen. The
+flag dies with the program: a status left behind by something that exited
+describes the past.
+
**`tab_bar_padding` is the air inside the strip**, between its frame and the
list: 1, 2 or 4 values in CSS order, the shape [`padding`](config.md) takes for
a pane. In cells rather than `padding`'s rows-times-`gap_aspect`, because the
diff --git a/docs/scripting.md b/docs/scripting.md
index 048a7fa..9971bc5 100644
--- a/docs/scripting.md
+++ b/docs/scripting.md
@@ -93,6 +93,8 @@ By printing an escape sequence. No plugin, no config:
```bash
printf '\033]5577;1;status;building 3/7\033\\'
+printf '\033]5577;1;busy;1\033\\' # ...and it is still going
+printf '\033]5577;1;busy;0\033\\' # ...and now it is not
printf '\033]5577;1;buttons;approve:Approve;cancel:Cancel\033\\'
# clicking [Approve] arrives on the program's stdin as:
# \033]5577;1;click;approve\033\\
@@ -108,6 +110,17 @@ the pane that said it. A status is not decoration on your own frame; it is how
a pane reports progress to somebody working elsewhere, which is a reason to
keep it current and `clear` it when the work is done.
+`busy` is the one thing a line of text cannot say about itself: `make test` and
+`make test` are the same words whether it is running or finished. It is a flag
+of its own rather than a field of `status`, because a status is the *whole*
+payload after the verb — `status;a;b;c` is the text `a;b;c` — so anything added
+to that line would change what every sender already means. In a sidebar a busy
+status gets the spinner (`busy_mark`) and `tab_status_busy`, which is how
+"working" and "done" tell themselves apart from another tab without reading the
+words. Anything but `0`, `false`, `no` or `off` turns it on; `clear` turns it
+off along with the text, and so does the program exiting — a status left behind
+by something that is gone describes the past, whatever it last claimed.
+
`purpose` is the other verb: `printf '\033]5577;1;purpose;logs\033\\'`. A purpose
declared by a layout or the control API wins and cannot be overwritten this way.
diff --git a/docs/slosh.5 b/docs/slosh.5
index 6d6acc2..9c88c1e 100644
--- a/docs/slosh.5
+++ b/docs/slosh.5
@@ -211,6 +211,18 @@ Whether a pane's bell shows at all (the mark, and the frame effect).
.BR zoom_mark ,\ zoom_on_mark ,\ close_mark ,\ min_mark ,\ newtab_mark ,\ bell_mark
The glyphs themselves, each one string.
.TP
+.BR busy_mark\ \fIframes\fR ,\ busy_ms\ \fIn\fR
+What a pane whose status says it is still working shows in a sidebar, and
+how long a frame of it is held.
+.B busy_mark
+is the spinner's frames separated by spaces; one frame is a static mark and
+costs nothing, several make it turn, and the session keeps a frame clock only
+while such a row is on screen. Empty draws no mark and leaves
+.B tab_status_busy
+to say it. The mark sits in the column
+.B tab_bar_padding
+holds blank, so nothing moves when a program starts or stops working.
+.TP
.BR newtab_button\ \fIbool\fR ,\ newtab_pad\ \fIn\fR
The new-tab button at the end of the tab strip, and the air between it and
the last tab \(em \fIn\fR blank rows in a sidebar, \fIn\fR blank columns in