diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/config.md | 36 | ||||
| -rw-r--r-- | docs/effects.md | 80 | ||||
| -rw-r--r-- | docs/render-pipeline.md | 11 | ||||
| -rw-r--r-- | docs/themes.md | 45 |
4 files changed, 159 insertions, 13 deletions
diff --git a/docs/config.md b/docs/config.md index 9d7446f1..58836b7b 100644 --- a/docs/config.md +++ b/docs/config.md @@ -109,11 +109,15 @@ project gains or loses a file. A name that is not in the ring is ignored. The fifteen [native Pardes themes](themes.md) lead the ring: `orchard` (the default), `dusk`, `ink`, `paper`, `daybreak`, `atelier`, `forge`, `lagoon`, `solarium`, `spectrum`, `harvest`, `clay`, `forge_black`, `forge_soft`, and -`orchard_black`. `Themes` lists them first under Pardes themes, followed by -a separate legacy/imported section. They add coordinated +`orchard_black`, then `acme` and `lapis`. `Themes` lists them first under +Pardes themes. They add coordinated focus, search, diagnostic and terminal colors; `ink` and `daybreak` are high -contrast dark and light options. The original `helix`, `dark` and `acme` -themes and all imported names remain available. +contrast dark and light options. After them come the +[faithful ports](themes.md#faithful-ports) of well-known themes, a section per +family, then the legacy `helix` and `dark`, then everything imported. Where a +port takes an imported theme's name (`dracula`), the imported one gains +`_helix` (`dracula_helix`), as zed's carry `_zed`. `NextColor` walks the same +ring in the same order. `FocusTint` toggles the focused pane and column tag tints; it is on by default. Workspace, column and pane command text can be edited directly; see @@ -513,7 +517,7 @@ 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. +- `PanelCurtain` — a wipe, left to right, behind a soft edge two cells wide. - `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. @@ -543,8 +547,11 @@ Crt 3 ``` The SDL GUI runs it as the bundled pass of its post chain, which also takes -Shadertoy files written for ghostty (`Shader ~/crt.glsl`, `Shader off`), and -`ShaderAnimation off|on|always` says when the chain animates on its own. With +Shadertoy files written for ghostty (`Shader ~/crt.glsl`, `Shader off`; +a file compiles again when it is saved, and a save that fails to compile +keeps the last good one and says why), and +`ShaderAnimation off|on|always` says when the chain animates on its own. A +GUI attached to a detached session runs the session's chain the same way. With the chain empty the pass is bypassed. CRT works in linear light with restrained scanlines, mask, bloom and vignette, and no curvature, so clicks land where they are drawn. @@ -574,6 +581,21 @@ InactiveDim 30 the unfocused panes' text fades 30% toward its ground Motion smooth off, crisp, smooth (the default), bouncy or playful SelectionGlow on a soft halo of the selection's colour round it in the body, fading in over 100 ms, never over a tag, a grip or the cursor +HoverGlow on a soft glow under the word a look-hover would open, fading + in over 80 ms +Occlusion on pane bodies darken faintly toward their edges (2%), never + over the cursor +Parallax on a theme's page pattern (lapis's dots) moves with the text + at a quarter of its speed +Afterglow on text that changes glows for a moment in the theme's accent + and fades (250 ms), never on a tag, the cursor or a selection +JumpTrail on in a terminal, a jump of the cursor of three cells or more + leaves a trail of a few cells that fades in 120 ms + (truecolor terminals; a pixel shell glides instead) +ChipShadow on in a terminal, a notice chip casts a shadow a cell right and + down: half blocks on blank cells, a darker ground on text +ThumbFlash on in a terminal, a pane's scroll thumb brightens as it scrolls + and fades back over 250 ms CursorBlink on the cursor blinks, solid while typing and half a second after, eased at each edge, solid after 10 idle seconds GripWidth 150 the grip's button and the scrollbar under it, percent of the diff --git a/docs/effects.md b/docs/effects.md index 0e0ad51a..a0edc2ab 100644 --- a/docs/effects.md +++ b/docs/effects.md @@ -44,6 +44,10 @@ why. The verdict is the user's. | G8 notice chips | follows `Motion` and `Lift` | a notice floats in tier 4 on a lift (shadow) while Lift is on, drops in easing out and dissolves easing in, quicker than it came (150 ms against 180) | .scratch/render/notices/ (acme, forge) | pending | | G9 selection glow | `SelectionGlow on\|off` (off) | a soft halo of the selection's colour round each block of it in a body, fading in over 100 ms | .scratch/render/selection/ (forge, acme, lapis; lapis-glow-zoom.png) | pending | | G10 theme crossfade | always (a theme change) | the chrome's colours fade through OKLab, easing in and out (out when retargeted) | .scratch/render/crossfade/ (forge, lapis, acme cut short by dusk) | pending | +| G11 look-hover glow | `HoverGlow on\|off` (off) | a soft underline of the theme's accent under the word a look-hover would open, fading in over 80 ms | .scratch/render/hover/ (forge, acme, lapis; zooms) | pending | +| G12 ambient occlusion | `Occlusion on\|off` (off) | pane bodies darken toward their edges, at most 2% (§9.1: 1 to 2%) | .scratch/render/occlusion/ (on/off on forge, acme, lapis; acme-diff-x40.png) | pending | +| G13 parallax | `Parallax on\|off` (off) | a theme's page pattern under the bodies (lapis's dots) moves with the text at a quarter of its speed, glides included | .scratch/render/parallax/ (lapis, notches down and up) | pending | +| G14 afterglow | `Afterglow on\|off` (off) | a body cell whose text changed glows in the accent at 18% and fades over 250 ms | .scratch/render/afterglow/ (forge, acme: two in-place edits) | pending | ## Motion flavours @@ -92,6 +96,13 @@ Which principles each motion uses: the flavour's arc), anticipation (playful's wind-up). A step of a cell or less, or any move in insert mode, lands at once, so typing never trails; a scroll carries the cursor with the text. Only the focused cursor moves. + A pane that moves carries it too: the springs keep its place in the pane + and the quad is drawn through the pane's presented box, so through a + slide, a zoom or a drag it rides with the text, and a layout change with + no transition lands it with the text. A focus change (to another pane, or + into a column's or the workspace's tag) glides from where the cursor is + drawn to the new one, free of the old pane's edges while it crosses + (.scratch/render/cursor/move/: ride-*, cross-*). Notes on G1: the lift and the dim run on one focus spring per pane, at the @@ -207,3 +218,72 @@ muddy, on a smooth ease-in-out; a change made mid-fade sets off from where it shows and eases out, so it moves at once instead of stalling. The page, its text and the syntax colours still change at once with the theme, as before: fading them would re-resolve every cell each frame. + +Notes on G11: the word a look-hover would open is already lit (the +affordance's tint); HoverGlow adds a strip three logical pixels tall along +its foot in the theme's accent, its edges blurred by one, at most 22% and +under the text's contrast floor, fading in over 80 ms (micro-feedback). It +stays on bodies and is split round a cursor, so it never touches one. The +word is found by the tint's colour, as G9 finds the selection. +Found while reviewing: with the machine loaded, test/gui_golden.py's +two-captures-agree settle can take a scene's frame before the scene's +change lands, and every later hash moves up a scene; a rerun on a quiet +machine matches. + +Notes on G12: four soft strips cast from just outside each body inward, +clipped to it and round a cursor, black in linear light, 2% at most and +under the lift's contrast ceiling, in the pane's own group so it moves +with it. At §9.1's strength it is all but invisible on a dark page (a +level of 255 on forge) and faint on a light one (acme's page steps one +level toward the edges); acme-diff-x40.png shows where it falls. + +Notes on G13: a body region now carries its first line (Region.line: a +file's scroll, a terminal's grid offset; on the wire, a u32 more a +region). Under Parallax the dots under each body are offset by a quarter +of its line times the row height, plus G6's glide offset while one runs, +so they drift with the text as it glides and settle with it (measured: 4 +lines at 35 px move the 22 px grid 13 px, 35 mod 22). The cell shader +reads the offset from the instance's serial slot, free since G7 took the +dissolve's per-cell noise out. Without a pattern, nothing happens. + +Notes on G14: the GUI keeps the grid it last drew and when each cell last +changed; a changed cell of a pane body glows in the theme's accent, 18% at +most and under the text's contrast floor, and fades with an ease-out over +250 ms, drawn as one flat rectangle a run of cells that changed together. +Never on a tag or a grip (bodies only), the cursor's cell or a selection; +a body whose first line moved (a scroll) starts over instead of lighting +up whole. It runs on the continuous path while anything glows, and costs +a compare of the grid a frame while on, nothing while off. + +## Terminal track (§9.2) + +Audit, after decision 2 (keep every whimsical effect and polish it, never +remove it): the six core-composed character transitions (ascii, edges, +fall, wave, scramble, typewriter) and curtain stay as they are, each +bounded to its pane's final rectangle and each cell's last sample its +canonical one; slide and vertical are the tty compositor's and follow the +Motion flavour (sxrrwplk); zoom stays (nearest-cell scaling, its look is +the effect); dissolve swaps each changed cell once at its threshold; +message fades and the theme's chrome fade are the core's (the latter in +OKLab since G10), and InactiveDim (T5's unfocused dim) works in a grid as +it does in a pixel shell. + +| # | effect | switch | state | review material | verdict | +|---|---|---|---|---|---| +| T2 | cursor jump trail | `JumpTrail on\|off` (off) | a jump of three cells or more leaves 3 to 5 cells of trail behind the cursor, their ground drawn toward the text's colour in OKLab, most beside it, fading in 120 ms; truecolor terminals (vaxis's answer or COLORTERM); never the cursor's cell, a selection or outside the focused body; off under Motion off; a few cells a frame | .scratch/render/tty/trail/ (pyte replay of a real tty session at 60 fps: trail-forge.mp4, zooms) | pending | +| T1 chip shadow | `ChipShadow on\|off` (off) | a notice chip casts a shadow a cell right and down in its body: half blocks (▌ ▀ ▘) in a darker ground on blank cells, the ground 35% darker (OKLab) under text; never the cursor, a selection, a tag or another chip; truecolor only | .scratch/render/tty/shadow/ (forge, acme; zooms) | pending | +| T4 ordered swap | `PanelDissolve` (off) | the terminal's dissolve swaps each changed cell once at its place in a 4x4 Bayer matrix (shifted per pane), an even patterned screen instead of noise; hit-testing follows the same order | .scratch/render/tty/dissolve/ (ordered-swap-sim: the matrix applied to two real frames; see note) | pending | +| T7 thumb flash | `ThumbFlash on\|off` (off) | a pane whose view moves has its scroll thumb drawn toward the text's colour, 60% at once and back over 250 ms (quadratic); the thumb only, never a focus indicator; truecolor only; a few cells a frame while it fades | .scratch/render/tty/thumb-flash.mp4, thumb-flash-strip.png (pyte replay, forge) | pending | +| T3 wipe | `PanelCurtain` (off) | the curtain becomes a wipe, left to right: new grid behind the head, old ahead, and a soft edge of two columns whose ink and ground sit 2/3 and 1/3 of the way to the old ground (OKLab; a palette colour steps at the half); only the head's columns change a frame; the head's cells are not hit-testable until settled | .scratch/render/tty/wipe/ (curtain-gui.mp4, curtain-edge-zoom.png) | pending | + +Note on T4's material: a pane opening in a tty session recorded through +pyte did not animate (PanelSlide did not either there), so the review +material applies the same matrix to two real frames of that session; the +unit test holds the order (a 4x4 block reveals exactly t x 16 cells). + +Not built: T5 (unfocused dim) is InactiveDim, which already works in a +grid. T6 (a truecolor ramp on the active tag band) would change the +focused tag's colour, a focus indicator no effect may alter, so it stays +out. The §9.2 byte budget (deferring a sample after an oversized frame, +DECRQM for sync 2026) is not built either: the terminal effects here change +a few cells a frame, and only PanelSlide rewrites a whole pane per sample. diff --git a/docs/render-pipeline.md b/docs/render-pipeline.md index b8f735d9..88309d4a 100644 --- a/docs/render-pipeline.md +++ b/docs/render-pipeline.md @@ -501,8 +501,15 @@ Mirror ghostty 1.3.2 (`zig-pkg/ghostty-*/src/renderer/shadertoy.zig`, file, not `<stdin>`. Level A redraws once a refresh of the window's display. A failed compile keeps the file's last good pipeline and says glslc's first line as a message; glslc missing is said once, and only files stay off (the bundled passes are compiled with the - build, through the same prefix). No file watching: `Shader <path>` twice - (out, then in) compiles it again. + build, through the same prefix). The files' directories are watched + (file_watch shader slots): a change there has each file read and hashed, + and one whose bytes moved compiles again; the same bytes (good or bad) + compile nothing and say nothing twice. The process that holds the core + compiles (shader_build.zig): a local GUI, or a detached session, which + sends its attached GUIs the chain with each file's SPIR-V (wire `post`, + on attach and on every change), so an attached GUI runs the same passes, + levels and ShaderAnimation as a local one and still reads no disk and runs + no program. - **Animation mode**: `ShaderAnimation off|on|always` (ghostty's `custom-shader-animation`): off = redraw only when content changes; on = continuous while the window is focused; always = continuous. Continuous means diff --git a/docs/themes.md b/docs/themes.md index 5349a764..d163b243 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -6,9 +6,10 @@ terminals together. `orchard` is the initial theme. Execute `Theme <name>` anywhere, or open `Themes` 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. -`Themes` groups the new palettes under `Pardes themes`, followed by -`Legacy and imported themes`; its navigation skips the section headings. +then `acme` and `lapis`, the [faithful ports](#faithful-ports), the legacy +`helix` and `dark`, and the imported palettes. `Themes` shows the same +order in sections: `Pardes themes`, one per ported family, `Legacy themes` +and `Imported themes (helix, zed)`; its navigation skips the section headings. See the [Agave visual review](ui-review.md) for the original six-palette gallery. | Theme | Character | Page | Accent | @@ -58,7 +59,8 @@ 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 +their existing names (one a [faithful port](#faithful-ports) now holds gains +`_helix`, as in `dracula_helix`); the adaptations have distinct Pardes names and do not claim upstream affiliation. Existing vendor provenance and licenses remain with those sources. @@ -81,6 +83,41 @@ no more than 1.6:1, keeping focus changes quiet. ANSI black is exempt because ap also use it as a background. These are palette checks, not a guarantee about arbitrary terminal escape sequences, reversed colors or shader effects. +## Faithful ports + +These are well-known themes taken as close to their originals as pardes can +draw them: every colour the original has (page, text, selection, syntax, line +numbers, diagnostics, terminal ANSI) is its own, read out of the original's +files, and each theme file cites the file and line of every value. The loose +adaptations above (`forge`, `solarium`, `spectrum`, ...) stay as they are. + +pardes has one colour each for keywords, strings, numbers and comments, so a +theme that splits a kind (VS Code's control-flow keywords) keeps its main +one. A pane's tag is the original's window bar (vim's `StatusLine` and +`StatusLineNC`, emacs's `mode-line` and `mode-line-inactive`) or, in a tabbed +editor, its tab. What the original lacks (grips, a scroll column) comes from +its own palette. Where a chrome colour misses one of pardes's floors (rules +1.5:1 off the page, the focused tag 1.5:1 off the unfocused one on a dark +page and 1.25:1 on a light one, tag text 4.5:1), only that chrome colour +moves, just far enough, and the file's header says so. Text, syntax and ANSI +are never adjusted. + +| Family | Themes | Source | +| --- | --- | --- | +| Visual Studio Code | `dark_plus` | VS Code 1.130.0 `extensions/theme-defaults/themes/dark_plus.json` and `dark_vs.json`; [microsoft/vscode](https://github.com/microsoft/vscode) 1.130.0 | +| Solarized | `solarized_dark`, `solarized_light` | [altercation/solarized](https://github.com/altercation/solarized); `~/05-genizah/solarized/vim-colors-solarized/colors/solarized.vim` | +| Dracula | `dracula`, `dracula_soft`, `alucard` | [dracula/dracula-theme](https://github.com/dracula/dracula-theme); [dracula/visual-studio-code](https://github.com/dracula/visual-studio-code) | +| Monokai | `monokai` | [download.sublimetext.com](https://download.sublimetext.com/Sublime%20Text%202.0.2%20x64.tar.bz2) | +| Monokai Pro | `monokai_pro`, `monokai_pro_classic`, `monokai_pro_machine`, `monokai_pro_octagon`, `monokai_pro_ristretto`, `monokai_pro_spectrum`, `monokai_pro_light`, `monokai_pro_light_sun` | [open-vsx.org](https://open-vsx.org/api/monokai/theme-monokai-pro-vscode/2.0.15/file/monokai.theme-monokai-pro-vscode-2.0.15.vsix) | +| Tokyo Night | `tokyonight_night`, `tokyonight_storm`, `tokyonight_moon`, `tokyonight_day` | [folke/tokyonight.nvim](https://github.com/folke/tokyonight.nvim) | +| Rosé Pine | `rose_pine`, `rose_pine_moon`, `rose_pine_dawn` | [rose-pine/palette](https://github.com/rose-pine/palette); [rose-pine/neovim](https://github.com/rose-pine/neovim) | +| Catppuccin | `catppuccin_latte`, `catppuccin_frappe`, `catppuccin_macchiato`, `catppuccin_mocha` | [catppuccin/palette](https://github.com/catppuccin/palette); [catppuccin/nvim](https://github.com/catppuccin/nvim) | +| Seoul256 | `seoul256_dark_233`, `seoul256_dark_234`, `seoul256_dark_235`, `seoul256_dark_236`, `seoul256_dark_237`, `seoul256_dark_238`, `seoul256_dark_239`, `seoul256_light_252`, `seoul256_light_253`, `seoul256_light_254`, `seoul256_light_255`, `seoul256_light_256` | [junegunn/seoul256.vim](https://github.com/junegunn/seoul256.vim) | +| Zenbones | `zenbones_light`, `zenbones_dark`, `neobones_light`, `neobones_dark`, `vimbones`, `forestbones_light`, `forestbones_dark`, `nordbones`, `rosebones_light`, `rosebones_dark`, `tokyobones_light`, `tokyobones_dark`, `seoulbones_light`, `seoulbones_dark`, `duckbones`, `zenburned`, `zenwritten_light`, `zenwritten_dark`, `kanagawabones` | [zenbones-theme/zenbones.nvim](https://github.com/zenbones-theme/zenbones.nvim) | +| Nord | `nord` | [nordtheme/nord](https://github.com/nordtheme/nord); [nordtheme/vim](https://github.com/nordtheme/vim); [nordtheme/visual-studio-code](https://github.com/nordtheme/visual-studio-code) | +| Ayu | `ayu_dark`, `ayu_mirage`, `ayu_light` | [ayu-theme/ayu-colors](https://github.com/ayu-theme/ayu-colors); [ayu-theme/vscode-ayu](https://github.com/ayu-theme/vscode-ayu) | +| Doom One | `doom_one`, `doom_one_light` | [doomemacs/themes](https://github.com/doomemacs/themes) | + ## Make a theme your own Run `DumpThemes` to export complete `.zon` files below the configuration |