docs: document per-tab floating panes

commit: c22bfd8c34f6cc332d237e447e62e3edb0c60599
author: brice · 3mo ago · 2026-07-10 10:40 UTC
parent: a0541a8
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +15 -0

M README.md +15 -0


@@ -49,8 +49,14 @@ vev reads `$XDG_CONFIG_HOME/vev/config`, or `~/.config/vev/config` when `XDG_CON
49	49		# Theme: auto follows the client; dark/light force built-in palettes.
50	50		theme = auto
51	51
	52	+	# One prewarmed floating terminal per tab. An empty command uses the normal shell.
	53	+	floating.command =
	54	+	floating.width = 80%
	55	+	floating.height = 80%
	56	+
52	57		# Rebindable actions. Leave a line out to keep its built-in binding.
53	58		open-palette = alt+space
	59	+	toggle-floating-pane = alt+f
54	60		jump-attention = alt+a
55	61		focus-pane-left = alt+h
56	62		focus-pane-right = alt+l

@@ -97,6 +103,7 @@ code.back-session = BSK
97	103		code.forward-session = FSK
98	104		code.session-picker = SSP
99	105		code.visual-mode = VIS
	106	+	code.toggle-floating-pane = FLT
100	107		code.rename-session = RNS
101	108		code.detach = DET
102	109		```

@@ -105,6 +112,8 @@ Configuring an action replaces all of its built-in aliases. In the example above
105	112
106	113		Key specs support `alt+<char>`, `alt+space`, and `alt+left/right/up/down`; digit key specs support `alt+1` through `alt+9`, not `alt+0`. `jump-attention` first opens the oldest attention tab in the current session; if none exists, it opens the oldest attention tab in another session. Invalid entries are logged as warnings and skipped where possible; duplicate config keys use the last value, binding conflicts keep the later action's defaults, and command-code conflicts drop the conflicting override.
107	114
	115	+	`floating.width` and `floating.height` require exact percentages from `1%` through `100%`; invalid values log a warning and retain the `80%` default. Reloaded floating settings apply to future floating processes only. Running processes, visibility, terminal screens, and scrollback remain unchanged, and only the configuration—not floating runtime state—is restored after a daemon restart.
	116	+
108	117		### Bar right anchors
109	118
110	119		The top and bottom bar right anchors run configurable commands on the daemon host. By default, `bar.top-right = vev-bar-top-right` prints CPU, memory, then hour text (for example `C 12% M 48% 09:41`), and `bar.bottom-right = vev-bar-bottom-right` prints compact git state for the focused pane's `VEV_PANE_CWD`. Set either value empty to disable that anchor, or set it to another command to replace it.

@@ -145,6 +154,7 @@ All bindings use Alt directly; there is no prefix key.
145	154		\| Key \| Action \|
146	155		\|---\|---\|
147	156		\| Alt+Space \| open the command palette \|
	157	+	\| Alt+f \| show or hide the current tab's floating terminal \|
148	158		\| Alt+1 .. Alt+9 \| switch to tab by number \|
149	159		\| Alt+h/j/k/l \| focus pane left/down/up/right \|
150	160		\| Alt+Arrow \| focus pane by direction \|

@@ -172,6 +182,7 @@ Successful commands are promoted near the top the next time the palette opens.
172	182		\| BSK / FSK \| move back / forward through recent sessions \|
173	183		\| SSP \| open session picker \|
174	184		\| VIS \| enter visual mode \|
	185	+	\| FLT \| show or hide the current tab's floating terminal \|
175	186		\| RNS \| rename session \|
176	187		\| RNT \| rename current tab \|
177	188		\| DET \| detach \|

