From 382abe3dafb872b3e6c9792a9cc0abcf6267e180 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 18 Aug 2026 14:21:38 -0300 Subject: file_watch + builtins + config: richer watch semantics, new builtins, config docs --- docs/config.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++---------- docs/design.typ | 7 ++++++- docs/web.md | 3 ++- 3 files changed, 62 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/config.md b/docs/config.md index 6485d46a..14854ccf 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,17 +1,19 @@ # Startup configuration -Native pardes builds read a per-user `pardes` file before the first frame: +Native pardes builds use a per-user `pardes` configuration directory. Its +main command file is named `init`: -- Unix: `$XDG_CONFIG_HOME/pardes`, falling back to `~/.config/pardes`. -- macOS: `$XDG_CONFIG_HOME/pardes` when that variable is set, otherwise - `~/Library/Application Support/pardes`. -- Windows: `%LOCALAPPDATA%\pardes`, with `%USERPROFILE%\AppData\Local\pardes` - as the fallback. +- 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. Windows never consults it. A file of 1 MiB or -more, or one that cannot be read, is treated as no file at all — the path +back to the home-directory form. Windows never consults it. An `init` of 1 MiB +or more, or one that cannot be read, is treated as no file at all — 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, which `Config` reports as such. @@ -63,9 +65,9 @@ Wrap A line matches a builtin whose name takes NO argument only as that whole word: `Kill` runs, `Kill something` does not. Builtins that take one (`Theme`, -`Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`, -`WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the name as -the argument. +`ThemeFile`, `Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`, +`Rename`, `WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the +name as the argument. `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 @@ -76,6 +78,47 @@ that came from zed with `_zed` so it cannot collide with a helix theme of the same name (zed's "Ayu Mirage" is `ayu_mirage_zed`; `ayu_mirage` is helix's). 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: one ZON struct with the theme name, the fifteen RGB roles, 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`. diff --git a/docs/design.typ b/docs/design.typ index 1c50cfde..d49be3e6 100644 --- a/docs/design.typ +++ b/docs/design.typ @@ -479,7 +479,12 @@ output buffer whose rows are those very commands — execute a row (Tab, middle click) and the theme goes on; n/N select such a row WHOLE, since a command line holds no place to pick out of it — the third grain of that motion, the other two being one stop per ROW in a results list (the location at its head, -never the matched text after it) and every look-able word in free text. +never the matched text after it) and every look-able word in free text. Native +shells also accept `ThemeFile `: one complete ZON `Theme`, loaded at +runtime and, where document watches are available, watched with the same +parent-directory/rename-over semantics. `DumpThemes` materializes the compiled +ring under `/themes/builtin/`, providing the schema and a copyable +starting point without adding inheritance or a second theme vocabulary. Colors toggles all recolor passes; Debug stats overlay; Dump writes state ZON. diff --git a/docs/web.md b/docs/web.md index a6e2e923..578654d3 100644 --- a/docs/web.md +++ b/docs/web.md @@ -59,7 +59,8 @@ real native TTY dump of that same selection; its top and bottom launcher snapshots jointly cover the complete list before opening `build.zig`. What is genuinely absent is narrower than "no IO". The module has no threads -and no host filesystem, so there is no startup config file, LOOK resolves +and no host filesystem, so there is no startup config directory, init file, +ThemeFile, or DumpThemes; LOOK resolves against the build-generated source archive rather than disk, and no language BACKEND is compiled in (`zls_backend` is off for wasm — which also means `lsp.supports` is empty, so the core never even raises a language query there; -- cgit v1.3