When asking for permission to exec a shebang script also add options to view or edit the script

Note that we loose unicode char matching for --type=word because of
https://github.com/dlclark/regexp2/issues/65 and of course user regexps
cant use \p{N} escapes any more. Hopefully regexp2 will add support for
these soon-ish. IMO lookaround is more important than \p.

Fixes #6265

.editorconfig

@@ -1,12 +1,12 @@
 root = true
 
 [*]
-indent_style = spaces
+indent_style = space
 indent_size = 4
 end_of_line = lf
 trim_trailing_whitespace = true
 
-[{Makefile,*.terminfo}]
+[{Makefile,*.terminfo,*.go}]
 indent_style = tab
 
 # Autogenerated files with tabs below this line.

.gitattributes

@@ -3,7 +3,9 @@ kitty/emoji.h linguist-generated=true
 kitty/charsets.c linguist-generated=true
 kitty/key_encoding.py linguist-generated=true
 kitty/unicode-data.c linguist-generated=true
+kitty/rowcolumn-diacritics.c linguist-generated=true
 kitty/rgb.py linguist-generated=true
+kitty/srgb_gamma.c linguist-generated=true
 kitty/gl-wrapper.* linguist-generated=true
 kitty/glfw-wrapper.* linguist-generated=true
 kitty/parse-graphics-command.h linguist-generated=true
@@ -15,6 +17,9 @@ kittens/diff/options/parse.py linguist-generated=true
 glfw/*.c linguist-vendored=true
 glfw/*.h linguist-vendored=true
 kittens/unicode_input/names.h linguist-generated=true
+tools/wcswidth/std.go linguist-generated=true
+tools/unicode_names/names.txt linguist-generated=true
 
 *.py  text diff=python
 *.m  text diff=objc
+*.go text diff=go

.github/workflows/ci.py

@@ -30,13 +30,22 @@ def install_deps():
     print('Installing kitty dependencies...')
     sys.stdout.flush()
     if is_macos:
-        items = (x.strip() for x in open('Brewfile').readlines() if not x.startswith('#'))
+        items = [x.split()[1].strip('"') for x in open('Brewfile').readlines() if x.strip().startswith('brew ')]
-        run('brew', 'install', *items)
+        openssl = 'openssl'
+        items.remove('go')  # already installed by ci.yml
+        import ssl
+        if ssl.OPENSSL_VERSION_INFO[0] == 1:
+            openssl += '@1.1'
+        run('brew', 'install', 'fish', openssl, *items)
     else:
         run('sudo apt-get update')
         run('sudo apt-get install -y libgl1-mesa-dev libxi-dev libxrandr-dev libxinerama-dev ca-certificates'
-            ' libxcursor-dev libxcb-xkb-dev libdbus-1-dev libxkbcommon-dev libharfbuzz-dev libx11-xcb-dev'
+            ' libxcursor-dev libxcb-xkb-dev libdbus-1-dev libxkbcommon-dev libharfbuzz-dev libx11-xcb-dev zsh'
-            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev librsync-dev uuid-dev')
+            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev librsync-dev uuid-dev'
+            ' zsh bash dash')
+        # for some reason these directories are world writable which causes zsh
+        # compinit to break
+        run('sudo chmod -R og-w /usr/share/zsh')
     if is_bundle:
         install_bundle()
     else:
@@ -55,7 +64,7 @@ def build_kitty():
 
 
 def test_kitty():
-    run('./kitty/launcher/kitty +launch test.py')
+    run('./test.py')
 
 
 def package_kitty():
@@ -121,6 +130,12 @@ def main():
         package_kitty()
     elif action == 'test':
         test_kitty()
+    elif action == 'gofmt':
+        q = subprocess.check_output('gofmt -s -l tools'.split())
+        if q.strip():
+            q = '\n'.join(filter(lambda x: not x.rstrip().endswith('_generated.go'), q.decode().strip().splitlines())).strip()
+            if q:
+                raise SystemExit(q)
     else:
         raise SystemExit(f'Unknown action: {action}')
 

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ env:
     LC_ALL: en_US.UTF-8
     LANG: en_US.UTF-8
 
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
 jobs:
     linux:
         name: Linux (python=${{ matrix.pyver }} cc=${{ matrix.cc }} sanitize=${{ matrix.sanitize }})
@@ -20,15 +23,15 @@ jobs:
                 cc: [gcc, clang]
                 include:
                     - python: a
-                      pyver: 3.7
+                      pyver: "3.8"
                       sanitize: 0
 
                     - python: b
-                      pyver: 3.8
+                      pyver: "3.11"
                       sanitize: 1
 
                     - python: c
-                      pyver: 3.9
+                      pyver: "3.9"
                       sanitize: 1
 
 
@@ -41,20 +44,26 @@ jobs:
                       cc: gcc
 
         steps:
-            - name: Checkout source code
+          - name: Checkout source code
-              uses: actions/checkout@master
+            uses: actions/checkout@v3
-              with:
+            with:
-                fetch-depth: 10
+              fetch-depth: 10
-            - name: Set up Python ${{ matrix.pyver }}
-              uses: actions/setup-python@master
-              with:
-                python-version: ${{ matrix.pyver }}
 
-            - name: Build kitty
+          - name: Set up Python ${{ matrix.pyver }}
-              run: python .github/workflows/ci.py build
+            uses: actions/setup-python@v4
+            with:
+              python-version: ${{ matrix.pyver }}
 
-            - name: Test kitty
+          - name: Install Go
-              run: python .github/workflows/ci.py test
+            uses: actions/setup-go@v3
+            with:
+              go-version-file: go.mod
+
+          - name: Build kitty
+            run: python .github/workflows/ci.py build
+
+          - name: Test kitty
+            run: python .github/workflows/ci.py test
 
     linux-package:
         name: Linux package
@@ -62,36 +71,53 @@ jobs:
         env:
             CFLAGS: -funsigned-char
         steps:
-            - name: Checkout source code
+          - name: Checkout source code
-              uses: actions/checkout@master
+            uses: actions/checkout@v3
-              with:
+            with:
-                fetch-depth: 10
+              fetch-depth: 0  # needed for :commit: docs role
 
-            - name: Test for trailing whitespace
+          - name: Test for trailing whitespace
-              run: if grep -Inr '\s$' kitty kitty_tests kittens docs *.py *.asciidoc *.rst .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
+            run: if grep -Inr '\s$' kitty kitty_tests kittens docs *.py *.asciidoc *.rst *.go .gitattributes .gitignore; then echo Trailing whitespace found, aborting.; exit 1; fi
 
-            - name: Set up Python
+          - name: Set up Python
-              uses: actions/setup-python@master
+            uses: actions/setup-python@v4
-              with:
+            with:
-                python-version: 3.8
+              python-version: "3.10"
 
-            - name: Install build-only deps
+          - name: Install Go
-              run: pip install -r docs/requirements.txt flake8 mypy types-requests types-docutils
+            uses: actions/setup-go@v3
+            with:
+              go-version-file: go.mod
 
-            - name: Run pyflakes
+          - name: Install build-only deps
-              run: python -m flake8 --count .
+            run: python -m pip install -r docs/requirements.txt ruff mypy types-requests types-docutils
 
-            - name: Build kitty package
+          - name: Run ruff
-              run: python .github/workflows/ci.py package
+            run: ruff .
 
-            - name: Run mypy
+          - name: Run gofmt
-              run: python test.py mypy
+            run: go version && python .github/workflows/ci.py gofmt
 
-            - name: Build man page
+          - name: Build kitty package
-              run: make FAIL_WARN=1 man
+            run: python .github/workflows/ci.py package
 
-            - name: Build HTML docs
+          - name: Build kitty
-              run: make FAIL_WARN=1 html
+            run: python setup.py build --debug
+
+          - name: Build static kitten
+            run: python setup.py build-static-binaries
+
+          - name: Run mypy
+            run: which python && python -m mypy --version && ./test.py mypy
+
+          - name: Run go vet
+            run: go version && go vet ./...
+
+          - name: Build man page
+            run: make FAIL_WARN=1 man
+
+          - name: Build HTML docs
+            run: make FAIL_WARN=1 html
 
     bundle:
         name: Bundle test (${{ matrix.os }})
@@ -102,31 +128,52 @@ jobs:
         env:
             KITTY_BUNDLE: 1
         steps:
-            - name: Checkout source code
+          - name: Checkout source code
-              uses: actions/checkout@master
+            uses: actions/checkout@v3
-              with:
+            with:
-                fetch-depth: 10
+              fetch-depth: 10
 
-            - name: Build kitty
+          - name: Install Go
-              run: which python3 && python3 .github/workflows/ci.py build
+            uses: actions/setup-go@v3
+            with:
+              go-version-file: go.mod
 
-            - name: Test kitty
+          - name: Build kitty
-              run: python3 .github/workflows/ci.py test
+            run: which python3 && python3 .github/workflows/ci.py build
+
+          - name: Test kitty
+            run: python3 .github/workflows/ci.py test
 
     brew:
         name: macOS Brew
         runs-on: macos-latest
         steps:
-            - name: Checkout source code
+          - name: Checkout source code
-              uses: actions/checkout@master
+            uses: actions/checkout@v3
-              with:
+            with:
-                  fetch-depth: 10
+              fetch-depth: 0  # needed for :commit: docs role
 
-            - name: Build kitty
+          - name: Set up Python
-              run: python3 .github/workflows/ci.py build
+            uses: actions/setup-python@v4
+            with:
+              python-version: "3.10"
 
-            - name: Test kitty
+          - name: Install Go
-              run: python3 .github/workflows/ci.py test
+            uses: actions/setup-go@v3
+            with:
+              go-version-file: go.mod
 
-            - name: Build kitty package
+          - name: Build kitty
-              run: python3 .github/workflows/ci.py package
+            run: python3 .github/workflows/ci.py build
+
+          - name: Test kitty
+            run: python3 .github/workflows/ci.py test
+
+          - name: Install deps for docs
+            run: python3 -m pip install -r docs/requirements.txt
+
+          - name: Builds docs
+            run: make FAIL_WARN=1 docs
+
+          - name: Build kitty package
+            run: python3 .github/workflows/ci.py package

.github/workflows/codeql-analysis.yml

@@ -9,27 +9,41 @@ on:
   schedule:
     - cron: '0 22 * * 5'
 
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
 jobs:
   CodeQL-Build:
 
+    permissions:
+      contents: read # to fetch code (actions/checkout)
+      security-events: write # to upload SARIF results (github/codeql-action/analyze)
+
     runs-on: ubuntu-latest
 
     steps:
+
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         # We must fetch at least the immediate parents so that if this is
         # a pull request then we can checkout the head.
         fetch-depth: 2
 
+    - name: Install Go
+      uses: actions/setup-go@v3
+      with:
+        go-version-file: go.mod
+
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v2
       with:
         languages: python, c
+        setup-python-dependencies: false
 
     - name: Build kitty
       run: python3 .github/workflows/ci.py build
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v2

.gitignore

@@ -1,22 +1,25 @@
 *.so
 *.pyc
 *.pyo
+*.bin
 *_stub.pyi
+*_generated.go
+*_generated.h
 /.dmypy.json
 /tags
 /build/
 /linux-package/
 /kitty.app/
-/compile_commands.json
-/link_commands.json
 /glad/out/
-/kitty/launcher/
+/kitty/launcher/kitt*
 /*.dSYM/
 __pycache__/
 /glfw/wayland-*-client-protocol.[ch]
 /docs/_build/
 /docs/generated/
 /.mypy_cache
+/.ruff_cache
 .DS_Store
+.cache
 bypy/b
 bypy/virtual-machines.conf

Brewfile

@@ -1,7 +1,8 @@
-pkg-config
+brew "pkg-config"
-zlib
+brew "zlib"
-librsync
+brew "librsync"
-python
+brew "python"
-imagemagick
+brew "imagemagick"
-harfbuzz
+brew "harfbuzz"
-sphinx-doc
+brew "sphinx-doc"
+brew "go"

CONTRIBUTING.md

@@ -7,6 +7,11 @@ When reporting a bug, provide full details of your environment, that means, at
 a minimum, kitty version, OS and OS version, kitty config (ideally a minimal
 config to reproduce the issue with).
 
+Note that bugs and feature requests are often closed quickly as they are either
+fixed or deemed wontfix/invalid. In my experience, this is the only scaleable way to
+manage a bug tracker. Feel free to continue to post to a closed bug report
+if you would like to discuss the issue further. Being closed does not mean you
+will not get any more responses.
 
 ### Contributing code
 

Makefile

@@ -35,6 +35,12 @@ profile:
 app:
 	python3 setup.py kitty.app $(VVAL)
 
+linux-package: FORCE
+	rm -rf linux-package
+	python3 setup.py linux-package
+
+FORCE:
+
 man:
 	$(MAKE) -C docs man
 

README.asciidoc

@@ -11,4 +11,4 @@ https://www.reddit.com/r/KittyTerminal[Reddit community]
 
 Packaging status in various repositories:
 
-image:https://repology.org/badge/vertical-allrepos/kitty.svg[https://repology.org/project/kitty/versions]
+image:https://repology.org/badge/vertical-allrepos/kitty.svg["Packaging status", link="https://repology.org/project/kitty/versions"]

__main__.py

@@ -1,169 +1,7 @@
 #!/usr/bin/env python3
 # License: GPL v3 Copyright: 2015, Kovid Goyal <kovid at kovidgoyal.net>
 
-import os
-import sys
-from typing import List
-
-
-def icat(args: List[str]) -> None:
-    from kittens.runner import run_kitten as rk
-    sys.argv = args
-    rk('icat')
-
-
-def list_fonts(args: List[str]) -> None:
-    from kitty.fonts.list import main as list_main
-    list_main(args)
-
-
-def remote_control(args: List[str]) -> None:
-    from kitty.remote_control import main as rc_main
-    rc_main(args)
-
-
-def runpy(args: List[str]) -> None:
-    if len(args) < 2:
-        raise SystemExit('Usage: kitty +runpy "some python code"')
-    sys.argv = ['kitty'] + args[2:]
-    exec(args[1])
-
-
-def hold(args: List[str]) -> None:
-    import subprocess
-    ret = subprocess.Popen(args[1:]).wait()
-    from kitty.utils import hold_till_enter
-    hold_till_enter()
-    raise SystemExit(ret)
-
-
-def complete(args: List[str]) -> None:
-    from kitty.complete import main as complete_main
-    complete_main(args[1:], entry_points, namespaced_entry_points)
-
-
-def launch(args: List[str]) -> None:
-    import runpy
-    sys.argv = args[1:]
-    try:
-        exe = args[1]
-    except IndexError:
-        raise SystemExit(
-            'usage: kitty +launch script.py [arguments to be passed to script.py ...]\n\n'
-            'script.py will be run with full access to kitty code. If script.py is '
-            'prefixed with a : it will be searched for in PATH'
-        )
-    if exe.startswith(':'):
-        import shutil
-        q = shutil.which(exe[1:])
-        if not q:
-            raise SystemExit(f'{exe[1:]} not found in PATH')
-        exe = q
-    if not os.path.exists(exe):
-        raise SystemExit(f'{exe} does not exist')
-    runpy.run_path(exe, run_name='__main__')
-
-
-def shebang(args: List[str]) -> None:
-    script_path = args[1]
-    cmd = args[2:]
-    if cmd == ['__ext__']:
-        cmd = [os.path.splitext(script_path)[1][1:].lower()]
-    try:
-        f = open(script_path)
-    except FileNotFoundError:
-        raise SystemExit(f'The file {script_path} does not exist')
-    with f:
-        if f.read(2) == '#!':
-            line = f.readline().strip()
-            _plat = sys.platform.lower()
-            is_macos: bool = 'darwin' in _plat
-            if is_macos:
-                cmd = line.split(' ')
-            else:
-                cmd = line.split(' ', maxsplit=1)
-    os.execvp(cmd[0], cmd + [script_path])
-
-
-def run_kitten(args: List[str]) -> None:
-    try:
-        kitten = args[1]
-    except IndexError:
-        from kittens.runner import list_kittens
-        list_kittens()
-        raise SystemExit(1)
-    sys.argv = args[1:]
-    from kittens.runner import run_kitten as rk
-    rk(kitten)
-
-
-def edit_config_file(args: List[str]) -> None:
-    from kitty.cli import create_default_opts
-    from kitty.fast_data_types import set_options
-    from kitty.utils import edit_config_file as f
-    set_options(create_default_opts())
-    f()
-
-
-def namespaced(args: List[str]) -> None:
-    try:
-        func = namespaced_entry_points[args[1]]
-    except KeyError:
-        pass
-    else:
-        func(args[1:])
-        return
-    raise SystemExit(f'{args[1]} is not a known entry point. Choices are: ' + ', '.join(namespaced_entry_points))
-
-
-entry_points = {
-    # These two are here for backwards compat
-    'icat': icat,
-    'list-fonts': list_fonts,
-
-    '@': remote_control,
-    '+': namespaced,
-}
-namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
-namespaced_entry_points['hold'] = hold
-namespaced_entry_points['complete'] = complete
-namespaced_entry_points['runpy'] = runpy
-namespaced_entry_points['launch'] = launch
-namespaced_entry_points['kitten'] = run_kitten
-namespaced_entry_points['edit-config'] = edit_config_file
-namespaced_entry_points['shebang'] = shebang
-
-
-def setup_openssl_environment() -> None:
-    # Use our bundled CA certificates instead of the system ones, since
-    # many systems come with no certificates in a useable form or have various
-    # locations for the certificates.
-    d = os.path.dirname
-    ext_dir: str = getattr(sys, 'kitty_extensions_dir')
-    if 'darwin' in sys.platform.lower():
-        cert_file = os.path.join(d(d(d(ext_dir))), 'cacert.pem')
-    else:
-        cert_file = os.path.join(d(ext_dir), 'cacert.pem')
-    os.environ['SSL_CERT_FILE'] = cert_file
-    setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_FILE')
-
-
-def main() -> None:
-    if getattr(sys, 'frozen', False) and getattr(sys, 'kitty_extensions_dir', ''):
-        setup_openssl_environment()
-    first_arg = '' if len(sys.argv) < 2 else sys.argv[1]
-    func = entry_points.get(first_arg)
-    if func is None:
-        if first_arg.startswith('@'):
-            remote_control(['@', first_arg[1:]] + sys.argv[2:])
-        elif first_arg.startswith('+'):
-            namespaced(['+', first_arg[1:]] + sys.argv[2:])
-        else:
-            from kitty.main import main as kitty_main
-            kitty_main()
-    else:
-        func(sys.argv[1:])
-
 
 if __name__ == '__main__':
+    from kitty.entry_points import main
     main()

build-terminfo

@@ -4,7 +4,6 @@
 
 import glob
 import os
-import re
 import shutil
 import subprocess
 import sys
@@ -13,11 +12,10 @@ import tempfile
 
 def compile_terminfo(base):
     with tempfile.TemporaryDirectory() as tdir:
-        proc = subprocess.run(['tic', '-x', f'-o{tdir}', 'terminfo/kitty.terminfo'], check=True, stderr=subprocess.PIPE)
+        proc = subprocess.run(['tic', '-x', f'-o{tdir}', 'terminfo/kitty.terminfo'], capture_output=True)
-        regex = '^"terminfo/kitty.terminfo", line [0-9]+, col [0-9]+, terminal \'xterm-kitty\': older tic versions may treat the description field as an alias$'
+        if proc.returncode != 0:
-        for error in proc.stderr.decode('utf-8').splitlines():
+            sys.stderr.buffer.write(proc.stderr)
-            if not re.match(regex, error):
+            raise SystemExit(proc.returncode)
-                print(error, file=sys.stderr)
         tfiles = glob.glob(os.path.join(tdir, '*', 'xterm-kitty'))
         if not tfiles:
             raise SystemExit('tic failed to output the compiled kitty terminfo file')
@@ -40,6 +38,13 @@ def generate_terminfo():
 
     with open('terminfo/kitty.terminfo', 'w') as f:
         f.write(generate_terminfo())
+    proc = subprocess.run(['tic', '-CrT0', 'terminfo/kitty.terminfo'], capture_output=True)
+    if proc.returncode != 0:
+        sys.stderr.buffer.write(proc.stderr)
+        raise SystemExit(proc.returncode)
+    tcap = proc.stdout.decode('utf-8').splitlines()[-1]
+    with open('terminfo/kitty.termcap', 'w') as f:
+        f.write(tcap)
 
     compile_terminfo(os.path.join(base, 'terminfo'))
 

bypy/init_env.py

@@ -11,9 +11,8 @@ import sys
 import tempfile
 from contextlib import suppress
 
-from bypy.constants import (
+from bypy.constants import LIBDIR, PREFIX, PYTHON, ismacos, worker_env
-    LIBDIR, PREFIX, PYTHON, SRC as KITTY_DIR, ismacos, worker_env
+from bypy.constants import SRC as KITTY_DIR
-)
 from bypy.utils import run_shell, walk
 
 
@@ -63,20 +62,31 @@ def build_frozen_launcher(extra_include_dirs):
 
 def run_tests(kitty_exe):
     with tempfile.TemporaryDirectory() as tdir:
-        env = {
+        uenv = {
             'KITTY_CONFIG_DIRECTORY': os.path.join(tdir, 'conf'),
             'KITTY_CACHE_DIRECTORY': os.path.join(tdir, 'cache')
         }
-        [os.mkdir(x) for x in env.values()]
+        [os.mkdir(x) for x in uenv.values()]
-        cmd = [kitty_exe, '+runpy', 'from kitty_tests.main import run_tests; run_tests()']
+        env = os.environ.copy()
+        env.update(uenv)
+        cmd = [kitty_exe, '+runpy', 'from kitty_tests.main import run_tests; run_tests(report_env=True)']
         print(*map(shlex.quote, cmd), flush=True)
-        if subprocess.call(cmd, env=env) != 0:
+        if subprocess.call(cmd, env=env, cwd=build_frozen_launcher.writeable_src_dir) != 0:
-            print('Checking of kitty build failed', file=sys.stderr)
+            print('Checking of kitty build failed, in directory:', build_frozen_launcher.writeable_src_dir, file=sys.stderr)
             os.chdir(os.path.dirname(kitty_exe))
             run_shell()
             raise SystemExit('Checking of kitty build failed')
 
 
+def build_frozen_tools(kitty_exe):
+    cmd = SETUP_CMD + ['--prefix', os.path.dirname(kitty_exe)] + ['build-frozen-tools']
+    if run(*cmd, cwd=build_frozen_launcher.writeable_src_dir) != 0:
+        print('Building of frozen kitten failed', file=sys.stderr)
+        os.chdir(KITTY_DIR)
+        run_shell()
+        raise SystemExit('Building of kitten launcher failed')
+
+
 def sanitize_source_folder(path: str) -> None:
     for q in walk(path):
         if os.path.splitext(q)[1] not in ('.py', '.glsl', '.ttf', '.otf'):
@@ -96,6 +106,8 @@ def build_c_extensions(ext_dir, args):
     cmd = SETUP_CMD + ['macos-freeze' if ismacos else 'linux-freeze']
     if args.dont_strip:
         cmd.append('--debug')
+    if args.extra_program_data:
+        cmd.append(f'--vcs-rev={args.extra_program_data}')
     dest = kitty_constants['appname'] + ('.app' if ismacos else '')
     dest = build_frozen_launcher.prefix = os.path.join(ext_dir, dest)
     cmd += ['--prefix', dest, '--full']

bypy/linux.conf

@@ -1,3 +1,3 @@
 image 'https://cloud-images.ubuntu.com/releases/bionic/release/ubuntu-18.04-server-cloudimg-{}.img'
 
-deps 'bison flex libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev libgl1-mesa-dev libxcb-xkb-dev libfontconfig1-dev libdbus-1-dev'
+deps 'bison flex libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev libgl1-mesa-dev libx11-xcb-dev libxcb-xkb-dev libfontconfig1-dev libdbus-1-dev'

bypy/linux/__main__.py

@@ -10,12 +10,8 @@ import subprocess
 import tarfile
 import time
 
-from bypy.constants import (
+from bypy.constants import OUTPUT_DIR, PREFIX, is64bit, python_major_minor_version
-    OUTPUT_DIR, PREFIX, is64bit, python_major_minor_version
+from bypy.freeze import extract_extension_modules, freeze_python, path_to_freeze_dir
-)
-from bypy.freeze import (
-    extract_extension_modules, freeze_python, path_to_freeze_dir
-)
 from bypy.utils import get_dll_path, mkdtemp, py_compile, walk
 
 j = os.path.join
@@ -35,7 +31,11 @@ def binary_includes():
             'expat', 'sqlite3', 'ffi', 'z', 'lzma', 'png16', 'lcms2', 'crypt',
             'iconv', 'pcre', 'graphite2', 'glib-2.0', 'freetype', 'rsync',
             'harfbuzz', 'xkbcommon', 'xkbcommon-x11',
-            'ncursesw', 'readline', 'brotlicommon', 'brotlienc', 'brotlidec'
+            # fontconfig is not bundled because in typical brain dead Linux
+            # distro fashion, different distros use different default config
+            # paths for fontconfig.
+            'ncursesw', 'readline', 'brotlicommon', 'brotlienc', 'brotlidec',
+            'wayland-client', 'wayland-cursor',
         ))) + (
                 get_dll_path('bz2', 2), get_dll_path('ssl', 2), get_dll_path('crypto', 2),
                 get_dll_path(f'python{py_ver}', 2),
@@ -139,6 +139,7 @@ def copy_python(env):
         iv['sanitize_source_folder'](os.path.join(env.py_dir, x))
     py_compile(env.py_dir)
     freeze_python(env.py_dir, pdir, env.obj_dir, ext_map, develop_mode_env_var='KITTY_DEVELOP_FROM', remove_pyc_files=True)
+    shutil.rmtree(env.py_dir)
 
 
 def build_launcher(env):
@@ -215,7 +216,7 @@ def create_tarfile(env, compression_level='9'):
     print('Compressing archive...')
     ans = f'{dist.rpartition(".")[0]}.txz'
     start_time = time.time()
-    subprocess.check_call(['xz', '--threads=0', '-f', f'-{compression_level}', dist])
+    subprocess.check_call(['xz', '--verbose', '--threads=0', '-f', f'-{compression_level}', dist])
     secs = time.time() - start_time
     print('Compressed in {} minutes {} seconds'.format(secs // 60, secs % 60))
     os.rename(f'{dist}.xz', ans)
@@ -233,10 +234,12 @@ def main():
     files = find_binaries(env)
     fix_permissions(files)
     add_ca_certs(env)
+    kitty_exe = os.path.join(env.base, 'bin', 'kitty')
+    iv['build_frozen_tools'](kitty_exe)
     if not args.dont_strip:
         strip_binaries(files)
     if not args.skip_tests:
-        iv['run_tests'](os.path.join(env.base, 'bin', 'kitty'))
+        iv['run_tests'](kitty_exe)
     create_tarfile(env, args.compression_level)
 
 

bypy/macos.conf

@@ -1,4 +1,4 @@
-# Requires installation of XCode 10.3 and Python 3 and
+# Requires installation of XCode 10.3 and go 1.19 and Python 3 and
 # python3 -m pip install certifi
 
 vm_name 'macos-kitty'

bypy/macos/__main__.py

@@ -13,16 +13,9 @@ import tempfile
 import zipfile
 
 from bypy.constants import PREFIX, PYTHON, SW, python_major_minor_version
-from bypy.freeze import (
+from bypy.freeze import extract_extension_modules, freeze_python, path_to_freeze_dir
-    extract_extension_modules, freeze_python, path_to_freeze_dir
+from bypy.macos_sign import codesign, create_entitlements_file, make_certificate_useable, notarize_app, verify_signature
-)
+from bypy.utils import current_dir, mkdtemp, py_compile, run_shell, timeit, walk
-from bypy.macos_sign import (
-    codesign, create_entitlements_file, make_certificate_useable, notarize_app,
-    verify_signature
-)
-from bypy.utils import (
-    current_dir, mkdtemp, py_compile, run_shell, timeit, walk
-)
 
 iv = globals()['init_env']
 kitty_constants = iv['kitty_constants']
@@ -113,6 +106,9 @@ def do_sign(app_dir):
             codesign(fw)
             items = set(os.listdir('.')) - fw
             codesign(expand_dirs(items))
+        # Sign kitten
+        with current_dir('MacOS'):
+            codesign('kitten')
 
     # Now sign the main app
     codesign(app_dir)
@@ -171,6 +167,7 @@ class Freeze(object):
         self.add_misc_libraries()
         self.freeze_python()
         self.add_ca_certs()
+        self.build_frozen_tools()
         if not self.dont_strip:
             self.strip_files()
         if not self.skip_tests:
@@ -185,7 +182,16 @@ class Freeze(object):
     def add_ca_certs(self):
         print('\nDownloading CA certs...')
         from urllib.request import urlopen
-        cdata = urlopen(kitty_constants['cacerts_url']).read()
+        cdata = None
+        for i in range(5):
+            try:
+                cdata = urlopen(kitty_constants['cacerts_url']).read()
+                break
+            except Exception as e:
+                print(f'Downloading CA certs failed with error: {e}, retrying...')
+
+        if cdata is None:
+            raise SystemExit('Downloading C certs failed, giving up')
         dest = join(self.contents_dir, 'Resources', 'cacert.pem')
         with open(dest, 'wb') as f:
             f.write(cdata)
@@ -360,6 +366,7 @@ class Freeze(object):
             iv['sanitize_source_folder'](join(self.python_stdlib, x))
         self.compile_py_modules()
         freeze_python(self.python_stdlib, pdir, self.obj_dir, ext_map, develop_mode_env_var='KITTY_DEVELOP_FROM', remove_pyc_files=True)
+        shutil.rmtree(self.python_stdlib)
         iv['build_frozen_launcher']([path_to_freeze_dir(), self.obj_dir])
         os.rename(join(dirname(self.contents_dir), 'bin', 'kitty'), join(self.contents_dir, 'MacOS', 'kitty'))
         shutil.rmtree(join(dirname(self.contents_dir), 'bin'))
@@ -368,6 +375,10 @@ class Freeze(object):
             if f.endswith('.so') or f.endswith('.dylib'):
                 self.fix_dependencies_in_lib(f)
 
+    @flush
+    def build_frozen_tools(self):
+        iv['build_frozen_tools'](join(self.contents_dir, 'MacOS', 'kitty'))
+
     @flush
     def add_site_packages(self):
         print('\nAdding site-packages')

bypy/rsync.conf

@@ -1 +1 @@
-to_vm_excludes '/build /dist /kitty/launcher/kitty /.build-cache /tags __pycache__ /*_commands.json *.so *.pyd *.pyc'
+to_vm_excludes '/build /dist /kitty/launcher/kitty* /.build-cache /tags __pycache__ /*_commands.json *.so *.pyd *.pyc *_generated.go'

bypy/sources.json

@@ -2,8 +2,8 @@
     {
         "name": "zlib",
         "unix": {
-            "filename": "zlib-1.2.11.tar.xz",
+            "filename": "zlib-1.2.13.tar.xz",
-            "hash": "sha256:4ff941449631ace0d4d203e3483be9dbc9da454084111f97ea0a2114e19bf066",
+            "hash": "sha256:d14c38e313afc35a9a8760dadf26042f51ea0f5d154b0630a31da0540107fb98",
             "urls": ["https://zlib.net/{filename}"]
         }
     },
@@ -163,15 +163,6 @@
         }
     },
 
-    {
-        "name": "pygments",
-        "unix": {
-            "filename": "Pygments-2.7.4.tar.gz",
-            "hash": "sha256:df49d09b498e83c1a73128295860250b0b7edd4c723a32e9bc0d295c7c2ec337",
-            "urls": ["pypi"]
-        }
-    },
-
     {
         "name": "libpng",
         "unix": {
@@ -273,8 +264,8 @@
         "name": "wayland",
         "os": "linux",
         "unix": {
-            "filename": "wayland-1.19.0.tar.xz",
+            "filename": "wayland-1.20.0.tar.xz",
-            "hash": "sha256:baccd902300d354581cd5ad3cc49daa4921d55fb416a5883e218750fef166d15",
+            "hash": "sha256:b8a034154c7059772e0fdbd27dbfcda6c732df29cae56a82274f6ec5d7cd8725",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     },
@@ -283,8 +274,8 @@
         "name": "wayland-protocols",
         "os": "linux",
         "unix": {
-            "filename": "wayland-protocols-1.20.tar.xz",
+            "filename": "wayland-protocols-1.25.tar.xz",
-            "hash": "sha256:9782b7a1a863d82d7c92478497d13c758f52e7da4f197aa16443f73de77e4de7",
+            "hash": "sha256:f1ff0f7199d0a0da337217dd8c99979967808dc37731a1e759e822b75b571460",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     }

count-lines-of-code

@@ -2,29 +2,20 @@
 
 import subprocess
 
-files_to_exclude = '''\
+ignored = []
-kitty/wcwidth-std.h
+for line in subprocess.check_output(['git', 'status', '--ignored', '--porcelain']).decode().splitlines():
-kitty/charsets.c
+    if line.startswith('!! '):
-kitty/unicode-data.c
+        ignored.append(line[3:])
-kitty/key_encoding.py
+files_to_exclude = '\n'.join(ignored)
-kitty/rgb.py
+
-kitty/gl.h
+cp = subprocess.run(['git', 'check-attr', 'linguist-generated', '--stdin'],
-kitty/gl-wrapper.h
+                    check=True, stdout=subprocess.PIPE, input=subprocess.check_output([ 'git', 'ls-files']))
-kitty/gl-wrapper.c
+for line in cp.stdout.decode().splitlines():
-kitty/glfw-wrapper.h
+    if line.endswith(' true'):
-kitty/glfw-wrapper.c
+        files_to_exclude += '\n' + line.split(':')[0]
-kitty/emoji.h
-kittens/unicode_input/names.h
-kitty/parse-graphics-command.h
-kitty/options/types.py
-kitty/options/parse.py
-kitty/options/to-c-generated.h
-kittens/diff/options/types.py
-kittens/diff/options/parse.py
-'''
 
 p = subprocess.Popen([
-    'cloc', '--exclude-list-file', '/dev/stdin', 'kitty', 'kittens'
+    'cloc', '--exclude-list-file', '/dev/stdin', 'kitty', 'kittens', 'tools', 'kitty_tests', 'docs',
 ], stdin=subprocess.PIPE)
 p.communicate(files_to_exclude.encode('utf-8'))
 raise SystemExit(p.wait())

docs/_static/custom.css

@@ -10,7 +10,7 @@
 }
 
 .sidebar-logo {
-    max-height: 128px;
+    height: 128px;
 }
 
 .major-features li {

docs/_templates/base.html

@@ -4,18 +4,14 @@
   {{ super() }}
 
   {%- if analytics_id %}
-      <script type="text/javascript">
+  <!-- Global site tag (gtag.js) - Google Analytics -->
-      var _gaq = _gaq || [];
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ analytics_id }}"></script>
-      _gaq.push(['_setAccount', '{{ analytics_id }}']);
+    <script>
-      _gaq.push(['_setDomainName', 'none']);
+        window.dataLayer = window.dataLayer || [];
-      _gaq.push(['_setAllowLinker', true]);
+        function gtag(){dataLayer.push(arguments);}
-      _gaq.push(['_trackPageview']);
+        gtag('js', new Date());
 
-      (function() {
+        gtag('config', '{{ analytics_id }}');
-        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-      })();
     </script>
   {% endif -%}
 

docs/basic.rst

@@ -1,12 +1,13 @@
 Tabs and Windows
 -------------------
 
-|kitty| is capable of running multiple programs organized into tabs and
+|kitty| is capable of running multiple programs organized into tabs and windows.
-windows. The top level of organization is the *Tab*. Each tab consists
+The top level of organization is the :term:`OS window <os_window>`. Each OS
-of one or more *windows*. The windows can be arranged in multiple
+window consists of one or more :term:`tabs <tab>`. Each tab consists of one or more
-different layouts, like windows are organized in a tiling window
+:term:`kitty windows <window>`. The kitty windows can be arranged in multiple
-manager. The keyboard controls (which are all customizable) for tabs and
+different :term:`layouts <layout>`, like windows are organized in a tiling
-windows are:
+window manager. The keyboard controls (which are :ref:`all customizable
+<conf-kitty-shortcuts>`) for tabs and windows are:
 
 Scrolling
 ~~~~~~~~~~~~~~
@@ -26,6 +27,11 @@ Browse scrollback in less   :sc:`show_scrollback`
 Browse last cmd output      :sc:`show_last_command_output` (see :ref:`shell_integration`)
 =========================   =======================
 
+The scroll actions only take effect when the terminal is in the main screen.
+When the alternate screen is active (for example when using a full screen
+program like an editor) the key events are instead passed to program running in the
+terminal.
+
 Tabs
 ~~~~~~~~~~~
 
@@ -52,6 +58,7 @@ Action                      Shortcut
 New window                  :sc:`new_window` (also :kbd:`⌘+↩` on macOS)
 New OS window               :sc:`new_os_window` (also :kbd:`⌘+n` on macOS)
 Close window                :sc:`close_window` (also :kbd:`⇧+⌘+d` on macOS)
+Resize window               :sc:`start_resizing_window` (also :kbd:`⌘+r` on macOS)
 Next window                 :sc:`next_window`
 Previous window             :sc:`previous_window`
 Move window forward         :sc:`move_window_forward`
@@ -64,8 +71,9 @@ Focus specific window       :sc:`first_window`, :sc:`second_window` ... :sc:`ten
                             (clockwise from the top-left)
 ========================    =======================
 
-Additionally, you can define shortcuts in :file:`kitty.conf` to focus neighboring
+Additionally, you can define shortcuts in :file:`kitty.conf` to focus
-windows and move windows around (similar to window movement in vim)::
+neighboring windows and move windows around (similar to window movement in
+:program:`vim`)::
 
    map ctrl+left neighboring_window left
    map shift+left move_window right
@@ -77,20 +85,20 @@ You can also define a shortcut to switch to the previously active window::
 
    map ctrl+p nth_window -1
 
-``nth_window`` will focus the nth window for positive numbers (starting from
+:ac:`nth_window` will focus the nth window for positive numbers (starting from
 zero) and the previously active windows for negative numbers.
 
-To switch to the nth OS window, you can define ``nth_os_window``. Only positive
+To switch to the nth OS window, you can define :ac:`nth_os_window`. Only
-numbers are accepted, starting from one.
+positive numbers are accepted, starting from one.
 
 .. _detach_window:
 
-You can define shortcuts to detach the current window and
+You can define shortcuts to detach the current window and move it to another tab
-move it to another tab or another OS window::
+or another OS window::
 
     # moves the window into a new OS window
     map ctrl+f2 detach_window
-    # moves the window into a new Tab
+    # moves the window into a new tab
     map ctrl+f3 detach_window new-tab
     # moves the window into the previously active tab
     map ctrl+f3 detach_window tab-prev
@@ -106,8 +114,8 @@ Similarly, you can detach the current tab, with::
     # asks which OS Window to move the tab into
     map ctrl+f4 detach_tab ask
 
-Finally, you can define a shortcut to close all windows in a tab other than
+Finally, you can define a shortcut to close all windows in a tab other than the
-the currently active window::
+currently active window::
 
     map f9 close_other_windows_in_tab
 
@@ -121,21 +129,22 @@ The full list of actions that can be mapped to key presses is available
 ==================================  =======================
 Action                              Shortcut
 ==================================  =======================
+Show this help                      :sc:`show_kitty_doc`
 Copy to clipboard                   :sc:`copy_to_clipboard` (also :kbd:`⌘+c` on macOS)
 Paste from clipboard                :sc:`paste_from_clipboard` (also :kbd:`⌘+v` on macOS)
 Paste from selection                :sc:`paste_from_selection`
+Pass selection to program           :sc:`pass_selection_to_program`
 Increase font size                  :sc:`increase_font_size` (also :kbd:`⌘++` on macOS)
 Decrease font size                  :sc:`decrease_font_size` (also :kbd:`⌘+-` on macOS)
 Restore font size                   :sc:`reset_font_size` (also :kbd:`⌘+0` on macOS)
 Toggle fullscreen                   :sc:`toggle_fullscreen` (also :kbd:`⌃+⌘+f` on macOS)
 Toggle maximized                    :sc:`toggle_maximized`
-Input unicode character             :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
+Input Unicode character             :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
 Open URL in web browser             :sc:`open_url`
 Reset the terminal                  :sc:`reset_terminal` (also :kbd:`⌥+⌘+r` on macOS)
+Edit :file:`kitty.conf`             :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
 Reload :file:`kitty.conf`           :sc:`reload_config_file` (also :kbd:`⌃+⌘+,` on macOS)
 Debug :file:`kitty.conf`            :sc:`debug_config` (also :kbd:`⌥+⌘+,` on macOS)
-Pass current selection to program   :sc:`pass_selection_to_program`
-Edit |kitty| config file            :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
 Open a |kitty| shell                :sc:`kitty_shell`
 Increase background opacity         :sc:`increase_background_opacity`
 Decrease background opacity         :sc:`decrease_background_opacity`

docs/binary.rst

@@ -4,17 +4,14 @@ Install kitty
 Binary install
 ----------------
 
-.. |ins| replace:: curl -L :literal:`https://sw.kovidgoyal.net/kitty/installer.sh` | sh /dev/stdin
-
 .. highlight:: sh
 
 You can install pre-built binaries of |kitty| if you are on macOS or Linux using
 the following simple command:
 
-.. parsed-literal::
+.. code-block:: sh
-    :class: pre
 
-    |ins|
+    _kitty_install_cmd
 
 
 The binaries will be installed in the standard location for your OS,
@@ -24,8 +21,9 @@ simply re-run the command.
 
 .. warning::
    **Do not** copy the kitty binary out of the installation folder. If you want
-   to add it to your ``PATH`` create a symlink in :file:`~/.local/bin` or
+   to add it to your :envvar:`PATH`, create a symlink in :file:`~/.local/bin` or
-   :file:`/usr/bin` or wherever.
+   :file:`/usr/bin` or wherever. You should create a symlink for the :file:`kitten`
+   binary as well.
 
 
 Manually installing
@@ -33,11 +31,12 @@ Manually installing
 
 If something goes wrong or you simply do not want to run the installer, you can
 manually download and install |kitty| from the `GitHub releases page
-<https://github.com/kovidgoyal/kitty/releases>`_. If you are on macOS, download
+<https://github.com/kovidgoyal/kitty/releases>`__. If you are on macOS, download
-the :file:`.dmg` and install as normal. If you are on Linux, download the tarball
+the :file:`.dmg` and install as normal. If you are on Linux, download the
-and extract it into a directory. The |kitty| executable will be in the
+tarball and extract it into a directory. The |kitty| executable will be in the
 :file:`bin` sub-directory.
 
+
 Desktop integration on Linux
 --------------------------------
 
@@ -48,18 +47,31 @@ particular desktop, but it should work for most major desktop environments.
 
 .. code-block:: sh
 
-    # Create a symbolic link to add kitty to PATH (assuming ~/.local/bin is in
+    # Create symbolic links to add kitty and kitten to PATH (assuming ~/.local/bin is in
-    # your PATH)
+    # your system-wide PATH)
-    ln -s ~/.local/kitty.app/bin/kitty ~/.local/bin/
+    ln -sf ~/.local/kitty.app/bin/kitty ~/.local/kitty.app/bin/kitten ~/.local/bin/
     # Place the kitty.desktop file somewhere it can be found by the OS
     cp ~/.local/kitty.app/share/applications/kitty.desktop ~/.local/share/applications/
-    # Update the path to the kitty icon in the kitty.desktop file
+    # If you want to open text files and images in kitty via your file manager also add the kitty-open.desktop file
-    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty.desktop
+    cp ~/.local/kitty.app/share/applications/kitty-open.desktop ~/.local/share/applications/
+    # Update the paths to the kitty and its icon in the kitty.desktop file(s)
+    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty*.desktop
+    sed -i "s|Exec=kitty|Exec=/home/$USER/.local/kitty.app/bin/kitty|g" ~/.local/share/applications/kitty*.desktop
 
 .. note::
-    If you use the venerable `stow <https://www.gnu.org/software/stow/>`_
+    In :file:`kitty-open.desktop`, kitty is registered to handle some supported
+    MIME types. This will cause kitty to take precedence on some systems where
+    the default apps are not explicitly set. For example, you expect to use
+    other GUI file managers to open dir paths when using commands such as
+    :program:`xdg-open`, you should configure the default opener for the MIME
+    type ``inode/directory``::
+
+        xdg-mime default org.kde.dolphin.desktop inode/directory
+
+.. note::
+    If you use the venerable `stow <https://www.gnu.org/software/stow/>`__
     command to manage your manual installations, the following takes care of the
-    above for you (use with :file:`dest=~/.local/stow`)::
+    above for you (use with :code:`dest=~/.local/stow`)::
 
         cd ~/.local/stow
         stow -v kitty.app
@@ -72,44 +84,39 @@ Customizing the installation
 
 * You can install the latest nightly kitty build with ``installer``:
 
-  .. parsed-literal::
+  .. code-block:: sh
-     :class: pre
 
-     |ins| \\
+     _kitty_install_cmd \
          installer=nightly
 
   If you want to install it in parallel to the released kitty specify a
   different install locations with ``dest``:
 
-  .. parsed-literal::
+  .. code-block:: sh
-     :class: pre
 
-     |ins| \\
+     _kitty_install_cmd \
          installer=nightly dest=/some/other/location
 
 * You can specify a different install location, with ``dest``:
 
-  .. parsed-literal::
+  .. code-block:: sh
-     :class: pre
 
-     |ins| \\
+     _kitty_install_cmd \
          dest=/some/other/location
 
 * You can tell the installer not to launch |kitty| after installing it with
   ``launch=n``:
 
-  .. parsed-literal::
+  .. code-block:: sh
-     :class: pre
 
-     |ins| \\
+     _kitty_install_cmd \
          launch=n
 
 * You can use a previously downloaded dmg/tarball, with ``installer``:
 
-  .. parsed-literal::
+  .. code-block:: sh
-     :class: pre
 
-     |ins| \\
+     _kitty_install_cmd \
          installer=/path/to/dmg or tarball
 
 

docs/build.rst

@@ -7,21 +7,21 @@ Build from source
 
 .. highlight:: sh
 
-|kitty| is designed to run from source, for easy hack-ability. Make sure
+|kitty| is designed to run from source, for easy hack-ability. Make sure the
-the following dependencies are installed first.
+following dependencies are installed first.
 
 .. note::
-   If you just want to test the latest changes to kitty you dont need to build
+   If you just want to test the latest changes to kitty, you don't need to build
    from source. Instead install the :ref:`latest nightly build <nightly>`.
 
 .. note::
-   If you are making small changes only to the python parts of kitty, there is no need to
+   If you are making small changes only to the Python parts of kitty, there is
-   build kitty at all, instead, assuming you have installed the official kitty
+   no need to build kitty at all, instead, assuming you have installed the
-   binaries, you can simply set the KITTY_DEVELOP_FROM enviroment variable to
+   official kitty binaries, you can simply set the :envvar:`KITTY_DEVELOP_FROM`
-   point to the directory into which you have checked out the kitty source
+   enviroment variable to point to the directory into which you have checked out
-   code. kitty will then load its python code from there. You should use a
+   the kitty source code. kitty will then load its Python code from there. You
-   version of the source that matches the binary version as closely as
+   should use a version of the source that matches the binary version as closely
-   possible, since the two are tightly coupled.
+   as possible, since the two are tightly coupled.
 
 
 Dependencies
@@ -29,24 +29,27 @@ Dependencies
 
 Run-time dependencies:
 
-* ``python`` >= 3.6
+* ``python`` >= 3.8
 * ``harfbuzz`` >= 2.2.0
 * ``zlib``
 * ``libpng``
 * ``liblcms2``
 * ``librsync``
+* ``openssl``
 * ``freetype`` (not needed on macOS)
 * ``fontconfig`` (not needed on macOS)
 * ``libcanberra`` (not needed on macOS)
-* ``ImageMagick`` (optional, needed to use the ``kitty +kitten icat`` tool to display images in the terminal)
+* ``ImageMagick`` (optional, needed to display uncommon image formats in the terminal)
-* ``pygments`` (optional, needed for syntax highlighting in ``kitty +kitten diff``)
 
 
 Build-time dependencies:
 
 * ``gcc`` or ``clang``
+* ``go`` >= _build_go_version (see :file:`go.mod` for go packages used during building)
 * ``pkg-config``
-* For building on Linux in addition to the above dependencies you might also need to install the following packages, if they are not already installed by your distro:
+* For building on Linux in addition to the above dependencies you might also
+  need to install the following packages, if they are not already installed by
+  your distro:
 
   - ``libdbus-1-dev``
   - ``libxcursor-dev``
@@ -58,6 +61,7 @@ Build-time dependencies:
   - ``libfontconfig-dev``
   - ``libx11-xcb-dev``
   - ``liblcms2-dev``
+  - ``libssl-dev``
   - ``libpython3-dev``
   - ``librsync-dev``
 
@@ -77,9 +81,12 @@ You can run |kitty|, as::
 
     ./kitty/launcher/kitty
 
-If that works, you can create a symlink to the launcher in :file:`~/bin` or
+If that works, you can create a symlink to the launcher in :file:`~/bin` or some
-some other directory on your PATH so that you can run |kitty| using
+other directory on your PATH so that you can run |kitty| using just ``kitty``.
-just ``kitty``.
+
+To have the kitty documentation available locally, run::
+
+    python3 -m pip install -r docs/requirements.txt && make docs
 
 
 Building kitty.app on macOS from source
@@ -87,28 +94,30 @@ Building kitty.app on macOS from source
 
 Run::
 
+    python3 -m pip install -r docs/requirements.txt && make docs
     make app
 
+Building the docs needs to be done only once.
+
 This :file:`kitty.app` unlike the released one does not include its own copy of
-python and the other dependencies. So if you ever un-install/upgrade those dependencies
+Python and the other dependencies. So if you ever un-install/upgrade those
-you might have to rebuild the app.
+dependencies you might have to rebuild the app.
 
 .. note::
    The released :file:`kitty.dmg` includes all dependencies, unlike the
    :file:`kitty.app` built above and is built automatically by using the
-   `bypy framework <https://github.com/kovidgoyal/bypy>`_ however, that is
+   `bypy framework <https://github.com/kovidgoyal/bypy>`__ however, that is
    designed to run on Linux and is not for the faint of heart.
 
 .. note::
-   Apple disallows certain functionality, such as notifications for unsigned applications.
+   Apple disallows certain functionality, such as notifications for unsigned
-   If you need this functionality, you can try signing the built kitty.app with
+   applications. If you need this functionality, you can try signing the built
-   a self signed certificate, see for example, `here
+   :file:`kitty.app` with a self signed certificate, see for example, `here
-   <https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`_.
+   <https://stackoverflow.com/questions/27474751/how-can-i-codesign-an-app-without-being-in-the-mac-developer-program/27474942>`__.
 
 .. note::
-   If you are facing issues with ``linker`` while building,
+   If you are facing issues with ``linker`` while building, try with a ``brew``
-   try with a ``brew`` installed python instead, see :iss:`289`
+   installed Python instead, see :iss:`289` for more discussion.
-   for more discussion.
 
 
 Build and run from source with Nix
@@ -116,89 +125,78 @@ Build and run from source with Nix
 
 On NixOS or any other Linux or macOS system with the Nix package manager
 installed, execute `nix-shell
-<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`_ to create
+<https://nixos.org/guides/nix-pills/developing-with-nix-shell.html>`__ to create
 the correct environment to build kitty or use ``nix-shell --pure`` instead to
 eliminate most of the influence of the outside system, e.g. globally installed
 packages. ``nix-shell`` will automatically fetch all required dependencies and
 make them available in the newly spawned shell.
 
-Then proceed with ``make`` or ``make app`` according to the platform specific instructions above.
+Then proceed with ``make`` or ``make app`` according to the platform specific
+instructions above.
 
 
+Debug builds
+--------------
+
+A basic debug build can be done with::
+
+    make debug
+
+This includes debug info in the binary for better traces. To build with address
+sanitizer, use::
+
+    make asan
+
+Which will result in a debug binary that uses the address sanitizer as well.
+
 .. _packagers:
 
 Notes for Linux/macOS packagers
 ----------------------------------
 
 The released |kitty| source code is available as a `tarball`_ from
-`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`_.
+`the GitHub releases page <https://github.com/kovidgoyal/kitty/releases>`__.
 
-While |kitty| does use python, it is not a traditional python package, so please
+While |kitty| does use Python, it is not a traditional Python package, so please
 do not install it in site-packages.
 Instead run::
 
-    python3 setup.py linux-package
+    make linux-package
 
-This will install |kitty| into the directory :file:`linux-package`. You can run |kitty|
+This will install |kitty| into the directory :file:`linux-package`. You can run
-with :file:`linux-package/bin/kitty`.  All the files needed to run kitty will be in
+|kitty| with :file:`linux-package/bin/kitty`. All the files needed to run kitty
-:file:`linux-package/lib/kitty`. The terminfo file will be installed into
+will be in :file:`linux-package/lib/kitty`. The terminfo file will be installed
-:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
+into :file:`linux-package/share/terminfo`. Simply copy these files into
-|kitty|. In other words, :file:`linux-package` is the staging area into which |kitty| is
+:file:`/usr` to install |kitty|. In other words, :file:`linux-package` is the
-installed. You can choose a different staging area, by passing the ``--prefix``
+staging area into which |kitty| is installed. You can choose a different staging
-argument to :file:`setup.py`.
+area, by passing the ``--prefix`` argument to :file:`setup.py`.
 
 You should probably split |kitty| into three packages:
 
 :code:`kitty-terminfo`
-    installs the terminfo file
+    Installs the terminfo file
 
 :code:`kitty-shell-integration`
-    installs the shell integration scripts (the contents of the
+    Installs the shell integration scripts (the contents of the
-    shell-integration directory in the kitty source code, probably to
+    shell-integration directory in the kitty source code), probably to
     :file:`/usr/share/kitty/shell-integration`
 
 :code:`kitty`
-    installs the main program
+    Installs the main program
 
 This allows users to install the terminfo and shell integration files on
-servers into which they ssh, without needing to install all of |kitty|.
+servers into which they ssh, without needing to install all of |kitty|. The
+shell integration files **must** still be present in
+:file:`lib/kitty/shell-integration` when installing the kitty main package as
+the kitty program expects to find them there.
 
 .. note::
-   You need a couple of extra dependencies to build linux-package.
+   You need a couple of extra dependencies to build linux-package. :file:`tic`
-   :file:`tic` to compile terminfo files, usually found in the
+   to compile terminfo files, usually found in the development package of
-   development package of :file:`ncurses`. Also, if you are building from
+   :file:`ncurses`. Also, if you are building from a git checkout instead of the
-   a git checkout instead of the released source code tarball, you will
+   released source code tarball, you will need to install the dependencies from
-   need to install the dependencies from ``docs/requirements.txt`` to
+   :file:`docs/requirements.txt` to build the kitty documentation. They can be
-   build the kitty documentation. They can be installed most easily with
+   installed most easily with ``python -m pip -r docs/requirements.txt``.
-   ``python -m pip -r docs/requirements.txt``.
 
 This applies to creating packages for |kitty| for macOS package managers such as
-brew or MacPorts as well.
+Homebrew or MacPorts as well.
-
-
-Changing defaults for packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-|kitty| has its defaults chosen to be suitable for a standalone distributable.
-If you are packaging it a few of these might need to be changed.
-
-update-checking
-   |kitty| has its own update check mechanism, if you would like to turn
-   it off for your package, use::
-
-       ./setup.py linux-package --update-check-interval=0
-
-shell-integration
-   |kitty| by default injects its :ref:`shell_integration` code into the user's
-   shell using environment variables or (for bash only) modifying
-   the user's :file:`~/.bashrc` file.
-   For a package, it might make more sense to distribute the shell
-   integration scripts into the system-wide shell vendor locations. The
-   shell integration files are found in the :file:`shell-integration`
-   directory. Copy them to the system wide shell vendor locations for each
-   shell, and use::
-
-       ./setup.py linux-package --shell-integration=enabled\ no-rc
-
-   This will prevent kitty from modifying the user's shell environment to load
-   the integration scripts.

docs/changelog.rst

@@ -9,23 +9,15 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 Recent major new features
 ---------------------------
 
-.. only:: dirhtml
+Truly convenient SSH
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-   A demo video
+The :doc:`ssh kitten <kittens/ssh>` is redesigned with powerful new features:
-   ~~~~~~~~~~~~~~~~
 
-   A new video showcasing some of kitty's many productivity enhancing features.
+* Automatic :ref:`shell_integration` on remote machines
-
+* Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote machines
-   .. raw:: html
+* Easily :ref:`edit files in your local editor <edit_file>` on remote machines
-
+* Automatic :opt:`re-use of existing connections <kitten-ssh.share_connections>` to avoid connection setup latency
-        <video controls width="640" height="360" poster="../_static/poster.png">
-            <source src="https://download.calibre-ebook.com/videos/kitty.mp4" type="video/mp4">
-            <source src="https://download.calibre-ebook.com/videos/kitty.webm" type="video/webm">
-        </video>
-
-   .. rst-class:: caption caption-text
-
-       Watch kitty in action!
 
 
 Shell integration
@@ -38,43 +30,613 @@ scrollback by pressing :sc:`scroll_to_previous_prompt` and clicking with the
 mouse anywhere in the current command to move the cursor there. See
 :doc:`shell-integration` for details.
 
-Logos for windows
-~~~~~~~~~~~~~~~~~~~~
-
-kitty has the ability to display arbitrary ``PNG`` images at the corner
-of any kitty window to serve as a *logo* for quick window identification.
-Can be controlled via :opt:`window_logo_path` and also and changed via
-the :ref:`at_set-window-logo` remote control command.
-Useful to quickly identify special windows or just for some *bling*.
-
-.. figure:: screenshots/window-logo.png
-    :alt: A screenshot of the kitty shell window showing the kitty logo
-    :align: center
-    :width: 100%
-
-    A screenshot of the kitty shell window showing the kitty logo
-
-
-Visual keyboard based window select
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Select a kitty window visually using the keyboard, like the
-:doc:`kittens/hints`, but for kitty windows. Can also be used from shell
-scripts/third party integrations via the :ref:`at_select-window` remote control
-command.
-
-.. figure:: screenshots/select-window.png
-    :alt: A screenshot of the kitty select window function
-    :align: center
-    :width: 100%
-
-    Hints for selecting kitty windows visually
-
 .. }}}
 
 Detailed list of changes
 -------------------------------------
 
+0.28.2 [future]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A new escape code ``<ESC>[22J`` that moves the current contents of the screen into the scrollback before clearing it
+
+- unicode_input kitten: Fix a regression in 0.28.0 that caused the order of recent and favorites entries to not be respected (:iss:`6214`)
+
+- unicode_input kitten: Fix a regression in 0.28.0 that caused editing of favorites to sometimes hang
+
+- clipboard kitten: Fix a bug causing the last MIME type available on the clipboard not being recognized when pasting
+
+- Fix regression in 0.28.0 causing color fringing when rendering in transparent windows on light backgrounds (:iss:`6209`)
+
+- show_key kitten: In kitty mode show the actual bytes sent by the terminal rather than a re-encoding of the parsed key event
+
+- hints kitten: Fix a regression in 0.28.0 that broke using sub-groups in regexp captures (:iss:`6228`)
+
+- hints kitten: Fix a regression in 0.28.0 that broke using lookahead/lookbehind in regexp captures (:iss:`6265`)
+
+- diff kitten: Fix a regression in 0.28.0 that broke using relative paths as arguments to the kitten (:iss:`6325`)
+
+- Fix re-using the image id of an animated image for a still image causing a crash (:iss:`6244`)
+
+- kitty +open: Ask for permission before executing script files that are not marked as executable. This prevents accidental execution
+  of script files via MIME type association from programs that unconditionally "open" attachments/downloaded files
+
+- edit-in-kitty: Fix running edit-in-kitty with elevated privileges to edit a restricted file not working (:disc:`6245`)
+
+- ssh kitten: Fix a regression in 0.28.0 that caused interrupt during setup to not be handled gracefully (:iss:`6254`)
+
+0.28.1 [2023-04-21]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Fix a regression in the previous release that broke the remote file kitten (:iss:`6186`)
+
+- Fix a regression in the previous release that broke handling of some keyboard shortcuts in some kittens on some keyboard layouts (:iss:`6189`)
+
+- Fix a regression in the previous release that broke usage of custom themes (:iss:`6191`)
+
+0.28.0 [2023-04-15]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Text rendering change**: Use sRGB correct linear gamma blending for nicer font
+  rendering and better color accuracy with transparent windows.
+  See the option :opt:`text_composition_strategy` for details.
+  The obsolete :opt:`macos_thicken_font` will make the font too thick and needs to be removed manually
+  if it is configured. (:pull:`5969`)
+
+- icat kitten: Support display of images inside tmux >= 3.3 (:pull:`5664`)
+
+- Graphics protocol: Add support for displaying images inside programs that do not support the protocol such as vim and tmux (:pull:`5664`)
+
+- diff kitten: Add support for selecting multi-line text with the mouse
+
+- Fix a regression in 0.27.0 that broke ``kitty @ set-font-size 0`` (:iss:`5992`)
+
+- launch: When using ``--cwd=current`` for a remote system support running non shell commands as well (:disc:`5987`)
+
+- When changing the cursor color via escape codes or remote control to a fixed color, do not reset cursor_text_color (:iss:`5994`)
+
+- Input Method Extensions: Fix incorrect rendering of IME in-progress and committed text in some situations (:pull:`6049`, :pull:`6087`)
+
+- Linux: Reduce minimum required OpenGL version from 3.3 to 3.1 + extensions (:iss:`2790`)
+
+- Fix a regression that broke drawing of images below cell backgrounds (:iss:`6061`)
+
+- macOS: Fix the window buttons not being hidden after exiting the traditional full screen (:iss:`6009`)
+
+- When reloading configuration, also reload custom MIME types from :file:`mime.types` config file (:pull:`6012`)
+
+- launch: Allow specifying the state (full screen/maximized/minimized) for newly created OS Windows (:iss:`6026`)
+
+- Sessions: Allow specifying the OS window state via the ``os_window_state`` directive (:iss:`5863`)
+
+- macOS: Display the newly created OS window in specified state to avoid or reduce the window transition animations (:pull:`6035`)
+
+- macOS: Fix the maximized window not taking up full space when the title bar is hidden or when :opt:`resize_in_steps` is configured (:iss:`6021`)
+
+- Linux: A new option :opt:`linux_bell_theme` to control which sound theme is used for the bell sound (:pull:`4858`)
+
+- ssh kitten: Change the syntax of glob patterns slightly to match common usage
+  elsewhere. Now the syntax is the same as "extendedglob" in most shells.
+
+- hints kitten: Allow copying matches to named buffers (:disc:`6073`)
+
+- Fix overlay windows not inheriting the per-window padding and margin settings
+  of their parents (:iss:`6063`)
+
+- Wayland KDE: Fix selecting in un-focused OS window not working correctly (:iss:`6095`)
+
+- Linux X11: Fix a crash if the X server requests clipboard data after we have relinquished the clipboard (:iss:`5650`)
+
+- Allow stopping of URL detection at newlines via :opt:`url_excluded_characters` (:iss:`6122`)
+
+- Linux Wayland: Fix animated images not being animated continuously (:iss:`6126`)
+
+- Keyboard input: Fix text not being reported as unicode codepoints for multi-byte characters in the kitty keyboard protocol (:iss:`6167`)
+
+
+0.27.1 [2023-02-07]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Fix :opt:`modify_font` not working for strikethrough position (:iss:`5946`)
+
+- Fix a regression causing the ``edit-in-kitty`` command not working if :file:`kitten` is not added
+  to PATH (:iss:`5956`)
+
+- icat kitten: Fix a regression that broke display of animated GIFs over SSH (:iss:`5958`)
+
+- Wayland GNOME: Fix for ibus not working when using XWayland (:iss:`5967`)
+
+- Fix regression in previous release that caused incorrect entries in terminfo for modifier+F3 key combinations (:pull:`5970`)
+
+- Bring back the deprecated and removed ``kitty +complete`` and delegate it to :program:`kitten` for backward compatibility (:pull:`5977`)
+
+- Bump the version of Go needed to build kitty to ``1.20`` so we can use the Go stdlib ecdh package for crypto.
+
+
+0.27.0 [2023-01-31]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A new statically compiled, standalone executable, ``kitten`` (written in Go)
+  that can be used on all UNIX-like servers for remote control (``kitten @``),
+  viewing images (``kitten icat``), manipulating the clipboard (``kitten clipboard``), etc.
+
+- :doc:`clipboard kitten </kittens/clipboard>`: Allow copying arbitrary data types to/from the clipboard, not just plain text
+
+- Speed up the ``kitty @`` executable by ~10x reducing the time for typical
+  remote control commands from ~50ms to ~5ms
+
+- icat kitten: Speed up by using POSIX shared memory when possible to transfer
+  image data to the terminal. Also support common image formats
+  GIF/PNG/JPEG/WEBP/TIFF/BMP out of the box without needing ImageMagick.
+
+- Option :opt:`show_hyperlink_targets` to show the target of terminal hyperlinks when hovering over them with the mouse (:pull:`5830`)
+
+- Keyboard protocol: Remove ``CSI R`` from the allowed encodings of the :kbd:`F3` key as it conflicts with the *Cursor Position Report* escape code (:disc:`5813`)
+
+- Allow using the cwd of the original process for :option:`launch --cwd` (:iss:`5672`)
+
+- Session files: Expand environment variables (:disc:`5917`)
+
+- Pass key events mapped to scroll actions to the program running in the terminal when the terminal is in alternate screen mode (:iss:`5839`)
+
+- Implement :ref:`edit-in-kitty <edit_file>` using the new ``kitten`` static executable (:iss:`5546`, :iss:`5630`)
+
+- Add an option :opt:`background_tint_gaps` to control background image tinting for window gaps (:iss:`5596`)
+
+- A new option :opt:`undercurl_style` to control the rendering of undercurls (:pull:`5883`)
+
+- Bash integration: Fix ``clone-in-kitty`` not working on bash >= 5.2 if environment variable values contain newlines or other special characters (:iss:`5629`)
+
+- A new :ac:`sleep` action useful in combine based mappings to make kitty sleep before executing the next action
+
+- Wayland GNOME: Workaround for latest mutter release breaking full screen for semi-transparent kitty windows (:iss:`5677`)
+
+- A new option :opt:`tab_title_max_length` to limit the length of tab (:iss:`5718`)
+
+- When drawing the tab bar have the default left and right margins drawn in a color matching the neighboring tab (:iss:`5719`)
+
+- When using the :code:`include` directive in :file:`kitty.conf` make the environment variable :envvar:`KITTY_OS` available for OS specific config
+
+- Wayland: Fix signal handling not working with some GPU drivers (:iss:`4636`)
+
+- Remote control: When matching windows allow using negative id numbers to match recently created windows (:iss:`5753`)
+
+- ZSH Integration: Bind :kbd:`alt+left` and :kbd:`alt+right` to move by word if not already bound. This mimics the default bindings in Terminal.app (:iss:`5793`)
+
+- macOS: Allow to customize :sc:`Hide <hide_macos_app>`, :sc:`Hide Others <hide_macos_other_apps>`, :sc:`Minimize <minimize_macos_window>`, and :sc:`Quit <quit>` global menu shortcuts. Note that :opt:`clear_all_shortcuts` will remove these shortcuts now (:iss:`948`)
+
+- When a multi-key sequence does not match any action, send all key events to the child program (:pull:`5841`)
+
+- broadcast kitten: Allow pressing a key to stop echoing of input into the broadcast window itself (:disc:`5868`)
+
+- When reporting unused activity in a window, ignore activity that occurs soon after a window resize (:iss:`5881`)
+
+- Fix using :opt:`cursor` = ``none`` not working on text that has reverse video (:iss:`5897`)
+
+- Fix ssh kitten not working on FreeBSD (:iss:`5928`)
+
+- macOS: Export kitty selected text to the system for use with services that accept it (patch by Sertaç Ö. Yıldız)
+
+
+0.26.5 [2022-11-07]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Splits layout: Add a new mappable action to move the active window to the screen edge (:iss:`5643`)
+
+- ssh kitten: Allow using absolute paths for the location of transferred data (:iss:`5607`)
+
+- Fix a regression in the previous release that caused a :opt:`resize_draw_strategy` of ``static`` to not work (:iss:`5601`)
+
+- Wayland KDE: Fix abort when pasting into Firefox (:iss:`5603`)
+
+- Wayland GNOME: Fix ghosting when using :opt:`background_tint` (:iss:`5605`)
+
+- Fix cursor position at x=0 changing to x=1 on resize (:iss:`5635`)
+
+- Wayland GNOME: Fix incorrect window size in some circumstances when switching between windows with window decorations disabled (:iss:`4802`)
+
+- Wayland: Fix high CPU usage when using some input methods (:pull:`5369`)
+
+- Remote control: When matching window by `state:focused` and no window currently has keyboard focus, match the window belonging to the OS window that was last focused (:iss:`5602`)
+
+
+0.26.4 [2022-10-17]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- macOS: Allow changing the kitty icon by placing a custom icon in the kitty config folder (:pull:`5464`)
+
+- Allow centering the :opt:`background_image` (:iss:`5525`)
+
+- X11: Fix a regression in the previous release that caused pasting from GTK based applications to have extra newlines (:iss:`5528`)
+
+- Tab bar: Improve empty space management when some tabs have short titles, allocate the saved space to the active tab (:iss:`5548`)
+
+- Fix :opt:`background_tint` not applying to window margins and padding (:iss:`3933`)
+
+- Wayland: Fix background image scaling using tiled mode on high DPI screens
+
+- Wayland: Fix an abort when changing background colors with :opt:`wayland_titlebar_color` set to ``background`` (:iss:`5562`)
+
+- Update to Unicode 15.0 (:pull:`5542`)
+
+- GNOME Wayland: Fix a memory leak in gnome-shell when using client side decorations
+
+
+0.26.3 [2022-09-22]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Wayland: Mark windows in which a bell occurs as urgent on compositors that support the xdg-activation protocol
+
+- Allow passing null bytes through the system clipboard (:iss:`5483`)
+
+- ssh kitten: Fix :envvar:`KITTY_PUBLIC_KEY` not being encoded properly when transmitting (:iss:`5496`)
+
+- Sessions: Allow controlling which OS Window is active via the ``focus_os_window`` directive
+
+- Wayland: Fix for bug in NVIDIA drivers that prevents transparency working (:iss:`5479`)
+
+- Wayland: Fix for a bug that could cause kitty to become non-responsive when
+  using multiple OS windows in a single instance on some compositors (:iss:`5495`)
+
+- Wayland: Fix for a bug preventing kitty from starting on Hyprland when using a non-unit scale (:iss:`5467`)
+
+- Wayland: Generate a XDG_ACTIVATION_TOKEN when opening URLs or running programs in the background via the launch action
+
+- Fix a regression that caused kitty not to restore SIGPIPE after python nukes it when launching children. Affects bash which does not sanitize its signal mask. (:iss:`5500`)
+
+- Fix a use-after-free when handling fake mouse clicks and the action causes windows to be removed/re-allocated (:iss:`5506`)
+
+
+0.26.2 [2022-09-05]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Allow creating :code:`overlay-main` windows, which are treated as the active window unlike normal overlays (:iss:`5392`)
+
+- hints kitten: Allow using :doc:`launch` as the program to run, to open the result in a new kitty tab/window/etc. (:iss:`5462`)
+
+- hyperlinked_grep kitten: Allow control over which parts of ``rg`` output are hyperlinked (:pull:`5428`)
+
+- Fix regression in 0.26.0 that caused launching kitty without working STDIO handles to result in high CPU usage and prewarming failing (:iss:`5444`)
+
+- :doc:`/launch`: Allow setting the margin and padding for newly created windows (:iss:`5463`)
+
+- macOS: Fix regression in 0.26.0 that caused asking the user for a line of input such as for :ac:`set_tab_title` to not work (:iss:`5447`)
+
+- hints kitten: hyperlink matching: Fix hints occasionally matching text on subsequent line as part of hyperlink (:pull:`5450`)
+
+- Fix a regression in 0.26.0 that broke mapping of native keys whose key codes did not fit in 21 bits (:iss:`5452`)
+
+- Wayland: Fix remembering window size not accurate when client side decorations are present
+
+- Fix an issue where notification identifiers were not sanitized leading to
+  code execution if the user clicked on a notification popup from a malicious
+  source. Thanks to Carter Sande for discovering this vulnerability.
+
+
+0.26.1 [2022-08-30]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- ssh kitten: Fix executable permission missing from kitty bootstrap script (:iss:`5438`)
+
+- Fix a regression in 0.26.0 that caused kitty to no longer set the ``LANG`` environment variable on macOS (:iss:`5439`)
+
+- Allow specifying a title when using the :ac:`set_tab_title` action (:iss:`5441`)
+
+
+0.26.0 [2022-08-29]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A new option :opt:`remote_control_password` to use fine grained permissions for what can be remote controlled (:disc:`5320`)
+
+- Reduce startup latency by ~30 milliseconds when running kittens via key bindings inside kitty (:iss:`5159`)
+
+- A new option :opt:`modify_font` to adjust various font metrics like underlines, cell sizes etc. (:pull:`5265`)
+
+- A new shortcut :sc:`show_kitty_doc` to display the kitty docs in a browser
+
+- Graphics protocol: Only delete temp files if they have the string
+  :code:`tty-graphics-protocol` in their file paths. This prevents deletion of arbitrary files in :file:`/tmp`.
+
+- Deprecate the ``adjust_baseline``, ``adjust_line_height`` and ``adjust_column_width`` options in favor of :opt:`modify_font`
+
+- Wayland: Fix a regression in the previous release that caused mouse cursor
+  animation and keyboard repeat to stop working when switching seats (:iss:`5188`)
+
+- Allow resizing windows created in session files (:pull:`5196`)
+
+- Fix horizontal wheel events not being reported to client programs when they grab the mouse (:iss:`2819`)
+
+- macOS: Remote control: Fix unable to launch a new OS window or background process when there is no OS window (:iss:`5210`)
+
+- macOS: Fix unable to open new tab or new window when there is no OS window (:iss:`5276`)
+
+- kitty @ set-colors: Fix changing inactive_tab_foreground not working (:iss:`5214`)
+
+- macOS: Fix a regression that caused switching keyboard input using Eisu and
+  Kana keys not working (:iss:`5232`)
+
+- Add a mappable action to toggle the mirrored setting for the tall and fat
+  layouts (:pull:`5344`)
+
+- Add a mappable action to switch between predefined bias values for the tall and fat
+  layouts (:pull:`5352`)
+
+- Wayland: Reduce flicker at startup by not using render frames immediately after a resize (:iss:`5235`)
+
+- Linux: Update cursor position after all key presses not just pre-edit text
+  changes (:iss:`5241`)
+
+- ssh kitten: Allow ssh kitten to work from inside tmux, provided the tmux
+  session inherits the correct KITTY env vars (:iss:`5227`)
+
+- ssh kitten: A new option :code:`--symlink-strategy` to control how symlinks
+  are copied to the remote machine (:iss:`5249`)
+
+- ssh kitten: Allow pressing :kbd:`Ctrl+C` to abort ssh before the connection is
+  completed (:iss:`5271`)
+
+- Bash integration: Fix declare not creating global variables in .bashrc (:iss:`5254`)
+
+- Bash integration: Fix the inherit_errexit option being set by shell integration (:iss:`5349`)
+
+- :command:`kitty @ scroll-window` allow scrolling by fractions of a screen
+  (:iss:`5294`)
+
+- remote files kitten: Fix working with files whose names have characters that
+  need to be quoted in shell scripts (:iss:`5313`)
+
+- Expand ~ in paths configured in :opt:`editor` and :opt:`exe_search_path` (:disc:`5298`)
+
+- Allow showing the working directory of the active window in tab titles
+  (:pull:`5314`)
+
+- ssh kitten: Allow completion of ssh options between the destination and command (:iss:`5322`)
+
+- macOS: Fix speaking selected text not working (:iss:`5357`)
+
+- Allow ignoring failure to close windows/tabs via rc commands (:disc:`5406`)
+
+- Fix hyperlinks not present when fetching text from the history buffer
+  (:iss:`5427`)
+
+
+0.25.2 [2022-06-07]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- A new command :command:`edit-in-kitty` to :ref:`edit_file`
+
+- Allow getting the last non-empty command output easily via an action or
+  remote control (:pull:`4973`)
+
+- Fix a bug that caused :opt:`macos_colorspace` to always be ``default`` regardless of its actual value (:iss:`5129`)
+
+- diff kitten: A new option :opt:`kitten-diff.ignore_name` to exclude files and directories from being scanned (:pull:`5171`)
+
+- ssh kitten: Fix bash not being executed as a login shell since kitty 0.25.0 (:iss:`5130`)
+
+- macOS: When pasting text and the clipboard has a filesystem path, paste the
+  full path instead of the text, which is sometimes just the file name (:pull:`5142`)
+
+- macOS: Allow opening executables without a file extension with kitty as well
+  (:iss:`5160`)
+
+- Themes kitten: Add a tab to show user defined custom color themes separately
+  (:pull:`5150`)
+
+- Iosevka: Fix incorrect rendering when there is a combining char that does not
+  group with its neighbors (:iss:`5153`)
+
+- Weston: Fix client side decorations flickering on slow computers during
+  window resize (:iss:`5162`)
+
+- Remote control: Fix commands with large or asynchronous payloads like
+  :command:`kitty @ set-backround-image`, :command:`kitty @ set-window-logo`
+  and :command:`kitty @ select-window` not working correctly
+  when using a socket (:iss:`5165`)
+
+- hints kitten: Fix surrounding quotes/brackets and embedded carriage returns
+  not being removed when using line number processing (:iss:`5170`)
+
+
+0.25.1 [2022-05-26]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Shell integration: Add a command to :ref:`clone_shell`
+
+- Remote control: Allow using :ref:`Boolean operators <search_syntax>` when constructing queries to match windows or tabs
+
+- Sessions: Fix :code:`os_window_size` and :code:`os_window_class` not applying to the first OS Window (:iss:`4957`)
+
+- Allow using the cwd of the oldest as well as the newest foreground process for :option:`launch --cwd` (:disc:`4869`)
+
+- Bash integration: Fix the value of :opt:`shell_integration` not taking effect if the integration script is sourced in bashrc (:pull:`4964`)
+
+- Fix a regression in the previous release that caused mouse move events to be incorrectly reported as drag events even when a button is not pressed (:iss:`4992`)
+
+- remote file kitten: Integrate with the ssh kitten for improved performance
+  and robustness. Re-uses the control master connection of the ssh kitten to
+  avoid round-trip latency.
+
+- Fix tab selection when closing a new tab not correct in some scenarios (:iss:`4987`)
+
+- A new action :ac:`open_url` to open the specified URL (:pull:`5004`)
+
+- A new option :opt:`select_by_word_characters_forward` that allows changing
+  which characters are considered part of a word to the right when double clicking to select
+  words (:pull:`5103`)
+
+- macOS: Make the global menu shortcut to open kitty website configurable (:pull:`5004`)
+
+- macOS: Add the :opt:`macos_colorspace` option to control what color space colors are rendered in (:iss:`4686`)
+
+- Fix reloading of config not working when :file:`kitty.conf` does not exist when kitty is launched (:iss:`5071`)
+
+- Fix deleting images by row not calculating image bounds correctly (:iss:`5081`)
+
+- Increase the max number of combining chars per cell from two to three, without increasing memory usage.
+
+- Linux: Load libfontconfig at runtime to allow the binaries to work for
+  running kittens on servers without FontConfig
+
+- GNOME: Fix for high CPU usage caused by GNOME's text input subsystem going
+  into an infinite loop when IME cursor position is updated after a done event
+  (:iss:`5105`)
+
+
+0.25.0 [2022-04-11]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- :doc:`kittens/ssh`: automatic shell integration when using SSH. Easily
+  clone local shell and editor configuration on remote machines, and automatic
+  re-use of existing connections to avoid connection setup latency.
+
+- When pasting URLs at shell prompts automatically quote them. Also allow filtering pasted text and confirm pastes. See :opt:`paste_actions` for details. (:iss:`4873`)
+
+- Change the default value of :opt:`confirm_os_window_close` to ask for confirmation when closing windows that are not sitting at shell prompts
+
+- A new value :code:`last_reported` for :option:`launch --cwd` to use the current working directory last reported by the program running in the terminal
+
+- macOS: When using Apple's less as the pager for viewing scrollback strip out OSC codes as it cant parse them (:iss:`4788`)
+
+- diff kitten: Fix incorrect rendering in rare circumstances when scrolling after changing the context size (:iss:`4831`)
+
+- icat kitten: Fix a regression that broke :option:`kitty +kitten icat --print-window-size` (:pull:`4818`)
+
+- Wayland: Fix :opt:`hide_window_decorations` causing docked windows to be resized on blur (:iss:`4797`)
+
+- Bash integration: Prevent shell integration code from running twice if user enables both automatic and manual integration
+
+- Bash integration: Handle existing PROMPT_COMMAND ending with a literal newline
+
+- Fix continued lines not having their continued status reset on line feed (:iss:`4837`)
+
+- macOS: Allow the New kitty Tab/Window Here services to open multiple selected folders.  (:pull:`4848`)
+
+- Wayland: Fix a regression that broke IME when changing windows/tabs (:iss:`4853`)
+
+- macOS: Fix Unicode paths not decoded correctly when dropping files (:pull:`4879`)
+
+- Avoid flicker when starting kittens such as the hints kitten (:iss:`4674`)
+
+- A new action :ac:`scroll_prompt_to_top` to move the current prompt to the top (:pull:`4891`)
+
+- :ac:`select_tab`: Use stable numbers when selecting the tab (:iss:`4792`)
+
+- Only check for updates in the official binary builds. Distro packages or source builds will no longer check for updates, regardless of the
+  value of :opt:`update_check_interval`.
+
+- Fix :opt:`inactive_text_alpha` still being applied to the cursor hidden window after focus (:iss:`4928`)
+
+- Fix resizing window that is extra tall/wide because of left-over cells not
+  working reliably (:iss:`4913`)
+
+- A new action :ac:`close_other_tabs_in_os_window` to close other tabs in the active OS window (:pull:`4944`)
+
+
+0.24.4 [2022-03-03]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Shell integration: Fix the default Bash :code:`$HISTFILE` changing to :file:`~/.sh_history` instead of :file:`~/.bash_history` (:iss:`4765`)
+
+- Linux binaries: Fix binaries not working on systems with older Wayland client libraries (:iss:`4760`)
+
+- Fix a regression in the previous release that broke kittens launched with :code:`STDIN` not connected to a terminal (:iss:`4763`)
+
+- Wayland: Fix surface configure events not being acknowledged before commit
+  the resized buffer (:pull:`4768`)
+
+
+0.24.3 [2022-02-28]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Bash integration: No longer modify :file:`~/.bashrc` to load :ref:`shell integration <shell_integration>`.
+  It is recommended to remove the lines used to load the shell integration from :file:`~/.bashrc` as they are no-ops.
+
+- macOS: Allow kitty to handle various URL types. Can be configured via
+  :ref:`launch_actions` (:pull:`4618`)
+
+- macOS: Add a new service ``Open with kitty`` to open file types that are not
+  recognized by the system (:pull:`4641`)
+
+- Splits layout: A new value for :option:`launch --location` to auto-select the split axis when splitting existing windows.
+  Wide windows are split side-by-side and tall windows are split one-above-the-other
+
+- hints kitten: Fix a regression that broke recognition of path:linenumber:colnumber (:iss:`4675`)
+
+- Fix a regression in the previous release that broke :opt:`active_tab_foreground` (:iss:`4620`)
+
+- Fix :ac:`show_last_command_output` not working when the output is stored
+  partially in the scrollback pager history buffer (:iss:`4435`)
+
+- When dropping URLs/files onto kitty at a shell prompt insert them appropriately quoted and space
+  separated (:iss:`4734`)
+
+- Improve CWD detection when there are multiple foreground processes in the TTY process group
+
+- A new option :opt:`narrow_symbols` to turn off opportunistic wide rendering of private use codepoints
+
+- ssh kitten: Fix location of generated terminfo files on NetBSD (:iss:`4622`)
+
+- A new action to clear the screen up to the line containing the cursor, see
+  :ac:`clear_terminal`
+
+- A new action :ac:`copy_ansi_to_clipboard` to copy the current selection with ANSI formatting codes
+  (:iss:`4665`)
+
+- Linux: Do not rescale fallback fonts to match the main font cell height, instead just
+  set the font size and let FreeType take care of it. This matches
+  rendering on macOS (:iss:`4707`)
+
+- macOS: Fix a regression in the previous release that broke switching input
+  sources by keyboard (:iss:`4621`)
+
+- macOS: Add the default shortcut :kbd:`cmd+k` to clear the terminal screen and
+  scrollback up to the cursor (:iss:`4625`)
+
+- Fix a regression in the previous release that broke strikethrough (:disc:`4632`)
+
+- A new action :ac:`scroll_prompt_to_bottom` to move the current prompt
+  to the bottom, filling in the window from the scrollback (:pull:`4634`)
+
+- Add two special arguments ``@first-line-on-screen`` and ``@last-line-on-screen``
+  for the :doc:`launch <launch>` command to be used for pager positioning.
+  (:iss:`4462`)
+
+- Linux: Fix rendering of emoji when using scalable fonts such as Segoe UI Emoji
+
+- Shell integration: bash: Dont fail if an existing PROMPT_COMMAND ends with a semi-colon (:iss:`4645`)
+
+- Shell integration: bash: Fix rendering of multiline prompts with more than two lines (:iss:`4681`)
+
+- Shell integration: fish: Check fish version 3.3.0+ and exit on outdated versions (:pull:`4745`)
+
+- Shell integration: fish: Fix pipestatus being overwritten (:pull:`4756`)
+
+- Linux: Fix fontconfig alias not being used if the aliased font is dual spaced instead of monospaced (:iss:`4649`)
+
+- macOS: Add an option :opt:`macos_menubar_title_max_length` to control the max length of the window title displayed in the global menubar (:iss:`2132`)
+
+- Fix :opt:`touch_scroll_multiplier` also taking effect in terminal programs such as vim that handle mouse events themselves (:iss:`4680`)
+
+- Fix symbol/PUA glyphs loaded via :opt:`symbol_map` instead of as fallbacks not using following spaces to render larger versions (:iss:`4670`)
+
+- macOS: Fix regression in previous release that caused Apple's global shortcuts to not work if they had never been configured on a particular machine (:iss:`4657`)
+
+- Fix a fast *click, move mouse, click* sequence causing the first click event to be discarded (:iss:`4603`)
+
+- Wayland: Fix wheel mice with line based scrolling being incorrectly handled as high precision devices (:iss:`4694`)
+
+- Wayland: Fix touchpads and high resolution wheels not scrolling at the same speed on monitors with different scales (:iss:`4703`)
+
+- Add an option :opt:`wheel_scroll_min_lines` to set the minimum number of lines for mouse wheel scrolling when using a mouse with a wheel that generates very small offsets when slow scrolling (:pull:`4710`)
+
+- macOS: Make the shortcut to toggle full screen configurable (:pull:`4714`)
+
+- macOS: Fix the mouse cursor being set to arrow after switching desktops or toggling full screen (:pull:`4716`)
+
+- Fix copying of selection after selection has been scrolled off history buffer raising an error (:iss:`4713`)
+
+
 0.24.2 [2022-02-03]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -420,7 +982,7 @@ Detailed list of changes
 0.22.0 [2021-07-26]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Add a new :ref:`action-toggle_layout` action to easily zoom/unzoom a window
+- Add a new :ac:`toggle_layout` action to easily zoom/unzoom a window
 
 - When right clicking to extend a selection, move the nearest selection
   boundary rather than the end of the selection. To restore previous behavior
@@ -490,7 +1052,7 @@ Detailed list of changes
 0.21.2 [2021-06-28]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- A new :opt:`adjust_baseline` option to adjust the vertical alignment of text
+- A new ``adjust_baseline`` option to adjust the vertical alignment of text
   inside a line (:pull:`3734`)
 
 - A new :opt:`url_excluded_characters` option to exclude additional characters
@@ -664,7 +1226,7 @@ Detailed list of changes
   scrollback buffer onto the screen. Useful, for example, to restore
   the screen after showing completions below the shell prompt.
 
-- A new remote control command :ref:`at_env` to change the default
+- A new remote control command :ref:`at-env` to change the default
   environment passed to newly created windows (:iss:`3529`)
 
 - Linux: Fix binary kitty builds not able to load fonts in WOFF2 format
@@ -689,7 +1251,7 @@ Detailed list of changes
   kitty window title bar
 
 - Fix reading :option:`kitty --session` from ``STDIN`` not working when the
-  :option:`kitty --detach` option is used (:iss:`3523`)
+  :code:`kitty --detach` option is used (:iss:`3523`)
 
 - Special case rendering of the few remaining Powerline box drawing chars
   (:iss:`3535`)
@@ -1247,6 +1809,7 @@ Detailed list of changes
 
 - Fix :option:`--title` not being applied at window creation time (:iss:`2570`)
 
+
 0.17.2 [2020-03-29]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1431,6 +1994,7 @@ Detailed list of changes
 - When windows are semi-transparent and all contain graphics, correctly render
   them. (:iss:`2310`)
 
+
 0.15.1 [2019-12-21]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1539,6 +2103,7 @@ Detailed list of changes
 
 - Use selection foreground color for underlines as well (:iss:`1982`)
 
+
 0.14.4 [2019-08-31]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1832,7 +2397,7 @@ Detailed list of changes
 - Allow the user to control the resize debounce time via
   :opt:`resize_debounce_time`.
 
-- Remote control: Make the :ref:`at_set-font-size` command more capable.
+- Remote control: Make the :ref:`at-set-font-size` command more capable.
   It can now increment font size and reset it. It also only acts on the
   active top-level window, by default (:iss:`1581`)
 
@@ -1845,6 +2410,7 @@ Detailed list of changes
 - Mouse selection: When extending by word, fix extending selection to non-word
   characters not working well (:iss:`1616`)
 
+
 0.13.3 [2019-01-19]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1938,6 +2504,7 @@ Detailed list of changes
 - Fix resizing window smaller and then restoring causing some wrapped lines to not
   be properly unwrapped (:iss:`1206`)
 
+
 0.13.0 [2018-12-05]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2035,6 +2602,7 @@ Detailed list of changes
 - Fix hover detection of URLs not working when hovering over the first colon
   and slash characters in short URLs (:iss:`1201`)
 
+
 0.12.3 [2018-09-29]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2111,6 +2679,7 @@ Detailed list of changes
 - Fix using :opt:`focus_follows_mouse` causing text selection with the
   mouse to malfunction when using multiple kitty windows (:iss:`1002`)
 
+
 0.12.1 [2018-09-08]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2141,7 +2710,7 @@ Detailed list of changes
 
 - Fix a regression in 0.12.0 that broke dynamic resizing of layouts (:iss:`860`)
 
-- Wayland: Allow using the :option:`kitty --class` command line flag
+- Wayland: Allow using the :code:`kitty --class` command line flag
   to set the app id (:iss:`862`)
 
 - Add completion of the kitty command for the fish shell (:pull:`829`)
@@ -2154,6 +2723,7 @@ Detailed list of changes
 - macOS: Diff kitten: Fix syntax highlighting not working because of
   a bug in the 0.12.0 macOS package
 
+
 0.12.0 [2018-09-01]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2184,7 +2754,7 @@ Detailed list of changes
   window is not the active window (:iss:`729`)
 
 - Remote control: Allow changing the current window layout with a new
-  :ref:`at_goto-layout` command (:iss:`845`)
+  :ref:`at-goto-layout` command (:iss:`845`)
 
 - Remote control: Allow matching windows by the environment variables of their
   child process as well
@@ -2664,6 +3234,7 @@ Detailed list of changes
 
 - Fix a crash when getting the contents of the scrollback buffer as text
 
+
 0.8.1 [2018-03-09]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2741,6 +3312,7 @@ Detailed list of changes
 - Browsing the scrollback buffer now happens in an overlay window instead of a
   new window/tab.
 
+
 0.7.1 [2018-01-31]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/clipboard.rst

@@ -0,0 +1,160 @@
+Copying all data types to the clipboard
+==============================================
+
+There already exists an escape code to allow terminal programs to
+read/write plain text data from the system clipboard, *OSC 52*.
+kitty introduces a more advanced protocol that supports:
+
+* Copy arbitrary data including images, rich text documents, etc.
+* Allow terminals to ask the user for permission to access the clipboard and
+  report permission denied
+
+The escape code is *OSC 5522*, an extension of *OSC 52*. The basic format
+of the escape code is::
+
+    <OSC>5522;metadata;payload<ST>
+
+Here, *metadata* is a colon separated list of key-value pairs and payload is
+base64 encoded data. :code:`OSC` is :code:`<ESC>[`.
+:code:`ST` is the string terminator, :code:`<ESC>\\`.
+
+Reading data from the system clipboard
+----------------------------------------
+
+To read data from the system clipboard, the escape code is::
+
+    <OSC>5522;type=read;<base 64 encoded space separated list of mime types to read><ST>
+
+For example, to read plain text and PNG data, the payload would be::
+
+    text/plain image/png
+
+encoded as base64. To read from the primary selection instead of the
+clipboard, add the key ``loc=primary`` to the metadata section.
+
+To get the list of MIME types available on the clipboard the payload must be
+just a period (``.``), encoded as base64.
+
+The terminal emulator will reply with a sequence of escape codes of the form::
+
+    <OSC>5522;type=read:status=OK<ST>
+    <OSC>5522;type=read:status=DATA:mime=<base 64 encoded mime type>;<base64 encoded data><ST>
+    <OSC>5522;type=read:status=DATA:mime=<base 64 encoded mime type>;<base64 encoded data><ST>
+    .
+    .
+    .
+    <OSC>5522;type=read:status=DONE<ST>
+
+Here, the ``status=DATA`` packets deliver the data (as base64 encoded bytes)
+associated with each MIME type. The terminal emulator should chunk up the data
+for an individual type. A recommended size for each chunk is 4096 bytes. All
+the chunks for a given type must be transmitted sequentially and only once they
+are done the chunks for the next type, if any, should be sent. The end of data
+is indicated by a ``status=DONE`` packet.
+
+If an error occurs, instead of the opening ``status=OK`` packet the terminal
+must send a ``status=ERRORCODE`` packet. The error code must be one of:
+
+``status=ENOSYS``
+    Sent if the requested clipboard type is not available. For example, primary
+    selection is not available on all systems and ``loc=primary`` was used.
+
+``status=EPERM``
+    Sent if permission to read from the clipboard was denied by the system or
+    the user.
+
+``status=EBUSY``
+    Sent if there is some temporary problem, such as multiple clients in a
+    multiplexer trying to access the clipboard simultaneously.
+
+Terminals should ask the user for permission before allowing a read request.
+However, if a read request only wishes to list the available data types on the
+clipboard, it should be allowed without a permission prompt. This is so that
+the user is not presented with a double permission prompt for reading the
+available MIME types and then reading the actual data.
+
+
+Writing data to the system clipboard
+----------------------------------------
+
+To write data to the system clipboard, the terminal programs sends the
+following sequence of packets::
+
+    <OSC>5522;type=write<ST>
+    <OSC>5522;type=wdata:mime=<base64 encoded mime type>;<base 64 encoded chunk of data for this type><ST>
+    <OSC>5522;type=wdata:mime=<base64 encoded mime type>;<base 64 encoded chunk of data for this type><ST>
+    .
+    .
+    .
+    <OSC>5522;type=wdata<ST>
+
+The final packet with no mime and no data indicates end of transmission. The
+data for every MIME type should be split into chunks of no more than 4096
+bytes. All the chunks for a given MIME type must be sent sequentially, before
+sending chunks for the next MIME type. After the transmission is complete, the
+terminal replies with a single packet indicating success::
+
+    <OSC>5522;type=write:status=DONE<ST>
+
+If an error occurs the terminal can, at any time, send an error packet of the
+form::
+
+    <OSC>5522;type=write:status=ERRORCODE<ST>
+
+Here ``ERRORCODE`` must be one of:
+
+``status=EIO``
+    An I/O error occurred while processing the data
+``status=EINVAL``
+    One of the packets was invalid, usually because of invalid base64 encoding.
+``status=ENOSYS``
+    The client asked to write to the primary selection with (``loc=primary``) and that is not
+    available on the system
+``status=EPERM``
+    Sent if permission to write to the clipboard was denied by the system or
+    the user.
+``status=EBUSY``
+    Sent if there is some temporary problem, such as multiple clients in a
+    multiplexer trying to access the clipboard simultaneously.
+
+Once an error occurs, the terminal must ignore all further OSC 5522 write related packets until it
+sees the start of a new write with a ``type=write`` packet.
+
+The client can send to the primary selection instead of the clipboard by adding
+``loc=primary`` to the initial ``type=write`` packet.
+
+Finally, clients have the ability to *alias* MIME types when sending data to
+the clipboard. To do that, the client must send a ``type=walias`` packet of the
+form::
+
+    <OSC>5522;type=walias;mime=<base64 encoded target MIME type>;<base64 encoded, space separated list of aliases><ST>
+
+The effect of an alias is that the system clipboard will make available all the
+aliased MIME types, with the same data as was transmitted for the target MIME
+type. This saves bandwidth, allowing the client to only transmit one copy of
+the data, but create multiple references to it in the system clipboard. Alias
+packets can be sent anytime after the initial write packet and before the end
+of data packet.
+
+
+Support for terminal multiplexers
+------------------------------------
+
+Since this protocol involves two way communication between the terminal
+emulator and the client program, multiplexers need a way to know which window
+to send responses from the terminal to. In order to make this possible, the
+metadata portion of this escape code includes an optional ``id`` field. If
+present the terminal emulator must send it back unchanged with every response.
+Valid ids must include only characters from the set: ``[a-zA-Z0-9-_+.]``. Any
+other characters must be stripped out from the id by the terminal emulator
+before retransmitting it.
+
+Note that when using a terminal multiplexer it is possible for two different
+programs to tread on each others clipboard requests. This is fundamentally
+unavoidable since the system clipboard is a single global shared resource.
+However, there is an additional complication where responses form this protocol
+could get lost if, for instance, multiple write requests are received
+simultaneously. It is up to well designed multiplexers to ensure that only a
+single request is in flight at a time. The multiplexer can abort requests by
+sending back the ``EBUSY`` error code indicating some other window is trying
+to access the clipboard.

docs/color-stack.rst

@@ -2,25 +2,25 @@ Saving and restoring colors
 ==============================
 
 It is often useful for a full screen application with its own color themes to
-set the default foreground, background, selection and cursor colors and the
+set the default foreground, background, selection and cursor colors and the ANSI
-ANSI color table. This allows for various performance optimizations when
+color table. This allows for various performance optimizations when drawing the
-drawing the screen. The problem is that if the user previously used the escape
+screen. The problem is that if the user previously used the escape codes to
-codes to change these colors herself, then running the full screen application
+change these colors themselves, then running the full screen application will
-will lose her changes even after it exits. To avoid this, kitty introduces a
+lose those changes even after it exits. To avoid this, kitty introduces a new
-new pair of *OSC* escape codes to push and pop the current color values from a
+pair of *OSC* escape codes to push and pop the current color values from a
 stack::
 
     <ESC>]30001<ESC>\  # push onto stack
     <ESC>]30101<ESC>\  # pop from stack
 
-These escape codes save/restore the colors, default
+These escape codes save/restore the colors, default background, default
-background, default foreground, selection background, selection foreground and
+foreground, selection background, selection foreground and cursor color and the
-cursor color and the 256 colors of the ANSI color table.
+256 colors of the ANSI color table.
 
-.. note:: In July 2020, after several years, XTerm copied this protocol
+.. note:: In July 2020, after several years, xterm copied this protocol
    extension, without acknowledgement, and using incompatible escape codes
    (XTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS). And they decided to save not
    just the dynamic colors but the entire ANSI color table. In the interests of
-   promoting interoperability, kitty added support for XTerm's escape codes as
+   promoting interoperability, kitty added support for xterm's escape codes as
    well, and changed this extension to also save/restore the entire ANSI color
    table.

docs/conf.py

@@ -13,14 +13,12 @@ import subprocess
 import sys
 import time
 from functools import partial
-from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+from typing import Any, Callable, Dict, Iterable, List, Tuple
 
 from docutils import nodes
 from docutils.parsers.rst.roles import set_classes
 from pygments.lexer import RegexLexer, bygroups  # type: ignore
-from pygments.token import (  # type: ignore
+from pygments.token import Comment, Keyword, Literal, Name, Number, String, Whitespace  # type: ignore
-    Comment, Keyword, Literal, Name, Number, String, Whitespace
-)
 from sphinx import addnodes, version_info
 from sphinx.util.logging import getLogger
 
@@ -67,6 +65,10 @@ extensions = [
 
 # URL for OpenGraph tags
 ogp_site_url = website_url()
+# OGP needs a PNG image because of: https://github.com/wpilibsuite/sphinxext-opengraph/issues/96
+ogp_social_cards = {
+    'image': '../logo/kitty.png'
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -85,7 +87,7 @@ master_doc = 'index'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language: Optional[str] = None
+language: str = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -104,6 +106,19 @@ rst_prolog = '''
 '''.replace('VERSION', str_version)
 smartquotes_action = 'qe'  # educate quotes and ellipses but not dashes
 
+def go_version(go_mod_path: str) -> str:  # {{{
+    with open(go_mod_path) as f:
+        for line in f:
+            if line.startswith('go '):
+                return line.strip().split()[1]
+    raise SystemExit(f'No Go version in {go_mod_path}')
+# }}}
+
+string_replacements = {
+    '_kitty_install_cmd': 'curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin',
+    '_build_go_version': go_version('../go.mod'),
+}
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -116,10 +131,23 @@ html_title = 'kitty'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
+github_icon_path = 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z'  # noqa
+
 html_theme_options: Dict[str, Any] = {
     'sidebar_hide_name': True,
     'navigation_with_keys': True,
+    'footer_icons': [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/kovidgoyal/kitty",
+            "html": f"""
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="{github_icon_path}"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
 }
 
 
@@ -198,7 +226,15 @@ def commit_role(
 
 # CLI docs {{{
 def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
+    from kittens.ssh.main import copy_message, option_text
     from kitty.cli import option_spec_as_rst
+    with open('generated/ssh-copy.rst', 'w') as f:
+        f.write(option_spec_as_rst(
+            appname='copy', ospec=option_text, heading_char='^',
+            usage='file-or-dir-to-copy ...', message=copy_message
+        ))
+    del sys.modules['kittens.ssh.main']
+
     from kitty.launch import options_spec as launch_options_spec
     with open('generated/launch.rst', 'w') as f:
         f.write(option_spec_as_rst(
@@ -225,12 +261,13 @@ if you specify a program-to-run you can use the special placeholder
         from kitty.rc.base import cli_params_for
         for cmd_name in sorted(all_command_names()):
             func = command_for_name(cmd_name)
-            p(f'.. _at_{func.name}:\n')
+            p(f'.. _at-{func.name}:\n')
             p('kitty @', func.name)
             p('-' * 120)
             p('.. program::', 'kitty @', func.name)
             p('\n\n' + as_rst(*cli_params_for(func)))
     from kittens.runner import get_kitten_cli_docs
+
     for kitten in all_kitten_names:
         data = get_kitten_cli_docs(kitten)
         if data:
@@ -239,7 +276,8 @@ if you specify a program-to-run you can use the special placeholder
                 p('.. program::', 'kitty +kitten', kitten)
                 p('\nSource code for', kitten)
                 p('-' * 72)
-                p(f'\nThe source code for this kitten is `available on GitHub <https://github.com/kovidgoyal/kitty/tree/master/kittens/{kitten}>`_.')
+                scurl = f'https://github.com/kovidgoyal/kitty/tree/master/kittens/{kitten}'
+                p(f'\nThe source code for this kitten is `available on GitHub <{scurl}>`_.')
                 p('\nCommand Line Interface')
                 p('-' * 72)
                 p('\n\n' + option_spec_as_rst(
@@ -250,10 +288,8 @@ if you specify a program-to-run you can use the special placeholder
 
 
 def write_remote_control_protocol_docs() -> None:  # {{{
-    from kitty.rc.base import (
+    from kitty.rc.base import RemoteCommand, all_command_names, command_for_name
-        RemoteCommand, all_command_names, command_for_name
+    field_pat = re.compile(r'\s*([^:]+?)\s*:\s*(.+)')
-    )
-    field_pat = re.compile(r'\s*([a-zA-Z0-9_+]+)\s*:\s*(.+)')
 
     def format_cmd(p: Callable[..., None], name: str, cmd: RemoteCommand) -> None:
         p(name)
@@ -265,7 +301,7 @@ def write_remote_control_protocol_docs() -> None:  # {{{
             if m is None:
                 p(line)
             else:
-                fields.append((m.group(1), m.group(2)))
+                fields.append((m.group(1).split('/')[0], m.group(2)))
         if fields:
             p('\nFields are:\n')
             for (name, desc) in fields:
@@ -293,8 +329,16 @@ def write_remote_control_protocol_docs() -> None:  # {{{
 # }}}
 
 
+def replace_string(app: Any, docname: str, source: List[str]) -> None:  # {{{
+    src = source[0]
+    for k, v in app.config.string_replacements.items():
+        src = src.replace(k, v)
+    source[0] = src
+# }}}
+
 # config file docs {{{
 
+
 class ConfLexer(RegexLexer):  # type: ignore
     name = 'Conf'
     aliases = ['conf']
@@ -399,6 +443,12 @@ def parse_shortcut_node(env: Any, sig: str, signode: Any) -> str:
     return sig
 
 
+def parse_action_node(env: Any, sig: str, signode: Any) -> str:
+    """Transform an action description into RST nodes."""
+    signode += addnodes.desc_name(sig, sig)
+    return sig
+
+
 def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
     conf_name, opt = target.partition('.')[::2]
     if not opt:
@@ -407,6 +457,10 @@ def process_opt_link(env: Any, refnode: Any, has_explicit_title: bool, title: st
     return title, opt_aliases.get(full_name, full_name)
 
 
+def process_action_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
+    return title, target
+
+
 def process_shortcut_link(env: Any, refnode: Any, has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
     conf_name, slug = target.partition('.')[::2]
     if not slug:
@@ -444,6 +498,15 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
     sc_role.process_link = process_shortcut_link
     shortcut_slugs.clear()
 
+    app.add_object_type(
+        'action', 'ac',
+        indextemplate="pair: %s; Action",
+        parse_node=parse_action_node,
+    )
+    ac_role = app.registry.domain_roles['std']['ac']
+    ac_role.warn_dangling = True
+    ac_role.process_link = process_action_link
+
     def generate_default_config(definition: Definition, name: str) -> None:
         with open(f'generated/conf-{name}.rst', 'w', encoding='utf-8') as f:
             print('.. highlight:: conf\n', file=f)
@@ -451,7 +514,7 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
 
         conf_name = re.sub(r'^kitten-', '', name) + '.conf'
         with open(f'generated/conf/{conf_name}', 'w', encoding='utf-8') as f:
-            text = '\n'.join(definition.as_conf())
+            text = '\n'.join(definition.as_conf(commented=True))
             print(text, file=f)
 
     from kitty.options.definition import definition
@@ -459,9 +522,9 @@ def write_conf_docs(app: Any, all_kitten_names: Iterable[str]) -> None:
 
     from kittens.runner import get_kitten_conf_docs
     for kitten in all_kitten_names:
-        definition = get_kitten_conf_docs(kitten)
+        defn = get_kitten_conf_docs(kitten)
-        if definition:
+        if defn is not None:
-            generate_default_config(definition, f'kitten-{kitten}')
+            generate_default_config(defn, f'kitten-{kitten}')
 
     from kitty.actions import as_rst
     with open('generated/actions.rst', 'w', encoding='utf-8') as f:
@@ -490,6 +553,8 @@ def setup(app: Any) -> None:
     write_cli_docs(kn)
     write_remote_control_protocol_docs()
     write_conf_docs(app, kn)
+    app.add_config_value('string_replacements', {}, True)
+    app.connect('source-read', replace_string)
     app.add_config_value('analytics_id', '', 'env')
     app.connect('html-page-context', add_html_context)
     app.add_lexer('session', SessionLexer() if version_info[0] < 3 else SessionLexer)

docs/conf.rst

@@ -3,13 +3,14 @@ kitty.conf
 
 .. highlight:: conf
 
-|kitty| is highly customizable, everything from keyboard shortcuts, to
+|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
-rendering frames-per-second. See below for an overview of all customization
+frames-per-second. See below for an overview of all customization possibilities.
-possibilities.
 
-You can open the config file within kitty by pressing :sc:`edit_config_file` (:kbd:`⌘+,` on macOS).
+You can open the config file within kitty by pressing :sc:`edit_config_file`
-You can reload the config file within kitty by pressing
+(:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
-:sc:`reload_config_file` (:kbd:`⌃+⌘+,` on macOS) or sending kitty the ``SIGUSR1`` signal.
+configurations and descriptions will be created if the file does not exist.
+You can reload the config file within kitty by pressing :sc:`reload_config_file`
+(:kbd:`⌃+⌘+,` on macOS) or sending kitty the ``SIGUSR1`` signal.
 You can also display the current configuration by pressing :sc:`debug_config`
 (:kbd:`⌥+⌘+,` on macOS).
 
@@ -17,26 +18,34 @@ You can also display the current configuration by pressing :sc:`debug_config`
 
 |kitty| looks for a config file in the OS config directories (usually
 :file:`~/.config/kitty/kitty.conf`) but you can pass a specific path via the
-:option:`kitty --config` option or use the ``KITTY_CONFIG_DIRECTORY``
+:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
-environment variable. See the :option:`kitty --config` option for full details.
+environment variable. See :option:`kitty --config` for full details.
 
 Comments can be added to the config file as lines starting with the ``#``
-character. This works only if the ``#`` character is the first character
+character. This works only if the ``#`` character is the first character in the
-in the line.
+line.
 
-You can include secondary config files via the :code:`include` directive.  If
+.. _include:
+
+You can include secondary config files via the :code:`include` directive. If
 you use a relative path for :code:`include`, it is resolved with respect to the
 location of the current config file. Note that environment variables are
 expanded, so :code:`${USER}.conf` becomes :file:`name.conf` if
-:code:`USER=name`. Also, you can use :code:`globinclude` to include files
+:code:`USER=name`. A special environment variable :envvar:`KITTY_OS` is available,
-matching a shell glob pattern. For example::
+to detect the operating system. It is ``linux``, ``macos`` or ``bsd``.
+Also, you can use :code:`globinclude` to include files
+matching a shell glob pattern and :code:`envinclude` to include configuration
+from environment variables. For example::
 
      include other.conf
+     # Include *.conf files from all subdirs of kitty.d inside the kitty config dir
      globinclude kitty.d/**/*.conf
+     # Include the *contents* of all env vars starting with KITTY_CONF_
+     envinclude KITTY_CONF_*
 
 
 .. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via
-   `vim-kitty <https://github.com/fladson/vim-kitty>`_.
+   `vim-kitty <https://github.com/fladson/vim-kitty>`__.
 
 
 .. include:: /generated/conf-kitty.rst
@@ -47,18 +56,23 @@ Sample kitty.conf
 
 .. only:: html
 
-    You can download a sample :file:`kitty.conf` file with all default settings and
+    You can download a sample :file:`kitty.conf` file with all default settings
-    comments describing each setting by clicking: :download:`sample kitty.conf
+    and comments describing each setting by clicking: :download:`sample
-    </generated/conf/kitty.conf>`.
+    kitty.conf </generated/conf/kitty.conf>`.
 
 .. only:: man
 
    You can edit a fully commented sample kitty.conf by pressing the
-   :sc:`edit_config_file` shortcut in kitty. This will generate a config
+   :sc:`edit_config_file` shortcut in kitty. This will generate a config file
-   file with full documentation and all settings commented out. If you
+   with full documentation and all settings commented out. If you have a
-   have a pre-existing kitty.conf, then that will be used instead, delete
+   pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
-   it to see the sample file.
+   see the sample file.
 
+A default configuration file can also be generated by running::
+
+    kitty +runpy 'from kitty.config import *; print(commented_out_default_config())'
+
+This will print the commented out default config file to :file:`STDOUT`.
 
 All mappable actions
 ------------------------

docs/deccara.rst

@@ -3,19 +3,18 @@ Setting text styles/colors in arbitrary regions of the screen
 
 There already exists an escape code to set *some* text attributes in arbitrary
 regions of the screen, `DECCARA
-<https://vt100.net/docs/vt510-rm/DECCARA.html>`_.  However, it is limited to
+<https://vt100.net/docs/vt510-rm/DECCARA.html>`__. However, it is limited to
 only a few attributes. |kitty| extends this to work with *all* SGR attributes.
 So, for example, this can be used to set the background color in an arbitrary
 region of the screen.
 
 The motivation for this extension is the various problems with the existing
 solution for erasing to background color, namely the *background color erase
-(bce)* capability. See
+(bce)* capability. See :iss:`this discussion <160#issuecomment-346470545>`
-:iss:`this discussion <160#issuecomment-346470545>`
+and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`__
-and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
 for a summary of problems with *bce*.
 
-For example, to set the background color to blue in a
+For example, to set the background color to blue in a rectangular region of the
-rectangular region of the screen from (3, 4) to (10, 11), you use::
+screen from (3, 4) to (10, 11), you use::
 
     <ESC>[2*x<ESC>[4;3;11;10;44$r<ESC>[*x

docs/desktop-notifications.rst

@@ -5,21 +5,20 @@ Desktop notifications
 =======================
 
 |kitty| implements an extensible escape code (OSC 99) to show desktop
-notifications. It is easy to use from shell scripts and fully extensible to
+notifications. It is easy to use from shell scripts and fully extensible to show
-show title and body.  Clicking on the notification can optionally focus the
+title and body. Clicking on the notification can optionally focus the window it
-window it came from, and/or send an escape code back to the application running
+came from, and/or send an escape code back to the application running in that
-in that window.
+window.
 
-The design of the escape code is partially based on the discussion in
+The design of the escape code is partially based on the discussion in the
-the defunct
+defunct `terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`__
-`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
 
 The escape code has the form::
 
     <OSC> 99 ; metadata ; payload <terminator>
 
 Here ``<OSC>`` is :code:`<ESC>]` and ``<terminator>`` is
-:code:`<ESC><backslash>`.  The metadata is a section of colon separated
+:code:`<ESC><backslash>`. The ``metadata`` is a section of colon separated
 :code:`key=value` pairs. Every key must be a single character from the set
 :code:`a-zA-Z` and every value must be a word consisting of characters from
 the set :code:`a-zA-Z0-9-_/\+.,(){}[]*&^%$#@!`~`. The payload must be
@@ -45,28 +44,28 @@ The design of the escape code is fundamentally chunked, this is because
 different terminal emulators have different limits on how large a single escape
 code can be. Chunking is accomplished by the ``i`` and ``d`` keys. The ``i``
 key is the *notification id* which can be any string containing the characters
-``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and can only take the
-can only take the values ``0`` and ``1``. A value of ``0`` means the
+values ``0`` and ``1``. A value of ``0`` means the notification is not yet done
-notification is not yet done and the terminal emulator should hold off
+and the terminal emulator should hold off displaying it. A value of ``1`` means
-displaying it. A value of ``1`` means the notification is done, and should be
+the notification is done, and should be displayed. You can specify the title or
-displayed. You can specify the title or body multiple times and the terminal
+body multiple times and the terminal emulator will concatenate them, thereby
-emulator will concatenate them, thereby allowing arbitrarily long text
+allowing arbitrarily long text (terminal emulators are free to impose a sensible
-(terminal emulators are free to impose a sensible limit to avoid
+limit to avoid Denial-of-Service attacks). The size of the payload must be no
-Denial-of-Service attacks).
+longer than ``2048`` bytes, *before being encoded*.
 
 Both the ``title`` and ``body`` payloads must be either UTF-8 encoded plain
-text with no embedded escape codes, or UTF-8 text that is base64 encoded, in
+text with no embedded escape codes, or UTF-8 text that is Base64 encoded, in
 which case there must be an ``e=1`` key in the metadata to indicate the payload
-is base64 encoded.
+is Base64 encoded.
 
 When the user clicks the notification, a couple of things can happen, the
 terminal emulator can focus the window from which the notification came, and/or
 it can send back an escape code to the application indicating the notification
-was activated. This is controlled by the ``a`` key which takes a comma
+was activated. This is controlled by the ``a`` key which takes a comma separated
-separated set of values, ``report`` and ``focus``. The value ``focus`` means
+set of values, ``report`` and ``focus``. The value ``focus`` means focus the
-focus the window from which the notification was issued and is the default.
+window from which the notification was issued and is the default. ``report``
-``report`` means send an escape code back to the application. The format of the
+means send an escape code back to the application. The format of the returned
-returned escape code is::
+escape code is::
 
     <OSC> 99 ; i=identifier ; <terminator>
 
@@ -87,9 +86,9 @@ to display it based on what it does understand.
 
 .. note::
    It is possible to extend this escape code to allow specifying an icon for
-   the notification, however, given that some platforms, such as macOS, dont
+   the notification, however, given that some platforms, such as legacy versions
-   allow displaying custom icons on a notification, at all, it was decided to
+   of macOS, don't allow displaying custom images on a notification, it was
-   leave it out of the spec for the time being.
+   decided to leave it out of the spec for the time being.
 
    Similarly, features such as scheduled notifications could be added in future
    revisions.
@@ -107,7 +106,7 @@ Key      Value                 Default    Description
 ``d``    ``0`` or ``1``        ``1``      Indicates if the notification is
                                           complete or not.
 
-``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is base64 encoded UTF-8,
+``e``    ``0`` or ``1``        ``0``      If set to ``1`` means the payload is Base64 encoded UTF-8,
                                           otherwise it is plain UTF-8 text with no C0 control codes in it
 
 ``i``    ``[a-zA-Z0-9-_+.]``   ``0``      Identifier for the notification
@@ -118,5 +117,6 @@ Key      Value                 Default    Description
 
 
 .. note::
-   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
+   |kitty| also supports the `legacy OSC 9 protocol developed by iTerm2
-   desktop notifications.
+   <https://iterm2.com/documentation-escape-codes.html>`__ for desktop
+   notifications.

docs/extract-rst-targets.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python
+# License: GPLv3 Copyright: 2022, Kovid Goyal <kovid at kovidgoyal.net>
+
+import os
+import re
+from typing import Dict, Iterator
+
+tgt_pat = re.compile(r'^.. _(\S+?):$', re.MULTILINE)
+title_pat = re.compile('^(.+)\n[-=^#*]{5,}$', re.MULTILINE)
+
+
+def find_explicit_targets(text: str) -> Iterator[str]:
+    for m in tgt_pat.finditer(text):
+        yield m.group(1)
+
+
+def find_page_title(text: str) -> str:
+    for m in title_pat.finditer(text):
+        return m.group(1)
+    return ''
+
+
+def main() -> Dict[str, Dict[str, str]]:
+    refs = {}
+    docs = {}
+    base = os.path.dirname(os.path.abspath(__file__))
+    for dirpath, dirnames, filenames in os.walk(base):
+        if 'generated' in dirnames:
+            dirnames.remove('generated')
+        for f in filenames:
+            if f.endswith('.rst'):
+                with open(os.path.join(dirpath, f)) as stream:
+                    raw = stream.read()
+                href = os.path.relpath(stream.name, base).replace(os.sep, '/')
+                href = href.rpartition('.')[0] + '/'
+                docs[href.rstrip('/')] = find_page_title(raw)
+                first_line = raw.lstrip('\n').partition('\n')[0]
+                first_target_added = False
+                for explicit_target in find_explicit_targets(raw):
+                    # Shorten the reference link to the top of the page.
+                    # Note that anchor links should still be used in HTML docs
+                    # to allow jumping within the same page.
+                    if not first_target_added:
+                        first_target_added = True
+                        if first_line.startswith(f'.. _{explicit_target}:'):
+                            refs[explicit_target] = href
+                            continue
+                    refs[explicit_target] = href + f'#{explicit_target.replace("_", "-")}'
+    return {'ref': refs, 'doc': docs}
+
+
+if __name__ == '__main__':
+    import json
+    print(json.dumps(main(), indent=2))

docs/faq.rst

@@ -6,117 +6,166 @@ Frequently Asked Questions
 Some special symbols are rendered small/truncated in kitty?
 -----------------------------------------------------------
 
-The number of cells a unicode character takes up are controlled by the unicode
+The number of cells a Unicode character takes up are controlled by the Unicode
-standard.  All characters are rendered in a single cell unless the unicode
+standard. All characters are rendered in a single cell unless the Unicode
 standard says they should be rendered in two cells. When a symbol does not fit,
 it will either be rescaled to be smaller or truncated (depending on how much
 extra space it needs). This is often different from other terminals which just
 let the character overflow into neighboring cells, which is fine if the
 neighboring cell is empty, but looks terrible if it is not.
 
-Some programs, like powerline, vim with fancy gutter symbols/status-bar, etc.
+Some programs, like Powerline, vim with fancy gutter symbols/status-bar, etc.
-misuse unicode characters from the private use area to represent symbols. Often
+use Unicode characters from the private use area to represent symbols. Often
-these symbols are square and should be rendered in two cells.  However, since
+these symbols are wide and should be rendered in two cells. However, since
-private use area symbols all have their width set to one in the unicode
+private use area symbols all have their width set to one in the Unicode
 standard, |kitty| renders them either smaller or truncated. The exception is if
 these characters are followed by a space or empty cell in which case kitty
-makes use of the extra cell to render them in two cells.
+makes use of the extra cell to render them in two cells. This behavior can be
+turned off for specific symbols using :opt:`narrow_symbols`.
 
 
 Using a color theme with a background color does not work well in vim?
 -----------------------------------------------------------------------
 
-First make sure you have not changed the TERM environment variable, it should
+Sadly, vim has very poor out-of-the-box detection for modern terminal features.
-be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
+Furthermore, it `recently broke detection even more <https://github.com/vim/vim/issues/11729>`__.
-does not contain the ``bce`` capability. This is a bug in vim. You can work around
+It kind of, but not really, supports terminfo, except it overrides it with its own hard-coded
-it by adding the following to your vimrc::
+values when it feels like it. Worst of all, it has no ability to detect modern
+features not present in terminfo, at all, even security sensitive ones like
+bracketed paste.
 
+Thankfully, probably as a consequence of this lack of detection, vim allows users to
+configure these low level details. So, to make vim work well with any modern
+terminal, including kitty, add the following to your :file:`~/.vimrc`.
+
+.. code-block:: vim
+
+    " Mouse support
+    set mouse=a
+    set ttymouse=sgr
+    set balloonevalterm
+    " Styled and colored underline support
+    let &t_AU = "\e[58:5:%dm"
+    let &t_8u = "\e[58:2:%lu:%lu:%lum"
+    let &t_Us = "\e[4:2m"
+    let &t_Cs = "\e[4:3m"
+    let &t_ds = "\e[4:4m"
+    let &t_Ds = "\e[4:5m"
+    let &t_Ce = "\e[4:0m"
+    " Strikethrough
+    let &t_Ts = "\e[9m"
+    let &t_Te = "\e[29m"
+    " Truecolor support
+    let &t_8f = "\e[38:2:%lu:%lu:%lum"
+    let &t_8b = "\e[48:2:%lu:%lu:%lum"
+    let &t_RF = "\e]10;?\e\\"
+    let &t_RB = "\e]11;?\e\\"
+    " Bracketed paste
+    let &t_BE = "\e[?2004h"
+    let &t_BD = "\e[?2004l"
+    let &t_PS = "\e[200~"
+    let &t_PE = "\e[201~"
+    " Cursor control
+    let &t_RC = "\e[?12$p"
+    let &t_SH = "\e[%d q"
+    let &t_RS = "\eP$q q\e\\"
+    let &t_SI = "\e[5 q"
+    let &t_SR = "\e[3 q"
+    let &t_EI = "\e[1 q"
+    let &t_VS = "\e[?12l"
+    " Focus tracking
+    let &t_fe = "\e[?1004h"
+    let &t_fd = "\e[?1004l"
+    execute "set <FocusGained>=\<Esc>[I"
+    execute "set <FocusLost>=\<Esc>[O"
+    " Window title
+    let &t_ST = "\e[22;2t"
+    let &t_RT = "\e[23;2t"
+
+    " vim hardcodes background color erase even if the terminfo file does
+    " not contain bce. This causes incorrect background rendering when
+    " using a color theme with a background color in terminals such as
+    " kitty that do not support background color erase.
     let &t_ut=''
 
-See :doc:`here <deccara>` for why |kitty| does not support background color erase.
+These settings must be placed **before** setting the ``colorscheme``. It is
+also important that the value of the vim ``term`` variable is not changed
+after these settings.
 
+I get errors about the terminal being unknown or opening the terminal failing or functional keys like arrow keys don't work?
+-------------------------------------------------------------------------------------------------------------------------------
 
-I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
+These issues all have the same root cause: the kitty terminfo files not being
------------------------------------------------------------------------------------------------------------------------
+available. The most common way this happens is SSHing into a computer that does
-
+not have the kitty terminfo files. The simplest fix for that is running::
-This happens because the |kitty| terminfo files are not available on the server.
-You can ssh in using the following command which will automatically copy the
-terminfo files to the server::
 
     kitty +kitten ssh myserver
 
-This ssh kitten takes all the same command line arguments
+It will automatically copy over the terminfo files and also magically enable
-as ssh, you can alias it to ssh in your shell's rc files to avoid having to
+:doc:`shell integration </shell-integration>` on the remote machine.
-type it each time::
 
-    alias ssh="kitty +kitten ssh"
+This :doc:`ssh kitten <kittens/ssh>` takes all the same command line arguments
+as :program:`ssh`, you can alias it to something small in your shell's rc files
+to avoid having to type it each time::
 
-Remember to also setup :ref:`shell_integration` for completion and other
+    alias s="kitty +kitten ssh"
-niceties.
 
-If for some reason that does not work (typically because the server is using a
+If this does not work, see :ref:`manual_terminfo_copy` for alternative ways to
-non POSIX compliant shell as ``/bin/sh``), you can try using it with ``python``
+get the kitty terminfo files onto a remote computer.
-instead::
 
-    kitty +kitten ssh use-python myserver
+The next most common reason for this is if you are running commands as root
+using :program:`sudo` or :program:`su`. These programs often filter the
+:envvar:`TERMINFO` environment variable which is what points to the kitty
+terminfo files.
 
-If that also fails, perhaps because python is not installed on the remote
+First, make sure the :envvar:`TERM` is set to ``xterm-kitty`` in the sudo
-server, use the following one-liner instead (it
+environment. By default, it should be automatically copied over.
-is slower as it needs to ssh into the server twice, but will work with most
-servers)::
 
-    infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
+If you are using a well maintained Linux distribution, it will have a
+``kitty-terminfo`` package that you can simply install to make the kitty
+terminfo files available system-wide. Then the problem will no longer occur.
 
-If you are behind a proxy (like Balabit) that prevents this, you must redirect the
+Alternately, you can configure :program:`sudo` to preserve :envvar:`TERMINFO`
-1st command to a file, copy that to the server and run ``tic`` manually.  If you
+by running ``sudo visudo`` and adding the following line::
-connect to a server, embedded or Android system that doesn't have ``tic``, copy over
-your local file terminfo to the other system as :file:`~/.terminfo/x/xterm-kitty`.
-
-Really, the correct solution for this is to convince the OpenSSH maintainers to
-have ssh do this automatically, if possible, when connecting to a server, so that
-all terminals work transparently.
-
-If the server is running FreeBSD, or another system that relies on termcap
-rather than terminfo, you will need to convert the terminfo file on your local
-machine by running (on local machine with |kitty|)::
-
-    infocmp -C xterm-kitty
-
-The output of this command is the termcap description, which should be appended
-to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
-command to apply your change (on the server)::
-
-    cap_mkdb /usr/share/misc/termcap
-
-
-Keys such as arrow keys, backspace, delete, home/end, etc. do not work when using su or sudo?
--------------------------------------------------------------------------------------------------
-
-Make sure the TERM environment variable, is ``xterm-kitty``.  And either the
-TERMINFO environment variable points to a directory containing :file:`x/xterm-kitty`
-or that file is under :file:`~/.terminfo/x/`.
-
-Note that ``sudo`` might remove TERMINFO.  Then setting it at the shell prompt can
-be too late, because command line editing may not be reinitialized.  In that case
-you can either ask ``sudo`` to set it or if that is not supported, insert an ``env``
-command before starting the shell, or, if not possible, after sudo start another
-Shell providing the right terminfo path::
-
-    sudo … TERMINFO=$HOME/.terminfo bash -i
-    sudo … env TERMINFO=$HOME/.terminfo bash -i
-    TERMINFO=/home/ORIGINALUSER/.terminfo exec bash -i
-
-You can configure sudo to preserve TERMINFO by running ``sudo
-visudo`` and adding the following line::
 
     Defaults env_keep += "TERM TERMINFO"
 
+If none of these are suitable for you, you can run sudo as follows::
+
+    sudo TERMINFO="$TERMINFO" -s -H
+
+This will start a new root shell with the correct :envvar:`TERMINFO` value from your
+current environment copied over.
+
 If you have double width characters in your prompt, you may also need to
 explicitly set a UTF-8 locale, like::
 
     export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8
 
 
+I cannot use the key combination X in program Y?
+-------------------------------------------------------
+
+First, run::
+
+    kitty +kitten show_key -m kitty
+
+Press the key combination X. If the kitten reports the key press
+that means kitty is correctly sending the key press to terminal programs.
+You need to report the issue to the developer of the terminal program. Most
+likely they have not added support for :doc:`/keyboard-protocol`.
+
+If the kitten does not report it, it means that the key is bound to some action
+in kitty. You can unbind it in :file:`kitty.conf` with:
+
+.. code-block:: conf
+
+   map X no_op
+
+Here X is the keys you press on the keyboard. So for example
+:kbd:`ctrl+shift+1`.
+
+
 How do I change the colors in a running kitty instance?
 ------------------------------------------------------------
 
@@ -131,12 +180,15 @@ You can also define keyboard shortcuts to set colors, for example::
 
     map f1 set_colors --configured /path/to/some/config/file/colors.conf
 
-Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :ref:`at_set-colors`.
+Or you can enable :doc:`remote control <remote-control>` for |kitty| and use
-The shortcut mapping technique has the same syntax as the remote control
+:ref:`at-set-colors`. The shortcut mapping technique has the same syntax as the
-command, for details, see :ref:`at_set-colors`.
+remote control command, for details, see :ref:`at-set-colors`.
+
+To change colors when SSHing into a remote host, use the :opt:`color_scheme
+<kitten-ssh.color_scheme>` setting for the :doc:`ssh kitten <kittens/ssh>`.
 
 Additionally, You can use the
-`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_
+`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`__
 to set colors. Examples of using OSC escape codes to set colors::
 
     Change the default foreground color:
@@ -153,7 +205,7 @@ to set colors. Examples of using OSC escape codes to set colors::
     printf '\x1b]4;n;green\x1b\\'
 
 You can use various syntaxes/names for color specifications in the above
-examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`_
+examples. See `XParseColor <https://linux.die.net/man/3/xparsecolor>`__
 for full details.
 
 If a ``?`` is given rather than a color specification, kitty will respond
@@ -166,14 +218,15 @@ How do I specify command line options for kitty on macOS?
 Apple does not want you to use command line options with GUI applications. To
 workaround that limitation, |kitty| will read command line options from the file
 :file:`<kitty config dir>/macos-launch-services-cmdline` when it is launched
-from the GUI, i.e. by clicking the |kitty| application icon or using ``open -a kitty``.
+from the GUI, i.e. by clicking the |kitty| application icon or using
-Note that this file is *only read* when running via the GUI.
+``open -a kitty``. Note that this file is *only read* when running via the GUI.
 
-You can, of course, also run |kitty| from a terminal with command line options, using:
+You can, of course, also run |kitty| from a terminal with command line options,
-:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+using: :file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+
+And within |kitty| itself, you can always run |kitty| using just ``kitty`` as it
+cleverly adds itself to the :envvar:`PATH`.
 
-And within |kitty| itself, you can always run |kitty| using just `kitty` as it
-cleverly adds itself to the ``PATH``.
 
 I catted a binary file and now kitty is hung?
 -----------------------------------------------
@@ -181,10 +234,10 @@ I catted a binary file and now kitty is hung?
 **Never** output unknown binary data directly into a terminal.
 
 Terminals have a single channel for both data and control. Certain bytes
-are control codes. Some of these control codes are of arbitrary length, so
+are control codes. Some of these control codes are of arbitrary length, so if
-if the binary data you output into the terminal happens to contain the starting
+the binary data you output into the terminal happens to contain the starting
-sequence for one of these control codes, the terminal will hang waiting for
+sequence for one of these control codes, the terminal will hang waiting for the
-the closing sequence. Press :kbd:`ctrl+shift+delete` to reset the terminal.
+closing sequence. Press :sc:`reset_terminal` to reset the terminal.
 
 If you do want to cat unknown data, use ``cat -v``.
 
@@ -192,29 +245,36 @@ If you do want to cat unknown data, use ``cat -v``.
 kitty is not able to use my favorite font?
 ---------------------------------------------
 
-|kitty| achieves its stellar performance by caching alpha masks of each
+|kitty| achieves its stellar performance by caching alpha masks of each rendered
-rendered character on the GPU, and rendering them all in parallel. This means
+character on the GPU, and rendering them all in parallel. This means it is a
-it is a strictly character cell based display. As such it can use only
+strictly character cell based display. As such it can use only monospace fonts,
-monospace fonts, since every cell in the grid has to be the same size.
+since every cell in the grid has to be the same size. Furthermore, it needs
-Furthermore, it needs fonts to be freely resizable, so it does not support
+fonts to be freely resizable, so it does not support bitmapped fonts.
-bitmapped fonts.
 
 .. note::
-   If you are trying to use a font patched with NERD font symbols, dont do that
+   If you are trying to use a font patched with `Nerd Fonts
-   as patching destroys fonts. There is no need, simply install the standalone
+   <https://nerdfonts.com/>`__ symbols, don't do that as patching destroys
-   NERD font, kitty should pick up symbols from it automatically, and you can
+   fonts. There is no need, simply install the standalone ``Symbols Nerd Font Mono``
-   tell it to do so explicitly in case it doesnt with the :opt:`symbol_map`
+   (the file :file:`NerdFontsSymbolsOnly.zip` from the `Nerd Fonts releases page
-   directive::
+   <https://github.com/ryanoasis/nerd-fonts/releases>`__). kitty should pick up
+   symbols from it automatically, and you can tell it to do so explicitly in
+   case it doesn't with the :opt:`symbol_map` directive::
 
-        symbol_map U+23FB-U+23FE,U+2B58,U+E200-U+E2A9,U+E0A0-U+E0A3,U+E0B0-U+E0BF,U+E0C0-U+E0C8,U+E0CC-U+E0CF,U+E0D0-U+E0D2,U+E0D4,U+E700-U+E7C5,U+F000-U+F2E0,U+2665,U+26A1,U+F400-U+F4A8,U+F67C,U+E000-U+E00A,U+F300-U+F313,U+E5FA-U+E62B Symbols Nerd Font
+        # Nerd Fonts v2.3.3
 
-If your font is not listed in ``kitty list-fonts`` it means that it is not
+        symbol_map U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E6AA,U+E700-U+E7C5,U+EA60-U+EBEB,U+F000-U+F2E0,U+F300-U+F32F,U+F400-U+F4A9,U+F500-U+F8FF,U+F0001-U+F1AF0 Symbols Nerd Font Mono
-monospace or is a bitmapped font. On Linux you can list all monospace fonts with::
+
+   Those Unicode symbols beyond the ``E000-F8FF`` Unicode private use area are
+   not included.
+
+If your font is not listed in ``kitty +list-fonts`` it means that it is not
+monospace or is a bitmapped font. On Linux you can list all monospace fonts
+with::
 
     fc-list : family spacing outline scalable | grep -e spacing=100 -e spacing=90 | grep -e outline=True | grep -e scalable=True
 
-Note that the spacing property is calculated by fontconfig based on actual
+Note that the spacing property is calculated by fontconfig based on actual glyph
-glyph widths in the font. If for some reason fontconfig concludes your favorite
+widths in the font. If for some reason fontconfig concludes your favorite
 monospace font does not have ``spacing=100`` you can override it by using the
 following :file:`~/.config/fontconfig/fonts.conf`::
 
@@ -236,7 +296,7 @@ command to rebuild your fontconfig cache::
 
     fc-cache -r
 
-Then, the font will be available in ``kitty list-fonts``.
+Then, the font will be available in ``kitty +list-fonts``.
 
 
 How can I assign a single global shortcut to bring up the kitty terminal?
@@ -254,7 +314,7 @@ I do not like the kitty icon!
 There are many alternate icons available, click on an icon to visit its
 homepage:
 
-.. image:: https://github.com/k0nserv/kitty-icon/raw/main/icon_512x512.png
+.. image:: https://github.com/k0nserv/kitty-icon/raw/main/kitty.iconset/icon_256x256.png
    :target: https://github.com/k0nserv/kitty-icon
    :width: 256
 
@@ -270,13 +330,52 @@ homepage:
    :target: https://github.com/hristost/kitty-alternative-icon
    :width: 256
 
-On macOS you can change the icon by following the steps:
+.. image:: https://github.com/igrmk/whiskers/raw/main/whiskers.svg
+   :target: https://github.com/igrmk/whiskers
+   :width: 256
 
-#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+i`
+.. image:: https://github.com/samholmes/whiskers/raw/main/whiskers.png
+   :target: https://github.com/samholmes/whiskers
+   :width: 256
+
+.. image:: https://github.com/eccentric-j/eccentric-icons/raw/main/icons/kitty-terminal/2d/kitty-preview.png
+   :target: https://github.com/eccentric-j/eccentric-icons
+   :width: 256
+
+.. image:: https://github.com/eccentric-j/eccentric-icons/raw/main/icons/kitty-terminal/3d/kitty-preview.png
+   :target: https://github.com/eccentric-j/eccentric-icons
+   :width: 256
+
+On macOS you can put :file:`kitty.app.icns` or :file:`kitty.app.png` in the
+:ref:`kitty configuration directory <confloc>`, and this icon will be applied
+automatically at startup. Unfortunately, Apple's Dock does not change its
+cached icon so the custom icon will revert when kitty is quit. Run the
+following to force the Dock to update its cached icons:
+
+.. code-block:: sh
+
+    rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock
+
+If you prefer not to keep a custom icon in the kitty config folder, you can
+also set it with the following command:
+
+.. code-block:: sh
+
+    # Set kitty.icns as the icon for currently running kitty
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_app_icon; import sys; cocoa_set_app_icon(*sys.argv[1:]); print("OK")' kitty.icns
+
+    # Set the icon for app bundle specified by the path
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_app_icon; import sys; cocoa_set_app_icon(*sys.argv[1:]); print("OK")' /path/to/icon.png /Applications/kitty.app
+
+You can also change the icon manually by following the steps:
+
+#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+I`
 #. Drag :file:`kitty.icns` onto the application icon in the kitty info pane
-#. Delete the icon cache and restart Dock::
+#. Delete the icon cache and restart Dock:
 
-    $ rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock
+.. code-block:: sh
+
+    rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock
 
 
 How do I map key presses in kitty to different keys in the terminal program?
@@ -292,7 +391,14 @@ the :sc:`send_text <send_text>` you can use the ``show_key`` kitten. Run::
 
     kitty +kitten show_key
 
-Then press the key you want to emulate.
+Then press the key you want to emulate. Note that this kitten will only show
+keys that actually reach the terminal program, in particular, keys mapped to
+actions in kitty will not be shown. To check those first map them to
+:ac:`no_op`. You can also start a kitty instance without any shortcuts to
+interfere::
+
+    kitty -o clear_all_shortcuts=yes kitty +kitten show_key
+
 
 How do I open a new window or tab with the same working directory as the current window?
 --------------------------------------------------------------------------------------------
@@ -319,8 +425,8 @@ variables which kitty will now inherit.
 You need to make sure that the environment variables you define in your shell's
 rc files are either also defined system wide or via the :opt:`env` directive in
 :file:`kitty.conf`. Common environment variables that cause issues are those
-related to localization, such as ``LANG, LC_*`` and loading of configuration
+related to localization, such as :envvar:`LANG`, ``LC_*`` and loading of
-files such as ``XDG_*, KITTY_CONFIG_DIRECTORY``.
+configuration files such as ``XDG_*``, :envvar:`KITTY_CONFIG_DIRECTORY`.
 
 To see the environment variables that kitty sees, you can add the following
 mapping to :file:`kitty.conf`::
@@ -337,40 +443,42 @@ sorts of places where they may or may not work.
 I am using tmux and have a problem
 --------------------------------------
 
-First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`, do
+First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`,
-not use them, if at all possible. kitty contains features that do all of what
+do not use them, if at all possible. kitty contains features that do all of what
 tmux does, but better, with the exception of remote persistence (:iss:`391`).
 If you still want to use tmux, read on.
 
 Image display will not work, see `tmux issue
-<https://github.com/tmux/tmux/issues/1391>`_.
+<https://github.com/tmux/tmux/issues/1391>`__.
 
-Using ancient versions of tmux such as 1.8 will
+Using ancient versions of tmux such as 1.8 will cause gibberish on screen when
-cause gibberish on screen when pressing keys (:iss:`3541`).
+pressing keys (:iss:`3541`).
 
-If you are using tmux with multiple terminals or you start it under one
+If you are using tmux with multiple terminals or you start it under one terminal
-terminal and then switch to another and these terminals have different TERM
+and then switch to another and these terminals have different :envvar:`TERM`
-variables, tmux will break. You will need to restart it as tmux does not
+variables, tmux will break. You will need to restart it as tmux does not support
-support multiple terminfo definitions.
+multiple terminfo definitions.
 
 If you use any of the advanced features that kitty has innovated, such as
-styled underlines, desktop notifications, extended keyboard support, etc.
+:doc:`styled underlines </underlines>`, :doc:`desktop notifications
-they may or may not work, depending on the whims of tmux's maintainer, your
+</desktop-notifications>`, :doc:`extended keyboard support
-version of tmux, etc.
+</keyboard-protocol>`, etc. they may or may not work, depending on the whims of
+tmux's maintainer, your version of tmux, etc.
 
 
 I opened and closed a lot of windows/tabs and top shows kitty's memory usage is very high?
 -------------------------------------------------------------------------------------------
 
-``top`` is not a good way to measure process memory usage. That is because on
+:program:`top` is not a good way to measure process memory usage. That is
-modern systems, when allocating memory to a process, the C library functions
+because on modern systems, when allocating memory to a process, the C library
-will typically allocate memory in large blocks, and give the process chunks of
+functions will typically allocate memory in large blocks, and give the process
-these blocks. When the process frees a chunk, the C library will not
+chunks of these blocks. When the process frees a chunk, the C library will not
 necessarily release the underlying block back to the OS. So even though the
-application has released the memory, ``top`` will still claim the process is
+application has released the memory, :program:`top` will still claim the process
-using it.
+is using it.
 
-To check for memory leaks, instead use a tool like ``valgrind``. Run::
+To check for memory leaks, instead use a tool like `Valgrind
+<https://valgrind.org/>`__. Run::
 
     PYTHONMALLOC=malloc valgrind --tool=massif kitty
 
@@ -383,18 +491,19 @@ that window, maybe run yes or find again. Then quit kitty and run::
 You will see the allocations graph goes up when you opened the windows, then
 goes back down when you closed them, indicating there were no memory leaks.
 
-For those interested, you can get a similar profile out of ``valgrind`` as you get
+For those interested, you can get a similar profile out of :program:`valgrind`
-with ``top`` by adding ``--pages-as-heap=yes`` then you will see that memory
+as you get with :program:`top` by adding ``--pages-as-heap=yes`` then you will
-allocated in malloc is not freed in free. This can be further refined if you
+see that memory allocated in malloc is not freed in free. This can be further
-use `glibc`` as your C library by setting the environment variable
+refined if you use ``glibc`` as your C library by setting the environment
-``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free memory
+variable ``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free
-allocated in sizes of more than 64 bytes. With this set, memory usage will
+memory allocated in sizes of more than 64 bytes. With this set, memory usage
-climb high, then fall when closing windows, but not fall all the way back. The
+will climb high, then fall when closing windows, but not fall all the way back.
-remaining used memory can be investigated using valgrind again, and it will
+The remaining used memory can be investigated using valgrind again, and it will
 come from arenas in the GPU drivers and the per thread arenas glibc's malloc
-maintains. These too allocate memory in large blocks and dont release it back
+maintains. These too allocate memory in large blocks and don't release it back
 to the OS immediately.
 
+
 Why does kitty sometimes start slowly on my Linux system?
 -------------------------------------------------------------------------------------------
 
@@ -418,4 +527,4 @@ The correct command will depend on your situation and hardware.
 :file:`libEGL_mesa.so` and ignore :file:`libEGL_nvidia.so` also available on the
 system, which will wake the NVIDIA card during device enumeration.
 ``MESA_LOADER_DRIVER_OVERRIDE`` also assures that Mesa won't offer any NVIDIA
-card during enumeration, and will instead just use `/lib/dri/radeonsi_dri.so`.
+card during enumeration, and will instead just use :file:`radeonsi_dri.so`.

docs/glossary.rst

@@ -30,14 +30,26 @@ Glossary
    overlay
       An *overlay window* is a :term:`kitty window <window>` that is placed on
       top of an existing kitty window, entirely covering it. Overlays are used
-      throught kitty, for example, to display the :ref:`the scrollback buffer <scrollback>`,
+      throughout kitty, for example, to display the :ref:`the scrollback buffer <scrollback>`,
       to display :doc:`hints </kittens/hints>`, for :doc:`unicode input
-      </kittens/unicode_input>` etc.
+      </kittens/unicode_input>` etc. Normal overlays are meant for short
+      duration popups and so are not considered the :italic:`active window`
+      when determining the current working directory or getting input text for
+      kittens, launch commands, etc. To create an overlay considered as a
+      :italic:`main window` use the :code:`overlay-main` argument to
+      :doc:`launch`.
 
    hyperlinks
       Terminals can have hyperlinks, just like the internet. In kitty you can
       :doc:`control exactly what happens <open_actions>` when clicking on a
-      hyperlink, based on the type of link and its URL.
+      hyperlink, based on the type of link and its URL. See also `Hyperlinks in terminal
+      emulators <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`__.
+
+   kittens
+      Small, independent statically compiled command line programs that are designed to run
+      inside kitty windows and provide it with lots of powerful and flexible
+      features such as viewing images, connecting conveniently to remote
+      computers, transferring files, inputting unicode characters, etc.
 
 .. _env_vars:
 
@@ -45,6 +57,7 @@ Environment variables
 ------------------------
 
 Variables that influence kitty behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. envvar:: KITTY_CONFIG_DIRECTORY
 
@@ -57,11 +70,17 @@ Variables that influence kitty behavior
    Controls where kitty stores cache files. Defaults to :file:`~/.cache/kitty`
    or :file:`~/Library/Caches/kitty` on macOS.
 
+.. envvar:: KITTY_RUNTIME_DIRECTORY
+
+   Controls where kitty stores runtime files like sockets. Defaults to
+   the :code:`XDG_RUNTIME_DIR` environment variable if that is defined
+   otherwise the run directory inside the kitty cache directory is used.
+
 .. envvar:: VISUAL
 
-   The terminal editor (such as ``vi`` or ``nano``) kitty uses, when, for
+   The terminal based text editor (such as :program:`vi` or :program:`nano`)
-   instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
+   kitty uses, when, for instance, opening :file:`kitty.conf` in response to
-
+   :sc:`edit_config_file`.
 
 .. envvar:: EDITOR
 
@@ -78,84 +97,129 @@ Variables that influence kitty behavior
    is possible for the autodiscovery to fail; the default Wayland XKB mappings
    are used in this case. See :pull:`3943` for details.
 
+.. envvar:: SSH_ASKPASS
+
+   Specify the program for SSH to ask for passwords. When this is set, :doc:`ssh
+   kitten </kittens/ssh>` will use this environment variable by default. See
+   :opt:`askpass <kitten-ssh.askpass>` for details.
+
+.. envvar:: KITTY_CLONE_SOURCE_CODE
+
+   Set this to some shell code that will be executed in the cloned window with
+   :code:`eval` when :ref:`clone-in-kitty <clone_shell>` is used.
+
+.. envvar:: KITTY_CLONE_SOURCE_PATH
+
+   Set this to the path of a file that will be sourced in the cloned window when
+   :ref:`clone-in-kitty <clone_shell>` is used.
+
+.. envvar:: KITTY_DEVELOP_FROM
+
+   Set this to the directory path of the kitty source code and its Python code
+   will be loaded from there. Only works with official binary builds.
+
+.. envvar:: KITTY_RC_PASSWORD
+
+   Set this to a pass phrase to use the ``kitty @`` remote control command with
+   :opt:`remote_control_password`.
+
 
 Variables that kitty sets when running child programs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. envvar:: LANG
 
-   This is set only on macOS, and only if the country and language from the
+   This is only set on macOS. If the country and language from the macOS user
-   macOS user settings form a valid locale.
+   settings form an invalid locale, it will be set to :code:`en_US.UTF-8`.
 
+.. envvar:: PATH
+
+   kitty prepends itself to the PATH of its own environment to ensure the
+   functions calling :program:`kitty` will work properly.
 
 .. envvar:: KITTY_WINDOW_ID
 
    An integer that is the id for the kitty :term:`window` the program is running in.
    Can be used with the :doc:`kitty remote control facility <remote-control>`.
 
-
 .. envvar:: KITTY_PID
 
    An integer that is the process id for the kitty process in which the program
    is running. Allows programs to tell kitty to reload its config by sending it
    the SIGUSR1 signal.
 
+.. envvar:: KITTY_PUBLIC_KEY
+
+   A public key that programs can use to communicate securely with kitty using
+   the remote control protocol. The format is: :code:`protocol:key data`.
 
 .. envvar:: WINDOWID
 
    The id for the :term:`OS Window <os_window>` the program is running in. Only available
    on platforms that have ids for their windows, such as X11 and macOS.
 
-
 .. envvar:: TERM
 
    The name of the terminal, defaults to ``xterm-kitty``. See :opt:`term`.
 
-
 .. envvar:: TERMINFO
 
    Path to a directory containing the kitty terminfo database.
 
-
 .. envvar:: KITTY_INSTALLATION_DIR
 
    Path to the kitty installation directory.
 
-
 .. envvar:: COLORTERM
 
    Set to the value ``truecolor`` to indicate that kitty supports 16 million
    colors.
 
-
 .. envvar:: KITTY_LISTEN_ON
 
    Set when the :doc:`remote control <remote-control>` facility is enabled and
    the a socket is used for control via :option:`kitty --listen-on` or :opt:`listen_on`.
-   Contains the path to the socket. Avoids needs to use :option:`kitty @ --to` when
+   Contains the path to the socket. Avoid the need to use :option:`kitty @ --to` when
    issuing remote control commands.
 
-
 .. envvar:: KITTY_PIPE_DATA
 
    Set to data describing the layout of the screen when running child
    programs using :option:`launch --stdin-source` with the contents of the
    screen/scrollback piped to them.
 
-
 .. envvar:: KITTY_CHILD_CMDLINE
 
    Set to the command line of the child process running in the kitty
    window when calling the notification callback program on terminal bell, see
    :opt:`command_on_bell`.
 
-
 .. envvar:: KITTY_COMMON_OPTS
 
    Set with the values of some common kitty options when running
-   kittens, so kittens can use them without needing to load kitty.conf.
+   kittens, so kittens can use them without needing to load :file:`kitty.conf`.
-
 
 .. envvar:: KITTY_SHELL_INTEGRATION
 
    Set when enabling :ref:`shell_integration`. It is automatically removed by
    the shell integration scripts.
+
+.. envvar:: ZDOTDIR
+
+   Set when enabling :ref:`shell_integration` with :program:`zsh`, allowing
+   :program:`zsh` to automatically load the integration script.
+
+.. envvar:: XDG_DATA_DIRS
+
+   Set when enabling :ref:`shell_integration` with :program:`fish`, allowing
+   :program:`fish` to automatically load the integration script.
+
+.. envvar:: ENV
+
+   Set when enabling :ref:`shell_integration` with :program:`bash`, allowing
+   :program:`bash` to automatically load the integration script.
+
+.. envvar:: KITTY_OS
+
+   Set when using the include directive in kitty.conf. Can take values:
+   ``linux``, ``macos``, ``bsd``.

docs/graphics-protocol.rst

@@ -28,24 +28,29 @@ alpha-blending and text over graphics.
 Some programs and libraries that use the kitty graphics protocol:
 
 * `termpdf.py <https://github.com/dsanson/termpdf.py>`_ - a terminal PDF/DJVU/CBR viewer
-* `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with
+* `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with image previews
-  image previews, see this `PR <https://github.com/ranger/ranger/pull/1077>`_
 * :doc:`kitty-diff <kittens/diff>` - a side-by-side terminal diff program with support for images
+* `tpix <https://github.com/jesvedberg/tpix>`_ - a statically compiled binary that can be used to display images and easily installed on remote servers without root access
+* `mpv <https://github.com/mpv-player/mpv/commit/874e28f4a41a916bb567a882063dd2589e9234e1>`_ - A video player that can play videos in the terminal
 * `pixcat <https://github.com/mirukana/pixcat>`_ - a third party CLI and python library that wraps the graphics protocol
 * `neofetch <https://github.com/dylanaraps/neofetch>`_ - A command line system
   information tool
 * `viu <https://github.com/atanunq/viu>`_ - a terminal image viewer
-* `glkitty <https://github.com/michaeljclark/glkitty>`_ - C library to draw OpenGL shaders in the terminal with a glgears demo
 * `ctx.graphics <https://ctx.graphics/>`_ - Library for drawing graphics
 * `timg <https://github.com/hzeller/timg>`_ - a terminal image and video viewer
 * `notcurses <https://github.com/dankamongmen/notcurses>`_ - C library for terminal graphics with bindings for C++, Rust and Python
 * `rasterm <https://github.com/BourgeoisBear/rasterm>`_  - Go library to display images in the terminal
 * `chafa <https://github.com/hpjansson/chafa>`_  - a terminal image viewer
 * `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_  - view images inside nvim
+* `term-image <https://github.com/AnonymouX47/term-image>`_  - A Python library, CLI and TUI to display and browse images in the terminal
+* `glkitty <https://github.com/michaeljclark/glkitty>`_ - C library to draw OpenGL shaders in the terminal with a glgears demo
+* `twitch-tui <https://github.com/Xithrius/twitch-tui>`_ - Twitch chat in the terminal
 
 Other terminals that have implemented the graphics protocol:
 
 * `WezTerm <https://github.com/wez/wezterm/issues/986>`_
+* `Konsole <https://invent.kde.org/utilities/konsole/-/merge_requests/594>`_
+* `wayst <https://github.com/91861/wayst>`_
 
 
 Getting the window size
@@ -53,7 +58,8 @@ Getting the window size
 
 In order to know what size of images to display and how to position them, the
 client must be able to get the window size in pixels and the number of cells
-per row and column. This can be done by using the ``TIOCGWINSZ`` ioctl.  Some
+per row and column. The cell width is then simply the window size divided by the
+number of rows. This can be done by using the ``TIOCGWINSZ`` ioctl. Some
 code to demonstrate its use
 
 .. tab:: C
@@ -84,6 +90,31 @@ code to demonstrate its use
             'number of rows: {} number of columns: {}'
             'screen width: {} screen height: {}').format(*buf))
 
+.. tab:: Go
+
+    .. code-block:: go
+
+        import "golang.org/x/sys/unix"
+        fd, err := unix.Open(fd, unix.O_NOCTTY|unix.O_CLOEXEC|unix.O_NDELAY|unix.O_RDWR, 0666)
+        sz, err := unix.IoctlGetWinsize(fd, unix.TIOCGWINSZ)
+        fmt.Println("rows: %v columns: %v width: %v height %v", sz.Row, sz.Col, sz.Xpixel, sz.Ypixel)
+
+
+.. tab:: Bash
+
+    .. code-block:: sh
+
+        #!/bin/bash
+
+        # This uses the kitten standalone binary from kitty to get the pixel sizes
+        # since we cant do IOCTLs directly. Fortunately, kitten is a static exe
+        # pre-built for every Unix like OS under the sun.
+
+        builtin read -r rows cols < <(command stty size)
+        IFS=x builtin read -r width height < <(command kitten icat --print-window-size); builtin unset IFS
+        builtin echo "number of rows: $rows number of columns: $cols screen width: $width screen height: $height"
+
+
 Note that some terminals return ``0`` for the width and height values. Such
 terminals should be modified to return the correct values.  Examples of
 terminals that return correct values: ``kitty, xterm``
@@ -97,47 +128,71 @@ kitty.
 A minimal example
 ------------------
 
-Some minimal python code to display PNG images in kitty, using the most basic
+Some minimal code to display PNG images in kitty, using the most basic
 features of the graphics protocol:
 
-.. code-block:: python
+.. tab:: Bash
 
-    import sys
+    .. code-block:: sh
-    from base64 import standard_b64encode
+
+        #!/bin/bash
+        transmit_png() {
+            data=$(base64 "$1")
+            data="${data//[[:space:]]}"
+            builtin local pos=0
+            builtin local chunk_size=4096
+            while [ $pos -lt ${#data} ]; do
+                builtin printf "\e_G"
+                [ $pos = "0" ] && printf "a=T,f=100,"
+                builtin local chunk="${data:$pos:$chunk_size}"
+                pos=$(($pos+$chunk_size))
+                [ $pos -lt ${#data} ] && builtin printf "m=1"
+                [ ${#chunk} -gt 0 ] && builtin printf ";%s" "${chunk}"
+                builtin printf "\e\\"
+            done
+        }
+
+        transmit_png "$1"
+
+.. tab:: Python
+
+    .. code-block:: python
+
+        #!/usr/bin/python
+        import sys
+        from base64 import standard_b64encode
+
+        def serialize_gr_command(**cmd):
+            payload = cmd.pop('payload', None)
+            cmd = ','.join(f'{k}={v}' for k, v in cmd.items())
+            ans = []
+            w = ans.append
+            w(b'\033_G'), w(cmd.encode('ascii'))
+            if payload:
+                w(b';')
+                w(payload)
+            w(b'\033\\')
+            return b''.join(ans)
+
+        def write_chunked(**cmd):
+            data = standard_b64encode(cmd.pop('data'))
+            while data:
+                chunk, data = data[:4096], data[4096:]
+                m = 1 if data else 0
+                sys.stdout.buffer.write(serialize_gr_command(payload=chunk, m=m,
+                                                            **cmd))
+                sys.stdout.flush()
+                cmd.clear()
+
+        with open(sys.argv[-1], 'rb') as f:
+            write_chunked(a='T', f=100, data=f.read())
 
 
-    def serialize_gr_command(**cmd):
+Save this script as :file:`send-png`, then you can use it to display any PNG
-        payload = cmd.pop('payload', None)
-        cmd = ','.join(f'{k}={v}' for k, v in cmd.items())
-        ans = []
-        w = ans.append
-        w(b'\033_G'), w(cmd.encode('ascii'))
-        if payload:
-            w(b';')
-            w(payload)
-        w(b'\033\\')
-        return b''.join(ans)
-
-
-    def write_chunked(**cmd):
-        data = standard_b64encode(cmd.pop('data'))
-        while data:
-            chunk, data = data[:4096], data[4096:]
-            m = 1 if data else 0
-            sys.stdout.buffer.write(serialize_gr_command(payload=chunk, m=m,
-                                                        **cmd))
-            sys.stdout.flush()
-            cmd.clear()
-
-
-    with open(sys.argv[-1], 'rb') as f:
-        write_chunked(a='T', f=100, data=f.read())
-
-
-Save this script as :file:`png.py`, then you can use it to display any PNG
 file in kitty as::
 
-   python png.py file.png
+    chmod +x send-png
+    ./send-png file.png
 
 
 The graphics escape code
@@ -233,7 +288,8 @@ Value of `t`          Meaning
                       the terminal emulator should only delete the file if it
                       is in a known temporary directory, such as :file:`/tmp`,
                       :file:`/dev/shm`, :file:`TMPDIR env var if present` and any platform
-                      specific temporary directories.
+                      specific temporary directories and the file has the
+                      string :code:`tty-graphics-protocol` in its full file path.
 ``s``                 A *shared memory object*, which on POSIX systems is a
                       `POSIX shared memory object <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shm_open.html>`_
                       and on Windows is a
@@ -290,12 +346,13 @@ sequence of escape codes to the terminal emulator::
     <ESC>_Gm=0;<encoded pixel data last chunk><ESC>\
 
 Note that only the first escape code needs to have the full set of control
-codes such as width, height, format etc. Subsequent chunks **must** have
+codes such as width, height, format, etc. Subsequent chunks **must** have only
-only the ``m`` key. The client **must** finish sending all chunks for a single image
+the ``m`` and optionally ``q`` keys. When sending animation frame data, subsequent
-before sending any other graphics related escape codes. Note that the cursor
+chunks **must** also specify the ``a=f`` key. The client **must** finish sending
-position used to display the image **must** be the position when the final chunk is
+all chunks for a single image before sending any other graphics related escape
-received. Finally, terminals must not display anything, until the entire sequence is
+codes. Note that the cursor position used to display the image **must** be the
-received and validated.
+position when the final chunk is received. Finally, terminals must not display
+anything, until the entire sequence is received and validated.
 
 
 Querying support and available transmission mediums
@@ -325,14 +382,14 @@ use the *query action*, set ``a=q``. Then the terminal emulator will try to load
 the image and respond with either OK or an error, as above, but it will not
 replace an existing image with the same id, nor will it store the image.
 
-As of September 2021, kitty and WezTerm are the only terminal emulators to support this
+As of April 2022, kitty and WezTerm are the only terminal emulators to
-graphics protocol. We intend that any terminal emulator that wishes to support
+support this graphics protocol completely, with Konsole and wayst having partial support.
-it can do so. To check if a terminal emulator supports the graphics protocol the best way
+We intend that any terminal emulator that wishes to support it can do so. To
-is to send the above *query action* followed by a request for the
+check if a terminal emulator supports the graphics protocol the best way is to
-`primary device attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you
+send the above *query action* followed by a request for the `primary device
-get back an answer for the device attributes without getting back an answer for
+attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you get back an
-the *query action* the terminal emulator does not support the graphics
+answer for the device attributes without getting back an answer for the *query
-protocol.
+action* the terminal emulator does not support the graphics protocol.
 
 This means that terminal emulators that support the graphics protocol, **must**
 reply to *query actions* immediately without processing other input. Most
@@ -375,7 +432,9 @@ id. To do so add the ``p`` key with a number between ``1`` and ``4294967295``.
 When you specify a placement id, it will be added to the acknowledgement code
 above. Every placement is uniquely identified by the pair of the ``image id``
 and the ``placement id``. If you specify a placement id for an image that does
-not have an id, it will be ignored. An example response::
+not have an id (i.e. has id=0), it will be ignored. In particular this means
+there can exist multiple images with ``image id=0, placement id=0``.
+An example response::
 
     <ESC>_Gi=<image id>,p=<placement id>;OK<ESC>\
 
@@ -412,7 +471,9 @@ they are semi-transparent. You can specify z-index values using the ``z`` key.
 Negative z-index values mean that the images will be drawn under the text. This
 allows rendering of text on top of images. Negative z-index values below
 INT32_MIN/2 (-1,073,741,824) will be drawn under cells with non-default background
-colors.
+colors. If two images with the same z-index overlap then the image with the
+lower id is considered to have the lower z-index. If the images have the same
+z-index and the same id, then the behavior is undefined.
 
 .. note:: After placing an image on the screen the cursor must be moved to the
    right by the number of cols in the image placement rectangle and down by the
@@ -427,6 +488,132 @@ colors.
    Support for the C=1 cursor movement policy
 
 
+.. _graphics_unicode_placeholders:
+
+Unicode placeholders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.28.0
+   Support for image display via Unicode placeholders
+
+You can also use a special Unicode character ``U+10EEEE`` as a placeholder for
+an image. This approach is less flexible, but it allows using images inside
+any host application that supports Unicode and foreground colors (tmux, vim, weechat, etc.)
+and has a way to pass escape codes through to the underlying terminal.
+
+The central idea is that we use a single *Private Use* Unicode character as a
+*placeholder* to indicate to the terminal that an image is supposed to be
+displayed at that cell. Since this character is just normal text, Unicode aware
+application will move it around as needed when they redraw their screens,
+thereby automatically moving the displayed image as well, even though they know
+nothing about the graphics protocol. So an image is first created using the
+normal graphics protocol escape codes (albeit in quiet mode (``q=2``) so that there are
+no responses from the terminal that could confuse the host application). Then,
+the actual image is displayed by getting the host application to emit normal
+text consisting of ``U+10EEEE`` and various diacritics (Unicode combining
+characters) and colors.
+
+To use it, first create an image as you would normally with the graphics
+protocol with (``q=2``), but do not create a placement for it, that is, do not
+display it. Then, create a *virtual image placement* by specifying ``U=1`` and
+the desired number of lines and columns::
+
+    <ESC>_Ga=p,U=1,i=<image_id>,c=<columns>,r=<rows><ESC>\
+
+The creation of the placement need not be a separate escape code, it can be
+combined with ``a=T`` to both transmit and create the virtual placement with a
+single code.
+
+The image will eventually be fit to the specified rectangle, its aspect ratio
+preserved. Finally, the image can be actually displayed by using the
+placeholder character, encoding the image ID in its foreground color. The row
+and column values are specified with diacritics listed in
+:download:`rowcolumn-diacritics.txt <../rowcolumn-diacritics.txt>`.  For
+example, here is how you can print a ``2x2`` placeholder for image ID ``42``:
+
+.. code-block:: sh
+
+    printf "\e[38;5;42m\U10EEEE\U0305\U0305\U10EEEE\U0305\U030D\e[39m\n"
+    printf "\e[38;5;42m\U10EEEE\U030D\U0305\U10EEEE\U030D\U030D\e[39m\n"
+
+Here, ``U+305`` is the diacritic corresponding to the number ``0``
+and ``U+30D`` corresponds to ``1``. So these two commands create the following
+``2x2`` placeholder:
+
+========== ==========
+(0, 0)     (1, 0)
+(1, 0)     (1, 1)
+========== ==========
+
+This will cause the image with ID ``42`` to be displayed in a ``2x2`` grid.
+Ideally, you would print out as many cells as the number of rows and columns
+specified when creating the virtual placement, but in case of a mismatch only
+part of the image will be displayed.
+
+By using only the foreground color for image ID you are limited to either 8-bit IDs in 256 color
+mode or 24-bit IDs in true color mode. Since IDs are in a global namespace
+there can easily be collisions. If you need more bits for the image
+ID, you can specify the most significant byte via a third diacritic. For
+example, this is the placeholder for the image ID ``33554474 = 42 + (2 << 24)``:
+
+.. code-block:: sh
+
+    printf "\e[38;5;42m\U10EEEE\U0305\U0305\U030E\U10EEEE\U0305\U030D\U030E\n"
+    printf "\e[38;5;42m\U10EEEE\U030D\U0305\U030E\U10EEEE\U030D\U030D\U030E\n"
+
+Here, ``U+30E`` is the diacritic corresponding to the number ``2``.
+
+You can also specify a placement ID using the underline color (if it's omitted
+or zero, the terminal may choose any virtual placement of the given image). The
+background color is interpreted as the background color, visible if the image is
+transparent. Other text attributes are reserved for future use.
+
+Row, column and most significant byte diacritics may also be omitted, in which
+case the placeholder cell will inherit the missing values from the placeholder
+cell to the left, following the algorithm:
+
+- If no diacritics are present, and the previous placeholder cell has the same
+  foreground and underline colors, then the row of the current cell will be the
+  row of the cell to the left, the column will be the column of the cell to the
+  left plus one, and the most significant image ID byte will be the most
+  significant image ID byte of the cell to the left.
+- If only the row diacritic is present, and the previous placeholder cell has
+  the same row and the same foreground and underline colors, then the column of
+  the current cell will be the column of the cell to the left plus one, and the
+  most significant image ID byte will be the most significant image ID byte of
+  the cell to the left.
+- If only the row and column diacritics are present, and the previous
+  placeholder cell has the same row, the same foreground and underline colors,
+  and its column is one less than the current column, then the most significant
+  image ID byte of the current cell will be the most significant image ID byte
+  of the cell to the left.
+
+These rules are applied left-to-right, which allows specifying only row
+diacritics of the first column, i.e. here is a 2 rows by 3 columns placeholder:
+
+.. code-block:: sh
+
+    printf "\e[38;5;42m\U10EEEE\U0305\U10EEEE\U10EEEE\n"
+    printf "\e[38;5;42m\U10EEEE\U030D\U10EEEE\U10EEEE\n"
+
+This will not work for horizontal scrolling and overlapping images since the two
+given rules will fail to guess the missing information. In such cases, the
+terminal may apply other heuristics (but it doesn't have to).
+
+It is important to distinguish between virtual image placements and real images
+displayed on top of Unicode placeholders. Virtual placements are invisible and only play
+the role of prototypes for real images. Virtual placements can be deleted by a
+deletion command only when the `d` key is equal to ``i``, ``I``, ``n`` or ``N``.
+The key values ``a``, ``c``, ``p``, ``q``, ``x``, ``y``, ``z`` and their capital
+variants never affect virtual placements because they do not have a physical
+location on the screen.
+
+Real images displayed on top of Unicode placeholders are not considered
+placements from the protocol perspective. They cannot be manipulated using
+graphics commands, instead they should be moved, deleted, or modified by
+manipulating the underlying Unicode placeholder as normal text.
+
+
 Deleting images
 ---------------------
 
@@ -745,6 +932,8 @@ Key      Value                 Default    Description
 ``r``    Positive integer      ``0``      The number of rows to display the image over
 ``C``    Positive integer      ``0``      Cursor movement policy. ``0`` is the default, to move the cursor to after the image.
                                           ``1`` is to not move the cursor at all when placing the image.
+``U``    Positive integer      ``0``      Set to ``1`` to create a virtual placement for a Unicode placeholder.
+                                          ``1`` is to not move the cursor at all when placing the image.
 ``z``    32-bit integer        ``0``      The *z-index* vertical stacking order of the image
 
 **Keys for animation frame loading**

docs/installer.py

@@ -1,261 +0,0 @@
-#!/usr/bin/env python3
-# vim:fileencoding=utf-8
-# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
-
-from __future__ import (
-    absolute_import, division, print_function, unicode_literals
-)
-
-import atexit
-import json
-import os
-import platform
-import re
-import shlex
-import shutil
-import subprocess
-import sys
-import tempfile
-
-py3 = sys.version_info[0] > 2
-is64bit = platform.architecture()[0] == '64bit'
-is_macos = 'darwin' in sys.platform.lower()
-is_linux_arm = is_linux_arm64 = False
-if is_macos:
-    mac_ver = tuple(map(int, platform.mac_ver()[0].split('.')))
-    if mac_ver[:2] < (10, 12):
-        raise SystemExit('Your version of macOS is too old, at least 10.12 is required')
-else:
-    machine = (os.uname()[4] or '').lower()
-    if machine.startswith('arm') or machine.startswith('aarch64'):
-        is_linux_arm = True
-        is_linux_arm64 = machine.startswith('arm64') or machine.startswith('aarch64')
-
-try:
-    __file__
-    from_file = True
-except NameError:
-    from_file = False
-
-if py3:
-    unicode = str
-    raw_input = input
-    import urllib.request as urllib
-
-    def encode_for_subprocess(x):
-        return x
-else:
-    from future_builtins import map
-    import urllib2 as urllib
-
-    def encode_for_subprocess(x):
-        if isinstance(x, unicode):
-            x = x.encode('utf-8')
-        return x
-
-
-def run(*args):
-    if len(args) == 1:
-        args = shlex.split(args[0])
-    args = list(map(encode_for_subprocess, args))
-    ret = subprocess.Popen(args).wait()
-    if ret != 0:
-        raise SystemExit(ret)
-
-
-class Reporter:  # {{{
-
-    def __init__(self, fname):
-        self.fname = fname
-        self.last_percent = 0
-
-    def __call__(self, blocks, block_size, total_size):
-        percent = (blocks*block_size)/float(total_size)
-        report = '\rDownloaded {:.1%}         '.format(percent)
-        if percent - self.last_percent > 0.05:
-            self.last_percent = percent
-            print(report, end='')
-            sys.stdout.flush()
-# }}}
-
-
-def get_release_data(relname='latest'):
-    print('Checking for latest release on GitHub...')
-    req = urllib.Request(
-        'https://api.github.com/repos/kovidgoyal/kitty/releases/' + relname,
-        headers={'Accept': 'application/vnd.github.v3+json'})
-    try:
-        res = urllib.urlopen(req).read().decode('utf-8')
-    except Exception as err:
-        raise SystemExit('Failed to contact {} with error: {}'.format(req.get_full_url(), err))
-    data = json.loads(res)
-    html_url = data['html_url'].replace('/tag/', '/download/').rstrip('/')
-    for asset in data.get('assets', ()):
-        name = asset['name']
-        if is_macos:
-            if name.endswith('.dmg'):
-                return html_url + '/' + name, asset['size']
-        else:
-            if name.endswith('.txz'):
-                if is64bit:
-                    q = '-arm64.txz' if is_linux_arm64 else '-x86_64.txz'
-                    if name.endswith(q):
-                        return html_url + '/' + name, asset['size']
-                else:
-                    if name.endswith('-i686.txz'):
-                        return html_url + '/' + name, asset['size']
-    raise SystemExit('Failed to find the installer package on github')
-
-
-def do_download(url, size, dest):
-    print('Will download and install', os.path.basename(dest))
-    reporter = Reporter(os.path.basename(dest))
-
-    # Get content length and check if range is supported
-    rq = urllib.urlopen(url)
-    headers = rq.info()
-    sent_size = int(headers['content-length'])
-    if sent_size != size:
-        raise SystemExit('Failed to download from {} Content-Length ({}) != {}'.format(url, sent_size, size))
-    with open(dest, 'wb') as f:
-        while f.tell() < size:
-            raw = rq.read(8192)
-            if not raw:
-                break
-            f.write(raw)
-            reporter(f.tell(), 1, size)
-    rq.close()
-    if os.path.getsize(dest) < size:
-        raise SystemExit('Download failed, try again later')
-    print('\rDownloaded {} bytes'.format(os.path.getsize(dest)))
-
-
-def clean_cache(cache, fname):
-    for x in os.listdir(cache):
-        if fname not in x:
-            os.remove(os.path.join(cache, x))
-
-
-def download_installer(url, size):
-    fname = url.rpartition('/')[-1]
-    tdir = tempfile.gettempdir()
-    cache = os.path.join(tdir, 'kitty-installer-cache')
-    if not os.path.exists(cache):
-        os.makedirs(cache)
-    clean_cache(cache, fname)
-    dest = os.path.join(cache, fname)
-    if os.path.exists(dest) and os.path.getsize(dest) == size:
-        print('Using previously downloaded', fname)
-        return dest
-    if os.path.exists(dest):
-        os.remove(dest)
-    do_download(url, size, dest)
-    return dest
-
-
-def macos_install(dmg, dest='/Applications', launch=True):
-    mp = tempfile.mkdtemp()
-    atexit.register(shutil.rmtree, mp)
-    run('hdiutil', 'attach', dmg, '-mountpoint', mp)
-    try:
-        os.chdir(mp)
-        app = 'kitty.app'
-        d = os.path.join(dest, app)
-        if os.path.exists(d):
-            shutil.rmtree(d)
-        dest = os.path.join(dest, app)
-        run('ditto', '-v', app, dest)
-        print('Successfully installed kitty into', dest)
-        if launch:
-            run('open', dest)
-    finally:
-        os.chdir('/')
-        run('hdiutil', 'detach', mp)
-
-
-def linux_install(installer, dest=os.path.expanduser('~/.local'), launch=True):
-    dest = os.path.join(dest, 'kitty.app')
-    if os.path.exists(dest):
-        shutil.rmtree(dest)
-    os.makedirs(dest)
-    print('Extracting tarball...')
-    run('tar', '-C', dest, '-xJof', installer)
-    print('kitty successfully installed to', dest)
-    kitty = os.path.join(dest, 'bin', 'kitty')
-    print('Use', kitty, 'to run kitty')
-    if launch:
-        run(kitty, '--detach')
-
-
-def main(dest=None, launch=True, installer=None):
-    if not dest:
-        if is_macos:
-            dest = '/Applications'
-        else:
-            dest = os.path.expanduser('~/.local')
-    if is_linux_arm and not is_linux_arm64:
-        raise SystemExit(
-            'You are running on a 32-bit ARM system. The kitty binaries are only'
-            ' available for 64 bit ARM systems. You will have to build from'
-            ' source.')
-    if not installer:
-        url, size = get_release_data()
-        installer = download_installer(url, size)
-    else:
-        if installer == 'nightly':
-            url, size = get_release_data('tags/nightly')
-            installer = download_installer(url, size)
-        else:
-            installer = os.path.abspath(installer)
-            if not os.access(installer, os.R_OK):
-                raise SystemExit('Could not read from: {}'.format(installer))
-    if is_macos:
-        macos_install(installer, dest=dest, launch=launch)
-    else:
-        linux_install(installer, dest=dest, launch=launch)
-
-
-def script_launch():
-    # To test: python3 -c "import runpy; runpy.run_path('installer.py', run_name='script_launch')"
-    def path(x):
-        return os.path.expandvars(os.path.expanduser(x))
-
-    def to_bool(x):
-        return x.lower() in {'y', 'yes', '1', 'true'}
-
-    type_map = {x: path for x in 'dest installer'.split()}
-    type_map['launch'] = to_bool
-    kwargs = {}
-
-    for arg in sys.argv[1:]:
-        if arg:
-            m = re.match('([a-z_]+)=(.+)', arg)
-            if m is None:
-                raise SystemExit('Unrecognized command line argument: ' + arg)
-            k = m.group(1)
-            if k not in type_map:
-                raise SystemExit('Unrecognized command line argument: ' + arg)
-            kwargs[k] = type_map[k](m.group(2))
-    main(**kwargs)
-
-
-def update_installer_wrapper():
-    # To run: python3 -c "import runpy; runpy.run_path('installer.py', run_name='update_wrapper')" installer.sh
-    with open(__file__, 'rb') as f:
-        src = f.read().decode('utf-8')
-    wrapper = sys.argv[-1]
-    with open(wrapper, 'r+b') as f:
-        raw = f.read().decode('utf-8')
-        nraw = re.sub(r'^# HEREDOC_START.+^# HEREDOC_END', lambda m: '# HEREDOC_START\n{}\n# HEREDOC_END'.format(src), raw, flags=re.MULTILINE | re.DOTALL)
-        if 'update_intaller_wrapper()' not in nraw:
-            raise SystemExit('regex substitute of HEREDOC failed')
-        f.seek(0), f.truncate()
-        f.write(nraw.encode('utf-8'))
-
-
-if __name__ == '__main__' and from_file:
-    main()
-elif __name__ == 'update_wrapper':
-    update_installer_wrapper()
-elif __name__ == 'script_launch':
-    script_launch()

docs/installer.sh

@@ -1,292 +1,176 @@
 #!/bin/sh
-#
-# installer.sh
 # Copyright (C) 2018 Kovid Goyal <kovid at kovidgoyal.net>
 #
 # Distributed under terms of the GPLv3 license.
-#
 
-python=$(command -v python3)
+{ \unalias command; \unset -f command; } >/dev/null 2>&1
-if [ -z "$python" ]; then
+tdir=''
-    python=$(command -v python2)
+cleanup() {
-fi
+    [ -n "$tdir" ] && {
-if [ -z "$python" ]; then
+        command rm -rf "$tdir"
-    python=$(command -v python2.7)
+        tdir=''
-fi
+    }
-if [ -z "$python" ]; then
+}
-    python=$(command -v python)
-fi
-if [ -z "$python" ]; then
-    python=python
-fi
 
-echo Using python executable: $python
+die() {
+    cleanup
+    printf "\033[31m%s\033[m\n\r" "$*" > /dev/stderr;
+    exit 1;
+}
 
-$python -c "import sys; script_launch=lambda:sys.exit('Download of installer failed!'); exec(sys.stdin.read()); script_launch()" "$@" <<'INSTALLER_HEREDOC'
+detect_network_tool() {
-# {{{
+    if command -v curl 2> /dev/null > /dev/null; then
-# HEREDOC_START
+        fetch() {
-#!/usr/bin/env python3
+            command curl -fL "$1"
-# vim:fileencoding=utf-8
+        }
-# License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
+        fetch_quiet() {
-
+            command curl -fsSL "$1"
-from __future__ import (
+        }
-    absolute_import, division, print_function, unicode_literals
+    elif command -v wget 2> /dev/null > /dev/null; then
-)
+        fetch() {
-
+            command wget -O- "$1"
-import atexit
+        }
-import json
+        fetch_quiet() {
-import os
+            command wget --quiet -O- "$1"
-import platform
+        }
-import re
+    else
-import shlex
+        die "Neither curl nor wget available, cannot download kitty"
-import shutil
+    fi
-import subprocess
+}
-import sys
-import tempfile
-
-py3 = sys.version_info[0] > 2
-is64bit = platform.architecture()[0] == '64bit'
-is_macos = 'darwin' in sys.platform.lower()
-is_linux_arm = is_linux_arm64 = False
-if is_macos:
-    mac_ver = tuple(map(int, platform.mac_ver()[0].split('.')))
-    if mac_ver[:2] < (10, 12):
-        raise SystemExit('Your version of macOS is too old, at least 10.12 is required')
-else:
-    machine = (os.uname()[4] or '').lower()
-    if machine.startswith('arm') or machine.startswith('aarch64'):
-        is_linux_arm = True
-        is_linux_arm64 = machine.startswith('arm64') or machine.startswith('aarch64')
-
-try:
-    __file__
-    from_file = True
-except NameError:
-    from_file = False
-
-if py3:
-    unicode = str
-    raw_input = input
-    import urllib.request as urllib
-
-    def encode_for_subprocess(x):
-        return x
-else:
-    from future_builtins import map
-    import urllib2 as urllib
-
-    def encode_for_subprocess(x):
-        if isinstance(x, unicode):
-            x = x.encode('utf-8')
-        return x
 
 
-def run(*args):
+detect_os() {
-    if len(args) == 1:
+    arch=""
-        args = shlex.split(args[0])
+    case "$(command uname)" in
-    args = list(map(encode_for_subprocess, args))
+        'Darwin') OS="macos";;
-    ret = subprocess.Popen(args).wait()
+        'Linux')
-    if ret != 0:
+            OS="linux"
-        raise SystemExit(ret)
+            case "$(command uname -m)" in
+                amd64|x86_64) arch="x86_64";;
+                aarch64*) arch="arm64";;
+                armv8*) arch="arm64";;
+                i386) arch="i686";;
+                i686) arch="i686";;
+                *) die "Unknown CPU architecture $(command uname -m)";;
+            esac
+            ;;
+        *) die "kitty binaries are not available for $(command uname)"
+    esac
+}
+
+expand_tilde() {
+    tilde_less="${1#\~/}"
+    [ "$1" != "$tilde_less" ] && tilde_less="$HOME/$tilde_less"
+    printf '%s' "$tilde_less"
+}
+
+parse_args() {
+    dest='~/.local'
+    [ "$OS" = "macos" ] && dest="/Applications"
+    launch='y'
+    installer=''
+    while :; do
+        case "$1" in
+            dest=*) dest="${1#*=}";;
+            launch=*) launch="${1#*=}";;
+            installer=*) installer="${1#*=}";;
+            "") break;;
+            *) die "Unrecognized command line option: $1";;
+        esac
+        shift
+    done
+    dest=$(expand_tilde "${dest}")
+    [ "$launch" != "y" -a "$launch" != "n" ] && die "Unrecognized command line option: launch=$launch"
+    dest="$dest/kitty.app"
+}
 
 
-class Reporter:  # {{{
+get_file_url() {
+    url="https://github.com/kovidgoyal/kitty/releases/download/$1/kitty-$2"
+    if [ "$OS" = "macos" ]; then
+        url="$url.dmg"
+    else
+        url="$url-$arch.txz"
+    fi
+}
 
-    def __init__(self, fname):
+get_release_url() {
-        self.fname = fname
+    release_version=$(fetch_quiet "https://sw.kovidgoyal.net/kitty/current-version.txt")
-        self.last_percent = 0
+    [ $? -ne 0 -o -z "$release_version" ] && die "Could not get kitty latest release version"
-
+    get_file_url "v$release_version" "$release_version"
-    def __call__(self, blocks, block_size, total_size):
+}
-        percent = (blocks*block_size)/float(total_size)
-        report = '\rDownloaded {:.1%}         '.format(percent)
-        if percent - self.last_percent > 0.05:
-            self.last_percent = percent
-            print(report, end='')
-            sys.stdout.flush()
-# }}}
 
 
-def get_release_data(relname='latest'):
+get_nightly_url() {
-    print('Checking for latest release on GitHub...')
+    get_file_url "nightly" "nightly"
-    req = urllib.Request(
+}
-        'https://api.github.com/repos/kovidgoyal/kitty/releases/' + relname,
-        headers={'Accept': 'application/vnd.github.v3+json'})
-    try:
-        res = urllib.urlopen(req).read().decode('utf-8')
-    except Exception as err:
-        raise SystemExit('Failed to contact {} with error: {}'.format(req.get_full_url(), err))
-    data = json.loads(res)
-    html_url = data['html_url'].replace('/tag/', '/download/').rstrip('/')
-    for asset in data.get('assets', ()):
-        name = asset['name']
-        if is_macos:
-            if name.endswith('.dmg'):
-                return html_url + '/' + name, asset['size']
-        else:
-            if name.endswith('.txz'):
-                if is64bit:
-                    q = '-arm64.txz' if is_linux_arm64 else '-x86_64.txz'
-                    if name.endswith(q):
-                        return html_url + '/' + name, asset['size']
-                else:
-                    if name.endswith('-i686.txz'):
-                        return html_url + '/' + name, asset['size']
-    raise SystemExit('Failed to find the installer package on github')
 
+get_download_url() {
+    installer_is_file="n"
+    case "$installer" in
+        "nightly") get_nightly_url ;;
+        "") get_release_url ;;
+        *) installer_is_file="y" ;;
+    esac
+}
 
-def do_download(url, size, dest):
+download_installer() {
-    print('Will download and install', os.path.basename(dest))
+    tdir=$(command mktemp -d "/tmp/kitty-install-XXXXXXXXXXXX")
-    reporter = Reporter(os.path.basename(dest))
+    [ "$installer_is_file" != "y" ] && {
+        printf '%s\n\n' "Downloading from: $url"
+        if [ "$OS" = "macos" ]; then
+            installer="$tdir/kitty.dmg"
+        else
+            installer="$tdir/kitty.txz"
+        fi
+        fetch "$url" > "$installer" || die "Failed to download: $url"
+        installer_is_file="y"
+    }
+}
 
-    # Get content length and check if range is supported
+linux_install() {
-    rq = urllib.urlopen(url)
+    command mkdir "$tdir/mp"
-    headers = rq.info()
+    command tar -C "$tdir/mp" "-xJof" "$installer" || die "Failed to extract kitty tarball"
-    sent_size = int(headers['content-length'])
+    printf "%s\n" "Installing to $dest"
-    if sent_size != size:
+    command rm -rf "$dest" || die "Failed to delete $dest"
-        raise SystemExit('Failed to download from {} Content-Length ({}) != {}'.format(url, sent_size, size))
+    command mv "$tdir/mp" "$dest" || die "Failed to move kitty.app to $dest"
-    with open(dest, 'wb') as f:
+}
-        while f.tell() < size:
-            raw = rq.read(8192)
-            if not raw:
-                break
-            f.write(raw)
-            reporter(f.tell(), 1, size)
-    rq.close()
-    if os.path.getsize(dest) < size:
-        raise SystemExit('Download failed, try again later')
-    print('\rDownloaded {} bytes'.format(os.path.getsize(dest)))
 
+macos_install() {
+    command mkdir "$tdir/mp"
+    command hdiutil attach "$installer" "-mountpoint" "$tdir/mp" || die "Failed to mount kitty.dmg"
+    printf "%s\n" "Installing to $dest"
+    command rm -rf "$dest"
+    command mkdir -p "$dest" || die "Failed to create the directory: $dest"
+    command ditto -v "$tdir/mp/kitty.app" "$dest"
+    rc="$?"
+    command hdiutil detach "$tdir/mp"
+    [ "$rc" != "0" ] && die "Failed to copy kitty.app from mounted dmg"
+}
 
-def clean_cache(cache, fname):
+exec_kitty() {
-    for x in os.listdir(cache):
+    if [ "$OS" = "macos" ]; then
-        if fname not in x:
+        exec "open" "$dest"
-            os.remove(os.path.join(cache, x))
+    else
+        exec "$dest/bin/kitty" "--detach"
+    fi
+    die "Failed to launch kitty"
+}
 
+main() {
+    detect_os
+    parse_args "$@"
+    detect_network_tool
+    get_download_url
+    download_installer
+    if [ "$OS" = "macos" ]; then
+        macos_install
+    else
+        linux_install
+    fi
+    cleanup
+    [ "$launch" = "y" ] && exec_kitty
+    exit 0
+}
 
-def download_installer(url, size):
+main "$@"
-    fname = url.rpartition('/')[-1]
-    tdir = tempfile.gettempdir()
-    cache = os.path.join(tdir, 'kitty-installer-cache')
-    if not os.path.exists(cache):
-        os.makedirs(cache)
-    clean_cache(cache, fname)
-    dest = os.path.join(cache, fname)
-    if os.path.exists(dest) and os.path.getsize(dest) == size:
-        print('Using previously downloaded', fname)
-        return dest
-    if os.path.exists(dest):
-        os.remove(dest)
-    do_download(url, size, dest)
-    return dest
-
-
-def macos_install(dmg, dest='/Applications', launch=True):
-    mp = tempfile.mkdtemp()
-    atexit.register(shutil.rmtree, mp)
-    run('hdiutil', 'attach', dmg, '-mountpoint', mp)
-    try:
-        os.chdir(mp)
-        app = 'kitty.app'
-        d = os.path.join(dest, app)
-        if os.path.exists(d):
-            shutil.rmtree(d)
-        dest = os.path.join(dest, app)
-        run('ditto', '-v', app, dest)
-        print('Successfully installed kitty into', dest)
-        if launch:
-            run('open', dest)
-    finally:
-        os.chdir('/')
-        run('hdiutil', 'detach', mp)
-
-
-def linux_install(installer, dest=os.path.expanduser('~/.local'), launch=True):
-    dest = os.path.join(dest, 'kitty.app')
-    if os.path.exists(dest):
-        shutil.rmtree(dest)
-    os.makedirs(dest)
-    print('Extracting tarball...')
-    run('tar', '-C', dest, '-xJof', installer)
-    print('kitty successfully installed to', dest)
-    kitty = os.path.join(dest, 'bin', 'kitty')
-    print('Use', kitty, 'to run kitty')
-    if launch:
-        run(kitty, '--detach')
-
-
-def main(dest=None, launch=True, installer=None):
-    if not dest:
-        if is_macos:
-            dest = '/Applications'
-        else:
-            dest = os.path.expanduser('~/.local')
-    if is_linux_arm and not is_linux_arm64:
-        raise SystemExit(
-            'You are running on a 32-bit ARM system. The kitty binaries are only'
-            ' available for 64 bit ARM systems. You will have to build from'
-            ' source.')
-    if not installer:
-        url, size = get_release_data()
-        installer = download_installer(url, size)
-    else:
-        if installer == 'nightly':
-            url, size = get_release_data('tags/nightly')
-            installer = download_installer(url, size)
-        else:
-            installer = os.path.abspath(installer)
-            if not os.access(installer, os.R_OK):
-                raise SystemExit('Could not read from: {}'.format(installer))
-    if is_macos:
-        macos_install(installer, dest=dest, launch=launch)
-    else:
-        linux_install(installer, dest=dest, launch=launch)
-
-
-def script_launch():
-    # To test: python3 -c "import runpy; runpy.run_path('installer.py', run_name='script_launch')"
-    def path(x):
-        return os.path.expandvars(os.path.expanduser(x))
-
-    def to_bool(x):
-        return x.lower() in {'y', 'yes', '1', 'true'}
-
-    type_map = {x: path for x in 'dest installer'.split()}
-    type_map['launch'] = to_bool
-    kwargs = {}
-
-    for arg in sys.argv[1:]:
-        if arg:
-            m = re.match('([a-z_]+)=(.+)', arg)
-            if m is None:
-                raise SystemExit('Unrecognized command line argument: ' + arg)
-            k = m.group(1)
-            if k not in type_map:
-                raise SystemExit('Unrecognized command line argument: ' + arg)
-            kwargs[k] = type_map[k](m.group(2))
-    main(**kwargs)
-
-
-def update_installer_wrapper():
-    # To run: python3 -c "import runpy; runpy.run_path('installer.py', run_name='update_wrapper')" installer.sh
-    with open(__file__, 'rb') as f:
-        src = f.read().decode('utf-8')
-    wrapper = sys.argv[-1]
-    with open(wrapper, 'r+b') as f:
-        raw = f.read().decode('utf-8')
-        nraw = re.sub(r'^# HEREDOC_START.+^# HEREDOC_END', lambda m: '# HEREDOC_START\n{}\n# HEREDOC_END'.format(src), raw, flags=re.MULTILINE | re.DOTALL)
-        if 'update_intaller_wrapper()' not in nraw:
-            raise SystemExit('regex substitute of HEREDOC failed')
-        f.seek(0), f.truncate()
-        f.write(nraw.encode('utf-8'))
-
-
-if __name__ == '__main__' and from_file:
-    main()
-elif __name__ == 'update_wrapper':
-    update_installer_wrapper()
-elif __name__ == 'script_launch':
-    script_launch()
-
-# HEREDOC_END
-# }}}
-INSTALLER_HEREDOC

docs/integrations.rst

@@ -4,8 +4,8 @@ Integrations with other tools
 ================================
 
 kitty provides extremely powerful interfaces such as :doc:`remote-control` and
-:doc:`kittens/custom` and :doc:`kittens/icat`
+:doc:`kittens/custom` and :doc:`kittens/icat` that allow it to be integrated
-that allow it to be integrated with other tools seamlessly.
+with other tools seamlessly.
 
 
 Image and document viewers
@@ -30,19 +30,28 @@ Display markdown files nicely formatted with images in the terminal
 
 `ranger <https://github.com/ranger/ranger>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+A terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
 
 .. _tool_nnn:
 
 `nnn <https://github.com/jarun/nnn/>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+Another terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
 
 .. _tool_hunter:
 
 `hunter <https://github.com/rabite0/hunter>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Another terminal file manager, with previews of file contents powered by kitty's graphics protocol.
+Another terminal file manager, with previews of file contents powered by kitty's
+graphics protocol.
+
+.. _tool_term_image:
+
+`term-image <https://github.com/AnonymouX47/term-image>`__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Tool to browse images in a terminal using kitty's graphics protocol.
 
 .. _tool_koneko:
 
@@ -61,8 +70,8 @@ View images in the terminal, similar to kitty's icat.
 
 `nb <https://github.com/xwmx/nb>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-command line and local web note-taking, bookmarking, archiving, and
+Command line and local web note-taking, bookmarking, archiving, and knowledge
-knowledge base application that uses kitty's graphics protocol for images.
+base application that uses kitty's graphics protocol for images.
 
 .. _tool_w3m:
 
@@ -71,13 +80,24 @@ knowledge base application that uses kitty's graphics protocol for images.
 A text mode WWW browser that supports kitty's graphics protocol to display
 images.
 
+`awrit <https://github.com/chase/awrit>`__
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A full Chromium based web browser running in the terminal using kitty's
+graphics protocol.
+
+.. _tool_mpv:
+
+`mpv <https://github.com/mpv-player/mpv/commit/874e28f4a41a916bb567a882063dd2589e9234e1>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A video player that can play videos in the terminal.
+
 .. _tool_timg:
 
 `timg <https://github.com/hzeller/timg>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A terminal image and video viewer, that displays static and animated
+A terminal image and video viewer, that displays static and animated images or
-images or plays videos. Fast multi-threaded loading, JPEG exif rotation,
+plays videos. Fast multi-threaded loading, JPEG exif rotation, grid view and
-grid view and connecting to the webcam make it a versatile terminal utility.
+connecting to the webcam make it a versatile terminal utility.
 
 
 System and data visualisation tools
@@ -87,7 +107,8 @@ System and data visualisation tools
 
 `neofetch <https://github.com/dylanaraps/neofetch>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A command line system information tool that shows images using kitty's graphics protocol
+A command line system information tool that shows images using kitty's graphics
+protocol
 
 .. _tool_matplotlib:
 
@@ -105,16 +126,16 @@ Show images from Julia directly in kitty
 
 `euporie <https://github.com/joouha/euporie>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A text-based user interface for running and editing Jupyter notebooks,
+A text-based user interface for running and editing Jupyter notebooks, powered
-powered by kitty's graphics protocol for displaying plots
+by kitty's graphics protocol for displaying plots
 
 .. _tool_gnuplot:
 
 `gnuplot <http://www.gnuplot.info/>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A graphing and data visualization tool that can be made to display its
+A graphing and data visualization tool that can be made to display its output in
-output in kitty with the following bash snippet:
+kitty with the following bash snippet:
 
 .. code-block:: sh
 
@@ -127,7 +148,7 @@ output in kitty with the following bash snippet:
         set object 1 rectangle from screen 0,0 to screen 1,1 fillcolor rgb"#fdf6e3" behind
         plot $@
         set output '/dev/null'
-        EOF
+    EOF
     }
 
 Add this to bashrc and then to plot a function, simply do:
@@ -171,26 +192,28 @@ Run applications on your system with fuzzy find inside a kitty window
 Editor integration
 -----------------------
 
-|kitty| can be integrated into many different terminal editors to add features
+|kitty| can be integrated into many different terminal based text editors to add
-such a split windows, previews, REPLs etc.
+features such a split windows, previews, REPLs etc.
 
 .. tool_kakoune:
 
 `kakoune <https://kakoune.org/>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-integrates with kitty to use native kitty windows for its windows/panels and REPLs.
+Integrates with kitty to use native kitty windows for its windows/panels and
+REPLs.
 
 .. tool_vim_slime:
 
 `vim-slime <https://github.com/jpalardy/vim-slime#kitty>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-uses kitty remote control for a Lisp REPL.
+Uses kitty remote control for a Lisp REPL.
 
 .. tool_vim_kitty_navigator:
 
 `vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+Allows you to navigate seamlessly between vim and kitty splits using a
+consistent set of hotkeys.
 
 .. tool_vim_test:
 
@@ -202,7 +225,8 @@ Allows easily running tests in a terminal window
 
 `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Terminal image viewer for nvim
+Terminal image viewer for Neovim. For a bit of fun, you can even have `cats
+running around inside nvim <https://github.com/giusgad/pets.nvim>`__.
 
 
 Scrollback manipulation
@@ -228,21 +252,21 @@ Miscellaneous
 
 `kitty-smart-tab <https://github.com/yurikhan/kitty-smart-tab>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-use keys to either control tabs or pass them onto running applications if
+Use keys to either control tabs or pass them onto running applications if no
-no tabs are present
+tabs are present
 
 .. tool_kitty_smart_scroll:
 
 `kitty-smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-use keys to either scroll or pass them onto running applications if
+Use keys to either scroll or pass them onto running applications if no
-no scrollback buffer is present
+scrollback buffer is present
 
 .. tool_kitti3:
 
 `kitti3 <https://github.com/LandingEllipse/kitti3>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-allow using kitty as a drop-down terminal under the i3 window manager
+Allow using kitty as a drop-down terminal under the i3 window manager
 
 .. tool_weechat_hints:
 

docs/keyboard-protocol.rst

@@ -35,9 +35,18 @@ inside the kitty terminal to report key events.
 In addition to kitty, this protocol is also implemented in:
 
 * The `foot terminal <https://codeberg.org/dnkl/foot/issues/319>`__
+* The `WezTerm terminal <https://wezfurlong.org/wezterm/config/lua/config/enable_kitty_keyboard.html>`__
 * The `notcurses library
   <https://github.com/dankamongmen/notcurses/issues/2131>`__
+* The `crossterm library
+  <https://github.com/crossterm-rs/crossterm/pull/688>`__
+* The `Vim text editor <https://github.com/vim/vim/commit/63a2e360cca2c70ab0a85d14771d3259d4b3aafa>`__
+* The `Emacs text editor via the kkp package <https://github.com/benjaminor/kkp>`__
+* The `Neovim text editor <https://github.com/neovim/neovim/pull/18181>`__
 * The `kakoune text editor <https://github.com/mawww/kakoune/issues/4103>`__
+* The `dte text editor <https://gitlab.com/craigbarnes/dte/-/issues/138>`__
+* The `Helix text editor <https://github.com/helix-editor/helix/pull/4939>`__
+* The `far2l file manager <https://github.com/elfmz/far2l/commit/e1f2ee0ef2b8332e5fa3ad7f2e4afefe7c96fc3b>`__
 
 .. versionadded:: 0.20.0
 
@@ -55,14 +64,14 @@ without too many changes, do the following:
    that are easy to parse unambiguously.
 #. Emit the escape sequence ``CSI < u`` at application exit if using the main
    screen or just before leaving alternate screen mode if using the alternate screen,
-   to restore the previously used keyboard mode.
+   to restore whatever the keyboard mode was before step 1.
 
 Key events will all be delivered to your application either as plain UTF-8
 text, or using the following escape codes, for those keys that do not produce
 text (``CSI`` is the bytes ``0x1b 0x5b``)::
 
     CSI number ; modifiers [u~]
-    CSI 1; modifiers [ABCDEFHPQRS]
+    CSI 1; modifiers [ABCDEFHPQS]
     0x0d - for the Enter key
     0x7f or 0x08 - for Backspace
     0x09 - for Tab
@@ -77,7 +86,7 @@ The second form is used for a few functional keys, such as the :kbd:`Home`,
 :kbd:`End`, :kbd:`Arrow` keys and :kbd:`F1` ... :kbd:`F4`, they are enumerated in
 the :ref:`functional` table below.  Note that if no modifiers are present the
 parameters are omitted entirely giving an escape code of the form ``CSI
-[ABCDEFHPQRS]``.
+[ABCDEFHPQS]``.
 
 If you want support for more advanced features such as repeat and release
 events, alternate keys for shortcut matching et cetera, these can be turned on
@@ -308,7 +317,7 @@ With this flag turned on, all key events that do not generate text are
 represented in one of the following two forms::
 
     CSI number; modifier u
-    CSI 1; modifier [~ABCDEFHPQRS]
+    CSI 1; modifier [~ABCDEFHPQS]
 
 This makes it very easy to parse key events in an application. In particular,
 :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
@@ -376,7 +385,7 @@ An application can query the terminal for support of this protocol by sending
 the escape code querying for the :ref:`current progressive enhancement
 <progressive_enhancement>` status
 followed by request for the `primary device attributes
-<https://vt100.net/docs/vt510-rm/DA1.html>`. If an answer for the device
+<https://vt100.net/docs/vt510-rm/DA1.html>`__. If an answer for the device
 attributes is received without getting back an answer for the progressive
 enhancement the terminal does not support this protocol.
 
@@ -399,7 +408,7 @@ Legacy functional keys
 These keys are encoded using three schemes::
 
     CSI number ; modifier ~
-    CSI 1 ; modifier {ABCDEFHPQRS}
+    CSI 1 ; modifier {ABCDEFHPQS}
     SS3 {ABCDEFHPQRS}
 
 In the above, if there are no modifiers, the modifier parameter is omitted.
@@ -527,7 +536,7 @@ compatibility reasons.
    "NUM_LOCK", "``57360 u``", "PRINT_SCREEN", "``57361 u``"
    "PAUSE", "``57362 u``", "MENU", "``57363 u``"
    "F1", "``1 P or 11 ~``", "F2", "``1 Q or 12 ~``"
-   "F3", "``1 R or 13 ~``", "F4", "``1 S or 14 ~``"
+   "F3", "``13 ~``", "F4", "``1 S or 14 ~``"
    "F5", "``15 ~``", "F6", "``17 ~``"
    "F7", "``18 ~``", "F8", "``19 ~``"
    "F9", "``20 ~``", "F10", "``21 ~``"
@@ -576,8 +585,14 @@ compatibility reasons.
 .. end functional key table
 .. }}}
 
-Note that the escape codes above of the form ``CSI 1 letter`` will omit the
+.. note::
-``1`` if there are no modifiers, since ``1`` is the default value.
+    The escape codes above of the form ``CSI 1 letter`` will omit the
+    ``1`` if there are no modifiers, since ``1`` is the default value.
+
+.. note::
+   The original version of this specification allowed F3 to be encoded as both
+   CSI R and CSI ~. However, CSI R conflicts with the Cursor Position Report,
+   so it was removed.
 
 .. _ctrl_mapping:
 
@@ -670,3 +685,31 @@ specification.
 * Handwaves that :kbd:`ctrl` *tends to* mask with ``0x1f``. In actual fact it
   does this only for some keys. The action of :kbd:`ctrl` is not specified and
   varies between terminals, historically because of different keyboard layouts.
+
+
+Why xterm's modifyOtherKeys should not be used
+---------------------------------------------------
+
+* Does not support release events
+
+* Does not fix the issue of :kbd:`Esc` key presses not being distinguishable from
+  escape codes.
+
+* Does not fix the issue of some keypresses generating identical bytes and thus
+  being indistinguishable
+
+* There is no robust way to query it or manage its state from a program running
+  in the terminal.
+
+* No support for shifted keys.
+
+* No support for alternate keyboard layouts.
+
+* No support for modifiers beyond the basic four.
+
+* No support for lock keys like Num lock and Caps lock.
+
+* Is completely unspecified. The most discussion of it available anywhere is
+  `here <https://invisible-island.net/xterm/modified-keys.html>`__
+  And it contains no specification of what numbers to assign to what function
+  keys beyond running a Perl script on an X11 system!!

docs/kittens/broadcast.rst

@@ -3,18 +3,21 @@ broadcast
 
 *Type text in all kitty windows simultaneously*
 
-The ``broadcast`` kitten can be used to type text simultaneously in
+The ``broadcast`` kitten can be used to type text simultaneously in all
-all kitty windows (or a subset as desired).
+:term:`kitty windows <window>` (or a subset as desired).
 
 To use it, simply create a mapping in :file:`kitty.conf` such as::
 
-    map F1 launch --allow-remote-control kitty +kitten broadcast
+    map f1 launch --allow-remote-control kitty +kitten broadcast
 
-Then press the :kbd:`F1` key and whatever you type in the newly created widow
+Then press the :kbd:`F1` key and whatever you type in the newly created window
 will be sent to all kitty windows.
 
-You can use the options described below to control which windows
+You can use the options described below to control which windows are selected.
-are selected.
+
+For example, only broadcast to other windows in the current tab::
+
+    map f1 launch --allow-remote-control kitty +kitten broadcast --match-tab state:focused
 
 .. program:: kitty +kitten broadcast
 

docs/kittens/clipboard.rst

@@ -11,14 +11,46 @@ from the shell. It even works over SSH. Using it is as simple as::
 
     echo hooray | kitty +kitten clipboard
 
-All text received on :file:`stdin` is copied to the clipboard.
+All text received on :file:`STDIN` is copied to the clipboard.
 
-To get text from the clipboard you have to enable reading of the clipboard
+To get text from the clipboard::
-in :opt:`clipboard_control` in :file:`kitty.conf`. Once you do that, you can
-use::
 
     kitty +kitten clipboard --get-clipboard
 
+The text will be written to :file:`STDOUT`. Note that by default kitty asks for
+permission when a program attempts to read the clipboard. This can be
+controlled via :opt:`clipboard_control`.
+
+.. versionadded:: 0.27.0
+   Support for copying arbitrary data types
+
+The clipboard kitten can be used to send/receive
+more than just plain text from the system clipboard. You can transfer arbitrary
+data types. Best illustrated with some examples::
+
+    # Copy an image to the clipboard:
+    kitty +kitten clipboard picture.png
+
+    # Copy an image and some text to the clipboard:
+    kitty +kitten clipboard picture.jpg text.txt
+
+    # Copy text from STDIN and an image to the clipboard:
+    echo hello | kitty +kitten clipboard picture.png /dev/stdin
+
+    # Copy any raster image available on the clipboard to a PNG file:
+    kitty +kitten clipboard -g picture.png
+
+    # Copy an image to a file and text to STDOUT:
+    kitty +kitten clipboard -g picture.png /dev/stdout
+
+    # List the formats available on the system clipboard
+    kitty +kitten clipboard -g -m . /dev/stdout
+
+Normally, the kitten guesses MIME types based on the file names. To control the
+MIME types precisely, use the :option:`--mime <kitty +kitten clipboard --mime>` option.
+
+This kitten uses a new protocol developed by kitty to function, for details,
+see :doc:`/clipboard`.
 
 .. program:: kitty +kitten clipboard
 

docs/kittens/custom.rst

@@ -1,21 +1,20 @@
 Custom kittens
 =================
 
-You can easily create your own kittens to extend kitty. They are just
+You can easily create your own kittens to extend kitty. They are just terminal
-terminal programs written in Python. When launching a kitten, kitty will
+programs written in Python. When launching a kitten, kitty will open an overlay
-open an overlay window over the current window and optionally pass the
+window over the current window and optionally pass the contents of the current
-contents of the current window/scrollback to the kitten over its :file:`STDIN`.
+window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
-The kitten can then perform whatever actions it likes, just as a normal
+perform whatever actions it likes, just as a normal terminal program. After
-terminal program. After execution of the kitten is complete, it has access
+execution of the kitten is complete, it has access to the running kitty instance
-to the running kitty instance so it can perform arbitrary actions
+so it can perform arbitrary actions such as closing windows, pasting text, etc.
-such as closing windows, pasting text, etc.
 
 Let's see a simple example of creating a kitten. It will ask the user for some
 input and paste it into the terminal window.
 
-Create a file in the kitty config folder, :file:`~/.config/kitty/mykitten.py`
+Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
-(you might need to adjust the path to wherever the kitty config folder is on
+(you might need to adjust the path to wherever the :ref:`kitty config directory
-your machine).
+<confloc>` is on your machine).
 
 
 .. code-block:: python
@@ -35,7 +34,7 @@ your machine).
         # get the kitty window into which to paste answer
         w = boss.window_id_map.get(target_window_id)
         if w is not None:
-            w.paste(answer)
+            w.paste_text(answer)
 
 
 Now in :file:`kitty.conf` add the lines::
@@ -43,11 +42,30 @@ Now in :file:`kitty.conf` add the lines::
     map ctrl+k kitten mykitten.py
 
 
-Start kitty and press :kbd:`ctrl+k` and you should see the kitten running.
+Start kitty and press :kbd:`Ctrl+K` and you should see the kitten running.
-The best way to develop your own kittens is to modify one of the built in
+The best way to develop your own kittens is to modify one of the built-in
-kittens. Look in the kittens sub-directory of the kitty source code for those.
+kittens. Look in the `kittens sub-directory
-Or see below for a list of :ref:`third-party kittens <external_kittens>`,
+<https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
-that other kitty users have created.
+code for those. Or see below for a list of :ref:`third-party kittens
+<external_kittens>`, that other kitty users have created.
+
+kitty API to use with kittens
+-------------------------------
+
+Kittens have full access to internal kitty APIs. However these are neither
+entirely stable nor documented. You can instead use the kitty
+:doc:`Remote control API </remote-control>`. Simply call
+:code:`boss.call_remote_control()`, with the same arguments you
+would pass to ``kitty @``. For example:
+
+.. code-block:: python
+
+    def handle_result(args: List[str], answer: str, target_window_id: int, boss: Boss) -> None:
+        # get the kitty window to which to send text
+        w = boss.window_id_map.get(target_window_id)
+        if w is not None:
+            boss.call_remote_control(w, ('send-text', 'hello world'))
+
 
 
 Passing arguments to kittens
@@ -60,36 +78,40 @@ You can pass arguments to kittens by defining them in the map directive in
 
 These will be available as the ``args`` parameter in the ``main()`` and
 ``handle_result()`` functions. Note also that the current working directory
-of the kitten is set to the working directory of whatever program is
+of the kitten is set to the working directory of whatever program is running in
-running in the active kitty window. The special argument ``@selection``
+the active kitty window. The special argument ``@selection`` is replaced by the
-is replaced by the currently selected text in the active kitty window.
+currently selected text in the active kitty window.
 
 
 Passing the contents of the screen to the kitten
 ---------------------------------------------------
 
 If you would like your kitten to have access to the contents of the screen
-and/or the scrollback buffer, you just need to add an annotation to the ``handle_result()``
+and/or the scrollback buffer, you just need to add an annotation to the
-function, telling kitty what kind of input your kitten would like. For example:
+``handle_result()`` function, telling kitty what kind of input your kitten would
+like. For example:
 
 .. code-block:: py
 
+    from typing import List
+    from kitty.boss import Boss
+
     # in main, STDIN is for the kitten process and will contain
     # the contents of the screen
-    def main(args):
+    def main(args: List[str]) -> str:
         return sys.stdin.read()
 
     # in handle_result, STDIN is for the kitty process itself, rather
     # than the kitten process and should not be read from.
     from kittens.tui.handler import result_handler
     @result_handler(type_of_input='text')
-    def handle_result(args, stdin_data, target_window_id, boss):
+    def handle_result(args: List[str], stdin_data: str, target_window_id: int, boss: Boss) -> None:
         pass
 
 
 This will send the plain text of the active window to the kitten's
-:file:`STDIN`. There are many other types of input you can ask for,
+:file:`STDIN`. There are many other types of input you can ask for, described in
-described in the table below:
+the table below:
 
 .. table:: Types of input to kittens
     :align: left
@@ -121,31 +143,35 @@ and ``first_output`` gives the output of the first command currently on screen.
 These can also be combined with ``screen`` and ``ansi`` for formatting.
 
 .. note::
-   For the types based on the output of a command,
+   For the types based on the output of a command, :ref:`shell_integration` is
-   :ref:`shell_integration` is required.
+   required.
 
 
 Using kittens to script kitty, without any terminal UI
 -----------------------------------------------------------
 
 If you would like your kitten to script kitty, without bothering to write a
-terminal program, you can tell the kittens system to run the
+terminal program, you can tell the kittens system to run the ``handle_result()``
-``handle_result()`` function without first running the ``main()`` function.
+function without first running the ``main()`` function.
 
-For example, here is a kitten that "zooms/unzooms" the current terminal window
+For example, here is a kitten that "zooms in/zooms out" the current terminal
-by switching to the stack layout or back to the previous layout. This is
+window by switching to the stack layout or back to the previous layout. This is
-equivalent to the builtin :ref:`action-toggle_layout` action.
+equivalent to the builtin :ac:`toggle_layout` action.
 
-Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
+Create a Python file in the :ref:`kitty config directory <confloc>`,
+:file:`~/.config/kitty/zoom_toggle.py`
 
 .. code-block:: py
 
-    def main(args):
+    from typing import List
+    from kitty.boss import Boss
+
+    def main(args: List[str]) -> str:
         pass
 
     from kittens.tui.handler import result_handler
     @result_handler(no_ui=True)
-    def handle_result(args, answer, target_window_id, boss):
+    def handle_result(args: List[str], answer: str, target_window_id: int, boss: Boss) -> None:
         tab = boss.active_tab
         if tab is not None:
             if tab.current_layout.name == 'stack':
@@ -154,7 +180,7 @@ Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
                 tab.goto_layout('stack')
 
 
-Now in kitty.conf add::
+Now in :file:`kitty.conf` add::
 
     map f11 kitten zoom_toggle.py
 
@@ -165,7 +191,7 @@ layout, by simply adding the line::
     boss.toggle_fullscreen()
 
 
-To the ``handle_result()`` function, above.
+to the ``handle_result()`` function, above.
 
 
 .. _send_mouse_event:
@@ -173,7 +199,7 @@ To the ``handle_result()`` function, above.
 Sending mouse events
 --------------------
 
-If the program running in a window is receiving mouse events you can simulate
+If the program running in a window is receiving mouse events, you can simulate
 those using::
 
     from kitty.fast_data_types import send_mouse_event
@@ -200,15 +226,15 @@ that type, and will return ``True`` if it sent the event, and ``False`` if not.
 Debugging kittens
 --------------------
 
-The part of the kitten that runs in ``main()`` is just a normal program and
+The part of the kitten that runs in ``main()`` is just a normal program and the
-the output of print statements will be visible in the kitten window. Or
+output of print statements will be visible in the kitten window. Or alternately,
-alternately, you can use::
+you can use::
 
     from kittens.tui.loop import debug
     debug('whatever')
 
-The ``debug()`` function is just like ``print()`` except that the output
+The ``debug()`` function is just like ``print()`` except that the output will
-will appear in the ``STDOUT`` of the kitty process inside which the kitten is
+appear in the ``STDOUT`` of the kitty process inside which the kitten is
 running.
 
 The ``handle_result()`` part of the kitten runs inside the kitty process.
@@ -216,12 +242,13 @@ The output of print statements will go to the ``STDOUT`` of the kitty process.
 So if you run kitty from another kitty instance, the output will be visible
 in the first kitty instance.
 
+
 Adding options to kittens
 ----------------------------
 
 If you would like to use kitty's config framework to make your kittens
-configurable, you will need some boilerplate. In the directory
+configurable, you will need some boilerplate. Put the following files in the
-of your kitten make the following files.
+directory of your kitten.
 
 :file:`kitten_options_definition.py`
 
@@ -311,8 +338,9 @@ You can parse and read the options in your kitten using the following code:
         opts.config_overrides = overrides
         return opts
 
-See the code for the builtin diff kitten for examples of creating more options
+See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
-and keyboard shortcuts.
+for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
+options and keyboard shortcuts.
 
 .. _external_kittens:
 
@@ -320,7 +348,8 @@ Kittens created by kitty users
 ---------------------------------------------
 
 `vim-kitty-navigator <https://github.com/knubie/vim-kitty-navigator>`_
-    Allows you to navigate seamlessly between vim and kitty splits using a consistent set of hotkeys.
+    Allows you to navigate seamlessly between vim and kitty splits using a
+    consistent set of hotkeys.
 
 `smart-scroll <https://github.com/yurikhan/kitty-smart-scroll>`_
     Makes the kitty scroll bindings work in full screen applications

docs/kittens/diff.rst

@@ -12,8 +12,8 @@ Major Features
 
     * Displays diffs side-by-side in the kitty terminal
 
-    * Does syntax highlighting of the displayed diffs, asynchronously, for maximum
+    * Does syntax highlighting of the displayed diffs, asynchronously, for
-      speed
+      maximum speed
 
     * Displays images as well as text diffs, even over SSH
 
@@ -31,11 +31,7 @@ Major Features
 Installation
 ---------------
 
-Simply :ref:`install kitty <quickstart>`.  You also need
+Simply :ref:`install kitty <quickstart>`.
-to have either the `git <https://git-scm.com/>`_ program or the ``diff`` program
-installed. Additionally, for syntax highlighting to work,
-`pygments <https://pygments.org/>`_ must be installed (note that pygments is
-included in the official kitty binary builds).
 
 
 Usage
@@ -45,9 +41,10 @@ In the kitty terminal, run::
 
     kitty +kitten diff file1 file2
 
-to see the diff between file1 and file2.
+to see the diff between :file:`file1` and :file:`file2`.
 
-Create an alias in your shell's startup file to shorten the command, for example:
+Create an alias in your shell's startup file to shorten the command, for
+example:
 
 .. code-block:: sh
 
@@ -64,36 +61,38 @@ directory contents.
 Keyboard controls
 ----------------------
 
-=========================   ===========================
+===========================       ===========================
-Action                      Shortcut
+Action                            Shortcut
-=========================   ===========================
+===========================       ===========================
-Quit                        :kbd:`q`, :kbd:`ctrl+c`, :kbd:`Esc`
+Quit                              :kbd:`Q`, :kbd:`Esc`
-Scroll line up              :kbd:`k`, :kbd:`Up`
+Scroll line up                    :kbd:`K`, :kbd:`Up`
-Scroll line down            :kbd:`j`, :kbd:`Down`
+Scroll line down                  :kbd:`J`, :kbd:`Down`
-Scroll page up              :kbd:`PgUp`
+Scroll page up                    :kbd:`PgUp`
-Scroll page down            :kbd:`PgDn`
+Scroll page down                  :kbd:`PgDn`
-Scroll to top               :kbd:`Home`
+Scroll to top                     :kbd:`Home`
-Scroll to bottom            :kbd:`End`
+Scroll to bottom                  :kbd:`End`
-Scroll to next page         :kbd:`Space`, :kbd:`PgDn`
+Scroll to next page               :kbd:`Space`, :kbd:`PgDn`
-Scroll to previous page     :kbd:`PgUp`
+Scroll to previous page           :kbd:`PgUp`
-Scroll to next change       :kbd:`n`
+Scroll to next change             :kbd:`N`
-Scroll to previous change   :kbd:`p`
+Scroll to previous change         :kbd:`P`
-Increase lines of context   :kbd:`+`
+Increase lines of context         :kbd:`+`
-Decrease lines of context   :kbd:`-`
+Decrease lines of context         :kbd:`-`
-All lines of context        :kbd:`a`
+All lines of context              :kbd:`A`
-Restore default context     :kbd:`=`
+Restore default context           :kbd:`=`
-Search forwards             :kbd:`/`
+Search forwards                   :kbd:`/`
-Search backwards            :kbd:`?`
+Search backwards                  :kbd:`?`
-Clear search                :kbd:`Esc`
+Clear search                      :kbd:`Esc`
-Scroll to next match        :kbd:`>`, :kbd:`.`
+Scroll to next match              :kbd:`>`, :kbd:`.`
-Scroll to previous match    :kbd:`<`, :kbd:`,`
+Scroll to previous match          :kbd:`<`, :kbd:`,`
-=========================   ===========================
+Copy selection to clipboard       :kbd:`y`
+Copy selection or exit            :kbd:`Ctrl+C`
+===========================       ===========================
 
 
 Integrating with git
 -----------------------
 
-Add the following to `~/.gitconfig`:
+Add the following to :file:`~/.gitconfig`:
 
 .. code-block:: ini
 
@@ -119,24 +118,23 @@ Why does this work only in kitty?
 ----------------------------------------
 
 The diff kitten makes use of various features that are :doc:`kitty only
-</protocol-extensions>`,  such as the :doc:`kitty graphics protocol
+</protocol-extensions>`, such as the :doc:`kitty graphics protocol
 </graphics-protocol>`, the :doc:`extended keyboard protocol
-</keyboard-protocol>`, etc. It also leverages terminal program
+</keyboard-protocol>`, etc. It also leverages terminal program infrastructure
-infrastructure I created for all of kitty's other kittens to reduce the amount
+I created for all of kitty's other kittens to reduce the amount of code needed
-of code needed (the entire implementation is under 2000 lines of code).
+(the entire implementation is under 3000 lines of code).
 
 And fundamentally, it's kitty only because I wrote it for myself, and I am
 highly unlikely to use any other terminals :)
 
 
-
 Configuration
 ------------------------
 
 You can configure the colors used, keyboard shortcuts, the diff implementation,
-the default lines of context, etc.  by creating a :file:`diff.conf` file in
+the default lines of context, etc. by creating a :file:`diff.conf` file in your
-your :ref:`kitty config folder <confloc>`. See below for the supported
+:ref:`kitty config folder <confloc>`. See below for the supported configuration
-configuration directives.
+directives.
 
 
 .. include:: /generated/conf-kitten-diff.rst
@@ -145,7 +143,6 @@ configuration directives.
 .. include:: /generated/cli-kitten-diff.rst
 
 
-
 Sample diff.conf
 -----------------
 

docs/kittens/hints.rst

@@ -1,9 +1,9 @@
 Hints
 ==========
 
-|kitty| has a *hints mode* to select and act on arbitrary text snippets currently
+|kitty| has a *hints mode* to select and act on arbitrary text snippets
-visible on the screen.  For example, you can press :sc:`open_url`
+currently visible on the screen.  For example, you can press :sc:`open_url`
-to choose any URL visible on the screen and then open it using your system
+to choose any URL visible on the screen and then open it using your default web
 browser.
 
 .. figure:: ../screenshots/hints_mode.png
@@ -13,25 +13,29 @@ browser.
 
     URL hints mode
 
-Similarly, you can press :sc:`insert_selected_path` to
+Similarly, you can press :sc:`insert_selected_path` to select anything that
-select anything that looks like a path or filename and then insert it into the
+looks like a path or filename and then insert it into the terminal, very useful
-terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and
+for picking files from the output of a :program:`git` or :program:`ls` command
-adding them to the command line for the next command.
+and adding them to the command line for the next command.
 
-You can also press :sc:`goto_file_line` to select anything that looks
+You can also press :sc:`goto_file_line` to select anything that looks like a
-like a path or filename followed by a colon and a line number and open
+path or filename followed by a colon and a line number and open the file in
-the file in vim at the specified line number. The patterns and editor
+:program:`vim` at the specified line number. The patterns and editor to be used
-to be used can be modified using options passed to the kitten. For example::
+can be modified using options passed to the kitten. For example::
 
     map ctrl+g kitten hints --type=linenum --linenum-action=tab nvim +{line} {path}
 
-will open the selected file in a new tab inside neovim when you press
+will open the selected file in a new tab inside `Neovim <https://neovim.io/>`__
-:kbd:`ctrl+g`.
+when you press :kbd:`Ctrl+G`.
 
-Pressing :sc:`open_selected_hyperlink` will open hyperlinks, i.e. a URL
+Pressing :sc:`open_selected_hyperlink` will open :term:`hyperlinks`, i.e. a URL
 that has been marked as such by the program running in the terminal,
-for example, by ``ls --hyperlink=auto``. You can also :doc:`customize what actions are
+for example, by ``ls --hyperlink=auto``. If :program:`ls` comes with your OS
-taken for different types of URLs <../open_actions>`.
+does not support hyperlink, you may need to install `GNU Coreutils
+<https://www.gnu.org/software/coreutils/>`__.
+
+You can also :doc:`customize what actions are taken for different types of URLs
+<../open_actions>`.
 
 .. note:: If there are more hints than letters, hints will use multiple
    letters. In this case, when you press the first letter, only hints
@@ -48,13 +52,12 @@ snippets. See :sc:`insert_selected_path <insert_selected_path>` for examples.
 Completely customizing the matching and actions of the kitten
 ---------------------------------------------------------------
 
-The hints kitten supports writing simple python scripts that can be used to
+The hints kitten supports writing simple Python scripts that can be used to
 completely customize how it finds matches and what happens when a match is
-selected. This allows the hints kitten to provide the user interface, while
+selected. This allows the hints kitten to provide the user interface, while you
-you can provide the logic for finding matches and performing actions on them.
+can provide the logic for finding matches and performing actions on them. This
-This is best illustrated with an example. Create the file
+is best illustrated with an example. Create the file :file:`custom-hints.py` in
-:file:`custom-hints.py` in the kitty config directory with the following
+the :ref:`kitty config directory <confloc>` with the following contents:
-contents:
 
 .. code-block:: python
 
@@ -69,7 +72,8 @@ contents:
             start, end = m.span()
             mark_text = text[start:end].replace('\n', '').replace('\0', '')
             # The empty dictionary below will be available as groupdicts
-            # in handle_result() and can contain arbitrary data.
+            # in handle_result() and can contain string keys and arbitrary JSON
+            # serializable values.
             yield Mark(idx, start, end, mark_text, {})
 
 
@@ -98,9 +102,10 @@ look it up in the Google dictionary.
 
 .. note::
 
-    To avoid having to specify the same command line options on every invocation,
+    To avoid having to specify the same command line options on every
-    you can use the :opt:`action_alias` option in :file:`kitty.conf`, creating aliases
+    invocation, you can use the :opt:`action_alias` option in
-    that have common sets of options. For example::
+    :file:`kitty.conf`, creating aliases that have common sets of options.
+    For example::
 
         action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890
         map f1 myhints --customize-processing custom-hints.py

docs/kittens/hyperlinked_grep.rst

@@ -1,11 +1,10 @@
 Hyperlinked grep
 =================
 
-
 This kitten allows you to search your files using `ripgrep
-<https://github.com/BurntSushi/ripgrep>`_ and open the results
+<https://github.com/BurntSushi/ripgrep>`__ and open the results directly in your
-directly in your favorite editor in the terminal, at the line containing
+favorite editor in the terminal, at the line containing the search result,
-the search result, simply by clicking on the result you want.
+simply by clicking on the result you want.
 
 .. versionadded:: 0.19.0
 
@@ -18,68 +17,57 @@ following contents:
     # by the hyperlink_grep kitten and nothing else so far.
     protocol file
     fragment_matches [0-9]+
-    action launch --type=overlay vim +${FRAGMENT} ${FILE_PATH}
+    action launch --type=overlay --cwd=current vim +${FRAGMENT} ${FILE_PATH}
 
     # Open text files without fragments in the editor
     protocol file
     mime text/*
-    action launch --type=overlay ${EDITOR} ${FILE_PATH}
+    action launch --type=overlay --cwd=current ${EDITOR} ${FILE_PATH}
-
 
 Now, run a search with::
 
     kitty +kitten hyperlinked_grep something
 
-Hold down the :kbd:`ctrl+shift` keys and click on any of the
+Hold down the :kbd:`Ctrl+Shift` keys and click on any of the result lines, to
-result lines, to open the file in vim at the matching line. If
+open the file in :program:`vim` at the matching line. If you use some editor
-you use some editor other than vim, you should adjust the
+other than :program:`vim`, you should adjust the :file:`open-actions.conf` file
-:file:`open-actions.conf` file accordingly.
+accordingly.
 
-Finally, add an alias to your shell's rc files to invoke the kitten as ``hg``::
+Finally, add an alias to your shell's rc files to invoke the kitten as
+:command:`hg`::
 
-    alias hg='kitty +kitten hyperlinked_grep'
+    alias hg="kitty +kitten hyperlinked_grep"
 
 
 You can now run searches with::
 
     hg some-search-term
 
-If you want to enable completion, for the kitten, you can delegate completion
-to rg. How to do that varies based on the shell:
-
-
-.. tab:: zsh
-
-    Instead of using an alias create a simple wrapper script named
-    :file:`hg` somewhere in your ``PATH``:
-
-    .. code-block:: sh
-
-        #!/bin/sh
-        exec kitty +kitten hyperlinked_grep "$@"
-
-    Then, add the following to :file:`.zshrc`::
-
-        compdef _rg hg
-
-.. tab:: fish
-
-    You can combine both the aliasing/wrapping and pointing fish
-    to rg's autocompletion with a fish "wrapper" function in your :file:`config.fish`:
-
-    .. code-block:: sh
-
-        function hg --wraps rg; kitty +kitten hyperlinked_grep $argv; end
-
 To learn more about kitty's powerful framework for customizing URL click
-actions, :doc:`see here </open_actions>`.
+actions, see :doc:`here </open_actions>`.
+
+By default, this kitten adds hyperlinks for several parts of ripgrep output:
+the per-file header, match context lines, and match lines. You can control
+which items are linked with a :code:`--kitten hyperlink` flag. For example,
+:code:`--kitten hyperlink=matching_lines` will only add hyperlinks to the
+match lines. :code:`--kitten hyperlink=file_headers,context_lines` will link
+file headers and context lines but not match lines. :code:`--kitten
+hyperlink=none` will cause the command line to be passed to directly to
+:command:`rg` so no hyperlinking will be performed. :code:`--kitten hyperlink`
+may be specified multiple times.
 
 Hopefully, someday this functionality will make it into some `upstream grep
-<https://github.com/BurntSushi/ripgrep/issues/665>`_
+<https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
-program directly removing the need for this kitten.
+the need for this kitten.
 
 
 .. note::
    While you can pass any of ripgrep's comand line options to the kitten and
-   they will be forwarded to rg, do not use options that change the output
+   they will be forwarded to :program:`rg`, do not use options that change the
-   formatting as the kitten works by parsing the output from ripgrep.
+   output formatting as the kitten works by parsing the output from ripgrep.
+   The unsupported options are: :code:`--context-separator`,
+   :code:`--field-context-separator`, :code:`--field-match-separator`,
+   :code:`--json`, :code:`-I --no-filename`, :code:`-0 --null`,
+   :code:`--null-data`, :code:`--path-separator`. If you specify options via
+   configuration file, then any changes to the default output format will not be
+   supported, not just the ones listed.

docs/kittens/icat.rst

@@ -7,10 +7,11 @@ The ``icat`` kitten can be used to display arbitrary images in the |kitty|
 terminal. Using it is as simple as::
 
     kitty +kitten icat image.jpeg
+    kitten icat image.jpeg
 
 It supports all image types supported by `ImageMagick
-<https://www.imagemagick.org>`_. It even works over SSH. For details, see
+<https://www.imagemagick.org>`__. It even works over SSH. For details, see the
-the :doc:`kitty graphics protocol </graphics-protocol>`.
+:doc:`kitty graphics protocol </graphics-protocol>`.
 
 You might want to create an alias in your shell's configuration files::
 
@@ -20,14 +21,15 @@ Then you can simply use ``icat image.png`` to view images.
 
 .. note::
 
-    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
+    `ImageMagick <https://www.imagemagick.org>`__ must be installed for the
-    work.
+    full range of image types. Without it only PNG/JPG/GIF/BMP/TIFF/WEBP are
+    supported.
 
 .. note::
 
     kitty's image display protocol may not work when used within a terminal
-    multiplexer such as ``screen`` or ``tmux``, depending on whether the
+    multiplexer such as :program:`screen` or :program:`tmux`, depending on
-    multiplexer has added support for it or not.
+    whether the multiplexer has added support for it or not.
 
 
 .. program:: kitty +kitten icat
@@ -35,18 +37,18 @@ Then you can simply use ``icat image.png`` to view images.
 
 The ``icat`` kitten has various command line arguments to allow it to be used
 from inside other programs to display images. In particular, :option:`--place`,
-:option:`--detect-support`, :option:`--silent` and :option:`--print-window-size`.
+:option:`--detect-support` and :option:`--print-window-size`.
 
-If you are trying to integrate icat into a complex program like a file
+If you are trying to integrate icat into a complex program like a file manager
-manager or editor, there are a few things to keep in mind. icat works by
+or editor, there are a few things to keep in mind. icat works by communicating
-communicating over the TTY device, it both writes to and reads from the TTY.
+over the TTY device, it both writes to and reads from the TTY. So it is
-So it is imperative that while it is running the host program does not do
+imperative that while it is running the host program does not do any TTY I/O.
-any TTY I/O. Any key presses or other input from the user on the TTY device
+Any key presses or other input from the user on the TTY device will be
-will be discarded. At a minimum, you should use the :option:`--silent` and
+discarded. At a minimum, you should use the :option:`--transfer-mode`
-:option:`--transfer-mode` command line arguments. To be
+command line arguments. To be really robust you should
-really robust you should consider writing proper support for the
+consider writing proper support for the :doc:`kitty graphics protocol
-:doc:`../graphics-protocol` in the program instead.  Nowadays there are many
+</graphics-protocol>` in the program instead. Nowadays there are many libraries
-libraries that have support for it.
+that have support for it.
 
 
 .. include:: /generated/cli-kitten-icat.rst

docs/kittens/panel.rst

@@ -4,8 +4,8 @@ Draw a GPU accelerated dock panel on your desktop
 .. highlight:: sh
 
 
-You can use this kitten to draw a GPU accelerated panel on the edge
+You can use this kitten to draw a GPU accelerated panel on the edge of your
-of your screen, that shows the output from an arbitrary terminal program.
+screen, that shows the output from an arbitrary terminal program.
 
 It is useful for showing status information or notifications on your desktop
 using terminal programs instead of GUI toolkits.
@@ -32,8 +32,8 @@ Using this kitten is simple, for example::
     kitty +kitten panel sh -c 'printf "\n\n\nHello, world."; sleep 5s'
 
 This will show ``Hello, world.`` at the top edge of your screen for five
-seconds. Here the terminal program we are running is ``sh`` with a script to
+seconds. Here the terminal program we are running is :program:`sh` with a script
-print out ``Hello, world!``. You can make the terminal program as complex as
+to print out ``Hello, world!``. You can make the terminal program as complex as
 you like, as demonstrated in the screenshot above.
 
 

docs/kittens/query_terminal.rst

@@ -1,18 +1,18 @@
 Query terminal
 =================
 
-Used to query kitty from terminal programs about version, values of various
+This kitten is used to query |kitty| from terminal programs about version, values
-runtime options controlling its features, etc.
+of various runtime options controlling its features, etc.
 
 The querying is done using the (*semi*) standard XTGETTCAP escape sequence
-pioneered by XTerm, so it works over SSH as well. The downside is that it
+pioneered by xterm, so it works over SSH as well. The downside is that it is
-is slow, since it requires a roundtrip to the terminal emulator and back.
+slow, since it requires a roundtrip to the terminal emulator and back.
 
 If you want to do some of the same querying in your terminal program without
 depending on the kitten, you can do so, by processing the same escape codes.
-Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`_
+Search `this page <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>`__
-for *XTGETTCAP* to see the syntax for the escape code and read the source
+for *XTGETTCAP* to see the syntax for the escape code and read the source of
-of this kitten to find the values of the keys for the various queries.
+this kitten to find the values of the keys for the various queries.
 
 
 .. include:: ../generated/cli-kitten-query_terminal.rst

docs/kittens/remote_file.rst

@@ -1,12 +1,12 @@
 Remote files
 ==============
 
-|kitty| has the ability to easily *Edit*, *Open* or *Download* files
+|kitty| has the ability to easily *Edit*, *Open* or *Download* files from a
-from a computer into which you are SSHed. In your SSH session run::
+computer into which you are SSHed. In your SSH session run::
 
     ls --hyperlink=auto
 
-Then hold down :kbd:`ctrl+shift` and click the name of the file.
+Then hold down :kbd:`Ctrl+Shift` and click the name of the file.
 
 .. figure:: ../screenshots/remote_file.png
     :alt: Remote file actions
@@ -19,23 +19,28 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file.
 to *Edit* it in which case kitty will download it and open it locally in your
 :envvar:`EDITOR`. As you make changes to the file, they are automatically
 transferred to the remote computer. Note that this happens without needing
-to install *any* special software on the server, beyond ``ls`` that supports
+to install *any* special software on the server, beyond :program:`ls` that
-hyperlinks.
+supports hyperlinks.
+
+.. seealso:: See the :ref:`edit-in-kitty <edit_file>` command
 
 .. seealso:: See the :doc:`transfer` kitten
 
 .. versionadded:: 0.19.0
 
 .. note::
-   Nested SSH sessions are not supported. The kitten will always try to copy
+   For best results, use this kitten with the :doc:`ssh kitten <./ssh>`.
-   remote files from the first SSH host. This is because there is no way for
+   Otherwise, nested SSH sessions are not supported. The kitten will always try to copy
+   remote files from the first SSH host. This is because, without the ssh
+   kitten, there is no way for
    |kitty| to detect and follow a nested SSH session robustly. Use the
    :doc:`transfer` kitten for such situations.
 
 .. note::
-   If you have not setup automatic password-less SSH access, then, when
+   If you have not setup automatic password-less SSH access, and are not using
-   editing starts you will be asked to enter your password just once,
+   the ssh kitten, then, when editing
-   thereafter the SSH connection will be re-used.
+   starts you will be asked to enter your password just once, thereafter the SSH
+   connection will be re-used.
 
 Similarly, you can choose to save the file to the local computer or download
 and open it in its default file handler.

docs/kittens/ssh.rst

@@ -0,0 +1,203 @@
+Truly convenient SSH
+=========================================
+
+* Automatic :ref:`shell_integration` on remote hosts
+
+* Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote hosts
+
+* Automatic :opt:`re-use of existing connections <kitten-ssh.share_connections>` to avoid connection setup latency
+
+* Make kitty itself available in the remote host :opt:`on demand <kitten-ssh.remote_kitty>`
+
+* Easily :opt:`change terminal colors <kitten-ssh.color_scheme>` when connecting to remote hosts
+
+.. versionadded:: 0.25.0
+   Automatic shell integration, file transfer and reuse of connections
+
+The ssh kitten allows you to login easily to remote hosts, and automatically
+setup the environment there to be as comfortable as your local shell. You can
+specify environment variables to set on the remote host and files to copy there,
+making your remote experience just like your local shell. Additionally, it
+automatically sets up :ref:`shell_integration` on the remote host and copies the
+kitty terminfo database there.
+
+The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
+command line program and supports all the same options and arguments and configuration.
+In interactive usage scenarios it is a drop in replacement for :program:`ssh`.
+To try it out, simply run:
+
+.. code-block:: sh
+
+    kitty +kitten ssh some-hostname-to-connect-to
+
+You should end up at a shell prompt on the remote host, with shell integration
+enabled. If you like it you can add an alias to it in your shell's rc files:
+
+.. code-block:: sh
+
+    alias s="kitty +kitten ssh"
+
+So now you can just type ``s hostname`` to connect.
+
+If you define a mapping in :file:`kitty.conf` such as::
+
+    map f1 new_window_with_cwd
+
+Then, pressing :kbd:`F1` will open a new window automatically logged into the
+same host using the ssh kitten, at the same directory.
+
+The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` file
+where you can specify environment variables to set on the remote host and files
+to copy from the local to the remote host. Let's see a quick example:
+
+.. code-block:: conf
+
+   # Copy the files and directories needed to setup some common tools
+   copy .zshrc .vimrc .vim
+   # Setup some environment variables
+   env SOME_VAR=x
+   # COPIED_VAR will have the same value on the remote host as it does locally
+   env COPIED_VAR=_kitty_copy_env_var_
+
+   # Create some per hostname settings
+   hostname someserver-*
+   copy env-files
+   env SOMETHING=else
+
+   hostname someuser@somehost
+   copy --dest=foo/bar some-file
+   copy --glob some/files.*
+
+
+See below for full details on the syntax and options of :file:`ssh.conf`.
+Additionally, you can pass config options on the command line:
+
+.. code-block:: sh
+
+   kitty +kitten ssh --kitten interpreter=python servername
+
+The :code:`--kitten` argument can be specified multiple times, with directives
+from :file:`ssh.conf`. These are merged with :file:`ssh.conf` as if they were
+appended to the end of that file. They apply only to the host being SSHed to by
+this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are
+ignored.
+
+.. warning::
+
+   Due to limitations in the design of SSH, any typing you do before the
+   shell prompt appears may be lost. So ideally don't start typing till you see
+   the shell prompt. 😇
+
+
+.. _real_world_ssh_kitten_config:
+
+A real world example
+----------------------
+
+Suppose you often SSH into a production server, and you would like to setup
+your shell and editor there using your custom settings. However, other people
+could SSH in as well and you don't want to clobber their settings. Here is how
+this could be achieved using the ssh kitten with :program:`zsh` and
+:program:`vim` as the shell and editor, respectively:
+
+.. code-block:: conf
+
+   # Have these settings apply to servers in my organization
+   hostname myserver-*
+
+   # Setup zsh to read its files from my-conf/zsh
+   env ZDOTDIR $HOME/my-conf/zsh
+   copy --dest my-conf/zsh/.zshrc .zshrc
+   copy --dest my-conf/zsh/.zshenv .zshenv
+   # If you use other zsh init files add them in a similar manner
+
+   # Setup vim to read its config from my-conf/vim
+   env VIMINIT $HOME/my-conf/vim/vimrc
+   env VIMRUNTIME $HOME/my-conf/vim
+   copy --dest my-conf/vim .vim
+   copy --dest my-conf/vim/vimrc .vimrc
+
+
+How it works
+----------------
+
+The ssh kitten works by having SSH transmit and execute a POSIX sh (or
+:opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the
+remote host using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
+reads setup data over the TTY device, which kitty sends as a Base64 encoded
+compressed tarball. The script extracts it and places the :opt:`files <kitten-ssh.copy>`
+and sets the :opt:`environment variables <kitten-ssh.env>` before finally
+launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
+integration <kitten-ssh.shell_integration>` enabled. The data is requested by
+the kitten over the TTY with a random one time password. kitty reads the request
+and if the password matches a password pre-stored in shared memory on the
+localhost by the kitten, the transmission is allowed. If your local
+`OpenSSH <https://www.openssh.com/>`__ version is >= 8.4 then the data is
+transmitted instantly without any roundtrip delay.
+
+.. note::
+
+   When connecting to BSD hosts, it is possible the bootstrap script will fail
+   or run slowly, because the default shells are crippled in various ways.
+   Your best bet is to install Python on the remote, make sure the login shell
+   is something POSIX sh compliant, and use :code:`python` as the
+   :opt:`interpreter <kitten-ssh.interpreter>` in :file:`ssh.conf`.
+
+
+.. note::
+
+   This may or may not work when using terminal multiplexers, depending on
+   whether they passthrough the escape codes and if the values of the
+   environment variables :envvar:`KITTY_PID` and :envvar:`KITTY_WINDOW_ID` are
+   correct in the current session (they can be wrong when connecting to a tmux
+   session running in a different window) and the ssh kitten is run in the
+   currently active multiplexer window.
+
+.. include:: /generated/conf-kitten-ssh.rst
+
+
+.. _ssh_copy_command:
+
+The copy command
+--------------------
+
+.. include:: /generated/ssh-copy.rst
+
+
+.. _manual_terminfo_copy:
+
+Copying terminfo files manually
+-------------------------------------
+
+Sometimes, the ssh kitten can fail, or maybe you dont like to use it. In such
+cases, the terminfo files can be copied over manually to a server with the
+following one liner::
+
+    infocmp -a xterm-kitty | ssh myserver tic -x -o \~/.terminfo /dev/stdin
+
+If you are behind a proxy (like Balabit) that prevents this, or you are SSHing
+into macOS where the :program:`tic` does not support reading from :file:`STDIN`,
+you must redirect the first command to a file, copy that to the server and run :program:`tic`
+manually. If you connect to a server, embedded, or Android system that doesn't
+have :program:`tic`, copy over your local file terminfo to the other system as
+:file:`~/.terminfo/x/xterm-kitty`.
+
+If the server is running a relatively modern Linux distribution and you have
+root access to it, you could simply install the ``kitty-terminfo`` package on
+the server to make the terminfo files available.
+
+Really, the correct solution for this is to convince the OpenSSH maintainers to
+have :program:`ssh` do this automatically, if possible, when connecting to a
+server, so that all terminals work transparently.
+
+If the server is running FreeBSD, or another system that relies on termcap
+rather than terminfo, you will need to convert the terminfo file on your local
+machine by running (on local machine with |kitty|)::
+
+    infocmp -CrT0 xterm-kitty
+
+The output of this command is the termcap description, which should be appended
+to :file:`/usr/share/misc/termcap` on the remote server. Then run the following
+command to apply your change (on the server)::
+
+    cap_mkdb /usr/share/misc/termcap

docs/kittens/themes.rst

@@ -1,8 +1,8 @@
 Changing kitty colors
 ========================
 
-The themes kitten allows you to easily change color themes, from a collection
+The themes kitten allows you to easily change color themes, from a collection of
-of almost two hundred pre-built themes available at `kitty-themes
+over two hundred pre-built themes available at `kitty-themes
 <https://github.com/kovidgoyal/kitty-themes>`_. To use it, simply run::
 
     kitty +kitten themes
@@ -12,9 +12,9 @@ of almost two hundred pre-built themes available at `kitty-themes
    :alt: The themes kitten in action
    :width: 600
 
-The kitten allows you to pick a theme, with live previews of the colors. You
+The kitten allows you to pick a theme, with live previews of the colors. You can
-can choose between light and dark themes and search by theme name by just
+choose between light and dark themes and search by theme name by just typing a
-typing a few characters from the name.
+few characters from the name.
 
 The kitten maintains a list of recently used themes to allow quick switching.
 
@@ -24,14 +24,15 @@ If you want to restore the colors to default, you can do so by choosing the
 .. versionadded:: 0.23.0
    The themes kitten
 
+
 How it works
 ----------------
 
 A theme in kitty is just a :file:`.conf` file containing kitty settings.
 When you select a theme, the kitten simply copies the :file:`.conf` file
 to :file:`~/.config/kitty/current-theme.conf` and adds an include for
-:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out
+:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out any
-any existing color settings in :file:`kitty.conf` so they do not interfere.
+existing color settings in :file:`kitty.conf` so they do not interfere.
 
 Once that's done, the kitten sends kitty a signal to make it reload its config.
 
@@ -39,11 +40,12 @@ Using your own themes
 -----------------------
 
 You can also create your own themes as :file:`.conf` files. Put them in the
-:file:`themes` sub-directory of the kitty config directory, usually,
+:file:`themes` sub-directory of the :ref:`kitty config directory <confloc>`,
-:file:`~/.config/kitty/themes` and the kitten will automatically add them to
+usually, :file:`~/.config/kitty/themes`. The kitten will automatically add them
-the list of themes. You can use this to modify the builtin themes, by giving
+to the list of themes. You can use this to modify the builtin themes, by giving
 the conf file the name :file:`Some theme name.conf` to override the builtin
-theme of that name. Note that after doing so you have to run the kitten and
+theme of that name. Here, ``Some theme name`` is the actual builtin theme name, not
+its file name. Note that after doing so you have to run the kitten and
 choose that theme once for your changes to be applied.
 
 
@@ -52,13 +54,13 @@ Contributing new themes
 
 If you wish to contribute a new theme to the kitty theme repository, start by
 going to the `kitty-themes <https://github.com/kovidgoyal/kitty-themes>`__
-repository.  `Fork it
+repository. `Fork it
-<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_, and use the
+<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`__, and use the
 file :download:`template.conf
 <https://github.com/kovidgoyal/kitty-themes/raw/master/template.conf>` as a
 template when creating your theme. Once you are satisfied with how it looks,
 `submit a pull request
-<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`__
 to have your theme merged into the `kitty-themes
 <https://github.com/kovidgoyal/kitty-themes>`__ repository, which will make it
 available in this kitten automatically.
@@ -67,12 +69,12 @@ available in this kitten automatically.
 Changing the theme non-interactively
 ---------------------------------------
 
-You can specify the theme name as an argument when invoking the kitten
+You can specify the theme name as an argument when invoking the kitten to have
-to have it change to that theme instantly. For example::
+it change to that theme instantly. For example::
 
     kitty +kitten themes --reload-in=all Dimmed Monokai
 
-Will change the theme to ``Dimmed Monokai`` in all running kitty
+Will change the theme to ``Dimmed Monokai`` in all running kitty instances. See
-instances. See below for more details on non-interactive operation.
+below for more details on non-interactive operation.
 
 .. include:: ../generated/cli-kitten-themes.rst

docs/kittens/transfer.rst

@@ -14,16 +14,16 @@ etc. Anywhere you have a terminal device, you can transfer files.
    :alt: The transfer kitten at work
 
 This kitten supports transferring entire directory trees, preserving soft and
-hard links, file permissions, times, etc. It even supports the rsync_
+hard links, file permissions, times, etc. It even supports the rsync_ protocol
-protocol to transfer only changes to large files.
+to transfer only changes to large files.
 
 .. seealso:: See the :doc:`remote_file` kitten
 
 .. note::
    This kitten (which practically means kitty) must be installed on the other
    machine as well. If that is not possible you can use the :doc:`remote_file`
-   kitten instead. Or write your own script to use the underlying :doc:`file transfer
+   kitten instead. Or write your own script to use the underlying
-   protocol </file-transfer-protocol>`.
+   :doc:`file transfer protocol </file-transfer-protocol>`.
 
 .. versionadded:: 0.24.0
 
@@ -32,7 +32,8 @@ Basic usage
 ---------------
 
 In what follows, the *local computer* is the computer running this kitten and
-the *remote computer* is the computer connected to the other end of the TTY pipe.
+the *remote computer* is the computer connected to the other end of the TTY
+pipe.
 
 To send a file from the local computer to the remote computer, simply run::
 
@@ -42,7 +43,7 @@ You will be prompted by kitty for confirmation on allowing the transfer, and if
 you grant permission, the file will be copied.
 
 Similarly, to get a file from the remote computer to the local computer, use
-the :option:`kitty +kitten transfer --direction` option::
+the :option:`--direction <kitty +kitten transfer --direction>` option::
 
     kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer
 
@@ -58,25 +59,25 @@ the fact that you are copying multiple things) it is good practice to always
 use a trailing slash when the destination is supposed to be a directory.
 
 Also, when transferring multiple files/directories it is a good idea to
-use the :option:`kitty +kitten transfer --confirm-paths` option which will give
+use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
-you an opportunity to review and confirm the files that will be touched.
+option which will give you an opportunity to review and confirm the files that
+will be touched.
 
 
 Avoiding the confirmation prompt
 ------------------------------------
 
-Normally, when you start a file transfer kitty will prompt you for
+Normally, when you start a file transfer kitty will prompt you for confirmation.
-confirmation. This is to ensure that hostile programs running on a remote
+This is to ensure that hostile programs running on a remote machine cannot
-machine cannot read/write files on your computer without your permission.
+read/write files on your computer without your permission. If the remote machine
-If the remote machine is trusted and the connection between your computer
+is trusted and the connection between your computer and the remote machine is
-and the remote machine is secure, then you can disable the confirmation prompt
+secure, then you can disable the confirmation prompt by:
-by:
 
-#. Setting the :opt:`file_transfer_confirmation_bypass` option to some
+#. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
-   password.
 
-#. When invoking the kitten use the :option:`kitty +kitten transfer --permissions-bypass`
+#. When invoking the kitten use the :option:`--permissions-bypass
-   to supply the password you set in step one.
+   <kitty +kitten transfer --permissions-bypass>` to supply the password you set
+   in step one.
 
 .. warning:: Using a password to bypass confirmation means any software running
    on the remote machine could potentially learn that password and use it to
@@ -89,9 +90,10 @@ Delta transfers
 -----------------------------------
 
 This kitten has the ability to use the rsync_ protocol to only transfer the
-differences between files. To turn it on use the :option:`kitty +kitten
+differences between files. To turn it on use the :option:`--transmit-deltas
-transfer --transmit-deltas` option. Note that this will actually be slower when
+<kitty +kitten transfer --transmit-deltas>` option. Note that this will actually
-transferring small files because of round trip overhead, so use with care.
+be slower when transferring small files because of round trip overhead, so use
+with care.
 
 
 .. include:: ../generated/cli-kitten-transfer.rst

docs/kittens/unicode_input.rst

@@ -1,27 +1,29 @@
 Unicode input
 ================
 
-You can input unicode characters by name, hex code, recently used and even an editable favorites list.
+You can input Unicode characters by name, hex code, recently used and even an
-Press :sc:`input_unicode_character` to start the unicode input widget, shown below.
+editable favorites list. Press :sc:`input_unicode_character` to start the
+unicode input kitten, shown below.
 
 .. figure:: ../screenshots/unicode.png
-    :alt: A screenshot of the unicode input widget
+    :alt: A screenshot of the unicode input kitten
     :align: center
     :width: 100%
 
-    A screenshot of the unicode input widget
+    A screenshot of the unicode input kitten
 
-In :guilabel:`Code` mode, you enter a unicode character by typing in the hex code for the
+In :guilabel:`Code` mode, you enter a Unicode character by typing in the hex
-character and pressing enter, for example, type in ``2716`` and press enter to get
+code for the character and pressing :kbd:`Enter`. For example, type in ``2716``
-✖. You can also choose a character from the list of recently used characters by
+and press :kbd:`Enter` to get ``✖``. You can also choose a character from the
-typing a leading period and then the two character index and pressing Enter.
+list of recently used characters by typing a leading period ``.`` and then the
-The up and down arrow keys can be used to choose the previous and next unicode
+two character index and pressing :kbd:`Enter`.
-symbol respectively.
+The :kbd:`Up` and :kbd:`Down` arrow keys can be used to choose the previous and
+next Unicode symbol respectively.
 
 In :guilabel:`Name` mode you instead type words from the character name and use
-the arrow keys/tab to select the character from the displayed matches. You can
+the :kbd:`ArrowKeys` / :kbd:`Tab` to select the character from the displayed
-also type a space followed by a period and the index for the match if you don't
+matches. You can also type a space followed by a period and the index for the
-like to use arrow keys.
+match if you don't like to use arrow keys.
 
 You can switch between modes using either the keys :kbd:`F1` ... :kbd:`F4` or
 :kbd:`Ctrl+1` ... :kbd:`Ctrl+4` or by pressing :kbd:`Ctrl+[` and :kbd:`Ctrl+]`

docs/kittens_intro.rst

@@ -15,12 +15,13 @@ Extend with kittens
    kittens/remote_file
    kittens/hyperlinked_grep
    kittens/transfer
+   kittens/ssh
    kittens/custom
    kittens/*
 
 |kitty| has a framework for easily creating terminal programs that make use of
-its advanced features. These programs are called kittens. They are used both
+its advanced features. These programs are called kittens. They are used both to
-to add features to |kitty| itself and to create useful standalone programs.
+add features to |kitty| itself and to create useful standalone programs.
 Some prominent kittens:
 
 :doc:`icat <kittens/icat>`
@@ -32,8 +33,8 @@ Some prominent kittens:
     images
 
 
-:doc:`Unicode Input <kittens/unicode_input>`
+:doc:`Unicode input <kittens/unicode_input>`
-    Easily input arbitrary unicode characters in |kitty| by name or hex code.
+    Easily input arbitrary Unicode characters in |kitty| by name or hex code.
 
 
 :doc:`Hints <kittens/hints>`
@@ -47,24 +48,31 @@ Some prominent kittens:
 
 
 :doc:`Transfer files <kittens/transfer>`
-    Transfer files and directories seamlessly and easily from remote machines over your existing
+    Transfer files and directories seamlessly and easily from remote machines
-    SSH sessions with a simple command.
+    over your existing SSH sessions with a simple command.
 
 
 :doc:`Hyperlinked grep <kittens/hyperlinked_grep>`
-    Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`_
+    Search your files using `ripgrep <https://github.com/BurntSushi/ripgrep>`__
     and open the results directly in your favorite editor in the terminal,
-    at the line containing the search result, simply by clicking on the result you want.
+    at the line containing the search result, simply by clicking on the result
+    you want.
 
 
 :doc:`Broadcast <kittens/broadcast>`
-    Type in one :term:`kitty window <window>` and have it broadcast to all (or a subset) of
+    Type in one :term:`kitty window <window>` and have it broadcast to all (or a
-    other :term:`kitty windows <window>`.
+    subset) of other :term:`kitty windows <window>`.
+
+
+:doc:`SSH <kittens/ssh>`
+    SSH with automatic :ref:`shell integration <shell_integration>`, connection
+    re-use for low latency and easy cloning of local shell and editor
+    configuration to the remote host.
 
 
 :doc:`Panel <kittens/panel>`
-    Draw a GPU accelerated dock panel on your desktop showing the output
+    Draw a GPU accelerated dock panel on your desktop showing the output from an
-    from an arbitrary terminal program.
+    arbitrary terminal program.
 
 
 :doc:`Clipboard <kittens/clipboard>`

docs/launch.rst

@@ -5,22 +5,21 @@ The :command:`launch` command
 
 
 |kitty| has a :code:`launch` action that can be used to run arbitrary programs
-in new windows/tabs. It can be mapped to user defined shortcuts in kitty.conf.
+in new windows/tabs. It can be mapped to user defined shortcuts in
-It is very powerful and allows sending the contents of
+:file:`kitty.conf`. It is very powerful and allows sending the contents of the
-the current window to the launched program, as well as many other options.
+current window to the launched program, as well as many other options.
 
 In the simplest form, you can use it to open a new kitty window running the
 shell, as shown below::
 
     map f1 launch
 
-To run a different program simply pass the command line as arguments to
+To run a different program simply pass the command line as arguments to launch::
-launch::
 
     map f1 launch vim path/to/some/file
 
-To open a new window with the same working directory as the currently
+To open a new window with the same working directory as the currently active
-active window::
+window::
 
     map f1 launch --cwd=current
 
@@ -30,9 +29,10 @@ To open the new window in a new tab::
 
 To run multiple commands in a shell, use::
 
-    map f1 launch sh -c "ls && zsh"
+    map f1 launch sh -c "ls && exec zsh"
 
-To pass the contents of the current screen and scrollback to the started process::
+To pass the contents of the current screen and scrollback to the started
+process::
 
     map f1 launch --stdin-source=@screen_scrollback less
 
@@ -46,16 +46,16 @@ There are many more powerful options, refer to the complete list below.
         map f1 launch_tab vim
         map f2 launch_tab emacs
 
-    The :kbd:`F1` key will now open vim in a new tab with the current windows
+    The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
-    working directory
+    windows working directory.
 
 
 The piping environment
 --------------------------
 
 When using :option:`launch --stdin-source`, the program to which the data is
-piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA` whose
+piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
-contents are::
+whose contents are::
 
    KITTY_PIPE_DATA={scrolled_by}:{cursor_x},{cursor_y}:{lines},{columns}
 
@@ -73,27 +73,33 @@ the command line:
 
 
 ``@selection``
-    replaced by the currently selected text
+    Replaced by the currently selected text.
 
 ``@active-kitty-window-id``
-    replaced by the id of the currently active kitty window
+    Replaced by the id of the currently active kitty window.
 
 ``@line-count``
-    replaced by the number of lines in STDIN. Only present when passing some
+    Replaced by the number of lines in STDIN. Only present when passing some
-    data to STDIN
+    data to STDIN.
 
 ``@input-line-number``
-    replaced the number of lines a pager should scroll to match the current
+    Replaced the number of lines a pager should scroll to match the current
-    scroll position in kitty. See :opt:`scrollback_pager` for details
+    scroll position in kitty. See :opt:`scrollback_pager` for details.
 
 ``@scrolled-by``
-    replaced by the number of lines kitty is currently scrolled by
+    Replaced by the number of lines kitty is currently scrolled by.
 
 ``@cursor-x``
-    replaced by the current cursor x position with 1 being the leftmost cell
+    Replaced by the current cursor x position with 1 being the leftmost cell.
 
 ``@cursor-y``
-    replaced by the current cursor y position with 1 being the topmost cell
+    Replaced by the current cursor y position with 1 being the topmost cell.
+
+``@first-line-on-screen``
+    Replaced by the first line on screen. Can be used for pager positioning.
+
+``@last-line-on-screen``
+    Replaced by the last line on screen. Can be used for pager positioning.
 
 
 For example::
@@ -106,44 +112,51 @@ For example::
 Watching launched windows
 ---------------------------
 
-The :option:`launch --watcher` option allows you to specify python functions
+The :option:`launch --watcher` option allows you to specify Python functions
 that will be called at specific events, such as when the window is resized or
-closed. Simply specify the path to a python module that specifies callback
+closed. Simply specify the path to a Python module that specifies callback
 functions for the events you are interested in, for example:
 
 .. code-block:: python
 
-    def on_resize(boss, window, data):
+    from typing import Any, Dict
+
+    from kitty.boss import Boss
+    from kitty.window import Window
+
+
+    def on_resize(boss: Boss, window: Window, data: Dict[str, Any]) -> None:
         # Here data will contain old_geometry and new_geometry
 
-    def on_focus_change(boss, window, data):
+    def on_focus_change(boss: Boss, window: Window, data: Dict[str, Any])-> None:
         # Here data will contain focused
 
-    def on_close(boss, window, data):
+    def on_close(boss: Boss, window: Window, data: Dict[str, Any])-> None:
         # called when window is closed, typically when the program running in
         # it exits.
 
 
 Every callback is passed a reference to the global ``Boss`` object as well as
-the ``Window`` object the action is occurring on. The ``data`` object is
+the ``Window`` object the action is occurring on. The ``data`` object is a dict
-a dict that contains event dependent data. Some useful methods and attributes
+that contains event dependent data. Some useful methods and attributes for the
-for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
+``Window`` object are: ``as_text(as_ans=False, add_history=False,
 add_wrap_markers=False, alternate_screen=False)`` with which you can get the
 contents of the window and its scrollback buffer. Similarly,
 ``window.child.pid`` is the PID of the processes that was launched
-in the window and ``window.id`` is the internal kitty ``id`` of the
+in the window and ``window.id`` is the internal kitty ``id`` of the window.
-window.
 
 
 Finding executables
 -----------------------
 
 When you specify a command to run as just a name rather than an absolute path,
-it is searched for in the system-wide ``PATH`` environment variable. Note that
+it is searched for in the system-wide :envvar:`PATH` environment variable. Note
-this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
+that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
-often change the value of this variable. If it is not found there, then a
+startup scripts often change the value of this variable. If it is not found
-system specific list of default paths is searched. If it is still not found,
+there, then a system specific list of default paths is searched. If it is still
-then your shell is run and the value of ``PATH`` inside the shell is used.
+not found, then your shell is run and the value of :envvar:`PATH` inside the
+shell is used.
+
 See :opt:`exe_search_path` for details and how to control this.
 
 Syntax reference

docs/layouts.rst

@@ -10,7 +10,8 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
     :align: center
     :width: 100%
 
-    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+    Screenshot, showing :program:`vim`, :program:`tig` and :program:`git`
+    running in |kitty| with the *Tall* layout
 
 
 .. figure:: screenshots/splits.png
@@ -18,21 +19,22 @@ other in arbitrary arrangements, based on *Layouts*, see below for examples:
     :align: center
     :width: 100%
 
-    Screenshot, showing windows with arbitrary arrangement in the 'Splits'
+    Screenshot, showing windows with arbitrary arrangement in the *Splits*
     layout
 
 
-There are many different layouts available. They are all enabled by default,
+There are many different layouts available. They are all enabled by default, you
-you can switch layouts using :sc:`next_layout`. To control which layouts
+can switch layouts using :ac:`next_layout` (:sc:`next_layout` by default). To
-are available use :opt:`enabled_layouts`, the first listed layout becomes
+control which layouts are available use :opt:`enabled_layouts`, the first listed
-the default. Individual layouts and how to use them are described below.
+layout becomes the default. Individual layouts and how to use them are described
+below.
 
 
 The Stack Layout
 ------------------
 
-This is the simplest layout it displays a single window using all available
+This is the simplest layout. It displays a single window using all available
-space, other windows are hidden behind it. It has no options::
+space, other windows are hidden behind it. This layout has no options::
 
     enabled_layouts stack
 
@@ -40,14 +42,14 @@ space, other windows are hidden behind it. It has no options::
 The Tall Layout
 ------------------
 
-Displays one (or optionally more) full height windows on the left half of the
+Displays one (or optionally more) full-height windows on the left half of the
 screen. Remaining windows are tiled vertically on the right half of the screen.
 There are options to control how the screen is split horizontally ``bias``
 (an integer between ``10`` and ``90``) and options to control how many
 full-height windows there are ``full_size`` (a positive integer). The
-``mirrored`` option when set to ``true`` will cause the short windows to be
+``mirrored`` option when set to ``true`` will cause the full-height windows to
-on the left side of the screen instead of the right. The syntax
+be on the right side of the screen instead of the left. The syntax
-for the options is shown below::
+for the options is::
 
     enabled_layouts tall:bias=50;full_size=1;mirrored=false
 
@@ -65,24 +67,32 @@ for the options is shown below::
     │              │               │
     └──────────────┴───────────────┘
 
-In addition, you can map keys to increase or decrease the number of full size
+In addition, you can map keys to increase or decrease the number of full-height
-windows, for example::
+windows, or toggle the mirrored setting, for example::
 
    map ctrl+[ layout_action decrease_num_full_size_windows
    map ctrl+] layout_action increase_num_full_size_windows
+   map ctrl+/ layout_action mirror toggle
+   map ctrl+y layout_action mirror true
+   map ctrl+n layout_action mirror false
 
+You can also map a key to change the bias by providing a list of percentages
+and it will rotate through the list as you press the key. If you only provide
+one number it'll toggle between that percentage and 50, for example::
+
+   map ctrl+. layout_action bias 50 62 70
+   map ctrl+, layout_action bias 62
 
 The Fat Layout
 ----------------
 
-Displays one (or optionally more) full width windows on the top half of the
+Displays one (or optionally more) full-width windows on the top half of the
-screen. Remaining windows are tiled horizontally on the bottom half of the screen.
+screen. Remaining windows are tiled horizontally on the bottom half of the
-There are options to control how the screen is split vertically ``bias``
+screen. There are options to control how the screen is split vertically ``bias``
 (an integer between ``10`` and ``90``) and options to control how many
-full-height windows there are ``full_size`` (a positive integer). The
+full-width windows there are ``full_size`` (a positive integer). The
-``mirrored`` option when set to ``true`` will cause the narrow windows to be
+``mirrored`` option when set to ``true`` will cause the full-width windows to be
-on the top of the screen instead of the bottom. The syntax for the options is
+on the bottom of the screen instead of the top. The syntax for the options is::
-shown below::
 
     enabled_layouts fat:bias=50;full_size=1;mirrored=false
 
@@ -100,11 +110,15 @@ shown below::
     └─────────┴──────────┴─────────┘
 
 
+This layout also supports the same layout actions as the *Tall* layout, shown above.
+
+
 The Grid Layout
 --------------------
 
 Display windows in a balanced grid with all windows the same size except the
-last column if there are not enough windows to fill the grid. Has no options::
+last column if there are not enough windows to fill the grid. This layout has no
+options::
 
     enabled_layouts grid
 
@@ -132,15 +146,20 @@ define a few extra key bindings in :file:`kitty.conf`::
 
     # Create a new window splitting the space used by the existing one so that
     # the two windows are placed one above the other
-    map F5 launch --location=hsplit
+    map f5 launch --location=hsplit
 
     # Create a new window splitting the space used by the existing one so that
     # the two windows are placed side by side
-    map F6 launch --location=vsplit
+    map f6 launch --location=vsplit
+
+    # Create a new window splitting the space used by the existing one so that
+    # the two windows are placed side by side if the existing window is wide or
+    # one above the other if the existing window is tall.
+    map f4 launch --location=split
 
     # Rotate the current split, chaging its split axis from vertical to
     # horizontal or vice versa
-    map F7 layout_action rotate
+    map f7 layout_action rotate
 
     # Move the active window in the indicated direction
     map shift+up move_window up
@@ -148,22 +167,28 @@ define a few extra key bindings in :file:`kitty.conf`::
     map shift+right move_window right
     map shift+down move_window down
 
+    # Move the active window to the indicated screen edge
+    map ctrl+shift+up layout_action move_to_screen_edge top
+    map ctrl+shift+left layout_action move_to_screen_edge left
+    map ctrl+shift+right layout_action move_to_screen_edge right
+    map ctrl+shift+down layout_action move_to_screen_edge bottom
+
     # Switch focus to the neighboring window in the indicated direction
     map ctrl+left neighboring_window left
     map ctrl+right neighboring_window right
     map ctrl+up neighboring_window up
     map ctrl+down neighboring_window down
 
-Windows can be resized using :ref:`window_resizing`.  You can swap the windows
+Windows can be resized using :ref:`window_resizing`. You can swap the windows
 in a split using the ``rotate`` action with an argument of ``180`` and rotate
 and swap with an argument of ``270``.
 
 This layout takes one option, ``split_axis`` that controls whether new windows
-are placed into vertical or horizontal splits when a ``--location`` is not
+are placed into vertical or horizontal splits when a :option:`--location <launch
-specified. A value of ``horizontal`` (same as ``--location=vsplit``)
+--location>` is not specified. A value of ``horizontal`` (same as
-means when a new split is created the two windows will be placed side by side
+``--location=vsplit``) means when a new split is created the two windows will be
-and a value of ``vertical`` (same as ``--location=hsplit``) means the two
+placed side by side and a value of ``vertical`` (same as ``--location=hsplit``)
-windows will be placed one on top of the other. By default::
+means the two windows will be placed one on top of the other. By default::
 
     enabled_layouts splits:split_axis=horizontal
 
@@ -188,7 +213,7 @@ windows will be placed one on top of the other. By default::
 The Horizontal Layout
 ------------------------
 
-All windows are shown side by side. Has no options::
+All windows are shown side by side. This layout has no options::
 
     enabled_layouts horizontal
 
@@ -208,7 +233,7 @@ All windows are shown side by side. Has no options::
 The Vertical Layout
 -----------------------
 
-All windows are shown one below the other. Has no options::
+All windows are shown one below the other. This layout has no options::
 
     enabled_layouts vertical
 
@@ -234,37 +259,38 @@ Resizing windows
 
 You can resize windows inside layouts. Press :sc:`start_resizing_window` (also
 :kbd:`⌘+r` on macOS) to enter resizing mode and follow the on-screen
-instructions.  In a given window layout only some operations may be possible
+instructions. In a given window layout only some operations may be possible for
-for a particular window. For example, in the Tall layout you can make the first
+a particular window. For example, in the *Tall* layout you can make the first
 window wider/narrower, but not taller/shorter. Note that what you are resizing
 is actually not a window, but a row/column in the layout, all windows in that
 row/column will be resized.
 
 You can also define shortcuts in :file:`kitty.conf` to make the active window
-wider, narrower, taller, or shorter by mapping to the ``resize_window``
+wider, narrower, taller, or shorter by mapping to the :ac:`resize_window`
 action, for example::
 
    map ctrl+left resize_window narrower
    map ctrl+right resize_window wider
    map ctrl+up resize_window taller
    map ctrl+down resize_window shorter 3
+   # reset all windows in the tab to default sizes
+   map ctrl+home resize_window reset
 
-The ``resize_window`` action has a second, optional argument to control
+The :ac:`resize_window` action has a second optional argument to control
 the resizing increment (a positive integer that defaults to 1).
 
-
+Some layouts take options to control their behavior. For example, the *Fat*
-Some layouts take options to control their behavior. For example, the ``fat``
+and *Tall* layouts accept the ``bias`` and ``full_size`` options to control
-and ``tall`` layouts accept the ``bias`` and ``full_size`` options to control
+how the available space is split up. To specify the option, in :opt:`kitty.conf
-how the available space is split up.
+<enabled_layouts>` use::
-To specify the option, in :opt:`kitty.conf <enabled_layouts>` use::
 
     enabled_layouts tall:bias=70;full_size=2
 
 This will have ``2`` instead of a single tall window, that occupy ``70%``
-instead of ``50%`` of available width. ``bias`` can be any number between 10
+instead of ``50%`` of available width. ``bias`` can be any number between ``10``
-and 90.
+and ``90``.
 
 Writing a new layout only requires about two hundred lines of code, so if there
 is some layout you want, take a look at one of the existing layouts in the
-`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`_
+`layout <https://github.com/kovidgoyal/kitty/tree/master/kitty/layout>`__
 package and submit a pull request!

docs/marks.rst

@@ -9,12 +9,12 @@ running programs or similar. Lets start with a few examples:
 Examples
 ----------
 
-Suppose we want to be able to highlight the word ERROR in the current window.
+Suppose we want to be able to highlight the word :code:`ERROR` in the current
-Add the following to :file:`kitty.conf`::
+window. Add the following to :file:`kitty.conf`::
 
     map f1 toggle_marker text 1 ERROR
 
-Now when you press :kbd:`F1` all instances of the word :code:`ERROR` will be
+Now when you press :kbd:`F1`, all instances of the word :code:`ERROR` will be
 highlighted. To turn off the highlighting, press :kbd:`F1` again.
 If you want to make it case-insensitive, use::
 
@@ -39,41 +39,40 @@ can control the colors used for these groups in :file:`kitty.conf` with::
 
 
 .. note::
-    For performance reasons, matching is done per line only, and only when that line is
+    For performance reasons, matching is done per line only, and only when that
-    altered in any way. So you cannot match text that stretches across multiple
+    line is altered in any way. So you cannot match text that stretches across
-    lines.
+    multiple lines.
 
 
 Creating markers dynamically
 ---------------------------------
 
 If you want to create markers dynamically rather than pre-defining them in
-:file:`kitty.conf` you can do so as follows::
+:file:`kitty.conf`, you can do so as follows::
 
     map f1 create_marker
     map f2 remove_marker
 
-Then pressing :kbd:`F1` will allow you to enter the marker definition and set
+Then pressing :kbd:`F1` will allow you to enter the marker definition and set it
-it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
+and pressing :kbd:`F2` will remove the marker. :ac:`create_marker` accepts the
-the same syntax as ``toggle_marker`` above. Note that while creating
+same syntax as :ac:`toggle_marker` above. Note that while creating markers, the
-markers, the prompt has history so you can easily re-use previous marker
+prompt has history so you can easily re-use previous marker expressions.
-expressions.
 
-You can also use the facilities for :doc:`remote-control` to dynamically
+You can also use the facilities for :doc:`remote-control` to dynamically add or
-add/remove markers.
+remove markers.
 
 
 Scrolling to marks
 --------------------
 
-kitty has an action to scroll to the next line that contains a mark. You can
+kitty has a :ac:`scroll_to_mark` action to scroll to the next line that contains
-use it by mapping it to some shortcut in :file:`kitty.conf`::
+a mark. You can use it by mapping it to some shortcut in :file:`kitty.conf`::
 
     map ctrl+p scroll_to_mark prev
     map ctrl+n scroll_to_mark next
 
-Then pressing :kbd:`ctrl+p` will scroll to the first line in the scrollback
+Then pressing :kbd:`Ctrl+P` will scroll to the first line in the scrollback
-buffer above the current top line that contains a mark. Pressing :kbd:`ctrl+n`
+buffer above the current top line that contains a mark. Pressing :kbd:`Ctrl+N`
 will scroll to show the first line below the current last line that contains
 a mark. If you wish to jump to a mark of a specific type, you can add that to
 the mapping::
@@ -86,26 +85,26 @@ Which will scroll only to marks of type 1.
 The full syntax for creating marks
 -------------------------------------
 
-The syntax of the :code:`toggle_marker` command is::
+The syntax of the :ac:`toggle_marker` action is::
 
     toggle_marker <marker-type> <specification>
 
 Here :code:`marker-type` is one of:
 
-* :code:`text` - simple substring matching
+* :code:`text` - Simple substring matching
-* :code:`itext` - case-insensitive substring matching
+* :code:`itext` - Case-insensitive substring matching
-* :code:`regex` - A python regular expression
+* :code:`regex` - A Python regular expression
-* :code:`iregex` - A case-insensitive python regular expression
+* :code:`iregex` - A case-insensitive Python regular expression
-* :code:`function` - An arbitrary function defined in a python file, see :ref:`marker_funcs`.
+* :code:`function` - An arbitrary function defined in a Python file, see :ref:`marker_funcs`.
 
 .. _marker_funcs:
 
 Arbitrary marker functions
 -----------------------------
 
-You can create your own marker functions. Create a python file named
+You can create your own marker functions. Create a Python file named
-:file:`mymarker.py` and in it create a :code:`marker` function. This
+:file:`mymarker.py` and in it create a :code:`marker` function. This function
-function receives the text of the line as input and must yield three numbers,
+receives the text of the line as input and must yield three numbers,
 the starting character position, the ending character position and the mark
 group (1-3). For example:
 
@@ -122,6 +121,7 @@ Save this file somewhere and in :file:`kitty.conf`, use::
 
     map f1 toggle_marker function /path/to/mymarker.py
 
-If you save the file in the kitty config directory, you can use::
+If you save the file in the :ref:`kitty config directory <confloc>`, you can
+use::
 
     map f1 toggle_marker function mymarker.py

docs/open_actions.rst

@@ -1,15 +1,14 @@
 Scripting the mouse click
 ======================================================
 
-|kitty| has support for `terminal hyperlinks
+|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
-<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
+generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
-are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
+:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
-:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these
+these hyperlinks in |kitty|.
-hyperlinks in |kitty|.
 
-You can tell kitty to take arbitrarily many, complex actions
+You can tell kitty to take arbitrarily many, complex actions when a link is
-when a link is clicked. Let us illustrate with some examples, first. Create
+clicked. Let us illustrate with some examples, first. Create the file
-the file :file:`~/.config/kitty/open-actions.conf` with the following:
+:file:`~/.config/kitty/open-actions.conf` with the following:
 
 .. code:: conf
 
@@ -22,6 +21,13 @@ Now, run ``ls --hyperlink=auto`` in kitty and click on the filename of an
 image, holding down :kbd:`ctrl+shift`. It will be opened over the current
 window. Press any key to close it.
 
+.. note::
+
+    The :program:`ls` comes with macOS does not support hyperlink, you need to
+    install `GNU Coreutils <https://www.gnu.org/software/coreutils/>`__. If you
+    install it via `Homebrew <https://formulae.brew.sh/formula/coreutils>`__, it
+    will be :program:`gls`.
+
 Each entry in :file:`open-actions.conf` consists of one or more
 :ref:`matching_criteria`, such as ``protocol`` and ``mime`` and one or more
 ``action`` entries. In the example above kitty uses the :doc:`launch <launch>`
@@ -29,8 +35,8 @@ action which can be used to run external programs. Entries are separated by
 blank lines.
 
 Actions are very powerful, anything that you can map to a key combination in
-`kitty.conf` can be used as an action. You can specify more than one action per
+:file:`kitty.conf` can be used as an action. You can specify more than one
-entry if you like, for example:
+action per entry if you like, for example:
 
 
 .. code:: conf
@@ -58,9 +64,20 @@ some special variables, documented below:
 ``FRAGMENT``
     The fragment (unquoted), if any of the URL or the empty string.
 
+``URL_PATH``
+    The path, query and fragment portions of the URL, without any
+    unquoting.
+
+``EDITOR``
+    The terminal based text editor. The configured :opt:`editor` in
+    :file:`kitty.conf` is preferred.
+
+``SHELL``
+    The path to the shell. The configured :opt:`shell` in :file:`kitty.conf` is
+    preferred, without arguments.
 
 .. note::
-   You can use the :opt:`action_alias` option just as in kitty.conf to
+   You can use the :opt:`action_alias` option just as in :file:`kitty.conf` to
    define aliases for frequently used actions.
 
 
@@ -77,7 +94,7 @@ lines. The various available criteria are:
 
 ``protocol``
     A comma separated list of protocols, for example: ``http, https``. If
-    absent, there is no constraint on protocol
+    absent, there is no constraint on protocol.
 
 ``url``
     A regular expression that must match against the entire (unquoted) URL
@@ -88,11 +105,13 @@ lines. The various available criteria are:
 
 ``mime``
     A comma separated list of MIME types, for example: ``text/*, image/*,
-    application/pdf``. You can add MIME types to kitty by creating the
+    application/pdf``. You can add MIME types to kitty by creating a file named
-    :file:`mime.types` in the kitty configuration directory. Useful if your
+    :file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
-    system MIME database does not have definitions you need. This file is
+    Useful if your system MIME database does not have definitions you need. This
-    in the standard format of one definition per line, like: ``text/plain rst
+    file is in the standard format of one definition per line, like:
-    md``. Note that the MIME type for directories is ``inode/directory``.
+    ``text/plain rst md``. Note that the MIME type for directories is
+    ``inode/directory``. MIME types are detected based on file extension, not
+    file contents.
 
 ``ext``
     A comma separated list of file extensions, for example: ``jpeg, tar.gz``
@@ -102,39 +121,42 @@ lines. The various available criteria are:
     ``image-??.png``
 
 
+.. _launch_actions:
+
 Scripting the opening of files with kitty on macOS
 -------------------------------------------------------
 
-On macOS you can use :guilabel:`Open With` in Finder or drag and drop files
+On macOS you can use :guilabel:`Open With` in Finder or drag and drop files and
-onto the kitty dock icon to open them with kitty. The default action
+URLs onto the kitty dock icon to open them with kitty. The default actions are:
-is to open text files in your editor and images using the icat kitten.
-Shell scripts are run in a shell. You can customize these actions by creating
-a :file:`launch-actions.conf` file in the kitty config directory, just like
-the :file:`open-actions.conf` file above. For example:
 
-.. code:: conf
+* Open text files in your editor and images using the icat kitten.
+* Run shell scripts in a shell
+* Open SSH urls using the ssh command
 
-    # Open script files based on their shebangs
+These actions can also be executed from the command line by running::
-    protocol file
-    ext sh,command,tool
-    action launch --hold --type=os-window kitty +shebang $FILE_PATH {SHELL}
 
-    # Open shell specific script files
+    kitty +open file_or_url another_url ...
-    protocol file
-    ext fish,bash,zsh
-    action launch --hold --type=os-window kitty +shebang $FILE_PATH __ext__
 
-    # Open directories
+    # macOS only
-    protocol file
+    open -a kitty.app file_or_url another_url ...
-    mime inode/directory
-    action launch --type=os-window --cwd $FILE_PATH
 
-    # Open text files without fragments in the editor
+Since macOS lacks an official interface to set default URL scheme handlers,
-    protocol file
+kitty has a command you can use for it. The first argument for is the URL
-    mime text/*
+scheme, and the second optional argument is the bundle id of the app, which
-    action launch --type=os-window $EDITOR $FILE_PATH
+defaults to kitty, if not specified. For example:
 
-    # Open image files with icat
+.. code-block:: sh
-    protocol file
+
-    mime image/*
+    # Set kitty as the handler for ssh:// URLs
-    action launch --type=os-window kitty +kitten icat --hold $FILE_PATH
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' ssh
+    # Set someapp as the handler for xyz:// URLs
+    kitty +runpy 'from kitty.fast_data_types import cocoa_set_url_handler; import sys; cocoa_set_url_handler(*sys.argv[1:]); print("OK")' xyz someapp.bundle.identifier
+
+You can customize these actions by creating a :file:`launch-actions.conf` file
+in the :ref:`kitty config directory <confloc>`, just like the
+:file:`open-actions.conf` file above. For example:
+
+.. literalinclude:: ../kitty/open_actions.py
+   :language: conf
+   :start-at: # Open script files
+   :end-before: '''.splitlines()))

docs/overview.rst

@@ -4,23 +4,23 @@ Overview
 Design philosophy
 -------------------
 
-|kitty| is designed for power keyboard users. To that end all its controls
+|kitty| is designed for power keyboard users. To that end all its controls work
-work with the keyboard (although it fully supports mouse interactions as
+with the keyboard (although it fully supports mouse interactions as well). Its
-well). Its configuration is a simple, human editable, single file for
+configuration is a simple, human editable, single file for easy reproducibility
-easy reproducibility (I like to store configuration in source control).
+(I like to store configuration in source control).
 
 The code in |kitty| is designed to be simple, modular and hackable. It is
-written in a mix of C (for performance sensitive parts) and Python (for
+written in a mix of C (for performance sensitive parts), Python (for easy
-easy hackability of the UI). It does not depend on any large and complex
+extensibility and flexibility of the UI) and Go (for the command line
-UI toolkit, using only OpenGL for rendering everything.
+:term:`kittens`).  It does not depend on any large and complex UI toolkit,
+using only OpenGL for rendering everything.
 
-Finally, |kitty| is designed from the ground up to support all modern
+Finally, |kitty| is designed from the ground up to support all modern terminal
-terminal features, such as unicode, true color, bold/italic fonts, text
+features, such as Unicode, true color, bold/italic fonts, text formatting, etc.
-formatting, etc. It even extends existing text formatting escape codes,
+It even extends existing text formatting escape codes, to add support for
-to add support for features not available elsewhere, such as colored and
+features not available elsewhere, such as colored and styled (curly) underlines.
-styled (curly) underlines. One of the design goals of |kitty| is to be
+One of the design goals of |kitty| is to be easily extensible so that new
-easily extensible so that new features can be added in the future with
+features can be added in the future with relatively little effort.
-relatively little effort.
 
 .. include:: basic.rst
 
@@ -28,10 +28,10 @@ relatively little effort.
 Configuring kitty
 -------------------
 
-|kitty| is highly configurable, everything from keyboard shortcuts to
+|kitty| is highly configurable, everything from keyboard shortcuts to painting
-painting frames-per-second. Press :sc:`edit_config_file` in kitty
+frames-per-second. Press :sc:`edit_config_file` in kitty to open its fully
-to open its fully commented sample config file in your text editor.
+commented sample config file in your text editor. For details see the
-For details see the :doc:`configuration docs <conf>`.
+:doc:`configuration docs <conf>`.
 
 .. toctree::
    :hidden:
@@ -51,17 +51,26 @@ windows automatically, resizing and moving them as needed. You can create a new
 
 Currently, there are seven layouts available:
 
-* **Fat** -- One (or optionally more) windows are shown full width on the top, the rest of the windows are shown side-by-side on the bottom
+* **Fat** -- One (or optionally more) windows are shown full width on the top,
+  the rest of the windows are shown side-by-side on the bottom
+
 * **Grid** -- All windows are shown in a grid
+
 * **Horizontal** -- All windows are shown side-by-side
-* **Splits** -- Windows arranged in arbitrary patterns created using horizontal and vertical splits
+
+* **Splits** -- Windows arranged in arbitrary patterns created using horizontal
+  and vertical splits
+
 * **Stack** -- Only a single maximized window is shown at a time
-* **Tall** -- One (or optionally more) windows are shown full height on the left, the rest of the windows are shown one below the other on the right
+
+* **Tall** -- One (or optionally more) windows are shown full height on the
+  left, the rest of the windows are shown one below the other on the right
+
 * **Vertical** -- All windows are shown one below the other
 
 By default, all layouts are enabled and you can switch between layouts using
 the :sc:`next_layout` key combination. You can also create shortcuts to select
-particular layouts, and choose which layouts you want to enable/disable, see
+particular layouts, and choose which layouts you want to enable, see
 :ref:`conf-kitty-shortcuts.layout` for examples. The first layout listed in
 :opt:`enabled_layouts` becomes the default layout.
 
@@ -77,11 +86,11 @@ Extending kitty
 ------------------
 
 kitty has a powerful framework for scripting. You can create small terminal
-programs called :doc:`kittens <kittens_intro>`. These can used to add features
+programs called :doc:`kittens <kittens_intro>`. These can be used to add features
 to kitty, for example, :doc:`editing remote files <kittens/remote_file>` or
-:doc:`inputting unicode characters <kittens/unicode_input>`. They can also be
+:doc:`inputting Unicode characters <kittens/unicode_input>`. They can also be
 used to create programs that leverage kitty's powerful features, for example,
-:doc:`viewing images <kittens/icat>` or :doc:`diffing files with images
+:doc:`viewing images <kittens/icat>` or :doc:`diffing files with image support
 <kittens/diff>`.
 
 You can :doc:`create your own kittens to scratch your own itches
@@ -101,9 +110,9 @@ Remote control
 |kitty| has a very powerful system that allows you to control it from the
 :doc:`shell prompt, even over SSH <remote-control>`. You can change colors,
 fonts, open new :term:`windows <window>`, :term:`tabs <tab>`, set their titles,
-change window layout, get text
+change window layout, get text from one window and send text to another, etc.
-from one window and send text to another, etc, etc. The possibilities are
+The possibilities are endless. See the :doc:`tutorial <remote-control>` to get
-endless. See the :doc:`tutorial <remote-control>` to get started.
+started.
 
 .. toctree::
    :hidden:
@@ -117,10 +126,9 @@ Startup Sessions
 ------------------
 
 You can control the :term:`tabs <tab>`, :term:`kitty window <window>` layout,
-working directory, startup programs,
+working directory, startup programs, etc. by creating a *session* file and using
-etc. by creating a "session" file and using the :option:`kitty --session`
+the :option:`kitty --session` command line flag or the :opt:`startup_session`
-command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
+option in :file:`kitty.conf`. An example, showing all available commands:
-For example:
 
 .. code-block:: session
 
@@ -130,37 +138,48 @@ For example:
     cd ~
     # Create a window and run the specified command in it
     launch zsh
-    # Create a window with some environment variables set and run
+    # Create a window with some environment variables set and run vim in it
-    # vim in it
     launch --env FOO=BAR vim
     # Set the title for the next window
     launch --title "Chat with x" irssi --profile x
 
-    # Create a new tab (the part after new_tab is the optional tab
+    # Create a new tab
-    # name which will be displayed in the tab bar, if omitted, the
+    # The part after new_tab is the optional tab title which will be displayed in
-    # title of the active window will be used instead)
+    # the tab bar, if omitted, the title of the active window will be used instead.
     new_tab my tab
     cd ~/somewhere
     # Set the layouts allowed in this tab
-    enabled_layouts tall, stack
+    enabled_layouts tall,stack
     # Set the current layout
     layout stack
     launch zsh
 
     # Create a new OS window
+    # Any definitions specified before the first new_os_window will apply to first OS window.
     new_os_window
-    # set new window size to 80x25 cells
+    # Set new window size to 80x24 cells
-    os_window_size 80c 25c
+    os_window_size 80c 24c
-    # set the --class for the new OS window
+    # Set the --class for the new OS window
     os_window_class mywindow
+    # Change the OS window state to normal, fullscreen, maximized or minimized
+    os_window_state normal
     launch sh
-    # Make the current window the active (focused) window
+    # Resize the current window (see the resize_window action for details)
+    resize_window wider 2
+    # Make the current window the active (focused) window in its tab
     focus
+    # Make the current OS Window the globally active window (not supported on Wayland)
+    focus_os_window
     launch emacs
 
 .. note::
-    The :doc:`launch <launch>` command when used in a session file
+    The :doc:`launch <launch>` command when used in a session file cannot create
-    cannot create new OS windows, or tabs.
+    new OS windows, or tabs.
+
+.. note::
+   Environment variables of the for :code:`${NAME}` or :code:`$NAME` are
+   expanded in the session file, except in the *arguments* (not options) to the
+   launch command.
 
 
 Creating tabs/windows
@@ -182,25 +201,25 @@ Mouse features
 * You can click on a URL to open it in a browser.
 * You can double click to select a word and then drag to select more words.
 * You can triple click to select a line and then drag to select more lines.
-* You can triple click while holding :kbd:`ctrl+alt` to select from clicked
+* You can triple click while holding :kbd:`Ctrl+Alt` to select from clicked
   point to end of line.
 * You can right click to extend a previous selection.
-* You can hold down :kbd:`ctrl+alt` and drag with the mouse to select in
+* You can hold down :kbd:`Ctrl+Alt` and drag with the mouse to select in
   columns.
-* Selecting text automatically copies it to the primary clipboard (on
+* Selecting text automatically copies it to the primary clipboard (on platforms
-  platforms with a primary clipboard).
-* You can middle click to paste from the primary clipboard (on platforms
   with a primary clipboard).
-* You can right click while holding :kbd:`ctrl+shift` to open the output
+* You can middle click to paste from the primary clipboard (on platforms with a
-  of the clicked on command in a pager (requires :ref:`shell_integration`)
+  primary clipboard).
-* You can select text with kitty even when a terminal program has grabbed
+* You can right click while holding :kbd:`Ctrl+Shift` to open the output of the
-  the mouse by holding down the :kbd:`shift` key
+  clicked on command in a pager (requires :ref:`shell_integration`)
+* You can select text with kitty even when a terminal program has grabbed the
+  mouse by holding down the :kbd:`Shift` key
 
 All these actions can be customized in :file:`kitty.conf` as described
 :ref:`here <conf-kitty-mouse.mousemap>`.
 
-You can also customize what happens when clicking on :term:`hyperlinks` in kitty,
+You can also customize what happens when clicking on :term:`hyperlinks` in
-having it open files in your editor, download remote files, open things
+kitty, having it open files in your editor, download remote files, open things
 in your browser, etc.
 
 For details, see :doc:`here <open_actions>`.
@@ -214,11 +233,11 @@ Font control
 -----------------
 
 |kitty| has extremely flexible and powerful font selection features. You can
-specify individual families for the regular, bold, italic and bold+italic
+specify individual families for the regular, bold, italic and bold+italic fonts.
-fonts. You can even specify specific font families for specific ranges of
+You can even specify specific font families for specific ranges of Unicode
-unicode characters. This allows precise control over text rendering. It can
+characters. This allows precise control over text rendering. It can come in
-come in handy for applications like powerline, without the need to use patched
+handy for applications like powerline, without the need to use patched fonts.
-fonts. See the various font related configuration directives in
+See the various font related configuration directives in
 :ref:`conf-kitty-fonts`.
 
 
@@ -228,29 +247,29 @@ The scrollback buffer
 -----------------------
 
 |kitty| supports scrolling back to view history, just like most terminals. You
-can use either keyboard shortcuts or the mouse scroll wheel to do so.  However,
+can use either keyboard shortcuts or the mouse scroll wheel to do so. However,
-|kitty| has an extra, neat feature. Sometimes you need to explore the
+|kitty| has an extra, neat feature. Sometimes you need to explore the scrollback
-scrollback buffer in more detail, maybe search for some text or refer to it
+buffer in more detail, maybe search for some text or refer to it side-by-side
-side-by-side while typing in a follow-up command. |kitty| allows you to do this
+while typing in a follow-up command. |kitty| allows you to do this by pressing
-by pressing the :sc:`show_scrollback` key-combination, which will open the
+the :sc:`show_scrollback` shortcut, which will open the scrollback buffer in
-scrollback buffer in your favorite pager program (which is ``less`` by default).
+your favorite pager program (which is :program:`less` by default). Colors and
-Colors and text formatting are preserved. You can explore the scrollback buffer
+text formatting are preserved. You can explore the scrollback buffer comfortably
-comfortably within the pager.
+within the pager.
 
 Additionally, you can pipe the contents of the scrollback buffer to an
-arbitrary, command running in a new :term:`window`, :term:`tab` or :term:`overlay`,
+arbitrary, command running in a new :term:`window`, :term:`tab` or
-for example::
+:term:`overlay`. For example::
 
    map f1 launch --stdin-source=@screen_scrollback --stdin-add-formatting less +G -R
 
-Would open the scrollback buffer in a new :term:`window` when you press the :kbd:`F1`
+Would open the scrollback buffer in a new :term:`window` when you press the
-key. See :sc:`show_scrollback <show_scrollback>` for details.
+:kbd:`F1` key. See :sc:`show_scrollback <show_scrollback>` for details.
 
-If you want to use it with an editor such as vim to get more powerful features,
+If you want to use it with an editor such as :program:`vim` to get more powerful
-you can see tips for doing so, in :iss:`this thread <719>`.
+features, you can see tips for doing so, in :iss:`this thread <719>`.
 
-If you wish to store very large amounts of scrollback to view using the piping or
+If you wish to store very large amounts of scrollback to view using the piping
-:sc:`show_scrollback <show_scrollback>` features, you can use the
+or :sc:`show_scrollback <show_scrollback>` features, you can use the
 :opt:`scrollback_pager_history_size` option.
 
 
@@ -258,8 +277,8 @@ Integration with shells
 ---------------------------------
 
 kitty has the ability to integrate closely within common shells, such as `zsh
-<https://www.zsh.org/>`_, `fish <https://fishshell.com>`_ and `bash
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
-<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
+<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
 previous prompts in the scrollback, viewing the output of the last command in
 :program:`less`, using the mouse to move the cursor while editing prompts, etc.
 See :doc:`shell-integration` for details.
@@ -274,17 +293,16 @@ See :doc:`shell-integration` for details.
 Multiple copy/paste buffers
 -----------------------------
 
-In addition to being able to copy/paste from the system clipboard, in |kitty| you
+In addition to being able to copy/paste from the system clipboard, in |kitty|
-can also setup an arbitrary number of copy paste buffers. To do so, simply add
+you can also setup an arbitrary number of copy paste buffers. To do so, simply
-something like the following to your :file:`kitty.conf`::
+add something like the following to your :file:`kitty.conf`::
 
    map f1 copy_to_buffer a
    map f2 paste_from_buffer a
 
 This will allow you to press :kbd:`F1` to copy the current selection to an
 internal buffer named ``a`` and :kbd:`F2` to paste from that buffer. The buffer
-names are arbitrary strings, so you can define as many such buffers as you
+names are arbitrary strings, so you can define as many such buffers as you need.
-need.
 
 
 Marks

docs/performance.rst

@@ -2,30 +2,31 @@ Performance
 ===================
 
 The main goals for |kitty| performance are user perceived latency while typing
-and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to find
+and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to
-an optimum balance for these. To that end it keeps a cache of each rendered
+find an optimum balance for these. To that end it keeps a cache of each rendered
-glyph in video RAM so that font rendering is not a bottleneck.  Interaction
+glyph in video RAM so that font rendering is not a bottleneck. Interaction with
-with child programs takes place in a separate thread from rendering, to improve
+child programs takes place in a separate thread from rendering, to improve
 smoothness.
 
-There are two parameters you can tune to adjust the performance. :opt:`repaint_delay`
+There are two config options you can tune to adjust the performance,
-and :opt:`input_delay`. These control the artificial delays introduced into the
+:opt:`repaint_delay` and :opt:`input_delay`. These control the artificial delays
-render loop to reduce CPU usage. See :ref:`conf-kitty-performance` for details.
+introduced into the render loop to reduce CPU usage. See
-See also the :opt:`sync_to_monitor` option to further decrease latency at the cost
+:ref:`conf-kitty-performance` for details. See also the :opt:`sync_to_monitor`
-of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+option to further decrease latency at the cost of some `screen tearing
+<https://en.wikipedia.org/wiki/Screen_tearing>`__ while scrolling.
 
-You can generate detailed per-function performance data using `gperftools
+You can generate detailed per-function performance data using
-<https://github.com/gperftools/gperftools>`_. Build |kitty| with `make
+`gperftools <https://github.com/gperftools/gperftools>`__. Build |kitty| with
-profile`. Run kitty and perform the task you want to analyse, for example,
+``make profile``. Run kitty and perform the task you want to analyse, for
-scrolling a large file with `less`. After you quit, function call statistics
+example, scrolling a large file with :program:`less`. After you quit, function
-will be printed to `stdout` and you can use tools like *kcachegrind* for more
+call statistics will be printed to STDOUT and you can use tools like
-detailed analysis.
+*KCachegrind* for more detailed analysis.
 
-Here are some CPU usage numbers for the task of scrolling a file continuously
+Here are some CPU usage numbers for the task of scrolling a file continuously in
-in less.  The CPU usage is for the terminal process and X together and is
+:program:`less`. The CPU usage is for the terminal process and X together and is
-measured using htop.  The measurements are taken at the same font and window
+measured using :program:`htop`. The measurements are taken at the same font and
-size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
+window size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz``
-with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
+CPU with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
 7770/8760 / R7 250X]`` GPU.
 
 ==============   =========================
@@ -49,11 +50,11 @@ admittedly biased, eyes).
 
 .. note::
 
-    Some people have asked why kitty does not perform better than terminal XXX in
+    Some people have asked why kitty does not perform better than terminal XXX
-    the test of sinking large amounts of data, such as catting a large text
+    in the test of sinking large amounts of data, such as catting a large text
-    file. The answer is because this is not a goal for kitty. kitty
+    file. The answer is because this is not a goal for kitty. kitty deliberately
-    deliberately throttles input parsing and output rendering to minimize
+    throttles input parsing and output rendering to minimize resource usage
-    resource usage while still being able to sink output faster than any real
+    while still being able to sink output faster than any real world program can
-    world program can produce it. Reducing CPU usage, and hence battery drain
+    produce it. Reducing CPU usage, and hence battery drain while achieving
-    while achieving instant response times and smooth scrolling to a human eye
+    instant response times and smooth scrolling to a human eye is a far more
-    is a far more important goal.
+    important goal.

docs/press-mentions.rst

@@ -1,5 +1,18 @@
 Press mentions of kitty
 ========================
 
-`Console #88 <https://console.substack.com/p/console-88>`__
+`Python Bytes 272 <https://youtu.be/8HKliSbA-gQ?t=815>`__ (Feb 2022)
+    A podcast demoing some of kitty's coolness
+
+`Console #88 <https://console.substack.com/p/console-88>`__ (Jan 2022)
     An interview with Kovid about kitty
+
+
+Video reviews
+--------------
+
+`Review (Jan 2021) <https://www.youtube.com/watch?v=TTzP2zYJn2k>`__
+    A kitty review by distrotube
+
+`Review (Dec 2020) <https://www.youtube.com/watch?v=KUMkLhFeBrI>`__
+    A kitty review/intro by TechHut

docs/protocol-extensions.rst

@@ -1,23 +1,24 @@
 Terminal protocol extensions
 ===================================
 
-|kitty| has extensions to the legacy terminal protocol, to enable advanced features.
+|kitty| has extensions to the legacy terminal protocol, to enable advanced
-These are typically in the form of new or re-purposed escape codes. While these
+features. These are typically in the form of new or re-purposed escape codes.
-extensions are currently |kitty| specific, it would be nice to get some of them
+While these extensions are currently |kitty| specific, it would be nice to get
-adopted more broadly, to push the state of terminal emulators forward.
+some of them adopted more broadly, to push the state of terminal emulators
+forward.
 
 The goal of these extensions is to be as small and unobtrusive as possible,
-while filling in some gaps in the existing xterm protocol. In particular, one
+while filling in some gaps in the existing xterm protocol. In particular, one of
-of the goals of this specification is explicitly not to "re-imagine" the tty.
+the goals of this specification is explicitly not to "re-imagine" the TTY. The
-The tty should remain what it is -- a device for efficiently processing text
+TTY should remain what it is -- a device for efficiently processing text
 received as a simple byte stream. Another objective is to only move the minimum
-possible amount of extra functionality into the terminal program itself. This
+possible amount of extra functionality into the terminal program itself. This is
-is to make it as easy to implement these protocol extensions as possible,
+to make it as easy to implement these protocol extensions as possible, thereby
-thereby hopefully encouraging their widespread adoption.
+hopefully encouraging their widespread adoption.
 
-If you wish to discuss these extensions, propose additions/changes to them
+If you wish to discuss these extensions, propose additions or changes to them,
-please do so by opening issues in the `GitHub
+please do so by opening issues in the `GitHub bug tracker
-<https://github.com/kovidgoyal/kitty/issues>`_ bug tracker.
+<https://github.com/kovidgoyal/kitty/issues>`__.
 
 
 .. toctree::
@@ -31,3 +32,4 @@ please do so by opening issues in the `GitHub
    unscroll
    color-stack
    deccara
+   clipboard

docs/quickstart.rst

@@ -9,9 +9,9 @@ Quickstart
    binary
    build
 
-Pre-built binaries of |kitty| are available for both macOS and Linux.
+Pre-built binaries of |kitty| are available for both macOS and Linux. See the
-See the :doc:`binary install instructions </binary>`. You can also
+:doc:`binary install instructions </binary>`. You can also :doc:`build from
-:doc:`build from source </build>`.
+source </build>`.
 
 Additionally, you can use your favorite package manager to install the |kitty|
 package, but note that some Linux distribution packages are woefully outdated.
@@ -25,4 +25,4 @@ and Linux.
 See :doc:`Configuring kitty <conf>` for help on configuring |kitty| and
 :doc:`Invocation <invocation>` for the command line arguments |kitty| supports.
 
-For a tour of kitty's design and features, see the :doc:`/overview`.
+For a tour of kitty's design and features, see the :doc:`overview`.

docs/rc_protocol.rst

@@ -7,34 +7,101 @@ form::
 
     <ESC>P@kitty-cmd<JSON object><ESC>\
 
-Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
+Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form:
+
+.. code-block:: json
 
     {
         "cmd": "command name",
-        "version": <kitty version>,
+        "version": "<kitty version>",
-        "no_response": <Optional Boolean>,
+        "no_response": "<Optional Boolean>",
-        "payload": <Optional JSON object>,
+        "kitty_window_id": "<Optional value of the KITTY_WINDOW_ID env var>",
+        "payload": "<Optional JSON object>"
     }
 
-The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are developing a
+The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are
-standalone client, use the kitty version that you are developing against. Using
+developing a standalone client, use the kitty version that you are developing
-a version greater than the version of the kitty instance you are talking to,
+against. Using a version greater than the version of the kitty instance you are
-will cause a failure.
+talking to, will cause a failure.
 
 Set ``no_response`` to ``true`` if you don't want a response from kitty.
 
-The optional payload is a JSON object that is specific to the actual command being sent.
+The optional payload is a JSON object that is specific to the actual command
-The fields in the object for every command are documented below.
+being sent. The fields in the object for every command are documented below.
 
 As a quick example showing how easy to use this protocol is, we will implement
-the ``@ ls`` command from the shell using only shell tools. First, run kitty
+the ``@ ls`` command from the shell using only shell tools.
-as::
+
+First, run kitty as::
 
     kitty -o allow_remote_control=socket-only --listen-on unix:/tmp/test
 
 Now, in a different terminal, you can get the pretty printed ``@ ls`` output
 with the following command line::
 
-    echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
+    echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .
+
+There is also the statically compiled stand-alone executable ``kitten``
+that can be used for this, available from the `kitty releases
+<https://github.com/kovidgoyal/kitty/releases>`__ page::
+
+    kitten @ --help
+
+.. _rc_crypto:
+
+Encrypted communication
+--------------------------
+
+.. versionadded:: 0.26.0
+
+When using the :opt:`remote_control_password` option communication to the
+terminal is encrypted to keep the password secure. A public key is used from
+the :envvar:`KITTY_PUBLIC_KEY` environment variable. Currently, only one
+encryption protocol is supported. The protocol number is present in
+:envvar:`KITTY_PUBLIC_KEY` as ``1``. The key data in this environment variable
+is :rfc:`Base-85 <1924>` encoded.  The algorithm used is `Elliptic Curve Diffie
+Helman <https://en.wikipedia.org/wiki/Elliptic-curve_Diffie–Hellman>`__ with
+the `X25519 curve <https://en.wikipedia.org/wiki/Curve25519>`__. A time based
+nonce is used to minimise replay attacks. The original JSON command has the
+fields: ``password`` and ``timestamp`` added. The timestamp is the number of
+nanoseconds since the epoch, excluding leap seconds. Commands with a timestamp
+more than 5 minutes from the current time are rejected. The command is then
+encrypted using AES-256-GCM in authenticated encryption mode, with a symmetric
+key that is derived from the ECDH key-pair by running the shared secret through
+SHA-256 hashing, once.  An IV of at least 96 bits of CSPRNG data is used. The
+tag for authenticated encryption **must** be at least 128 bits long.  The tag
+**must** authenticate only the value of the ``encrypted`` field. A new command
+is created and transmitted that contains the fields:
+
+.. code-block:: json
+
+    {
+        "version": "<kitty version>",
+        "iv": "base85 encoded IV",
+        "tag": "base85 encoded AEAD tag",
+        "pubkey": "base85 encoded ECDH public key of sender",
+        "encrypted": "The original command encrypted and base85 encoded"
+    }
+
+Async and streaming requests
+---------------------------------
+
+Some remote control commands require asynchronous communication, that is, the
+response from the terminal can happen after an arbitrary amount of time. For
+example, the :code:`select-window` command requires the user to select a window
+before a response can be sent. Such command must set the field :code:`async`
+in the JSON block above to a random string that serves as a unique id. The
+client can cancel an async request in flight by adding the :code:`cancel_async`
+field to the JSON block. A async response remains in flight until the terminal
+sends a response to the request. Note that cancellation requests dont need to
+be encrypted as users must not be prompted for these and the worst a malicious
+cancellation request can do is prevent another sync request from getting a
+response.
+
+Similar to async requests are *streaming* requests. In these the client has to
+send a large amount of data to the terminal and so the request is split into
+chunks. In every chunk the JSON block must contain the field ``stream`` set to
+``true`` and ``stream_id`` set to a random long string, that should be the same for
+all chunks in a request. End of data is indicated by sending a chunk with no data.
 
 .. include:: generated/rc.rst

docs/remote-control.rst

@@ -4,9 +4,12 @@ Control kitty from scripts
 .. highlight:: sh
 
 |kitty| can be controlled from scripts or the shell prompt. You can open new
-windows, send arbitrary text input to any window, name windows and tabs, etc.
+windows, send arbitrary text input to any window, change the title of windows
+and tabs, etc.
+
 Let's walk through a few examples of controlling |kitty|.
 
+
 Tutorial
 ------------
 
@@ -14,50 +17,52 @@ Start by running |kitty| as::
 
     kitty -o allow_remote_control=yes -o enabled_layouts=tall
 
-In order for control to work, :opt:`allow_remote_control` must be enabled in
+In order for control to work, :opt:`allow_remote_control` or
-:file:`kitty.conf`. Here we turn it on explicitly at the command line.
+:opt:`remote_control_password` must be enabled in :file:`kitty.conf`. Here we
+turn it on explicitly at the command line.
 
 Now, in the new |kitty| window, enter the command::
 
     kitty @ launch --title Output --keep-focus cat
 
-This will open a new window, running the ``cat`` program that will appear next
+This will open a new window, running the :program:`cat` program that will appear
-to the current window.
+next to the current window.
 
 Let's send some text to this new window::
 
     kitty @ send-text --match cmdline:cat Hello, World
 
-This will make ``Hello, World`` show up in the window running the ``cat`` program.
+This will make ``Hello, World`` show up in the window running the :program:`cat`
-The :option:`kitty @ send-text --match` option is very powerful, it allows selecting windows by their
+program. The :option:`kitty @ send-text --match` option is very powerful, it
-titles, the command line of the program running in the window, the working
+allows selecting windows by their titles, the command line of the program
-directory of the program running in the window, etc.  See ``kitty @ send-text
+running in the window, the working directory of the program running in the
---help`` for details.
+window, etc. See :ref:`kitty @ send-text --help <at-send-text>` for details.
 
 More usefully, you can pipe the output of a command running in one window to
 another window, for example::
 
-    ls | kitty @ send-text --match title:Output --stdin
+    ls | kitty @ send-text --match 'title:^Output' --stdin
 
-This will show the output of ls in the output window instead of the current
+This will show the output of :program:`ls` in the output window instead of the
-window. You can use this technique to, for example, show the output of running
+current window. You can use this technique to, for example, show the output of
-``make`` in your editor in a different window. The possibilities are endless.
+running :program:`make` in your editor in a different window. The possibilities
+are endless.
 
 You can even have things you type show up in a different window. Run::
 
-    kitty @ send-text --match title:Output --stdin
+    kitty @ send-text --match 'title:^Output' --stdin
 
 And type some text, it will show up in the output window, instead of the current
-window. Type ``Ctrl+D`` when you are ready to stop.
+window. Type :kbd:`Ctrl+D` when you are ready to stop.
 
 Now, let's open a new tab::
 
    kitty @ launch --type=tab --tab-title "My Tab" --keep-focus bash
 
 This will open a new tab running the bash shell with the title "My Tab".
-We can change the title of the tab with::
+We can change the title of the tab to "New Title" with::
 
-   kitty @ set-tab-title --match title:My  New Title
+   kitty @ set-tab-title --match 'title:^My' New Title
 
 Let's change the title of the current tab::
 
@@ -65,79 +70,196 @@ Let's change the title of the current tab::
 
 Now lets switch to the newly opened tab::
 
-   kitty @ focus-tab --match title:New
+   kitty @ focus-tab --match 'title:^New'
 
 Similarly, to focus the previously opened output window (which will also switch
 back to the old tab, automatically)::
 
-   kitty @ focus-window --match title:Output
+   kitty @ focus-window --match 'title:^Output'
 
 You can get a listing of available tabs and windows, by running::
 
    kitty @ ls
 
 This outputs a tree of data in JSON format. The top level of the tree is all
-operating system kitty windows. Each OS window has an id and a list of tabs.
+:term:`OS windows <os_window>`. Each OS window has an id and a list of
-Each tab has its own id, a title and a list of windows. Each window has an id,
+:term:`tabs <tab>`. Each tab has its own id, a title and a list of :term:`kitty
-title, current working directory, process id (PID) and command-line of the
+windows <window>`. Each window has an id, title, current working directory,
-process running in the window. You can use this information with :option:`kitty @ focus-window --match`
+process id (PID) and command-line of the process running in the window. You can
-to control individual windows.
+use this information with :option:`kitty @ focus-window --match` to control
+individual windows.
 
-As you can see, it is very easy to control |kitty| using the
+As you can see, it is very easy to control |kitty| using the ``kitty @``
-``kitty @`` messaging system. This tutorial touches only the
+messaging system. This tutorial touches only the surface of what is possible.
-surface of what is possible. See ``kitty @ --help`` for more details.
+See ``kitty @ --help`` for more details.
 
-Note that in the example's above, ``kitty @`` messaging works only when run inside a |kitty| window,
+In the example's above, ``kitty @`` messaging works only when run
-not anywhere. But, within a |kitty| window it even works over SSH. If you want to control
+inside a |kitty| window, not anywhere. But, within a |kitty| window it even
-|kitty| from programs/scripts not running inside a |kitty| window, you have to implement a couple of
+works over SSH. If you want to control |kitty| from programs/scripts not running
-extra steps. First start |kitty| as::
+inside a |kitty| window, see the section on :ref:`using a socket for remote control <rc_via_socket>`
+below.
+
+
+Note that if all you want to do is run a single |kitty| "daemon" and have
+subsequent |kitty| invocations appear as new top-level windows, you can use the
+simpler :option:`kitty --single-instance` option, see ``kitty --help`` for that.
+
+
+.. _rc_via_socket:
+
+Remote control via a socket
+--------------------------------
+First, start |kitty| as::
 
     kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty
 
-The :option:`kitty --listen-on` option tells |kitty| to listen for control messages at the
+The :option:`kitty --listen-on` option tells |kitty| to listen for control
-specified path. See ``kitty --help`` for details. Now you can control this
+messages at the specified UNIX-domain socket. See ``kitty --help`` for details.
-instance of |kitty| using the :option:`kitty @ --to` command line argument to ``kitty @``. For example::
+Now you can control this instance of |kitty| using the :option:`kitty @ --to`
+command line argument to ``kitty @``. For example::
 
     kitty @ --to unix:/tmp/mykitty ls
 
 
-Note that if all you want to do is run a single |kitty| "daemon" and have subsequent
-|kitty| invocations appear as new top-level windows, you can use the simpler :option:`kitty --single-instance`
-option, see ``kitty --help`` for that.
-
 The builtin kitty shell
 --------------------------
 
-You can explore the |kitty| command language more easily using the builtin |kitty|
+You can explore the |kitty| command language more easily using the builtin
-shell. Run ``kitty @`` with no arguments and you will be dropped into the |kitty|
+|kitty| shell. Run ``kitty @`` with no arguments and you will be dropped into
-shell with completion for |kitty| command names and options.
+the |kitty| shell with completion for |kitty| command names and options.
 
 You can even open the |kitty| shell inside a running |kitty| using a simple
 keyboard shortcut (:sc:`kitty_shell` by default).
 
 .. note:: This has the added advantage that you don't need to use
-   ``allow_remote_control`` to make it work.
+   :opt:`allow_remote_control` to make it work.
 
 
 Allowing only some windows to control kitty
 ----------------------------------------------
 
-If you do not want to allow all programs running in |kitty| to control it, you can selectively
+If you do not want to allow all programs running in |kitty| to control it, you
-enable remote control for only some |kitty| windows. Simply create a shortcut
+can selectively enable remote control for only some |kitty| windows. Simply
-such as::
+create a shortcut such as::
 
     map ctrl+k launch --allow-remote-control some_program
 
 Then programs running in windows created with that shortcut can use ``kitty @``
 to control kitty. Note that any program with the right level of permissions can
-still write to the pipes of any other program on the same computer and
+still write to the pipes of any other program on the same computer and therefore
-therefore can control |kitty|. It can, however, be useful to block programs
+can control |kitty|. It can, however, be useful to block programs running on
-running on other computers (for example, over ssh) or as other users.
+other computers (for example, over SSH) or as other users.
 
-.. note:: You dont need ``allow_remote_control`` to make this work as it is
+.. note:: You don't need :opt:`allow_remote_control` to make this work as it is
    limited to only programs running in that specific window. Be careful with
    what programs you run in such windows, since they can effectively control
-   kitty, as if you were running with ``allow_remote_control`` turned on.
+   kitty, as if you were running with :opt:`allow_remote_control` turned on.
+
+    You can further restrict what is allowed in these windows by using
+    :option:`kitty @ launch --remote-control-password`.
+
+
+Fine grained permissions for remote control
+----------------------------------------------
+
+.. versionadded:: 0.26.0
+
+The :opt:`allow_remote_control` option discussed so far is a blunt
+instrument, granting the ability to any program running on your computer
+or even on remote computers via SSH the ability to use remote control.
+
+You can instead define remote control passwords that can be used to grant
+different levels of control to different places. You can even write your
+own script to decide which remote control requests are allowed. This is
+done using the :opt:`remote_control_password` option in :file:`kitty.conf`.
+Set :opt:`allow_remote_control` to :code:`password` to use this feature.
+Let's see some examples:
+
+.. code-block:: conf
+
+   remote_control_password "control colors" get-colors set-colors
+
+Now, using this password, you can, in scripts run the command::
+
+    kitty @ --password="control colors" set-colors background=red
+
+Any script with access to the password can now change colors in kitty using
+remote control, but only that and nothing else. You can even supply the
+password via the :envvar:`KITTY_RC_PASSWORD` environment variable, or the
+file :file:`~/.config/kitty/rc-password` to avoid having to type it repeatedly.
+See :option:`kitty @ --password-file` and :option:`kitty @ --password-env`.
+
+The :opt:`remote_control_password` can be specified multiple times to create
+different passwords with different capabilities. Run the following to get a
+list of all action names::
+
+    kitty @ --help
+
+You can even use glob patterns to match action names, for example:
+
+.. code-block:: conf
+
+   remote_control_password "control colors" *-colors
+
+If no action names are specified, all actions are allowed.
+
+If ``kitty @`` is run with a password that is not present in
+:file:`kitty.conf`, then kitty will interactively prompt the user to allow or
+disallow the remote control request. The user can choose to allow or disallow
+either just that request or all requests using that password. The user's
+decision is remembered for the duration of that kitty instance.
+
+.. note::
+   For password based authentication to work over SSH, you must pass the
+   :envvar:`KITTY_PUBLIC_KEY` environment variable to the remote host. The
+   :doc:`ssh kitten <kittens/ssh>` does this for you automatically. When
+   using a password, :ref:`rc_crypto` is used to ensure the password
+   is kept secure. This does mean that using password based authentication
+   is slower as the entire command is encrypted before transmission. This
+   can be noticeable when using a command like ``kitty @ set-background-image``
+   which transmits large amounts of image data. Also, the clock on the remote
+   system must match (within a few minutes) the clock on the local system.
+   kitty uses a time based nonce to minimise the potential for replay attacks.
+
+.. _rc_custom_auth:
+
+Customizing authorization with your own program
+____________________________________________________________
+
+If the ability to control access by action names is not fine grained enough,
+you can define your own Python script to examine every remote control command
+and allow/disallow it. To do so create a file in the kitty configuration
+directory, :file:`~/.config/kitty/my_rc_auth.py` and add the following
+to :file:`kitty.conf`:
+
+.. code-block:: conf
+
+    remote_control_password "testing custom auth" my_rc_auth.py
+
+:file:`my_rc_auth.py` should define a :code:`is_cmd_allowed` function
+as shown below:
+
+.. code-block:: py
+
+    def is_cmd_allowed(pcmd, window, from_socket, extra_data):
+        cmd_name = pcmd['cmd']  # the name of the command
+        cmd_payload = pcmd['payload']  # the arguments to the command
+        # examine the cmd_name and cmd_payload and return True to allow
+        # the command or False to disallow it. Return None to have no
+        # effect on the command.
+
+        # The command payload will vary from command to command, see
+        # the rc protocol docs for details. Below is an example of
+        # restricting the launch command to allow only running the
+        # default shell.
+
+        if cmd_name != 'launch':
+            return None
+        if cmd_payload.get('args') or cmd_payload.get('env') or cmd_payload.get('copy_cmdline') or cmd_payload.get('copy_env'):
+            return False
+        # prints in this function go to the parent kitty process STDOUT
+        print('Allowing launch command:', cmd_payload)
+        return True
 
 
 .. _rc_mapping:
@@ -148,15 +270,21 @@ Mapping key presses to remote control commands
 If you wish to trigger a remote control command easily with just a keypress,
 you can map it in :file:`kitty.conf`. For example::
 
-    map F1 remote_control set-spacing margin=30
+    map f1 remote_control set-spacing margin=30
 
-Then pressing the :kbd:`F1` key will set the active window margins to 30.
+Then pressing the :kbd:`F1` key will set the active window margins to
-The syntax for what follows :code:`remote_control` is exactly the same
+:code:`30`. The syntax for what follows :ac:`remote_control` is exactly the same
 as the syntax for what follows :code:`kitty @` above.
 
-.. note:: You do not need ``allow_remote_control`` to use these mappings,
+If you wish to ignore errors from the command, prefix the command with an
-   as they are not actual remote programs, but are simply a way to resuse
+``!``. For example, the following will not return an error when no windows
-   the remote control infrastructure via keybings.
+are matched::
+
+    map f1 remote_control !focus-window --match XXXXXX
+
+.. note:: You do not need :opt:`allow_remote_control` to use these mappings,
+   as they are not actual remote programs, but are simply a way to resuse the
+   remote control infrastructure via keybings.
 
 
 Broadcasting what you type to all kitty windows
@@ -166,17 +294,42 @@ As a simple illustration of the power of remote control, lets
 have what we type sent to all open kitty windows. To do that define the
 following mapping in :file:`kitty.conf`::
 
-    map F1 launch --allow-remote-control kitty +kitten broadcast
+    map f1 launch --allow-remote-control kitty +kitten broadcast
 
-Now press, F1 and start typing, what you type will be sent to all windows,
+Now press :kbd:`F1` and start typing, what you type will be sent to all windows,
 live, as you type it.
 
 
 The remote control protocol
 -----------------------------------------------
 
-If you wish to develop your own client to talk to |kitty|, you
+If you wish to develop your own client to talk to |kitty|, you can use the
-can use the :doc:`protocol specification <rc_protocol>`.
+:doc:`remote control protocol specification <rc_protocol>`. Note that there
+is a statically compiled, standalone executable, ``kitten`` available that
+can be used as a remote control client on any UNIX like computer. This can be
+downloaded and used directly from the `kitty releases
+<https://github.com/kovidgoyal/kitty/releases>`__ page::
+
+    kitten @ --help
+
+
+.. _search_syntax:
+
+Matching windows and tabs
+----------------------------
+
+Many remote control operations operate on windows or tabs. To select these, the
+:code:`--match` option is often used. This allows matching using various
+sophisticated criteria such as title, ids, cmdlines, etc. These criteria are
+expressions of the form :code:`field:query`. Where :italic:`field` is the field
+against which to match and :italic:`query` is the expression to match. They can
+be further combined using Boolean operators, best illustrated with some
+examples::
+
+    title:"My special window" or id:43
+    title:bash and env:USER=kovid
+    not id:1
+    (id:2 or id:3) and title:something
 
 .. toctree::
    :hidden:

docs/shell-integration.rst

@@ -4,8 +4,8 @@ Shell integration
 -------------------
 
 kitty has the ability to integrate closely within common shells, such as `zsh
-<https://www.zsh.org/>`_, `fish <https://fishshell.com>`_ and `bash
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
-<https://www.gnu.org/software/bash/>`_ to enable features such as jumping to
+<https://www.gnu.org/software/bash/>`__ to enable features such as jumping to
 previous prompts in the scrollback, viewing the output of the last command in
 :program:`less`, using the mouse to move the cursor while editing prompts, etc.
 
@@ -22,7 +22,7 @@ Features
 
 * Click with the mouse anywhere in the current command to move the cursor there
 
-* Hold :kbd:`ctrl+shift` and right-click on any command output in the scrollback
+* Hold :kbd:`Ctrl+Shift` and right-click on any command output in the scrollback
   to view it in a pager
 
 * The current working directory or the command being executed are automatically
@@ -30,37 +30,57 @@ Features
 
 * The text cursor is changed to a bar when editing commands at the shell prompt
 
+* :ref:`clone_shell` with all environment variables and the working directory
+  copied
+
+* :ref:`Edit files in new kitty windows <edit_file>` even over SSH
+
 * Glitch free window resizing even with complex prompts. Achieved by erasing
   the prompt on resize and allowing the shell to redraw it cleanly.
 
 * Sophisticated completion for the :program:`kitty` command in the shell.
 
 * When confirming a quit command if a window is sitting at a shell prompt,
-  it is optionally, not counted (see :opt:`confirm_os_window_close`)
+  it is not counted (for details, see :opt:`confirm_os_window_close`)
 
 
 Configuration
 ---------------
 
 Shell integration is controlled by the :opt:`shell_integration` option. By
-default, all shell integration is enabled. Individual features can be turned
+default, all integration features are enabled. Individual features can be turned
 off or it can be disabled entirely as well. The :opt:`shell_integration` option
 takes a space separated list of keywords:
 
 disabled
-    Turn off all shell integration
+    Turn off all shell integration. The shell's launch environment is not
+    modified and :envvar:`KITTY_SHELL_INTEGRATION` is not set. Useful for
+    :ref:`manual integration <manual_shell_integration>`.
 
 no-rc
-    Do not modify the shell's launch environment to enable integration. Useful if you prefer
+    Do not modify the shell's launch environment to enable integration. Useful
-    to :ref:`manually enable integration <manual_shell_integration>`.
+    if you prefer to load the kitty shell integration code yourself, either as
+    part of :ref:`manually integration <manual_shell_integration>` or because
+    you have some other software that sets up shell integration.
+    This will still set the :envvar:`KITTY_SHELL_INTEGRATION` environment
+    variable when kitty runs the shell.
 
 no-cursor
-    Turn off changing of the text cursor to a bar when editing text
+    Turn off changing of the text cursor to a bar when editing shell command
+    line.
 
 no-title
     Turn off setting the kitty window/tab title based on shell state.
-    Note that for the ``fish`` shell kitty relies on fish's native title
+    Note that for the fish shell kitty relies on fish's native title setting
-    setting functionality instead.
+    functionality instead.
+
+no-cwd
+    Turn off reporting the current working directory. This is used to allow
+    :ac:`new_window_with_cwd` and similar to open windows logged into remote
+    machines using the :doc:`ssh kitten <kittens/ssh>` automatically with the
+    same working directory as the current window.
+    Note that for the fish shell this will not disable its built-in current
+    working directory reporting.
 
 no-prompt-mark
     Turn off marking of prompts. This disables jumping to prompt, browsing
@@ -68,16 +88,16 @@ no-prompt-mark
 
 no-complete
     Turn off completion for the kitty command.
-    Note that for the ``fish`` shell this does not take effect, since fish
+    Note that for the fish shell this does not take effect, since fish already
-    already comes with a kitty completion script.
+    comes with a kitty completion script.
 
 
 More ways to browse command output
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can add further key and mouse bindings to browse the output of commands
-easily. For example to select the output of a command by right clicking the mouse
+easily. For example to select the output of a command by right clicking the
-on the output, define the following in :file:`kitty.conf`:
+mouse on the output, define the following in :file:`kitty.conf`:
 
 .. code:: conf
 
@@ -88,8 +108,8 @@ to be copied.
 
 The feature to jump to previous prompts (
 :sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse
-actions (:ref:`action-mouse_select_command_output` and :ref:`action-mouse_show_command_output`) can
+actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`)
-be integrated with browsing command output as well. For example, define the
+can be integrated with browsing command output as well. For example, define the
 following mapping in :file:`kitty.conf`:
 
 .. code:: conf
@@ -121,38 +141,41 @@ How it works
 -----------------
 
 At startup, kitty detects if the shell you have configured (either system wide
-or in kitty.conf) is a supported shell. If so, kitty injects some shell specific
+or the :opt:`shell` option in :file:`kitty.conf`) is a supported shell. If so,
-code into the shell, to enable shell integration. How it does so varies for
+kitty injects some shell specific code into the shell, to enable shell
-different shells.
+integration. How it does so varies for different shells.
 
 
 .. tab:: zsh
 
-   For zsh, kitty sets the ``ZDOTDIR`` environment variable to make zsh load
+   For zsh, kitty sets the :envvar:`ZDOTDIR` environment variable to make zsh
-   kitty's :file:`.zshenv` which restores the original value of ``ZDOTDIR``
+   load kitty's :file:`.zshenv` which restores the original value of
-   and sources the original :file:`.zshenv`. It then loads the shell integration code.
+   :envvar:`ZDOTDIR` and sources the original :file:`.zshenv`. It then loads
-   The remainder of zsh's startup process proceeds as normal.
+   the shell integration code. The remainder of zsh's startup process proceeds
+   as normal.
 
 .. tab:: fish
 
     For fish, to make it automatically load the integration code provided by
     kitty, the integration script directory path is prepended to the
-    :code:`XDG_DATA_DIRS` environment variable. This is only applied to the fish
+    :envvar:`XDG_DATA_DIRS` environment variable. This is only applied to the
-    process and will be cleaned up by the integration script after startup. No files
+    fish process and will be cleaned up by the integration script after startup.
-    are added or modified.
+    No files are added or modified.
 
 .. tab:: bash
 
-    For bash, kitty adds a couple of lines to the bottom of :file:`~/.bashrc`
+    For bash, kitty starts bash in POSIX mode, using the environment variable
-    (in an atomic manner) to load the shell integration code.
+    :envvar:`ENV` to load the shell integration script. This prevents bash from
+    loading any startup files itself. The loading of the startup files is done
+    by the integration script, after disabling POSIX mode. From the perspective
+    of those scripts there should be no difference to running vanilla bash.
 
 
 Then, when launching the shell, kitty sets the environment variable
 :envvar:`KITTY_SHELL_INTEGRATION` to the value of the :opt:`shell_integration`
 option. The shell integration code reads the environment variable, turns on the
 specified integration functionality and then unsets the variable so as to not
-pollute the system. This has the nice effect that the changes to the shell's rc
+pollute the system.
-files become no-ops when running the shell in anything other than kitty itself.
 
 The actual shell integration code uses hooks provided by each shell to send
 special escape codes to kitty, to perform the various tasks. You can see the
@@ -185,13 +208,97 @@ code used for each shell below:
    </details>
 
 
+Shell integration over SSH
+----------------------------
+
+The easiest way to have shell integration work when SSHing into remote systems
+is to use the :doc:`ssh kitten <kittens/ssh>`. Simply run::
+
+    kitty +kitten ssh hostname
+
+And, by magic, you will be logged into the remote system with fully functional
+shell integration. Alternately, you can :ref:`setup shell integration manually
+<manual_shell_integration>`, by copying the kitty shell integration scripts to
+the remote server and editing the shell rc files there, as described below.
+
+
+.. _clone_shell:
+
+Clone the current shell into a new window
+-----------------------------------------------
+
+You can clone the current shell into a new kitty window by simply running the
+:command:`clone-in-kitty` command, for example:
+
+.. code-block:: sh
+
+    clone-in-kitty
+    clone-in-kitty --type=tab
+    clone-in-kitty --title "I am a clone"
+
+This will open a new window running a new shell instance but with all
+environment variables and the current working directory copied. This even works
+over SSH when using :doc:`kittens/ssh`.
+
+The :command:`clone-in-kitty` command takes almost all the same arguments as the
+:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
+window, etc. Arguments of launch that can cause code execution or that don't
+make sense when cloning are ignored. Most prominently, the following options are
+ignored: :option:`--allow-remote-control <launch --allow-remote-control>`,
+:option:`--copy-cmdline <launch --copy-cmdline>`, :option:`--copy-env <launch
+--copy-env>`, :option:`--stdin-source <launch --stdin-source>`,
+:option:`--marker <launch --marker>` and :option:`--watcher <launch --watcher>`.
+
+:command:`clone-in-kitty` can be configured to source arbitrary code in the
+cloned window using environment variables. It will automatically clone virtual
+environments created by the :link:`Python venv module
+<https://docs.python.org/3/library/venv.html>` or :link:`Conda
+<https://conda.io/>`. In addition, setting the
+env var :envvar:`KITTY_CLONE_SOURCE_CODE` to some shell code will cause that
+code to be run in the cloned window with :code:`eval`. Similarly, setting
+:envvar:`KITTY_CLONE_SOURCE_PATH` to the path of a file will cause that file to
+be sourced in the cloned window. This can be controlled by
+:opt:`clone_source_strategies`.
+
+:command:`clone-in-kitty` works by asking the shell to serialize its internal
+state (mainly CWD and env vars) and this state is transmitted to kitty and
+restored by the shell integration scripts in the cloned window.
+
+
+.. _edit_file:
+
+Edit files in new kitty windows even over SSH
+------------------------------------------------
+
+.. code-block:: sh
+
+   edit-in-kitty myfile.txt
+   edit-in-kitty --type tab --title "Editing My File" myfile.txt
+   # open myfile.txt at line 75 (works with vim, neovim, emacs, nano, micro)
+   edit-in-kitty +75 myfile.txt
+
+The :command:`edit-in-kitty` command allows you to seamlessly edit files
+in your default :opt:`editor` in new kitty windows. This works even over
+SSH (if you use the :doc:`ssh kitten <kittens/ssh>`), allowing you
+to easily edit remote files in your local editor with all its bells and
+whistles.
+
+The :command:`edit-in-kitty` command takes almost all the same arguments as the
+:doc:`launch <launch>` command, so you can open a new tab instead or a new OS
+window, etc. Not all arguments are supported, see the discussion in the
+:ref:`clone_shell` section above.
+
+In order to avoid remote code execution, kitty will only execute the configured
+editor and pass the file path to edit to it.
+
+
 .. _manual_shell_integration:
 
 Manual shell integration
 ----------------------------
 
 The automatic shell integration is designed to be minimally intrusive, as such
-it wont work for sub-shells, terminal multiplexers, containers, remote systems, etc.
+it wont work for sub-shells, terminal multiplexers, containers, etc.
 For such systems, you should setup manual shell integration by adding some code
 to your shells startup files to load the shell integration script.
 
@@ -239,18 +346,17 @@ The value of :envvar:`KITTY_SHELL_INTEGRATION` is the same as that for
 completely, in which case simply do not set the
 :envvar:`KITTY_SHELL_INTEGRATION` variable at all.
 
-If you want this to work while SSHing into a remote system, then you will
+In a container, you will need to install the kitty shell integration scripts
-need to add some code to the snippets above to check if :envvar:`KITTY_INSTALLATION_DIR`
+and make sure the :envvar:`KITTY_INSTALLATION_DIR` environment variable is set
-is empty and if so to set it to some hard coded location with the shell
+to point to the location of the scripts.
-integration scripts that need to be copied onto the remote system.
-
 
 Integration with other shells
 -------------------------------
 
-There exist third-party integrations to use these features for various other shells:
+There exist third-party integrations to use these features for various other
+shells:
 
-* Jupyter console via a patch (:iss:`4475`)
+* Jupyter console and IPython via a patch (:iss:`4475`)
 * `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__
 
 

docs/underlines.rst

@@ -1,24 +1,25 @@
 Colored and styled underlines
 ================================
 
-|kitty| supports colored and styled (wavy) underlines. This is of particular
+|kitty| supports colored and styled (wavy) underlines. This is of particular use
-use in terminal editors such as vim and emacs to display red, wavy underlines
+in terminal based text editors such as :program:`vim` and :program:`emacs` to
-under mis-spelled words and/or syntax errors. This is done by re-purposing some
+display red, wavy underlines under mis-spelled words and/or syntax errors. This
-SGR escape codes that are not used in modern terminals (`CSI codes
+is done by re-purposing some SGR escape codes that are not used in modern
-<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`_)
+terminals (`CSI codes <https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`__)
 
 To set the underline style::
 
-    <ESC>[4:0m  # this is no underline
+    <ESC>[4:0m  # no underline
-    <ESC>[4:1m  # this is a straight underline
+    <ESC>[4:1m  # straight underline
-    <ESC>[4:2m  # this is a double underline
+    <ESC>[4:2m  # double underline
-    <ESC>[4:3m  # this is a curly underline
+    <ESC>[4:3m  # curly underline
-    <ESC>[4:4m  # this is a dotted underline
+    <ESC>[4:4m  # dotted underline
-    <ESC>[4:5m  # this is a dashed underline
+    <ESC>[4:5m  # dashed underline
-    <ESC>[4m    # this is a straight underline (for backwards compat)
+    <ESC>[4m    # straight underline (for backwards compat)
-    <ESC>[24m   # this is no underline (for backwards compat)
+    <ESC>[24m   # no underline (for backwards compat)
 
-To set the underline color (this is reserved and as far as I can tell not actually used for anything)::
+To set the underline color (this is reserved and as far as I can tell not
+actually used for anything)::
 
     <ESC>[58...m
 
@@ -29,8 +30,8 @@ To reset the underline color (also previously reserved and unused)::
 
     <ESC>[59m
 
-The underline color must remain the same under reverse video, if it has a
+The underline color must remain the same under reverse video, if it has a color,
-color, if not, it should follow the foreground color.
+if not, it should follow the foreground color.
 
-To detect support for this feature in a terminal emulator, query the terminfo database
+To detect support for this feature in a terminal emulator, query the terminfo
-for the ``Su`` boolean capability.
+database for the ``Su`` boolean capability.

docs/unscroll.rst

@@ -4,10 +4,10 @@ Unscrolling the screen
 ========================
 
 This is a small extension to the `SD (Pan up) escape code
-<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The
+<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The ``SD``
-``SD`` escape code normally causes the text on screen to scroll down by the
+escape code normally causes the text on screen to scroll down by the specified
-specified number of lines, with empty lines appearing at the top of the screen.
+number of lines, with empty lines appearing at the top of the screen. This
-This extension allows the new lines to be filled in from the scrollback buffer
+extension allows the new lines to be filled in from the scrollback buffer
 instead of being blank.
 
 The motivation for this is that many modern shells will show completions in a
@@ -22,17 +22,17 @@ scrolled down is implementation defined, but must be at least one screen worth.
 
 The syntax of the escape code is identical to that of ``SD`` except that it has
 a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
-<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`_
+<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`__
 and unused for any other purpose as far as I can tell. So for example, to
 unscroll three lines, the escape code would be::
 
     CSI 3 + T
 
 See `discussion here
-<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`_.
+<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`__.
 
 .. versionadded:: 0.20.2
 
 Also supported by the terminals:
 
-    * `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`_
+* `mintty <https://github.com/mintty/mintty/releases/tag/3.5.2>`__

gen-apc-parsers.py

@@ -274,6 +274,7 @@ def graphics_parser() -> None:
         'Y': ('cell_y_offset', 'uint'),
         'z': ('z_index', 'int'),
         'C': ('cursor_movement', 'uint'),
+        'U': ('unicode_placement', 'uint'),
     }
     text = generate('parse_graphics_code', 'screen_handle_graphics_command', 'graphics_command', keymap, 'GraphicsCommand')
     write_header(text, 'kitty/parse-graphics-command.h')

gen-config.py

@@ -1,8 +1,9 @@
-#!/usr/bin/env python
+#!./kitty/launcher/kitty +launch
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 
 import re
+import subprocess
 from typing import List
 
 from kitty.conf.generate import write_output
@@ -11,14 +12,25 @@ from kitty.conf.generate import write_output
 def patch_color_list(path: str, colors: List[str], name: str, spc: str = '    ') -> None:
     with open(path, 'r+') as f:
         raw = f.read()
-        nraw = re.sub(
+        colors = sorted(colors)
-            fr'(# {name}_COLORS_START).+?(\s+# {name}_COLORS_END)',
+        if path.endswith('.go'):
-            r'\1' + f'\n{spc}' + f'\n{spc}'.join(map(lambda x: f'{x!r},', sorted(colors))) + r'\2',
+            spc = '\t'
-            raw, flags=re.DOTALL | re.MULTILINE)
+            nraw = re.sub(
+                fr'(// {name}_COLORS_START).+?(\s+// {name}_COLORS_END)',
+                r'\1' + f'\n{spc}' + f'\n{spc}'.join(map(lambda x: f'"{x}":true,', colors)) + r'\2',
+                raw, flags=re.DOTALL | re.MULTILINE)
+        else:
+            nraw = re.sub(
+                fr'(# {name}_COLORS_START).+?(\s+# {name}_COLORS_END)',
+                r'\1' + f'\n{spc}' + f'\n{spc}'.join(map(lambda x: f'{x!r},', colors)) + r'\2',
+                raw, flags=re.DOTALL | re.MULTILINE)
         if nraw != raw:
             f.seek(0)
             f.truncate()
             f.write(nraw)
+            f.flush()
+            if path.endswith('.go'):
+                subprocess.check_call(['gofmt', '-w', path])
 
 
 def main() -> None:
@@ -34,10 +46,8 @@ def main() -> None:
             elif opt.parser_func.__name__ in ('to_color', 'titlebar_color', 'macos_titlebar_color'):
                 all_colors.append(opt.name)
     patch_color_list('kitty/rc/set_colors.py', nullable_colors, 'NULLABLE')
-    patch_color_list('kittens/themes/collection.py', all_colors, 'ALL', ' ' * 8)
+    patch_color_list('tools/cmd/at/set_colors.go', nullable_colors, 'NULLABLE')
-
+    patch_color_list('tools/themes/collection.go', all_colors, 'ALL')
-    from kittens.diff.options.definition import definition as kd
-    write_output('kittens.diff', kd)
 
 
 if __name__ == '__main__':

gen-go-code.py

@@ -0,0 +1,767 @@
+#!./kitty/launcher/kitty +launch
+# License: GPLv3 Copyright: 2022, Kovid Goyal <kovid at kovidgoyal.net>
+
+import bz2
+import io
+import json
+import os
+import re
+import struct
+import subprocess
+import sys
+import tarfile
+from contextlib import contextmanager, suppress
+from functools import lru_cache
+from itertools import chain
+from typing import (
+    Any,
+    BinaryIO,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    Sequence,
+    Set,
+    TextIO,
+    Tuple,
+    Union,
+)
+
+import kitty.constants as kc
+from kittens.tui.operations import Mode
+from kittens.tui.spinners import spinners
+from kitty.cli import (
+    CompletionSpec,
+    GoOption,
+    go_options_for_seq,
+    parse_option_spec,
+    serialize_as_go_string,
+)
+from kitty.conf.generate import gen_go_code
+from kitty.conf.types import Definition
+from kitty.guess_mime_type import known_extensions, text_mimes
+from kitty.key_encoding import config_mod_map
+from kitty.key_names import character_key_name_aliases, functional_key_name_aliases
+from kitty.options.types import Options
+from kitty.rc.base import RemoteCommand, all_command_names, command_for_name
+from kitty.remote_control import global_options_spec
+from kitty.rgb import color_names
+
+changed: List[str] = []
+
+
+def newer(dest: str, *sources: str) -> bool:
+    try:
+        dtime = os.path.getmtime(dest)
+    except OSError:
+        return True
+    for s in chain(sources, (__file__,)):
+        with suppress(FileNotFoundError):
+            if os.path.getmtime(s) >= dtime:
+                return True
+    return False
+
+
+
+# Utils {{{
+
+def serialize_go_dict(x: Union[Dict[str, int], Dict[int, str], Dict[int, int], Dict[str, str]]) -> str:
+    ans = []
+
+    def s(x: Union[int, str]) -> str:
+        if isinstance(x, int):
+            return str(x)
+        return f'"{serialize_as_go_string(x)}"'
+
+    for k, v in x.items():
+        ans.append(f'{s(k)}: {s(v)}')
+    return '{' + ', '.join(ans) + '}'
+
+
+def replace(template: str, **kw: str) -> str:
+    for k, v in kw.items():
+        template = template.replace(k, v)
+    return template
+# }}}
+
+
+# Completions {{{
+
+@lru_cache
+def kitten_cli_docs(kitten: str) -> Any:
+    from kittens.runner import get_kitten_cli_docs
+    return get_kitten_cli_docs(kitten)
+
+
+@lru_cache
+def go_options_for_kitten(kitten: str) -> Tuple[Sequence[GoOption], Optional[CompletionSpec]]:
+    kcd = kitten_cli_docs(kitten)
+    if kcd:
+        ospec = kcd['options']
+        return (tuple(go_options_for_seq(parse_option_spec(ospec())[0])), kcd.get('args_completion'))
+    return (), None
+
+
+def generate_kittens_completion() -> None:
+    from kittens.runner import all_kitten_names, get_kitten_wrapper_of
+    for kitten in sorted(all_kitten_names()):
+        kn = 'kitten_' + kitten
+        print(f'{kn} := plus_kitten.AddSubCommand(&cli.Command{{Name:"{kitten}", Group: "Kittens"}})')
+        wof = get_kitten_wrapper_of(kitten)
+        if wof:
+            print(f'{kn}.ArgCompleter = cli.CompletionForWrapper("{serialize_as_go_string(wof)}")')
+            print(f'{kn}.OnlyArgsAllowed = true')
+            continue
+        gopts, ac = go_options_for_kitten(kitten)
+        if gopts or ac:
+            for opt in gopts:
+                print(opt.as_option(kn))
+            if ac is not None:
+                print(''.join(ac.as_go_code(kn + '.ArgCompleter', ' = ')))
+        else:
+            print(f'{kn}.HelpText = ""')
+
+
+@lru_cache
+def clone_safe_launch_opts() -> Sequence[GoOption]:
+    from kitty.launch import clone_safe_opts, options_spec
+    ans = []
+    allowed = clone_safe_opts()
+    for o in go_options_for_seq(parse_option_spec(options_spec())[0]):
+        if o.obj_dict['name'] in allowed:
+            ans.append(o)
+    return tuple(ans)
+
+
+def completion_for_launch_wrappers(*names: str) -> None:
+    for o in clone_safe_launch_opts():
+        for name in names:
+            print(o.as_option(name))
+
+
+def generate_completions_for_kitty() -> None:
+    from kitty.config import option_names_for_completion
+    print('package completion\n')
+    print('import "kitty/tools/cli"')
+    print('import "kitty/tools/cmd/tool"')
+    print('import "kitty/tools/cmd/at"')
+    conf_names = ', '.join((f'"{serialize_as_go_string(x)}"' for x in option_names_for_completion()))
+    print('var kitty_option_names_for_completion = []string{' + conf_names + '}')
+
+    print('func kitty(root *cli.Command) {')
+
+    # The kitty exe
+    print('k := root.AddSubCommand(&cli.Command{'
+          'Name:"kitty", SubCommandIsOptional: true, ArgCompleter: cli.CompleteExecutableFirstArg, SubCommandMustBeFirst: true })')
+    print('kt := root.AddSubCommand(&cli.Command{Name:"kitten", SubCommandMustBeFirst: true })')
+    print('tool.KittyToolEntryPoints(kt)')
+    for opt in go_options_for_seq(parse_option_spec()[0]):
+        print(opt.as_option('k'))
+
+    # kitty +
+    print('plus := k.AddSubCommand(&cli.Command{Name:"+", Group:"Entry points", ShortDescription: "Various special purpose tools and kittens"})')
+
+    # kitty +launch
+    print('plus_launch := plus.AddSubCommand(&cli.Command{'
+          'Name:"launch", Group:"Entry points", ShortDescription: "Launch Python scripts", ArgCompleter: complete_plus_launch})')
+    print('k.AddClone("", plus_launch).Name = "+launch"')
+
+    # kitty +list-fonts
+    print('plus_list_fonts := plus.AddSubCommand(&cli.Command{'
+          'Name:"list-fonts", Group:"Entry points", ShortDescription: "List all available monospaced fonts"})')
+    print('k.AddClone("", plus_list_fonts).Name = "+list-fonts"')
+
+    # kitty +runpy
+    print('plus_runpy := plus.AddSubCommand(&cli.Command{'
+          'Name: "runpy", Group:"Entry points", ArgCompleter: complete_plus_runpy, ShortDescription: "Run Python code"})')
+    print('k.AddClone("", plus_runpy).Name = "+runpy"')
+
+    # kitty +open
+    print('plus_open := plus.AddSubCommand(&cli.Command{'
+          'Name:"open", Group:"Entry points", ArgCompleter: complete_plus_open, ShortDescription: "Open files and URLs"})')
+    print('for _, og := range k.OptionGroups { plus_open.OptionGroups = append(plus_open.OptionGroups, og.Clone(plus_open)) }')
+    print('k.AddClone("", plus_open).Name = "+open"')
+
+    # kitty +kitten
+    print('plus_kitten := plus.AddSubCommand(&cli.Command{Name:"kitten", Group:"Kittens", SubCommandMustBeFirst: true})')
+    generate_kittens_completion()
+    print('k.AddClone("", plus_kitten).Name = "+kitten"')
+
+    # @
+    print('at.EntryPoint(k)')
+
+    # clone-in-kitty, edit-in-kitty
+    print('cik := root.AddSubCommand(&cli.Command{Name:"clone-in-kitty"})')
+    completion_for_launch_wrappers('cik')
+
+    print('}')
+    print('func init() {')
+    print('cli.RegisterExeForCompletion(kitty)')
+    print('}')
+# }}}
+
+
+# rc command wrappers {{{
+json_field_types: Dict[str, str] = {
+    'bool': 'bool', 'str': 'escaped_string', 'list.str': '[]escaped_string', 'dict.str': 'map[escaped_string]escaped_string', 'float': 'float64', 'int': 'int',
+    'scroll_amount': 'any', 'spacing': 'any', 'colors': 'any',
+}
+
+
+def go_field_type(json_field_type: str) -> str:
+    q = json_field_types.get(json_field_type)
+    if q:
+        return q
+    if json_field_type.startswith('choices.'):
+        return 'string'
+    if '.' in json_field_type:
+        p, r = json_field_type.split('.', 1)
+        p = {'list': '[]', 'dict': 'map[string]'}[p]
+        return p + go_field_type(r)
+    raise TypeError(f'Unknown JSON field type: {json_field_type}')
+
+
+class JSONField:
+
+    def __init__(self, line: str) -> None:
+        field_def = line.split(':', 1)[0]
+        self.required = False
+        self.field, self.field_type = field_def.split('/', 1)
+        if self.field.endswith('+'):
+            self.required = True
+            self.field = self.field[:-1]
+        self.struct_field_name = self.field[0].upper() + self.field[1:]
+
+    def go_declaration(self) -> str:
+        return self.struct_field_name + ' ' + go_field_type(self.field_type) + f'`json:"{self.field},omitempty"`'
+
+
+def go_code_for_remote_command(name: str, cmd: RemoteCommand, template: str) -> str:
+    template = '\n' + template[len('//go:build exclude'):]
+    NO_RESPONSE_BASE = 'false'
+    af: List[str] = []
+    a = af.append
+    af.extend(cmd.args.as_go_completion_code('ans'))
+    od: List[str] = []
+    option_map: Dict[str, GoOption] = {}
+    for o in rc_command_options(name):
+        option_map[o.go_var_name] = o
+        a(o.as_option('ans'))
+        if o.go_var_name in ('NoResponse', 'ResponseTimeout'):
+            continue
+        od.append(o.struct_declaration())
+    jd: List[str] = []
+    json_fields = []
+    field_types: Dict[str, str] = {}
+    for line in cmd.protocol_spec.splitlines():
+        line = line.strip()
+        if ':' not in line:
+            continue
+        f = JSONField(line)
+        json_fields.append(f)
+        field_types[f.field] = f.field_type
+        jd.append(f.go_declaration())
+    jc: List[str] = []
+    handled_fields: Set[str] = set()
+    jc.extend(cmd.args.as_go_code(name, field_types, handled_fields))
+
+    unhandled = {}
+    used_options = set()
+    for field in json_fields:
+        oq = (cmd.field_to_option_map or {}).get(field.field, field.field)
+        oq = ''.join(x.capitalize() for x in oq.split('_'))
+        if oq in option_map:
+            o = option_map[oq]
+            used_options.add(oq)
+            if field.field_type == 'str':
+                jc.append(f'payload.{field.struct_field_name} = escaped_string(options_{name}.{o.go_var_name})')
+            elif field.field_type == 'list.str':
+                jc.append(f'payload.{field.struct_field_name} = escape_list_of_strings(options_{name}.{o.go_var_name})')
+            elif field.field_type == 'dict.str':
+                jc.append(f'payload.{field.struct_field_name} = escape_dict_of_strings(options_{name}.{o.go_var_name})')
+            else:
+                jc.append(f'payload.{field.struct_field_name} = options_{name}.{o.go_var_name}')
+        elif field.field in handled_fields:
+            pass
+        else:
+            unhandled[field.field] = field
+    for x in tuple(unhandled):
+        if x == 'match_window' and 'Match' in option_map and 'Match' not in used_options:
+            used_options.add('Match')
+            o = option_map['Match']
+            field = unhandled[x]
+            if field.field_type == 'str':
+                jc.append(f'payload.{field.struct_field_name} = escaped_string(options_{name}.{o.go_var_name})')
+            else:
+                jc.append(f'payload.{field.struct_field_name} = options_{name}.{o.go_var_name}')
+            del unhandled[x]
+    if unhandled:
+        raise SystemExit(f'Cant map fields: {", ".join(unhandled)} for cmd: {name}')
+    if name != 'send_text':
+        unused_options = set(option_map) - used_options - {'NoResponse', 'ResponseTimeout'}
+        if unused_options:
+            raise SystemExit(f'Unused options: {", ".join(unused_options)} for command: {name}')
+
+    argspec = cmd.args.spec
+    if argspec:
+        argspec = ' ' + argspec
+    ans = replace(
+        template,
+        CMD_NAME=name, __FILE__=__file__, CLI_NAME=name.replace('_', '-'),
+        SHORT_DESC=serialize_as_go_string(cmd.short_desc),
+        LONG_DESC=serialize_as_go_string(cmd.desc.strip()),
+        IS_ASYNC='true' if cmd.is_asynchronous else 'false',
+        NO_RESPONSE_BASE=NO_RESPONSE_BASE, ADD_FLAGS_CODE='\n'.join(af),
+        WAIT_TIMEOUT=str(cmd.response_timeout),
+        OPTIONS_DECLARATION_CODE='\n'.join(od),
+        JSON_DECLARATION_CODE='\n'.join(jd),
+        JSON_INIT_CODE='\n'.join(jc), ARGSPEC=argspec,
+        STRING_RESPONSE_IS_ERROR='true' if cmd.string_return_is_error else 'false',
+        STREAM_WANTED='true' if cmd.reads_streaming_data else 'false',
+    )
+    return ans
+# }}}
+
+
+# kittens {{{
+
+@lru_cache
+def wrapped_kittens() -> Sequence[str]:
+    with open('shell-integration/ssh/kitty') as f:
+        for line in f:
+            if line.startswith('    wrapped_kittens="'):
+                val = line.strip().partition('"')[2][:-1]
+                return tuple(sorted(filter(None, val.split())))
+    raise Exception('Failed to read wrapped kittens from kitty wrapper script')
+
+
+def generate_conf_parser(kitten: str, defn: Definition) -> None:
+    with replace_if_needed(f'kittens/{kitten}/conf_generated.go'):
+        print(f'package {kitten}')
+        print(gen_go_code(defn))
+
+
+def generate_extra_cli_parser(name: str, spec: str) -> None:
+    print('import "kitty/tools/cli"')
+    go_opts = tuple(go_options_for_seq(parse_option_spec(spec)[0]))
+    print(f'type {name}_options struct ''{')
+    for opt in go_opts:
+        print(opt.struct_declaration())
+    print('}')
+    print(f'func parse_{name}_args(args []string) (*{name}_options, []string, error) ''{')
+    print(f'root := cli.Command{{Name: `{name}` }}')
+    for opt in go_opts:
+        print(opt.as_option('root'))
+    print('cmd, err := root.ParseArgs(args)')
+    print('if err != nil { return nil, nil, err }')
+    print(f'var opts {name}_options')
+    print('err = cmd.GetOptionValues(&opts)')
+    print('if err != nil { return nil, nil, err }')
+    print('return &opts, cmd.Args, nil')
+    print('}')
+
+
+def kitten_clis() -> None:
+    from kittens.runner import get_kitten_conf_docs, get_kitten_extra_cli_parsers
+    for kitten in wrapped_kittens():
+        defn = get_kitten_conf_docs(kitten)
+        if defn is not None:
+            generate_conf_parser(kitten, defn)
+        ecp = get_kitten_extra_cli_parsers(kitten)
+        if ecp:
+            for name, spec in ecp.items():
+                with replace_if_needed(f'kittens/{kitten}/{name}_cli_generated.go'):
+                    print(f'package {kitten}')
+                    generate_extra_cli_parser(name, spec)
+
+        with replace_if_needed(f'kittens/{kitten}/cli_generated.go'):
+            od = []
+            kcd = kitten_cli_docs(kitten)
+            has_underscore = '_' in kitten
+            print(f'package {kitten}')
+            print('import "kitty/tools/cli"')
+            print('func create_cmd(root *cli.Command, run_func func(*cli.Command, *Options, []string)(int, error)) {')
+            print('ans := root.AddSubCommand(&cli.Command{')
+            print(f'Name: "{kitten}",')
+            if kcd:
+                print(f'ShortDescription: "{serialize_as_go_string(kcd["short_desc"])}",')
+                if kcd['usage']:
+                    print(f'Usage: "[options] {serialize_as_go_string(kcd["usage"])}",')
+                print(f'HelpText: "{serialize_as_go_string(kcd["help_text"])}",')
+            print('Run: func(cmd *cli.Command, args []string) (int, error) {')
+            print('opts := Options{}')
+            print('err := cmd.GetOptionValues(&opts)')
+            print('if err != nil { return 1, err }')
+            print('return run_func(cmd, &opts, args)},')
+            if has_underscore:
+                print('Hidden: true,')
+            print('})')
+            gopts, ac = go_options_for_kitten(kitten)
+            for opt in gopts:
+                print(opt.as_option('ans'))
+                od.append(opt.struct_declaration())
+            if ac is not None:
+                print(''.join(ac.as_go_code('ans.ArgCompleter', ' = ')))
+            if has_underscore:
+                print("clone := root.AddClone(ans.Group, ans)")
+                print('clone.Hidden = false')
+                print(f'clone.Name = "{serialize_as_go_string(kitten.replace("_", "-"))}"')
+            if not kcd:
+                print('specialize_command(ans)')
+            print('}')
+            print('type Options struct {')
+            print('\n'.join(od))
+            print('}')
+
+# }}}
+
+
+# Constants {{{
+
+def generate_spinners() -> str:
+    ans = ['package tui', 'import "time"', 'func NewSpinner(name string) *Spinner {', 'var ans *Spinner', 'switch name {']
+    a = ans.append
+    for name, spinner in spinners.items():
+        a(f'case "{serialize_as_go_string(name)}":')
+        a('ans = &Spinner{')
+        a(f'Name: "{serialize_as_go_string(name)}",')
+        a(f'interval: {spinner["interval"]},')
+        frames = ', '.join(f'"{serialize_as_go_string(x)}"' for x in spinner['frames'])
+        a(f'frames: []string{{{frames}}},')
+        a('}')
+    a('}')
+    a('if ans != nil {')
+    a('ans.interval *= time.Millisecond')
+    a('ans.current_frame = -1')
+    a('ans.last_change_at = time.Now().Add(-ans.interval)')
+    a('}')
+    a('return ans}')
+    return '\n'.join(ans)
+
+
+def generate_color_names() -> str:
+    selfg = "" if Options.selection_foreground is None else Options.selection_foreground.as_sharp
+    selbg = "" if Options.selection_background is None else Options.selection_background.as_sharp
+    cursor = "" if Options.cursor is None else Options.cursor.as_sharp
+    return 'package style\n\nvar ColorNames = map[string]RGBA{' + '\n'.join(
+        f'\t"{name}": RGBA{{ Red:{val.red}, Green:{val.green}, Blue:{val.blue} }},'
+        for name, val in color_names.items()
+    ) + '\n}' + '\n\nvar ColorTable = [256]uint32{' + ', '.join(
+        f'{x}' for x in Options.color_table) + '}\n' + f'''
+var DefaultColors = struct {{
+Foreground, Background, Cursor, SelectionFg, SelectionBg string
+}}{{
+Foreground: "{Options.foreground.as_sharp}",
+Background: "{Options.background.as_sharp}",
+Cursor: "{cursor}",
+SelectionFg: "{selfg}",
+SelectionBg: "{selbg}",
+}}
+'''
+
+
+def load_ref_map() -> Dict[str, Dict[str, str]]:
+    with open('kitty/docs_ref_map_generated.h') as f:
+        raw = f.read()
+    raw = raw.split('{', 1)[1].split('}', 1)[0]
+    data = json.loads(bytes(bytearray(json.loads(f'[{raw}]'))))
+    return data  # type: ignore
+
+
+def generate_constants() -> str:
+    from kittens.hints.main import DEFAULT_REGEX
+    from kitty.options.types import Options
+    from kitty.options.utils import allowed_shell_integration_values
+    del sys.modules['kittens.hints.main']
+    ref_map = load_ref_map()
+    with open('kitty/data-types.h') as dt:
+        m = re.search(r'^#define IMAGE_PLACEHOLDER_CHAR (\S+)', dt.read(), flags=re.M)
+        assert m is not None
+        placeholder_char = int(m.group(1), 16)
+    dp = ", ".join(map(lambda x: f'"{serialize_as_go_string(x)}"', kc.default_pager_for_help))
+    url_prefixes = ','.join(f'"{x}"' for x in Options.url_prefixes)
+    return f'''\
+package kitty
+
+type VersionType struct {{
+    Major, Minor, Patch int
+}}
+const VersionString string = "{kc.str_version}"
+const WebsiteBaseURL string = "{kc.website_base_url}"
+const ImagePlaceholderChar rune = {placeholder_char}
+const VCSRevision string = ""
+const SSHControlMasterTemplate = "{kc.ssh_control_master_template}"
+const RC_ENCRYPTION_PROTOCOL_VERSION string = "{kc.RC_ENCRYPTION_PROTOCOL_VERSION}"
+const IsFrozenBuild bool = false
+const IsStandaloneBuild bool = false
+const HandleTermiosSignals = {Mode.HANDLE_TERMIOS_SIGNALS.value[0]}
+const HintsDefaultRegex = `{DEFAULT_REGEX}`
+var Version VersionType = VersionType{{Major: {kc.version.major}, Minor: {kc.version.minor}, Patch: {kc.version.patch},}}
+var DefaultPager []string = []string{{ {dp} }}
+var FunctionalKeyNameAliases = map[string]string{serialize_go_dict(functional_key_name_aliases)}
+var CharacterKeyNameAliases = map[string]string{serialize_go_dict(character_key_name_aliases)}
+var ConfigModMap = map[string]uint16{serialize_go_dict(config_mod_map)}
+var RefMap = map[string]string{serialize_go_dict(ref_map['ref'])}
+var DocTitleMap = map[string]string{serialize_go_dict(ref_map['doc'])}
+var AllowedShellIntegrationValues = []string{{ {str(sorted(allowed_shell_integration_values))[1:-1].replace("'", '"')} }}
+var KittyConfigDefaults = struct {{
+Term, Shell_integration, Select_by_word_characters string
+Wheel_scroll_multiplier int
+Url_prefixes []string
+}}{{
+Term: "{Options.term}", Shell_integration: "{' '.join(Options.shell_integration)}", Url_prefixes: []string{{ {url_prefixes} }},
+Select_by_word_characters: `{Options.select_by_word_characters}`, Wheel_scroll_multiplier: {Options.wheel_scroll_multiplier},
+}}
+'''  # }}}
+
+
+# Boilerplate {{{
+
+@contextmanager
+def replace_if_needed(path: str, show_diff: bool = False) -> Iterator[io.StringIO]:
+    buf = io.StringIO()
+    origb = sys.stdout
+    sys.stdout = buf
+    try:
+        yield buf
+    finally:
+        sys.stdout = origb
+    orig = ''
+    with suppress(FileNotFoundError), open(path, 'r') as f:
+        orig = f.read()
+    new = buf.getvalue()
+    new = f'// Code generated by {os.path.basename(__file__)}; DO NOT EDIT.\n\n' + new
+    if orig != new:
+        changed.append(path)
+        if show_diff:
+            with open(path + '.new', 'w') as f:
+                f.write(new)
+                subprocess.run(['diff', '-Naurp', path, f.name], stdout=open('/dev/tty', 'w'))
+                os.remove(f.name)
+        with open(path, 'w') as f:
+            f.write(new)
+
+
+@lru_cache(maxsize=256)
+def rc_command_options(name: str) -> Tuple[GoOption, ...]:
+    cmd = command_for_name(name)
+    return tuple(go_options_for_seq(parse_option_spec(cmd.options_spec or '\n\n')[0]))
+
+
+def update_at_commands() -> None:
+    with open('tools/cmd/at/template.go') as f:
+        template = f.read()
+    for name in all_command_names():
+        cmd = command_for_name(name)
+        code = go_code_for_remote_command(name, cmd, template)
+        dest = f'tools/cmd/at/cmd_{name}_generated.go'
+        with replace_if_needed(dest) as f:
+            f.write(code)
+    struct_def = []
+    opt_def = []
+    for o in go_options_for_seq(parse_option_spec(global_options_spec())[0]):
+        struct_def.append(o.struct_declaration())
+        opt_def.append(o.as_option(depth=1, group="Global options"))
+    sdef = '\n'.join(struct_def)
+    odef = '\n'.join(opt_def)
+    code = f'''
+package at
+import "kitty/tools/cli"
+type rc_global_options struct {{
+{sdef}
+}}
+var rc_global_opts rc_global_options
+
+func add_rc_global_opts(cmd *cli.Command) {{
+{odef}
+}}
+'''
+    with replace_if_needed('tools/cmd/at/global_opts_generated.go') as f:
+        f.write(code)
+
+
+def update_completion() -> None:
+    with replace_if_needed('tools/cmd/completion/kitty_generated.go'):
+        generate_completions_for_kitty()
+    with replace_if_needed('tools/cmd/edit_in_kitty/launch_generated.go'):
+        print('package edit_in_kitty')
+        print('import "kitty/tools/cli"')
+        print('func AddCloneSafeOpts(cmd *cli.Command) {')
+        completion_for_launch_wrappers('cmd')
+        print(''.join(CompletionSpec.from_string('type:file mime:text/* group:"Text files"').as_go_code('cmd.ArgCompleter', ' = ')))
+        print('}')
+
+
+def define_enum(package_name: str, type_name: str, items: str, underlying_type: str = 'uint') -> str:
+    actions = []
+    for x in items.splitlines():
+        x = x.strip()
+        if x:
+            actions.append(x)
+    ans = [f'package {package_name}', 'import "strconv"', f'type {type_name} {underlying_type}', 'const (']
+    stringer = [f'func (ac {type_name}) String() string ''{', 'switch(ac) {']
+    for i, ac in enumerate(actions):
+        stringer.append(f'case {ac}: return "{ac}"')
+        if i == 0:
+            ac = ac + f' {type_name} = iota'
+        ans.append(ac)
+    ans.append(')')
+    stringer.append('}\nreturn strconv.Itoa(int(ac)) }')
+    return '\n'.join(ans + stringer)
+
+
+def generate_readline_actions() -> str:
+    return define_enum('readline', 'Action', '''\
+        ActionNil
+
+        ActionBackspace
+        ActionDelete
+        ActionMoveToStartOfLine
+        ActionMoveToEndOfLine
+        ActionMoveToStartOfDocument
+        ActionMoveToEndOfDocument
+        ActionMoveToEndOfWord
+        ActionMoveToStartOfWord
+        ActionCursorLeft
+        ActionCursorRight
+        ActionEndInput
+        ActionAcceptInput
+        ActionCursorUp
+        ActionHistoryPreviousOrCursorUp
+        ActionCursorDown
+        ActionHistoryNextOrCursorDown
+        ActionHistoryNext
+        ActionHistoryPrevious
+        ActionHistoryFirst
+        ActionHistoryLast
+        ActionHistoryIncrementalSearchBackwards
+        ActionHistoryIncrementalSearchForwards
+        ActionTerminateHistorySearchAndApply
+        ActionTerminateHistorySearchAndRestore
+        ActionClearScreen
+        ActionAddText
+        ActionAbortCurrentLine
+
+        ActionStartKillActions
+        ActionKillToEndOfLine
+        ActionKillToStartOfLine
+        ActionKillNextWord
+        ActionKillPreviousWord
+        ActionKillPreviousSpaceDelimitedWord
+        ActionEndKillActions
+        ActionYank
+        ActionPopYank
+
+        ActionNumericArgumentDigit0
+        ActionNumericArgumentDigit1
+        ActionNumericArgumentDigit2
+        ActionNumericArgumentDigit3
+        ActionNumericArgumentDigit4
+        ActionNumericArgumentDigit5
+        ActionNumericArgumentDigit6
+        ActionNumericArgumentDigit7
+        ActionNumericArgumentDigit8
+        ActionNumericArgumentDigit9
+        ActionNumericArgumentDigitMinus
+
+        ActionCompleteForward
+        ActionCompleteBackward
+    ''')
+
+
+def generate_mimetypes() -> str:
+    import mimetypes
+    if not mimetypes.inited:
+        mimetypes.init()
+    ans = ['package utils', 'import "sync"', 'var only_once sync.Once', 'var builtin_types_map map[string]string',
+           'func set_builtins() {', 'builtin_types_map = map[string]string{',]
+    for k, v in mimetypes.types_map.items():
+        ans.append(f'  "{serialize_as_go_string(k)}": "{serialize_as_go_string(v)}",')
+    ans.append('}}')
+    return '\n'.join(ans)
+
+
+def generate_textual_mimetypes() -> str:
+    ans = ['package utils', 'var KnownTextualMimes = map[string]bool{',]
+    for k in text_mimes:
+        ans.append(f'  "{serialize_as_go_string(k)}": true,')
+    ans.append('}')
+    ans.append('var KnownExtensions = map[string]string{')
+    for k, v in known_extensions.items():
+        ans.append(f'  ".{serialize_as_go_string(k)}": "{serialize_as_go_string(v)}",')
+    ans.append('}')
+    return '\n'.join(ans)
+
+
+def write_compressed_data(data: bytes, d: BinaryIO) -> None:
+    d.write(struct.pack('<I', len(data)))
+    d.write(bz2.compress(data))
+
+
+def generate_unicode_names(src: TextIO, dest: BinaryIO) -> None:
+    num_names, num_of_words = map(int, next(src).split())
+    gob = io.BytesIO()
+    gob.write(struct.pack('<II', num_names, num_of_words))
+    for line in src:
+        line = line.strip()
+        if line:
+            a, aliases = line.partition('\t')[::2]
+            cp, name = a.partition(' ')[::2]
+            ename = name.encode()
+            record = struct.pack('<IH', int(cp), len(ename)) + ename
+            if aliases:
+                record += aliases.encode()
+            gob.write(struct.pack('<H', len(record)) + record)
+    write_compressed_data(gob.getvalue(), dest)
+
+
+def generate_ssh_kitten_data() -> None:
+    files = {
+        'terminfo/kitty.terminfo', 'terminfo/x/xterm-kitty',
+    }
+    for dirpath, dirnames, filenames in os.walk('shell-integration'):
+        for f in filenames:
+            path = os.path.join(dirpath, f)
+            files.add(path.replace(os.sep, '/'))
+    dest = 'kittens/ssh/data_generated.bin'
+
+    def normalize(t: tarfile.TarInfo) -> tarfile.TarInfo:
+        t.uid = t.gid = 0
+        t.uname = t.gname = ''
+        return t
+
+    if newer(dest, *files):
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode='w') as tf:
+            for f in sorted(files):
+                tf.add(f, filter=normalize)
+        with open(dest, 'wb') as d:
+            write_compressed_data(buf.getvalue(), d)
+
+
+def main() -> None:
+    with replace_if_needed('constants_generated.go') as f:
+        f.write(generate_constants())
+    with replace_if_needed('tools/utils/style/color-names_generated.go') as f:
+        f.write(generate_color_names())
+    with replace_if_needed('tools/tui/readline/actions_generated.go') as f:
+        f.write(generate_readline_actions())
+    with replace_if_needed('tools/tui/spinners_generated.go') as f:
+        f.write(generate_spinners())
+    with replace_if_needed('tools/utils/mimetypes_generated.go') as f:
+        f.write(generate_mimetypes())
+    with replace_if_needed('tools/utils/mimetypes_textual_generated.go') as f:
+        f.write(generate_textual_mimetypes())
+    if newer('tools/unicode_names/data_generated.bin', 'tools/unicode_names/names.txt'):
+        with open('tools/unicode_names/data_generated.bin', 'wb') as dest, open('tools/unicode_names/names.txt') as src:
+            generate_unicode_names(src, dest)
+    generate_ssh_kitten_data()
+
+    update_completion()
+    update_at_commands()
+    kitten_clis()
+    print(json.dumps(changed, indent=2))
+
+
+if __name__ == '__main__':
+    main()  # }}}

gen-key-constants.py

@@ -2,8 +2,8 @@
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 import string
-from typing import Dict, List, Any
 from pprint import pformat
+from typing import Any, Dict, List, Union
 
 functional_key_defs = '''# {{{
 # kitty                     XKB                         macVK  macU
@@ -130,7 +130,7 @@ functional_encoding_overrides = {
 }
 different_trailer_functionals = {
     'up': 'A', 'down': 'B', 'right': 'C', 'left': 'D', 'kp_begin': 'E', 'end': 'F', 'home': 'H',
-    'f1': 'P', 'f2': 'Q', 'f3': 'R', 'f4': 'S', 'enter': 'u', 'tab': 'u',
+    'f1': 'P', 'f2': 'Q', 'f3': '~', 'f4': 'S', 'enter': 'u', 'tab': 'u',
     'backspace': 'u', 'escape': 'u'
 }
 
@@ -248,6 +248,19 @@ def serialize_dict(x: Dict[Any, Any]) -> str:
     return pformat(x, indent=4).replace('{', '{\n ', 1)
 
 
+def serialize_go_dict(x: Union[Dict[str, int], Dict[int, str], Dict[int, int]]) -> str:
+    ans = []
+
+    def s(x: Union[int, str]) -> str:
+        if isinstance(x, int):
+            return str(x)
+        return f'"{x}"'
+
+    for k, v in x.items():
+        ans.append(f'{s(k)}: {s(v)}')
+    return '{' + ', '.join(ans) + '}'
+
+
 def generate_glfw_header() -> None:
     lines = [
         'typedef enum {',
@@ -309,14 +322,20 @@ def generate_functional_table() -> None:
     patch_file('kitty/key_encoding.c', 'special numbers', '\n'.join(enc_lines))
     code_to_name = {v: k.upper() for k, v in name_to_code.items()}
     csi_map = {v: name_to_code[k] for k, v in functional_encoding_overrides.items()}
-    letter_trailer_codes = {
+    letter_trailer_codes: Dict[str, int] = {
-        v: functional_encoding_overrides.get(k, name_to_code.get(k))
+        v: functional_encoding_overrides.get(k, name_to_code.get(k, 0))
         for k, v in different_trailer_functionals.items() if v in 'ABCDEHFPQRSZ'}
     text = f'functional_key_number_to_name_map = {serialize_dict(code_to_name)}'
     text += f'\ncsi_number_to_functional_number_map = {serialize_dict(csi_map)}'
     text += f'\nletter_trailer_to_csi_number_map = {letter_trailer_codes!r}'
     text += f'\ntilde_trailers = {tilde_trailers!r}'
     patch_file('kitty/key_encoding.py', 'csi mapping', text, start_marker='# ', end_marker='')
+    text = f'var functional_key_number_to_name_map = map[int]string{serialize_go_dict(code_to_name)}\n'
+    text += f'\nvar csi_number_to_functional_number_map = map[int]int{serialize_go_dict(csi_map)}\n'
+    text += f'\nvar letter_trailer_to_csi_number_map = map[string]int{serialize_go_dict(letter_trailer_codes)}\n'
+    tt = ', '.join(f'{x}: true' for x in tilde_trailers)
+    text += '\nvar tilde_trailers = map[int]bool{' + f'{tt}' + '}\n'
+    patch_file('tools/tui/loop/key-encoding.go', 'csi mapping', text, start_marker='// ', end_marker='')
 
 
 def generate_legacy_text_key_maps() -> None:

gen-srgb-lut.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+# vim:fileencoding=utf-8
+
+import os
+from typing import List
+
+
+def to_linear(a: float) -> float:
+    if a <= 0.04045:
+        return a / 12.92
+    else:
+        return float(pow((a + 0.055) / 1.055, 2.4))
+
+
+def generate_srgb_lut(line_prefix: str = '') -> List[str]:
+    values: List[str] = []
+    lines: List[str] = []
+
+    for i in range(256):
+        values.append('{:1.5f}f'.format(to_linear(i / 255.0)))
+
+    for i in range(16):
+        lines.append(line_prefix + ', '.join(values[i * 16:(i + 1) * 16]) + ',')
+
+    return lines
+
+
+def generate_srgb_gamma_c() -> str:
+    lines: List[str] = []
+
+    lines.append('// Generated by gen-srgb-lut.py DO NOT edit')
+    lines.append('#include "srgb_gamma.h"')
+    lines.append('')
+    lines.append('const GLfloat srgb_lut[256] = {')
+    lines += generate_srgb_lut('    ')
+    lines.append('};')
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    c = generate_srgb_gamma_c()
+    with open(os.path.join('kitty', 'srgb_gamma.c'), 'w') as f:
+        f.write(f'{c}\n')
+
+
+if __name__ == '__main__':
+    main()

gen-wcwidth.py

@@ -3,17 +3,26 @@
 
 import os
 import re
+import subprocess
 import sys
 from collections import defaultdict
 from contextlib import contextmanager
-from datetime import date
+from functools import lru_cache, partial
-from functools import partial
 from html.entities import html5
 from itertools import groupby
 from operator import itemgetter
 from typing import (
-    Callable, DefaultDict, Dict, FrozenSet, Generator, Iterable, List,
+    Callable,
-    Optional, Set, Tuple, Union
+    DefaultDict,
+    Dict,
+    FrozenSet,
+    Generator,
+    Iterable,
+    List,
+    Optional,
+    Set,
+    Tuple,
+    Union,
 )
 from urllib.request import urlopen
 
@@ -44,6 +53,15 @@ def get_data(fname: str, folder: str = 'UCD') -> Iterable[str]:
             yield line
 
 
+@lru_cache(maxsize=2)
+def unicode_version() -> Tuple[int, int, int]:
+    for line in get_data("ReadMe.txt"):
+        m = re.search(r'Version\s+(\d+)\.(\d+)\.(\d+)', line)
+        if m is not None:
+            return int(m.group(1)), int(m.group(2)), int(m.group(3))
+    raise ValueError('Could not find Unicode Version')
+
+
 # Map of class names to set of codepoints in class
 class_maps: Dict[str, Set[int]] = {}
 all_symbols: Set[int] = set()
@@ -254,9 +272,13 @@ def get_ranges(items: List[int]) -> Generator[Union[int, Tuple[int, int]], None,
             yield a, b
 
 
-def write_case(spec: Union[Tuple[int, ...], int], p: Callable[..., None]) -> None:
+def write_case(spec: Union[Tuple[int, ...], int], p: Callable[..., None], for_go: bool = False) -> None:
     if isinstance(spec, tuple):
-        p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
+        if for_go:
+            v = ', '.join(f'0x{x:x}' for x in range(spec[0], spec[1] + 1))
+            p(f'\t\tcase {v}:')
+        else:
+            p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
     else:
         p(f'\t\tcase 0x{spec:x}:')
 
@@ -265,8 +287,8 @@ def write_case(spec: Union[Tuple[int, ...], int], p: Callable[..., None]) -> Non
 def create_header(path: str, include_data_types: bool = True) -> Generator[Callable[..., None], None, None]:
     with open(path, 'w') as f:
         p = partial(print, file=f)
-        p('// unicode data, built from the unicode standard on:', date.today())
+        p('// Unicode data, built from the Unicode Standard', '.'.join(map(str, unicode_version())))
-        p('// see gen-wcwidth.py')
+        p(f'// Code generated by {os.path.basename(__file__)}, DO NOT EDIT.', end='\n\n')
         if path.endswith('.h'):
             p('#pragma once')
         if include_data_types:
@@ -347,19 +369,25 @@ def codepoint_to_mark_map(p: Callable[..., None], mark_map: List[int]) -> Dict[i
     return rmap
 
 
-def classes_to_regex(classes: Iterable[str], exclude: str = '') -> Iterable[str]:
+def classes_to_regex(classes: Iterable[str], exclude: str = '', for_go: bool = True) -> Iterable[str]:
     chars: Set[int] = set()
     for c in classes:
         chars |= class_maps[c]
     for x in map(ord, exclude):
         chars.discard(x)
 
-    def as_string(codepoint: int) -> str:
+    if for_go:
-        if codepoint < 256:
+        def as_string(codepoint: int) -> str:
-            return fr'\x{codepoint:02x}'
+            if codepoint < 256:
-        if codepoint <= 0xffff:
+                return fr'\x{codepoint:02x}'
-            return fr'\u{codepoint:04x}'
+            return fr'\x{{{codepoint:x}}}'
-        return fr'\U{codepoint:08x}'
+    else:
+        def as_string(codepoint: int) -> str:
+            if codepoint < 256:
+                return fr'\x{codepoint:02x}'
+            if codepoint <= 0xffff:
+                return fr'\u{codepoint:04x}'
+            return fr'\U{codepoint:08x}'
 
     for spec in get_ranges(list(chars)):
         if isinstance(spec, tuple):
@@ -416,153 +444,144 @@ def gen_ucd() -> None:
             f.truncate()
             f.write(raw)
 
-    with open('kittens/hints/url_regex.py', 'w') as f:
+    chars = ''.join(classes_to_regex(cz, exclude='\n\r'))
-        f.write('# generated by gen-wcwidth.py, do not edit\n\n')
+    with open('tools/cmd/hints/url_regex.go', 'w') as f:
-        f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz, exclude='\n\r'))))
+        f.write('// generated by gen-wcwidth.py, do not edit\n\n')
+        f.write('package hints\n\n')
+        f.write(f'const URL_DELIMITERS = `{chars}`\n')
 
 
 def gen_names() -> None:
-    with create_header('kittens/unicode_input/names.h') as p:
+    aliases_map: Dict[int, Set[str]] = {}
-        mark_to_cp = list(sorted(name_map))
+    for word, codepoints in word_search_map.items():
-        cp_to_mark = {cp: m for m, cp in enumerate(mark_to_cp)}
+        for cp in codepoints:
-        # Mapping of mark to codepoint name
+            aliases_map.setdefault(cp, set()).add(word)
-        p(f'static const char* name_map[{len(mark_to_cp)}] = {{' ' // {{{')
+    if len(name_map) > 0xffff:
-        for cp in mark_to_cp:
+        raise Exception('Too many named codepoints')
-            w = name_map[cp].replace('"', '\\"')
+    with open('tools/unicode_names/names.txt', 'w') as f:
-            p(f'\t"{w}",')
+        print(len(name_map), len(word_search_map), file=f)
-        p("}; // }}}\n")
+        for cp in sorted(name_map):
-
+            name = name_map[cp]
-        # Mapping of mark to codepoint
+            words = name.lower().split()
-        p(f'static const char_type mark_to_cp[{len(mark_to_cp)}] = {{' ' // {{{')
+            aliases = aliases_map.get(cp, set()) - set(words)
-        p(', '.join(map(str, mark_to_cp)))
+            end = '\n'
-        p('}; // }}}\n')
+            if aliases:
-
+                end = '\t' + ' '.join(sorted(aliases)) + end
-        # Function to get mark number for codepoint
+            print(cp, *words, end=end, file=f)
-        p('static char_type mark_for_codepoint(char_type c) {')
-        codepoint_to_mark_map(p, mark_to_cp)
-        p('}\n')
-        p('static inline const char* name_for_codepoint(char_type cp) {')
-        p('\tchar_type m = mark_for_codepoint(cp); if (m == 0) return NULL;')
-        p('\treturn name_map[m];')
-        p('}\n')
-
-        # Array of all words
-        word_map = tuple(sorted(word_search_map))
-        word_rmap = {w: i for i, w in enumerate(word_map)}
-        p(f'static const char* all_words_map[{len(word_map)}] = {{' ' // {{{')
-        cwords = (w.replace('"', '\\"') for w in word_map)
-        p(', '.join(f'"{w}"' for w in cwords))
-        p('}; // }}}\n')
-
-        # Array of sets of marks for each word
-        word_to_marks = {word_rmap[w]: frozenset(map(cp_to_mark.__getitem__, cps)) for w, cps in word_search_map.items()}
-        all_mark_groups = frozenset(word_to_marks.values())
-        array = [0]
-        mg_to_offset = {}
-        for mg in all_mark_groups:
-            mg_to_offset[mg] = len(array)
-            array.append(len(mg))
-            array.extend(sorted(mg))
-        p(f'static const char_type mark_groups[{len(array)}] = {{' ' // {{{')
-        p(', '.join(map(str, array)))
-        p('}; // }}}\n')
-        offsets_array = []
-        for wi, w in enumerate(word_map):
-            mg = word_to_marks[wi]
-            offsets_array.append(mg_to_offset[mg])
-        p(f'static const char_type mark_to_offset[{len(offsets_array)}] = {{' ' // {{{')
-        p(', '.join(map(str, offsets_array)))
-        p('}; // }}}\n')
-
-        # The trie
-        p('typedef struct { uint32_t children_offset; uint32_t match_offset; } word_trie;\n')
-        all_trie_nodes: List['TrieNode'] = []  # noqa
-
-        class TrieNode:
-
-            def __init__(self) -> None:
-                self.match_offset = 0
-                self.children_offset = 0
-                self.children: Dict[int, int] = {}
-
-            def add_letter(self, letter: int) -> int:
-                if letter not in self.children:
-                    self.children[letter] = len(all_trie_nodes)
-                    all_trie_nodes.append(TrieNode())
-                return self.children[letter]
-
-            def __str__(self) -> str:
-                return f'{{ .children_offset={self.children_offset}, .match_offset={self.match_offset} }}'
-
-        root = TrieNode()
-        all_trie_nodes.append(root)
-
-        def add_word(word_idx: int, word: str) -> None:
-            parent = root
-            for letter in map(ord, word):
-                idx = parent.add_letter(letter)
-                parent = all_trie_nodes[idx]
-            parent.match_offset = offsets_array[word_idx]
-
-        for i, word in enumerate(word_map):
-            add_word(i, word)
-        children_array = [0]
-        for node in all_trie_nodes:
-            if node.children:
-                node.children_offset = len(children_array)
-                children_array.append(len(node.children))
-                for letter, child_offset in node.children.items():
-                    children_array.append((child_offset << 8) | (letter & 0xff))
-
-        p(f'static const word_trie all_trie_nodes[{len(all_trie_nodes)}] = {{' ' // {{{')
-        p(',\n'.join(map(str, all_trie_nodes)))
-        p('\n}; // }}}\n')
-        p(f'static const uint32_t children_array[{len(children_array)}] = {{' ' // {{{')
-        p(', '.join(map(str, children_array)))
-        p('}; // }}}\n')
 
 
 def gen_wcwidth() -> None:
     seen: Set[int] = set()
+    non_printing = class_maps['Cc'] | class_maps['Cf'] | class_maps['Cs']
 
-    def add(p: Callable[..., None], comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
+    def add(p: Callable[..., None], comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int, for_go: bool = False) -> None:
         chars = chars_ - seen
         seen.update(chars)
         p(f'\t\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
         for spec in get_ranges(list(chars)):
-            write_case(spec, p)
+            write_case(spec, p, for_go)
             p(f'\t\t\treturn {ret};')
         p('\t\t// }}}\n')
 
-    with create_header('kitty/wcwidth-std.h') as p:
+    def add_all(p: Callable[..., None], for_go: bool = False) -> None:
-        p('static inline int\nwcwidth_std(int32_t code) {')
+        seen.clear()
-        p('\tif (LIKELY(0x20 <= code && code <= 0x7e)) return 1;')
+        add(p, 'Flags', flag_codepoints, 2, for_go)
-        p('\tswitch(code) {')
+        add(p, 'Marks', marks | {0}, 0, for_go)
+        add(p, 'Non-printing characters', non_printing, -1, for_go)
+        add(p, 'Private use', class_maps['Co'], -3, for_go)
+        add(p, 'Text Presentation', narrow_emoji, 1, for_go)
+        add(p, 'East Asian ambiguous width', ambiguous, -2, for_go)
+        add(p, 'East Asian double width', doublewidth, 2, for_go)
+        add(p, 'Emoji Presentation', wide_emoji, 2, for_go)
 
-        non_printing = class_maps['Cc'] | class_maps['Cf'] | class_maps['Cs']
+        add(p, 'Not assigned in the unicode character database', not_assigned, -4, for_go)
-        add(p, 'Flags', flag_codepoints, 2)
-        add(p, 'Marks', marks | {0}, 0)
-        add(p, 'Non-printing characters', non_printing, -1)
-        add(p, 'Private use', class_maps['Co'], -3)
-        add(p, 'Text Presentation', narrow_emoji, 1)
-        add(p, 'East Asian ambiguous width', ambiguous, -2)
-        add(p, 'East Asian double width', doublewidth, 2)
-        add(p, 'Emoji Presentation', wide_emoji, 2)
 
-        add(p, 'Not assigned in the unicode character database', not_assigned, -4)
+        p('\t\tdefault:\n\t\t\treturn 1;')
-
-        p('\t\tdefault: return 1;')
         p('\t}')
-        p('\treturn 1;\n}')
+        if for_go:
+            p('\t}')
+        else:
+            p('\treturn 1;\n}')
+
+    with create_header('kitty/wcwidth-std.h') as p, open('tools/wcswidth/std.go', 'w') as gof:
+        gop = partial(print, file=gof)
+        gop('package wcswidth\n\n')
+        gop('func Runewidth(code rune) int {')
+        p('static inline int\nwcwidth_std(int32_t code) {')
+        p('\tif (LIKELY(0x20 <= code && code <= 0x7e)) { return 1; }')
+        p('\tswitch(code) {')
+        gop('\tswitch(code) {')
+        add_all(p)
+        add_all(gop, True)
 
         p('static inline bool\nis_emoji_presentation_base(uint32_t code) {')
+        gop('func IsEmojiPresentationBase(code rune) bool {')
         p('\tswitch(code) {')
+        gop('\tswitch(code) {')
         for spec in get_ranges(list(emoji_presentation_bases)):
             write_case(spec, p)
+            write_case(spec, gop, for_go=True)
             p('\t\t\treturn true;')
+            gop('\t\t\treturn true;')
         p('\t\tdefault: return false;')
         p('\t}')
-        p('\treturn 1;\n}')
+        gop('\t\tdefault:\n\t\t\treturn false')
+        gop('\t}')
+        p('\treturn true;\n}')
+        gop('\n}')
+        uv = unicode_version()
+        p(f'#define UNICODE_MAJOR_VERSION {uv[0]}')
+        p(f'#define UNICODE_MINOR_VERSION {uv[1]}')
+        p(f'#define UNICODE_PATCH_VERSION {uv[2]}')
+        gop('var UnicodeDatabaseVersion [3]int = [3]int{' f'{uv[0]}, {uv[1]}, {uv[2]}' + '}')
+    subprocess.check_call(['gofmt', '-w', '-s', gof.name])
+
+
+def gen_rowcolumn_diacritics() -> None:
+    # codes of all row/column diacritics
+    codes = []
+    with open("./rowcolumn-diacritics.txt") as file:
+        for line in file.readlines():
+            if line.startswith('#'):
+                continue
+            code = int(line.split(";")[0], 16)
+            codes.append(code)
+
+    go_file = 'tools/utils/images/rowcolumn_diacritics.go'
+    with create_header('kitty/rowcolumn-diacritics.c') as p, create_header(go_file, include_data_types=False) as g:
+        p('#include "unicode-data.h"')
+        p('int diacritic_to_num(char_type code) {')
+        p('\tswitch (code) {')
+        g('package images')
+        g(f'var NumberToDiacritic = [{len(codes)}]rune''{')
+        g(', '.join(f'0x{x:x}' for x in codes) + ',')
+        g('}')
+
+        range_start_num = 1
+        range_start = 0
+        range_end = 0
+
+        def print_range() -> None:
+            if range_start >= range_end:
+                return
+            write_case((range_start, range_end), p)
+            p('\t\treturn code - ' + hex(range_start) + ' + ' +
+              str(range_start_num) + ';')
+
+        for code in codes:
+            if range_end == code:
+                range_end += 1
+            else:
+                print_range()
+                range_start_num += range_end - range_start
+                range_start = code
+                range_end = code + 1
+        print_range()
+
+        p('\t}')
+        p('\treturn 0;')
+        p('}')
+    subprocess.check_call(['gofmt', '-w', '-s', go_file])
 
 
 parse_ucd()
@@ -573,3 +592,4 @@ gen_ucd()
 gen_wcwidth()
 gen_emoji()
 gen_names()
+gen_rowcolumn_diacritics()

glad/generate.py

@@ -8,10 +8,9 @@ import shlex
 import shutil
 import subprocess
 
-
 cmdline = (
-    'glad --out-path {dest} --api gl:core=3.3 '
+    'glad --out-path {dest} --api gl:core=3.1 '
-    ' --extensions GL_ARB_texture_storage,GL_ARB_copy_image,GL_ARB_multisample,GL_ARB_robustness,GL_KHR_debug '
+    ' --extensions GL_ARB_texture_storage,GL_ARB_copy_image,GL_ARB_multisample,GL_ARB_robustness,GL_ARB_instanced_arrays,GL_KHR_debug '
     'c --header-only --debug'
 )
 

glfw/cocoa_init.m

@@ -358,32 +358,49 @@ static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
         finish_launching_callback();
 }
 
-- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename {
+- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename {
-    (void)theApplication;
+    (void)sender;
-    if (!filename || !_glfw.ns.file_open_callback) return NO;
+    if (!filename || !_glfw.ns.url_open_callback) return NO;
-    const char *path = NULL;
+    const char *url = NULL;
     @try {
-        path = [[NSFileManager defaultManager] fileSystemRepresentationWithPath: filename];
+        url = [[[NSURL fileURLWithPath:filename] absoluteString] UTF8String];
     } @catch(NSException *exc) {
         NSLog(@"Converting openFile filename: %@ failed with error: %@", filename, exc.reason);
         return NO;
     }
-    if (!path) return NO;
+    if (!url) return NO;
-    return _glfw.ns.file_open_callback(path);
+    return _glfw.ns.url_open_callback(url);
 }
 
 - (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames {
     (void)sender;
-    if (!_glfw.ns.file_open_callback || !filenames) return;
+    if (!_glfw.ns.url_open_callback || !filenames) return;
     for (id x in filenames) {
         NSString *filename = x;
-        const char *path = NULL;
+        const char *url = NULL;
         @try {
-            path = [[NSFileManager defaultManager] fileSystemRepresentationWithPath: filename];
+            url = [[[NSURL fileURLWithPath:filename] absoluteString] UTF8String];
         } @catch(NSException *exc) {
             NSLog(@"Converting openFiles filename: %@ failed with error: %@", filename, exc.reason);
         }
-        if (path) _glfw.ns.file_open_callback(path);
+        if (url) _glfw.ns.url_open_callback(url);
+    }
+}
+
+// Remove openFile and openFiles when the minimum supported macOS version is 10.13
+- (void)application:(NSApplication *)sender openURLs:(NSArray<NSURL *> *)urls
+{
+    (void)sender;
+    if (!_glfw.ns.url_open_callback || !urls) return;
+    for (id x in urls) {
+        NSURL *ns_url = x;
+        const char *url = NULL;
+        @try {
+            url = [[ns_url absoluteString] UTF8String];
+        } @catch(NSException *exc) {
+            NSLog(@"Converting openURLs url: %@ failed with error: %@", ns_url, exc.reason);
+        }
+        if (url) _glfw.ns.url_open_callback(url);
     }
 }
 
@@ -391,7 +408,6 @@ static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
 {
     (void)notification;
     [NSApp stop:nil];
-    if (_glfw.ns.file_open_callback) _glfw.ns.file_open_callback(":cocoa::application launched::");
 
     CGDisplayRegisterReconfigurationCallback(display_reconfigured, NULL);
     _glfwCocoaPostEmptyEvent();
@@ -563,7 +579,10 @@ is_shiftable_shortcut(int scv) {
 
 static void
 build_global_shortcuts_lookup(void) {
+    // dump these in a terminal with: defaults read com.apple.symbolichotkeys
     NSMutableDictionary<NSString*, NSNumber*> *temp = [NSMutableDictionary dictionaryWithCapacity:128];  // will be autoreleased
+    NSMutableSet<NSNumber*> *temp_configured = [NSMutableSet setWithCapacity:128];  // will be autoreleased
+    NSMutableSet<NSNumber*> *temp_missing_value = [NSMutableSet setWithCapacity:128];  // will be autoreleased
     NSDictionary *apple_settings = [[NSUserDefaults standardUserDefaults] persistentDomainForName:@"com.apple.symbolichotkeys"];
     if (apple_settings) {
         NSDictionary<NSString*, id> *symbolic_hotkeys = [apple_settings objectForKey:@"AppleSymbolicHotKeys"];
@@ -574,9 +593,14 @@ build_global_shortcuts_lookup(void) {
                 NSInteger sc = [key integerValue];
                 NSDictionary *sc_value = obj;
                 id enabled = [sc_value objectForKey:@"enabled"];
-                if (!enabled || ![enabled isKindOfClass:[NSNumber class]] || ![(NSNumber*)enabled boolValue]) continue;
+                if (!enabled || ![enabled isKindOfClass:[NSNumber class]]) continue;
+                [temp_configured addObject:@(sc)];
+                if (![enabled boolValue]) continue;
                 id v = [sc_value objectForKey:@"value"];
-                if (!v || ![v isKindOfClass:[NSDictionary class]]) continue;
+                if (!v || ![v isKindOfClass:[NSDictionary class]]) {
+                    if ([enabled boolValue]) [temp_missing_value addObject:@(sc)];
+                    continue;
+                }
                 NSDictionary *value = v;
                 id t = [value objectForKey:@"type"];
                 if (!t || ![t isKindOfClass:[NSString class]] || ![t isEqualToString:@"standard"]) continue;
@@ -601,6 +625,39 @@ build_global_shortcuts_lookup(void) {
             }
         }
     }
+
+    // Add global shortcut definitions when the default enabled shortcut is not defined,
+    // or when the default enabled shortcut is not disabled and is missing a value.
+    // Here are the shortcuts that are enabled by default in the standard ANSI (US) layout.
+    // macOS provides separate configurations for some languages or keyboards.
+    // In general, the rules here will not take effect.
+    static char buf[64];
+#define S(i, t, m, k) if ([temp_configured member:@(i)] == nil || [temp_missing_value member:@(i)] != nil) { \
+        snprintf(buf, sizeof(buf) - 1, #t":%lx:%ld", (unsigned long)m, (long)k); \
+        temp[@(buf)] = @(i); \
+    }
+
+    // launchpad & dock
+    S(kSHKTurnDockHidingOnOrOff, c, (NSEventModifierFlagOption | NSEventModifierFlagCommand), 'd'); // Opt, Cmd, D
+    // mission control
+    S(kSHKMissionControl, v, NSEventModifierFlagControl, 126); // Ctrl, Arrow Up
+    S(kSHKApplicationWindows, v, NSEventModifierFlagControl, 125); // Ctrl, Arrow Down
+    // keyboard
+    S(kSHKMoveFocusToTheMenuBar, v, NSEventModifierFlagControl, 120); // Ctrl, F2
+    S(kSHKMoveFocusToTheDock, v, NSEventModifierFlagControl, 99); // Ctrl, F3
+    S(kSHKMoveFocusToActiveOrNextWindow, v, NSEventModifierFlagControl, 118); // Ctrl, F4
+    S(kSHKMoveFocusToActiveOrNextWindow, v, (NSEventModifierFlagShift | NSEventModifierFlagControl), 118); // Shift, Ctrl, F4
+    S(kSHKMoveFocusToNextWindow, c, NSEventModifierFlagCommand, 96); // Cmd, `
+    S(kSHKMoveFocusToNextWindow, c, (NSEventModifierFlagShift | NSEventModifierFlagCommand), 96); // Shift, Cmd, `
+    S(kSHKMoveFocusToStatusMenus, v, NSEventModifierFlagControl, 100); // Ctrl, F8
+    // input sources
+    S(kSHKSelectThePreviousInputSource, c, NSEventModifierFlagControl, 32); // Ctrl, Space bar
+    S(kSHKSelectNextSourceInInputMenu, c, (NSEventModifierFlagControl | NSEventModifierFlagOption), 32); // Ctrl, Opt, Space bar
+    // spotlight
+    S(kSHKShowSpotlightSearch, c, NSEventModifierFlagCommand, 32); // Cmd, Space bar
+    S(kSHKShowFinderSearchWindow, c, (NSEventModifierFlagOption | NSEventModifierFlagCommand), 32); // Opt, Cmd, Space bar
+
+#undef S
     global_shortcuts = [[NSDictionary dictionaryWithDictionary:temp] retain];
     /* NSLog(@"global_shortcuts: %@", global_shortcuts); */
 }
@@ -610,11 +667,10 @@ is_active_apple_global_shortcut(NSEvent *event) {
     if (global_shortcuts == nil) build_global_shortcuts_lookup();
     NSEventModifierFlags modifierFlags = USEFUL_MODS([event modifierFlags]);
     static char lookup_key[64];
-
 #define LOOKUP(t, k) \
     snprintf(lookup_key, sizeof(lookup_key) - 1, #t":%lx:%ld", (unsigned long)modifierFlags, (long)k); \
     NSNumber *sc = global_shortcuts[@(lookup_key)]; \
-    if (sc != nil) return [sc intValue];
+    if (sc != nil) return [sc intValue]; \
 
     if ([event.charactersIgnoringModifiers length] == 1) {
         if (modifierFlags & NSEventModifierFlagShift) {
@@ -714,6 +770,11 @@ is_useful_apple_global_shortcut(int sc) {
     }
 }
 
+static bool
+is_apple_jis_layout_function_key(NSEvent *event) {
+    return [event keyCode] == 0x66 /* kVK_JIS_Eisu */ || [event keyCode] == 0x68 /* kVK_JIS_Kana */;
+}
+
 GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
     GLFWapplicationshouldhandlereopenfun previous = handle_reopen_callback;
     handle_reopen_callback = callback;
@@ -752,9 +813,11 @@ int _glfwPlatformInit(void)
     [NSApp setDelegate:_glfw.ns.delegate];
     static struct {
         unsigned short virtual_key_code;
+        NSEventModifierFlags input_source_switch_modifiers;
         NSTimeInterval timestamp;
     } last_keydown_shortcut_event;
     last_keydown_shortcut_event.virtual_key_code = 0xffff;
+    last_keydown_shortcut_event.input_source_switch_modifiers = 0;
 
     NSEvent* (^keydown_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
     {
@@ -765,6 +828,7 @@ int _glfwPlatformInit(void)
             if ([[NSApp mainMenu] performKeyEquivalent:event]) {
                 debug_key("keyDown triggerred global menu bar action ignoring\n");
                 last_keydown_shortcut_event.virtual_key_code = [event keyCode];
+                last_keydown_shortcut_event.input_source_switch_modifiers = 0;
                 last_keydown_shortcut_event.timestamp = [event timestamp];
                 return nil;
             }
@@ -773,6 +837,16 @@ int _glfwPlatformInit(void)
             if (is_useful_apple_global_shortcut(global_shortcut)) {
                 debug_key("keyDown triggerred global macOS shortcut ignoring\n");
                 last_keydown_shortcut_event.virtual_key_code = [event keyCode];
+                // record the modifier keys if switching to the next input source
+                last_keydown_shortcut_event.input_source_switch_modifiers = (global_shortcut == kSHKSelectNextSourceInInputMenu) ? USEFUL_MODS([event modifierFlags]) : 0;
+                last_keydown_shortcut_event.timestamp = [event timestamp];
+                return event;
+            }
+            // check for JIS keyboard layout function keys
+            if (is_apple_jis_layout_function_key(event)) {
+                debug_key("keyDown triggerred JIS layout function key ignoring\n");
+                last_keydown_shortcut_event.virtual_key_code = [event keyCode];
+                last_keydown_shortcut_event.input_source_switch_modifiers = 0;
                 last_keydown_shortcut_event.timestamp = [event timestamp];
                 return event;
             }
@@ -805,6 +879,12 @@ int _glfwPlatformInit(void)
         debug_key("-------------- flags changed -----------------\n");
         debug_key("%s\n", [[event description] UTF8String]);
         last_keydown_shortcut_event.virtual_key_code = 0xffff;
+        // switching to the next input source is only confirmed when all modifier keys are released
+        if (last_keydown_shortcut_event.input_source_switch_modifiers) {
+            if (!([event modifierFlags] & last_keydown_shortcut_event.input_source_switch_modifiers))
+                last_keydown_shortcut_event.input_source_switch_modifiers = 0;
+            return event;
+        }
         NSWindow *kw = [NSApp keyWindow];
         if (kw && kw.contentView) [kw.contentView flagsChanged:event];
         else debug_key("flagsChanged ignored as no keyWindow present\n");
@@ -912,8 +992,6 @@ void _glfwPlatformTerminate(void)
         _glfw.ns.appleSettings = nil;
     }
 
-    free(_glfw.ns.clipboardString);
-
     _glfwTerminateNSGL();
     if (global_shortcuts != nil) { [global_shortcuts release]; global_shortcuts = nil; }
 
@@ -936,7 +1014,7 @@ static pthread_t main_thread;
 static NSLock *tick_lock = NULL;
 
 
-void _glfwDispatchTickCallback() {
+void _glfwDispatchTickCallback(void) {
     if (tick_lock && tick_callback) {
         [tick_lock lock];
         while(tick_callback_requested) {
@@ -948,7 +1026,7 @@ void _glfwDispatchTickCallback() {
 }
 
 static void
-request_tick_callback() {
+request_tick_callback(void) {
     if (!tick_callback_requested) {
         tick_callback_requested = true;
         [NSApp performSelectorOnMainThread:@selector(tick_callback) withObject:nil waitUntilDone:NO];

glfw/cocoa_monitor.m

@@ -323,7 +323,7 @@ static double getFallbackRefreshRate(CGDirectDisplayID displayID)
 //////                       GLFW internal API                      //////
 //////////////////////////////////////////////////////////////////////////
 
-void _glfwClearDisplayLinks() {
+void _glfwClearDisplayLinks(void) {
     for (size_t i = 0; i < _glfw.ns.displayLinks.count; i++) {
         if (_glfw.ns.displayLinks.entries[i].displayLink) {
             CVDisplayLinkStop(_glfw.ns.displayLinks.entries[i].displayLink);

glfw/cocoa_platform.h

@@ -68,7 +68,7 @@ typedef void* CVDisplayLinkRef;
 
 typedef int (* GLFWcocoatextinputfilterfun)(int,int,unsigned int, unsigned long);
 typedef bool (* GLFWapplicationshouldhandlereopenfun)(int);
-typedef bool (* GLFWhandlefileopen)(const char*);
+typedef bool (* GLFWhandleurlopen)(const char*);
 typedef void (* GLFWapplicationwillfinishlaunchingfun)(void);
 typedef bool (* GLFWcocoatogglefullscreenfun)(GLFWwindow*);
 typedef void (* GLFWcocoarenderframefun)(GLFWwindow*);
@@ -131,6 +131,7 @@ typedef struct _GLFWwindowNS
     bool            maximized;
     bool            retina;
     bool            in_traditional_fullscreen;
+    bool            in_fullscreen_transition;
     bool            titlebar_hidden;
     unsigned long   pre_full_screen_style_mask;
 
@@ -153,6 +154,8 @@ typedef struct _GLFWwindowNS
     // Whether a render frame has been requested for this window
     bool renderFrameRequested;
     GLFWcocoarenderframefun renderFrameCallback;
+    // update cursor after switching desktops with Mission Control
+    bool delayed_cursor_update_requested;
 } _GLFWwindowNS;
 
 typedef struct _GLFWDisplayLinkNS
@@ -180,7 +183,6 @@ typedef struct _GLFWlibraryNS
 
     char                keyName[64];
     char                text[256];
-    char*               clipboardString;
     CGPoint             cascadePoint;
     // Where to place the cursor when re-enabled
     double              restoreCursorPosX, restoreCursorPosY;
@@ -199,8 +201,8 @@ typedef struct _GLFWlibraryNS
         _GLFWDisplayLinkNS entries[256];
         size_t count;
     } displayLinks;
-    // the callback to handle file open events
+    // the callback to handle url open events
-    GLFWhandlefileopen file_open_callback;
+    GLFWhandleurlopen url_open_callback;
 
 } _GLFWlibraryNS;
 

glfw/cocoa_window.m

@@ -29,6 +29,9 @@
 #include "internal.h"
 #include "../kitty/monotonic.h"
 
+#include <Availability.h>
+#import <CoreServices/CoreServices.h>
+#import <UniformTypeIdentifiers/UniformTypeIdentifiers.h>
 #include <float.h>
 #include <string.h>
 
@@ -582,6 +585,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 }
 
 - (instancetype)initWithGlfwWindow:(_GLFWwindow *)initWindow;
+- (void)request_delayed_cursor_update:(id)sender;
 
 @end
 
@@ -692,6 +696,9 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
         _glfwPlatformGetCursorPos(window, &x, &y);
         _glfwInputCursorPos(window, x, y);
     }
+    // macOS will send a delayed event to update the cursor to arrow after switching desktops.
+    // So we need to delay and update the cursor once after that.
+    [self performSelector:@selector(request_delayed_cursor_update:) withObject:nil afterDelay:0.3];
 }
 
 - (void)windowDidResignKey:(NSNotification *)notification
@@ -722,6 +729,38 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     }
 }
 
+- (void)request_delayed_cursor_update:(id)sender
+{
+    (void)sender;
+    if (window) window->ns.delayed_cursor_update_requested = true;
+}
+
+- (void)windowWillEnterFullScreen:(NSNotification *)notification
+{
+    (void)notification;
+    if (window) window->ns.in_fullscreen_transition = true;
+}
+
+- (void)windowDidEnterFullScreen:(NSNotification *)notification
+{
+    (void)notification;
+    if (window) window->ns.in_fullscreen_transition = false;
+    [self performSelector:@selector(request_delayed_cursor_update:) withObject:nil afterDelay:0.3];
+}
+
+- (void)windowWillExitFullScreen:(NSNotification *)notification
+{
+    (void)notification;
+    if (window) window->ns.in_fullscreen_transition = true;
+}
+
+- (void)windowDidExitFullScreen:(NSNotification *)notification
+{
+    (void)notification;
+    if (window) window->ns.in_fullscreen_transition = false;
+    [self performSelector:@selector(request_delayed_cursor_update:) withObject:nil afterDelay:0.3];
+}
+
 @end // }}}
 
 // Text input context class for the GLFW content view {{{
@@ -904,6 +943,11 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 
     window->ns.cursorWarpDeltaX = 0;
     window->ns.cursorWarpDeltaY = 0;
+
+    if (window->ns.delayed_cursor_update_requested) {
+        window->ns.delayed_cursor_update_requested = false;
+        if (cursorInContentArea(window)) updateCursorImage(window);
+    }
 }
 
 - (void)rightMouseDown:(NSEvent *)event
@@ -966,6 +1010,18 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     _glfwInputCursorEnter(window, true);
 }
 
+- (void)viewDidChangeEffectiveAppearance
+{
+    static int appearance = 0;
+    if (_glfw.callbacks.system_color_theme_change) {
+        int new_appearance = glfwGetCurrentSystemColorTheme();
+        if (new_appearance != appearance) {
+            appearance = new_appearance;
+            _glfw.callbacks.system_color_theme_change(appearance);
+        }
+    }
+}
+
 - (void)viewDidChangeBackingProperties
 {
     if (!window) return;
@@ -1003,6 +1059,8 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 
 - (void)updateTrackingAreas
 {
+    if (window && [window->ns.object areCursorRectsEnabled])
+        [window->ns.object disableCursorRects];
     if (trackingArea != nil)
     {
         [self removeTrackingArea:trackingArea];
@@ -1325,14 +1383,17 @@ is_ascii_control_char(char x) {
                                               options:options];
     if (!objs) return NO;
     const NSUInteger count = [objs count];
+    NSMutableString *uri_list = [NSMutableString stringWithCapacity:4096];  // auto-released
     if (count)
     {
         for (NSUInteger i = 0;  i < count;  i++)
         {
             id obj = objs[i];
             if ([obj isKindOfClass:[NSURL class]]) {
-                const char *path = [obj fileSystemRepresentation];
+                NSURL *url = (NSURL*)obj;
-                _glfwInputDrop(window, "text/plain;charset=utf-8", path, strlen(path));
+                if ([uri_list length] > 0) [uri_list appendString:@("\n")];
+                if (url.fileURL) [uri_list appendString:url.filePathURL.absoluteString];
+                else [uri_list appendString:url.absoluteString];
             } else if ([obj isKindOfClass:[NSString class]]) {
                 const char *text = [obj UTF8String];
                 _glfwInputDrop(window, "text/plain;charset=utf-8", text, strlen(text));
@@ -1342,6 +1403,7 @@ is_ascii_control_char(char x) {
             }
         }
     }
+    if ([uri_list length] > 0) _glfwInputDrop(window, "text/uri-list", uri_list.UTF8String, strlen(uri_list.UTF8String));
 
     return YES;
 }
@@ -1404,15 +1466,11 @@ is_ascii_control_char(char x) {
 }
 
 void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
-    [w->ns.view updateIMEStateFor: ev->type focused:(bool)ev->focused left:(CGFloat)ev->cursor.left top:(CGFloat)ev->cursor.top cellWidth:(CGFloat)ev->cursor.width cellHeight:(CGFloat)ev->cursor.height];
+    [w->ns.view updateIMEStateFor: ev->type focused:(bool)ev->focused];
 }
 
 - (void)updateIMEStateFor:(GLFWIMEUpdateType)which
                   focused:(bool)focused
-                     left:(CGFloat)left
-                      top:(CGFloat)top
-                cellWidth:(CGFloat)cellWidth
-               cellHeight:(CGFloat)cellHeight
 {
     if (which == GLFW_IME_UPDATE_FOCUS && !focused && [self hasMarkedText] && window) {
         [input_context discardMarkedText];
@@ -1422,16 +1480,7 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
         _glfw.ns.text[0] = 0;
     }
     if (which != GLFW_IME_UPDATE_CURSOR_POSITION) return;
-    left /= window->ns.xscale;
+
-    top /= window->ns.yscale;
-    cellWidth /= window->ns.xscale;
-    cellHeight /= window->ns.yscale;
-    debug_key("updateIMEPosition: left=%f, top=%f, width=%f, height=%f\n", left, top, cellWidth, cellHeight);
-    const NSRect frame = [window->ns.view frame];
-    const NSRect rectInView = NSMakeRect(left,
-                                         frame.size.height - top - cellHeight,
-                                         cellWidth, cellHeight);
-    markedRect = [window->ns.object convertRectToScreen: rectInView];
     if (_glfwPlatformWindowFocused(window)) [[window->ns.view inputContext] invalidateCharacterCoordinates];
 }
 
@@ -1457,6 +1506,21 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
                          actualRange:(NSRangePointer)actualRange
 {
     (void)range; (void)actualRange;
+    if (_glfw.callbacks.get_ime_cursor_position) {
+        GLFWIMEUpdateEvent ev = { .type = GLFW_IME_UPDATE_CURSOR_POSITION };
+        if (_glfw.callbacks.get_ime_cursor_position((GLFWwindow*)window, &ev)) {
+            const CGFloat left = (CGFloat)ev.cursor.left / window->ns.xscale;
+            const CGFloat top = (CGFloat)ev.cursor.top / window->ns.yscale;
+            const CGFloat cellWidth = (CGFloat)ev.cursor.width / window->ns.xscale;
+            const CGFloat cellHeight = (CGFloat)ev.cursor.height / window->ns.yscale;
+            debug_key("updateIMEPosition: left=%f, top=%f, width=%f, height=%f\n", left, top, cellWidth, cellHeight);
+            const NSRect frame = [window->ns.view frame];
+            const NSRect rectInView = NSMakeRect(left,
+                                                 frame.size.height - top - cellHeight,
+                                                 cellWidth, cellHeight);
+            markedRect = [window->ns.object convertRectToScreen: rectInView];
+        }
+    }
     return markedRect;
 }
 
@@ -1493,6 +1557,104 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
     debug_key("\n\tdoCommandBySelector: (%s)\n", [NSStringFromSelector(selector) UTF8String]);
 }
 
+- (BOOL)isAccessibilityElement
+{
+    return YES;
+}
+
+- (BOOL)isAccessibilitySelectorAllowed:(SEL)selector
+{
+    if (selector == @selector(accessibilityRole) || selector == @selector(accessibilitySelectedText)) return YES;
+    return NO;
+}
+
+#if (TARGET_OS_OSX && __MAC_OS_X_VERSION_MIN_REQUIRED >= 101400)
+
+- (NSAccessibilityRole)accessibilityRole
+{
+    return NSAccessibilityTextAreaRole;
+}
+
+#endif
+
+- (NSString *)accessibilitySelectedText
+{
+    NSString *text = nil;
+    if (_glfw.callbacks.get_current_selection) {
+        char *s = _glfw.callbacks.get_current_selection();
+        if (s) {
+            text = [NSString stringWithUTF8String:s];
+            free(s);
+        }
+    }
+    return text;
+}
+
+// <https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/SysServices/Articles/using.html>
+
+// Support services receiving "public.utf8-plain-text" and "NSStringPboardType"
+- (id)validRequestorForSendType:(NSString *)sendType returnType:(NSString *)returnType
+{
+    if (
+        (!sendType || [sendType isEqual:NSPasteboardTypeString] || [sendType isEqual:@"NSStringPboardType"]) &&
+        (!returnType || [returnType isEqual:NSPasteboardTypeString] || [returnType isEqual:@"NSStringPboardType"])
+    ) {
+        if (_glfw.callbacks.has_current_selection && _glfw.callbacks.has_current_selection()) return self;
+    }
+    return [super validRequestorForSendType:sendType returnType:returnType];
+}
+
+// Selected text as input to be sent to Services
+// For example, after selecting an absolute path, open the global menu bar kitty->Services and click `Show in Finder`.
+- (BOOL)writeSelectionToPasteboard:(NSPasteboard *)pboard types:(NSArray *)types
+{
+    if (!_glfw.callbacks.get_current_selection) return NO;
+    char *text = _glfw.callbacks.get_current_selection();
+    if (!text) return NO;
+    BOOL ans = NO;
+    if (text[0]) {
+        if ([types containsObject:NSPasteboardTypeString] == YES) {
+            [pboard declareTypes:@[NSPasteboardTypeString] owner:self];
+            ans = [pboard setString:@(text) forType:NSPasteboardTypeString];
+        } else if ([types containsObject:@"NSStringPboardType"] == YES) {
+            [pboard declareTypes:@[@"NSStringPboardType"] owner:self];
+            ans = [pboard setString:@(text) forType:@"NSStringPboardType"];
+        }
+        free(text);
+    }
+    return ans;
+}
+
+// Service output to be handled
+// For example, open System Settings->Keyboard->Keyboard Shortcuts->Services->Text, enable `Convert Text to Full Width`, select some text and execute the service.
+- (BOOL)readSelectionFromPasteboard:(NSPasteboard *)pboard
+{
+    NSString* text = nil;
+    NSArray *types = [pboard types];
+    if ([types containsObject:NSPasteboardTypeString] == YES) {
+        text = [pboard stringForType:NSPasteboardTypeString]; // public.utf8-plain-text
+    } else if ([types containsObject:@"NSStringPboardType"] == YES) {
+        text = [pboard stringForType:@"NSStringPboardType"]; // for older services (need re-encode?)
+    } else {
+        return NO;
+    }
+    if (text && [text length] > 0) {
+        // The service wants us to replace the selection, but we can't replace anything but insert text.
+        const char *utf8 = polymorphic_string_as_utf8(text);
+        debug_key("Sending text received in readSelectionFromPasteboard as key event\n");
+        GLFWkeyevent glfw_keyevent = {.text=utf8, .ime_state=GLFW_IME_COMMIT_TEXT};
+        _glfwInputKeyboard(window, &glfw_keyevent);
+        // Restore pre-edit text after inserting the received text
+        if ([self hasMarkedText]) {
+            glfw_keyevent.text = [[markedText string] UTF8String];
+            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
+            _glfwInputKeyboard(window, &glfw_keyevent);
+        }
+        return YES;
+    }
+    return NO;
+}
+
 @end
 // }}}
 
@@ -1554,8 +1716,11 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
 
 - (void)toggleFullScreen:(nullable id)sender
 {
-    if (glfw_window && glfw_window->ns.toggleFullscreenCallback && glfw_window->ns.toggleFullscreenCallback((GLFWwindow*)glfw_window) == 1)
+    if (glfw_window) {
-            return;
+        if (glfw_window->ns.in_fullscreen_transition) return;
+        if (glfw_window->ns.toggleFullscreenCallback && glfw_window->ns.toggleFullscreenCallback((GLFWwindow*)glfw_window) == 1) return;
+        glfw_window->ns.in_fullscreen_transition = true;
+    }
     // When resizeIncrements is set, Cocoa cannot restore the original window size after returning from fullscreen.
     const NSSize original = [self resizeIncrements];
     [self setResizeIncrements:NSMakeSize(1.0, 1.0)];
@@ -1566,6 +1731,18 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
     if (glfw_window && !glfw_window->decorated && glfw_window->ns.view) [self makeFirstResponder:glfw_window->ns.view];
 }
 
+- (void)zoom:(id)sender
+{
+    if (![self isZoomed]) {
+        const NSSize original = [self resizeIncrements];
+        [self setResizeIncrements:NSMakeSize(1.0, 1.0)];
+        [super zoom:sender];
+        [self setResizeIncrements:original];
+    } else {
+        [super zoom:sender];
+    }
+}
+
 @end
 // }}}
 
@@ -1681,7 +1858,11 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
 
     if (!createNativeWindow(window, wndconfig, fbconfig))
         return false;
-    [window->ns.object setColorSpace:[NSColorSpace sRGBColorSpace]];
+    switch((GlfwCocoaColorSpaces)wndconfig->ns.color_space) {
+        case SRGB_COLORSPACE: [window->ns.object setColorSpace:[NSColorSpace sRGBColorSpace]]; break;
+        case DISPLAY_P3_COLORSPACE: [window->ns.object setColorSpace:[NSColorSpace displayP3ColorSpace]]; break;
+        case DEFAULT_COLORSPACE: break;
+    }
 
     if (ctxconfig->client != GLFW_NO_API)
     {
@@ -1715,8 +1896,9 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
 
     if (window->monitor)
     {
-        _glfwPlatformShowWindow(window);
+        // Do not show the window here until after setting the window size, maximized state, and full screen
-        _glfwPlatformFocusWindow(window);
+        // _glfwPlatformShowWindow(window);
+        // _glfwPlatformFocusWindow(window);
         acquireMonitor(window);
     }
 
@@ -1908,8 +2090,9 @@ void _glfwPlatformRestoreWindow(_GLFWwindow* window)
 
 void _glfwPlatformMaximizeWindow(_GLFWwindow* window)
 {
-    if (![window->ns.object isZoomed])
+    if (![window->ns.object isZoomed]) {
         [window->ns.object zoom:nil];
+    }
 }
 
 void _glfwPlatformShowWindow(_GLFWwindow* window)
@@ -2415,41 +2598,166 @@ bool _glfwPlatformToggleFullscreen(_GLFWwindow* w, unsigned int flags) {
         if (in_fullscreen) made_fullscreen = false;
         [window toggleFullScreen: nil];
     }
+    // Update window button visibility
+    if (w->ns.titlebar_hidden) {
+        // The hidden buttons might be automatically reset to be visible after going full screen
+        // to show up in the auto-hide title bar, so they need to be set back to hidden.
+        BOOL button_hidden = YES;
+        // When title bar is configured to be hidden, it should be shown with buttons (auto-hide) after going to full screen.
+        if (!traditional) {
+            button_hidden = (BOOL) !made_fullscreen;
+        }
+        [[window standardWindowButton: NSWindowCloseButton] setHidden:button_hidden];
+        [[window standardWindowButton: NSWindowMiniaturizeButton] setHidden:button_hidden];
+        [[window standardWindowButton: NSWindowZoomButton] setHidden:button_hidden];
+    }
     return made_fullscreen;
 }
 
-void _glfwPlatformSetClipboardString(const char* string)
+// Clipboard {{{
-{
+
-    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+#define UTI_ROUNDTRIP_PREFIX @"uti-is-typical-apple-nih."
-    [pasteboard declareTypes:@[NSPasteboardTypeString] owner:nil];
+
-    [pasteboard setString:@(string) forType:NSPasteboardTypeString];
+static NSString*
+mime_to_uti(const char *mime) {
+    if (strcmp(mime, "text/plain") == 0) return NSPasteboardTypeString;
+    if (@available(macOS 11.0, *)) {
+        UTType *t = [UTType typeWithMIMEType:@(mime)];  // auto-released
+        if (t != nil && !t.dynamic) return t.identifier;
+    }
+    return [NSString stringWithFormat:@"%@%s", UTI_ROUNDTRIP_PREFIX, mime];  // auto-released
 }
 
-const char* _glfwPlatformGetClipboardString(void)
+static const char*
-{
+uti_to_mime(NSString *uti) {
-    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    if ([uti isEqualToString:NSPasteboardTypeString]) return "text/plain";
-
+    if ([uti hasPrefix:UTI_ROUNDTRIP_PREFIX]) return [[uti substringFromIndex:[UTI_ROUNDTRIP_PREFIX length]] UTF8String];
-    if (![[pasteboard types] containsObject:NSPasteboardTypeString])
+    if (@available(macOS 11.0, *)) {
-    {
+        UTType *t = [UTType typeWithIdentifier:uti];  // auto-released
-        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
+        if (t.preferredMIMEType != nil) return [t.preferredMIMEType UTF8String];
-                        "Cocoa: Failed to retrieve string from pasteboard");
-        return NULL;
     }
-
+    return "";
-    NSString* object = [pasteboard stringForType:NSPasteboardTypeString];
-    if (!object)
-    {
-        _glfwInputError(GLFW_PLATFORM_ERROR,
-                        "Cocoa: Failed to retrieve object from pasteboard");
-        return NULL;
-    }
-
-    free(_glfw.ns.clipboardString);
-    _glfw.ns.clipboardString = _glfw_strdup([object UTF8String]);
-
-    return _glfw.ns.clipboardString;
 }
 
+static void
+list_clipboard_mimetypes(GLFWclipboardwritedatafun write_data, void *object) {
+#define w(x) { if (ok) ok = write_data(object, x, strlen(x)); }
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    NSDictionary* options = @{NSPasteboardURLReadingFileURLsOnlyKey:@YES};
+    BOOL has_file_urls = [pasteboard canReadObjectForClasses:@[[NSURL class]] options:options];
+    BOOL has_strings = [pasteboard canReadObjectForClasses:@[[NSString class]] options:nil];
+    /* NSLog(@"has_file_urls: %d has_strings: %d", has_file_urls, has_strings); */
+    bool ok = true;
+    if (has_strings) w("text/plain");
+    if (has_file_urls) w("text/local-path-list");
+    for (NSPasteboardItem * item in pasteboard.pasteboardItems) {
+        for (NSPasteboardType type in item.types) {
+            /* NSLog(@"%@", type); */
+            const char *mime = uti_to_mime(type);
+            if (mime && mime[0] && ![@(mime) hasPrefix:@"text/plain"]) {
+                /* NSLog(@"ut: %@ mt: %@ tags: %@", ut, ut.preferredMIMEType, ut.tags); */
+                w(mime);
+            }
+        }
+    }
+#undef w
+}
+
+static void
+get_text_plain(GLFWclipboardwritedatafun write_data, void *object) {
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    NSDictionary* options = @{NSPasteboardURLReadingFileURLsOnlyKey:@YES};
+    NSArray* objs = [pasteboard readObjectsForClasses:@[[NSURL class], [NSString class]] options:options];
+    bool found = false;
+    if (objs) {
+        const NSUInteger count = [objs count];
+        if (count) {
+            NSMutableData *path_list = [NSMutableData dataWithCapacity:4096];  // auto-released
+            NSMutableData *text_list = [NSMutableData dataWithCapacity:4096];  // auto-released
+            for (NSUInteger i = 0;  i < count;  i++) {
+                id obj = objs[i];
+                if ([obj isKindOfClass:[NSURL class]]) {
+                    NSURL *url = (NSURL*)obj;
+                    if (url.fileURL && url.fileSystemRepresentation) {
+                        if ([path_list length] > 0) [path_list appendBytes:"\n" length:1];
+                        [path_list appendBytes:url.fileSystemRepresentation length:strlen(url.fileSystemRepresentation)];
+                    }
+                } else if ([obj isKindOfClass:[NSString class]]) {
+                    if ([text_list length] > 0) [text_list appendBytes:"\n" length:1];
+                    [text_list appendData:[obj dataUsingEncoding:NSUTF8StringEncoding]];
+                }
+            }
+            const NSMutableData *text = nil;
+            if (path_list.length > 0) text = path_list;
+            else if (text_list.length > 0) text = text_list;
+            if (text) {
+                found = true;
+                write_data(object, text.mutableBytes, text.length);
+            }
+        }
+    }
+    if (!found) _glfwInputError(GLFW_PLATFORM_ERROR, "Cocoa: Failed to retrieve text/plain from pasteboard");
+}
+
+void
+_glfwPlatformGetClipboard(GLFWClipboardType clipboard_type, const char* mime_type, GLFWclipboardwritedatafun write_data, void *object) {
+    if (clipboard_type != GLFW_CLIPBOARD) return;
+    if (mime_type == NULL) {
+        list_clipboard_mimetypes(write_data, object);
+        return;
+    }
+    if (strcmp(mime_type, "text/plain") == 0) {
+        get_text_plain(write_data, object);
+        return;
+    }
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    /* NSLog(@"mime: %s uti: %@", mime_type, mime_to_uti(mime_type)); */
+    NSPasteboardType t = [pasteboard availableTypeFromArray:@[mime_to_uti(mime_type)]];
+    /* NSLog(@"available type: %@", t); */
+    if (t != nil) {
+        NSData *data = [pasteboard dataForType:t];  // auto-released
+        /* NSLog(@"data: %@", data); */
+        if (data != nil && data.length > 0) {
+            write_data(object, data.bytes, data.length);
+        }
+    }
+}
+
+static NSMutableData*
+get_clipboard_data(const _GLFWClipboardData *cd, const char *mime) {
+    NSMutableData *ans = [NSMutableData dataWithCapacity:8192];
+    if (ans == nil) return nil;
+    GLFWDataChunk chunk = cd->get_data(mime, NULL, cd->ctype);
+    void *iter = chunk.iter;
+    if (!iter) return ans;
+    while (true) {
+        chunk = cd->get_data(mime, iter, cd->ctype);
+        if (!chunk.sz) break;
+        [ans appendBytes:chunk.data length:chunk.sz];
+        if (chunk.free) chunk.free((void*)chunk.free_data);
+    }
+    cd->get_data(NULL, iter, cd->ctype);
+    return ans;
+}
+
+
+void
+_glfwPlatformSetClipboard(GLFWClipboardType t) {
+    if (t != GLFW_CLIPBOARD) return;
+    NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    NSMutableArray<NSPasteboardType> *ptypes = [NSMutableArray arrayWithCapacity:_glfw.clipboard.num_mime_types];  // auto-released
+    for (size_t i = 0; i < _glfw.clipboard.num_mime_types; i++) {
+        [ptypes addObject:mime_to_uti(_glfw.clipboard.mime_types[i])];
+    }
+    [pasteboard declareTypes:ptypes owner:nil];
+    for (size_t i = 0; i < _glfw.clipboard.num_mime_types; i++) {
+        NSMutableData *data = get_clipboard_data(&_glfw.clipboard, _glfw.clipboard.mime_types[i]);  // auto-released
+        /* NSLog(@"putting data: %@ for: %s with UTI: %@", data, _glfw.clipboard.mime_types[i], ptypes[i]); */
+        if (data != nil) [pasteboard setData:data forType:ptypes[i]];
+    }
+}
+// }}}
+
 EGLenum _glfwPlatformGetEGLPlatform(EGLint** attribs)
 {
     if (_glfw.egl.ANGLE_platform_angle)
@@ -2642,10 +2950,10 @@ GLFWAPI GLFWcocoatextinputfilterfun glfwSetCocoaTextInputFilter(GLFWwindow *hand
     return previous;
 }
 
-GLFWAPI GLFWhandlefileopen glfwSetCocoaFileOpenCallback(GLFWhandlefileopen callback) {
+GLFWAPI GLFWhandleurlopen glfwSetCocoaURLOpenCallback(GLFWhandleurlopen callback) {
     _GLFW_REQUIRE_INIT_OR_RETURN(nil);
-    GLFWhandlefileopen prev = _glfw.ns.file_open_callback;
+    GLFWhandleurlopen prev = _glfw.ns.url_open_callback;
-    _glfw.ns.file_open_callback = callback;
+    _glfw.ns.url_open_callback = callback;
     return prev;
 }
 
@@ -2661,6 +2969,19 @@ GLFWAPI void glfwCocoaRequestRenderFrame(GLFWwindow *w, GLFWcocoarenderframefun
     requestRenderFrame((_GLFWwindow*)w, callback);
 }
 
+GLFWAPI int glfwGetCurrentSystemColorTheme(void) {
+    int theme_type = 0;
+    NSAppearance *changedAppearance = NSApp.effectiveAppearance;
+    NSAppearanceName newAppearance = [changedAppearance bestMatchFromAppearancesWithNames:@[NSAppearanceNameAqua, NSAppearanceNameDarkAqua]];
+    if([newAppearance isEqualToString:NSAppearanceNameDarkAqua]){
+        theme_type = 1;
+    } else {
+        theme_type = 2;
+    }
+    return theme_type;
+}
+
+
 GLFWAPI uint32_t
 glfwGetCocoaKeyEquivalent(uint32_t glfw_key, int glfw_mods, int *cocoa_mods) {
     *cocoa_mods = 0;

glfw/context.c

@@ -396,15 +396,6 @@ bool _glfwRefreshContextAttribs(_GLFWwindow* window,
             window->context.release = GLFW_RELEASE_BEHAVIOR_FLUSH;
     }
 
-    // Clearing the front buffer to black to avoid garbage pixels left over from
-    // previous uses of our bit of VRAM
-    {
-        PFNGLCLEARPROC glClear = (PFNGLCLEARPROC)
-            window->context.getProcAddress("glClear");
-        glClear(GL_COLOR_BUFFER_BIT);
-        window->context.swapBuffers(window);
-    }
-
     glfwMakeContextCurrent((GLFWwindow*) previous);
     return true;
 }
@@ -487,6 +478,9 @@ GLFWAPI void glfwSwapBuffers(GLFWwindow* handle)
     }
 
     window->context.swapBuffers(window);
+#ifdef _GLFW_WAYLAND
+    _glfwWaylandAfterBufferSwap(window);
+#endif
 }
 
 GLFWAPI void glfwSwapInterval(int interval)

glfw/dbus_glfw.c

@@ -174,7 +174,7 @@ glfw_dbus_dispatch(DBusConnection *conn) {
 }
 
 void
-glfw_dbus_session_bus_dispatch() {
+glfw_dbus_session_bus_dispatch(void) {
     if (session_bus) glfw_dbus_dispatch(session_bus);
 }
 
@@ -263,7 +263,7 @@ call_method_with_msg(DBusConnection *conn, DBusMessage *msg, int timeout, dbus_p
 
 static bool
 call_method(DBusConnection *conn, const char *node, const char *path, const char *interface, const char *method, int timeout, dbus_pending_callback callback, void *user_data, va_list ap) {
-    if (!conn) return false;
+    if (!conn || !path) return false;
     DBusMessage *msg = dbus_message_new_method_call(node, path, interface, method);
     if (!msg) return false;
     bool retval = false;
@@ -344,7 +344,7 @@ glfw_dbus_connect_to_session_bus(void) {
 }
 
 DBusConnection *
-glfw_dbus_session_bus() {
+glfw_dbus_session_bus(void) {
     if (!session_bus) glfw_dbus_connect_to_session_bus();
     return session_bus;
 }

glfw/egl_context.c

@@ -326,6 +326,7 @@ bool _glfwInitEGL(void)
     glfw_dlsym(_glfw.egl.SwapBuffers, _glfw.egl.handle, "eglSwapBuffers");
     glfw_dlsym(_glfw.egl.SwapInterval, _glfw.egl.handle, "eglSwapInterval");
     glfw_dlsym(_glfw.egl.QueryString, _glfw.egl.handle, "eglQueryString");
+    glfw_dlsym(_glfw.egl.QuerySurface, _glfw.egl.handle, "eglQuerySurface");
     glfw_dlsym(_glfw.egl.GetProcAddress, _glfw.egl.handle, "eglGetProcAddress");
 
     if (!_glfw.egl.GetConfigAttrib ||
@@ -428,6 +429,8 @@ bool _glfwInitEGL(void)
         extensionSupportedEGL("EGL_KHR_get_all_proc_addresses");
     _glfw.egl.KHR_context_flush_control =
         extensionSupportedEGL("EGL_KHR_context_flush_control");
+    _glfw.egl.EXT_present_opaque =
+        extensionSupportedEGL("EGL_EXT_present_opaque");
 
     return true;
 }
@@ -598,6 +601,11 @@ bool _glfwCreateContextEGL(_GLFWwindow* window,
         if (_glfw.egl.KHR_gl_colorspace)
             setAttrib(EGL_GL_COLORSPACE_KHR, EGL_GL_COLORSPACE_SRGB_KHR);
     }
+    // Disabled because it prevents transparency from working on NVIDIA drivers under Wayland
+    // https://github.com/kovidgoyal/kitty/issues/5479
+    // We anyway dont use the alpha bits for anything.
+    /* if (_glfw.egl.EXT_present_opaque) */
+    /*     setAttrib(EGL_PRESENT_OPAQUE_EXT, !fbconfig->transparent); */
 
     setAttrib(EGL_NONE, EGL_NONE);
 

glfw/egl_context.h

@@ -132,6 +132,7 @@ typedef EGLBoolean (EGLAPIENTRY * PFN_eglMakeCurrent)(EGLDisplay,EGLSurface,EGLS
 typedef EGLBoolean (EGLAPIENTRY * PFN_eglSwapBuffers)(EGLDisplay,EGLSurface);
 typedef EGLBoolean (EGLAPIENTRY * PFN_eglSwapInterval)(EGLDisplay,EGLint);
 typedef const char* (EGLAPIENTRY * PFN_eglQueryString)(EGLDisplay,EGLint);
+typedef const char* (EGLAPIENTRY * PFN_eglQuerySurface)(EGLDisplay,EGLSurface,EGLint,EGLint*);
 typedef GLFWglproc (EGLAPIENTRY * PFN_eglGetProcAddress)(const char*);
 #define eglGetConfigAttrib _glfw.egl.GetConfigAttrib
 #define eglGetConfigs _glfw.egl.GetConfigs
@@ -149,6 +150,7 @@ typedef GLFWglproc (EGLAPIENTRY * PFN_eglGetProcAddress)(const char*);
 #define eglSwapBuffers _glfw.egl.SwapBuffers
 #define eglSwapInterval _glfw.egl.SwapInterval
 #define eglQueryString _glfw.egl.QueryString
+#define eglQuerySurface _glfw.egl.QuerySurface
 #define eglGetProcAddress _glfw.egl.GetProcAddress
 
 typedef EGLDisplay (EGLAPIENTRY * PFNEGLGETPLATFORMDISPLAYEXTPROC)(EGLenum,void*,const EGLint*);
@@ -160,11 +162,11 @@ typedef EGLSurface (EGLAPIENTRY * PFNEGLCREATEPLATFORMWINDOWSURFACEEXTPROC)(EGLD
 //
 typedef struct _GLFWcontextEGL
 {
-   EGLConfig        config;
+    EGLConfig        config;
-   EGLContext       handle;
+    EGLContext       handle;
-   EGLSurface       surface;
+    EGLSurface       surface;
 
-   void*            client;
+    void*            client;
 
 } _GLFWcontextEGL;
 
@@ -186,6 +188,7 @@ typedef struct _GLFWlibraryEGL
     bool            EXT_platform_base;
     bool            EXT_platform_x11;
     bool            EXT_platform_wayland;
+    bool            EXT_present_opaque;
     bool            ANGLE_platform_angle;
     bool            ANGLE_platform_angle_opengl;
     bool            ANGLE_platform_angle_d3d;
@@ -210,6 +213,7 @@ typedef struct _GLFWlibraryEGL
     PFN_eglSwapBuffers          SwapBuffers;
     PFN_eglSwapInterval         SwapInterval;
     PFN_eglQueryString          QueryString;
+    PFN_eglQuerySurface         QuerySurface;
     PFN_eglGetProcAddress       GetProcAddress;
 
     PFNEGLGETPLATFORMDISPLAYEXTPROC GetPlatformDisplayEXT;

glfw/glfw.py

@@ -14,6 +14,10 @@ is_openbsd = 'openbsd' in _plat
 base = os.path.dirname(os.path.abspath(__file__))
 
 
+def null_func() -> None:
+    return None
+
+
 class CompileKey(NamedTuple):
     src: str
     dest: str
@@ -23,7 +27,7 @@ class Command(NamedTuple):
     desc: str
     cmd: Sequence[str]
     is_newer_func: Callable[[], bool]
-    on_success: Callable[[], None] = lambda: None
+    on_success: Callable[[], None] = null_func
     key: Optional[CompileKey] = None
     keyfile: Optional[str] = None
 
@@ -37,6 +41,7 @@ class Env:
     library_paths: Dict[str, List[str]] = {}
     ldpaths: List[str] = []
     ccver: Tuple[int, int]
+    vcs_rev: str = ''
 
     # glfw stuff
     all_headers: List[str] = []
@@ -48,11 +53,13 @@ class Env:
 
     def __init__(
         self, cc: List[str] = [], cppflags: List[str] = [], cflags: List[str] = [], ldflags: List[str] = [],
-        library_paths: Dict[str, List[str]] = {}, ldpaths: Optional[List[str]] = None, ccver: Tuple[int, int] = (0, 0)
+        library_paths: Dict[str, List[str]] = {}, ldpaths: Optional[List[str]] = None, ccver: Tuple[int, int] = (0, 0),
+        vcs_rev: str = ''
     ):
         self.cc, self.cppflags, self.cflags, self.ldflags, self.library_paths = cc, cppflags, cflags, ldflags, library_paths
         self.ldpaths = ldpaths or []
         self.ccver = ccver
+        self.vcs_rev = vcs_rev
 
     def copy(self) -> 'Env':
         ans = Env(self.cc, list(self.cppflags), list(self.cflags), list(self.ldflags), dict(self.library_paths), list(self.ldpaths), self.ccver)
@@ -62,6 +69,7 @@ class Env:
         ans.wayland_scanner = self.wayland_scanner
         ans.wayland_scanner_code = self.wayland_scanner_code
         ans.wayland_protocols = self.wayland_protocols
+        ans.vcs_rev = self.vcs_rev
         return ans
 
 
@@ -111,7 +119,7 @@ def init_env(
 
     elif module == 'cocoa':
         ans.cppflags.append('-DGL_SILENCE_DEPRECATION')
-        for f_ in 'Cocoa IOKit CoreFoundation CoreVideo'.split():
+        for f_ in 'Cocoa IOKit CoreFoundation CoreVideo UniformTypeIdentifiers'.split():
             ans.ldpaths.extend(('-framework', f_))
 
     elif module == 'wayland':
@@ -172,6 +180,8 @@ class Arg:
         while self.name.startswith('*'):
             self.name = self.name[1:]
             self.type = self.type + '*'
+        if '[' in self.name:
+            self.type += '[' + self.name.partition('[')[-1]
 
     def __repr__(self) -> str:
         return f'Arg({self.type}, {self.name})'
@@ -233,7 +243,7 @@ def generate_wrappers(glfw_header: str) -> None:
     void* glfwGetNSGLContext(GLFWwindow *window)
     uint32_t glfwGetCocoaMonitor(GLFWmonitor* monitor)
     GLFWcocoatextinputfilterfun glfwSetCocoaTextInputFilter(GLFWwindow* window, GLFWcocoatextinputfilterfun callback)
-    GLFWhandlefileopen glfwSetCocoaFileOpenCallback(GLFWhandlefileopen callback)
+    GLFWhandleurlopen glfwSetCocoaURLOpenCallback(GLFWhandleurlopen callback)
     GLFWcocoatogglefullscreenfun glfwSetCocoaToggleFullscreenIntercept(GLFWwindow *window, GLFWcocoatogglefullscreenfun callback)
     GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback)
     GLFWapplicationwillfinishlaunchingfun glfwSetApplicationWillFinishLaunching(GLFWapplicationwillfinishlaunchingfun callback)
@@ -245,11 +255,15 @@ def generate_wrappers(glfw_header: str) -> None:
     const char* glfwGetPrimarySelectionString(GLFWwindow* window, void)
     int glfwGetNativeKeyForName(const char* key_name, int case_sensitive)
     void glfwRequestWaylandFrameEvent(GLFWwindow *handle, unsigned long long id, GLFWwaylandframecallbackfunc callback)
+    void glfwWaylandActivateWindow(GLFWwindow *handle, const char *activation_token)
+    void glfwWaylandRunWithActivationToken(GLFWwindow *handle, GLFWactivationcallback cb, void *cb_data)
     bool glfwWaylandSetTitlebarColor(GLFWwindow *handle, uint32_t color, bool use_system_color)
     unsigned long long glfwDBusUserNotify(const char *app_name, const char* icon, const char *summary, const char *body, \
 const char *action_text, int32_t timeout, GLFWDBusnotificationcreatedfun callback, void *data)
     void glfwDBusSetUserNotificationHandler(GLFWDBusnotificationactivatedfun handler)
     int glfwSetX11LaunchCommand(GLFWwindow *handle, char **argv, int argc)
+    void glfwSetX11WindowAsDock(int32_t x11_window_id)
+    void glfwSetX11WindowStrut(int32_t x11_window_id, uint32_t dimensions[12])
 '''.splitlines():
         if line:
             functions.append(Function(line.strip(), check_fail=False))
@@ -277,7 +291,7 @@ const char *action_text, int32_t timeout, GLFWDBusnotificationcreatedfun callbac
 
 typedef int (* GLFWcocoatextinputfilterfun)(int,int,unsigned int,unsigned long);
 typedef bool (* GLFWapplicationshouldhandlereopenfun)(int);
-typedef bool (* GLFWhandlefileopen)(const char*);
+typedef bool (* GLFWhandleurlopen)(const char*);
 typedef void (* GLFWapplicationwillfinishlaunchingfun)(void);
 typedef bool (* GLFWcocoatogglefullscreenfun)(GLFWwindow*);
 typedef void (* GLFWcocoarenderframefun)(GLFWwindow*);
@@ -292,6 +306,8 @@ const char* load_glfw(const char* path);
         f.write(header)
 
     code = '''
+// generated by glfw.py DO NOT edit
+
 #define GFW_EXTERN
 #include "data-types.h"
 #include "glfw-wrapper.h"

glfw/glfw3.h

@@ -512,6 +512,7 @@ typedef enum {
  *  GLFW_LOCK_KEY_MODS input mode is set.
  */
 #define GLFW_MOD_NUM_LOCK        0x0080
+#define GLFW_MOD_LAST            GLFW_MOD_NUM_LOCK
 #define GLFW_LOCK_MASK           (GLFW_MOD_NUM_LOCK | GLFW_MOD_CAPS_LOCK)
 
 /*! @} */
@@ -1024,6 +1025,16 @@ typedef enum GLFWMouseButton {
  *  [window hint](@ref GLFW_COCOA_GRAPHICS_SWITCHING_hint).
  */
 #define GLFW_COCOA_GRAPHICS_SWITCHING 0x00023003
+/*! @brief macOS specific
+ *  [window hint](@ref GLFW_COCOA_COLOR_SPACE_hint).
+ */
+#define GLFW_COCOA_COLOR_SPACE 0x00023004
+typedef enum {
+    DEFAULT_COLORSPACE = 0,
+    SRGB_COLORSPACE = 1,
+    DISPLAY_P3_COLORSPACE = 2,
+} GlfwCocoaColorSpaces;
+
 /*! @brief X11 specific
  *  [window hint](@ref GLFW_X11_CLASS_NAME_hint).
  */
@@ -1206,7 +1217,8 @@ typedef enum {
 typedef enum {
     GLFW_IME_NONE,
     GLFW_IME_PREEDIT_CHANGED,
-    GLFW_IME_COMMIT_TEXT
+    GLFW_IME_COMMIT_TEXT,
+    GLFW_IME_WAYLAND_DONE_EVENT,
 } GLFWIMEState;
 
 typedef enum {
@@ -1356,6 +1368,22 @@ typedef void (* GLFWwindowclosefun)(GLFWwindow*);
  */
 typedef void (* GLFWapplicationclosefun)(int);
 
+/*! @brief The function pointer type for system color theme change callbacks.
+ *
+ *  This is the function pointer type for system color theme changes.
+ *  @code
+ *  void function_name(int theme_type)
+ *  @endcode
+ *
+ *  @param[in] theme_type 0 for unknown, 1 for dark and 2 for light
+ *
+ *  @sa @ref glfwSetSystemColorThemeChangeCallback
+ *
+ *  @ingroup window
+ */
+typedef void (* GLFWsystemcolorthemechangefun)(int);
+
+
 /*! @brief The function pointer type for window content refresh callbacks.
  *
  *  This is the function pointer type for window content refresh callbacks.
@@ -1704,7 +1732,23 @@ typedef void (* GLFWjoystickfun)(int,int);
 
 typedef void (* GLFWuserdatafun)(unsigned long long, void*);
 typedef void (* GLFWtickcallback)(void*);
+typedef void (* GLFWactivationcallback)(GLFWwindow *window, const char *token, void *data);
 typedef bool (* GLFWdrawtextfun)(GLFWwindow *window, const char *text, uint32_t fg, uint32_t bg, uint8_t *output_buf, size_t width, size_t height, float x_offset, float y_offset, size_t right_margin);
+typedef char* (* GLFWcurrentselectionfun)(void);
+typedef bool (* GLFWhascurrentselectionfun)(void);
+typedef void (* GLFWclipboarddatafreefun)(void* data);
+typedef struct GLFWDataChunk {
+    const char *data;
+    size_t sz;
+    GLFWclipboarddatafreefun free;
+    void *iter, *free_data;
+} GLFWDataChunk;
+typedef enum {
+    GLFW_CLIPBOARD, GLFW_PRIMARY_SELECTION
+} GLFWClipboardType;
+typedef GLFWDataChunk (* GLFWclipboarditerfun)(const char *mime_type, void *iter, GLFWClipboardType ctype);
+typedef bool (* GLFWclipboardwritedatafun)(void *object, const char *data, size_t sz);
+typedef bool (* GLFWimecursorpositionfun)(GLFWwindow *window, GLFWIMEUpdateEvent *ev);
 
 /*! @brief Video mode type.
  *
@@ -1862,6 +1906,9 @@ GLFWAPI unsigned long long glfwAddTimer(monotonic_t interval, bool repeats, GLFW
 GLFWAPI void glfwUpdateTimer(unsigned long long timer_id, monotonic_t interval, bool enabled);
 GLFWAPI void glfwRemoveTimer(unsigned long long);
 GLFWAPI GLFWdrawtextfun glfwSetDrawTextFunction(GLFWdrawtextfun function);
+GLFWAPI GLFWcurrentselectionfun glfwSetCurrentSelectionCallback(GLFWcurrentselectionfun callback);
+GLFWAPI GLFWhascurrentselectionfun glfwSetHasCurrentSelectionCallback(GLFWhascurrentselectionfun callback);
+GLFWAPI GLFWimecursorpositionfun glfwSetIMECursorPositionCallback(GLFWimecursorpositionfun callback);
 
 /*! @brief Terminates the GLFW library.
  *
@@ -2757,6 +2804,7 @@ GLFWAPI void glfwWindowHintString(int hint, const char* value);
 GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share);
 GLFWAPI bool glfwToggleFullscreen(GLFWwindow *window, unsigned int flags);
 GLFWAPI bool glfwIsFullscreen(GLFWwindow *window, unsigned int flags);
+GLFWAPI bool glfwAreSwapsAllowed(const GLFWwindow* window);
 
 /*! @brief Destroys the specified window and its context.
  *
@@ -3874,6 +3922,8 @@ GLFWAPI GLFWwindowsizefun glfwSetWindowSizeCallback(GLFWwindow* window, GLFWwind
  */
 GLFWAPI GLFWwindowclosefun glfwSetWindowCloseCallback(GLFWwindow* window, GLFWwindowclosefun callback);
 GLFWAPI GLFWapplicationclosefun glfwSetApplicationCloseCallback(GLFWapplicationclosefun callback);
+GLFWAPI GLFWsystemcolorthemechangefun glfwSetSystemColorThemeChangeCallback(GLFWsystemcolorthemechangefun callback);
+GLFWAPI int glfwGetCurrentSystemColorTheme(void);
 
 /*! @brief Sets the refresh callback for the specified window.
  *
@@ -5205,64 +5255,8 @@ GLFWAPI const char* glfwGetGamepadName(int jid);
  */
 GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state);
 
-/*! @brief Sets the clipboard to the specified string.
+GLFWAPI void glfwSetClipboardDataTypes(GLFWClipboardType clipboard_type, const char* const *mime_types, size_t num_mime_types, GLFWclipboarditerfun get_iter);
- *
+GLFWAPI void glfwGetClipboard(GLFWClipboardType clipboard_type, const char* mime_type, GLFWclipboardwritedatafun write_data, void *object);
- *  This function sets the system clipboard to the specified, UTF-8 encoded
- *  string.
- *
- *  @param[in] window Deprecated.  Any valid window or `NULL`.
- *  @param[in] string A UTF-8 encoded string.
- *
- *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
- *  GLFW_PLATFORM_ERROR.
- *
- *  @remark @wayland Clipboard is currently unimplemented.
- *
- *  @pointer_lifetime The specified string is copied before this function
- *  returns.
- *
- *  @thread_safety This function must only be called from the main thread.
- *
- *  @sa @ref clipboard
- *  @sa @ref glfwGetClipboardString
- *
- *  @since Added in version 3.0.
- *
- *  @ingroup input
- */
-GLFWAPI void glfwSetClipboardString(GLFWwindow* window, const char* string);
-
-/*! @brief Returns the contents of the clipboard as a string.
- *
- *  This function returns the contents of the system clipboard, if it contains
- *  or is convertible to a UTF-8 encoded string.  If the clipboard is empty or
- *  if its contents cannot be converted, `NULL` is returned and a @ref
- *  GLFW_FORMAT_UNAVAILABLE error is generated.
- *
- *  @param[in] window Deprecated.  Any valid window or `NULL`.
- *  @return The contents of the clipboard as a UTF-8 encoded string, or `NULL`
- *  if an [error](@ref error_handling) occurred.
- *
- *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
- *  GLFW_PLATFORM_ERROR.
- *
- *  @remark @wayland Clipboard is currently unimplemented.
- *
- *  @pointer_lifetime The returned string is allocated and freed by GLFW.  You
- *  should not free it yourself.  It is valid until the next call to @ref
- *  glfwGetClipboardString or @ref glfwSetClipboardString, or until the library
- *  is terminated.
- *
- *  @thread_safety This function must only be called from the main thread.
- *
- *  @sa @ref clipboard
- *  @sa @ref glfwSetClipboardString
- *
- *  @since Added in version 3.0.
- *
- *  @ingroup input
- */
-GLFWAPI const char* glfwGetClipboardString(GLFWwindow* window);
 
 /*! @brief Returns the GLFW time.
  *

glfw/ibus_glfw.c

@@ -283,29 +283,35 @@ static const char*
 get_ibus_address_file_name(void) {
     const char *addr;
     static char ans[PATH_MAX];
+    static char display[64] = {0};
     addr = getenv("IBUS_ADDRESS");
     int offset = 0;
     if (addr && addr[0]) {
         memcpy(ans, addr, GLFW_MIN(strlen(addr), sizeof(ans)));
         return ans;
     }
-
+    const char* disp_num = NULL;
-    const char *de = getenv("DISPLAY");
+    const char *host = "unix";
-    if (!de || !de[0]) de = ":0.0";
+    // See https://github.com/ibus/ibus/commit/8ce25208c3f4adfd290a032c6aa739d2b7580eb1 for why we need this dance.
-    char *display = _glfw_strdup(de);
+    const char *de = getenv("WAYLAND_DISPLAY");
-    const char *host = display;
+    if (de) {
-    char *disp_num  = strrchr(display, ':');
+        disp_num = de;
-    char *screen_num = strrchr(display, '.');
+    } else {
-
+        const char *de = getenv("DISPLAY");
-    if (!disp_num) {
+        if (!de || !de[0]) de = ":0.0";
-        _glfwInputError(GLFW_PLATFORM_ERROR, "Could not get IBUS address file name as DISPLAY env var has no colon");
+        strncpy(display, de, sizeof(display) - 1);
-        free(display);
+        char *dnum = strrchr(display, ':');
-        return NULL;
+        if (!dnum) {
+            _glfwInputError(GLFW_PLATFORM_ERROR, "Could not get IBUS address file name as DISPLAY env var has no colon");
+            return NULL;
+        }
+        char *screen_num = strrchr(display, '.');
+        *dnum = 0;
+        dnum++;
+        if (screen_num) *screen_num = 0;
+        if (*display) host = display;
+        disp_num = dnum;
     }
-    *disp_num = 0;
-    disp_num++;
-    if (screen_num) *screen_num = 0;
-    if (!*host) host = "unix";
 
     memset(ans, 0, sizeof(ans));
     const char *conf_env = getenv("XDG_CONFIG_HOME");
@@ -315,7 +321,6 @@ get_ibus_address_file_name(void) {
         conf_env = getenv("HOME");
         if (!conf_env || !conf_env[0]) {
             _glfwInputError(GLFW_PLATFORM_ERROR, "Could not get IBUS address file name as no HOME env var is set");
-            free(display);
             return NULL;
         }
         offset = snprintf(ans, sizeof(ans), "%s/.config", conf_env);
@@ -323,7 +328,6 @@ get_ibus_address_file_name(void) {
     char *key = dbus_get_local_machine_id();
     snprintf(ans + offset, sizeof(ans) - offset, "/ibus/bus/%s-%s-%s", key, host, disp_num);
     dbus_free(key);
-    free(display);
     return ans;
 }
 
@@ -383,12 +387,12 @@ input_context_created(DBusMessage *msg, const char* errmsg, void *data) {
     enum Capabilities caps = IBUS_CAP_FOCUS | IBUS_CAP_PREEDIT_TEXT;
     if (!glfw_dbus_call_method_no_reply(ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, "SetCapabilities", DBUS_TYPE_UINT32, &caps, DBUS_TYPE_INVALID)) return;
     ibus->ok = true;
-    glfw_ibus_set_focused(ibus, false);
+    glfw_ibus_set_focused(ibus, _glfwFocusedWindow() != NULL);
     glfw_ibus_set_cursor_geometry(ibus, 0, 0, 0, 0);
     debug("Connected to IBUS daemon for IME input management\n");
 }
 
-bool
+static bool
 setup_connection(_GLFWIBUSData *ibus) {
     const char *client_name = "GLFW_Application";
     const char *address_file_name = get_ibus_address_file_name();

glfw/init.c

@@ -68,6 +68,8 @@ static void terminate(void)
     int i;
 
     memset(&_glfw.callbacks, 0, sizeof(_glfw.callbacks));
+    _glfw_free_clipboard_data(&_glfw.clipboard);
+    _glfw_free_clipboard_data(&_glfw.primary);
 
     while (_glfw.windowListHead)
         glfwDestroyWindow((GLFWwindow*) _glfw.windowListHead);
@@ -380,9 +382,38 @@ GLFWAPI GLFWapplicationclosefun glfwSetApplicationCloseCallback(GLFWapplicationc
     return cbfun;
 }
 
+GLFWAPI GLFWapplicationclosefun glfwSetSystemColorThemeChangeCallback(GLFWsystemcolorthemechangefun cbfun)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    _GLFW_SWAP_POINTERS(_glfw.callbacks.system_color_theme_change, cbfun);
+    return cbfun;
+}
+
+
 GLFWAPI GLFWdrawtextfun glfwSetDrawTextFunction(GLFWdrawtextfun cbfun)
 {
     _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
     _GLFW_SWAP_POINTERS(_glfw.callbacks.draw_text, cbfun);
     return cbfun;
 }
+
+GLFWAPI GLFWcurrentselectionfun glfwSetCurrentSelectionCallback(GLFWcurrentselectionfun cbfun)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    _GLFW_SWAP_POINTERS(_glfw.callbacks.get_current_selection, cbfun);
+    return cbfun;
+}
+
+GLFWAPI GLFWhascurrentselectionfun glfwSetHasCurrentSelectionCallback(GLFWhascurrentselectionfun cbfun)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    _GLFW_SWAP_POINTERS(_glfw.callbacks.has_current_selection, cbfun);
+    return cbfun;
+}
+
+GLFWAPI GLFWimecursorpositionfun glfwSetIMECursorPositionCallback(GLFWimecursorpositionfun cbfun)
+{
+    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    _GLFW_SWAP_POINTERS(_glfw.callbacks.get_ime_cursor_position, cbfun);
+    return cbfun;
+}

glfw/input.c

@@ -1526,36 +1526,41 @@ GLFWAPI int glfwGetGamepadState(int jid, GLFWgamepadstate* state)
     return true;
 }
 
-GLFWAPI void glfwSetClipboardString(GLFWwindow* handle UNUSED, const char* string)
+void _glfw_free_clipboard_data(_GLFWClipboardData *cd) {
-{
+    if (cd->mime_types) {
-    assert(string != NULL);
+        for (size_t i = 0; i < cd->num_mime_types; i++) free((void*)cd->mime_types[i]);
+        free((void*)cd->mime_types);
+    }
+    memset(cd, 0, sizeof(cd[0]));
+}
 
+GLFWAPI void glfwGetClipboard(GLFWClipboardType clipboard_type, const char* mime_type, GLFWclipboardwritedatafun write_data, void *object) {
     _GLFW_REQUIRE_INIT();
-    _glfwPlatformSetClipboardString(string);
+    _glfwPlatformGetClipboard(clipboard_type, mime_type, write_data, object);
 }
 
-GLFWAPI const char* glfwGetClipboardString(GLFWwindow* handle UNUSED)
+GLFWAPI void glfwSetClipboardDataTypes(GLFWClipboardType clipboard_type, const char* const *mime_types, size_t num_mime_types, GLFWclipboarditerfun get_data) {
-{
+    assert(mime_types != NULL);
-    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
+    assert(get_data != NULL);
-    return _glfwPlatformGetClipboardString();
-}
-
-#if defined(_GLFW_X11) || defined(_GLFW_WAYLAND)
-GLFWAPI void glfwSetPrimarySelectionString(GLFWwindow* handle UNUSED, const char* string)
-{
-    assert(string != NULL);
-
     _GLFW_REQUIRE_INIT();
-    _glfwPlatformSetPrimarySelectionString(string);
+    _GLFWClipboardData *cd = NULL;
+    switch(clipboard_type) {
+        case GLFW_CLIPBOARD: cd = &_glfw.clipboard; break;
+        case GLFW_PRIMARY_SELECTION: cd = &_glfw.primary; break;
+    }
+    _glfw_free_clipboard_data(cd);
+    cd->get_data = get_data;
+    cd->mime_types = calloc(num_mime_types, sizeof(char*));
+    cd->num_mime_types = 0;
+    cd->ctype = clipboard_type;
+    for (size_t i = 0; i < num_mime_types; i++) {
+        if (mime_types[i]) {
+            cd->mime_types[cd->num_mime_types++] = _glfw_strdup(mime_types[i]);
+        }
+    }
+    _glfwPlatformSetClipboard(clipboard_type);
 }
 
-GLFWAPI const char* glfwGetPrimarySelectionString(GLFWwindow* handle UNUSED)
-{
-    _GLFW_REQUIRE_INIT_OR_RETURN(NULL);
-    return _glfwPlatformGetPrimarySelectionString();
-}
-#endif
-
 GLFWAPI monotonic_t glfwGetTime(void)
 {
     _GLFW_REQUIRE_INIT_OR_RETURN(0);

glfw/internal.h

@@ -34,6 +34,9 @@
 #endif
 
 #define arraysz(x) (sizeof(x)/sizeof(x[0]))
+#define MAX(x, y) __extension__ ({ \
+    __typeof__ (x) a = (x); __typeof__ (y) b = (y); \
+        a > b ? a : b;})
 
 #if defined(GLFW_INCLUDE_GLCOREARB) || \
     defined(GLFW_INCLUDE_ES1)       || \
@@ -52,6 +55,8 @@
 #define GLFW_INCLUDE_NONE
 #include "glfw3.h"
 
+#define EGL_PRESENT_OPAQUE_EXT 0x31df
+
 #define _GLFW_INSERT_FIRST      0
 #define _GLFW_INSERT_LAST       1
 
@@ -307,6 +312,7 @@ struct _GLFWwndconfig
     bool          scaleToMonitor;
     struct {
         bool      retina;
+        int       color_space;
         char      frameName[256];
     } ns;
     struct {
@@ -438,6 +444,11 @@ struct _GLFWwindow
     bool                rawMouseMotion;
 
     _GLFWcontext        context;
+#ifdef _GLFW_WAYLAND
+    bool                swaps_disallowed;
+#else
+    const bool                swaps_disallowed;
+#endif
 
     struct {
         GLFWwindowposfun        pos;
@@ -553,6 +564,13 @@ struct _GLFWmutex
     _GLFW_PLATFORM_MUTEX_STATE;
 };
 
+typedef struct _GLFWClipboardData {
+    const char** mime_types;
+    size_t num_mime_types;
+    GLFWclipboarditerfun get_data;
+    GLFWClipboardType ctype;
+} _GLFWClipboardData;
+
 // Library global data
 //
 struct _GLFWlibrary
@@ -567,6 +585,8 @@ struct _GLFWlibrary
         int             refreshRate;
     } hints;
 
+    _GLFWClipboardData primary, clipboard;
+
     _GLFWerror*         errorListHead;
     _GLFWcursor*        cursorListHead;
     _GLFWwindow*        windowListHead;
@@ -612,10 +632,13 @@ struct _GLFWlibrary
         GLFWmonitorfun  monitor;
         GLFWjoystickfun joystick;
         GLFWapplicationclosefun application_close;
+        GLFWsystemcolorthemechangefun system_color_theme_change;
         GLFWdrawtextfun draw_text;
+        GLFWcurrentselectionfun get_current_selection;
+        GLFWhascurrentselectionfun has_current_selection;
+        GLFWimecursorpositionfun get_ime_cursor_position;
     } callbacks;
 
-
     // This is defined in the window API's platform.h
     _GLFW_PLATFORM_LIBRARY_WINDOW_STATE;
     // This is defined in the context API's context.h
@@ -665,12 +688,8 @@ void _glfwPlatformGetVideoMode(_GLFWmonitor* monitor, GLFWvidmode* mode);
 bool _glfwPlatformGetGammaRamp(_GLFWmonitor* monitor, GLFWgammaramp* ramp);
 void _glfwPlatformSetGammaRamp(_GLFWmonitor* monitor, const GLFWgammaramp* ramp);
 
-void _glfwPlatformSetClipboardString(const char* string);
+void _glfwPlatformSetClipboard(GLFWClipboardType t);
-const char* _glfwPlatformGetClipboardString(void);
+void _glfwPlatformGetClipboard(GLFWClipboardType clipboard_type, const char* mime_type, GLFWclipboardwritedatafun write_data, void *object);
-#if defined(_GLFW_X11) || defined(_GLFW_WAYLAND)
-void _glfwPlatformSetPrimarySelectionString(const char* string);
-const char* _glfwPlatformGetPrimarySelectionString(void);
-#endif
 
 bool _glfwPlatformInitJoysticks(void);
 void _glfwPlatformTerminateJoysticks(void);
@@ -846,3 +865,5 @@ void _glfwPlatformUpdateTimer(unsigned long long timer_id, monotonic_t interval,
 void _glfwPlatformRemoveTimer(unsigned long long timer_id);
 
 char* _glfw_strdup(const char* source);
+
+void _glfw_free_clipboard_data(_GLFWClipboardData *cd);

glfw/linux_desktop_settings.c

@@ -10,77 +10,123 @@
 #include <strings.h>
 #include <string.h>
 
-static const char *DESKTOP_SERVICE = "org.freedesktop.portal.Desktop";
+#define DESKTOP_SERVICE "org.freedesktop.portal.Desktop"
-static const char *DESKTOP_PATH = "/org/freedesktop/portal/desktop";
+#define DESKTOP_PATH "/org/freedesktop/portal/desktop"
-static const char *DESKTOP_INTERFACE = "org.freedesktop.portal.Settings";
+#define DESKTOP_INTERFACE "org.freedesktop.portal.Settings"
-static const char *GNOME_DESKTOP_NAMESPACE = "org.gnome.desktop.interface";
+#define GNOME_DESKTOP_NAMESPACE "org.gnome.desktop.interface"
+#define FDO_DESKTOP_NAMESPACE "org.freedesktop.appearance"
+#define FDO_APPEARANCE_KEY "color-scheme"
 
 
-static char theme_name[64] = {0};
+static char theme_name[128] = {0};
 static int theme_size = -1;
-static bool gnome_cursor_theme_read = false, gnome_cursor_size_read = false;
+static uint32_t appearance = 0;
+static bool is_gnome = false;
+static bool cursor_theme_changed = false;
 
-static bool
+int
-parse_dbus_message_for_type(DBusMessage *const reply, const char *errmsg, const int type, void *value) {
+glfw_current_system_color_theme(void) {
-	DBusMessageIter iter[3];
+    return appearance;
-	dbus_message_iter_init(reply, &iter[0]);
-#define FAIL { _glfwInputError(GLFW_PLATFORM_ERROR, "%s", errmsg); return false; }
-	if (dbus_message_iter_get_arg_type(&iter[0]) != DBUS_TYPE_VARIANT) FAIL;
-	dbus_message_iter_recurse(&iter[0], &iter[1]);
-	if (dbus_message_iter_get_arg_type(&iter[1]) != DBUS_TYPE_VARIANT) FAIL;
-	dbus_message_iter_recurse(&iter[1], &iter[2]);
-	if (dbus_message_iter_get_arg_type(&iter[2]) != type) FAIL;
-	dbus_message_iter_get_basic(&iter[2], value);
-	return true;
-#undef FAIL
 }
 
-#define HANDLER(name) void name(DBusMessage *msg, const char* errmsg, void *data) { \
+#define HANDLER(name) static void name(DBusMessage *msg, const char* errmsg, void *data) { \
     (void)data; \
     if (errmsg) { \
         _glfwInputError(GLFW_PLATFORM_ERROR, "%s: failed with error: %s", #name, errmsg); \
         return; \
     }
 
-HANDLER(on_gnome_cursor_theme_read)
+static void
-    const char *name;
+process_fdo_setting(const char *key, DBusMessageIter *value) {
-    if (!parse_dbus_message_for_type(msg, "Failed to get cursor theme name from reply", DBUS_TYPE_STRING, &name)) return;
+    if (strcmp(key, FDO_APPEARANCE_KEY) == 0) {
-    if (name && name[0]) {
+        if (dbus_message_iter_get_arg_type(value) == DBUS_TYPE_UINT32) {
-        gnome_cursor_theme_read = true;
+            dbus_message_iter_get_basic(value, &appearance);
-        strncpy(theme_name, name, sizeof(theme_name) - 1);
+            if (appearance > 2) appearance = 0;
-        if (gnome_cursor_size_read) _glfwPlatformChangeCursorTheme();
+        }
     }
 }
 
-HANDLER(on_gnome_cursor_size_read)
-    int32_t sz;
-    if (!parse_dbus_message_for_type(msg, "Failed to get cursor theme size from reply", DBUS_TYPE_INT32, &sz)) return;
-    gnome_cursor_size_read = true;
-    theme_size = sz;
-    if (gnome_cursor_theme_read) _glfwPlatformChangeCursorTheme();
-}
-#undef HANDLER
-
-
-static bool
-call_read(DBusConnection *session_bus, dbus_pending_callback callback, const char *namespace, const char *key) {
-    return glfw_dbus_call_method_with_reply(
-            session_bus, DESKTOP_SERVICE, DESKTOP_PATH, DESKTOP_INTERFACE, "Read", DBUS_TIMEOUT_USE_DEFAULT,
-            callback, NULL, DBUS_TYPE_STRING, &namespace, DBUS_TYPE_STRING, &key, DBUS_TYPE_INVALID);
-}
-
 static void
-get_from_gnome(void) {
+process_gnome_setting(const char *key, DBusMessageIter *value) {
-    theme_size = 32;
+    if (strcmp(key, "cursor-size") == 0) {
-    DBusConnection *session_bus = glfw_dbus_session_bus();
+        if (dbus_message_iter_get_arg_type(value) == DBUS_TYPE_INT32) {
-    if (session_bus) {
+            int32_t sz;
-        const char *theme_key = "cursor-theme";
+            dbus_message_iter_get_basic(value, &sz);
-        call_read(session_bus, on_gnome_cursor_theme_read, GNOME_DESKTOP_NAMESPACE, theme_key);
+            if (sz > 0 && sz != theme_size) {
-        const char *size_key = "cursor-size";
+                theme_size = sz;
-        call_read(session_bus, on_gnome_cursor_size_read, GNOME_DESKTOP_NAMESPACE, size_key);
+                cursor_theme_changed = true;
+            }
+        }
+    } else if (strcmp(key, "cursor-theme") == 0) {
+        if (dbus_message_iter_get_arg_type(value) == DBUS_TYPE_STRING) {
+            const char *name;
+            dbus_message_iter_get_basic(value, &name);
+            if (name) {
+                strncpy(theme_name, name, sizeof(theme_name) - 1);
+                cursor_theme_changed = true;
+            }
+        }
     }
 }
 
+static void
+process_settings_dict(DBusMessageIter *array_iter, void(process_setting)(const char *, DBusMessageIter*)) {
+    DBusMessageIter item_iter, value_iter;
+    while (dbus_message_iter_get_arg_type(array_iter) == DBUS_TYPE_DICT_ENTRY) {
+        dbus_message_iter_recurse(array_iter, &item_iter);
+        if (dbus_message_iter_get_arg_type(&item_iter) == DBUS_TYPE_STRING) {
+            const char *key;
+            dbus_message_iter_get_basic(&item_iter, &key);
+            if (dbus_message_iter_next(&item_iter) && dbus_message_iter_get_arg_type(&item_iter) == DBUS_TYPE_VARIANT) {
+                dbus_message_iter_recurse(&item_iter, &value_iter);
+                process_setting(key, &value_iter);
+            }
+        }
+        if (!dbus_message_iter_next(array_iter)) break;
+    }
+}
+
+HANDLER(process_desktop_settings)
+    cursor_theme_changed = false;
+    DBusMessageIter root, array, item, settings;
+    dbus_message_iter_init(msg, &root);
+#define die(...) { _glfwInputError(GLFW_PLATFORM_ERROR, __VA_ARGS__); return; }
+    if (dbus_message_iter_get_arg_type(&root) != DBUS_TYPE_ARRAY) die("Reply to request for desktop settings is not an array");
+    dbus_message_iter_recurse(&root, &array);
+    while (dbus_message_iter_get_arg_type(&array) == DBUS_TYPE_DICT_ENTRY) {
+        dbus_message_iter_recurse(&array, &item);
+        if (dbus_message_iter_get_arg_type(&item) == DBUS_TYPE_STRING) {
+            const char *namespace;
+            dbus_message_iter_get_basic(&item, &namespace);
+            if (dbus_message_iter_next(&item) && dbus_message_iter_get_arg_type(&item) == DBUS_TYPE_ARRAY) {
+                dbus_message_iter_recurse(&item, &settings);
+                if (strcmp(namespace, FDO_DESKTOP_NAMESPACE) == 0) {
+                    process_settings_dict(&settings, process_fdo_setting);
+                } else if (is_gnome && strcmp(namespace, GNOME_DESKTOP_NAMESPACE) == 0) {
+                    process_settings_dict(&settings, process_gnome_setting);
+                }
+            }
+        }
+        if (!dbus_message_iter_next(&array)) break;
+    }
+#undef die
+    if (cursor_theme_changed) _glfwPlatformChangeCursorTheme();
+}
+
+#undef HANDLER
+
+static bool
+read_desktop_settings(DBusConnection *session_bus) {
+    DBusMessage *msg = dbus_message_new_method_call(DESKTOP_SERVICE, DESKTOP_PATH, DESKTOP_INTERFACE, "ReadAll");
+    if (!msg) return false;
+    DBusMessageIter iter, array_iter;
+    dbus_message_iter_init_append(msg, &iter);
+    if (!dbus_message_iter_open_container(&iter, DBUS_TYPE_ARRAY, "s", &array_iter)) { dbus_message_unref(msg); return false; }
+    if (!dbus_message_iter_close_container(&iter, &array_iter)) { dbus_message_unref(msg); return false; }
+    bool ok = call_method_with_msg(session_bus, msg, DBUS_TIMEOUT_USE_DEFAULT, process_desktop_settings, NULL);
+    dbus_message_unref(msg);
+    return ok;
+}
 
 void
 glfw_current_cursor_theme(const char **theme, int *size) {
@@ -100,10 +146,58 @@ get_cursor_theme_from_env(void) {
     }
 }
 
+static void
+on_color_scheme_change(DBusMessage *message) {
+    DBusMessageIter iter[2];
+    dbus_message_iter_init (message, &iter[0]);
+    int current_type;
+    while ((current_type = dbus_message_iter_get_arg_type (&iter[0])) != DBUS_TYPE_INVALID) {
+        if (current_type == DBUS_TYPE_VARIANT) {
+            dbus_message_iter_recurse(&iter[0], &iter[1]);
+            if (dbus_message_iter_get_arg_type(&iter[1]) == DBUS_TYPE_UINT32) {
+                uint32_t val = 0;
+                dbus_message_iter_get_basic(&iter[1], &val);
+                if (val > 2) val = 0;
+                if (val != appearance) {
+                    appearance = val;
+                    if (_glfw.callbacks.system_color_theme_change) {
+                        _glfw.callbacks.system_color_theme_change(appearance);
+                    }
+                }
+            }
+            break;
+        }
+        dbus_message_iter_next(&iter[0]);
+    }
+}
+
+static DBusHandlerResult
+setting_changed(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data UNUSED) {
+    /* printf("session_bus settings_changed invoked interface: %s member: %s\n", dbus_message_get_interface(msg), dbus_message_get_member(msg)); */
+    if (dbus_message_is_signal(msg, DESKTOP_INTERFACE, "SettingChanged")) {
+        const char *namespace = NULL, *key = NULL;
+        if (glfw_dbus_get_args(msg, "Failed to get namespace and key from SettingChanged notification signal", DBUS_TYPE_STRING, &namespace, DBUS_TYPE_STRING, &key, DBUS_TYPE_INVALID)) {
+            if (strcmp(namespace, FDO_DESKTOP_NAMESPACE) == 0) {
+                if (strcmp(key, FDO_APPEARANCE_KEY) == 0) {
+                    on_color_scheme_change(msg);
+                }
+            }
+        }
+
+    }
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+}
+
+
 void
 glfw_initialize_desktop_settings(void) {
     get_cursor_theme_from_env();
     const char *desktop = getenv("XDG_CURRENT_DESKTOP");
-    bool is_gnome = desktop && strncasecmp(desktop, "GNOME", sizeof("GNOME") - 1) == 0;
+    is_gnome = desktop && strstr(desktop, "GNOME");
-    if (is_gnome) get_from_gnome();
+    DBusConnection *session_bus = glfw_dbus_session_bus();
+    if (session_bus) {
+        if (!read_desktop_settings(session_bus)) _glfwInputError(GLFW_PLATFORM_ERROR, "Failed to read desktop settings, make sure you have the desktop portal running.");
+        dbus_bus_add_match(session_bus, "type='signal',interface='" DESKTOP_INTERFACE "',member='SettingChanged'", NULL);
+        dbus_connection_add_filter(session_bus, setting_changed, NULL, NULL);
+    }
 }

glfw/linux_desktop_settings.h

@@ -12,3 +12,4 @@
 
 void glfw_initialize_desktop_settings(void);
 void glfw_current_cursor_theme(const char **theme, int *size);
+int glfw_current_system_color_theme(void);

glfw/source-info.json

@@ -77,7 +77,8 @@
       "unstable/idle-inhibit/idle-inhibit-unstable-v1.xml",
       "unstable/xdg-decoration/xdg-decoration-unstable-v1.xml",
       "unstable/primary-selection/primary-selection-unstable-v1.xml",
-      "unstable/text-input/text-input-unstable-v3.xml"
+      "unstable/text-input/text-input-unstable-v3.xml",
+      "staging/xdg-activation/xdg-activation-v1.xml"
     ],
     "sources": [
       "wl_init.c",

glfw/window.c

@@ -71,7 +71,7 @@ void _glfwInputWindowFocus(_GLFWwindow* window, bool focused)
         _glfw.focusedWindowId = window->id;
 }
 
-_GLFWwindow* _glfwFocusedWindow() {
+_GLFWwindow* _glfwFocusedWindow(void) {
     if (_glfw.focusedWindowId) {
         _GLFWwindow *w = _glfw.windowListHead;
         while (w) {
@@ -332,6 +332,8 @@ void glfwDefaultWindowHints(void)
 
     // The default is to use full Retina resolution framebuffers
     _glfw.hints.window.ns.retina = true;
+    // use the default colorspace assigned by the system
+    _glfw.hints.window.ns.color_space = 0;
 }
 
 GLFWAPI void glfwWindowHint(int hint, int value)
@@ -412,6 +414,9 @@ GLFWAPI void glfwWindowHint(int hint, int value)
         case GLFW_COCOA_RETINA_FRAMEBUFFER:
             _glfw.hints.window.ns.retina = value ? true : false;
             return;
+        case GLFW_COCOA_COLOR_SPACE:
+            _glfw.hints.window.ns.color_space = value;
+            return;
         case GLFW_COCOA_GRAPHICS_SWITCHING:
             _glfw.hints.context.nsgl.offline = value ? true : false;
             return;
@@ -1062,6 +1067,10 @@ GLFWAPI bool glfwIsFullscreen(GLFWwindow* wh, unsigned int flags) {
     return _glfwPlatformIsFullscreen((_GLFWwindow*)wh, flags);
 }
 
+GLFWAPI bool glfwAreSwapsAllowed(const GLFWwindow* wh) {
+    return !(((_GLFWwindow*)wh)->swaps_disallowed);
+}
+
 GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* handle, void* pointer)
 {
     _GLFWwindow* window = (_GLFWwindow*) handle;

glfw/wl_client_side_decorations.c

@@ -31,13 +31,13 @@ static void
 build_blur_kernel(kernel_type *blur_kernel, const size_t size, kernel_type sigma) {
     // 1D Normalized Gaussian
     const kernel_type half = size / (kernel_type)2;
-	kernel_type sum = 0;
+    kernel_type sum = 0;
-	for (size_t i = 0; i < size; i++) {
+    for (size_t i = 0; i < size; i++) {
-		kernel_type f = (i - half);
+        kernel_type f = (i - half);
-		blur_kernel[i] = (kernel_type)exp(- f * f / sigma);
+        blur_kernel[i] = (kernel_type)exp(- f * f / sigma);
-		sum += blur_kernel[i];
+        sum += blur_kernel[i];
-	}
+    }
-	for (size_t i = 0; i < size; i++) blur_kernel[i] /= sum;
+    for (size_t i = 0; i < size; i++) blur_kernel[i] /= sum;
 }
 
 static void
@@ -102,13 +102,34 @@ init_buffer_pair(_GLFWWaylandBufferPair *pair, size_t width, size_t height, unsi
     return 2 * pair->size_in_bytes;
 }
 
+static bool
+window_has_buffer(_GLFWwindow *window, struct wl_buffer *q) {
+#define Q(which) if (decs.which.buffer.a == q) { decs.which.buffer.a_needs_to_be_destroyed = false; return true; } if (decs.which.buffer.b == q) { decs.which.buffer.b_needs_to_be_destroyed = false; return true; }
+    Q(left); Q(top); Q(right); Q(bottom);
+#undef Q
+    return false;
+}
+
 static void
-alloc_buffer_pair(_GLFWWaylandBufferPair *pair, struct wl_shm_pool *pool, uint8_t *data, size_t *offset) {
+buffer_release_event(void *data, struct wl_buffer *buffer) {
+    wl_buffer_destroy(buffer);
+    _GLFWwindow *window = _glfwWindowForId((uintptr_t)data);
+    if (window && window_has_buffer(window, buffer)) decs.buffer_destroyed = true;
+}
+
+static struct wl_buffer_listener handle_buffer_events = {.release = buffer_release_event};
+
+static void
+alloc_buffer_pair(uintptr_t window_id, _GLFWWaylandBufferPair *pair, struct wl_shm_pool *pool, uint8_t *data, size_t *offset) {
     pair->data.a = data + *offset;
     pair->a = wl_shm_pool_create_buffer(pool, *offset, pair->width, pair->height, pair->stride, WL_SHM_FORMAT_ARGB8888);
+    pair->a_needs_to_be_destroyed = true;
+    wl_buffer_add_listener(pair->a, &handle_buffer_events, (void*)window_id);
     *offset += pair->size_in_bytes;
     pair->data.b = data + *offset;
     pair->b = wl_shm_pool_create_buffer(pool, *offset, pair->width, pair->height, pair->stride, WL_SHM_FORMAT_ARGB8888);
+    pair->b_needs_to_be_destroyed = true;
+    wl_buffer_add_listener(pair->b, &handle_buffer_events, (void*)window_id);
     *offset += pair->size_in_bytes;
     pair->front = pair->a; pair->back = pair->b;
     pair->data.front = pair->data.a; pair->data.back = pair->data.b;
@@ -287,7 +308,7 @@ create_shm_buffers(_GLFWwindow* window) {
     struct wl_shm_pool* pool = wl_shm_create_pool(_glfw.wl.shm, fd, decs.mapping.size);
     close(fd);
     size_t offset = 0;
-#define a(which) alloc_buffer_pair(&decs.which.buffer, pool, decs.mapping.data, &offset)
+#define a(which) alloc_buffer_pair(window->id, &decs.which.buffer, pool, decs.mapping.data, &offset)
     a(top); a(left); a(bottom); a(right);
 #undef a
     wl_shm_pool_destroy(pool);
@@ -313,8 +334,8 @@ free_csd_surfaces(_GLFWwindow *window) {
 static void
 free_csd_buffers(_GLFWwindow *window) {
 #define d(which) { \
-    if (decs.which.buffer.a) wl_buffer_destroy(decs.which.buffer.a); \
+    if (decs.which.buffer.a_needs_to_be_destroyed && decs.which.buffer.a) wl_buffer_destroy(decs.which.buffer.a); \
-    if (decs.which.buffer.b) wl_buffer_destroy(decs.which.buffer.b); \
+    if (decs.which.buffer.b_needs_to_be_destroyed && decs.which.buffer.b) wl_buffer_destroy(decs.which.buffer.b); \
     memset(&decs.which.buffer, 0, sizeof(_GLFWWaylandBufferPair)); \
 }
     d(left); d(top); d(right); d(bottom);
@@ -337,9 +358,10 @@ create_csd_surfaces(_GLFWwindow *window, _GLFWWaylandCSDEdge *s) {
 }
 
 #define damage_csd(which, xbuffer) \
-    wl_surface_attach(decs.which.surface, xbuffer, 0, 0); \
+    wl_surface_attach(decs.which.surface, (xbuffer), 0, 0); \
     wl_surface_damage(decs.which.surface, 0, 0, decs.which.buffer.width, decs.which.buffer.height); \
-    wl_surface_commit(decs.which.surface)
+    wl_surface_commit(decs.which.surface); \
+    if (decs.which.buffer.a == (xbuffer)) { decs.which.buffer.a_needs_to_be_destroyed = false; } else { decs.which.buffer.b_needs_to_be_destroyed = false; }
 
 bool
 ensure_csd_resources(_GLFWwindow *window) {
@@ -352,11 +374,14 @@ ensure_csd_resources(_GLFWwindow *window) {
         decs.for_window_state.scale != window->wl.scale ||
         !decs.mapping.data
     );
-    const bool needs_update = focus_changed || size_changed || !decs.left.surface;
+    const bool needs_update = focus_changed || size_changed || !decs.left.surface || decs.buffer_destroyed;
+    debug("CSD: old.size: %dx%d new.size: %dx%d needs_update: %d size_changed: %d buffer_destroyed: %d\n",
+            decs.for_window_state.width, decs.for_window_state.height, window->wl.width, window->wl.height, needs_update, size_changed, decs.buffer_destroyed);
     if (!needs_update) return false;
-    if (size_changed) {
+    if (size_changed || decs.buffer_destroyed) {
         free_csd_buffers(window);
         if (!create_shm_buffers(window)) return false;
+        decs.buffer_destroyed = false;
     }
 
     int32_t x, y, scale = window->wl.scale < 1 ? 1 : window->wl.scale;
@@ -409,7 +434,7 @@ change_csd_title(_GLFWwindow *window) {
 
 void
 set_csd_window_geometry(_GLFWwindow *window, int32_t *width, int32_t *height) {
-    bool has_csd = window->decorated && !window->wl.decorations.serverSide && window->wl.decorations.left.surface && !(window->wl.toplevel_states & TOPLEVEL_STATE_FULLSCREEN);
+    bool has_csd = window->decorated && !window->wl.decorations.serverSide && window->wl.decorations.left.surface && !(window->wl.current.toplevel_states & TOPLEVEL_STATE_FULLSCREEN);
     bool size_specified_by_compositor = *width > 0 && *height > 0;
     if (!size_specified_by_compositor) {
         *width = window->wl.user_requested_content_size.width;
@@ -431,8 +456,5 @@ set_titlebar_color(_GLFWwindow *window, uint32_t color, bool use_system_color) {
         decs.use_custom_titlebar_color = use_custom_color;
         decs.titlebar_color = color;
     }
-    if (window->decorated && decs.top.surface) {
+    change_csd_title(window);
-        update_title_bar(window);
-        damage_csd(top, decs.top.buffer.front);
-    }
 }

glfw/wl_init.c

@@ -54,6 +54,8 @@
 #endif
 
 
+#define debug(...) if (_glfw.hints.init.debugRendering) fprintf(stderr, __VA_ARGS__);
+
 static int min(int n1, int n2)
 {
     return n1 < n2 ? n1 : n2;
@@ -96,9 +98,8 @@ static void pointerHandleEnter(void* data UNUSED,
         if (!window)
             return;
     }
-
     window->wl.decorations.focus = focus;
-    _glfw.wl.serial = serial;
+    _glfw.wl.serial = serial; _glfw.wl.input_serial = serial;
     _glfw.wl.pointerFocus = window;
 
     window->wl.hovered = true;
@@ -142,10 +143,19 @@ static void setCursor(GLFWCursorShape shape, _GLFWwindow* window)
 
     if (!image)
         return;
+    if (image->width % scale || image->height % scale) {
+        static uint32_t warned_width = 0, warned_height = 0;
+        if (warned_width != image->width || warned_height != image->height) {
+            _glfwInputError(GLFW_PLATFORM_ERROR, "WARNING: Cursor image size: %dx%d is not a multiple of window scale: %d. This will"
+                    " cause some compositors such as GNOME to crash. See https://github.com/kovidgoyal/kitty/issues/4878", image->width, image->height, scale);
+            warned_width = image->width; warned_height = image->height;
+        }
+    }
 
     buffer = wl_cursor_image_get_buffer(image);
     if (!buffer)
         return;
+    debug("Calling wl_pointer_set_cursor in setCursor with surface: %p\n", (void*)surface);
     wl_pointer_set_cursor(_glfw.wl.pointer, _glfw.wl.serial,
                           surface,
                           image->hotspot_x / scale,
@@ -243,7 +253,7 @@ static void pointerHandleButton(void* data UNUSED,
                     window->wl.decorations.last_click_on_top_decoration_at = monotonic();
                     if (window->wl.decorations.last_click_on_top_decoration_at - last_click_at <= _glfwPlatformGetDoubleClickInterval(window)) {
                         window->wl.decorations.last_click_on_top_decoration_at = 0;
-                        if (window->wl.toplevel_states & TOPLEVEL_STATE_MAXIMIZED)
+                        if (window->wl.current.toplevel_states & TOPLEVEL_STATE_MAXIMIZED)
                             xdg_toplevel_unset_maximized(window->wl.xdg.toplevel);
                         else
                             xdg_toplevel_set_maximized(window->wl.xdg.toplevel);
@@ -301,7 +311,7 @@ static void pointerHandleButton(void* data UNUSED,
     if (window->wl.decorations.focus != CENTRAL_WINDOW)
         return;
 
-    _glfw.wl.serial = serial;
+    _glfw.wl.serial = serial; _glfw.wl.input_serial = serial;
 
     /* Makes left, right and middle 0, 1 and 2. Overall order follows evdev
      * codes. */
@@ -331,20 +341,83 @@ static void pointerHandleAxis(void* data UNUSED,
     assert(axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL ||
            axis == WL_POINTER_AXIS_VERTICAL_SCROLL);
 
-    if (axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL)
+    if (axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL) {
-        x = -wl_fixed_to_double(value);
+        if (window->wl.axis_discrete_count.x) {
-    else if (axis == WL_POINTER_AXIS_VERTICAL_SCROLL)
+            window->wl.axis_discrete_count.x--;
-        y = -wl_fixed_to_double(value);
+            return;
+        }
+        x = -wl_fixed_to_double(value) * (window->wl.scale);
+    }
+    else if (axis == WL_POINTER_AXIS_VERTICAL_SCROLL) {
+        if (window->wl.axis_discrete_count.y) {
+            window->wl.axis_discrete_count.y--;
+            return;
+        }
+        y = -wl_fixed_to_double(value) * (window->wl.scale);
+    }
 
     _glfwInputScroll(window, x, y, 1, _glfw.wl.xkb.states.modifiers);
 }
 
+static void pointerHandleFrame(void* data UNUSED,
+                               struct wl_pointer* pointer UNUSED)
+{
+    _GLFWwindow* window = _glfw.wl.pointerFocus;
+    if (window) {
+        window->wl.axis_discrete_count.x = 0;
+        window->wl.axis_discrete_count.y = 0;
+    }
+}
+
+static void pointerHandleAxisSource(void* data UNUSED,
+                                    struct wl_pointer* pointer UNUSED,
+                                    uint32_t source UNUSED)
+{
+}
+
+static void pointerHandleAxisStop(void *data UNUSED,
+                  struct wl_pointer *wl_pointer UNUSED,
+                  uint32_t time UNUSED,
+                  uint32_t axis UNUSED)
+{
+}
+
+
+static void pointerHandleAxisDiscrete(void *data UNUSED,
+                  struct wl_pointer *wl_pointer UNUSED,
+                  uint32_t axis,
+                  int32_t discrete)
+{
+    _GLFWwindow* window = _glfw.wl.pointerFocus;
+    double x = 0.0, y = 0.0;
+    if (!window)
+        return;
+
+    assert(axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL ||
+           axis == WL_POINTER_AXIS_VERTICAL_SCROLL);
+
+    if (axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL) {
+        x = -discrete;
+        window->wl.axis_discrete_count.x++;
+    }
+    else if (axis == WL_POINTER_AXIS_VERTICAL_SCROLL) {
+        y = -discrete;
+        window->wl.axis_discrete_count.y++;
+    }
+
+    _glfwInputScroll(window, x, y, 0, _glfw.wl.xkb.states.modifiers);
+}
+
 static const struct wl_pointer_listener pointerListener = {
     pointerHandleEnter,
     pointerHandleLeave,
     pointerHandleMotion,
     pointerHandleButton,
     pointerHandleAxis,
+    pointerHandleFrame,
+    pointerHandleAxisSource,
+    pointerHandleAxisStop,
+    pointerHandleAxisDiscrete,
 };
 
 static void keyboardHandleKeymap(void* data UNUSED,
@@ -390,7 +463,7 @@ static void keyboardHandleEnter(void* data UNUSED,
             return;
     }
 
-    _glfw.wl.serial = serial;
+    _glfw.wl.serial = serial; _glfw.wl.input_serial = serial;
     _glfw.wl.keyboardFocusId = window->id;
     _glfwInputWindowFocus(window, true);
     uint32_t* key;
@@ -443,7 +516,7 @@ static void keyboardHandleKey(void* data UNUSED,
         return;
     int action = state == WL_KEYBOARD_KEY_STATE_PRESSED ? GLFW_PRESS : GLFW_RELEASE;
 
-    _glfw.wl.serial = serial;
+    _glfw.wl.serial = serial; _glfw.wl.input_serial = serial;
     glfw_xkb_handle_key_event(window, &_glfw.wl.xkb, key, action);
 
     if (action == GLFW_PRESS && _glfw.wl.keyboardRepeatRate > 0 && glfw_xkb_should_repeat(&_glfw.wl.xkb, key))
@@ -466,7 +539,7 @@ static void keyboardHandleModifiers(void* data UNUSED,
                                     uint32_t modsLocked,
                                     uint32_t group)
 {
-    _glfw.wl.serial = serial;
+    _glfw.wl.serial = serial; _glfw.wl.input_serial = serial;
     glfw_xkb_update_modifiers(&_glfw.wl.xkb, modsDepressed, modsLatched, modsLocked, 0, 0, group);
 }
 
@@ -504,6 +577,7 @@ static void seatHandleCapabilities(void* data UNUSED,
     {
         wl_pointer_destroy(_glfw.wl.pointer);
         _glfw.wl.pointer = NULL;
+        if (_glfw.wl.cursorAnimationTimer) toggleTimer(&_glfw.wl.eventLoopData, _glfw.wl.cursorAnimationTimer, 0);
     }
 
     if ((caps & WL_SEAT_CAPABILITY_KEYBOARD) && !_glfw.wl.keyboard)
@@ -515,6 +589,8 @@ static void seatHandleCapabilities(void* data UNUSED,
     {
         wl_keyboard_destroy(_glfw.wl.keyboard);
         _glfw.wl.keyboard = NULL;
+        _glfw.wl.keyboardFocusId = 0;
+        if (_glfw.wl.keyRepeatInfo.keyRepeatTimer) toggleTimer(&_glfw.wl.eventLoopData, _glfw.wl.keyRepeatInfo.keyRepeatTimer, 0);
     }
 }
 
@@ -571,7 +647,7 @@ static void registryHandleGlobal(void* data UNUSED,
     {
         if (!_glfw.wl.seat)
         {
-            _glfw.wl.seatVersion = min(4, version);
+            _glfw.wl.seatVersion = min(5, version);
             _glfw.wl.seat =
                 wl_registry_bind(registry, name, &wl_seat_interface,
                                  _glfw.wl.seatVersion);
@@ -643,6 +719,9 @@ static void registryHandleGlobal(void* data UNUSED,
             _glfwSetupWaylandPrimarySelectionDevice();
         }
     }
+    else if (strstr(interface, "xdg_activation_v1") != 0) {
+        _glfw.wl.xdg_activation_v1 = wl_registry_bind(registry, name, &xdg_activation_v1_interface, 1);
+    }
 
 }
 
@@ -710,6 +789,10 @@ glfwWaylandCheckForServerSideDecorations(void) {
     return has_ssd ? "YES" : "NO";
 }
 
+GLFWAPI int glfwGetCurrentSystemColorTheme(void) {
+    return glfw_current_system_color_theme();
+}
+
 //////////////////////////////////////////////////////////////////////////
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
@@ -806,6 +889,14 @@ int _glfwPlatformInit(void)
 
 void _glfwPlatformTerminate(void)
 {
+    if (_glfw.wl.activation_requests.array) {
+        for (size_t i=0; i < _glfw.wl.activation_requests.sz; i++) {
+            glfw_wl_xdg_activation_request *r = _glfw.wl.activation_requests.array + i;
+            if (r->callback) r->callback(NULL, NULL, r->callback_data);
+            xdg_activation_token_v1_destroy(r->token);
+        }
+        free(_glfw.wl.activation_requests.array);
+    }
     _glfwTerminateEGL();
     if (_glfw.wl.egl.handle)
     {
@@ -850,6 +941,8 @@ void _glfwPlatformTerminate(void)
         zwp_idle_inhibit_manager_v1_destroy(_glfw.wl.idleInhibitManager);
     if (_glfw.wl.dataSourceForClipboard)
         wl_data_source_destroy(_glfw.wl.dataSourceForClipboard);
+    if (_glfw.wl.dataSourceForPrimarySelection)
+        zwp_primary_selection_source_v1_destroy(_glfw.wl.dataSourceForPrimarySelection);
     for (size_t doi=0; doi < arraysz(_glfw.wl.dataOffers); doi++) {
         if (_glfw.wl.dataOffers[doi].id) {
             destroy_data_offer(&_glfw.wl.dataOffers[doi]);
@@ -863,6 +956,8 @@ void _glfwPlatformTerminate(void)
         zwp_primary_selection_device_v1_destroy(_glfw.wl.primarySelectionDevice);
     if (_glfw.wl.primarySelectionDeviceManager)
         zwp_primary_selection_device_manager_v1_destroy(_glfw.wl.primarySelectionDeviceManager);
+    if (_glfw.wl.xdg_activation_v1)
+        xdg_activation_v1_destroy(_glfw.wl.xdg_activation_v1);
     if (_glfw.wl.registry)
         wl_registry_destroy(_glfw.wl.registry);
     if (_glfw.wl.display)
@@ -871,10 +966,6 @@ void _glfwPlatformTerminate(void)
         wl_display_disconnect(_glfw.wl.display);
     }
     finalizePollData(&_glfw.wl.eventLoopData);
-    free(_glfw.wl.clipboardString); _glfw.wl.clipboardString = NULL;
-    free(_glfw.wl.primarySelectionString); _glfw.wl.primarySelectionString = NULL;
-    free(_glfw.wl.pasteString); _glfw.wl.pasteString = NULL;
-
 }
 
 const char* _glfwPlatformGetVersionString(void)

glfw/wl_platform.h

@@ -58,7 +58,9 @@ typedef VkBool32 (APIENTRY *PFN_vkGetPhysicalDeviceWaylandPresentationSupportKHR
 #include "wayland-pointer-constraints-unstable-v1-client-protocol.h"
 #include "wayland-idle-inhibit-unstable-v1-client-protocol.h"
 #include "wayland-primary-selection-unstable-v1-client-protocol.h"
+#include "wayland-primary-selection-unstable-v1-client-protocol.h"
 #include "wl_text_input.h"
+#include "wayland-xdg-activation-v1-client-protocol.h"
 
 #define _glfw_dlopen(name) dlopen(name, RTLD_LAZY | RTLD_LOCAL)
 #define _glfw_dlclose(handle) dlclose(handle)
@@ -102,6 +104,7 @@ typedef struct _GLFWWaylandBufferPair {
     struct { uint8_t *a, *b, *front, *back; } data;
     bool has_pending_update;
     size_t size_in_bytes, width, height, stride;
+    bool a_needs_to_be_destroyed, b_needs_to_be_destroyed;
 } _GLFWWaylandBufferPair;
 
 typedef struct _GLFWWaylandCSDEdge {
@@ -116,17 +119,29 @@ typedef enum WaylandWindowState {
     TOPLEVEL_STATE_NONE = 0,
     TOPLEVEL_STATE_MAXIMIZED = 1,
     TOPLEVEL_STATE_FULLSCREEN = 2,
-	TOPLEVEL_STATE_RESIZING = 4,
+    TOPLEVEL_STATE_RESIZING = 4,
-	TOPLEVEL_STATE_ACTIVATED = 8,
+    TOPLEVEL_STATE_ACTIVATED = 8,
-	TOPLEVEL_STATE_TILED_LEFT = 16,
+    TOPLEVEL_STATE_TILED_LEFT = 16,
-	TOPLEVEL_STATE_TILED_RIGHT = 32,
+    TOPLEVEL_STATE_TILED_RIGHT = 32,
-	TOPLEVEL_STATE_TILED_TOP = 64,
+    TOPLEVEL_STATE_TILED_TOP = 64,
-	TOPLEVEL_STATE_TILED_BOTTOM = 128,
+    TOPLEVEL_STATE_TILED_BOTTOM = 128,
 } WaylandWindowState;
 
+typedef struct glfw_wl_xdg_activation_request {
+    GLFWid window_id;
+    GLFWactivationcallback callback;
+    void *callback_data;
+    uintptr_t request_id;
+    void *token;
+} glfw_wl_xdg_activation_request;
+
 
 static const WaylandWindowState TOPLEVEL_STATE_DOCKED = TOPLEVEL_STATE_MAXIMIZED | TOPLEVEL_STATE_FULLSCREEN | TOPLEVEL_STATE_TILED_TOP | TOPLEVEL_STATE_TILED_LEFT | TOPLEVEL_STATE_TILED_RIGHT | TOPLEVEL_STATE_TILED_BOTTOM;
 
+enum WaylandWindowPendingState {
+    PENDING_STATE_TOPLEVEL = 1,
+    PENDING_STATE_DECORATION = 2
+};
 
 // Wayland-specific per-window data
 //
@@ -137,6 +152,7 @@ typedef struct _GLFWwindowWayland
     bool                        hovered;
     bool                        transparent;
     struct wl_surface*          surface;
+    bool                        waiting_for_swap_to_commit;
     struct wl_egl_window*       native;
     struct wl_callback*         callback;
 
@@ -168,7 +184,7 @@ typedef struct _GLFWwindowWayland
     struct zwp_idle_inhibitor_v1*          idleInhibitor;
 
     struct {
-        bool serverSide;
+        bool serverSide, buffer_destroyed;
         _GLFWdecorationSideWayland focus;
         _GLFWWaylandCSDEdge top, left, right, bottom;
 
@@ -210,9 +226,20 @@ typedef struct _GLFWwindowWayland
         int32_t width, height;
     } user_requested_content_size;
 
-    uint32_t toplevel_states;
     bool maximize_on_first_show;
+    // counters for ignoring axis events following axis_discrete events in the
+    // same frame along the same axis
+    struct {
+        unsigned int x, y;
+    } axis_discrete_count;
+    bool surface_configured_once;
 
+    uint32_t pending_state;
+    struct {
+        int width, height;
+        uint32_t toplevel_states;
+        uint32_t decoration_mode;
+    } current, pending;
 } _GLFWwindowWayland;
 
 typedef enum _GLFWWaylandOfferType
@@ -261,13 +288,14 @@ typedef struct _GLFWlibraryWayland
     struct zwp_primary_selection_device_manager_v1* primarySelectionDeviceManager;
     struct zwp_primary_selection_device_v1*    primarySelectionDevice;
     struct zwp_primary_selection_source_v1*    dataSourceForPrimarySelection;
+    struct xdg_activation_v1* xdg_activation_v1;
 
     int                         compositorVersion;
     int                         seatVersion;
 
     struct wl_surface*          cursorSurface;
     GLFWCursorShape             cursorPreviousShape;
-    uint32_t                    serial;
+    uint32_t                    serial, input_serial;
 
     int32_t                     keyboardRepeatRate;
     monotonic_t                 keyboardRepeatDelay;
@@ -301,12 +329,14 @@ typedef struct _GLFWlibraryWayland
         PFN_wl_egl_window_resize window_resize;
     } egl;
 
+    struct {
+        glfw_wl_xdg_activation_request *array;
+        size_t capacity, sz;
+    } activation_requests;
+
     EventLoopData eventLoopData;
-    char* pasteString;
-    char* clipboardString;
     size_t dataOffersCounter;
     _GLFWWaylandDataOffer dataOffers[8];
-    char* primarySelectionString;
 } _GLFWlibraryWayland;
 
 // Wayland-specific per-monitor data
@@ -340,6 +370,7 @@ typedef struct _GLFWcursorWayland
 
 
 void _glfwAddOutputWayland(uint32_t name, uint32_t version);
+void _glfwWaylandAfterBufferSwap(_GLFWwindow *window);
 void _glfwSetupWaylandDataDevice(void);
 void _glfwSetupWaylandPrimarySelectionDevice(void);
 void animateCursorImage(id_type timer_id, void *data);

glfw/wl_text_input.c

@@ -9,12 +9,15 @@
 #include "internal.h"
 #include "wayland-text-input-unstable-v3-client-protocol.h"
 #include <stdlib.h>
+#include <string.h>
 #define debug(...) if (_glfw.hints.init.debugKeyboard) printf(__VA_ARGS__);
 
 static struct zwp_text_input_v3*                  text_input;
 static struct zwp_text_input_manager_v3*          text_input_manager;
 static char *pending_pre_edit = NULL;
+static char *current_pre_edit = NULL;
 static char *pending_commit   = NULL;
+static int last_cursor_left = 0, last_cursor_top = 0, last_cursor_width = 0, last_cursor_height = 0;
 uint32_t commit_serial = 0;
 
 static void commit(void) {
@@ -47,7 +50,7 @@ static void
 send_text(const char *text, GLFWIMEState ime_state) {
     _GLFWwindow *w = _glfwFocusedWindow();
     if (w && w->callbacks.keyboard) {
-        GLFWkeyevent fake_ev = {.action = GLFW_PRESS};
+        GLFWkeyevent fake_ev = {.action = text ? GLFW_PRESS : GLFW_RELEASE};
         fake_ev.text = text;
         fake_ev.ime_state = ime_state;
         w->callbacks.keyboard((GLFWwindow*) w, &fake_ev);
@@ -84,15 +87,26 @@ text_input_delete_surrounding_text(
 }
 
 static void
-text_input_done(void *data UNUSED, struct zwp_text_input_v3 *txt_input UNUSED, uint32_t serial UNUSED) {
+text_input_done(void *data UNUSED, struct zwp_text_input_v3 *txt_input UNUSED, uint32_t serial) {
     debug("text-input: done event: serial: %u current_commit_serial: %u\n", serial, commit_serial);
     if (serial != commit_serial) {
-        _glfwInputError(GLFW_PLATFORM_ERROR, "Wayland: text_input_done serial mismatch, expected=%u got=%u\n", commit_serial, serial);
+        if (serial > commit_serial) _glfwInputError(GLFW_PLATFORM_ERROR, "Wayland: text_input_done serial mismatch, expected=%u got=%u\n", commit_serial, serial);
         return;
     }
-    if (pending_pre_edit) {
+
-        send_text(pending_pre_edit, GLFW_IME_PREEDIT_CHANGED);
+    if ((pending_pre_edit == NULL && current_pre_edit == NULL) ||
+        (pending_pre_edit && current_pre_edit && strcmp(pending_pre_edit, current_pre_edit) == 0)) {
         free(pending_pre_edit); pending_pre_edit = NULL;
+    } else {
+        free(current_pre_edit);
+        current_pre_edit = pending_pre_edit;
+        pending_pre_edit = NULL;
+        if (current_pre_edit) {
+            send_text(current_pre_edit, GLFW_IME_PREEDIT_CHANGED);
+        } else {
+            // Clear pre-edit text
+            send_text(NULL, GLFW_IME_WAYLAND_DONE_EVENT);
+        }
     }
     if (pending_commit) {
         send_text(pending_commit, GLFW_IME_COMMIT_TEXT);
@@ -130,6 +144,7 @@ _glfwWaylandDestroyTextInput(void) {
     if (text_input_manager) zwp_text_input_manager_v3_destroy(text_input_manager);
     text_input = NULL; text_input_manager = NULL;
     free(pending_pre_edit); pending_pre_edit = NULL;
+    free(current_pre_edit); current_pre_edit = NULL;
     free(pending_commit); pending_commit = NULL;
 }
 
@@ -139,15 +154,35 @@ _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
     switch(ev->type) {
         case GLFW_IME_UPDATE_FOCUS:
             debug("\ntext-input: updating IME focus state, focused: %d\n", ev->focused);
-            if (ev->focused) zwp_text_input_v3_enable(text_input); else zwp_text_input_v3_disable(text_input);
+            if (ev->focused) {
+                zwp_text_input_v3_enable(text_input);
+                zwp_text_input_v3_set_content_type(text_input, ZWP_TEXT_INPUT_V3_CONTENT_HINT_NONE, ZWP_TEXT_INPUT_V3_CONTENT_PURPOSE_TERMINAL);
+            } else {
+                free(pending_pre_edit); pending_pre_edit = NULL;
+                if (current_pre_edit) {
+                    // Clear pre-edit text
+                    send_text(NULL, GLFW_IME_PREEDIT_CHANGED);
+                    free(current_pre_edit); current_pre_edit = NULL;
+                }
+                if (pending_commit) {
+                    free(pending_commit); pending_commit = NULL;
+                }
+                zwp_text_input_v3_disable(text_input);
+            }
             commit();
             break;
         case GLFW_IME_UPDATE_CURSOR_POSITION: {
             const int scale = w->wl.scale;
             const int left = ev->cursor.left / scale, top = ev->cursor.top / scale, width = ev->cursor.width / scale, height = ev->cursor.height / scale;
-            debug("\ntext-input: updating cursor position: left=%d top=%d width=%d height=%d\n", left, top, width, height);
+            if (left != last_cursor_left || top != last_cursor_top || width != last_cursor_width || height != last_cursor_height) {
-            zwp_text_input_v3_set_cursor_rectangle(text_input, left, top, width, height);
+                last_cursor_left = left;
-            commit();
+                last_cursor_top = top;
+                last_cursor_width = width;
+                last_cursor_height = height;
+                debug("\ntext-input: updating cursor position: left=%d top=%d width=%d height=%d\n", left, top, width, height);
+                zwp_text_input_v3_set_cursor_rectangle(text_input, left, top, width, height);
+                commit();
+            }
         }
             break;
     }

glfw/wl_window.c

@@ -44,6 +44,59 @@
 
 #define debug(...) if (_glfw.hints.init.debugRendering) fprintf(stderr, __VA_ARGS__);
 
+static void
+activation_token_done(void *data, struct xdg_activation_token_v1 *xdg_token, const char *token) {
+    for (size_t i = 0; i < _glfw.wl.activation_requests.sz; i++) {
+        glfw_wl_xdg_activation_request *r = _glfw.wl.activation_requests.array + i;
+        if (r->request_id == (uintptr_t)data) {
+            _GLFWwindow *window = _glfwWindowForId(r->window_id);
+            if (r->callback) r->callback((GLFWwindow*)window, token, r->callback_data);
+            remove_i_from_array(_glfw.wl.activation_requests.array, i, _glfw.wl.activation_requests.sz);
+            break;
+        }
+    }
+    xdg_activation_token_v1_destroy(xdg_token);
+}
+
+
+static const struct
+xdg_activation_token_v1_listener activation_token_listener = {
+    .done = &activation_token_done,
+};
+
+
+static bool
+get_activation_token(
+    _GLFWwindow *window, uint32_t serial, GLFWactivationcallback cb, void *cb_data
+) {
+#define fail(msg) { _glfwInputError(GLFW_PLATFORM_ERROR, msg); if (cb) cb((GLFWwindow*)window, NULL, cb_data); return false; }
+    if (_glfw.wl.xdg_activation_v1 == NULL) fail("Wayland: activation requests not supported by this Wayland compositor");
+    struct xdg_activation_token_v1 *token = xdg_activation_v1_get_activation_token(_glfw.wl.xdg_activation_v1);
+    if (token == NULL) fail("Wayland: failed to create activation request token");
+    if (_glfw.wl.activation_requests.capacity < _glfw.wl.activation_requests.sz + 1) {
+        _glfw.wl.activation_requests.capacity = MAX(64u, _glfw.wl.activation_requests.capacity * 2);
+        _glfw.wl.activation_requests.array = realloc(_glfw.wl.activation_requests.array, _glfw.wl.activation_requests.capacity * sizeof(_glfw.wl.activation_requests.array[0]));
+        if (!_glfw.wl.activation_requests.array) {
+            _glfw.wl.activation_requests.capacity = 0;
+            fail("Wayland: Out of memory while allocation activation request");
+        }
+    }
+    glfw_wl_xdg_activation_request *r = _glfw.wl.activation_requests.array + _glfw.wl.activation_requests.sz++;
+    memset(r, 0, sizeof(*r));
+    static uintptr_t rq = 0;
+    r->window_id = window->id;
+    r->callback = cb; r->callback_data = cb_data;
+    r->request_id = ++rq; r->token = token;
+    if (serial != 0)
+        xdg_activation_token_v1_set_serial(token, serial, _glfw.wl.seat);
+
+    xdg_activation_token_v1_set_surface(token, window->wl.surface);
+    xdg_activation_token_v1_add_listener(token, &activation_token_listener, (void*)r->request_id);
+    xdg_activation_token_v1_commit(token);
+    return true;
+#undef fail
+}
+
 static struct wl_buffer* createShmBuffer(const GLFWimage* image, bool is_opaque, bool init_data)
 {
     struct wl_shm_pool* pool;
@@ -147,6 +200,7 @@ setCursorImage(_GLFWwindow* window, bool on_theme_change) {
         cursorWayland->yhot = image->hotspot_y;
     }
 
+    debug("Calling wl_pointer_set_cursor in setCursorImage with surface: %p\n", (void*)surface);
     wl_pointer_set_cursor(_glfw.wl.pointer, _glfw.wl.serial,
                           surface,
                           cursorWayland->xhot / scale,
@@ -197,8 +251,17 @@ static bool checkScaleChange(_GLFWwindow* window)
     return false;
 }
 
+static void
+commit_window_surface_if_safe(_GLFWwindow *window) {
+    // we only commit if the buffer attached to the surface is the correct size,
+    // which means that at least one frame is drawn after resizeFramebuffer()
+    if (!window->wl.waiting_for_swap_to_commit) {
+        wl_surface_commit(window->wl.surface);
+    }
+}
+
 // Makes the surface considered as XRGB instead of ARGB.
-static void setOpaqueRegion(_GLFWwindow* window)
+static void setOpaqueRegion(_GLFWwindow* window, bool commit_surface)
 {
     struct wl_region* region;
 
@@ -208,7 +271,7 @@ static void setOpaqueRegion(_GLFWwindow* window)
 
     wl_region_add(region, 0, 0, window->wl.width, window->wl.height);
     wl_surface_set_opaque_region(window->wl.surface, region);
-    wl_surface_commit(window->wl.surface);
+    if (commit_surface) commit_window_surface_if_safe(window);
     wl_region_destroy(region);
 }
 
@@ -220,10 +283,21 @@ resizeFramebuffer(_GLFWwindow* window) {
     int scaledHeight = window->wl.height * scale;
     debug("Resizing framebuffer to: %dx%d at scale: %d\n", window->wl.width, window->wl.height, scale);
     wl_egl_window_resize(window->wl.native, scaledWidth, scaledHeight, 0, 0);
-    if (!window->wl.transparent) setOpaqueRegion(window);
+    if (!window->wl.transparent) setOpaqueRegion(window, false);
+    window->wl.waiting_for_swap_to_commit = true;
     _glfwInputFramebufferSize(window, scaledWidth, scaledHeight);
 }
 
+void
+_glfwWaylandAfterBufferSwap(_GLFWwindow* window) {
+    if (window->wl.waiting_for_swap_to_commit) {
+        debug("Waiting for swap to commit: swap has happened\n");
+        window->wl.waiting_for_swap_to_commit = false;
+        // this is not really needed, since I think eglSwapBuffers() calls wl_surface_commit()
+        // but lets be safe. See https://gitlab.freedesktop.org/mesa/mesa/-/blob/main/src/egl/drivers/dri2/platform_wayland.c#L1510
+        wl_surface_commit(window->wl.surface);
+    }
+}
 
 static const char*
 clipboard_mime(void) {
@@ -234,7 +308,7 @@ clipboard_mime(void) {
     return buf;
 }
 
-static void
+static bool
 dispatchChangesAfterConfigure(_GLFWwindow *window, int32_t width, int32_t height) {
     bool size_changed = width != window->wl.width || height != window->wl.height;
     bool scale_changed = checkScaleChange(window);
@@ -246,12 +320,14 @@ dispatchChangesAfterConfigure(_GLFWwindow *window, int32_t width, int32_t height
     }
 
     if (scale_changed) {
-        if (!size_changed)
+        debug("Scale changed to %d in dispatchChangesAfterConfigure\n", window->wl.scale);
-            resizeFramebuffer(window);
+        if (!size_changed) resizeFramebuffer(window);
         _glfwInputWindowContentScale(window, window->wl.scale, window->wl.scale);
     }
 
     _glfwInputWindowDamage(window);
+
+    return size_changed || scale_changed;
 }
 
 static void
@@ -269,24 +345,9 @@ xdgDecorationHandleConfigure(void* data,
                                          uint32_t mode)
 {
     _GLFWwindow* window = data;
-
+    window->wl.pending.decoration_mode = mode;
-    bool has_server_side_decorations = (mode == ZXDG_TOPLEVEL_DECORATION_V1_MODE_SERVER_SIDE);
+    window->wl.pending_state |= PENDING_STATE_DECORATION;
-    debug("XDG decoration configure event received: has_server_side_decorations: %d\n", has_server_side_decorations);
+    debug("XDG decoration configure event received: has_server_side_decorations: %d\n", (mode == ZXDG_TOPLEVEL_DECORATION_V1_MODE_SERVER_SIDE));
-    if (has_server_side_decorations == window->wl.decorations.serverSide) return;
-    window->wl.decorations.serverSide = has_server_side_decorations;
-    int width = window->wl.width, height = window->wl.height;
-    if (window->wl.decorations.serverSide) {
-        free_csd_surfaces(window);
-        height += window->wl.decorations.metrics.visible_titlebar_height;
-    } else {
-        ensure_csd_resources(window);
-    }
-    set_csd_window_geometry(window, &width, &height);
-    dispatchChangesAfterConfigure(window, width, height);
-    ensure_csd_resources(window);
-    wl_surface_commit(window->wl.surface);
-    debug("final window content size: %dx%d\n", window->wl.width, window->wl.height);
-    inform_compositor_of_window_geometry(window, "configure-decorations");
 }
 
 static const struct zxdg_toplevel_decoration_v1_listener xdgDecorationListener = {
@@ -311,6 +372,7 @@ static void surfaceHandleEnter(void *data,
     window->wl.monitors[window->wl.monitorsCount++] = monitor;
 
     if (checkScaleChange(window)) {
+        debug("Scale changed to %d in surface enter event\n", window->wl.scale);
         resizeFramebuffer(window);
         _glfwInputWindowContentScale(window, window->wl.scale, window->wl.scale);
         ensure_csd_resources(window);
@@ -336,6 +398,7 @@ static void surfaceHandleLeave(void *data,
     window->wl.monitors[--window->wl.monitorsCount] = NULL;
 
     if (checkScaleChange(window)) {
+        debug("Scale changed to %d in surface leave event\n", window->wl.scale);
         resizeFramebuffer(window);
         _glfwInputWindowContentScale(window, window->wl.scale, window->wl.scale);
         ensure_csd_resources(window);
@@ -378,9 +441,22 @@ static bool createSurface(_GLFWwindow* window,
 
     wl_surface_set_user_data(window->wl.surface, window);
 
-    window->wl.native = wl_egl_window_create(window->wl.surface,
+    // If we already have been notified of the primary monitor scale, assume
-                                             wndconfig->width,
+    // the window will be created on it and so avoid a rescale roundtrip in the common
-                                             wndconfig->height);
+    // case of the window being shown on the primary monitor or all monitors having the same scale.
+    // If you change this also change get_window_content_scale() in the kitty code.
+    GLFWmonitor* monitor = glfwGetPrimaryMonitor();
+    float xscale = 1.0, yscale = 1.0;
+    int scale = 1;
+    if (monitor) {
+        glfwGetMonitorContentScale(monitor, &xscale, &yscale);
+        // see wl_monitor.c xscale is always == yscale
+        if (xscale <= 0.0001 || xscale != xscale || xscale >= 24) xscale = 1.0;
+        if (xscale > 1) scale = (int)xscale;
+    }
+
+    debug("Creating window at size: %dx%d and scale %d\n", wndconfig->width, wndconfig->height, scale);
+    window->wl.native = wl_egl_window_create(window->wl.surface, wndconfig->width * scale, wndconfig->height * scale);
     if (!window->wl.native)
         return false;
 
@@ -388,11 +464,13 @@ static bool createSurface(_GLFWwindow* window,
     window->wl.height = wndconfig->height;
     window->wl.user_requested_content_size.width = wndconfig->width;
     window->wl.user_requested_content_size.height = wndconfig->height;
-    window->wl.scale = 1;
+
+    window->wl.scale = scale;
 
     if (!window->wl.transparent)
-        setOpaqueRegion(window);
+        setOpaqueRegion(window, false);
 
+    wl_surface_set_buffer_scale(window->wl.surface, scale);
     return true;
 }
 
@@ -416,7 +494,7 @@ static void setFullscreen(_GLFWwindow* window, _GLFWmonitor* monitor, bool on)
 
 bool
 _glfwPlatformIsFullscreen(_GLFWwindow *window, unsigned int flags UNUSED) {
-    return window->wl.toplevel_states & TOPLEVEL_STATE_FULLSCREEN;
+    return window->wl.current.toplevel_states & TOPLEVEL_STATE_FULLSCREEN;
 }
 
 bool
@@ -458,7 +536,7 @@ xdgToplevelHandleConfigure(void* data,
     if (new_states & TOPLEVEL_STATE_RESIZING) {
         if (width) window->wl.user_requested_content_size.width = width;
         if (height) window->wl.user_requested_content_size.height = height;
-        if (!(window->wl.toplevel_states & TOPLEVEL_STATE_RESIZING)) _glfwInputLiveResize(window, true);
+        if (!(window->wl.current.toplevel_states & TOPLEVEL_STATE_RESIZING)) _glfwInputLiveResize(window, true);
     }
     if (width != 0 && height != 0)
     {
@@ -475,16 +553,11 @@ xdgToplevelHandleConfigure(void* data,
             }
         }
     }
-    bool live_resize_done = !(new_states & TOPLEVEL_STATE_RESIZING) && (window->wl.toplevel_states & TOPLEVEL_STATE_RESIZING);
+
-    window->wl.toplevel_states = new_states;
+    window->wl.pending.toplevel_states = new_states;
-    set_csd_window_geometry(window, &width, &height);
+    window->wl.pending.width = width;
-    dispatchChangesAfterConfigure(window, width, height);
+    window->wl.pending.height = height;
-    debug("final window content size: %dx%d\n", window->wl.width, window->wl.height);
+    window->wl.pending_state |= PENDING_STATE_TOPLEVEL;
-    _glfwInputWindowFocus(window, window->wl.toplevel_states & TOPLEVEL_STATE_ACTIVATED);
-    ensure_csd_resources(window);
-    wl_surface_commit(window->wl.surface);
-    inform_compositor_of_window_geometry(window, "configure");
-    if (live_resize_done) _glfwInputLiveResize(window, false);
 }
 
 static void xdgToplevelHandleClose(void* data,
@@ -499,11 +572,66 @@ static const struct xdg_toplevel_listener xdgToplevelListener = {
     xdgToplevelHandleClose
 };
 
-static void xdgSurfaceHandleConfigure(void* data UNUSED,
+static void xdgSurfaceHandleConfigure(void* data,
                                       struct xdg_surface* surface,
                                       uint32_t serial)
 {
+    // The poorly documented pattern Wayland requires is:
+    // 1) ack the configure,
+    // 2) set the window geometry
+    // 3) attach a new buffer of the correct size to the surface
+    // 4) only then commit the surface.
+    // buffer is attached only by eglSwapBuffers,
+    // so we set a flag to not commit the surface till the next swapbuffers. Note that
+    // wl_egl_window_resize() does not actually resize the buffer until the next draw call
+    // or buffer state query.
+    _GLFWwindow* window = data;
     xdg_surface_ack_configure(surface, serial);
+    if (window->wl.pending_state & PENDING_STATE_TOPLEVEL) {
+        uint32_t new_states = window->wl.pending.toplevel_states;
+        int width = window->wl.pending.width;
+        int height = window->wl.pending.height;
+        if (!window->wl.surface_configured_once) {
+            window->swaps_disallowed = false;
+            window->wl.waiting_for_swap_to_commit = true;
+            window->wl.surface_configured_once = true;
+        }
+
+        if (new_states != window->wl.current.toplevel_states ||
+                width != window->wl.current.width ||
+                height != window->wl.current.height) {
+
+            bool live_resize_done = !(new_states & TOPLEVEL_STATE_RESIZING) && (window->wl.current.toplevel_states & TOPLEVEL_STATE_RESIZING);
+            window->wl.current.toplevel_states = new_states;
+            window->wl.current.width = width;
+            window->wl.current.height = height;
+            _glfwInputWindowFocus(window, window->wl.current.toplevel_states & TOPLEVEL_STATE_ACTIVATED);
+            if (live_resize_done) _glfwInputLiveResize(window, false);
+        }
+    }
+
+    if (window->wl.pending_state & PENDING_STATE_DECORATION) {
+        uint32_t mode = window->wl.pending.decoration_mode;
+        bool has_server_side_decorations = (mode == ZXDG_TOPLEVEL_DECORATION_V1_MODE_SERVER_SIDE);
+        window->wl.decorations.serverSide = has_server_side_decorations;
+        window->wl.current.decoration_mode = mode;
+    }
+
+    if (window->wl.pending_state) {
+        int width = window->wl.pending.width, height = window->wl.pending.height;
+        set_csd_window_geometry(window, &width, &height);
+        bool resized = dispatchChangesAfterConfigure(window, width, height);
+        if (window->wl.decorations.serverSide || window->monitor || window->wl.current.toplevel_states & TOPLEVEL_STATE_FULLSCREEN) {
+            free_csd_surfaces(window);
+        } else {
+            ensure_csd_resources(window);
+        }
+        debug("final window content size: %dx%d resized: %d\n", width, height, resized);
+    }
+
+    inform_compositor_of_window_geometry(window, "configure");
+    commit_window_surface_if_safe(window);
+    window->wl.pending_state = 0;
 }
 
 static const struct xdg_surface_listener xdgSurfaceListener = {
@@ -746,6 +874,7 @@ int _glfwPlatformCreateWindow(_GLFWwindow* window,
     initialize_csd_metrics(window);
     window->wl.transparent = fbconfig->transparent;
     strncpy(window->wl.appId, wndconfig->wl.appId, sizeof(window->wl.appId));
+    window->swaps_disallowed = true;
 
     if (!createSurface(window, wndconfig))
         return false;
@@ -901,7 +1030,7 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
         window->wl.width = w; window->wl.height = h;
         resizeFramebuffer(window);
         ensure_csd_resources(window);
-        wl_surface_commit(window->wl.surface);
+        commit_window_surface_if_safe(window);
         inform_compositor_of_window_geometry(window, "SetWindowSize");
     }
 }
@@ -918,7 +1047,7 @@ void _glfwPlatformSetWindowSizeLimits(_GLFWwindow* window,
             maxwidth = maxheight = 0;
         xdg_toplevel_set_min_size(window->wl.xdg.toplevel, minwidth, minheight);
         xdg_toplevel_set_max_size(window->wl.xdg.toplevel, maxwidth, maxheight);
-        wl_surface_commit(window->wl.surface);
+        commit_window_surface_if_safe(window);
     }
 }
 
@@ -955,7 +1084,7 @@ void _glfwPlatformGetWindowFrameSize(_GLFWwindow* window,
     if (window->decorated && !window->monitor && !window->wl.decorations.serverSide)
     {
         if (top)
-            *top = window->wl.decorations.metrics.top;
+            *top = window->wl.decorations.metrics.top - window->wl.decorations.metrics.visible_titlebar_height;
         if (left)
             *left = window->wl.decorations.metrics.width;
         if (right)
@@ -991,7 +1120,7 @@ void _glfwPlatformRestoreWindow(_GLFWwindow* window)
     {
         if (window->monitor)
             xdg_toplevel_unset_fullscreen(window->wl.xdg.toplevel);
-        if (window->wl.toplevel_states & TOPLEVEL_STATE_MAXIMIZED)
+        if (window->wl.current.toplevel_states & TOPLEVEL_STATE_MAXIMIZED)
             xdg_toplevel_unset_maximized(window->wl.xdg.toplevel);
         // There is no way to unset minimized, or even to know if we are
         // minimized, so there is nothing to do in this case.
@@ -1024,38 +1153,51 @@ void _glfwPlatformHideWindow(_GLFWwindow* window)
         xdg_surface_destroy(window->wl.xdg.surface);
         window->wl.xdg.toplevel = NULL;
         window->wl.xdg.surface = NULL;
+        window->wl.surface_configured_once = false;
+        window->swaps_disallowed = true;
     }
     window->wl.visible = false;
 }
 
-void _glfwPlatformRequestWindowAttention(_GLFWwindow* window UNUSED)
+static void
-{
+request_attention(GLFWwindow *window, const char *token, void *data UNUSED) {
-    // TODO
+    if (window && token && token[0]) xdg_activation_v1_activate(_glfw.wl.xdg_activation_v1, token, ((_GLFWwindow*)window)->wl.surface);
-    static bool notified = false;
+}
-    if (!notified) {
+
-        _glfwInputError(GLFW_FEATURE_UNIMPLEMENTED,
+static bool
-                        "Wayland: Window attention request not implemented yet");
+has_activation_in_flight(_GLFWwindow* window, GLFWactivationcallback callback) {
-        notified = true;
+    for (size_t i = 0; i < _glfw.wl.activation_requests.sz; i++) {
+        glfw_wl_xdg_activation_request *r = _glfw.wl.activation_requests.array + i;
+        if (r->window_id == window->id && r->callback == callback) return true;
     }
+    return false;
+}
+
+void _glfwPlatformRequestWindowAttention(_GLFWwindow* window) {
+    if (!has_activation_in_flight(window, request_attention)) get_activation_token(window, 0, request_attention, NULL);
 }
 
 int _glfwPlatformWindowBell(_GLFWwindow* window UNUSED)
 {
     // TODO: Use an actual Wayland API to implement this when one becomes available
-    static char tty[L_ctermid + 1];
-    int fd = open(ctermid(tty), O_WRONLY | O_CLOEXEC);
-    if (fd > -1) {
-        int ret = write(fd, "\x07", 1) == 1 ? true : false;
-        close(fd);
-        return ret;
-    }
     return false;
 }
 
+static void
+focus_window(GLFWwindow *window, const char *token, void *data UNUSED) {
+    if (!window) return;
+    if (token && token[0]) xdg_activation_v1_activate(_glfw.wl.xdg_activation_v1, token, ((_GLFWwindow*)window)->wl.surface);
+    else {
+        _glfwInputError(GLFW_PLATFORM_ERROR, "Wayland: Window focus request via xdg-activation protocol was denied by the compositor. Use a better compositor.");
+    }
+}
+
 void _glfwPlatformFocusWindow(_GLFWwindow* window UNUSED)
 {
-    _glfwInputError(GLFW_FEATURE_UNAVAILABLE,
+    // Attempt to focus the window by using the activation protocol, whether it works
-                    "Wayland: The platform does not support setting the input focus");
+    // is entirely compositor dependent and as we all know Wayland and its ecosystem is
+    // the product of morons.
+    if (_glfw.wl.input_serial && !has_activation_in_flight(window, focus_window)) get_activation_token(window, _glfw.wl.input_serial, focus_window, NULL);
 }
 
 void _glfwPlatformSetWindowMonitor(_GLFWwindow* window,
@@ -1092,7 +1234,7 @@ int _glfwPlatformWindowVisible(_GLFWwindow* window)
 
 int _glfwPlatformWindowMaximized(_GLFWwindow* window)
 {
-    return window->wl.toplevel_states & TOPLEVEL_STATE_MAXIMIZED;
+    return window->wl.current.toplevel_states & TOPLEVEL_STATE_MAXIMIZED;
 }
 
 int _glfwPlatformWindowHovered(_GLFWwindow* window)
@@ -1140,7 +1282,7 @@ void _glfwPlatformSetWindowMousePassthrough(_GLFWwindow* window, bool enabled)
     }
     else
         wl_surface_set_input_region(window->wl.surface, 0);
-    wl_surface_commit(window->wl.surface);
+    commit_window_surface_if_safe(window);
 }
 
 float _glfwPlatformGetWindowOpacity(_GLFWwindow* window UNUSED)
@@ -1204,7 +1346,7 @@ void _glfwPlatformSetCursorPos(_GLFWwindow* window, double x, double y)
         zwp_locked_pointer_v1_set_cursor_position_hint(
             window->wl.pointerLock.lockedPointer,
             wl_fixed_from_double(x), wl_fixed_from_double(y));
-        wl_surface_commit(window->wl.surface);
+        commit_window_surface_if_safe(window);
     }
 }
 
@@ -1360,6 +1502,7 @@ static void lockPointer(_GLFWwindow* window)
     window->wl.pointerLock.relativePointer = relativePointer;
     window->wl.pointerLock.lockedPointer = lockedPointer;
 
+    debug("Calling wl_pointer_set_cursor in lockPointer with surface: %p\n", NULL);
     wl_pointer_set_cursor(_glfw.wl.pointer, _glfw.wl.serial,
                           NULL, 0, 0);
 }
@@ -1396,57 +1539,73 @@ void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor)
     }
     else if (window->cursorMode == GLFW_CURSOR_HIDDEN)
     {
+        debug("Calling wl_pointer_set_cursor in _glfwPlatformSetCursor with surface: %p\n", NULL);
         wl_pointer_set_cursor(_glfw.wl.pointer, _glfw.wl.serial, NULL, 0, 0);
     }
 }
 
-static void send_text(char *text, int fd)
+static bool
-{
+write_all(int fd, const char *data, size_t sz) {
-    if (text) {
+    monotonic_t start = glfwGetTime();
-        size_t len = strlen(text), pos = 0;
+    size_t pos = 0;
-        monotonic_t start = glfwGetTime();
+    while (pos < sz && glfwGetTime() - start < s_to_monotonic_t(2ll)) {
-        while (pos < len && glfwGetTime() - start < s_to_monotonic_t(2ll)) {
+        ssize_t ret = write(fd, data + pos, sz - pos);
-            ssize_t ret = write(fd, text + pos, len - pos);
+        if (ret < 0) {
-            if (ret < 0) {
+            if (errno == EAGAIN || errno == EINTR) continue;
-                if (errno == EAGAIN || errno == EINTR) continue;
+            _glfwInputError(GLFW_PLATFORM_ERROR,
-                _glfwInputError(GLFW_PLATFORM_ERROR,
+                "Wayland: Could not copy writing to destination fd failed with error: %s", strerror(errno));
-                    "Wayland: Could not copy writing to destination fd failed with error: %s", strerror(errno));
+            return false;
-                break;
+        }
-            }
+        if (ret > 0) {
-            if (ret > 0) {
+            start = glfwGetTime();
-                start = glfwGetTime();
+            pos += ret;
-                pos += ret;
-            }
         }
     }
+    return pos >= sz;
+}
+
+static void
+send_clipboard_data(const _GLFWClipboardData *cd, const char *mime, int fd) {
+    if (strcmp(mime, "text/plain;charset=utf-8") == 0 || strcmp(mime, "UTF8_STRING") == 0 || strcmp(mime, "TEXT") == 0 || strcmp(mime, "STRING") == 0) mime = "text/plain";
+    GLFWDataChunk chunk = cd->get_data(mime, NULL, cd->ctype);
+    void *iter = chunk.iter;
+    if (!iter) return;
+    bool keep_going = true;
+    while (keep_going) {
+        chunk = cd->get_data(mime, iter, cd->ctype);
+        if (!chunk.sz) break;
+        if (!write_all(fd, chunk.data, chunk.sz)) keep_going = false;
+        if (chunk.free) chunk.free((void*)chunk.free_data);
+    }
+    cd->get_data(NULL, iter, cd->ctype);
+}
+
+static void _glfwSendClipboardText(void *data UNUSED, struct wl_data_source *data_source UNUSED, const char *mime_type, int fd) {
+    send_clipboard_data(&_glfw.clipboard, mime_type, fd);
     close(fd);
 }
 
-static void _glfwSendClipboardText(void *data UNUSED, struct wl_data_source *data_source UNUSED, const char *mime_type UNUSED, int fd) {
-    send_text(_glfw.wl.clipboardString, fd);
-}
-
 static void _glfwSendPrimarySelectionText(void *data UNUSED, struct zwp_primary_selection_source_v1 *primary_selection_source UNUSED,
-        const char *mime_type UNUSED, int fd) {
+        const char *mime_type, int fd) {
-    send_text(_glfw.wl.primarySelectionString, fd);
+    send_clipboard_data(&_glfw.primary, mime_type, fd);
+    close(fd);
 }
 
-static char* read_offer_string(int data_pipe, size_t *data_sz) {
+static void
+read_offer(int data_pipe, GLFWclipboardwritedatafun write_data, void *object) {
     wl_display_flush(_glfw.wl.display);
-    size_t capacity = 0;
-    char *buf = NULL;
-    *data_sz = 0;
     struct pollfd fds;
     fds.fd = data_pipe;
     fds.events = POLLIN;
     monotonic_t start = glfwGetTime();
 #define bail(...) { \
     _glfwInputError(GLFW_PLATFORM_ERROR, __VA_ARGS__); \
-    free(buf); buf = NULL; \
     close(data_pipe); \
-    return NULL; \
+    return; \
 }
 
+    char buf[8192];
+
     while (glfwGetTime() - start < s_to_monotonic_t(2ll)) {
         int ret = poll(&fds, 1, 2000);
         if (ret == -1) {
@@ -1456,34 +1615,65 @@ static char* read_offer_string(int data_pipe, size_t *data_sz) {
         if (!ret) {
             bail("Wayland: Failed to read clipboard data from pipe (timed out)");
         }
-        if (capacity <= *data_sz || capacity - *data_sz <= 64) {
+        ret = read(data_pipe, buf, sizeof(buf));
-            capacity += 4096;
-            buf = realloc(buf, capacity);
-            if (!buf) {
-                bail("Wayland: Failed to allocate memory to read clipboard data");
-            }
-        }
-        ret = read(data_pipe, buf + *data_sz, capacity - *data_sz - 1);
         if (ret == -1) {
             if (errno == EINTR || errno == EAGAIN || errno == EWOULDBLOCK) continue;
             bail("Wayland: Failed to read clipboard data from pipe with error: %s", strerror(errno));
         }
-        if (ret == 0) { close(data_pipe); buf[*data_sz] = 0; return buf; }
+        if (ret == 0) { close(data_pipe); return; }
-        *data_sz += ret;
+        if (!write_data(object, buf, ret)) bail("Wayland: call to write_data() failed with data from data offer");
         start = glfwGetTime();
     }
     bail("Wayland: Failed to read clipboard data from pipe (timed out)");
 #undef bail
-
 }
 
-static char* read_primary_selection_offer(struct zwp_primary_selection_offer_v1 *primary_selection_offer, const char *mime) {
+
+typedef struct chunked_writer {
+    char *buf; size_t sz, cap;
+} chunked_writer;
+
+static bool
+write_chunk(void *object, const char *data, size_t sz) {
+    chunked_writer *cw = object;
+    if (cw->cap < cw->sz + sz) {
+        cw->cap = MAX(cw->cap * 2, cw->sz + 8*sz);
+        cw->buf = realloc(cw->buf, cw->cap * sizeof(cw->buf[0]));
+    }
+    memcpy(cw->buf + cw->sz, data, sz);
+    cw->sz += sz;
+    return true;
+}
+
+
+static char*
+read_offer_string(int data_pipe, size_t *sz) {
+    chunked_writer cw = {0};
+    read_offer(data_pipe, write_chunk, &cw);
+    if (cw.buf) {
+        *sz = cw.sz;
+        return cw.buf;
+    }
+    *sz = 0;
+    return NULL;
+}
+
+static void
+read_clipboard_data_offer(struct wl_data_offer *data_offer, const char *mime, GLFWclipboardwritedatafun write_data, void *object) {
     int pipefd[2];
-    if (pipe2(pipefd, O_CLOEXEC) != 0) return NULL;
+    if (pipe2(pipefd, O_CLOEXEC) != 0) return;
+    wl_data_offer_receive(data_offer, mime, pipefd[1]);
+    close(pipefd[1]);
+    read_offer(pipefd[0], write_data, object);
+}
+
+static void
+read_primary_selection_offer(struct zwp_primary_selection_offer_v1 *primary_selection_offer, const char *mime, GLFWclipboardwritedatafun write_data, void *object) {
+    int pipefd[2];
+    if (pipe2(pipefd, O_CLOEXEC) != 0) return;
     zwp_primary_selection_offer_v1_receive(primary_selection_offer, mime, pipefd[1]);
     close(pipefd[1]);
-    size_t sz = 0;
+    read_offer(pipefd[0], write_data, object);
-    return read_offer_string(pipefd[0], &sz);
 }
 
 static char* read_data_offer(struct wl_data_offer *data_offer, const char *mime, size_t *sz) {
@@ -1495,24 +1685,33 @@ static char* read_data_offer(struct wl_data_offer *data_offer, const char *mime,
 }
 
 static void data_source_canceled(void *data UNUSED, struct wl_data_source *wl_data_source) {
-    if (_glfw.wl.dataSourceForClipboard == wl_data_source)
+    if (_glfw.wl.dataSourceForClipboard == wl_data_source) {
         _glfw.wl.dataSourceForClipboard = NULL;
+        _glfw_free_clipboard_data(&_glfw.clipboard);
+    }
     wl_data_source_destroy(wl_data_source);
 }
 
 static void primary_selection_source_canceled(void *data UNUSED, struct zwp_primary_selection_source_v1 *primary_selection_source) {
-    if (_glfw.wl.dataSourceForPrimarySelection == primary_selection_source)
+    if (_glfw.wl.dataSourceForPrimarySelection == primary_selection_source) {
         _glfw.wl.dataSourceForPrimarySelection = NULL;
+        _glfw_free_clipboard_data(&_glfw.primary);
+    }
     zwp_primary_selection_source_v1_destroy(primary_selection_source);
 }
 
-static void data_source_target(void *data UNUSED, struct wl_data_source *wl_data_source UNUSED, const char* mime UNUSED) {
+// KWin aborts if we don't define these even though they are not used for copy/paste
+static void dummy_data_source_target(void* data UNUSED, struct wl_data_source* wl_data_source UNUSED, const char* mime_type UNUSED) {
+}
+
+static void dummy_data_source_action(void* data UNUSED, struct wl_data_source* wl_data_source UNUSED, uint dnd_action UNUSED) {
 }
 
 static const struct wl_data_source_listener data_source_listener = {
     .send = _glfwSendClipboardText,
     .cancelled = data_source_canceled,
-    .target = data_source_target,
+    .target = dummy_data_source_target,
+    .action = dummy_data_source_action,
 };
 
 static const struct zwp_primary_selection_source_v1_listener primary_selection_source_listener = {
@@ -1753,12 +1952,12 @@ primary_selection_copy_callback_done(void *data, struct wl_callback *callback, u
     wl_callback_destroy(callback);
 }
 
-void _glfwSetupWaylandDataDevice() {
+void _glfwSetupWaylandDataDevice(void) {
     _glfw.wl.dataDevice = wl_data_device_manager_get_data_device(_glfw.wl.dataDeviceManager, _glfw.wl.seat);
     if (_glfw.wl.dataDevice) wl_data_device_add_listener(_glfw.wl.dataDevice, &data_device_listener, NULL);
 }
 
-void _glfwSetupWaylandPrimarySelectionDevice() {
+void _glfwSetupWaylandPrimarySelectionDevice(void) {
     _glfw.wl.primarySelectionDevice = zwp_primary_selection_device_manager_v1_get_device(_glfw.wl.primarySelectionDeviceManager, _glfw.wl.seat);
     if (_glfw.wl.primarySelectionDevice) zwp_primary_selection_device_v1_add_listener(_glfw.wl.primarySelectionDevice, &primary_selection_device_listener, NULL);
 }
@@ -1789,30 +1988,69 @@ static bool _glfwEnsureDataDevice(void) {
     return true;
 }
 
-void _glfwPlatformSetClipboardString(const char* string)
+typedef void(*add_offer_func)(void*, const char *mime);
-{
+
-    if (!_glfwEnsureDataDevice()) return;
+
-    free(_glfw.wl.clipboardString);
+void
-    _glfw.wl.clipboardString = _glfw_strdup(string);
+_glfwPlatformSetClipboard(GLFWClipboardType t) {
-    if (_glfw.wl.dataSourceForClipboard)
+    _GLFWClipboardData *cd = NULL;
-        wl_data_source_destroy(_glfw.wl.dataSourceForClipboard);
+    void *data_source;
-    _glfw.wl.dataSourceForClipboard = wl_data_device_manager_create_data_source(_glfw.wl.dataDeviceManager);
+    add_offer_func f;
-    if (!_glfw.wl.dataSourceForClipboard)
+    if (t == GLFW_CLIPBOARD) {
-    {
+        if (!_glfwEnsureDataDevice()) return;
-        _glfwInputError(GLFW_PLATFORM_ERROR,
+        cd = &_glfw.clipboard;
-                        "Wayland: Cannot copy failed to create data source");
+        f = (add_offer_func)wl_data_source_offer;
-        return;
+        if (_glfw.wl.dataSourceForClipboard) wl_data_source_destroy(_glfw.wl.dataSourceForClipboard);
+        _glfw.wl.dataSourceForClipboard = wl_data_device_manager_create_data_source(_glfw.wl.dataDeviceManager);
+        if (!_glfw.wl.dataSourceForClipboard)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "Wayland: Cannot copy failed to create data source");
+            return;
+        }
+        wl_data_source_add_listener(_glfw.wl.dataSourceForClipboard, &data_source_listener, NULL);
+        data_source = _glfw.wl.dataSourceForClipboard;
+    } else {
+        if (!_glfw.wl.primarySelectionDevice) {
+            static bool warned_about_primary_selection_device = false;
+            if (!warned_about_primary_selection_device) {
+                _glfwInputError(GLFW_PLATFORM_ERROR,
+                                "Wayland: Cannot copy no primary selection device available");
+                warned_about_primary_selection_device = true;
+            }
+            return;
+        }
+        cd = &_glfw.primary;
+        f = (add_offer_func)zwp_primary_selection_source_v1_offer;
+        if (_glfw.wl.dataSourceForPrimarySelection) zwp_primary_selection_source_v1_destroy(_glfw.wl.dataSourceForPrimarySelection);
+        _glfw.wl.dataSourceForPrimarySelection = zwp_primary_selection_device_manager_v1_create_source(_glfw.wl.primarySelectionDeviceManager);
+        if (!_glfw.wl.dataSourceForPrimarySelection)
+        {
+            _glfwInputError(GLFW_PLATFORM_ERROR,
+                            "Wayland: Cannot copy failed to create primary selection source");
+            return;
+        }
+        zwp_primary_selection_source_v1_add_listener(_glfw.wl.dataSourceForPrimarySelection, &primary_selection_source_listener, NULL);
+        data_source = _glfw.wl.dataSourceForPrimarySelection;
+    }
+    f(data_source, clipboard_mime());
+    for (size_t i = 0; i < cd->num_mime_types; i++) {
+        if (strcmp(cd->mime_types[i], "text/plain") == 0) {
+            f(data_source, "TEXT");
+            f(data_source, "STRING");
+            f(data_source, "UTF8_STRING");
+            f(data_source, "text/plain;charset=utf-8");
+        }
+        f(data_source, cd->mime_types[i]);
     }
-    wl_data_source_add_listener(_glfw.wl.dataSourceForClipboard, &data_source_listener, NULL);
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, clipboard_mime());
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, "text/plain");
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, "text/plain;charset=utf-8");
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, "TEXT");
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, "STRING");
-    wl_data_source_offer(_glfw.wl.dataSourceForClipboard, "UTF8_STRING");
     struct wl_callback *callback = wl_display_sync(_glfw.wl.display);
-    static const struct wl_callback_listener clipboard_copy_callback_listener = {.done = clipboard_copy_callback_done};
+    if (t == GLFW_CLIPBOARD) {
-    wl_callback_add_listener(callback, &clipboard_copy_callback_listener, _glfw.wl.dataSourceForClipboard);
+        static const struct wl_callback_listener clipboard_copy_callback_listener = {.done = clipboard_copy_callback_done};
+        wl_callback_add_listener(callback, &clipboard_copy_callback_listener, _glfw.wl.dataSourceForClipboard);
+    } else {
+        static const struct wl_callback_listener primary_selection_copy_callback_listener = {.done = primary_selection_copy_callback_done};
+        wl_callback_add_listener(callback, &primary_selection_copy_callback_listener, _glfw.wl.dataSourceForPrimarySelection);
+    }
 }
 
 static bool
@@ -1830,81 +2068,47 @@ plain_text_mime_for_offer(const _GLFWWaylandDataOffer *d) {
     A("text/plain");
     A("UTF8_STRING");
     A("STRING");
+    A("TEXT");
 #undef A
     return NULL;
 }
 
-const char* _glfwPlatformGetClipboardString(void)
+void
-{
+_glfwPlatformGetClipboard(GLFWClipboardType clipboard_type, const char* mime_type, GLFWclipboardwritedatafun write_data, void *object) {
+    _GLFWWaylandOfferType offer_type = clipboard_type == GLFW_PRIMARY_SELECTION ? PRIMARY_SELECTION : CLIPBOARD;
     for (size_t i = 0; i < arraysz(_glfw.wl.dataOffers); i++) {
         _GLFWWaylandDataOffer *d = _glfw.wl.dataOffers + i;
-        if (d->id && d->offer_type == CLIPBOARD) {
+        if (d->id && d->offer_type == offer_type) {
-            if (d->is_self_offer) return _glfw.wl.clipboardString;
+            if (d->is_self_offer) {
-            const char *mime = plain_text_mime_for_offer(d);
+                write_data(object, NULL, 1);
-            if (mime) {
+                return;
-                free(_glfw.wl.pasteString);
-                size_t sz = 0;
-                _glfw.wl.pasteString = read_data_offer(d->id, mime, &sz);
-                return _glfw.wl.pasteString;
             }
-        }
+            if (mime_type == NULL) {
-    }
+                bool ok = true;
-    return NULL;
+                for (size_t o = 0; o < d->mimes_count; o++) {
-}
+                    const char *q = d->mimes[o];
-
+                    if (strchr(d->mimes[0], '/')) {
-void _glfwPlatformSetPrimarySelectionString(const char* string)
+                        if (strcmp(q, clipboard_mime()) == 0) continue;
-{
+                        if (strcmp(q, "text/plain;charset=utf-8") == 0) q = "text/plain";
-    if (!_glfw.wl.primarySelectionDevice) {
+                    } else {
-        static bool warned_about_primary_selection_device = false;
+                        if (strcmp(q, "UTF8_STRING") == 0 || strcmp(q, "STRING") == 0 || strcmp(q, "TEXT") == 0) q = "text/plain";
-        if (!warned_about_primary_selection_device) {
+                    }
-            _glfwInputError(GLFW_PLATFORM_ERROR,
+                    if (ok) ok = write_data(object, q, strlen(q));
-                            "Wayland: Cannot copy no primary selection device available");
+                }
-            warned_about_primary_selection_device = true;
+                return;
-        }
-        return;
-    }
-    if (_glfw.wl.primarySelectionString == string) return;
-    free(_glfw.wl.primarySelectionString);
-    _glfw.wl.primarySelectionString = _glfw_strdup(string);
-
-    if (_glfw.wl.dataSourceForPrimarySelection)
-        zwp_primary_selection_source_v1_destroy(_glfw.wl.dataSourceForPrimarySelection);
-    _glfw.wl.dataSourceForPrimarySelection = zwp_primary_selection_device_manager_v1_create_source(_glfw.wl.primarySelectionDeviceManager);
-    if (!_glfw.wl.dataSourceForPrimarySelection)
-    {
-        _glfwInputError(GLFW_PLATFORM_ERROR,
-                        "Wayland: Cannot copy failed to create primary selection source");
-        return;
-    }
-    zwp_primary_selection_source_v1_add_listener(_glfw.wl.dataSourceForPrimarySelection, &primary_selection_source_listener, NULL);
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, clipboard_mime());
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, "text/plain");
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, "text/plain;charset=utf-8");
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, "TEXT");
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, "STRING");
-    zwp_primary_selection_source_v1_offer(_glfw.wl.dataSourceForPrimarySelection, "UTF8_STRING");
-    struct wl_callback *callback = wl_display_sync(_glfw.wl.display);
-    static const struct wl_callback_listener primary_selection_copy_callback_listener = {.done = primary_selection_copy_callback_done};
-    wl_callback_add_listener(callback, &primary_selection_copy_callback_listener, _glfw.wl.dataSourceForPrimarySelection);
-}
-
-const char* _glfwPlatformGetPrimarySelectionString(void)
-{
-    if (_glfw.wl.dataSourceForPrimarySelection != NULL) return _glfw.wl.primarySelectionString;
-
-    for (size_t i = 0; i < arraysz(_glfw.wl.dataOffers); i++) {
-        _GLFWWaylandDataOffer *d = _glfw.wl.dataOffers + i;
-        if (d->id && d->is_primary && d->offer_type == PRIMARY_SELECTION) {
-            if (d->is_self_offer) return _glfw.wl.primarySelectionString;
-            const char *mime = plain_text_mime_for_offer(d);
-            if (mime) {
-                free(_glfw.wl.pasteString);
-                _glfw.wl.pasteString = read_primary_selection_offer(d->id, mime);
-                return _glfw.wl.pasteString;
             }
+            if (strcmp(mime_type, "text/plain") == 0) {
+                mime_type = plain_text_mime_for_offer(d);
+                if (!mime_type) return;
+            }
+            if (d->is_primary) {
+                read_primary_selection_offer(d->id, mime_type, write_data, object);
+            } else {
+                read_clipboard_data_offer(d->id, mime_type, write_data, object);
+            }
+            break;
         }
     }
-    return NULL;
 }
 
 EGLenum _glfwPlatformGetEGLPlatform(EGLint** attribs UNUSED)
@@ -2026,6 +2230,18 @@ GLFWAPI struct wl_surface* glfwGetWaylandWindow(GLFWwindow* handle)
     return window->wl.surface;
 }
 
+GLFWAPI void glfwWaylandActivateWindow(GLFWwindow* handle, const char *activation_token) {
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT();
+    if (activation_token && activation_token[0]) xdg_activation_v1_activate(_glfw.wl.xdg_activation_v1, activation_token, window->wl.surface);
+}
+
+GLFWAPI void glfwWaylandRunWithActivationToken(GLFWwindow *handle, GLFWactivationcallback cb, void *cb_data) {
+    _GLFWwindow* window = (_GLFWwindow*) handle;
+    _GLFW_REQUIRE_INIT();
+    get_activation_token(window, _glfw.wl.input_serial, cb, cb_data);
+}
+
 GLFWAPI int glfwGetNativeKeyForName(const char* keyName, bool caseSensitive) {
     return glfw_xkb_keysym_from_name(keyName, caseSensitive);
 }
@@ -2034,12 +2250,19 @@ GLFWAPI void glfwRequestWaylandFrameEvent(GLFWwindow *handle, unsigned long long
     _GLFWwindow* window = (_GLFWwindow*) handle;
     static const struct wl_callback_listener frame_listener = { .done = frame_handle_redraw };
     if (window->wl.frameCallbackData.current_wl_callback) wl_callback_destroy(window->wl.frameCallbackData.current_wl_callback);
-    window->wl.frameCallbackData.id = id;
+    if (window->wl.waiting_for_swap_to_commit) {
-    window->wl.frameCallbackData.callback = callback;
+        callback(id);
-    window->wl.frameCallbackData.current_wl_callback = wl_surface_frame(window->wl.surface);
+        window->wl.frameCallbackData.id = 0;
-    if (window->wl.frameCallbackData.current_wl_callback) {
+        window->wl.frameCallbackData.callback = NULL;
-        wl_callback_add_listener(window->wl.frameCallbackData.current_wl_callback, &frame_listener, window);
+        window->wl.frameCallbackData.current_wl_callback = NULL;
-        wl_surface_commit(window->wl.surface);
+    } else {
+        window->wl.frameCallbackData.id = id;
+        window->wl.frameCallbackData.callback = callback;
+        window->wl.frameCallbackData.current_wl_callback = wl_surface_frame(window->wl.surface);
+        if (window->wl.frameCallbackData.current_wl_callback) {
+            wl_callback_add_listener(window->wl.frameCallbackData.current_wl_callback, &frame_listener, window);
+            commit_window_surface_if_safe(window);
+        }
     }
 }
 

glfw/x11_init.c

@@ -137,6 +137,8 @@ static void detectEWMH(void)
         getAtomIfSupported(supportedAtoms, atomCount, "_NET_WM_WINDOW_TYPE");
     _glfw.x11.NET_WM_WINDOW_TYPE_NORMAL =
         getAtomIfSupported(supportedAtoms, atomCount, "_NET_WM_WINDOW_TYPE_NORMAL");
+    _glfw.x11.NET_WM_WINDOW_TYPE_DOCK =
+        getAtomIfSupported(supportedAtoms, atomCount, "_NET_WM_WINDOW_TYPE_DOCK");
     _glfw.x11.NET_WORKAREA =
         getAtomIfSupported(supportedAtoms, atomCount, "_NET_WORKAREA");
     _glfw.x11.NET_CURRENT_DESKTOP =
@@ -147,6 +149,8 @@ static void detectEWMH(void)
         getAtomIfSupported(supportedAtoms, atomCount, "_NET_FRAME_EXTENTS");
     _glfw.x11.NET_REQUEST_FRAME_EXTENTS =
         getAtomIfSupported(supportedAtoms, atomCount, "_NET_REQUEST_FRAME_EXTENTS");
+    _glfw.x11.NET_WM_STRUT_PARTIAL =
+        getAtomIfSupported(supportedAtoms, atomCount, "_NET_WM_STRUT_PARTIAL");
 
     XFree(supportedAtoms);
 }
@@ -610,6 +614,10 @@ Cursor _glfwCreateCursorX11(const GLFWimage* image, int xhot, int yhot)
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
+GLFWAPI int glfwGetCurrentSystemColorTheme(void) {
+    return 0;
+}
+
 int _glfwPlatformInit(void)
 {
     XInitThreads();
@@ -680,8 +688,14 @@ void _glfwPlatformTerminate(void)
 
     glfw_xkb_release(&_glfw.x11.xkb);
     glfw_dbus_terminate(&_glfw.x11.dbus);
-    free(_glfw.x11.primarySelectionString);
+    if (_glfw.x11.mime_atoms.array) {
-    free(_glfw.x11.clipboardString);
+        for (size_t i = 0; i < _glfw.x11.mime_atoms.sz; i++) {
+            free((void*)_glfw.x11.mime_atoms.array[i].mime);
+        }
+        free(_glfw.x11.mime_atoms.array);
+    }
+    if (_glfw.x11.clipboard_atoms.array) { free(_glfw.x11.clipboard_atoms.array); }
+    if (_glfw.x11.primary_atoms.array) { free(_glfw.x11.primary_atoms.array); }
 
     if (_glfw.x11.display)
     {