# Workspaces and windows

URL: https://tuios.dev/docs/configuration/workspaces-and-windows

> Workspaces and windows: part of the Configuration of TUIOS.

This page is one part of `docs/CONFIGURATION.md` of the [tuios repository](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/CONFIGURATION.md). The [Configuration](https://tuios.dev/docs/configuration) page lists every part.

## Graphical programs from the launcher

The launcher starts a desktop entry in a new pane. A graphical program opens
its own window, so its pane stays empty. Set [`launcher.gui_command`](https://tuios.dev/docs/option-reference#launcher.gui_command) to start
such an entry with another command. The launcher adds the entry's argv to that
command. Entries with `Terminal=true` and programs from `$PATH` still open in
a pane.

```toml
[launcher]
gui_command = "tuios-wayland launch --"   # or "niri msg action spawn --"
```

Use only a command that takes an argv and runs it as an argv. Do not use a
command that joins its arguments into a shell line, such as `swaymsg exec --`
or `hyprctl dispatch exec`. With such a command, the text of a desktop entry
becomes shell code. Any installed package can write a desktop entry.

A program from the launcher closes its pane when it exits. Set
[`launcher.keep_open`](https://tuios.dev/docs/option-reference#launcher.keep_open) to keep the pane. A line under the output shows the exit
status, as with `tuios new-window --keep-open`. Close the pane when you are
done with it. The option needs a daemon session. With `--standalone` the pane
closes as before.

```toml
[launcher]
keep_open = true
```

## Workspace numbers

A workspace's number is its position. Moving a workspace with
`move_workspace_left` or `move_workspace_right`, or dragging its tab in the
dock, renumbers it. A workspace exists while it holds a pane or is on screen.
When a workspace that held a pane stops existing, because its last pane
closed or moved away and it is not on screen, it loses its name.

The numbers close up only when you change something: close a pane, move a
pane to another workspace, close a workspace or move one. Then every
workspace above an empty place moves down one: closing workspace 2 of 1, 2
and 3 leaves 1 and 2. A pane whose program exits on its own (a command
window with `close_on_exit`, a `tuios xpanes` run, an agent finishing)
leaves the numbers alone, so a script or agent that holds a workspace number
still names the same workspace. Its place stays empty until your next close
or move closes it up. Typing `exit` in a pane's shell is a close. An empty workspace you only looked at goes without
moving anything.

`Alt+N` with a number past the last workspace that holds a pane opens the
next one: with three workspaces, `Alt+5` opens workspace 4. When the
workspace on screen is empty, it is the new one, and `Alt+N` to an unused
number stays on it. A pane put directly on a higher number, with
`tuios new-window --workspace 7` or `send_to_workspace_7`, keeps that number
until the numbers below it close up.

### Starting at zero

Workspaces are numbered from 1 by default. To number them from 0, like tmux's
`base-index`, set:

```toml
[workspaces]
base_index = 0
```

The first workspace is then shown as 0 and the one after it as 1, up to 8.
Every workspace digit key moves with the number: `Alt+0` reaches the first
workspace, `Alt+1` the second, and the same shift applies to
`move_and_follow`, `send_to_workspace`, the workspace prefix chords and the
GUI keys. Edit the configuration file and reload it or restart tuios to change
this option; it is resolved together with the default keybindings when loaded.

This only changes the number a person sees and presses. tuios, its daemon and
tape scripts still number workspaces from 1 internally, so a command such as
`tuios new-window --workspace 7` keeps using that internal numbering.
A binding you set yourself is left alone; only the shipped workspace digit
bindings move.

## When a workspace becomes empty

When the last pane on the workspace on screen closes, tuios shows the
workspace you came from. This happens when the pane's program stops, when you
close the pane, when `tuios xpanes -ss` closes it, and with
`tuios close-workspace` or the `close_workspace` action.

tuios goes back in this order:

1. For a workspace that `tuios xpanes` opened, the workspace where you ran
   `tuios xpanes`.
2. The workspace you showed last that still has panes. After a chain of
   empty workspaces, tuios goes back past each one.
3. The workspace with the lowest number that has panes.

When no workspace has panes, tuios shows the splash screen. The workspace on
screen is the same for every client of the session, so every client goes
back. Moving a pane to another workspace does not close it, so tuios does not
go back.

To stay on the empty workspace, turn the setting off:

```toml
[workspaces]
return_when_empty = false
```

The daemon reads the setting when it starts and when the file changes.
`tuios set-config workspaces.return_when_empty false` changes it while tuios
runs.

## When you switch to an empty workspace

By default, a workspace with no panes shows the splash screen. To open a
pane there when you switch to it, as the new-window key does, turn on this
setting:

```toml
[workspaces]
new_window_when_empty = true
```

The new pane starts in the folder of the pane that had focus on the
workspace you came from. The new pane starts in the session's start folder
in these cases:

- You came from a workspace with no pane.
- You came from a scratch terminal.
- The pane you came from runs on another machine.

The start folder is the folder that `tuios new --cwd` gave.

A pane opens only when you switch: with a workspace key, a click on the
dock, go-to, the pane navigator or the command palette.
These switches do not open a pane:

- `move_and_follow` and other moves that take a pane with them.
- `tuios xpanes`, `tuios select-workspace`, `tuios run-command` and tape
  scripts. These bring their own panes or run from a script.
- The switch back from an empty workspace that `return_when_empty` makes.
- The start of tuios and an attach to a session. The workspace on screen
  stays as it is.

When two clients show the same session, the client that switches opens the
pane. The other client shows it. A workspace gets one pane, also when two
clients switch to it at the same time. When you switch away before the pane
opens, you stay where you went, and a switch back does not open a second
pane.

With `appearance.new_window_follow_ssh = true`, a pane that runs ssh gives a
new pane that runs the same ssh, as the new-window key does.

The daemon must be this version of tuios or newer. With an older daemon, a
switch opens no pane. Run `tuios kill-server` and start tuios again to load
the new daemon.

Each client reads the setting from its config file, and a change applies at
once. The settings page has it under Daemon, and
`tuios set-config workspaces.new_window_when_empty true` changes it while
tuios runs.

## Paste preview

An image paste (`Ctrl+B V`, the paste key when the clipboard holds only an
image, or the empty paste some terminals send for an image) writes the image
to a file and pastes the file's path. tuios then shows
the image in a small card at the pane's cursor, so you can see what the path
holds:

- The picture is drawn with kitty graphics when your terminal has them, and
  with block glyphs when it does not.
- The line under it names the size, the type and the file.
- The card takes no input. The next key or click takes it down and still goes
  where it was going, and so does a key sent with `tuios send-keys`. A panel
  opened over it, or the pane leaving the screen, takes it down too.
  Otherwise it goes after six seconds.

```toml
[appearance]
paste_preview = false   # paste the path alone; the default is true
```

## Paste buffers

tuios keeps your recent yanks as paste buffers. `Ctrl+B ]` pastes the newest,
and `Ctrl+B #` shows them all (see [KEYBINDINGS.md](https://tuios.dev/docs/keybindings/copy-mode#paste-buffers)).

```toml
[paste_buffers]
limit = 20     # how many unnamed buffers to keep. 0 keeps none.
max_kb = 16384 # most KiB all buffers hold together, at most 262144. 0 uses 16384.
```

The rules are the tmux rules. A yank makes a buffer that tuios names
`buffer0`, `buffer1` and so on. `limit` counts only these buffers, and past it
the oldest of them goes. A buffer that you name with `set-buffer -b` stays
until you delete it, or until the buffers pass `max_kb`. Past `max_kb` the
oldest unnamed buffer goes first, then the oldest named one. tuios does not
keep a yank that is larger than `max_kb` as a buffer, but the yank still goes
to the clipboard. With `limit = 0`, a yank goes only to the
clipboard.

The daemon keeps the buffers in memory, so every client and every session
shares them. They go when the daemon stops. The daemon reads the setting when
it starts and when the file changes. A smaller limit drops the oldest buffers
at once.

A buffer is yours or one pane's. Your yanks, and what you set from outside
every pane or from a pane that holds `admin`, are yours. What a pane without
`admin` sets is that pane's own. A buffer can hold a secret that you copied,
so a pane without `admin` sees and pastes only its own buffers: not yours,
and not another pane's, in its session or not. It cannot change or replace a
buffer that you set, and it cannot make a named buffer, so a name you keep a
command under stays yours. From inside a pane, reading its buffers needs the
`read` grant, changing them needs `write`, and pasting needs both. See
[What a pane may do](https://tuios.dev/docs/configuration/permissions#what-a-pane-may-do).

Large requests to the daemon, such as a big `set-buffer`, a `stash put` or an
image paste, take memory from a budget. You, outside every pane or in a pane
that holds `admin`, have a budget of your own. A pane without `admin` shares
another, so it cannot use up yours.

One thing a pane can still learn: the automatic buffer numbers (`buffer0`,
`buffer1`) come from one counter for everybody. A gap between two of a pane's
own buffer numbers tells it that other buffers were made in between, such as
your yanks. It tells the pane how often you copy, not what. tuios accepts this
as a low risk.

## Master-stack layout

These options shape the master-stack layout. Each workspace starts with them.
The layout keys change the workspace on screen, and the workspace keeps the
change. See [LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md#master-stack-layout).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.master_position`](https://tuios.dev/docs/option-reference#appearance.master_position), [`appearance.master_count`](https://tuios.dev/docs/option-reference#appearance.master_count), [`appearance.master_ratio`](https://tuios.dev/docs/option-reference#appearance.master_ratio), [`appearance.master_grid`](https://tuios.dev/docs/option-reference#appearance.master_grid).

This example puts an editor in the middle with terminals on both sides. It
keeps that layout at every pane count:

```toml
[startup]
layout = "master-stack"

[appearance]
master_position = "center"
master_ratio = 50
```

`[startup] layout` applies to a new session, and a new workspace takes the layout of the workspace you open it from.

With `center`, the grid is off, so `master_grid` has no effect. The first pane
of the workspace is the master. To make another pane the master, focus it and
press `Ctrl+B L Enter`.

## Start session and start pane

Two `[startup]` options choose where a plain `tuios` opens. Both are empty by
default.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`startup.session`](https://tuios.dev/docs/option-reference#startup.session), [`startup.window`](https://tuios.dev/docs/option-reference#startup.window).

```toml
[startup]
session = "home"
window = "start"
```

`tuios attach`, `tuios new` and every other command use the session you give
them, and ignore these options. [`startup.session`](https://tuios.dev/docs/option-reference#startup.session) uses the daemon even when
[`startup.daemon`](https://tuios.dev/docs/option-reference#startup.daemon) is `false`. `--standalone` and `TUIOS_NO_DAEMON=1` still run a
local session. Both options are on the settings page, in the Startup section.
See [SESSIONS.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/SESSIONS.md#start-session-and-start-pane).

## Scrolling layout

These options shape the scrolling layout. See
[LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md#scrolling-layout).

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.scroll_column_width`](https://tuios.dev/docs/option-reference#appearance.scroll_column_width), [`appearance.scroll_column_max`](https://tuios.dev/docs/option-reference#appearance.scroll_column_max), [`appearance.scroll_column_presets`](https://tuios.dev/docs/option-reference#appearance.scroll_column_presets).

`scroll_cycle_width` sets the focused column to the next width in the list
that is larger than the current width. After the largest width, it goes back
to the smallest. tuios sorts the list. It skips a width that is larger than
`scroll_column_max`. It ignores a value that is not from 1 to 100 and shows a
config warning. This example cycles a column through a half, two thirds and the
full screen:

```toml
[appearance]
scroll_column_width = 50
scroll_column_max = 100
scroll_column_presets = [50, 67, 100]
```

A change to the list applies when tuios reloads the config. The settings page
does not show this option. Edit it in `config.toml`.

## Drop preview

While you drag a tiled pane in BSP, tuios shows where the pane would land if you let go. See [LAYOUT\_MODES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/LAYOUT_MODES.md). The preview is a frame in the accent colour, drawn with the same border characters as the panes. With `fill`, the area inside the frame gets one tint, and the text under it fades into that tint. On a 16-colour terminal the frame is reverse video and the area inside stays as it is. Two options shape that preview:

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.drop_preview`](https://tuios.dev/docs/option-reference#appearance.drop_preview), [`appearance.drop_preview_delay`](https://tuios.dev/docs/option-reference#appearance.drop_preview_delay).

```toml
[appearance]
drop_preview = "fill"
drop_preview_delay = "250ms"
```

Neither option changes the drop: with `off`, releasing on an edge still splits that pane, and releasing in the middle still swaps. Both are on the settings page, in the Appearance section, and `tuios set-config appearance.drop_preview off` applies at once. A value that is not one of the above reads as the default, with a warning when the config loads, and `tuios set-config` refuses it.

## Rounded dock pills

[`appearance.dock_pill_caps`](https://tuios.dev/docs/option-reference#appearance.dock_pill_caps) puts rounded caps on every pill in the dock: the
mode chip, the workspace tabs and the minimized windows. It is `true` by
default. Set it to `false` for flat pills:

```toml
[appearance]
dock_pill_caps = false
```

Under ASCII glyphs the workspace tabs have no caps. The option also controls
the ends that `[dock.tabs] caps` puts on flat tabs. The rail's pills do not
change with this option.

## Mode pill icons

The mode pill at the start of the dock shows an icon for the mode. Three
options set the icons:

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.dock_mode_icon_window`](https://tuios.dev/docs/option-reference#appearance.dock_mode_icon_window), [`appearance.dock_mode_icon_terminal`](https://tuios.dev/docs/option-reference#appearance.dock_mode_icon_terminal), [`appearance.dock_mode_icon_tiling`](https://tuios.dev/docs/option-reference#appearance.dock_mode_icon_tiling).

```toml
[appearance]
dock_mode_icon_window = "WM"
dock_mode_icon_terminal = ">_"
dock_mode_icon_tiling = ""
```

- When an option is not set, the pill shows the icon of the glyph set. With
  `use_ascii_only`, that icon is `W`, `T` or `#`.
- An empty string shows no icon. If the mode has no other text, the dock shows
  no pill in that mode.
- An icon can be at most 8 cells wide. A wide character, such as `終`, counts
  as two cells. The dock does not accept control characters. For an icon that
  it does not accept, the dock shows the default icon and the config check
  shows a warning.
- The pill adds one space on each side of the icon. You do not need to add
  spaces.
- While tiling is on, the pill also shows the next split direction, `V` or
  `H`. Set `appearance.dock_mode_split_letter = false` to show the tiling icon
  alone. With the default icons, the pill then has the same width as the pill
  of the leader key, so the workspace tabs do not move when you press the
  leader key.
- [`appearance.dock_mode_pill`](https://tuios.dev/docs/option-reference#appearance.dock_mode_pill) sets what the pill shows while tiling is on.
  `tiling` (the default) shows the tiling icon in terminal mode and in window
  mode. `input` shows the terminal icon or the window icon, and the split
  letter after it shows that tiling is on.

```toml
[appearance]
dock_mode_pill = "input"
```

To remove the whole mode pill, remove `"mode"` from the `left` list in the
`[dock]` table. See [The dock's components](https://tuios.dev/docs/configuration/dock-and-rail#the-docks-components).

You can also set the icons on the settings page, in the Dock section, or with
`tuios set-config dock_mode_icon_window WM`. The word `default` puts an icon
back to the icon of the glyph set, in the settings, with set-config and in
`config.toml`. The change applies at once.

## Prefix indicator

When you press the leader key, the mode pill shows a keyboard icon on the
warning colour until you press the next key. With `use_ascii_only`, the icon is
`P`. [`appearance.dock_prefix_indicator`](https://tuios.dev/docs/option-reference#appearance.dock_prefix_indicator) sets where the armed leader shows:

| Value   | What it does                                                                             |
| ------- | ---------------------------------------------------------------------------------------- |
| `pill`  | The mode pill shows the armed leader. This is the default                                |
| `badge` | A `PREFIX` badge shows in the corner across from the dock. The mode pill does not change |

```toml
[appearance]
dock_prefix_indicator = "badge"
```

The badge shows for each value when the dock is hidden or has no mode pill.
The option is on the settings page, in the Dock section.

## Workspace label cap

[`appearance.dock_workspace_label_max`](https://tuios.dev/docs/option-reference#appearance.dock_workspace_label_max) caps a workspace tab's label in cells,
so one long name cannot push the other pills off the bar. The cap is `12` by
default and counts the tab format's own characters, so `"<{name}>"` loses two
of them to the brackets. Set it to `0` to draw the whole name and let the
strip scroll instead:

```toml
[appearance]
dock_workspace_label_max = 0
```

A dock too narrow for even one pill keeps the current workspace's tab, cut to
whatever room is left, so the workspaces always have something to click. You
can also set it on the settings page, in the Appearance section. The change
applies at once.

## Workspace name on hover

[`appearance.dock_workspace_tooltip`](https://tuios.dev/docs/option-reference#appearance.dock_workspace_tooltip) shows the workspace name above a pill
when you hover it. The name shows when the pill cuts the name short. It also
shows when [`appearance.dock_workspace_tab_format`](https://tuios.dev/docs/option-reference#appearance.dock_workspace_tab_format) has no `{name}`, for
example with number-only tabs. A workspace with no name shows its number,
but only when the tab format has no `{index}`. The option is on by default.

```toml
[appearance]
dock_workspace_tab_format = "{index}"
dock_workspace_tooltip = true
```

## Compact dock

The dock has two rows by default: a rule and the row of pills.
[`appearance.dock_compact`](https://tuios.dev/docs/option-reference#appearance.dock_compact) removes the rule, so the dock has one row. The panes
get that row. The default is `false`.

```toml
[appearance]
dock_compact = true
```

The option works with the dock at the top and at the bottom. It has no effect
when `dockbar_position` is `hidden`. You can also set it on the settings page,
in the Dock section, or with `tuios set-config dock_compact true`. The change
applies at once.

The rule shows how long a dock message stays. A compact dock does not show
this.

When clients with different docks share a session, the panes keep the
largest dock height. A client with a compact dock shows a blank row in that
case.

## Window titles

A pane's title sits on its border. Two options set its shape and its place:

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.window_title_style`](https://tuios.dev/docs/option-reference#appearance.window_title_style), [`appearance.window_title_align`](https://tuios.dev/docs/option-reference#appearance.window_title_align).

```toml
[appearance]
window_title_style = "plain"
window_title_align = "center"
```

[`appearance.window_title_position`](https://tuios.dev/docs/option-reference#appearance.window_title_position) sets the row: `top`, `bottom` or
`hidden`. The caps of `pill` come from the glyph set. Both options are on the
settings page, in the Appearance section, and `tuios set-config` applies them
at once.

### The title of a screenshot

A screenshot with a frame draws a title bar. [`screenshot.title_format`](https://tuios.dev/docs/option-reference#screenshot.title_format) sets its
text, with three tokens:

| Token     | Becomes                                                                                                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{title}` | The window's title as its title bar shows it: the pane's name through [`appearance.window_title_format`](https://tuios.dev/docs/option-reference#appearance.window_title_format) |
| `{index}` | The window's place, from 1                                                                                                                                                       |
| `{cwd}`   | The window's folder                                                                                                                                                              |

```toml
[screenshot]
title_format = "{title} in {cwd}"
```

The default is `{title}`, the same title the window has on screen. An empty
format draws no title. In a capture of the whole screen or of a region,
`{title}` is "screen" or "region", and `{index}` and `{cwd}` are the focused
window's. An unknown token, such as `{name}`, is shown as written, and tuios warns about
it when it loads the file.

## Host terminal title

[`appearance.host_title`](https://tuios.dev/docs/option-reference#appearance.host_title) sets the title of the terminal tuios runs in, such as
Ghostty's title bar, from the focused pane. It follows the focus, the
workspace and the session, and the focused pane's own title changes. It is
tmux's `set-titles`. Empty, the default, sets no title. Emptied while a client
is attached, it clears the title it set, as a client does when it detaches.

| Placeholder   | What it holds                                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `{title}`     | the focused pane's name, as its title on the border shows it                                                                                    |
| `{index}`     | the pane's place in its workspace, from 1                                                                                                       |
| `{cwd}`       | the pane's working directory                                                                                                                    |
| `{session}`   | the session's name as the rail shows it, its display name if it has one, or `tuios` without a daemon                                            |
| `{workspace}` | the workspace's name, else the name its active pane gave with OSC 1, else its number. With a scratch group open, the workspace it is shown over |

```toml
[appearance]
host_title = "{title} · {session}"
```

With no focused pane on the workspace in view, the title is the session's
name. So it is when the template uses `{title}` and the pane has no name, as a
fresh shell has none, and when the template comes out empty. A title a tool
set with herdr's `terminal title set` wins while it is set. Each client sets
the title of its own terminal. The option is on the settings page, in the
Appearance section, and `tuios set-config` applies it at once.

## Focused border colour

The focused pane's border shows the mode. By default it is the theme's cyan
in window mode and its green in terminal mode. Three keys set it.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.border_focused_color`](https://tuios.dev/docs/option-reference#appearance.border_focused_color), [`appearance.border_focused_color_window`](https://tuios.dev/docs/option-reference#appearance.border_focused_color_window), [`appearance.border_focused_color_terminal`](https://tuios.dev/docs/option-reference#appearance.border_focused_color_terminal).

```toml
[appearance]
border_focused_color_window = "accent"
border_focused_color_terminal = "#ff9e64"
```

- A key for one mode wins over `border_focused_color` in that mode.
- An empty key uses the next key. After the three keys, the theme sets the colour.
- `border_focused_color` also replaces the colours for copy mode and for an
  agent that waits. The keys for one mode do not.
- On many themes the cyan and the green have the same lightness. The default
  terminal mode colour then moves darker, or lighter when darker is too faint.
  You can then see the mode without the hue.
- The default unfocused border is darker than both focused borders on a dark
  background, and lighter on a light one. You can see focus without the hue.
- Each default focused border has at least twice the contrast of the unfocused
  border against the background.
- With no theme, the default unfocused border is a grey near your terminal
  background. The focused borders use a saturated cyan and green.
- With [`appearance.session_border`](https://tuios.dev/docs/option-reference#appearance.session_border) on, the focused border in window mode uses
  the session colour. In terminal mode it uses the terminal mode colour.
  Terminal mode stands further from the background and is at least as
  saturated, so it is the more visible of the two. The session colour moves
  toward the background to make the step.
- At 16 colours the default borders use bright cyan and bright green, the
  slots of your terminal's palette.
- The settings page has a row for each key, in the Appearance section.

## Focused border gradient

[`appearance.border_focused_gradient`](https://tuios.dev/docs/option-reference#appearance.border_focused_gradient) draws the focused pane's border in two
or more colours that blend from one to the next.
[`appearance.border_gradient_angle`](https://tuios.dev/docs/option-reference#appearance.border_gradient_angle) sets the direction in degrees.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.border_focused_gradient`](https://tuios.dev/docs/option-reference#appearance.border_focused_gradient), [`appearance.border_gradient_angle`](https://tuios.dev/docs/option-reference#appearance.border_gradient_angle).

```toml
[appearance]
border_focused_gradient = "#33ccff #00ff99"
border_gradient_angle = 45
```

- The gradient is static. It changes only when the pane moves, resizes or
  takes focus.
- The border steps through 8 colours, so the cells of one step share one
  colour code. This keeps the bytes sent to the terminal small.
- The window buttons and the title keep their own colours.
- A focused border in a colour for its state (copy mode or an agent that
  waits, see [THEMES.md](https://github.com/Gaurav-Gosain/tuios/blob/f32fbfd7faca14e5260a1d711262cb81c49f68a6/docs/THEMES.md#roles-for-one-piece-of-chrome)) is drawn
  in that colour, not the gradient.
- At 16 colours the border uses one colour, as before.
- A colour value can name a slot or a role, such as `"accent accent_bright"`,
  so the gradient follows the theme.

## Dialog and panel borders

The small dialogs, such as rename, confirm and new space, draw their frame in the pane border style, [`appearance.border_style`](https://tuios.dev/docs/option-reference#appearance.border_style). The larger panels, such as the command palette, the switchers, the Agents view and the settings page, have no frame unless [`appearance.frame_panels`](https://tuios.dev/docs/option-reference#appearance.frame_panels) is on. Then they take the same frame.

The scrollback browser and its help modal draw their frame in the border style too.

With [`appearance.pane_overlays`](https://tuios.dev/docs/option-reference#appearance.pane_overlays) on, a dialog or a panel looks like a pane window:

- Every panel is framed, as if `frame_panels` were on.
- The frame takes the focused pane's border colour, because an open dialog or panel is the focused thing. That is [`appearance.border_focused_color`](https://tuios.dev/docs/option-reference#appearance.border_focused_color) when it is set. Otherwise it is the theme's colour for the current mode (copy mode or a waiting agent) or the session's tint.
- The frame and everything in it sit on the background of an empty pane cell. That is [`appearance.pane_background`](https://tuios.dev/docs/option-reference#appearance.pane_background) when it is set, else the terminal's own. The title and hints in the frame line share that background, as they do in a pane.
- The selected row, the row under the pointer and input fields are steps of that background. On a navy pane, a selected row is a darker navy.
- Pills keep their own colours.

The scrollback browser and the copy-mode search bar follow the option too. The browser's frame takes the focused pane's border colour, and its selected row and key pills are steps of the pane's background. The search bar sits on the pane's background.

The option is off by default. Then a dialog or a panel keeps its own shaded background, and its frame keeps its quiet ink. Some cases keep the shade even with the option on:

- Under `hidden`, no frame is drawn, so the shade is a dialog's only edge.
- At 16 colours every background is the terminal's own, so the option changes only the frame's colour.
- With no theme, and a terminal that never reports its background, there is no colour to fill the overlay with or to step its rows from.

[`appearance.overlay_border_color`](https://tuios.dev/docs/option-reference#appearance.overlay_border_color) sets a colour for every dialog and panel frame, and for the scrollback browser's, with or without `pane_overlays`.

These options are in the [option reference](https://tuios.dev/docs/option-reference): [`appearance.border_style`](https://tuios.dev/docs/option-reference#appearance.border_style), [`appearance.frame_panels`](https://tuios.dev/docs/option-reference#appearance.frame_panels), [`appearance.pane_overlays`](https://tuios.dev/docs/option-reference#appearance.pane_overlays), [`appearance.overlay_border_color`](https://tuios.dev/docs/option-reference#appearance.overlay_border_color).

```toml
[appearance]
border_style = "double"
frame_panels = true
pane_overlays = true
overlay_border_color = "accent"
```

How each border style draws a dialog or a framed panel:

- `rounded`, `normal`, `thick`, `double` and `ascii` draw that style's corners and lines.
- `hidden` draws no frame. The dialog keeps its size, and its title and key hints stay where the frame would carry them. A frame that is the only edge of what it holds is drawn as in `rounded` instead: the frame of a panel at 16 colours, the frames round the regions inside a panel, such as an explorer's list and preview, and the frames of the scrollback browser and its help modal, which have no background of their own.
- `block`, `outer-half-block` and `inner-half-block` draw the `rounded` frame. A solid frame is too heavy round a dialog of three rows.
- `glyphs` draws the border of the active glyph set. A part of the border the set does not name is drawn as in `rounded`.
- With `--ascii-only`, every frame is drawn with `+`, `-` and `|`.
- At 16 colours a panel always has a frame, because its background is the terminal's own. The frame takes the border style, except `hidden` as above.

Both options are on the settings page, in the Appearance section. A change applies at once.

## Borderless zoom

`z` zooms the focused pane. By default the zoomed pane keeps its border, and
[`appearance.zoom_size`](https://tuios.dev/docs/option-reference#appearance.zoom_size) sets how much of the screen it takes.
[`appearance.zoom_borderless`](https://tuios.dev/docs/option-reference#appearance.zoom_borderless) shows the zoomed pane on the whole pane region
with no border and no title bar. The program in the pane gets the full size.
The dock and the rail stay on the screen. The default is `false`.

```toml
[appearance]
zoom_borderless = true
```

With this option on, `zoom_size` and `zoom_max_width` have no effect. The
option also applies to a floating pane. When you zoom out, the pane gets its
border back. You can also set it on the settings page, in the Advanced section,
or with `tuios set-config appearance.zoom_borderless true`. The change applies
at once.