@@ -193,6 +204,10 @@ Open it with `SSP` in the palette. It lists sessions and tabs, previews the sele
193	204
194	205		Tabs hold pane layouts. Panes can be split left/right/up/down, stacked, focused by direction, and closed from the command palette. Clicking a pane focuses it.
195	206
	207	+	Each tab also owns one independent floating terminal. It prewarms asynchronously on the tab's first visit, opens centered at the configured percentage of the pane-content area, and dims normal pane content while leaving status bars and popup chrome crisp. Hiding it retains the process, screen, and scrollback; switching tabs restores each tab's own visible or hidden state. Process exit clears the slot so the next open recreates it. The title combines the foreground process and OSC terminal title as `ProcessName: ProcessTerminalTitle`, falling back to either available title and then the configured command or shell.
	208	+
	209	+	While visible, the floating terminal receives ordinary input, bracketed paste, mouse input, clipboard-path injection, and scrollback/copy mode. Global vev bindings remain active, and a bare Esc is passed to the floating application. `Alt+f` and `FLT` toggle visibility; there is no separate floating-pane close command.
	210	+
196	211		The top bar shows numbered tabs. The bottom bar shows the active session followed by recent sessions, fading toward older entries. Ephemeral sessions are marked with ``, for example `0`.
197	212
198	213		## Scrollback mode and copy


