# Startup configuration Native pardes builds use a per-user `pardes` configuration directory. Its main command file is named `init`: - Unix: `$XDG_CONFIG_HOME/pardes/init`, falling back to `~/.config/pardes/init`. - macOS: `$XDG_CONFIG_HOME/pardes/init` when that variable is set, otherwise `~/Library/Application Support/pardes/init`. - Windows: `%LOCALAPPDATA%\pardes\init`, with `%USERPROFILE%\AppData\Local\pardes\init` as the fallback. On the two unixes `XDG_CONFIG_HOME` counts only when it is ABSOLUTE, as the XDG base-directory specification requires; an empty or relative value falls back to the home-directory form (`user_config.xdgBase`, and the test beside it). Windows never consults it. An `init` that does not fit the `max_bytes` read limit — 1 MiB, `src/user_config.zig` — or that cannot be read at all is treated as no file: `load` takes the `readFileAlloc` error and keeps going. The path still resolves, because "nothing is there yet" is the answer `Config` exists to give. There is one case with no path at all: a native launch with no `HOME` set (or, on Windows, neither `%LOCALAPPDATA%` nor `%USERPROFILE%`), which `Config` reports as `no per-user config path`. `Config` (`SPC f c`, or the word executed anywhere) opens one refreshable `+Config` pane. It reports the startup path and every live config-like value: theme, colors, wrapping, tag position, debug mode, the requested shell and the executable actually resolved at the last spawn, requested/effective GUI font and size, tagline scale, panel transition, scene effects, hover delay, platform, native-image support, and (on SDL) whether the executable uses live-built shaders or the paired prebuilt shader snapshot. Platform-dependent rows say `unsupported` instead of looking like an off or empty supported setting. The four fields of `runtime_config.Capabilities` gate them and are stated once as plain data in `builtins.capabilities`: `font_picker` is the SDL GUI and native macOS only, `scene_shaders` the same two, `panel_transitions` every hosted shell, and `tagline_font_size` everything but the TTY and the board. So the TTY reports Font, TaglineSize and the scene shaders as unsupported; the browser reports Font, panel transitions and the scene shaders as unsupported, and its TaglineSize row reads `82% (build-time only)` — tagline font size is its own capability precisely because GUI font SELECTION is native-only while the browser still applies the compiled percentage to its DOM glyphs. The startup path is printed whether or not a file exists — that is usually when it is most useful — and is ordinary selectable text, so a right click on it opens the file. Shell follows the same requested/effective/pending model as Font. `Compiled default shell` is the command built into the binary; `Shell effective (last spawn)` is the executable the native host really chose after installation lookup and fallback. A changed request remains pending until a terminal is spawned, because the core does not resolve native executables. The mutable global values live together in the plain `runtime_config.State` record. One plain capability record gates the setting registry, leader table, `EffectCode`, and report; the compile-time setting table generates both setter builtins and their `Config` rows. Exhaustive checks require every table-backed toggle, transition, and scene-effect switch to occur exactly once, so those generated setting builtins cannot quietly lose their query row or leave a renderer switch unnamed. Manual pane-local actions remain with their payload (for example an image tag reports its renderer choices); they are not global configuration. The browser build has no local user-config path and does not load this file. (Nor does it have `Font`, the effect builtins or `EffectCode`, a language backend, or ptys of its own — see `docs/web.md`.) The format is one existing builtin command per line, using the same spelling and argument parsing as commands executed inside pardes: ```text Theme acme Font DejaVuSansMono-Regular TaglineSize 82 Shell zsh Wrap ``` A line matches a builtin whose name takes NO argument only as that whole word: `Kill` runs, `Kill something` does not. A builtin that takes one (`takes_arg` in `src/builtins.zig`, or a `settings` row whose action is `shell`, `theme`, `font` or `tagline_size` in `src/runtime_config.zig`) takes everything after the name as the argument. On a native build that is `Theme`, `ThemeFile`, `Font`, `TaglineSize`, `Shell`, `Save`, `Restore`, `Attach`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`, `Exec`, `Msg` and `EffectCode`. (`Peek`, `Poke`, `Hexdump` and `Gpio` take one too, but they exist only where `board_memory.enabled` holds, and that build has no config file.) `Theme ` wants one of the 228 names in the ring. Do not derive the spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the exact `Theme ` line that selects it. `slug` in `tools/gen_themes.zig` lowercases, folds punctuation runs to a single `_` and then TRIMS leading and trailing ones (`penumbra+.toml` is `penumbra`, not `penumbra_`), and every variant read out of a zed `.json` gets `_zed` on the end so it cannot collide with a helix theme of the same name — zed's "Ayu Mirage" is `ayu_mirage_zed` and `ayu_mirage` is helix's `ayu_mirage.toml`. The suffix goes on all of them rather than only the eight that clash today, so a name cannot move when either project gains or loses a file. A name that is not in the ring is ignored. ## Runtime theme files `ThemeFile ` loads one complete theme from a `.zon` file. An absolute path is used as written; a relative path is resolved from the `pardes` configuration directory, not from the process working directory. A typical layout is: ```text ~/.config/pardes/ ├── init └── themes/ └── mine.zon ``` and the corresponding init line is: ```text ThemeFile themes/mine.zon ``` After a successful load, hosts with document live reload watch the path with the same parent-directory mechanism, so in-place writes and editor-style rename-over saves reload the theme live. A malformed or incomplete save does not replace the last valid theme; fixing and saving the file applies the next valid snapshot. Selecting a compiled theme with `Theme ` or `NextColor` stops the custom-file watch. Execute `DumpThemes` to write every theme compiled into the executable to: ```text /themes/builtin/.zon ``` The command replaces those generated reference files but leaves unrelated files alone. Copy one into `themes/`, rename it, change its `.name`, and use it as the starting point for a custom theme. The dumped file is also the complete format, and it is `pardes.Theme` serialised by `std.zon.stringify`: the theme name, thirteen required RGB roles (`sel_bg`, `sel_fg`, `tag_bg`, `tag_fg`, `box`, `box_dim`, `kw`, `str`, `num`, `comment`, `lineno`, `scroll_track`, `scroll_thumb`), nullable `bg`/`fg`, and either a 16-color RGB `palette` or `null`. RGB values are three-byte arrays, and hex literals are accepted. There is no inheritance or partial override layer. `Shell ` sets the binary that the NEXT terminal pane execs; panes already open keep the shell they are running. A bare name is resolved against the handful of directories a shell actually lives in, not `$PATH`. `Font` and `FontSel` exist ONLY in the SDL GUI and native macOS builds — a terminal's font belongs to its emulator and a browser's to the page — so a `Font` line is one of the silently-ignored ones everywhere else. Both builds resolve the name by walking the font directories on every lookup, so a face installed a moment ago is findable. `Font` is asynchronous at the renderer boundary. `Config` therefore keeps requested name/path, pending state, and the effective face/point-or-pixel size as separate facts; a failed request never gets reported as the face on screen. Taglines use a distinct face size in both native GUI renderers. Execute `TaglineSize ` to change it live, for example `TaglineSize 70`; the accepted range is 1 through 100 and the default comes from `gui_tagline_font_percent` in `src/config.zig` (82). The native renderer remeasures both the glyph and its visible tag band while retaining body-grid pane geometry. The SDL GUI uses the smaller face's measured monospace advance as a real per-pane tagline grid, including pointer hit testing; it does not pad each smaller glyph back out to a body-width cell. The 100% ceiling is deliberate: a tagline remains exactly one logical grid row, so a larger face or band would overlap its pane body or a neighbour instead of leaving the body grid stable. `Config` reports the active percentage. The browser applies the same compiled percentage to its DOM glyphs but has no runtime setter. The SDL GUI joins the reduced-height global and pane tagline bands with `gui_topbar_pane_border_px` physical pixels. Set it to zero for a direct join. `gui_topbar_pane_border_rgb` can pin an RGB color; its default `null` follows the active theme's scrollbar-track color. With `Tagbottom` enabled, a tagline on the final grid row is bottom-aligned so the same unused half-band does not show beneath it. What happens to a codepoint the chosen face has no glyph for differs by shell. The SDL GUI falls back through a chain it builds itself: embedded Adwaita Mono, then installed `NotoSansMono-Regular`, `DejaVuSansMono`, `SymbolsNerdFont-Regular`, `NotoSansSymbols2-Regular`, `NotoSansSymbols-Regular`, and `DejaVuSans`, in that order, missing entries skipped; the rasterized glyphs are retained in its GPU atlas. The macOS shell has none of that and needs none. It embeds no font. Its default face is `NSFont.monospacedSystemFont`, resolved through the descriptor rather than by name, and `Menlo` only if that face turns out not to be fixed-pitch — a proportional face in a fixed grid is a broken screen, not a cosmetic problem (`PardesView.defaultFace`). A `Font ` arrives as a PATH the core already resolved by walking the font directories, and a file CoreText cannot measure leaves the face already on screen rather than substituting one, because the alternative is a terminal with no way back out (`PardesView.fromFile`). Per-codepoint fallback is CoreText's own cascade at draw time. What the shell caches is `CGGlyph` ids, not pixels. Blank, unknown, malformed, or unsuccessful lines are ignored silently, and a bad line does not prevent later lines from running. Top-level text that is not a builtin is not sent to a shell. (`Exec ...` remains an ordinary builtin and therefore keeps its normal behavior.) Key bindings remain compile-time choices in `src/config.zig`; this startup file does not remap them. ## Panel and scene effects Exactly one panel transition is selected at a time. Executing its builtin a second time turns it off; selecting another replaces it: ```text PanelSlide PanelZoom PanelDissolve PanelAscii PanelVertical PanelEdges PanelFall PanelWave PanelCurtain PanelScramble PanelType ``` All panel transitions start off. Slide uses cubic ease-out and zoom uses an overshooting ease-out-back. Dissolve and ASCII compare the last successfully presented grid with the new one. Dissolve switches visually changed cells at stable noise thresholds. ASCII walks every changed single-byte printable glyph from its old `u8` value to its new one, spending that byte distance as the frames of the walk. The walk is eased in and out: a glyph creeps at both ends and crosses the middle of its distance in a few large skips, inside the same number of frames a constant one-value-per-frame walk would have taken. Glyph-stable style changes and non-ASCII graphemes become canonical immediately. A walk is capped at twelve movement frames, and each pane lasts only as long as its longest walk. The core computes and composes that semantic diff once for every backend; pixel attachments, which have no character value, pass through unchanged. Six further transitions are character *motion* over the same frozen/new grid pair, and are composed in the core the same way: - `PanelEdges` — whole rows slide in from alternating screen edges. - `PanelFall` — columns rain down into place, each with its own head start. - `PanelWave` — a vertical ripple travels across the pane and decays. - `PanelCurtain` — a curtain of glyphs marches column by column, left to right. - `PanelScramble` — every cell churns through printable ASCII and locks onto its final glyph at its own stable noise threshold. - `PanelType` — reading-order reveal with a caret sitting on the write head. Unlike dissolve and ASCII these carry *every* glyph in the pane, changed or not: text flying in from a screen edge has to bring its unchanged glyphs with it. A cell whose glyph has not arrived shows the frozen old cell rather than a blank or a blend, so every intermediate frame is made of real characters. No cell is a valid input target until its own glyph has settled. Vertical is a pane-lifecycle effect: a newly added pane rises from below inside its own fixed box, and a deleted pane's frozen content drops back down; surviving panes are never animated. The TTY implementation performs its remaining geometry/dissolve operations directly on a copy of the core-composed presentation grid. The SDL and native macOS GUI implementations pass plain panel tracks to their GPU shaders, including native image/PDF pixels; layout itself commits immediately and remains the one authoritative geometry. DOM web intentionally does not expose these builtins: its renderer is selectable HTML/CSS and has no canvas or shader stage. The scene effects are independent switches and can be combined: ```text Crt Ripple Glitch ``` They share one full-scene shader pass in SDL and macOS. With all three off the pass is bypassed. CRT works in linear light with restrained scanlines, mask, bloom, curvature, and noise rather than remapping the theme to a strong fixed palette; Ripple and Glitch primarily perturb sample coordinates. `EffectCode ` opens the build-embedded effect math, host paint/submission path, and backend shader/grid sources, for example `EffectCode PanelAscii` or, in a GUI build, `EffectCode Crt`. TTY exposes it for its grid transitions; native GUI builds expose it for transitions and scene shaders. It is absent on web, where no effect argument could succeed. Shared passes are shown as shared source segments rather than manufactured per-effect copies. The command works from an installed binary and does not need the source checkout beside it. SDL output also labels its shader provenance. An ordinary build prints the live GLSL that `glslc` compiled for that executable; `-Dprebuilt-shaders` prints the tracked GLSL snapshot paired with the committed SPIR-V instead and labels those segments with their `shaders/prebuilt/` paths. `zig build shaders` refreshes both files of every pair together, so editing live GLSL without that explicit refresh changes neither half of a prebuilt executable. ## Delayed Look preview The preview is enabled by default. Moving the pointer onto selectable text and leaving it still for `look_preview_delay_frames` — 2 animation ticks, and `animation.frame_ms` is 16, so about 32 ms — paints a subtle theme-derived preview of the exact operand a right-click Look would receive. Repeated motion reports in the same semantic grid cell do not restart the delay. The preview uses the same side-effect-free word/path expansion as Look; it does not focus a pane, move a cursor, install a selection, activate a PDF page, or execute anything. Motion to another operand, pointer leave, input, pane teardown, and relevant content changes cancel it. Set this compile-time option in `src/config.zig` to disable the feature: ```zig pub const look_preview_delay_frames: ?u16 = null; ``` ## Build-time configuration Everything above is chosen at runtime or in `src/config.zig`. The build itself takes these, and this is the whole list — every `b.option` in `build.zig`, besides `-Dtarget` and `-Doptimize` from `standardTargetOptions` and `standardOptimizeOption`: | option | values | default | |---|---|---| | `-Dplatform` | `tty`, `gui`, `web`, `macos`, `esp32p4` | absent builds the tty cli and the SDL gui together | | `-Dstatic` | bool | `false` | | `-Dmupdf` | bool | on for a native target, off for web and esp32p4 | | `-Djpx` | bool | `true` — JPEG 2000, and with it scanned PDFs | | `-Dtree-sitter` | `disabled`, `zig`, `minimal`, `full` | `full` natively, `zig` for web, `disabled` for esp32p4 | | `-Dtheme-animation` | bool | on everywhere except `-Dplatform=esp32p4` | | `-Dprebuilt-shaders` | bool | on for a bare `zig build`, off when `-Dplatform` names a shell | | `-Dtracy` | path to a Tracy source checkout | off | | `-Dmacos-identity` | codesigning identity for `pardes.app` | `-` (ad-hoc) | | `-Ddump` | a `dump.zon` to embed in the web shell | none | | `-Dtest-filter` | substring; run only tests whose name contains it | none | | `-Desp32p4-cols` | u16, the board's grid width in cells | `56` | | `-Desp32p4-rows` | u16, the board's grid height in cells | `14` | | `-Desp32p4-cpu-mhz` | u16: `90`, `180` or `360` | `90`, the bootloader default | | `-Desp32p4-port` | serial port the board is wired to | `/dev/ttyUSB0` | | `-Desp32p4-prof` | bool; per-phase cycle counts for every frame | `false` | | `-Desp32p4-firmware` | bool; also build the flashable image and its board steps | `false` | The five `-Desp32p4-*` options that are not `-Desp32p4-firmware` are registered unconditionally rather than inside the `-Desp32p4-firmware` block that consumes them, so `zig build --help` lists them and passing one without the flag is not an "unknown option" error. Two build inputs reach the running binary as ordinary values rather than as behaviour. `build.zig` reads `.version` from `build.zig.zon` through an untyped `@import("build.zig.zon")` — one place to bump — and `gitCommit(b)` reads the revision at configure time. Both land in `pardes_config` and are re-exported as `pardes.version` and `pardes.commit`, and `pardes --version` prints `pardes ()`, or `pardes ` alone when there is no commit: a tarball, a container with no `git`, or a checkout outside version control all yield null, and the flag has to work anyway. Neither is a question asked at runtime — a binary that shelled out to `git` would describe whatever tree it was standing in rather than the one it came from.