aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authoruser <user@clank>2026-09-02 14:57:46 +0200
committeruser <user@clank>2026-09-02 14:57:46 +0200
commitbac4b796f3f729d8d76b9c7c973126eac49872f2 (patch)
tree0d040eb64e433122f982ea45912eba37ab54822a /docs
parentwebdemo: version from contrib/version, published by ship (diff)
parentmulti-attach: the config knobs (diff)
downloadslosh-bac4b796f3f729d8d76b9c7c973126eac49872f2.tar.gz
slosh-bac4b796f3f729d8d76b9c7c973126eac49872f2.tar.xz
slosh-bac4b796f3f729d8d76b9c7c973126eac49872f2.zip
Merge branch 'multiplayer': shared multi-client attach
Several terminals can attach to one session at once: the canonical screen becomes a model projected into every client's own size, with per-client diff history, input parsing and kitty graphics state. The active client (newest attach, then last input) sizes the canvas by default; multi_attach and size_follows in the config control both halves of the policy.
Diffstat (limited to 'docs')
-rw-r--r--docs/config.md2
-rw-r--r--docs/index.md4
-rw-r--r--docs/slosh.120
-rw-r--r--docs/slosh.520
4 files changed, 38 insertions, 8 deletions
diff --git a/docs/config.md b/docs/config.md
index 72668f0..71ca297 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -84,7 +84,7 @@ theme { frame_focus "#00ff88" } // ...but that one colour is mine
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| geometry | `gap` `gap_aspect` `padding` `compact` `rounded` `title_align` `title_inset` `min_pane` `min_split` |
| chrome | `status_bar` `status_line` `status_pad` `hints` `version_banner` `pane_buttons` `bell_indicator` and the marks (`zoom_mark` `zoom_on_mark` `close_mark` `min_mark` `newtab_mark` `bell_mark`) |
-| 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` `shell` `editor` |
+| 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` `size_follows` `shell` `editor` |
| projects | `project_roots` `project_layout` (see [workspaces](workspaces.md)) |
| colour | `theme { }` |
| effects | `shaders { }`, `states { }` (see [shaders](shaders.md) and [chrome](chrome.md)) |
diff --git a/docs/index.md b/docs/index.md
index 09b0466..c4d9746 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -62,7 +62,9 @@ slosh ls # what is running
```
Sessions keep running when you detach, or when your terminal or ssh connection
-goes away. Reattach with the same command.
+goes away. Several terminals can attach at once: the last one to interact sets
+the shared layout size, while the others see a cursor-following crop or blank
+filler. Reattach with the same command.
**TIP:** press `C-a ?` for the key combo cheatsheet, or `C-a p` for the command palette.
diff --git a/docs/slosh.1 b/docs/slosh.1
index 4a473af..3fb3ff1 100644
--- a/docs/slosh.1
+++ b/docs/slosh.1
@@ -51,6 +51,18 @@ creating it if nobody is home; detaching (or losing the connection)
leaves the session and everything in it running, and the same command
reattaches.
.PP
+Several terminals may attach to one session at once. The newest attachment,
+then the client with the most recent keyboard or mouse activity, sets the
+shared screen size. Resizing that active client resizes the session; resizing
+another client changes only its view. A smaller view follows the cursor over
+the shared screen, and a larger one is filled with blank cells. Detaching
+leaves the other clients attached. Both halves are configurable:
+.B multi_attach
+restores the old displacing attach, and
+.B size_follows
+picks whose size rules \(em see
+.BR slosh (5).
+.PP
A trailing
.B \-\-
.I command\ ...
@@ -58,9 +70,9 @@ is run in the first pane instead of the configured shell.
Every other pane runs the shell the configuration names, or
.BR $SHELL .
.PP
-Attaching from inside a pane of the same session is refused, because the
-new client would displace the very view it was typed into; the error
-message names the escape hatches.
+Attaching from inside a pane of the same session is refused, because it would
+draw the session recursively inside itself; the error message names the
+escape hatches.
Attaching to a
.I different
session from inside a pane is nesting, and allowed.
@@ -123,7 +135,7 @@ This is what the test suite drives.
.TP
.BI \-\-cols\ n ,\ \-\-rows\ n
The screen size for the headless modes (default 80\(mu24).
-When attaching from a terminal, the terminal's own size wins.
+When attaching from a terminal, its size enters the latest-active rule above.
.TP
.BI \-\-idle\-ms\ n
How long
diff --git a/docs/slosh.5 b/docs/slosh.5
index f523da0..4437035 100644
--- a/docs/slosh.5
+++ b/docs/slosh.5
@@ -147,6 +147,22 @@ The glyphs themselves, each one string.
Hovering focuses \(em never at the cost of what you were doing: not
during a prefix, a drag, or a modal.
.TP
+.BI multi_attach\ bool
+Several terminals may attach to one session at once (the default).
+Off, a new client displaces the previous one, which is the classic
+\[dq]move my session here and close it there\[dq].
+.TP
+.BI size_follows\ active\ |\ smallest\ |\ largest
+Whose size the shared screen takes when several clients are attached.
+.B active
+(the default) follows the newest attachment, then the last client to type or
+click; smaller clients see a cursor-following crop and larger ones blank
+filler.
+.B smallest
+is the tmux rule: nobody is cropped, the roomiest terminal pays in filler.
+.B largest
+gives the big display everything and the small ones a crop.
+.TP
.BI ctrl_d_exits\ bool
Ctrl-D at an idle shell prompt sends
.B exit
@@ -167,8 +183,8 @@ Applied to the next pane you open: shrinking history retroactively
would throw away output somebody is reading.
.TP
.BR toast_ms\ \fIn\fR ,\ splash_ms\ \fIn\fR
-How long an announcement stays up, and how long the logo greets an
-attach (0 for never).
+How long an announcement stays up, and how long the logo greets the first
+attach after a session had no viewers (0 for never).
.TP
.BI hover_delay_ms\ n
How long the pointer must rest on a border before the split guide arms.