@@ -49,8 +49,14 @@ vev reads `$XDG_CONFIG_HOME/vev/config`, or `~/.config/vev/config` when `XDG_CON
49	# Theme: auto follows the client; dark/light force built-in palettes.	49		# Theme: auto follows the client; dark/light force built-in palettes.
50	theme = auto	50		theme = auto
51		51
		52	+	# One prewarmed floating terminal per tab. An empty command uses the normal shell.
		53	+	floating.command =
		54	+	floating.width = 80%
		55	+	floating.height = 80%
		56	+
52	# Rebindable actions. Leave a line out to keep its built-in binding.	57		# Rebindable actions. Leave a line out to keep its built-in binding.
53	open-palette = alt+space	58		open-palette = alt+space
		59	+	toggle-floating-pane = alt+f
54	jump-attention = alt+a	60		jump-attention = alt+a
55	focus-pane-left = alt+h	61		focus-pane-left = alt+h
56	focus-pane-right = alt+l	62		focus-pane-right = alt+l

@@ -97,6 +103,7 @@ code.back-session = BSK
97	code.forward-session = FSK	103		code.forward-session = FSK
98	code.session-picker = SSP	104		code.session-picker = SSP
99	code.visual-mode = VIS	105		code.visual-mode = VIS
		106	+	code.toggle-floating-pane = FLT
100	code.rename-session = RNS	107		code.rename-session = RNS
101	code.detach = DET	108		code.detach = DET
102	```	109		```

@@ -105,6 +112,8 @@ Configuring an action replaces all of its built-in aliases. In the example above
105		112
106	Key specs support `alt+<char>`, `alt+space`, and `alt+left/right/up/down`; digit key specs support `alt+1` through `alt+9`, not `alt+0`. `jump-attention` first opens the oldest attention tab in the current session; if none exists, it opens the oldest attention tab in another session. Invalid entries are logged as warnings and skipped where possible; duplicate config keys use the last value, binding conflicts keep the later action's defaults, and command-code conflicts drop the conflicting override.	113		Key specs support `alt+<char>`, `alt+space`, and `alt+left/right/up/down`; digit key specs support `alt+1` through `alt+9`, not `alt+0`. `jump-attention` first opens the oldest attention tab in the current session; if none exists, it opens the oldest attention tab in another session. Invalid entries are logged as warnings and skipped where possible; duplicate config keys use the last value, binding conflicts keep the later action's defaults, and command-code conflicts drop the conflicting override.
107		114
		115	+	`floating.width` and `floating.height` require exact percentages from `1%` through `100%`; invalid values log a warning and retain the `80%` default. Reloaded floating settings apply to future floating processes only. Running processes, visibility, terminal screens, and scrollback remain unchanged, and only the configuration—not floating runtime state—is restored after a daemon restart.
		116	+
108	### Bar right anchors	117		### Bar right anchors
109		118
110	The top and bottom bar right anchors run configurable commands on the daemon host. By default, `bar.top-right = vev-bar-top-right` prints CPU, memory, then hour text (for example `C 12% M 48% 09:41`), and `bar.bottom-right = vev-bar-bottom-right` prints compact git state for the focused pane's `VEV_PANE_CWD`. Set either value empty to disable that anchor, or set it to another command to replace it.	119		The top and bottom bar right anchors run configurable commands on the daemon host. By default, `bar.top-right = vev-bar-top-right` prints CPU, memory, then hour text (for example `C 12% M 48% 09:41`), and `bar.bottom-right = vev-bar-bottom-right` prints compact git state for the focused pane's `VEV_PANE_CWD`. Set either value empty to disable that anchor, or set it to another command to replace it.

@@ -145,6 +154,7 @@ All bindings use Alt directly; there is no prefix key.
145	\| Key \| Action \|	154		\| Key \| Action \|
146	\|---\|---\|	155		\|---\|---\|
147	\| Alt+Space \| open the command palette \|	156		\| Alt+Space \| open the command palette \|
		157	+	\| Alt+f \| show or hide the current tab's floating terminal \|
148	\| Alt+1 .. Alt+9 \| switch to tab by number \|	158		\| Alt+1 .. Alt+9 \| switch to tab by number \|
149	\| Alt+h/j/k/l \| focus pane left/down/up/right \|	159		\| Alt+h/j/k/l \| focus pane left/down/up/right \|
150	\| Alt+Arrow \| focus pane by direction \|	160		\| Alt+Arrow \| focus pane by direction \|

@@ -172,6 +182,7 @@ Successful commands are promoted near the top the next time the palette opens.
172	\| BSK / FSK \| move back / forward through recent sessions \|	182		\| BSK / FSK \| move back / forward through recent sessions \|
173	\| SSP \| open session picker \|	183		\| SSP \| open session picker \|
174	\| VIS \| enter visual mode \|	184		\| VIS \| enter visual mode \|
		185	+	\| FLT \| show or hide the current tab's floating terminal \|
175	\| RNS \| rename session \|	186		\| RNS \| rename session \|
176	\| RNT \| rename current tab \|	187		\| RNT \| rename current tab \|
177	\| DET \| detach \|	188		\| DET \| detach \|

@@ -193,6 +204,10 @@ Open it with `SSP` in the palette. It lists sessions and tabs, previews the sele
193		204
194	Tabs hold pane layouts. Panes can be split left/right/up/down, stacked, focused by direction, and closed from the command palette. Clicking a pane focuses it.	205		Tabs hold pane layouts. Panes can be split left/right/up/down, stacked, focused by direction, and closed from the command palette. Clicking a pane focuses it.
195		206
		207	+	Each tab also owns one independent floating terminal. It prewarms asynchronously on the tab's first visit, opens centered at the configured percentage of the pane-content area, and dims normal pane content while leaving status bars and popup chrome crisp. Hiding it retains the process, screen, and scrollback; switching tabs restores each tab's own visible or hidden state. Process exit clears the slot so the next open recreates it. The title combines the foreground process and OSC terminal title as `ProcessName: ProcessTerminalTitle`, falling back to either available title and then the configured command or shell.
		208	+
		209	+	While visible, the floating terminal receives ordinary input, bracketed paste, mouse input, clipboard-path injection, and scrollback/copy mode. Global vev bindings remain active, and a bare Esc is passed to the floating application. `Alt+f` and `FLT` toggle visibility; there is no separate floating-pane close command.
		210	+
196	The top bar shows numbered tabs. The bottom bar shows the active session followed by recent sessions, fading toward older entries. Ephemeral sessions are marked with ``, for example `0`.	211		The top bar shows numbered tabs. The bottom bar shows the active session followed by recent sessions, fading toward older entries. Ephemeral sessions are marked with ``, for example `0`.
197		212
198	## Scrollback mode and copy	213		## Scrollback mode and copy