trunk: resume before the Reload experiment

Empty marker on the last pre-Reload change. Keep the Reload experiment on reload (3801914), its first change on reload-start (200a1fc), and the unfinished performance investigation on reload-perf-wip.

1 files changed, 124 insertions, 0 deletions

diff --git a/docs/themes.md b/docs/themes.md
new file mode 100644
index 00000000..7d71d0dd
--- /dev/null
+++ b/docs/themes.md
@@ -0,0 +1,124 @@
+# Pardes themes
+
+Pardes ships fifteen native palettes: six originals, six classic-inspired
+adaptations and three contrast variants, designed for tags, text, search, diagnostics and embedded
+terminals together. `orchard` is the initial theme.
+Execute `Theme <name>` anywhere, or open `ThemeSel` with `SPC t t` and select
+a theme's command. Put the same command in your [startup configuration](config.md)
+to keep a preference. `NextColor` cycles through the native themes first,
+then the retained `helix`, `dark` and `acme` themes and imported palettes.
+`ThemeSel` groups the new palettes under `Pardes themes`, followed by
+`Legacy and imported themes`; its navigation skips the section headings.
+See the [Agave visual review](ui-review.md) for the original six-palette gallery.
+
+| Theme | Character | Page | Accent |
+| --- | --- | --- | --- |
+| `orchard` | Near-black evergreen; bright leaf comments and plum syntax | `#0d1410` | `#adcc91` |
+| `dusk` | Soft plum charcoal; copper comments and gentle text | `#39323b` | `#e4b39b` |
+| `ink` | Pure black; bright, distinct signals and ice-blue comments | `#000000` | `#86d8ff` |
+| `paper` | Neutral uncoated paper; graphite and teal | `#f5f3ed` | `#3c6b56` |
+| `daybreak` | High contrast light; white and deep blue ink | `#ffffff` | `#075f91` |
+| `atelier` | Acme homage; butter-yellow paper and blue-green tags | `#fffdeb` | `#3e7a68` |
+| `forge` | Dark Plus-inspired near-black, blue and peach; slate-blue tags | `#0c0c0e` | `#a5c4ee` |
+| `lagoon` | Softer Material-inspired slate; vivid sea-glass comments | `#34464c` | `#89c7b4` |
+| `solarium` | Softer Solarized-inspired blue-green; golden comments and teal tags | `#173e45` | `#d5bc72` |
+| `spectrum` | Monokai-inspired near-black and candy colors; golden comments | `#100e11` | `#ffd866` |
+| `harvest` | Autumn-inspired near-black earth, ember and leaf green | `#100e0b` | `#cfba8b` |
+| `clay` | Gruvbox-inspired near-black and earthy brights; amber comments | `#10100e` | `#8ec07c` |
+| `forge_black` | Pure-black Forge; luminous text and cool slate tags | `#000000` | `#a5c4ee` |
+| `forge_soft` | Neutral-slate Forge; gentler text, still vivid blue comments | `#35383e` | `#a5c4ee` |
+| `orchard_black` | Pure-black Orchard; luminous garden ink and bright leaf comments | `#000000` | `#adcc91` |
+
+The six adaptations retain recognizable classic syntax identities, but are
+not exact ports. Their Acme influence is deliberate: quiet command strips,
+thin boundaries, and a search surface
+distinct from selection. Forge uses cool-neutral chrome instead of green
+tints. Active pane and column tags use a restrained tone-on-tone shift, not
+a light/dark inversion: dark palettes keep dark tags, and light palettes
+keep light tags. A slight text lift and the focus marker retain the cue
+without turning the entire command strip into a highlight.
+Comments are colorful first-class text, while line numbers stay quiet;
+the current line number gets a small color emphasis and bold weight, never a bright tag-colored
+block. These are appearance changes only;
+tag editing, commands and terminal interaction are unchanged.
+
+Dark backgrounds make an explicit choice: near-black with bright text, or
+the gentler slate/plum/blue-green of `forge_soft`, `dusk`, `lagoon` and
+`solarium`. The softer group keeps body text around 5.5–6.7:1 contrast; the
+near-black group exceeds 14:1. Try `Theme forge_black` and `Theme forge_soft`
+back-to-back to compare the extremes without changing the syntax identity.
+Light paper and the Acme homage remain available.
+
+Their local references are `vendor/themes/dark_plus.toml`,
+`material_oceanic.toml` (and its `material_deep_ocean.toml` parent),
+`solarized_dark.toml`, `monokai_pro.toml`, `autumn.toml`, and the Gruvbox Dark
+entry in `gruvbox.json`. The original imported themes remain selectable under
+their existing names; the adaptations have distinct Pardes names and do not
+claim upstream affiliation. Existing vendor provenance and licenses remain
+with those sources.
+
+All fifteen palettes specify their own ANSI colors, so indexed terminal output
+belongs to the same palette as the editor. Explicit true-color output can
+still carry an application's own colors; the existing terminal `Filter`
+command projects those colors through the theme. The older `dark` palette
+continues to inherit the surrounding terminal's default background and text.
+
+The native palettes keep normal text, syntax colors, comments,
+diagnostics and ANSI foregrounds at a calculated sRGB contrast ratio of at
+least 4.5:1 against the page. `ink` and `daybreak` raise that floor to 7:1.
+Comments additionally stay above 5:1. Decorative line numbers sit between
+2.5:1 and 4:1, with current numbers capped at 4.5:1; they deliberately do not
+compete with source text. ANSI bright black is independent of the comment
+color, so making comments vivid does not recolor gray terminal output.
+Tag, active-tag, selection and search text are checked against their respective
+surfaces at the same thresholds. Active/inactive tag backgrounds differ by
+no more than 1.6:1, keeping focus changes quiet. ANSI black is exempt because applications
+also use it as a background. These are palette checks, not a guarantee about
+arbitrary terminal escape sequences, reversed colors or shader effects.
+
+## Make a theme your own
+
+Run `DumpThemes` to export complete `.zon` files below the configuration
+directory's `themes/builtin/`. Copy a native file to `themes/mine.zon`, change
+its `.name`, and run:
+
+```text
+ThemeFile themes/mine.zon
+```
+
+On hosts with live document reload, saving a valid theme file updates it
+immediately. An incomplete save keeps the last valid version. Selecting a
+built-in theme stops the custom theme watch.
+
+Pardes roles extend the original editor palette with independent choices
+for its UI. Each value is an RGB triple, for example
+`.search_bg = .{ 0x57, 0x47, 0x2a }`. New roles are optional and accept `null`,
+so existing exported themes remain valid.
+
+| Optional role | Purpose | When absent |
+| --- | --- | --- |
+| `tag_active_bg`, `tag_active_fg` | Focused pane tag surface and text | `tag_bg`, `tag_fg` |
+| `border` | Quiet separators | `scroll_track` |
+| `lineno_active` | Restrained current line number foreground | `lineno` |
+| `search_bg`, `search_fg` | Search matches, independent of selection | `sel_bg`, `sel_fg` |
+| `diagnostic_error` | Error text | `fg`, or `tag_fg` for an inherited foreground |
+| `diagnostic_warning` | Warning text | Same foreground fallback |
+| `diagnostic_info` | Informational diagnostic text | Same foreground fallback |
+| `diagnostic_hint` | Hint text | Same foreground fallback |
+
+These colors are shared by the GUI and TTY. Tags and their active tint retain
+the same text, command execution, drag targets and focus behavior. Selection
+and search have separate palette roles because they communicate different
+states. Theme changes use the existing chrome transition; body and terminal
+colors switch directly so syntax and ANSI content stay coherent.
+
+`FocusTint` toggles the focused pane's tag tint, which is on by default.
+`SyntaxBold` toggles bold syntax keywords, which are off by default. Both
+commands take no argument, work in GUI and TTY, and report their states in
+`Config`. Use them in the startup configuration to reverse the defaults.
+
+The original required roles remain unchanged: nullable `bg` and `fg`,
+`sel_bg`, `sel_fg`, `tag_bg`, `tag_fg`, `box`, `box_dim`, `kw`, `str`, `num`,
+`comment`, `lineno`, `scroll_track`, `scroll_thumb`, and a nullable 16-entry
+`palette`. `ThemeFile` loads a complete theme, with no inheritance or partial
+override syntax. The exported native files are the easiest starting point.