@kecan0406/ttheme 0.1.4 → 1.0.0

package/LICENSE

@@ -19,12 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-Shaders under ghostty/shaders/ are from sahaj-b/ghostty-cursor-shaders and
-carry their own MIT license; see ghostty/shaders/LICENSE.
-
-Palettes are inspired by characters from third-party works. This project is
-unaffiliated with their rights holders and redistributes no character art,
-audio or trademarked asset — only color values.

package/README.md

@@ -7,7 +7,8 @@ Steins;Gate, Lucky☆Star, Bocchi the Rock!, Monogatari, Sailor Moon, Serial
 Experiments Lain, VA-11 Hall-A, Persona 5, Undertale, Call of the Night,
 Higurashi, Doki Doki Literature Club, Umineko, K-On!, Cyberpunk: Edgerunners,
 Touhou Project, Chuunibyou and Jujutsu Kaisen, built for **Ghostty, kitty, Alacritty,
-WezTerm and iTerm2**, plus a zsh layer that rotates through them as you open tabs.
+WezTerm and iTerm2**, plus a zsh layer that repaints tabs at runtime — one palette everywhere, or
+the next one on every new tab.
 
 Two things separate this from the usual color-scheme dump:
 
@@ -56,25 +57,33 @@ came from — `ttheme` prints it, and it is in the theme's TOML.
 
 ## Install
 
-**Ghostty, kitty or Alacritty** — one command, no clone:
+**Ghostty, kitty, Alacritty or iTerm2** — one command, no clone:
 
 ```sh
 npx @kecan0406/ttheme@latest init
 ```
 
 It asks which terminals to wire and which series to install — `space` marks
-one, enter moves on, and `select all` takes the lot — then shows what it is
-about to change and writes it all at once, so cancelling before that touches
-nothing. It places the zsh layer under `~/.config/ttheme` and edits your
-terminal config and `~/.zshrc` between `# ttheme begin` / `# ttheme end`
-markers — everything outside the markers is left alone. It ends with a receipt,
-paints the first palette onto the tab you ran it in and lists what to do next
-(`exec zsh` for the `ttheme` command here, a terminal restart for new tabs).
+one, enter moves on, and `select all` takes the lot — and how the terminal
+should wear them: `default` (preselected) puts one palette on every tab,
+`rotate` gives every new tab the next palette, `keep` leaves your terminal colors
+alone and only installs. Then it shows what it is about to change and writes it all at once,
+so cancelling before that touches nothing. It places the zsh layer under
+`~/.config/ttheme` and edits your terminal config and `~/.zshrc` between
+`# ttheme begin` / `# ttheme end` markers — everything outside the markers is
+left alone. iTerm2 has no config file to edit, so it gets one profile per
+installed palette instead — `ttheme · miku` and so on, in
+`~/Library/Application Support/iTerm2/DynamicProfiles/ttheme.json`, which
+iTerm2 reloads by itself whenever `ttheme browse` adds or drops one. iTerm2
+keeps its own default profile: Set as Default on one under Settings › Profiles
+and every new tab wears it. It ends with a receipt, paints the first palette onto the tab you
+ran it in (not under `keep`) and lists what to do next (`exec zsh` for the
+`ttheme` command here, a terminal restart for new tabs).
 Running it again updates in place; `--yes` skips every prompt and installs no
 palettes — `ttheme browse` opens the full catalog any time, to add or drop
 single palettes.
 
