path: root/docs/config.md

# Configuration

## The startup file

Native builds read one command file, `init`, from the per-user `pardes`
configuration directory:

- Unix: `$XDG_CONFIG_HOME/pardes/init` (only an absolute `XDG_CONFIG_HOME`
  counts), else `~/.config/pardes/init`.
- macOS: `$XDG_CONFIG_HOME/pardes/init` when set, else
  `~/Library/Application Support/pardes/init`.
- Windows: `%LOCALAPPDATA%\pardes\init`, else
  `%USERPROFILE%\AppData\Local\pardes\init`.

The browser build has none. A file over 1 MiB or unreadable counts as absent.

Each line is one builtin, spelled as it would be executed in pardes:

```text
Theme orchard
Font DejaVuSansMono-Regular
TaglineSize 82
Shell zsh
Wrap
```

A builtin that takes no argument matches only as the whole line (`Kill` runs,
`Kill something` does not); one that takes an argument takes the rest of the
line. Blank, unknown, malformed or failing lines are ignored silently and do
not stop later ones. Text that is no builtin is not run as a shell command
(`Exec ...` still is). Key bindings are compile-time choices in
`src/config.zig`; `init` does not remap them.

`Config` (`SPC f c`) opens `init` itself in a pane, or goes to its pane when
it is open. With no file there yet, the pane is named for it, empty, and
Save writes it, making its directory first. `DumpConfig` opens a
`+DumpConfig` pane with every live setting, each line the word that sets
it and its value (`Shell /bin/bash`, `PanelSlide off`, `LocationsConfig …`)
and `unsupported` for one the frontend cannot show. After a blank line
come what is in effect but set by no word, such as the last shell spawned
and the font in use, and the startup path (a right click opens it), each a
`#` line. A line starting with `#` is a comment wherever a line runs (the
init file, a ctl, an exec), so the report can be written back as is. The
root `ctl` file reads the settings back in the words a write takes
([fs.md](fs.md#the-root-ctl)).

## Settings

A setting that chooses among words (`on`/`off` switches, `Placement`,
`BootShell`, `Crt`, `Bloom`, `Vignette`, `Grain`, `Lift`, `Motion`,
`ShaderAnimation`) steps to its next value when given bare, as its word
clicked in a tag does; a value it does not take is refused, naming those it
does. `/commands` lists every builtin and its values.

| setting | default | |
|---|---|---|
| `Theme <name>` | `orchard` | names as `Themes` (`SPC t t`) lists them ([themes.md](themes.md)); `NextColor` walks the ring |
| `ThemeFile <path>` | | a `.zon` theme, relative to the config directory; reloads live when saved |
| `FocusTint` | on | tint the focused pane's and column's tags |
| `SyntaxBold` | off | bold syntax keywords |
| `Verbose` | on | a builtin announces its name on the message row |
| `MessageAnimation` | on | messages ease in and dissolve |
| `MessageLinger`, `MessageFall`, `MessageDissolve` | 800, 180, 150 | milliseconds, at most 60000 |
| `Placement acme\|pardes` | `acme` | where new panes go ([tags.md](tags.md#where-new-panes-go)) |
| `BootShell keep\|replace` | `keep` | `replace` closes the untouched lone shell a dragged document lands beside |
| `LookWord search\|list` | `search` | a looked-at word selects its next place, or lists all in `+Search` |
| `Shell <name or path>` | `$SHELL`, else the login shell, else `/bin/sh` | the shell the next terminal runs; a bare name is looked for in the usual bin directories, not `$PATH`; bare `Shell` returns to the default |
| `DumpDir <dir>` | `$XDG_DATA_HOME/pardes`, else `~/.local/share/pardes` | where `Dump` writes; `~/` is home; bare returns to the default |
| `TreeContext` | off | sticky declaration headers in a source pane (per pane, dumped) |
| `TreeContextTagStyle` | on | draw those headers in the tagline style |
| `LocationsConfig ...` | | Search, Grep and LSP result layout (below) |
| `Wrap`, `Colors`, `Tagbottom`, `Debug` | | toggles |
| `Font <name>[:<size>]`, `Fonts` | | SDL and macOS only; size 8-72 (pixels in SDL, points on macOS) |
| `TaglineSize <1-100>` | 82 | tagline face, percent; SDL and macOS |
| `WindowOpacity <0-100>` | 100 | SDL only: everything but text and the cursor |
| `Ligatures` | on | SDL only; macOS draws CoreText's own |
| `Pet cat\|frog\|off` | off | SDL only: a sprite in the workspace tag's blank space |

`Tty9p` (`SPC n 9`) is described in [v9fs.md](v9fs.md); the
`PARDES_V9FS_HELPER` variable points development builds at the helper.

### Terminals

Ctrl-B switches a terminal between raw input and editor mode. Plain Escape
at a detected shell prompt hops back to the previous pane; other keys,
Ctrl-O, Ctrl-W and modified Escape included, go to the program. `Mode` in the
tag returns to editor mode in place. Ctrl-V types the yank register and
Ctrl-Shift-V the desktop clipboard, through bracketed paste when the program
asked for it; neither reaches the program as a keystroke.

`Filter` in a terminal's tag maps its ANSI colours through the theme,
keeping each foreground at least `tty_filter_min_contrast` (WCAG 1.5, in
`src/config.zig`) against its background.

### Location results

`LocationsConfig` with no argument prints the current settings as a line
that can be run again; with fields it changes only those:

```text
LocationsConfig context:5 tscontext:on tslocations:off layout:stacked
```

- `context` (0): source lines shown above and below each match.
- `tscontext` (off): include the enclosing tree-sitter declaration headers.
- `tslocations` (on): show a location on each declaration header.
- `layout` (`stacked`): the location on its own line; `inline` puts it
  beside the source, padded in groups of eight matches.

An invalid field rejects the whole line; a repeated field's last value wins.
The settings survive Dump and Restore. Source analysis is cached for 64
files and 64 MiB.

### Effects

Panel transitions, one at a time; running the active one again turns it
off: `PanelSlide`, `PanelZoom`, `PanelDissolve`, `PanelAscii`,
`PanelVertical`, `PanelEdges`, `PanelFall`, `PanelWave`, `PanelCurtain`,
`PanelScramble`, `PanelType`. All start off; the web shell has none.

Scene passes (SDL GUI, and a GUI attached to a detached session), each at a
level 0-3 (`on` is 2), all off by default: `Crt`, `Bloom`, `Vignette`,
`Grain`. `Shader <file.glsl>` adds a Shadertoy file written for ghostty to
the chain (`Shader off` removes it; it recompiles when saved);
`ShaderAnimation off|on|always` says when the chain animates by itself.

The focused pane can stand off the page: `Lift shadow|rim|auto|off`,
`InactiveDim <percent>`, `Motion off|crisp|smooth|bouncy|playful`
(default `smooth`), `SelectionGlow`, `HoverGlow`, `Occlusion`, `Parallax`,
`JumpTrail`, `ChipShadow`, `ThumbFlash`, `CursorBlink`, `GripWidth <50-300>`.
Most are GUI-only; `InactiveDim` works everywhere, and `JumpTrail`,
`ChipShadow` and `ThumbFlash` are the terminal's. No effect may lower the
contrast of text, the selection or a focus indicator
([effects.md](effects.md)).

`EffectCode <effect>` lists that effect's sources under `/virtual` when the
build embeds them (`-Dembed-sources=true`). `zig build shaders` refreshes
the committed SPIR-V with its GLSL.

### Look preview

Resting the pointer on text for about 32 ms (`look_preview_delay_frames`, 2
frames) tints what a right click would look at, with no other effect. Set
`look_preview_delay_frames` to `null` in `src/config.zig` to turn it off.

## Themes from files

`ThemeFile themes/mine.zon` loads a complete theme; a malformed save keeps
the last good one, and `Theme <name>` stops the watch. `DumpThemes` writes
every compiled theme to `<config dir>/themes/builtin/<name>.zon`: copy one,
change its `.name`, and edit. The format is `pardes.Theme` as
`std.zon.stringify` writes it; [themes.md](themes.md) describes each role.

## Dumps

`Dump` writes `pardes-<date>-<time>.zon` (UTC) in `DumpDir`, creating the
last directory if it is missing (a missing parent fails `no such
directory`); `$PARDES_DUMP` overrides the file. `Restore <path>` looks for a
relative path in `DumpDir`, then in the directory pardes started in; bare
`Restore` takes the last dump this session wrote. `pardes -l <dump.zon>`
starts from one.

A dump keeps panes, columns and their tags, each text pane's selection, the
theme, and the settings that differ from a fresh session's; the font stays
the frontend's. A terminal comes back with its last MiB of output as
history, a `── restored history ──` line, and a new shell in its old
directory; a command pane comes back finished (`exit ?` if it was running).
Undo history and REPL bindings are not kept. A dump holds at most 6 columns.

## Crash records

A panic appends two lines to `crashes` beside `init` (build, time, platform,
pid; then the panic message) before printing to stderr. There is no stack
trace in it: collecting one from a panic handler can hang the process. The
trace stays on stderr.

## Build options

`zig build --help` lists the options for the selected platform.

| option | values | default |
|---|---|---|
| `-Dplatform` | `tty`, `gui`, `web`, `macos`, `esp32p4` | absent: the tty and SDL shells together, installed into `~/.local` |
| `-Dstatic` | bool | `false` |
| `-Dquic` | bool; 9P over QUIC with system OpenSSL 3.6+ | `false` |
| `-Dmupdf` | bool | on natively, off for web and esp32p4 |
| `-Djpx` | bool; JPEG 2000, and with it scanned PDFs | `true` |
| `-Dtree-sitter` | `disabled`, `zig`, `minimal`, `full` | `full` natively, `zig` for web, `disabled` for esp32p4 |
| `-Dembed-sources` | bool; serve the sources under `/src` | `false` |
| `-Dstamp-commit` | bool; the git commit in `--version` and crash records | on for release builds and the `~/.local` install |
| `-Dtheme-animation` | bool | on except for esp32p4 |
| `-Dworkspace-tag` | bool; draw the workspace tag row | on except for macOS, whose menu bar carries it |
| `-Dprebuilt-shaders` | bool; embed the committed SPIR-V | on for a bare `zig build`, off with `-Dplatform` |
| `-Dtracy` | path to a Tracy checkout | off |
| `-Dmacos-identity` | codesigning identity for `pardes.app` | `-` (ad-hoc) |
| `-Ddump` | a `dump.zon` to embed in the web shell | none |
| `-Dtest-filter` | run only tests whose name contains it | none |
| `-Dtest-rebuild` | bool; fresh Zig test compilation | `false` |
| `-Dhelix-harness` | reference executable for live differential tests | `HX_HARNESS`, else `hx-harness` on PATH |
| `-Desp32p4-cols`, `-Desp32p4-rows` | the board's grid | 56, 14 |

The version comes from `build.zig.zon`'s `.version`.