@kecan0406/ttheme 0.1.5 → 1.0.1

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

@@ -57,7 +57,7 @@ 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
@@ -71,14 +71,20 @@ alone and only installs. Then it shows what it is about to change and writes it
 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
+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. One more,
+`ttheme · default`, always wears your default palette (none under `keep`): Set
+as Default on it once under Settings › Profiles and new tabs follow `ttheme
+default` from then on. 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
@@ -100,12 +106,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`.
@@ -155,19 +161,22 @@ 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` (the default), enter asks **this tab** or
+Under Ghostty or iTerm2 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
+your Ghostty config and sends `SIGUSR2` to the Ghostty that owns the tab, and
+rewrites iTerm2's `ttheme · default` profile, which iTerm2 reloads by itself — so new tabs, and open tabs you have not
+painted by hand, take the palette without a restart. Painting is per surface
 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
@@ -177,8 +186,24 @@ 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.
+
+iTerm2 keeps a picture per tab. There the picture lives in the palette's own
+profile — `ttheme · kagami` carries the file, its opacity as Blend and cover or
+contain as the image mode, rewritten whenever the picture or its tuning
+changes — and putting a palette with a picture on, or taking one off, moves the
+tab to that palette's profile with `OSC 1337 SetProfile`. The first time,
+iTerm2 asks at the top of the tab whether a control sequence may change the
+profile: Always Allow lets every later switch through — put the palette on once
+more for the one that asked — and a tab it refuses still wears the palette's
+colors, only without the picture. iTerm2 has no
+position setting, so a picture that does not fill the window sits centered.
 
 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
@@ -257,14 +282,15 @@ 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.
 
 `preview` shows the background of the palette under the cursor while you
-browse: through the kitty graphics protocol it draws that palette's
-`background-image` where Ghostty would place it, faded by
+browse: through the kitty graphics protocol (Ghostty, and iTerm2 3.7 or newer)
+it draws that palette's `background-image` where Ghostty would place it, faded by
 `background-image-opacity`, behind the list — or just its plain background when
 it has no file. Only PNG images preview.
 
@@ -283,6 +309,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
@@ -401,13 +435,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