-**WezTerm and iTerm2** — one archive per terminal in the
+**WezTerm, or any of them by hand** — one archive per terminal in the
 [latest release](https://github.com/kecan0406/ttheme/releases/latest):
 
 ```sh
@@ -96,12 +105,12 @@ curl -L $REL/ttheme-wezterm.tar.gz | tar xz
 cp wezterm/colors/miku.toml ~/.config/wezterm/colors/
 #   wezterm.lua:  config.color_scheme = "miku"
 
-# iTerm2 — import the .itermcolors under Settings > Profiles > Colors
+# iTerm2 — open a .itermcolors to add it to Settings > Profiles > Colors presets
 curl -L $REL/ttheme-iterm2.tar.gz | tar xz
 ```
 
-Each archive also carries a `config/` file per theme with that theme's font —
-separate so you can take the colors without the rest. Ghostty is laid out
+The kitty, Alacritty and WezTerm archives also carry a `config/` file per theme
+with that theme's font — separate so you can take the colors without the rest. Ghostty is laid out
 differently: the dock-icon colors travel inside each theme file (they derive
 from the palette), and the font + shader — identical across themes — ship as
 one shared `ttheme.conf` you include once with `config-file`.
@@ -115,9 +124,10 @@ it for real.
 
 ```
 ttheme          list every palette, grouped, with previews
-ttheme homura   pin this tab      (a unique prefix works: ttheme ho)
+ttheme homura   paint this tab    (a unique prefix works: ttheme ho)
 ttheme preview  browse live — focus repaints the tab, enter keeps it (this tab or default)
 ttheme next     advance this tab to the next palette
+ttheme default  make a palette the one new tabs open with
 ttheme pin      pick a palette for this directory — cd into it repaints, cd out restores
 ttheme unpin    drop the palette pinned to this directory
 ttheme config   edit settings in $EDITOR — they apply in new tabs
@@ -150,8 +160,8 @@ the cursor. The list and the sample widen with the window (the sample up to 64
 columns) and the gap between them takes the rest; the tuning panel takes the
 sample's place while open, and so does the key list once the sample is 48
 columns wide.
-Under Ghostty with `TTHEME_TAB_PALETTE=off`, enter asks **this tab** or
-**default**: default records the palette as your startup palette (so a later
+Under Ghostty with `TTHEME_TAB_PALETTE=off` (the default), enter asks **this tab** or
+**default**: default records the palette as your default palette (so a later
 `add` or `remove` keeps it), rewrites `theme =` in the `# ttheme begin` block of
 your Ghostty config and sends `SIGUSR2` to the Ghostty that owns the tab, so new tabs — and open tabs you have not
 painted by hand — take the palette without a restart. Painting is per surface
@@ -159,10 +169,12 @@ otherwise: a new tab starts from the configured theme, not from what the last
 tab was painted.
 
 A palette can also bring a Ghostty background image. The block `init` writes
-includes `~/.config/ttheme/backgrounds/<palette>.conf` for the configured
-theme with an optional `config-file = ?…`, and choosing **default** points that
-include at the new palette — so whatever Ghostty settings you put in that file
-follow the default, and palettes without one show no image:
+includes `~/.config/ttheme/backgrounds/shown.conf` with an optional
+`config-file = ?…`, and that one line names the palette whose picture is up.
+Putting a palette on — `ttheme <name>`, enter in `preview`, `ttheme next`,
+`ttheme default`, cd into a pinned directory — rewrites the line and sends
+`SIGUSR2`, so whatever Ghostty settings you put in `<palette>.conf` arrive with
+the palette, and palettes without a file show no image:
 
 ```
 # ~/.config/ttheme/backgrounds/kagami.conf
@@ -172,8 +184,13 @@ background-image-opacity = 0.2
 ```
 
 ttheme ships no images; they stay on your machine. A background is Ghostty
-config, not an escape sequence, so it follows the default for every window
-rather than the palette painted on one tab.
+config, not an escape sequence, and Ghostty keeps one background for the whole
+app, so one picture is up at a time, in every window. Moving to another tab
+brings its own: while a tab sits at its prompt it asks for focus events, and
+taking focus puts that tab's picture up — or clears it, when its palette has
+none. A tab busy with a command catches up at its next prompt, focus reporting
+is off while that command runs, and a tab whose colors are not a ttheme palette
+leaves the picture where it is.
 
 A palette with no background yet can find one: on it in `preview`, tab opens
 **find**, which searches a booru for the palette's character tag
@@ -252,7 +269,8 @@ list of images — the tag is all it knows about a character.
 
 An install writes `<palette>.png` (the tinted figure), `<palette>@fill-<focus>.png`
 (the window-shaped crop), `<palette>.conf` and the untouched original under
-`backgrounds/originals/`, and removes any earlier tuning of that palette. The
+`backgrounds/originals/`, and starts it untuned — the picture it replaces moves
+to the shelf with the tuning it had. The
 conf opens with where the picture came from —
 `# from yande.re 214705 https://yande.re/post/show/214705` — and the tuning
 panel shows it next to the palette's name.
@@ -278,6 +296,14 @@ background off and on, `=` returns it to its defaults, enter keeps the change
 and esc puts back what the panel opened with. `f` in the panel opens find again
 to replace the picture.
 
+A palette holds every picture installed on it: an install shelves the one on
+screen rather than dropping it, `,` and `.` walk the saved pictures, and `D`
+removes the one shown. Each picture carries its own settings — size, position,
+opacity, the off switch and the baked crops travel with it under
+`backgrounds/shelf/<palette>/<post>/`, so walking back to a picture puts it
+back the way you left it, and tuning you have not confirmed is written to the
+picture before `,` or `.` moves off it.
+
 The palette's `.conf` holds those defaults; the preview only appends two
 optional includes to it and keeps everything else in `<palette>.tune.conf` (the
 tuning) and `<palette>.off.conf` (the off switch), which Ghostty loads after
@@ -307,23 +333,24 @@ case your pick stays. The nearest pinned ancestor wins, so a project can pin
 one palette and a subfolder another. Open tabs pick up a changed pins file on
 their next `cd`; `unpin` drops the pin on the current directory.
 
-`preview`, `next`, `pin`, `unpin`, `config` and `help` match exactly; every other first argument is read
+`preview`, `next`, `default`, `pin`, `unpin`, `config` and `help` match exactly; every other first argument is read
 as a palette name, where a unique prefix is enough. Mistyped names get a "did
 you mean" suggestion instead of a wall of output. Piped output drops color and
 turns tab-separated, and `NO_COLOR` is respected.
 
-New tabs take the next palette in group order, with the counter shared across
+With `TTHEME_TAB_PALETTE=seq`, new tabs take the next palette in group order, with the counter shared across
 tabs — so opening four tabs walks you through four different characters rather
 than rolling the same one twice.
 
 Settings live in `~/.config/ttheme/config.zsh` — `init` seeds it with the
-defaults and never overwrites a line you changed, `ttheme config` opens it in `$EDITOR` and alt-c in `preview` edits it in place. Each line is a plain zsh
+defaults and never overwrites a line you changed — bar `TTHEME_TAB_PALETTE`, which its
+default/rotate/keep question sets — `ttheme config` opens it in `$EDITOR` and alt-c in `preview` edits it in place. Each line is a plain zsh
 `: ${VAR:=value}` assignment, so a variable exported before the layer loads
 still wins:
 
 | Setting | Default | |
 |---|---|---|
-| `TTHEME_TAB_PALETTE` | `seq` | `off` keeps new tabs on the terminal's configured theme (`preview` → default changes it) |
+| `TTHEME_TAB_PALETTE` | `off` | `off` keeps new tabs on the terminal's configured theme (`preview` → default changes it); `seq` gives every new tab the next palette. `init` writes `seq` for rotate and `off` for default and keep |
 | `TTHEME_ANNOUNCE` | `1` | `0` silences the one-line notice under "Last login:" |
 | `TTHEME_FX` | `typewriter` | search hint animation — `typewriter`, `decode` or `glitch` |
 | `TTHEME_SORT` | `abc` | `series` lists series and palettes in the order they were added instead of by name — in `ttheme`, `preview` and, once exported, the `init` picker |
@@ -395,13 +422,18 @@ get it.
 | **kitty** | ✅ | ✅ native adapter | family + size | ✗ |
 | **WezTerm** | ✅ | OSC — per window, never per pane | family + size | ✗ |
 | **Alacritty** | ✅ | OSC only (no runtime color API exists) | family + size | ✗ |
-| **iTerm2** | ✅ | OSC, minus the cursor (it ignores OSC 12) | profile-only | ✗ |
+| **iTerm2** | ✅ a profile per palette | OSC | profile-only | ✗ |
 | anything else | — | OSC, if it speaks it | — | ✗ |
 
 Ghostty is the only terminal here with GLSL shaders, and the only one with
 per-codepoint font mapping — which is why the Hangul→D2Coding rule survives only
 in its build.
 
+iTerm2 reads the colors an OSC sets as Display P3 — its default color space — so
+its profiles and `.itermcolors` files are written in P3 too: a tab opened on a
+`ttheme · <palette>` profile and a tab repainted to that palette land on the
+same colors, and ttheme recognizes the palette either way.
+
 ## Adding a palette
 
 One file — copy any of `themes/*.toml`. `CONTRIBUTING.md` has the rules for