version 0.25.2

The prewarm process and its controller are implemented with some basic
tests.

.github/workflows/ci.py

@@ -30,13 +30,17 @@ 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('#'))
-        run('brew', 'install', *items)
+        items = (x.split()[1].strip('"') for x in open('Brewfile').readlines() if x.strip().startswith('brew '))
+        run('brew', 'install', 'fish', *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'
-            ' libpng-dev liblcms2-dev libfontconfig-dev libxkbcommon-x11-dev libcanberra-dev librsync-dev uuid-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'
+            ' 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:
@@ -48,7 +52,7 @@ def install_deps():
 
 def build_kitty():
     python = shutil.which('python3') if is_bundle else sys.executable
-    cmd = '{} setup.py build --verbose'.format(python)
+    cmd = f'{python} setup.py build --verbose'
     if os.environ.get('KITTY_SANITIZE') == '1':
         cmd += ' --debug --sanitize'
     run(cmd)
@@ -59,8 +63,8 @@ def test_kitty():
 
 
 def package_kitty():
-    py = 'python3' if is_macos else 'python'
-    run(py + ' setup.py linux-package --update-check-interval=0 --verbose')
+    python = 'python3' if is_macos else 'python'
+    run(f'{python} setup.py linux-package --update-check-interval=0 --verbose')
     if is_macos:
         run('python3 setup.py kitty.app --update-check-interval=0 --verbose')
         run('kitty.app/Contents/MacOS/kitty +runpy "from kitty.constants import *; print(kitty_exe())"')
@@ -76,11 +80,11 @@ def replace_in_file(path, src, dest):
 def setup_bundle_env():
     global SW
     os.environ['SW'] = SW = '/Users/Shared/kitty-build/sw/sw' if is_macos else os.path.join(os.environ['GITHUB_WORKSPACE'], 'sw')
-    os.environ['PKG_CONFIG_PATH'] = SW + '/lib/pkgconfig'
+    os.environ['PKG_CONFIG_PATH'] = os.path.join(SW, 'lib', 'pkgconfig')
     if is_macos:
         os.environ['PATH'] = '{}:{}'.format('/usr/local/opt/sphinx-doc/bin', os.environ['PATH'])
     else:
-        os.environ['LD_LIBRARY_PATH'] = SW + '/lib'
+        os.environ['LD_LIBRARY_PATH'] = os.path.join(SW, 'lib')
         os.environ['PYTHONHOME'] = SW
     os.environ['PATH'] = '{}:{}'.format(os.path.join(SW, 'bin'), os.environ['PATH'])
 
@@ -111,7 +115,7 @@ def main():
         setup_bundle_env()
     else:
         if not is_macos and 'pythonLocation' in os.environ:
-            os.environ['LD_LIBRARY_PATH'] = '{}/lib'.format(os.environ['pythonLocation'])
+            os.environ['LD_LIBRARY_PATH'] = os.path.join(os.environ['pythonLocation'], 'lib')
     action = sys.argv[-1]
     if action in ('build', 'package'):
         install_deps()
@@ -122,7 +126,7 @@ def main():
     elif action == 'test':
         test_kitty()
     else:
-        raise SystemExit('Unknown action: ' + action)
+        raise SystemExit(f'Unknown action: {action}')
 
 
 if __name__ == '__main__':

.github/workflows/ci.yml

@@ -20,15 +20,15 @@ jobs:
                 cc: [gcc, clang]
                 include:
                     - python: a
-                      pyver: 3.7
+                      pyver: "3.8"
                       sanitize: 0
 
                     - python: b
-                      pyver: 3.8
+                      pyver: "3.9"
                       sanitize: 1
 
                     - python: c
-                      pyver: 3.9
+                      pyver: "3.10"
                       sanitize: 1
 
 
@@ -42,11 +42,11 @@ jobs:
 
         steps:
             - name: Checkout source code
-              uses: actions/checkout@master
+              uses: actions/checkout@v3
               with:
                 fetch-depth: 10
             - name: Set up Python ${{ matrix.pyver }}
-              uses: actions/setup-python@master
+              uses: actions/setup-python@v3
               with:
                 python-version: ${{ matrix.pyver }}
 
@@ -63,15 +63,15 @@ jobs:
             CFLAGS: -funsigned-char
         steps:
             - name: Checkout source code
-              uses: actions/checkout@master
+              uses: actions/checkout@v3
               with:
-                fetch-depth: 10
+                fetch-depth: 0  # needed for :commit: docs role
 
             - 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
 
             - name: Set up Python
-              uses: actions/setup-python@master
+              uses: actions/setup-python@v3
               with:
                 python-version: 3.8
 
@@ -88,10 +88,10 @@ jobs:
               run: python test.py mypy
 
             - name: Build man page
-              run: make FAIL_WARN=-W man
+              run: make FAIL_WARN=1 man
 
             - name: Build HTML docs
-              run: make FAIL_WARN=-W html
+              run: make FAIL_WARN=1 html
 
     bundle:
         name: Bundle test (${{ matrix.os }})

.github/workflows/codeql-analysis.yml

@@ -16,7 +16,7 @@ jobs:
 
     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.
@@ -27,6 +27,7 @@ jobs:
       uses: github/codeql-action/init@v1
       with:
         languages: python, c
+        setup-python-dependencies: false
 
     - name: Build kitty
       run: python3 .github/workflows/ci.py build

Brewfile

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

Makefile

@@ -5,6 +5,10 @@ ifdef VERBOSE
 	VVAL=--verbose
 endif
 
+ifdef FAIL_WARN
+export FAIL_WARN
+endif
+
 all:
 	python3 setup.py $(VVAL)
 
@@ -32,13 +36,16 @@ app:
 	python3 setup.py kitty.app $(VVAL)
 
 man:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs man
+	$(MAKE) -C docs man
 
 html:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs html
+	$(MAKE) -C docs html
+
+dirhtml:
+	$(MAKE) -C docs dirhtml
 
 linkcheck:
-	$(MAKE) FAIL_WARN=$(FAIL_WARN) -C docs linkcheck
+	$(MAKE) -C docs linkcheck
 
 website:
 	./publish.py --only website

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,152 +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
-    import tty
-    from contextlib import suppress
-    ret = subprocess.Popen(args[1:]).wait()
-    with suppress(BaseException):
-        print('\n\x1b[1;32mPress any key to exit', end='', flush=True)
-    with suppress(BaseException):
-        tty.setraw(sys.stdin.fileno())
-        sys.stdin.buffer.read(1)
-    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 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,
-    'runpy': runpy,
-    'launch': launch,
-    'kitten': run_kitten,
-    'edit-config': edit_config_file,
-
-    '@': 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
-
-
-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', '-o' + tdir, 'terminfo/kitty.terminfo'], check=True, stderr=subprocess.PIPE)
-        regex = '^"terminfo/kitty.terminfo", line [0-9]+, col [0-9]+, terminal \'xterm-kitty\': older tic versions may treat the description field as an alias$'
-        for error in proc.stderr.decode('utf-8').splitlines():
-            if not re.match(regex, error):
-                print(error, file=sys.stderr)
+        proc = subprocess.run(['tic', '-x', f'-o{tdir}', 'terminfo/kitty.terminfo'], capture_output=True)
+        if proc.returncode != 0:
+            sys.stderr.buffer.write(proc.stderr)
+            raise SystemExit(proc.returncode)
         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

@@ -26,7 +26,7 @@ def initialize_constants():
     kitty_constants = {}
     src = read_src_file('constants.py')
     nv = re.search(r'Version\((\d+), (\d+), (\d+)\)', src)
-    kitty_constants['version'] = '%s.%s.%s' % (nv.group(1), nv.group(2), nv.group(3))
+    kitty_constants['version'] = f'{nv.group(1)}.{nv.group(2)}.{nv.group(3)}'
     kitty_constants['appname'] = re.search(
             r'appname: str\s+=\s+(u{0,1})[\'"]([^\'"]+)[\'"]', src
     ).group(2)

bypy/linux/__main__.py

@@ -35,10 +35,14 @@ 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('python' + py_ver, 2),
+                get_dll_path(f'python{py_ver}', 2),
         )
 
 
@@ -47,7 +51,7 @@ class Env:
     def __init__(self, package_dir):
         self.base = package_dir
         self.lib_dir = j(self.base, 'lib')
-        self.py_dir = j(self.lib_dir, 'python' + py_ver)
+        self.py_dir = j(self.lib_dir, f'python{py_ver}')
         os.makedirs(self.py_dir)
         self.bin_dir = j(self.base, 'bin')
         self.obj_dir = mkdtemp('launchers-')
@@ -107,7 +111,7 @@ def add_ca_certs(env):
 
 def copy_python(env):
     print('Copying python...')
-    srcdir = j(PREFIX, 'lib/python' + py_ver)
+    srcdir = j(PREFIX, f'lib/python{py_ver}')
 
     for x in os.listdir(srcdir):
         y = j(srcdir, x)
@@ -187,11 +191,11 @@ def strip_files(files, argv_max=(256 * 1024)):
 
 
 def strip_binaries(files):
-    print('Stripping %d files...' % len(files))
+    print(f'Stripping {len(files)} files...')
     before = sum(os.path.getsize(x) for x in files)
     strip_files(files)
     after = sum(os.path.getsize(x) for x in files)
-    print('Stripped %.1f MB' % ((before - after) / (1024 * 1024.)))
+    print('Stripped {:.1f} MB'.format((before - after) / (1024 * 1024.)))
 
 
 def create_tarfile(env, compression_level='9'):
@@ -203,7 +207,7 @@ def create_tarfile(env, compression_level='9'):
         if err.errno != errno.ENOENT:
             raise
     os.mkdir(base)
-    dist = os.path.join(base, '%s-%s-%s.tar' % (kitty_constants['appname'], kitty_constants['version'], arch))
+    dist = os.path.join(base, f'{kitty_constants["appname"]}-{kitty_constants["version"]}-{arch}.tar')
     with tarfile.open(dist, mode='w', format=tarfile.PAX_FORMAT) as tf:
         cwd = os.getcwd()
         os.chdir(env.base)
@@ -213,13 +217,13 @@ def create_tarfile(env, compression_level='9'):
         finally:
             os.chdir(cwd)
     print('Compressing archive...')
-    ans = dist.rpartition('.')[0] + '.txz'
+    ans = f'{dist.rpartition(".")[0]}.txz'
     start_time = time.time()
-    subprocess.check_call(['xz', '--threads=0', '-f', '-' + compression_level, dist])
+    subprocess.check_call(['xz', '--threads=0', '-f', f'-{compression_level}', dist])
     secs = time.time() - start_time
-    print('Compressed in %d minutes %d seconds' % (secs // 60, secs % 60))
-    os.rename(dist + '.xz', ans)
-    print('Archive %s created: %.2f MB' % (
+    print('Compressed in {} minutes {} seconds'.format(secs // 60, secs % 60))
+    os.rename(f'{dist}.xz', ans)
+    print('Archive {} created: {:.2f} MB'.format(
         os.path.basename(ans), os.stat(ans).st_size / (1024.**2)))
 
 

bypy/macos/__main__.py

@@ -90,7 +90,7 @@ def strip_files(files, argv_max=(256 * 1024)):
 def files_in(folder):
     for record in os.walk(folder):
         for f in record[-1]:
-            yield os.path.join(record[0], f)
+            yield join(record[0], f)
 
 
 def expand_dirs(items, exclude=lambda x: x.endswith('.so')):
@@ -103,7 +103,7 @@ def expand_dirs(items, exclude=lambda x: x.endswith('.so')):
 
 
 def do_sign(app_dir):
-    with current_dir(os.path.join(app_dir, 'Contents')):
+    with current_dir(join(app_dir, 'Contents')):
         # Sign all .so files
         so_files = {x for x in files_in('.') if x.endswith('.so')}
         codesign(so_files)
@@ -153,7 +153,7 @@ class Freeze(object):
         self.to_strip = []
         self.warnings = []
         self.py_ver = py_ver
-        self.python_stdlib = join(self.resources_dir, 'Python', 'lib', 'python' + self.py_ver)
+        self.python_stdlib = join(self.resources_dir, 'Python', 'lib', f'python{self.py_ver}')
         self.site_packages = self.python_stdlib  # hack to avoid needing to add site-packages to path
         self.obj_dir = mkdtemp('launchers-')
 
@@ -177,7 +177,7 @@ class Freeze(object):
             self.run_tests()
         # self.run_shell()
 
-        ret = self.makedmg(self.build_dir, APPNAME + '-' + VERSION)
+        ret = self.makedmg(self.build_dir, f'{APPNAME}-{VERSION}')
 
         return ret
 
@@ -185,8 +185,17 @@ class Freeze(object):
     def add_ca_certs(self):
         print('\nDownloading CA certs...')
         from urllib.request import urlopen
-        cdata = urlopen(kitty_constants['cacerts_url']).read()
-        dest = os.path.join(self.contents_dir, 'Resources', 'cacert.pem')
+        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)
 
@@ -197,7 +206,7 @@ class Freeze(object):
 
     @flush
     def run_tests(self):
-        iv['run_tests'](os.path.join(self.contents_dir, 'MacOS', 'kitty'))
+        iv['run_tests'](join(self.contents_dir, 'MacOS', 'kitty'))
 
     @flush
     def set_id(self, path_to_lib, new_id):
@@ -222,10 +231,10 @@ class Freeze(object):
     @flush
     def get_local_dependencies(self, path_to_lib):
         for x, is_id in self.get_dependencies(path_to_lib):
-            for y in (PREFIX + '/lib/', PREFIX + '/python/Python.framework/', '@rpath/'):
+            for y in (f'{PREFIX}/lib/', f'{PREFIX}/python/Python.framework/', '@rpath/'):
                 if x.startswith(y):
-                    if y == PREFIX + '/python/Python.framework/':
-                        y = PREFIX + '/python/'
+                    if y == f'{PREFIX}/python/Python.framework/':
+                        y = f'{PREFIX}/python/'
                     yield x, x[len(y):], is_id
                     break
 
@@ -239,7 +248,7 @@ class Freeze(object):
         self.to_strip.append(path_to_lib)
         old_mode = flipwritable(path_to_lib)
         for dep, bname, is_id in self.get_local_dependencies(path_to_lib):
-            ndep = self.FID + '/' + bname
+            ndep = f'{self.FID}/{bname}'
             self.change_dep(dep, ndep, is_id, path_to_lib)
         ldeps = list(self.get_local_dependencies(path_to_lib))
         if ldeps:
@@ -252,7 +261,7 @@ class Freeze(object):
     @flush
     def add_python_framework(self):
         print('\nAdding Python framework')
-        src = join(PREFIX + '/python', 'Python.framework')
+        src = join(f'{PREFIX}/python', 'Python.framework')
         x = join(self.frameworks_dir, 'Python.framework')
         curr = os.path.realpath(join(src, 'Versions', 'Current'))
         currd = join(x, 'Versions', basename(curr))
@@ -262,12 +271,12 @@ class Freeze(object):
         shutil.copy2(join(curr, 'Python'), currd)
         self.set_id(
             join(currd, 'Python'),
-            self.FID + '/Python.framework/Versions/%s/Python' % basename(curr))
+            f'{self.FID}/Python.framework/Versions/{basename(curr)}/Python')
         # The following is needed for codesign
         with current_dir(x):
             os.symlink(basename(curr), 'Versions/Current')
             for y in ('Python', 'Resources'):
-                os.symlink('Versions/Current/%s' % y, y)
+                os.symlink(f'Versions/Current/{y}', y)
 
     @flush
     def install_dylib(self, path, set_id=True):
@@ -275,7 +284,7 @@ class Freeze(object):
         if set_id:
             self.set_id(
                 join(self.frameworks_dir, basename(path)),
-                self.FID + '/' + basename(path))
+                f'{self.FID}/{basename(path)}')
         self.fix_dependencies_in_lib(join(self.frameworks_dir, basename(path)))
 
     @flush
@@ -291,11 +300,11 @@ class Freeze(object):
                 'rsync.2',
         ):
             print('\nAdding', x)
-            x = 'lib%s.dylib' % x
+            x = f'lib{x}.dylib'
             src = join(PREFIX, 'lib', x)
             shutil.copy2(src, self.frameworks_dir)
             dest = join(self.frameworks_dir, x)
-            self.set_id(dest, self.FID + '/' + x)
+            self.set_id(dest, f'{self.FID}/{x}')
             self.fix_dependencies_in_lib(dest)
 
     @flush
@@ -321,7 +330,7 @@ class Freeze(object):
     @flush
     def add_stdlib(self):
         print('\nAdding python stdlib')
-        src = PREFIX + '/python/Python.framework/Versions/Current/lib/python' + self.py_ver
+        src = f'{PREFIX}/python/Python.framework/Versions/Current/lib/python{self.py_ver}'
         dest = self.python_stdlib
         if not os.path.exists(dest):
             os.makedirs(dest)
@@ -345,19 +354,19 @@ class Freeze(object):
         kitty_dir = join(self.resources_dir, 'kitty')
         bases = ('kitty', 'kittens', 'kitty_tests')
         for x in bases:
-            dest = os.path.join(self.python_stdlib, x)
-            os.rename(os.path.join(kitty_dir, x), dest)
+            dest = join(self.python_stdlib, x)
+            os.rename(join(kitty_dir, x), dest)
             if x == 'kitty':
-                shutil.rmtree(os.path.join(dest, 'launcher'))
-        os.rename(os.path.join(kitty_dir, '__main__.py'), os.path.join(self.python_stdlib, 'kitty_main.py'))
-        shutil.rmtree(os.path.join(kitty_dir, '__pycache__'))
-        pdir = os.path.join(dirname(self.python_stdlib), 'kitty-extensions')
+                shutil.rmtree(join(dest, 'launcher'))
+        os.rename(join(kitty_dir, '__main__.py'), join(self.python_stdlib, 'kitty_main.py'))
+        shutil.rmtree(join(kitty_dir, '__pycache__'))
+        pdir = join(dirname(self.python_stdlib), 'kitty-extensions')
         os.mkdir(pdir)
         print('Extracting extension modules from', self.python_stdlib, 'to', pdir)
         ext_map = extract_extension_modules(self.python_stdlib, pdir)
-        shutil.copy(os.path.join(os.path.dirname(self_dir), 'site.py'), os.path.join(self.python_stdlib, 'site.py'))
+        shutil.copy(join(os.path.dirname(self_dir), 'site.py'), join(self.python_stdlib, 'site.py'))
         for x in bases:
-            iv['sanitize_source_folder'](os.path.join(self.python_stdlib, x))
+            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)
         iv['build_frozen_launcher']([path_to_freeze_dir(), self.obj_dir])
@@ -434,23 +443,23 @@ class Freeze(object):
         ''' Copy a directory d into a dmg named volname '''
         print('\nMaking dmg...')
         sys.stdout.flush()
-        destdir = os.path.join(SW, 'dist')
+        destdir = join(SW, 'dist')
         try:
             shutil.rmtree(destdir)
         except FileNotFoundError:
             pass
         os.mkdir(destdir)
-        dmg = os.path.join(destdir, volname + '.dmg')
+        dmg = join(destdir, f'{volname}.dmg')
         if os.path.exists(dmg):
             os.unlink(dmg)
         tdir = tempfile.mkdtemp()
-        appdir = os.path.join(tdir, os.path.basename(d))
+        appdir = join(tdir, os.path.basename(d))
         shutil.copytree(d, appdir, symlinks=True)
         if self.sign_installers:
             with timeit() as times:
                 sign_app(appdir, self.notarize)
-            print('Signing completed in %d minutes %d seconds' % tuple(times))
-        os.symlink('/Applications', os.path.join(tdir, 'Applications'))
+            print('Signing completed in {} minutes {} seconds'.format(*times))
+        os.symlink('/Applications', join(tdir, 'Applications'))
         size_in_mb = int(
             subprocess.check_output(['du', '-s', '-k', tdir]).decode('utf-8')
             .split()[0]) / 1024.
@@ -466,10 +475,10 @@ class Freeze(object):
         print('\nCreating dmg...')
         with timeit() as times:
             subprocess.check_call(cmd + [dmg])
-        print('dmg created in %d minutes and %d seconds' % tuple(times))
+        print('dmg created in {} minutes and {} seconds'.format(*times))
         shutil.rmtree(tdir)
         size = os.stat(dmg).st_size / (1024 * 1024.)
-        print('\nInstaller size: %.2fMB\n' % size)
+        print(f'\nInstaller size: {size:.2f}MB\n')
         return dmg
 
 
@@ -477,7 +486,7 @@ def main():
     args = globals()['args']
     ext_dir = globals()['ext_dir']
     Freeze(
-        os.path.join(ext_dir, kitty_constants['appname'] + '.app'),
+        join(ext_dir, f'{kitty_constants["appname"]}.app'),
         dont_strip=args.dont_strip,
         sign_installers=args.sign_installers,
         notarize=args.notarize,

bypy/sources.json

@@ -166,8 +166,8 @@
     {
         "name": "pygments",
         "unix": {
-            "filename": "Pygments-2.7.4.tar.gz",
-            "hash": "sha256:df49d09b498e83c1a73128295860250b0b7edd4c723a32e9bc0d295c7c2ec337",
+            "filename": "Pygments-2.11.2.tar.gz",
+            "hash": "sha256:4e426f72023d88d03b2fa258de560726ce890ff3b630f88c21cbb8b2503b8c6a",
             "urls": ["pypi"]
         }
     },
@@ -273,8 +273,8 @@
         "name": "wayland",
         "os": "linux",
         "unix": {
-            "filename": "wayland-1.19.0.tar.xz",
-            "hash": "sha256:baccd902300d354581cd5ad3cc49daa4921d55fb416a5883e218750fef166d15",
+            "filename": "wayland-1.20.0.tar.xz",
+            "hash": "sha256:b8a034154c7059772e0fdbd27dbfcda6c732df29cae56a82274f6ec5d7cd8725",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     },
@@ -283,8 +283,8 @@
         "name": "wayland-protocols",
         "os": "linux",
         "unix": {
-            "filename": "wayland-protocols-1.20.tar.xz",
-            "hash": "sha256:9782b7a1a863d82d7c92478497d13c758f52e7da4f197aa16443f73de77e4de7",
+            "filename": "wayland-protocols-1.25.tar.xz",
+            "hash": "sha256:f1ff0f7199d0a0da337217dd8c99979967808dc37731a1e759e822b75b571460",
             "urls": ["https://wayland.freedesktop.org/releases/{filename}"]
         }
     }

docs/Makefile

@@ -1,6 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
+ifdef FAIL_WARN
+override FAIL_WARN=-W
+endif
+
 # You can set these variables from the command line.
 SPHINXOPTS    = -n -q -j auto -T $(FAIL_WARN) $(OPTS)
 SPHINXBUILD   = sphinx-build

docs/_static/custom.css

@@ -28,3 +28,9 @@ details > summary {
     text-decoration-color: var(--color-link-underline);
     text-decoration-line: underline;
 }
+
+/* pygments adds an underline to some white-space, this is particularly visible in
+ * dark mode. Remove it. */
+.highlight .w {
+    text-decoration: none
+}

docs/basic.rst

@@ -1,12 +1,13 @@
 Tabs and Windows
 -------------------
 
-|kitty| is capable of running multiple programs organized into tabs and
-windows. The top level of organization is the *Tab*. Each tab consists
-of one or more *windows*. The windows can be arranged in multiple
-different layouts, like windows are organized in a tiling window
-manager. The keyboard controls (which are all customizable) for tabs and
-windows are:
+|kitty| is capable of running multiple programs organized into tabs and windows.
+The top level of organization is the :term:`OS window <os_window>`. Each OS
+window consists of one or more :term:`tabs <tab>`. Each tab consists of one or more
+:term:`kitty windows <window>`. The kitty windows can be arranged in multiple
+different :term:`layouts <layout>`, like windows are organized in a tiling
+window manager. The keyboard controls (which are :ref:`all customizable
+<conf-kitty-shortcuts>`) for tabs and windows are:
 
 Scrolling
 ~~~~~~~~~~~~~~
@@ -64,8 +65,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
-windows and move windows around (similar to window movement in vim)::
+Additionally, you can define shortcuts in :file:`kitty.conf` to focus
+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,17 +79,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 and the
-previously active windows for negative numbers.
+: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 :ac:`nth_os_window`. Only
+positive numbers are accepted, starting from one.
 
 .. _detach_window:
 
-You can define shortcuts to detach the current window and
-move it to another tab or another OS window::
+You can define shortcuts to detach the current window and move it to another tab
+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
@@ -103,8 +108,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
-the currently active window::
+Finally, you can define a shortcut to close all windows in a tab other than the
+currently active window::
 
     map f9 close_other_windows_in_tab
 
@@ -121,18 +126,18 @@ Action                              Shortcut
 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)
-Click URL using the keyboard        :sc:`open_url`
-Reset the terminal                  :sc:`reset_terminal`
+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:`⌘+⌥+f6` on macOS)
-Pass current selection to program   :sc:`pass_selection_to_program`
-Edit |kitty| config file            :sc:`edit_config_file`
+Debug :file:`kitty.conf`            :sc:`debug_config` (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::
-    :class: pre
+.. code-block:: sh
 
-    |ins|
+    _kitty_install_cmd
 
 
 The binaries will be installed in the standard location for your OS,
@@ -24,7 +21,7 @@ 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.
 
 
@@ -33,11 +30,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
-the :file:`.dmg` and install as normal. If you are on Linux, download the tarball
-and extract it into a directory. The |kitty| executable will be in the
+<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 and extract it into a directory. The |kitty| executable will be in the
 :file:`bin` sub-directory.
 
+
 Desktop integration on Linux
 --------------------------------
 
@@ -49,17 +47,30 @@ 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
-    # your PATH)
+    # your system-wide PATH)
     ln -s ~/.local/kitty.app/bin/kitty ~/.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
-    sed -i "s|Icon=kitty|Icon=/home/$USER/.local/kitty.app/share/icons/hicolor/256x256/apps/kitty.png|g" ~/.local/share/applications/kitty.desktop
+    # If you want to open text files and images in kitty via your file manager also add the kitty-open.desktop file
+    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 +83,39 @@ Customizing the installation
 
 * You can install the latest nightly kitty build with ``installer``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |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::
-     :class: pre
+  .. code-block:: sh
 
-     |ins| \\
+     _kitty_install_cmd \\
          installer=nightly dest=/some/other/location
 
 * You can specify a different install location, with ``dest``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |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::
-     :class: pre
+  .. code-block:: sh
 
-     |ins| \\
+     _kitty_install_cmd \\
          launch=n
 
 * You can use a previously downloaded dmg/tarball, with ``installer``:
 
-  .. parsed-literal::
-     :class: pre
+  .. code-block:: sh
 
-     |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
-the following dependencies are installed first.
+|kitty| is designed to run from source, for easy hack-ability. Make sure the
+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
-   build kitty at all, instead, assuming you have installed the official kitty
-   binaries, you can simply set the KITTY_DEVELOP_FROM enviroment variable to
-   point to the directory into which you have checked out the kitty source
-   code. kitty will then load its python code from there. You should use a
-   version of the source that matches the binary version as closely as
-   possible, since the two are tightly coupled.
+   If you are making small changes only to the Python parts of kitty, there is
+   no need to build kitty at all, instead, assuming you have installed the
+   official kitty binaries, you can simply set the :envvar:`KITTY_DEVELOP_FROM`
+   enviroment variable to point to the directory into which you have checked out
+   the kitty source code. kitty will then load its Python code from there. You
+   should use a version of the source that matches the binary version as closely
+   as possible, since the two are tightly coupled.
 
 
 Dependencies
@@ -46,7 +46,9 @@ Build-time dependencies:
 
 * ``gcc`` or ``clang``
 * ``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``
@@ -77,9 +79,8 @@ You can run |kitty|, as::
 
     ./kitty/launcher/kitty
 
-If that works, you can create a symlink to the launcher in :file:`~/bin` or
-some other directory on your PATH so that you can run |kitty| using
-just ``kitty``.
+If that works, you can create a symlink to the launcher in :file:`~/bin` or some
+other directory on your PATH so that you can run |kitty| using just ``kitty``.
 
 
 Building kitty.app on macOS from source
@@ -90,25 +91,24 @@ Run::
     make app
 
 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
-you might have to rebuild the app.
+Python and the other dependencies. So if you ever un-install/upgrade those
+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.
-   If you need this functionality, you can try signing the built 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>`_.
+   Apple disallows certain functionality, such as notifications for unsigned
+   applications. If you need this functionality, you can try signing the built
+   :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>`__.
 
 .. note::
-   If you are facing issues with ``linker`` while building,
-   try with a ``brew`` installed python instead, see :iss:`289`
-   for more discussion.
+   If you are facing issues with ``linker`` while building, try with a ``brew``
+   installed Python instead, see :iss:`289` for more discussion.
 
 
 Build and run from source with Nix
@@ -116,89 +116,75 @@ 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
 
-This will install |kitty| into the directory :file:`linux-package`. You can run |kitty|
-with :file:`linux-package/bin/kitty`.  All the files needed to run kitty will be in
-:file:`linux-package/lib/kitty`. The terminfo file will be installed into
-:file:`linux-package/share/terminfo`. Simply copy these files into :file:`/usr` to install
-|kitty|. In other words, :file:`linux-package` is the staging area into which |kitty| is
-installed. You can choose a different staging area, by passing the ``--prefix``
-argument to :file:`setup.py`.
+This will install |kitty| into the directory :file:`linux-package`. You can run
+|kitty| with :file:`linux-package/bin/kitty`. All the files needed to run kitty
+will be in :file:`linux-package/lib/kitty`. The terminfo file will be installed
+into :file:`linux-package/share/terminfo`. Simply copy these files into
+:file:`/usr` to install |kitty|. In other words, :file:`linux-package` is the
+staging area into which |kitty| is installed. You can choose a different staging
+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
-    shell-integration directory in the kitty source code, probably to
+    Installs the shell integration scripts (the contents of the
+    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|.
+This allows users to install the terminfo and shell integration files on servers
+into which they ssh, without needing to install all of |kitty|.
 
 .. note::
-   You need a couple of extra dependencies to build linux-package.
-   :file:`tic` to compile terminfo files, usually found in the
-   development package of :file:`ncurses`. Also, if you are building from
-   a git checkout instead of the released source code tarball, you will
-   need to install the dependencies from ``docs/requirements.txt`` to
-   build the kitty documentation. They can be installed most easily with
-   ``python -m pip -r docs/requirements.txt``.
+   You need a couple of extra dependencies to build linux-package. :file:`tic`
+   to compile terminfo files, usually found in the development package of
+   :file:`ncurses`. Also, if you are building from a git checkout instead of the
+   released source code tarball, you will need to install the dependencies from
+   :file:`docs/requirements.txt` to build the kitty documentation. They can be
+   installed most easily with ``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.
-
-
-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.
+Homebrew or MacPorts as well.

docs/changelog.rst

@@ -4,26 +4,20 @@ Changelog
 |kitty| is a feature-rich, cross-platform, *fast*, GPU based terminal.
 To update |kitty|, :doc:`follow the instructions <binary>`.
 
+.. recent major features {{{
+
 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.
-
-   .. raw:: html
-
-        <video controls width="640" height="360">
-            <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!
+* Automatic :ref:`shell_integration` on remote machines
+* Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote machines
+* 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
 
 
 Shell integration
@@ -36,43 +30,335 @@ 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.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]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- macOS: Allow opening text files, images and directories with kitty when
+  launched using "Open with" in Finder (:iss:`4460`)
+
+- Allow including config files matching glob patterns in :file:`kitty.conf`
+  (:iss:`4533`)
+
+- Shell integration: Fix bash integration not working when ``PROMPT_COMMAND``
+  is used to change the prompt variables (:iss:`4476`)
+
+- Shell integration: Fix cursor shape not being restored to default when
+  running commands in the shell
+
+- Improve the UI of the ask kitten (:iss:`4545`)
+
+- Allow customizing the placement and formatting of the
+  :opt:`tab_activity_symbol` and :opt:`bell_on_tab` symbols
+  by adding them to the :opt:`tab_title_template` (:iss:`4581`, :pull:`4507`)
+
+- macOS: Persist "Secure Keyboard Entry" across restarts to match the behavior
+  of Terminal.app (:iss:`4471`)
+
+- hints kitten: Fix common single letter extension files not being detected
+  (:iss:`4491`)
+
+- Support dotted and dashed underline styles (:pull:`4529`)
+
+- For the vertical and horizontal layouts have the windows arranged on a ring
+  rather than a plane. This means the first and last window are considered
+  neighbors (:iss:`4494`)
+
+- A new action to clear the current selection (:iss:`4600`)
+
+- Shell integration: fish: Fix cursor shape not working with fish's vi mode
+  (:iss:`4508`)
+
+- Shell integration: fish: Dont override fish's native title setting functionality.
+  See `discussion <https://github.com/fish-shell/fish-shell/issues/8641>`__.
+
+- macOS: Fix hiding via :kbd:`cmd+h` not working on macOS 10.15.7 (:iss:`4472`)
+
+- Draw the dots for braille characters more evenly spaced at all font sizes (:iss:`4499`)
+
+- icat kitten: Add options to mirror images and remove their transparency
+  before displaying them (:iss:`4513`)
+
+- macOS: Respect the users system-wide global keyboard shortcut preferences
+  (:iss:`4501`)
+
+- macOS: Fix a few key-presses causing beeps from Cocoa's text input system
+  (:iss:`4489`)
+
+- macOS: Fix using shortcuts from the global menu bar as subsequent key presses
+  in a multi key mapping not working (:iss:`4519`)
+
+- Fix getting last command output not working correctly when the screen is
+  scrolled (:pull:`4522`)
+
+- Show number of windows per tab in the :ac:`select_tab` action (:pull:`4523`)
+
+- macOS: Fix the shift key not clearing pre-edit text in IME (:iss:`4541`)
+
+- Fix clicking in a window to focus it and typing immediately sometimes having
+  unexpected effects if at a shell prompt (:iss:`4128`)
+
+- themes kitten: Allow writing to a different file than :file:`kitty.conf`.
+
+
+0.24.1 [2022-01-06]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Shell integration: Work around conflicts with some zsh plugins (:iss:`4428`)
+
+- Have the zero width space and various other characters from the *Other,
+  formatting* Unicode category be treated as combining characters (:iss:`4439`)
+
+- Fix using ``--shell-integration`` with :file:`setup.py` broken (:iss:`4434`)
+
+- Fix showing debug information not working if kitty's :file:`STDIN` is not a tty
+  (:iss:`4424`)
+
+- Linux: Fix a regression that broke rendering of emoji with variation selectors
+  (:iss:`4444`)
+
+
 0.24.0 [2022-01-04]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -331,7 +617,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

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
-ANSI color table. This allows for various performance optimizations when
-drawing the screen. The problem is that if the user previously used the escape
-codes to change these colors herself, then running the full screen application
-will lose her changes even after it exits. To avoid this, kitty introduces a
-new pair of *OSC* escape codes to push and pop the current color values from a
+set the default foreground, background, selection and cursor colors and the ANSI
+color table. This allows for various performance optimizations when drawing the
+screen. The problem is that if the user previously used the escape codes to
+change these colors themselves, then running the full screen application will
+lose those changes even after it exits. To avoid this, kitty introduces a new
+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
-background, default foreground, selection background, selection foreground and
-cursor color and the 256 colors of the ANSI color table.
+These escape codes save/restore the colors, default background, default
+foreground, selection background, selection foreground and cursor color and the
+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,7 +13,7 @@ import subprocess
 import sys
 import time
 from functools import partial
-from typing import Any, Callable, Dict, Iterable, List, Match, Optional, Tuple
+from typing import Any, Callable, Dict, Iterable, List, Tuple
 
 from docutils import nodes
 from docutils.parsers.rst.roles import set_classes
@@ -22,16 +22,13 @@ from pygments.token import (  # type: ignore
     Comment, Keyword, Literal, Name, Number, String, Whitespace
 )
 from sphinx import addnodes, version_info
-from sphinx.builders.html.transforms import KeyboardTransform
 from sphinx.util.logging import getLogger
 
-KeyboardTransform.builders = ('html', 'dirhtml')  # type: ignore
-
 kitty_src = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 if kitty_src not in sys.path:
     sys.path.insert(0, kitty_src)
 
-from kitty.conf.types import Definition  # noqa
+from kitty.conf.types import Definition, expand_opt_references  # noqa
 from kitty.constants import str_version, website_url  # noqa
 
 # config {{{
@@ -62,6 +59,7 @@ extensions = [
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
     'sphinx_copybutton',
     'sphinx_inline_tabs',
     "sphinxext.opengraph",
@@ -87,7 +85,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.
@@ -106,6 +104,10 @@ rst_prolog = '''
 '''.replace('VERSION', str_version)
 smartquotes_action = 'qe'  # educate quotes and ellipses but not dashes
 
+string_replacements = {
+    '_kitty_install_cmd': 'curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh /dev/stdin',
+}
+
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -170,24 +172,11 @@ texinfo_documents = [
 
 # GitHub linking inline roles {{{
 
-def num_role(
-    which: str, name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
-) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
-    ' Link to a github issue '
-    try:
-        issue_num = int(text)
-        if issue_num <= 0:
-            raise ValueError
-    except ValueError:
-        msg = inliner.reporter.error(
-            'GitHub issue number must be a number greater than or equal to 1; '
-            '"%s" is invalid.' % text, line=lineno)
-        prb = inliner.problematic(rawtext, rawtext, msg)
-        return [prb], [msg]
-    url = f'https://github.com/kovidgoyal/kitty/{which}/{issue_num}'
-    set_classes(options)
-    node = nodes.reference(rawtext, f'#{issue_num}', refuri=url, **options)
-    return [node], []
+extlinks = {
+    'iss': ('https://github.com/kovidgoyal/kitty/issues/%s', '#%s'),
+    'pull': ('https://github.com/kovidgoyal/kitty/pull/%s', '#%s'),
+    'disc': ('https://github.com/kovidgoyal/kitty/discussions/%s', '#%s'),
+}
 
 
 def commit_role(
@@ -215,6 +204,13 @@ def commit_role(
 def write_cli_docs(all_kitten_names: Iterable[str]) -> None:
     from kitty.cli import option_spec_as_rst
     from kitty.launch import options_spec as launch_options_spec
+    from kittens.ssh.copy import option_text
+    from kittens.ssh.options.definition import copy_message
+    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
+        ))
     with open('generated/launch.rst', 'w') as f:
         f.write(option_spec_as_rst(
             appname='launch', ospec=launch_options_spec, heading_char='_',
@@ -232,7 +228,8 @@ if you specify a program-to-run you can use the special placeholder
     from kitty.remote_control import cli_msg, global_options_spec
     with open('generated/cli-kitty-at.rst', 'w') as f:
         p = partial(print, file=f)
-        p('kitty @\n' + '-' * 80)
+        p('kitty @')
+        p('-' * 80)
         p('.. program::', 'kitty @')
         p('\n\n' + as_rst(
             global_options_spec, message=cli_msg, usage='command ...', appname='kitty @'))
@@ -240,7 +237,8 @@ if you specify a program-to-run you can use the special placeholder
         for cmd_name in sorted(all_command_names()):
             func = command_for_name(cmd_name)
             p(f'.. _at_{func.name}:\n')
-            p('kitty @', func.name + '\n' + '-' * 120)
+            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
@@ -249,12 +247,12 @@ if you specify a program-to-run you can use the special placeholder
         if data:
             with open(f'generated/cli-kitten-{kitten}.rst', 'w') as f:
                 p = partial(print, file=f)
-                p('.. program::', f'kitty +kitten {kitten}')
-                p(f'\nSource code for {kitten}')
+                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}>`_.')
                 p('\nCommand Line Interface')
-                p('-' * 72, file=f)
+                p('-' * 72)
                 p('\n\n' + option_spec_as_rst(
                     data['options'], message=data['help_text'], usage=data['usage'], appname=f'kitty +kitten {kitten}',
                     heading_char='^'))
@@ -306,8 +304,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']
@@ -379,19 +385,6 @@ def link_role(
     return [node], []
 
 
-def expand_opt_references(conf_name: str, text: str) -> str:
-    conf_name += '.'
-
-    def expand(m: Match[str]) -> str:
-        ref = m.group(1)
-        if '<' not in ref and '.' not in ref:
-            full_ref = conf_name + ref
-            return ':opt:`{} <{}>`'.format(ref, full_ref)
-        return str(m.group())
-
-    return re.sub(r':opt:`(.+?)`', expand, text)
-
-
 opt_aliases: Dict[str, str] = {}
 shortcut_slugs: Dict[str, Tuple[str, str]] = {}
 
@@ -414,7 +407,7 @@ def parse_opt_node(env: Any, sig: str, signode: Any) -> str:
             opt_aliases[optname] = firstname
         count += 1
     if not firstname:
-        raise ValueError('{} is not a valid opt'.format(sig))
+        raise ValueError(f'{sig} is not a valid opt')
     return firstname
 
 
@@ -425,23 +418,33 @@ 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:
         conf_name, opt = 'kitty', conf_name
-    full_name = conf_name + '.' + opt
+    full_name = f'{conf_name}.{opt}'
     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:
         conf_name, slug = 'kitty', conf_name
-    full_name = conf_name + '.' + slug
+    full_name = f'{conf_name}.{slug}'
     try:
         target, stitle = shortcut_slugs[full_name]
     except KeyError:
-        logger.warning('Unknown shortcut: {}'.format(target), location=refnode)
+        logger.warning(f'Unknown shortcut: {target}', location=refnode)
     else:
         if not has_explicit_title:
             title = stitle
@@ -470,6 +473,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)
@@ -516,13 +528,12 @@ 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)
     app.add_role('link', link_role)
-    app.add_role('iss', partial(num_role, 'issues'))
-    app.add_role('pull', partial(num_role, 'pull'))
-    app.add_role('disc', partial(num_role, 'discussions'))
     app.add_role('commit', commit_role)
     # monkey patch sphinx_inline_tabs to avoid a warning about parallel reads
     # see https://github.com/pradyunsg/sphinx-inline-tabs/issues/26

docs/conf.rst

@@ -3,38 +3,47 @@ kitty.conf
 
 .. highlight:: conf
 
-|kitty| is highly customizable, everything from keyboard shortcuts, to
-rendering frames-per-second. See below for an overview of all customization
-possibilities.
+|kitty| is highly customizable, everything from keyboard shortcuts, to rendering
+frames-per-second. See below for an overview of all customization possibilities.
 
-You can open the config file within kitty by pressing :sc:`edit_config_file`.
-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 the :sc:`debug_config`
-(:kbd:`⌘+⌥+f6` on macOS) key.
+You can open the config file within kitty by pressing :sc:`edit_config_file`
+(:kbd:`⌘+,` on macOS). A :file:`kitty.conf` with commented default
+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).
 
 .. _confloc:
 
 |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``
-environment variable. See the :option:`kitty --config` option for full details.
+:option:`kitty --config` option or use the :envvar:`KITTY_CONFIG_DIRECTORY`
+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
-in the line.
+character. This works only if the ``#`` character is the first character in the
+line.
+
+.. _include:
 
 You can include secondary config files via the :code:`include` directive.  If
-you use a relative path for include, it is resolved with respect to the
+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`.  For example::
+:code:`USER=name`. 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
@@ -45,17 +54,17 @@ Sample kitty.conf
 
 .. only:: html
 
-    You can download a sample :file:`kitty.conf` file with all default settings and
-    comments describing each setting by clicking: :download:`sample kitty.conf
-    </generated/conf/kitty.conf>`.
+    You can download a sample :file:`kitty.conf` file with all default settings
+    and comments describing each setting by clicking: :download:`sample
+    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
-   file with full documentation and all settings commented out. If you
-   have a pre-existing kitty.conf, then that will be used instead, delete
-   it to see the sample file.
+   :sc:`edit_config_file` shortcut in kitty. This will generate a config file
+   with full documentation and all settings commented out. If you have a
+   pre-existing :file:`kitty.conf`, then that will be used instead, delete it to
+   see the sample file.
 
 
 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
-`this discussion <https://github.com/kovidgoyal/kitty/issues/160#issuecomment-346470545>`_
-and `this FAQ <https://invisible-island.net/ncurses/ncurses.faq.html#bce_mismatches>`_
+(bce)* capability. See :iss:`this discussion <160#issuecomment-346470545>`
+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
-rectangular region of the screen from (3, 4) to (10, 11), you use::
+For example, to set the background color to blue in a rectangular region of the
+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
-show title and body.  Clicking on the notification can optionally focus the
-window it came from, and/or send an escape code back to the application running
-in that window.
+notifications. It is easy to use from shell scripts and fully extensible to show
+title and body. Clicking on the notification can optionally focus the window it
+came from, and/or send an escape code back to the application running in that
+window.
 
-The design of the escape code is partially based on the discussion in
-the defunct
-`terminal-wg <https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/13>`_
+The design of the escape code is partially based on the discussion in the
+defunct `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,27 @@ 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
-can only take the values ``0`` and ``1``. A value of ``0`` means the
-notification is not yet done and the terminal emulator should hold off
-displaying it. A value of ``1`` means the notification is done, and should be
-displayed. You can specify the title or body multiple times and the terminal
-emulator will concatenate them, thereby allowing arbitrarily long text
-(terminal emulators are free to impose a sensible limit to avoid
-Denial-of-Service attacks).
+``[a-zA-Z0-9_-+.]``. The ``d`` key stands for *done* and can only take the
+values ``0`` and ``1``. A value of ``0`` means the notification is not yet done
+and the terminal emulator should hold off displaying it. A value of ``1`` means
+the notification is done, and should be displayed. You can specify the title or
+body multiple times and the terminal emulator will concatenate them, thereby
+allowing arbitrarily long text (terminal emulators are free to impose a sensible
+limit to avoid Denial-of-Service attacks).
 
 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
-separated set of values, ``report`` and ``focus``. The value ``focus`` means
-focus the window from which the notification was issued and is the default.
-``report`` means send an escape code back to the application. The format of the
-returned escape code is::
+was activated. This is controlled by the ``a`` key which takes a comma separated
+set of values, ``report`` and ``focus``. The value ``focus`` means focus the
+window from which the notification was issued and is the default. ``report``
+means send an escape code back to the application. The format of the returned
+escape code is::
 
     <OSC> 99 ; i=identifier ; <terminator>
 
@@ -87,9 +85,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
-   allow displaying custom icons on a notification, at all, it was decided to
-   leave it out of the spec for the time being.
+   the notification, however, given that some platforms, such as legacy versions
+   of macOS, don't allow displaying custom images on a notification, it was
+   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 +105,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 +116,6 @@ Key      Value                 Default    Description
 
 
 .. note::
-   |kitty| also supports the legacy OSC 9 protocol developed by iTerm2 for
-   desktop notifications.
+   |kitty| also supports the `legacy OSC 9 protocol developed by iTerm2
+   <https://iterm2.com/documentation-escape-codes.html>`__ for desktop
+   notifications.

docs/faq.rst

@@ -6,34 +6,36 @@ 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
-standard.  All characters are rendered in a single cell unless 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 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.
-misuse unicode characters from the private use area to represent symbols. Often
-these symbols are square and should be rendered in two cells.  However, since
-private use area symbols all have their width set to one in the unicode
+Some programs, like Powerline, vim with fancy gutter symbols/status-bar, etc.
+use Unicode characters from the private use area to represent symbols. Often
+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
 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
-be ``xterm-kitty``. vim uses *background color erase* even if the terminfo file
-does not contain the ``bce`` capability. This is a bug in vim. You can work around
-it by adding the following to your vimrc::
+First make sure you have not changed the :envvar:`TERM` environment variable, it
+should be ``xterm-kitty``. vim uses *background color erase* even if the
+terminfo file does not contain the ``bce`` capability. This is a bug in vim. You
+can work around it by adding the following to your vimrc::
 
     let &t_ut=''
 
-See :doc:`here <deccara>` for why |kitty| does not support background color erase.
+See :doc:`here <deccara>` for why |kitty| does not support background color
+erase.
 
 
 I get errors about the terminal being unknown or opening the terminal failing when SSHing into a different computer?
@@ -45,42 +47,33 @@ terminfo files to the server::
 
     kitty +kitten ssh myserver
 
-This ssh kitten takes all the same command line arguments
-as ssh, you can alias it to ssh in your shell's rc files to avoid having to
-type it each time::
+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::
 
-    alias ssh="kitty +kitten ssh"
+    alias s="kitty +kitten ssh"
 
-Remember to also setup :ref:`shell_integration` for completion and other
-niceties.
-
-If for some reason that does not work (typically because the server is using a
-non POSIX compliant shell as ``/bin/sh``), you can try using it with ``python``
-instead::
-
-    kitty +kitten ssh use-python myserver
-
-If that also fails, perhaps because python is not installed on the remote
-server, use the following one-liner instead (it
-is slower as it needs to ssh into the server twice, but will work with most
-servers)::
+If the ssh kitten fails, use the following one-liner instead (it 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 behind a proxy (like Balabit) that prevents this, you must redirect the
-1st command to a file, copy that to the server and run ``tic`` manually.  If you
-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`.
+If you are behind a proxy (like Balabit) that prevents this, or :program:`tic`
+comes with macOS that does not support reading from 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`.
 
 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.
+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 -C xterm-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
@@ -92,22 +85,29 @@ command to apply your change (on the server)::
 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/`.
+Make sure the :envvar:`TERM` environment variable, is ``xterm-kitty``.  And
+either the :envvar:`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::
+For macOS, you may also need to put that file under :file:`~/.terminfo/78/`::
+
+    mkdir -p ~/.terminfo/{78,x}
+    ln -snf ../x/xterm-kitty ~/.terminfo/78/xterm-kitty
+    tic -x -o ~/.terminfo "$KITTY_INSTALLATION_DIR/terminfo/kitty.terminfo"
+
+Note that :program:`sudo` might remove :envvar:`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 :program:`sudo` to set it or if
+that is not supported, insert an :program:`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::
+You can configure :program:`sudo` to preserve :envvar:`TERMINFO` by running
+``sudo visudo`` and adding the following line::
 
     Defaults env_keep += "TERM TERMINFO"
 
@@ -131,12 +131,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`.
-The shortcut mapping technique has the same syntax as the remote control
-command, for details, see :ref:`at_set-colors`.
+Or you can enable :doc:`remote control <remote-control>` for |kitty| and use
+:ref:`at_set-colors`. The shortcut mapping technique has the same syntax as the
+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 +156,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 +169,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``.
-Note that this file is *only read* when running via the GUI.
+from the GUI, i.e. by clicking the |kitty| application icon or using
+``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:
-:file:`/Applications/kitty.app/Contents/MacOS/kitty`.
+You can, of course, also run |kitty| from a terminal with command line options,
+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 +185,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
-if 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
-the closing sequence. Press :kbd:`ctrl+shift+delete` to reset the terminal.
+are control codes. Some of these control codes are of arbitrary length, so if
+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 the
+closing sequence. Press :sc:`reset_terminal` to reset the terminal.
 
 If you do want to cat unknown data, use ``cat -v``.
 
@@ -192,29 +196,34 @@ 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
-rendered character on the GPU, and rendering them all in parallel. This means
-it is a strictly character cell based display. As such it can use only
-monospace fonts, since every cell in the grid has to be the same size.
-Furthermore, it needs fonts to be freely resizable, so it does not support
-bitmapped fonts.
+|kitty| achieves its stellar performance by caching alpha masks of each rendered
+character on the GPU, and rendering them all in parallel. This means it is a
+strictly character cell based display. As such it can use only monospace fonts,
+since every cell in the grid has to be the same size. Furthermore, it needs
+fonts to be freely resizable, so it does not support bitmapped fonts.
 
 .. note::
-   If you are trying to use a font patched with NERD font symbols, dont do that
-   as patching destroys fonts. There is no need, simply install the standalone
-   NERD font, kitty should pick up symbols from it automatically, and you can
-   tell it to do so explicitly in case it doesnt with the :opt:`symbol_map`
-   directive::
+   If you are trying to use a font patched with `Nerd Fonts
+   <https://nerdfonts.com/>`__ symbols, don't do that as patching destroys
+   fonts. There is no need, simply install the standalone ``Symbols Nerd Font``
+   (the file :file:`NerdFontsSymbolsOnly.zip` from the `Nerd Fonts releases page
+   <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
+        symbol_map U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0C8,U+E0CA,U+E0CC-U+E0D2,U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E62F,U+E700-U+E7C5,U+F000-U+F2E0,U+F300-U+F31C,U+F400-U+F4A9,U+F500-U+F8FF Symbols Nerd Font
 
-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::
+   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
-glyph widths in the font. If for some reason fontconfig concludes your favorite
+Note that the spacing property is calculated by fontconfig based on actual glyph
+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 +245,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?
@@ -245,7 +254,7 @@ How can I assign a single global shortcut to bring up the kitty terminal?
 Bringing up applications on a single key press is the job of the window
 manager/desktop environment. For ways to do it with kitty (or indeed any
 terminal) in different environments,
-see `here <https://github.com/kovidgoyal/kitty/issues/45>`_.
+see :iss:`here <45>`.
 
 
 I do not like the kitty icon!
@@ -270,9 +279,13 @@ homepage:
    :target: https://github.com/hristost/kitty-alternative-icon
    :width: 256
 
+.. image:: https://github.com/igrmk/whiskers/raw/main/whiskers.svg
+   :target: https://github.com/igrmk/whiskers
+   :width: 256
+
 On macOS you can change the icon by following the steps:
 
-#. Find :file:`kitty.app` in the Applications folder, select it and press :kbd:`⌘+i`
+#. 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::
 
@@ -292,7 +305,10 @@ 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`.
 
 How do I open a new window or tab with the same working directory as the current window?
 --------------------------------------------------------------------------------------------
@@ -319,8 +335,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
-files such as ``XDG_*, KITTY_CONFIG_DIRECTORY``.
+related to localization, such as :envvar:`LANG`, ``LC_*`` and loading of
+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,41 +353,42 @@ sorts of places where they may or may not work.
 I am using tmux and have a problem
 --------------------------------------
 
-First, terminal multiplexers are `a bad idea
-<https://github.com/kovidgoyal/kitty/issues/391#issuecomment-638320745>`_, do
-not use them, if at all possible. kitty contains features that do all of what
+First, terminal multiplexers are :iss:`a bad idea <391#issuecomment-638320745>`,
+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
-cause gibberish on screen when pressing keys (:iss:`3541`).
+Using ancient versions of tmux such as 1.8 will cause gibberish on screen when
+pressing keys (:iss:`3541`).
 
-If you are using tmux with multiple terminals or you start it under one
-terminal and then switch to another and these terminals have different TERM
-variables, tmux will break. You will need to restart it as tmux does not
-support multiple terminfo definitions.
+If you are using tmux with multiple terminals or you start it under one terminal
+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 support
+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.
-they may or may not work, depending on the whims of tmux's maintainer, your
-version of tmux, etc.
+:doc:`styled underlines </underlines>`, :doc:`desktop notifications
+</desktop-notifications>`, :doc:`extended keyboard support
+</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
-modern systems, when allocating memory to a process, the C library functions
-will typically allocate memory in large blocks, and give the process chunks of
-these blocks. When the process frees a chunk, the C library will not
+:program:`top` is not a good way to measure process memory usage. That is
+because on modern systems, when allocating memory to a process, the C library
+functions will typically allocate memory in large blocks, and give the process
+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
-using it.
+application has released the memory, :program:`top` will still claim the process
+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
 
@@ -384,18 +401,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
-with ``top`` by adding ``--pages-as-heap=yes`` then you will see that memory
-allocated in malloc is not freed in free. This can be further refined if you
-use `glibc`` as your C library by setting the environment variable
-``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free memory
-allocated in sizes of more than 64 bytes. With this set, memory usage will
-climb high, then fall when closing windows, but not fall all the way back. The
-remaining used memory can be investigated using valgrind again, and it will
+For those interested, you can get a similar profile out of :program:`valgrind`
+as you get with :program:`top` by adding ``--pages-as-heap=yes`` then you will
+see that memory allocated in malloc is not freed in free. This can be further
+refined if you use ``glibc`` as your C library by setting the environment
+variable ``MALLOC_MMAP_THRESHOLD_=64``. This will cause free to actually free
+memory allocated in sizes of more than 64 bytes. With this set, memory usage
+will climb high, then fall when closing windows, but not fall all the way back.
+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?
 -------------------------------------------------------------------------------------------
 
@@ -419,4 +437,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

@@ -37,7 +37,8 @@ Glossary
    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>`__.
 
 .. _env_vars:
 
@@ -45,6 +46,7 @@ Environment variables
 ------------------------
 
 Variables that influence kitty behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. envvar:: KITTY_CONFIG_DIRECTORY
 
@@ -57,11 +59,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
-   instance, opening :file:`kitty.conf` in response to :sc:`edit_config_file`.
-
+   The terminal based text editor (such as :program:`vi` or :program:`nano`)
+   kitty uses, when, for instance, opening :file:`kitty.conf` in response to
+   :sc:`edit_config_file`.
 
 .. envvar:: EDITOR
 
@@ -78,13 +86,41 @@ 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.
+
 
 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
-   macOS user settings form a valid locale.
+   This is only set on macOS. If the country and language from the macOS user
+   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
@@ -131,7 +167,7 @@ Variables that kitty sets when running child programs
 
    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.
 
 
@@ -152,10 +188,28 @@ Variables that kitty sets when running child programs
 .. 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.

docs/graphics-protocol.rst

@@ -12,8 +12,7 @@ emulator. The major design goals are:
   below as well as above the text, with alpha blending. The graphics should also scroll with the text, automatically.
 * Should use optimizations when the client is running on the same computer as the terminal emulator.
 
-For some discussion regarding the design choices, see `#33
-<https://github.com/kovidgoyal/kitty/issues/33>`_.
+For some discussion regarding the design choices, see :iss:`33`.
 
 To see a quick demo, inside a |kitty| terminal run::
 
@@ -32,6 +31,7 @@ Some programs and libraries that use the kitty graphics protocol:
 * `ranger <https://github.com/ranger/ranger>`_ - a terminal file manager, with
   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
 * `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
@@ -47,6 +47,8 @@ Some programs and libraries that use the kitty graphics protocol:
 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
@@ -109,7 +111,7 @@ features of the graphics protocol:
 
     def serialize_gr_command(**cmd):
         payload = cmd.pop('payload', None)
-        cmd = ','.join('{}={}'.format(k, v) for k, v in cmd.items())
+        cmd = ','.join(f'{k}={v}' for k, v in cmd.items())
         ans = []
         w = ans.append
         w(b'\033_G'), w(cmd.encode('ascii'))
@@ -326,14 +328,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
-graphics protocol. We intend that any terminal emulator that wishes to support
-it can do so. To check if a terminal emulator supports the graphics protocol the best way
-is to send the above *query action* followed by a request for the
-`primary device attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you
-get back an answer for the device attributes without getting back an answer for
-the *query action* the terminal emulator does not support the graphics
-protocol.
+As of April 2022, kitty and WezTerm are the only terminal emulators to
+support this graphics protocol completely, with Konsole and wayst having partial support.
+We intend that any terminal emulator that wishes to support it can do so. To
+check if a terminal emulator supports the graphics protocol the best way is to
+send the above *query action* followed by a request for the `primary device
+attributes <https://vt100.net/docs/vt510-rm/DA1.html>`_. If you get back an
+answer for the device attributes without getting back an answer for the *query
+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
@@ -376,7 +378,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>\
 

docs/index.rst

@@ -14,13 +14,13 @@ kitty
     changelog
     integrations
     protocol-extensions
+    press-mentions
 
 
 .. tab:: Fast
 
    * Offloads rendering to the GPU for :doc:`lower system load <performance>`
-   * Uses threaded rendering for
-     `absolutely minimal latency <https://github.com/kovidgoyal/kitty/issues/2701#issuecomment-636497270>`_
+   * Uses threaded rendering for :iss:`absolutely minimal latency <2701#issuecomment-636497270>`
    * Performance tradeoffs can be :ref:`tuned <conf-kitty-performance>`
 
 .. tab:: Capable
@@ -61,7 +61,7 @@ kitty
 
     .. raw:: html
 
-        <video controls width="640" height="360">
+        <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>

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,173 @@
 #!/bin/sh
-#
-# installer.sh
 # Copyright (C) 2018 Kovid Goyal <kovid at kovidgoyal.net>
 #
 # Distributed under terms of the GPLv3 license.
-#
 
-python=$(command -v python3)
-if [ -z "$python" ]; then
-    python=$(command -v python2)
-fi
-if [ -z "$python" ]; then
-    python=$(command -v python2.7)
-fi
-if [ -z "$python" ]; then
-    python=$(command -v python)
-fi
-if [ -z "$python" ]; then
-    python=python
-fi
+{ \unalias command; \unset -f command; } >/dev/null 2>&1
+tdir=''
+cleanup() {
+    [ -n "$tdir" ] && {
+        command rm -rf "$tdir"
+        tdir=''
+    }
+}
 
-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'
-# {{{
-# HEREDOC_START
-#!/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
+detect_network_tool() {
+    if command -v curl 2> /dev/null > /dev/null; then
+        fetch() {
+            command curl -fL "$1"
+        }
+        fetch_quiet() {
+            command curl -fsSL "$1"
+        }
+    elif command -v wget 2> /dev/null > /dev/null; then
+        fetch() {
+            command wget -O- "$1"
+        }
+        fetch_quiet() {
+            command wget --quiet -O- "$1"
+        }
+    else
+        die "Neither curl nor wget available, cannot download kitty"
+    fi
+}
 
 
-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)
+detect_os() {
+    arch=""
+    case "$(command uname)" in
+        'Darwin') OS="macos";;
+        'Linux')
+            OS="linux"
+            case "$(command uname -m)" in
+                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):
-        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()
-# }}}
+get_release_url() {
+    release_version=$(fetch_quiet "https://sw.kovidgoyal.net/kitty/current-version.txt")
+    [ $? -ne 0 -o -z "$release_version" ] && die "Could not get kitty latest release version"
+    get_file_url "v$release_version" "$release_version"
+}
 
 
-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')
+get_nightly_url() {
+    get_file_url "nightly" "nightly"
+}
 
+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):
-    print('Will download and install', os.path.basename(dest))
-    reporter = Reporter(os.path.basename(dest))
+linux_install() {
+    if [ "$installer_is_file" = "y" ]; then
+        command tar -C "$dest" "-xJof" "$installer"
+    else
+        printf '%s\n\n' "Downloading from: $url"
+        fetch "$url" | command tar -C "$dest" "-xJof" "-"
+    fi
+}
 
-    # 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)))
+macos_install() {
+    tdir=$(command mktemp -d "/tmp/kitty-install-XXXXXXXXXXXX")
+    [ "$installer_is_file" != "y" ] && {
+        installer="$tdir/kitty.dmg"
+        printf '%s\n\n' "Downloading from: $url"
+        fetch "$url" > "$installer" || die "Failed to download: $url"
+    }
+    command mkdir "$tdir/mp"
+    command hdiutil attach "$installer" "-mountpoint" "$tdir/mp" || die "Failed to mount kitty.dmg"
+    command ditto -v "$tdir/mp/kitty.app" "$dest"
+    rc="$?"
+    command hdiutil detach "$tdir/mp"
+    command rm -rf "$tdir"
+    tdir=''
+    [ "$rc" != "0" ] && die "Failed to copy kitty.app from mounted dmg"
+}
 
+prepare_install_dest() {
+    printf "%s\n" "Installing to $dest"
+    command rm -rf "$dest"
+    command mkdir -p "$dest" || die "Failed to create the directory: $dest"
+}
 
-def clean_cache(cache, fname):
-    for x in os.listdir(cache):
-        if fname not in x:
-            os.remove(os.path.join(cache, x))
+exec_kitty() {
+    if [ "$OS" = "macos" ]; then
+        exec "open" "$dest"
+    else
+        exec "$dest/bin/kitty" "--detach"
+    fi
+    die "Failed to launch kitty"
+}
 
+main() {
+    detect_os
+    parse_args "$@"
+    detect_network_tool
+    get_download_url
+    prepare_install_dest
+    if [ "$OS" = "macos" ]; then
+        macos_install
+    else
+        linux_install
+    fi
+    [ "$launch" = "y" ] && exec_kitty
+    exit 0
+}
 
-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()
-
-# HEREDOC_END
-# }}}
-INSTALLER_HEREDOC
+main "$@"

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`
-that allow it to be integrated with other tools seamlessly.
+:doc:`kittens/custom` and :doc:`kittens/icat` that allow it to be integrated
+with other tools seamlessly.
 
 
 Image and document viewers
@@ -30,19 +30,22 @@ 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_koneko:
 
@@ -61,8 +64,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
-knowledge base application that uses kitty's graphics protocol for images.
+Command line and local web note-taking, bookmarking, archiving, and knowledge
+base application that uses kitty's graphics protocol for images.
 
 .. _tool_w3m:
 
@@ -75,9 +78,9 @@ images.
 
 `timg <https://github.com/hzeller/timg>`_
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-A terminal image and video viewer, that displays static and animated
-images or plays videos. Fast multi-threaded loading, JPEG exif rotation,
-grid view and connecting to the webcam make it a versatile terminal utility.
+A terminal image and video viewer, that displays static and animated images or
+plays videos. Fast multi-threaded loading, JPEG exif rotation, grid view and
+connecting to the webcam make it a versatile terminal utility.
 
 
 System and data visualisation tools
@@ -87,7 +90,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 +109,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,
-powered by kitty's graphics protocol for displaying plots
+A text-based user interface for running and editing Jupyter notebooks, powered
+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
-output in kitty with the following bash snippet:
+A graphing and data visualization tool that can be made to display its output in
+kitty with the following bash snippet:
 
 .. code-block:: sh
 
@@ -171,26 +175,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
-such a split windows, previews, REPLs etc.
+|kitty| can be integrated into many different terminal based text editors to add
+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 +208,7 @@ 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
 
 
 Scrollback manipulation
@@ -228,21 +234,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
-no tabs are present
+Use keys to either control tabs or pass them onto running applications if no
+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
-no scrollback buffer is present
+Use keys to either scroll or pass them onto running applications if no
+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

@@ -37,7 +37,9 @@ In addition to kitty, this protocol is also implemented in:
 * The `foot terminal <https://codeberg.org/dnkl/foot/issues/319>`__
 * The `notcurses library
   <https://github.com/dankamongmen/notcurses/issues/2131>`__
+* 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>`__
 
 .. versionadded:: 0.20.0
 
@@ -376,7 +378,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.
 
@@ -441,6 +443,7 @@ mode* (the ``smkx/rmkx`` terminfo capabilities). This form is used only in
     "F10",       "kf10",       "CSI 21 ~"
     "F11",       "kf11",       "CSI 23 ~"
     "F12",       "kf12",       "CSI 24 ~"
+    "MENU",      "kf16",       "CSI 29 ~"
 
 There are a few more functional keys that have special cased legacy encodings.
 These are present because they are commonly used and for the sake of legacy

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
-all kitty windows (or a subset as desired).
+The ``broadcast`` kitten can be used to type text simultaneously in all
+: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
-are selected.
+You can use the options described below to control which windows 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/custom.rst

@@ -1,21 +1,20 @@
 Custom kittens
 =================
 
-You can easily create your own kittens to extend kitty. They are just
-terminal programs written in Python. When launching a kitten, kitty will
-open an overlay window over the current window and optionally pass the
-contents of the current window/scrollback to the kitten over its :file:`STDIN`.
-The kitten can then perform whatever actions it likes, just as a normal
-terminal program. After execution of the kitten is complete, it has access
-to the running kitty instance so it can perform arbitrary actions
-such as closing windows, pasting text, etc.
+You can easily create your own kittens to extend kitty. They are just terminal
+programs written in Python. When launching a kitten, kitty will open an overlay
+window over the current window and optionally pass the contents of the current
+window/scrollback to the kitten over its :file:`STDIN`. The kitten can then
+perform whatever actions it likes, just as a normal terminal program. After
+execution of the kitten is complete, it has access to the running kitty instance
+so it can perform arbitrary actions 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`
-(you might need to adjust the path to wherever the kitty config folder is on
-your machine).
+Create a file in the kitty config directory, :file:`~/.config/kitty/mykitten.py`
+(you might need to adjust the path to wherever the :ref:`kitty config directory
+<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,12 @@ 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.
-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.
-Or see below for a list of :ref:`third-party kittens <external_kittens>`,
-that other kitty users have created.
+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
+kittens. Look in the `kittens sub-directory
+<https://github.com/kovidgoyal/kitty/tree/master/kittens>`__ of the kitty source
+code for those. Or see below for a list of :ref:`third-party kittens
+<external_kittens>`, that other kitty users have created.
 
 
 Passing arguments to kittens
@@ -60,36 +60,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
-running in the active kitty window. The special argument ``@selection``
-is replaced by the currently selected text in the active kitty window.
+of the kitten is set to the working directory of whatever program is running in
+the active kitty window. The special argument ``@selection`` is replaced by the
+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()``
-function, telling kitty what kind of input your kitten would like. For example:
+and/or the scrollback buffer, you just need to add an annotation to the
+``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,
-described in the table below:
+:file:`STDIN`. There are many other types of input you can ask for, described in
+the table below:
 
 .. table:: Types of input to kittens
     :align: left
@@ -121,31 +125,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,
-   :ref:`shell_integration` is required.
+   For the types based on the output of a command, :ref:`shell_integration` is
+   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
-``handle_result()`` function without first running the ``main()`` function.
+terminal program, you can tell the kittens system to run the ``handle_result()``
+function without first running the ``main()`` function.
 
-For example, here is a kitten that "zooms/unzooms" the current terminal window
-by switching to the stack layout or back to the previous layout. This is
-equivalent to the builtin :ref:`action-toggle_layout` action.
+For example, here is a kitten that "zooms in/zooms out" the current terminal
+window by switching to the stack layout or back to the previous layout. This is
+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 +162,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 +173,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 +181,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 +208,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 output of print statements will be visible in the kitten window. Or
-alternately, you can use::
+The part of the kitten that runs in ``main()`` is just a normal program and the
+output of print statements will be visible in the kitten window. Or alternately,
+you can use::
 
     from kittens.tui.loop import debug
     debug('whatever')
 
-The ``debug()`` function is just like ``print()`` except that the output
-will appear in the ``STDOUT`` of the kitty process inside which the kitten is
+The ``debug()`` function is just like ``print()`` except that the output will
+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 +224,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
-of your kitten make the following files.
+configurable, you will need some boilerplate. Put the following files in the
+directory of your kitten.
 
 :file:`kitten_options_definition.py`
 
@@ -311,8 +320,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
-and keyboard shortcuts.
+See `the code <https://github.com/kovidgoyal/kitty/tree/master/kittens/diff>`__
+for the builtin :doc:`diff kitten </kittens/diff>` for examples of creating more
+options and keyboard shortcuts.
 
 .. _external_kittens:
 
@@ -320,12 +330,13 @@ 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
 
-`insert password <https://github.com/kovidgoyal/kitty/issues/1222>`_
+:iss:`insert password <1222>`
     Insert a password from a CLI password manager, taking care to only do it at
     a password prompt.
 

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
-      speed
+    * Does syntax highlighting of the displayed diffs, asynchronously, for
+      maximum speed
 
     * Displays images as well as text diffs, even over SSH
 
@@ -31,11 +31,11 @@ Major Features
 Installation
 ---------------
 
-Simply :ref:`install kitty <quickstart>`.  You also need
-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).
+Simply :ref:`install kitty <quickstart>`.  You also need to have either the `git
+<https://git-scm.com/>`__ program or the :program:`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 +45,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
 
@@ -67,20 +68,20 @@ Keyboard controls
 =========================   ===========================
 Action                      Shortcut
 =========================   ===========================
-Quit                        :kbd:`q`, :kbd:`ctrl+c`, :kbd:`Esc`
-Scroll line up              :kbd:`k`, :kbd:`Up`
-Scroll line down            :kbd:`j`, :kbd:`Down`
+Quit                        :kbd:`Q`, :kbd:`Ctrl+C`, :kbd:`Esc`
+Scroll line up              :kbd:`K`, :kbd:`Up`
+Scroll line down            :kbd:`J`, :kbd:`Down`
 Scroll page up              :kbd:`PgUp`
 Scroll page down            :kbd:`PgDn`
 Scroll to top               :kbd:`Home`
 Scroll to bottom            :kbd:`End`
 Scroll to next page         :kbd:`Space`, :kbd:`PgDn`
 Scroll to previous page     :kbd:`PgUp`
-Scroll to next change       :kbd:`n`
-Scroll to previous change   :kbd:`p`
+Scroll to next change       :kbd:`N`
+Scroll to previous change   :kbd:`P`
 Increase 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:`=`
 Search forwards             :kbd:`/`
 Search backwards            :kbd:`?`
@@ -93,7 +94,7 @@ Scroll to previous match    :kbd:`<`, :kbd:`,`
 Integrating with git
 -----------------------
 
-Add the following to `~/.gitconfig`:
+Add the following to :file:`~/.gitconfig`:
 
 .. code-block:: ini
 
@@ -119,24 +120,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
-infrastructure I created for all of kitty's other kittens to reduce the amount
-of code needed (the entire implementation is under 2000 lines of code).
+</keyboard-protocol>`, etc. It also leverages terminal program infrastructure
+I created for all of kitty's other kittens to reduce the amount of code needed
+(the entire implementation is under 2000 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
-your :ref:`kitty config folder <confloc>`. See below for the supported
-configuration directives.
+the default lines of context, etc. by creating a :file:`diff.conf` file in your
+:ref:`kitty config folder <confloc>`. See below for the supported configuration
+directives.
 
 
 .. include:: /generated/conf-kitten-diff.rst
@@ -145,7 +145,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
-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
+|kitty| has a *hints mode* to select and act on arbitrary text snippets
+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 default web
 browser.
 
 .. figure:: ../screenshots/hints_mode.png
@@ -13,25 +13,35 @@ browser.
 
     URL hints mode
 
-Similarly, you can press :sc:`insert_selected_path` to
-select anything that looks like a path or filename and then insert it into the
-terminal, very useful for picking files from the output of a ``git`` or ``ls`` command and
-adding them to the command line for the next command.
+Similarly, you can press :sc:`insert_selected_path` to select anything that
+looks like a path or filename and then insert it into the terminal, very useful
+for picking files from the output of a :program:`git` or :program:`ls` 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
-like a path or filename followed by a colon and a line number and open
-the file in vim at the specified line number. The patterns and editor
-to be used can be modified using options passed to the kitten. For example::
+You can also press :sc:`goto_file_line` to select anything that looks like a
+path or filename followed by a colon and a line number and open the file in
+:program:`vim` at the specified line number. The patterns and editor to be used
+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
-:kbd:`ctrl+g`.
+will open the selected file in a new tab inside `Neovim <https://neovim.io/>`__
+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
-taken for different types of URLs <../open_actions>`.
+for example, by ``ls --hyperlink=auto``. If :program:`ls` comes with your OS
+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
+   starting with that letter are displayed. Pressing the second letter will
+   select that hint or press :kbd:`Enter` or :kbd:`Space` to select the empty
+   hint.
 
 The hints kitten is very powerful to see more detailed help on its various
 options and modes of operation, see below. You can use these options to
@@ -42,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
-you can provide the logic for finding matches and performing actions on them.
-This is best illustrated with an example. Create the file
-:file:`custom-hints.py` in the kitty config directory with the following
-contents:
+selected. This allows the hints kitten to provide the user interface, while you
+can provide the logic for finding matches and performing actions on them. This
+is best illustrated with an example. Create the file :file:`custom-hints.py` in
+the :ref:`kitty config directory <confloc>` with the following contents:
 
 .. code-block:: python
 
@@ -92,9 +101,10 @@ look it up in the Google dictionary.
 
 .. note::
 
-    To avoid having to specify the same command line options on every invocation,
-    you can use the :opt:`action_alias` option in :file:`kitty.conf`, creating aliases
-    that have common sets of options. For example::
+    To avoid having to specify the same command line options on every
+    invocation, you can use the :opt:`action_alias` option in
+    :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
-directly in your favorite editor in the terminal, at the line containing
-the search result, simply by clicking on the result you want.
+<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.
 
 .. versionadded:: 0.19.0
 
@@ -25,19 +24,19 @@ following contents:
     mime text/*
     action launch --type=overlay ${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
-result lines, to open the file in vim at the matching line. If
-you use some editor other than vim, you should adjust the
-:file:`open-actions.conf` file accordingly.
+Hold down the :kbd:`Ctrl+Shift` keys and click on any of the result lines, to
+open the file in :program:`vim` at the matching line. If you use some editor
+other than :program:`vim`, you should adjust the :file:`open-actions.conf` file
+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::
@@ -45,27 +44,42 @@ 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. For that, instead of using an alias create a simple wrapper script named
-:file:`hg` somewhere in your ``PATH``:
+to :program:`rg`. How to do that varies based on the shell:
 
-.. code-block:: sh
 
-    #!/bin/sh
-    exec kitty +kitten hyperlinked_grep "$@"
+.. tab:: zsh
 
-Then, for example, for ZSH, add the following to :file:`.zshrc`::
+    Instead of using an alias, create a simple wrapper script named
+    :program:`hg` somewhere in your :envvar:`PATH`:
 
-    compdef _rg hg
+    .. 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 ripgrep's
+    autocompletion with a fish wrapper function in your :file:`config.fish`
+    or :file:`~/.config/fish/functions/hg.fish`:
+
+    .. code-block:: fish
+
+        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>`.
 
 Hopefully, someday this functionality will make it into some `upstream grep
-<https://github.com/BurntSushi/ripgrep/issues/665>`_
-program directly removing the need for this kitten.
+<https://github.com/BurntSushi/ripgrep/issues/665>`__ program directly removing
+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
-   formatting as the kitten works by parsing the output from ripgrep.
+   they will be forwarded to :program:`rg`, do not use options that change the
+   output formatting as the kitten works by parsing the output from ripgrep.

docs/kittens/icat.rst

@@ -9,8 +9,8 @@ terminal. Using it is as simple as::
     kitty +kitten icat image.jpeg
 
 It supports all image types supported by `ImageMagick
-<https://www.imagemagick.org>`_. It even works over SSH. For details, see
-the :doc:`kitty graphics protocol </graphics-protocol>`.
+<https://www.imagemagick.org>`__. It even works over SSH. For details, see the
+:doc:`kitty graphics protocol </graphics-protocol>`.
 
 You might want to create an alias in your shell's configuration files::
 
@@ -20,14 +20,14 @@ Then you can simply use ``icat image.png`` to view images.
 
 .. note::
 
-    `ImageMagick <https://www.imagemagick.org>`_ must be installed for ``icat`` to
-    work.
+    `ImageMagick <https://www.imagemagick.org>`__ must be installed for icat
+    kitten to work.
 
 .. 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 has added support for it or not.
+    multiplexer such as :program:`screen` or :program:`tmux`, depending on
+    whether the multiplexer has added support for it or not.
 
 
 .. program:: kitty +kitten icat
@@ -35,6 +35,19 @@ 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` and :option:`--print-window-size`.
+:option:`--detect-support`, :option:`--silent` and
+:option:`--print-window-size`.
+
+If you are trying to integrate icat into a complex program like a file manager
+or editor, there are a few things to keep in mind. icat works by communicating
+over the TTY device, it both writes to and reads from the TTY. So it is
+imperative that while it is running the host program does not do any TTY I/O.
+Any key presses or other input from the user on the TTY device will be
+discarded. At a minimum, you should use the :option:`--silent` and
+:option:`--transfer-mode` command line arguments. To be really robust you should
+consider writing proper support for the :doc:`kitty graphics protocol
+</graphics-protocol>` in the program instead. Nowadays there are many libraries
+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
-of your screen, that shows the output from an arbitrary terminal program.
+You can use this kitten to draw a GPU accelerated panel on the edge of your
+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
-print out ``Hello, world!``. You can make the terminal program as complex as
+seconds. Here the terminal program we are running is :program:`sh` with a script
+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
-runtime options controlling its features, etc.
+This kitten is used to query |kitty| from terminal programs about version, values
+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
-is slow, since it requires a roundtrip to the terminal emulator and back.
+pioneered by xterm, so it works over SSH as well. The downside is that it is
+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>`_
-for *XTGETTCAP* to see the syntax for the escape code and read the source
-of this kitten to find the values of the keys for the various queries.
+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 of
+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
-from a computer into which you are SSHed. In your SSH session run::
+|kitty| has the ability to easily *Edit*, *Open* or *Download* files from a
+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
-hyperlinks.
+to install *any* special software on the server, beyond :program:`ls` that
+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
-   remote files from the first SSH host. This is because there is no way for
+   For best results, use this kitten with the :doc:`ssh kitten <./ssh>`.
+   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
-   editing starts you will be asked to enter your password just once,
-   thereafter the SSH connection will be re-used.
+   If you have not setup automatic password-less SSH access, and are not using
+   the ssh kitten, then, when editing
+   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,154 @@
+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`.
+
+.. include:: /generated/conf-kitten-ssh.rst
+
+
+.. _ssh_copy_command:
+
+The copy command
+--------------------
+
+.. include:: /generated/ssh-copy.rst

docs/kittens/themes.rst

@@ -1,8 +1,8 @@
 Changing kitty colors
 ========================
 
-The themes kitten allows you to easily change color themes, from a collection
-of almost two hundred pre-built themes available at `kitty-themes
+The themes kitten allows you to easily change color themes, from a collection of
+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
-can choose between light and dark themes and search by theme name by just
-typing a few characters from the name.
+The kitten allows you to pick a theme, with live previews of the colors. You can
+choose between light and dark themes and search by theme name by just typing a
+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
-any existing color settings in :file:`kitty.conf` so they do not interfere.
+:file:`current-theme.conf` to :file:`kitty.conf`. It also comments out any
+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,9 +40,9 @@ 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:`~/.config/kitty/themes` and the kitten will automatically add them to
-the list of themes. You can use this to modify the builtin themes, by giving
+:file:`themes` sub-directory of the :ref:`kitty config directory <confloc>`,
+usually, :file:`~/.config/kitty/themes`. The kitten will automatically add them
+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
 choose that theme once for your changes to be applied.
@@ -52,13 +53,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
-<https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_, and use the
+repository. `Fork it
+<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 +68,12 @@ available in this kitten automatically.
 Changing the theme non-interactively
 ---------------------------------------
 
-You can specify the theme name as an argument when invoking the kitten
-to have it change to that theme instantly. For example::
+You can specify the theme name as an argument when invoking the kitten to have
+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
-instances. See below for more details on non-interactive operation.
+Will change the theme to ``Dimmed Monokai`` in all running kitty instances. See
+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_
-protocol to transfer only changes to large files.
+hard links, file permissions, times, etc. It even supports the rsync_ protocol
+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
-   protocol </file-transfer-protocol>`.
+   kitten instead. Or write your own script to use the underlying
+   :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
-you an opportunity to review and confirm the files that will be touched.
+use the :option:`--confirm-paths <kitty +kitten transfer --confirm-paths>`
+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
-confirmation. This is to ensure that hostile programs running on a remote
-machine cannot read/write files on your computer without your permission.
-If the remote machine is trusted and the connection between your computer
-and the remote machine is secure, then you can disable the confirmation prompt
-by:
+Normally, when you start a file transfer kitty will prompt you for confirmation.
+This is to ensure that hostile programs running on a remote machine cannot
+read/write files on your computer without your permission. If the remote machine
+is trusted and the connection between your computer and the remote machine is
+secure, then you can disable the confirmation prompt by:
 
-#. Setting the :opt:`file_transfer_confirmation_bypass` option to some
-   password.
+#. Setting the :opt:`file_transfer_confirmation_bypass` option to some password.
 
-#. When invoking the kitten use the :option:`kitty +kitten transfer --permissions-bypass`
-   to supply the password you set in step one.
+#. When invoking the kitten use the :option:`--permissions-bypass
+   <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
-transfer --transmit-deltas` option. Note that this will actually be slower when
-transferring small files because of round trip overhead, so use with care.
+differences between files. To turn it on use the :option:`--transmit-deltas
+<kitty +kitten transfer --transmit-deltas>` option. Note that this will actually
+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.
-Press :sc:`input_unicode_character` to start the unicode input widget, shown below.
+You can input Unicode characters by name, hex code, recently used and even an
+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
-character and pressing enter, for example, type in ``2716`` and press enter to get
-✖. You can also choose a character from the list of recently used characters by
-typing a leading period and then the two character index and pressing Enter.
-The up and down arrow keys can be used to choose the previous and next unicode
-symbol respectively.
+In :guilabel:`Code` mode, you enter a Unicode character by typing in the hex
+code for the character and pressing :kbd:`Enter`. For example, type in ``2716``
+and press :kbd:`Enter` to get ``✖``. You can also choose a character from the
+list of recently used characters by typing a leading period ``.`` and then the
+two character index and pressing :kbd:`Enter`.
+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
-also type a space followed by a period and the index for the match if you don't
-like to use arrow keys.
+the :kbd:`ArrowKeys` / :kbd:`Tab` to select the character from the displayed
+matches. You can also type a space followed by a period and the index for the
+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
-to add features to |kitty| itself and to create useful standalone programs.
+its advanced features. These programs are called kittens. They are used both to
+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>`
-    Easily input arbitrary unicode characters in |kitty| by name or hex code.
+:doc:`Unicode input <kittens/unicode_input>`
+    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
-    SSH sessions with a simple command.
+    Transfer files and directories seamlessly and easily from remote machines
+    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
-    other :term:`kitty windows <window>`.
+    Type in one :term:`kitty window <window>` and have it broadcast to all (or a
+    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
-    from an arbitrary terminal program.
+    Draw a GPU accelerated dock panel on your desktop showing the output from an
+    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.
-It is very powerful and allows sending the contents of
-the current window to the launched program, as well as many other options.
+in new windows/tabs. It can be mapped to user defined shortcuts in
+:file:`kitty.conf`. It is very powerful and allows sending the contents of the
+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
-launch::
+To run a different program simply pass the command line as arguments to launch::
 
     map f1 launch vim path/to/some/file
 
-To open a new window with the same working directory as the currently
-active window::
+To open a new window with the same working directory as the currently active
+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
-    working directory
+    The :kbd:`F1` key will now open :program:`vim` in a new tab with the current
+    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
-contents are::
+piped has a special environment variable declared, :envvar:`KITTY_PIPE_DATA`
+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
-    data to STDIN
+    Replaced by the number of lines in STDIN. Only present when passing some
+    data to STDIN.
 
 ``@input-line-number``
-    replaced the number of lines a pager should scroll to match the current
-    scroll position in kitty. See :opt:`scrollback_pager` for details
+    Replaced the number of lines a pager should scroll to match the current
+    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
-a dict that contains event dependent data. Some useful methods and attributes
-for the ``Window`` object are: ``as_text(as_ans=False, add_history=False,
+the ``Window`` object the action is occurring on. The ``data`` object is a dict
+that contains event dependent data. Some useful methods and attributes for the
+``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
-window.
+in the window and ``window.id`` is the internal kitty ``id`` of the 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
-this **may not** be the value of ``PATH`` inside a shell, as shell startup scripts
-often change the value of this variable. If it is not found there, then a
-system specific list of default paths is searched. If it is still not found,
-then your shell is run and the value of ``PATH`` inside the shell is used.
+it is searched for in the system-wide :envvar:`PATH` environment variable. Note
+that this **may not** be the value of :envvar:`PATH` inside a shell, as shell
+startup scripts often change the value of this variable. If it is not found
+there, then a system specific list of default paths is searched. If it is still
+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,
-you can switch layouts using :sc:`next_layout`. To control which layouts
-are available use :opt:`enabled_layouts`, the first listed layout becomes
-the default. Individual layouts and how to use them are described below.
+There are many different layouts available. They are all enabled by default, you
+can switch layouts using :ac:`next_layout` (:sc:`next_layout` by default). To
+control which layouts are available use :opt:`enabled_layouts`, the first listed
+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
-space, other windows are hidden behind it. It has no options::
+This is the simplest layout. It displays a single window using all available
+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
-on the left side of the screen instead of the right. The syntax
-for the options is shown below::
+``mirrored`` option when set to ``true`` will cause the full-height windows to
+be on the right side of the screen instead of the left. The syntax
+for the options is::
 
     enabled_layouts tall:bias=50;full_size=1;mirrored=false
 
@@ -65,7 +67,7 @@ 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::
 
    map ctrl+[ layout_action decrease_num_full_size_windows
@@ -75,14 +77,13 @@ windows, for example::
 The Fat Layout
 ----------------
 
-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.
-There are options to control how the screen is split vertically ``bias``
+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. 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
-``mirrored`` option when set to ``true`` will cause the narrow windows to be
-on the top of the screen instead of the bottom. The syntax for the options is
-shown below::
+full-width windows there are ``full_size`` (a positive integer). The
+``mirrored`` option when set to ``true`` will cause the full-width windows to be
+on the bottom of the screen instead of the top. The syntax for the options is::
 
     enabled_layouts fat:bias=50;full_size=1;mirrored=false
 
@@ -100,11 +101,16 @@ shown below::
     └─────────┴──────────┴─────────┘
 
 
+This layout also supports ``decrease_num_full_size_windows`` layout action like
+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
 
@@ -128,33 +134,47 @@ The Splits Layout
 
 This is the most flexible layout. You can create any arrangement of windows
 by splitting exiting windows repeatedly. To best use this layout you should
-define a few extra keybindings in :file:`kitty.conf`::
+define a few extra key bindings in :file:`kitty.conf`::
 
-    map F5 launch --location=hsplit
-    map F6 launch --location=vsplit
-    map F7 layout_action rotate
+    # 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
 
+    # 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
+
+    # 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
+
+    # Move the active window in the indicated direction
     map shift+up move_window up
     map shift+left move_window left
     map shift+right move_window right
     map shift+down move_window down
 
+    # 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
 
-Now you can create horizontal and vertical splits by using :kbd:`F5` and
-:kbd:`F6`. You can move them around using :kbd:`shift+arrow` keys
-and you can move focus to neighboring windows using :kbd:`ctrl+arrow` keys.
-You can switch an existing split from horizontal to vertical and vice versa
-using :kbd:`F7`. Finally, windows can be resized using :ref:`window_resizing`.
-
-Note that 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``.
+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, by default::
+are placed into vertical or horizontal splits when a :option:`--location <launch
+--location>` is not specified. A value of ``horizontal`` (same as
+``--location=vsplit``) means when a new split is created the two windows will be
+placed side by side and a value of ``vertical`` (same as ``--location=hsplit``)
+means the two windows will be placed one on top of the other. By default::
 
     enabled_layouts splits:split_axis=horizontal
 
@@ -179,7 +199,7 @@ are placed into vertical or horizontal splits, 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
 
@@ -199,7 +219,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
 
@@ -225,37 +245,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
-for a particular window. For example, in the Tall layout you can make the first
+instructions. In a given window layout only some operations may be possible for
+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``
-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 <enabled_layouts>` use::
+Some layouts take options to control their behavior. For example, the *Fat*
+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
+<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
-and 90.
+instead of ``50%`` of available width. ``bias`` can be any number between ``10``
+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.
-Add the following to :file:`kitty.conf`::
+Suppose we want to be able to highlight the word :code:`ERROR` in the current
+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
-    altered in any way. So you cannot match text that stretches across multiple
-    lines.
+    For performance reasons, matching is done per line only, and only when that
+    line is altered in any way. So you cannot match text that stretches across
+    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
-it and pressing :kbd:`F2` will remove the marker. ``create_marker`` accepts
-the same syntax as ``toggle_marker`` above. Note that while creating
-markers, the prompt has history so you can easily re-use previous marker
-expressions.
+Then pressing :kbd:`F1` will allow you to enter the marker definition and set it
+and pressing :kbd:`F2` will remove the marker. :ac:`create_marker` accepts the
+same syntax as :ac:`toggle_marker` above. Note that while creating markers, the
+prompt has history so you can easily re-use previous marker expressions.
 
-You can also use the facilities for :doc:`remote-control` to dynamically
-add/remove markers.
+You can also use the facilities for :doc:`remote-control` to dynamically add or
+remove markers.
 
 
 Scrolling to marks
 --------------------
 
-kitty has an action to scroll to the next line that contains a mark. You can
-use it by mapping it to some shortcut in :file:`kitty.conf`::
+kitty has a :ac:`scroll_to_mark` action to scroll to the next line that contains
+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
-buffer above the current top line that contains a mark. Pressing :kbd:`ctrl+n`
+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`
 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:`itext` - case-insensitive substring matching
-* :code:`regex` - A 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:`text` - Simple substring matching
+* :code:`itext` - Case-insensitive substring matching
+* :code:`regex` - A 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`.
 
 .. _marker_funcs:
 
 Arbitrary marker functions
 -----------------------------
 
-You can create your own marker functions. Create a python file named
-:file:`mymarker.py` and in it create a :code:`marker` function. This
-function receives the text of the line as input and must yield three numbers,
+You can create your own marker functions. Create a Python file named
+:file:`mymarker.py` and in it create a :code:`marker` function. This function
+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
-<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_. These
-are generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
-:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on these
-hyperlinks in |kitty|.
+|kitty| has support for :term:`terminal hyperlinks <hyperlinks>`. These are
+generated by many terminal programs, such as ``ls``, ``gcc``, ``systemd``,
+:ref:`tool_mdcat`, etc. You can customize exactly what happens when clicking on
+these hyperlinks in |kitty|.
 
-You can tell kitty to take arbitrarily many, complex actions
-when a link is clicked. Let us illustrate with some examples, first. Create
-the file :file:`~/.config/kitty/open-actions.conf` with the following:
+You can tell kitty to take arbitrarily many, complex actions when a link is
+clicked. Let us illustrate with some examples, first. Create the file
+: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
-entry if you like, for example:
+:file:`kitty.conf` can be used as an action. You can specify more than one
+action per entry if you like, for example:
 
 
 .. code:: conf
@@ -60,7 +66,7 @@ some special variables, documented below:
 
 
 .. 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 +83,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 +94,12 @@ 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
-    :file:`mime.types` in the kitty configuration directory. Useful if your
-    system MIME database does not have definitions you need. This file is
-    in the standard format of one definition per line, like: ``text/plain rst
-    md``. Note that the MIME type for directories is ``inode/directory``.
+    application/pdf``. You can add MIME types to kitty by creating a file named
+    :file:`mime.types` in the :ref:`kitty configuration directory <confloc>`.
+    Useful if your system MIME database does not have definitions you need. This
+    file is in the standard format of one definition per line, like:
+    ``text/plain rst md``. Note that the MIME type for directories is
+    ``inode/directory``.
 
 ``ext``
     A comma separated list of file extensions, for example: ``jpeg, tar.gz``
@@ -100,3 +107,44 @@ lines. The various available criteria are:
 ``file``
     A shell glob pattern that must match the filename, for example:
     ``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 and
+URLs onto the kitty dock icon to open them with kitty. The default actions are:
+
+* 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
+
+These actions can also be executed from the command line by running::
+
+    kitty +open file_or_url another_url ...
+
+    # macOS only
+    open -a kitty.app file_or_url another_url ...
+
+Since macOS lacks an official interface to set default URL scheme handlers,
+kitty has a command you can use for it. The first argument for is the URL
+scheme, and the second optional argument is the bundle id of the app, which
+defaults to kitty, if not specified. For example:
+
+.. code-block:: sh
+
+    # Set kitty as the handler for ssh:// URLs
+    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,22 @@ Overview
 Design philosophy
 -------------------
 
-|kitty| is designed for power keyboard users. To that end all its controls
-work with the keyboard (although it fully supports mouse interactions as
-well). Its configuration is a simple, human editable, single file for
-easy reproducibility (I like to store configuration in source control).
+|kitty| is designed for power keyboard users. To that end all its controls work
+with the keyboard (although it fully supports mouse interactions as well). Its
+configuration is a simple, human editable, single file for easy reproducibility
+(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
-easy hackability of the UI). It does not depend on any large and complex
-UI toolkit, using only OpenGL for rendering everything.
+written in a mix of C (for performance sensitive parts) and Python (for easy
+hackability of the UI). 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
-terminal features, such as unicode, true color, bold/italic fonts, text
-formatting, etc. It even extends existing text formatting escape codes,
-to add support for features not available elsewhere, such as colored and
-styled (curly) underlines. One of the design goals of |kitty| is to be
-easily extensible so that new features can be added in the future with
-relatively little effort.
+Finally, |kitty| is designed from the ground up to support all modern terminal
+features, such as Unicode, true color, bold/italic fonts, text formatting, etc.
+It even extends existing text formatting escape codes, to add support for
+features not available elsewhere, such as colored and styled (curly) underlines.
+One of the design goals of |kitty| is to be easily extensible so that new
+features can be added in the future with relatively little effort.
 
 .. include:: basic.rst
 
@@ -28,10 +27,10 @@ relatively little effort.
 Configuring kitty
 -------------------
 
-|kitty| is highly configurable, everything from keyboard shortcuts to
-painting frames-per-second. Press :sc:`edit_config_file` in kitty
-to open its fully commented sample config file in your text editor.
-For details see the :doc:`configuration docs <conf>`.
+|kitty| is highly configurable, everything from keyboard shortcuts to painting
+frames-per-second. Press :sc:`edit_config_file` in kitty to open its fully
+commented sample config file in your text editor. For details see the
+:doc:`configuration docs <conf>`.
 
 .. toctree::
    :hidden:
@@ -51,17 +50,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.
 
@@ -79,9 +87,9 @@ 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
 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 +109,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
-from one window and send text to another, etc, etc. The possibilities are
-endless. See the :doc:`tutorial <remote-control>` to get started.
+change window layout, get text from one window and send text to another, etc.
+The possibilities are endless. See the :doc:`tutorial <remote-control>` to get
+started.
 
 .. toctree::
    :hidden:
@@ -117,10 +125,9 @@ Startup Sessions
 ------------------
 
 You can control the :term:`tabs <tab>`, :term:`kitty window <window>` layout,
-working directory, startup programs,
-etc. by creating a "session" file and using the :option:`kitty --session`
-command line flag or the :opt:`startup_session` option in :file:`kitty.conf`.
-For example:
+working directory, startup programs, etc. by creating a *session* file and using
+the :option:`kitty --session` command line flag or the :opt:`startup_session`
+option in :file:`kitty.conf`. For example:
 
 .. code-block:: session
 
@@ -130,28 +137,28 @@ 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
-    # vim in it
+    # Create a window with some environment variables set and run 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
-    # name which will be displayed in the tab bar, if omitted, the
-    # title of the active window will be used instead)
+    # Create a new tab
+    # The part after new_tab is the optional tab title which will be displayed in
+    # 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 specifed before the first new_os_window will apply to first OS window.
     new_os_window
-    # set new window size to 80x25 cells
-    os_window_size 80c 25c
-    # set the --class for the new OS window
+    # Set new window size to 80x24 cells
+    os_window_size 80c 24c
+    # Set the --class for the new OS window
     os_window_class mywindow
     launch sh
     # Make the current window the active (focused) window
@@ -159,8 +166,8 @@ For example:
     launch emacs
 
 .. note::
-    The :doc:`launch <launch>` command when used in a session file
-    cannot create new OS windows, or tabs.
+    The :doc:`launch <launch>` command when used in a session file cannot create
+    new OS windows, or tabs.
 
 
 Creating tabs/windows
@@ -182,25 +189,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
-  platforms with a primary clipboard).
-* You can middle click to paste from the primary clipboard (on platforms
+* Selecting text automatically copies it to the primary clipboard (on platforms
   with a primary clipboard).
-* You can right click while holding :kbd:`ctrl+shift` to open the output
-  of the 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
+* 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 of the
+  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,
-having it open files in your editor, download remote files, open things
+You can also customize what happens when clicking on :term:`hyperlinks` in
+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,12 +221,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
-fonts. You can even specify specific font families for specific ranges of
-unicode characters. This allows precise control over text rendering. It can
-come in handy for applications like powerline, without the need to use patched
-fonts. See the various font related configuration directives in
-:ref:`conf-kitty-fonts`.
+specify individual families for the regular, bold, italic and bold+italic fonts.
+You can even specify specific font families for specific ranges of Unicode
+characters. This allows precise control over text rendering. It can comein handy
+for applications like powerline, without the need to use patched fonts. See the
+various font related configuration directives in :ref:`conf-kitty-fonts`.
 
 
 .. _scrollback:
@@ -228,30 +234,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,
-|kitty| has an extra, neat feature. Sometimes you need to explore the
-scrollback buffer in more detail, maybe search for some text or refer to it
-side-by-side while typing in a follow-up command. |kitty| allows you to do this
-by pressing the :sc:`show_scrollback` key-combination, which will open the
-scrollback buffer in your favorite pager program (which is ``less`` by default).
-Colors and text formatting are preserved. You can explore the scrollback buffer
-comfortably within the pager.
+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 scrollback
+buffer in more detail, maybe search for some text or refer to it side-by-side
+while typing in a follow-up command. |kitty| allows you to do this by pressing
+the :sc:`show_scrollback` shortcut, which will open the scrollback buffer in
+your favorite pager program (which is :program:`less` by default). Colors and
+text formatting are preserved. You can explore the scrollback buffer comfortably
+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`,
-for example::
+arbitrary, command running in a new :term:`window`, :term:`tab` or
+: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`
-key. See :sc:`show_scrollback <show_scrollback>` for details.
+Would open the scrollback buffer in a new :term:`window` when you press the
+: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,
-you can see tips for doing so, in
-`this thread <https://github.com/kovidgoyal/kitty/issues/719>`_.
+If you want to use it with an editor such as :program:`vim` to get more powerful
+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
-:sc:`show_scrollback <show_scrollback>` features, you can use the
+If you wish to store very large amounts of scrollback to view using the piping
+or :sc:`show_scrollback <show_scrollback>` features, you can use the
 :opt:`scrollback_pager_history_size` option.
 
 
@@ -259,8 +264,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.gnu.org/software/bash/>`_ to enable features such as jumping to
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
+<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.
@@ -275,17 +280,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
-can also setup an arbitrary number of copy paste buffers. To do so, simply add
-something like the following to your :file:`kitty.conf`::
+In addition to being able to copy/paste from the system clipboard, in |kitty|
+you can also setup an arbitrary number of copy paste buffers. To do so, simply
+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
-need.
+names are arbitrary strings, so you can define as many such buffers as you 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
-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
-with child programs takes place in a separate thread from rendering, to improve
+and "smoothness" while scrolling as well as CPU usage. |kitty| tries hard to
+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 with
+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`
-and :opt:`input_delay`. These control the artificial delays introduced into the
-render loop to reduce CPU usage. See :ref:`conf-kitty-performance` for details.
-See also the :opt:`sync_to_monitor` option to further decrease latency at the cost
-of some `tearing <https://en.wikipedia.org/wiki/Screen_tearing>`_ while scrolling.
+There are two config options you can tune to adjust the performance,
+:opt:`repaint_delay` and :opt:`input_delay`. These control the artificial delays
+introduced into the render loop to reduce CPU usage. See
+:ref:`conf-kitty-performance` for details. See also the :opt:`sync_to_monitor`
+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
-<https://github.com/gperftools/gperftools>`_. Build |kitty| with `make
-profile`. Run kitty and perform the task you want to analyse, for example,
-scrolling a large file with `less`. After you quit, function call statistics
-will be printed to `stdout` and you can use tools like *kcachegrind* for more
-detailed analysis.
+You can generate detailed per-function performance data using
+`gperftools <https://github.com/gperftools/gperftools>`__. Build |kitty| with
+``make profile``. Run kitty and perform the task you want to analyse, for
+example, scrolling a large file with :program:`less`. After you quit, function
+call statistics will be printed to STDOUT and you can use tools like
+*KCachegrind* for more detailed analysis.
 
-Here are some CPU usage numbers for the task of scrolling a file continuously
-in 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
-size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz`` CPU
-with a ``Advanced Micro Devices, Inc. [AMD/ATI] Cape Verde XT [Radeon HD
+Here are some CPU usage numbers for the task of scrolling a file continuously in
+:program:`less`. The CPU usage is for the terminal process and X together and is
+measured using :program:`htop`. The measurements are taken at the same font and
+window size for all terminals on a ``Intel(R) Core(TM) i7-4820K CPU @ 3.70GHz``
+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
-    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
-    deliberately throttles input parsing and output rendering to minimize
-    resource usage while still being able to sink output faster than any real
-    world program can produce it. Reducing CPU usage, and hence battery drain
-    while achieving instant response times and smooth scrolling to a human eye
-    is a far more important goal.
+    Some people have asked why kitty does not perform better than terminal XXX
+    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 deliberately
+    throttles input parsing and output rendering to minimize resource usage
+    while still being able to sink output faster than any real world program can
+    produce it. Reducing CPU usage, and hence battery drain while achieving
+    instant response times and smooth scrolling to a human eye is a far more
+    important goal.

docs/press-mentions.rst

@@ -0,0 +1,18 @@
+Press mentions of kitty
+========================
+
+`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.
-These are typically in the form of new or re-purposed escape codes. While these
-extensions are currently |kitty| specific, it would be nice to get some of them
-adopted more broadly, to push the state of terminal emulators forward.
+|kitty| has extensions to the legacy terminal protocol, to enable advanced
+features. These are typically in the form of new or re-purposed escape codes.
+While these extensions are currently |kitty| specific, it would be nice to get
+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
-of the goals of this specification is explicitly not to "re-imagine" the tty.
-The tty should remain what it is -- a device for efficiently processing text
+while filling in some gaps in the existing xterm protocol. In particular, one of
+the goals of this specification is explicitly not to "re-imagine" the TTY. The
+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
-is to make it as easy to implement these protocol extensions as possible,
-thereby hopefully encouraging their widespread adoption.
+possible amount of extra functionality into the terminal program itself. This is
+to make it as easy to implement these protocol extensions as possible, thereby
+hopefully encouraging their widespread adoption.
 
-If you wish to discuss these extensions, propose additions/changes to them
-please do so by opening issues in the `GitHub
-<https://github.com/kovidgoyal/kitty/issues>`_ bug tracker.
+If you wish to discuss these extensions, propose additions or changes to them,
+please do so by opening issues in the `GitHub bug tracker
+<https://github.com/kovidgoyal/kitty/issues>`__.
 
 
 .. toctree::

docs/quickstart.rst

@@ -9,9 +9,9 @@ Quickstart
    binary
    build
 
-Pre-built binaries of |kitty| are available for both macOS and Linux.
-See the :doc:`binary install instructions </binary>`. You can also
-:doc:`build from source </build>`.
+Pre-built binaries of |kitty| are available for both macOS and Linux. See the
+:doc:`binary install instructions </binary>`. You can also :doc:`build from
+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

@@ -16,25 +16,26 @@ Where ``<ESC>`` is the byte ``0x1b``. The JSON object has the form::
         "payload": <Optional JSON object>,
     }
 
-The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are developing a
-standalone client, use the kitty version that you are developing against. Using
-a version greater than the version of the kitty instance you are talking to,
-will cause a failure.
+The ``version`` above is an array of the form :code:`[0, 14, 2]`. If you are
+developing a standalone client, use the kitty version that you are developing
+against. Using a version greater than the version of the kitty instance you are
+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 fields in the object for every command are documented below.
+The optional payload is a JSON object that is specific to the actual command
+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
-as::
+the ``@ ls`` command from the shell using only shell tools.
+
+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 .
 
 .. 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
 ------------
 
@@ -21,43 +24,44 @@ 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
-to the current window.
+This will open a new window, running the :program:`cat` program that will appear
+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.
-The :option:`kitty @ send-text --match` option is very powerful, it allows selecting windows by their
-titles, the command line of the program running in the window, the working
-directory of the program running in the window, etc.  See ``kitty @ send-text
---help`` for details.
+This will make ``Hello, World`` show up in the window running the :program:`cat`
+program. The :option:`kitty @ send-text --match` option is very powerful, it
+allows selecting windows by their titles, the command line of the program
+running in the window, the working directory of the program running in the
+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
-window. You can use this technique to, for example, show the output of running
-``make`` in your editor in a different window. The possibilities are endless.
+This will show the output of :program:`ls` in the output window instead of the
+current window. You can use this technique to, for example, show the output of
+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 +69,83 @@ 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.
-Each tab has its own id, a title and a list of windows. Each window has an id,
-title, current working directory, process id (PID) and command-line of the
-process running in the window. You can use this information with :option:`kitty @ focus-window --match`
-to control individual windows.
+:term:`OS windows <os_window>`. Each OS window has an id and a list of
+:term:`tabs <tab>`. Each tab has its own id, a title and a list of :term:`kitty
+windows <window>`. Each window has an id, title, current working directory,
+process id (PID) and command-line of the process running in the window. You can
+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
-``kitty @`` messaging system. This tutorial touches only the
-surface of what is possible. See ``kitty @ --help`` for more details.
+As you can see, it is very easy to control |kitty| using the ``kitty @``
+messaging system. This tutorial touches only the surface of what is possible.
+See ``kitty @ --help`` for more details.
 
-Note that in the example's above, ``kitty @`` messaging works only when run inside a |kitty| window,
-not anywhere. But, within a |kitty| window it even works over SSH. If you want to control
-|kitty| from programs/scripts not running inside a |kitty| window, you have to implement a couple of
-extra steps. First start |kitty| as::
+Note that in the example's above, ``kitty @`` messaging works only when run
+inside a |kitty| window, not anywhere. But, within a |kitty| window it even
+works over SSH. If you want to control |kitty| from programs/scripts not running
+inside a |kitty| window, you have to implement a couple of extra steps. 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
-specified path. See ``kitty --help`` for details. Now you can control this
-instance of |kitty| using the :option:`kitty @ --to` command line argument to ``kitty @``. For example::
+The :option:`kitty --listen-on` option tells |kitty| to listen for control
+messages at the specified UNIX-domain socket. See ``kitty --help`` for details.
+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.
+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|
-shell. Run ``kitty @`` with no arguments and you will be dropped into the |kitty|
-shell with completion for |kitty| command names and options.
+You can explore the |kitty| command language more easily using the builtin
+|kitty| shell. Run ``kitty @`` with no arguments and you will be dropped into
+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
-enable remote control for only some |kitty| windows. Simply create a shortcut
-such as::
+If you do not want to allow all programs running in |kitty| to control it, you
+can selectively enable remote control for only some |kitty| windows. Simply
+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
-therefore can control |kitty|. It can, however, be useful to block programs
-running on other computers (for example, over ssh) or as other users.
+still write to the pipes of any other program on the same computer and therefore
+can control |kitty|. It can, however, be useful to block programs running on
+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.
 
 
 .. _rc_mapping:
@@ -148,15 +156,15 @@ 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.
-The syntax for what follows :code:`remote_control` is exactly the same
+Then pressing the :kbd:`F1` key will set the active window margins to
+: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,
-   as they are not actual remote programs, but are simply a way to resuse
-   the remote control infrastructure via keybings.
+.. 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 +174,36 @@ 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
-can use the :doc:`protocol specification <rc_protocol>`.
+If you wish to develop your own client to talk to |kitty|, you can use the
+:doc:`remote control protocol specification <rc_protocol>`.
+
+
+.. _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.gnu.org/software/bash/>`_ to enable features such as jumping to
+<https://www.zsh.org/>`__, `fish <https://fishshell.com>`__ and `bash
+<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,14 +22,19 @@ 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
-  displayed in the kitty window titlebar/tab title.
+  displayed in the kitty window titlebar/tab title
 
 * 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.
 
@@ -43,22 +48,39 @@ 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
-    to :ref:`manually enable integration <manual_shell_integration>`.
+    Do not modify the shell's launch environment to enable integration. Useful
+    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
+    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 setting
+    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
@@ -66,14 +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 already
+    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
-on the output, define the following in :file:`kitty.conf`:
+easily. For example to select the output of a command by right clicking the
+mouse on the output, define the following in :file:`kitty.conf`:
 
 .. code:: conf
 
@@ -84,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
-be integrated with browsing command output as well. For example, define the
+actions (:ac:`mouse_select_command_output` and :ac:`mouse_show_command_output`)
+can be integrated with browsing command output as well. For example, define the
 following mapping in :file:`kitty.conf`:
 
 .. code:: conf
@@ -117,37 +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
-code into the shell, to enable shell integration. How it does so varies for
-different shells.
+or the :opt:`shell` option in :file:`kitty.conf`) is a supported shell. If so,
+kitty injects some shell specific code into the shell, to enable shell
+integration. How it does so varies for different shells.
 
 
 .. tab:: zsh
 
-   For zsh, kitty sets the ``ZDOTDIR`` environment variable to make zsh load
-   kitty's :file:`.zshenv` which restores the original value of ``ZDOTDIR``
-   and sources the original :file:`.zshenv`. It then loads the shell integration code.
-   The remainder of zsh's startup process proceeds as normal.
-
-.. tab:: bash
-
-    For bash, kitty adds a couple of lines to the bottom of :file:`~/.bashrc`
-    (in an atomic manner) to load the shell integration code.
+   For zsh, kitty sets the :envvar:`ZDOTDIR` environment variable to make zsh
+   load kitty's :file:`.zshenv` which restores the original value of
+   :envvar:`ZDOTDIR` and sources the original :file:`.zshenv`. It then loads
+   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
-    process and will be cleaned up by the integration script after startup. No files
-    are added or modified.
+    :envvar:`XDG_DATA_DIRS` environment variable. This is only applied to the
+    fish process and will be cleaned up by the integration script after startup.
+    No files are added or modified.
+
+.. tab:: bash
+
+    For bash, kitty starts bash in POSIX mode, using the environment variable
+    :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
-files become no-ops when running the shell in anything other than kitty itself.
+pollute the system.
 
 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
@@ -168,6 +196,7 @@ code used for each shell below:
 
     .. literalinclude:: ../shell-integration/fish/vendor_conf.d/kitty-shell-integration.fish
         :language: fish
+        :force:
 
 .. tab:: bash
 
@@ -179,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 file.txt at line 75 (works with vim, emacs, nano, micro)
+   edit-in-kitty +75 file.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.
 
@@ -197,15 +310,6 @@ First, in :file:`kitty.conf` set:
 
 Then in your shell's rc file, add the lines:
 
-.. tab:: bash
-
-    .. code-block:: sh
-
-        if test -n "$KITTY_INSTALLATION_DIR"; then
-            export KITTY_SHELL_INTEGRATION="enabled"
-            source "$KITTY_INSTALLATION_DIR/shell-integration/bash/kitty.bash"
-        fi
-
 .. tab:: zsh
 
     .. code-block:: sh
@@ -228,15 +332,32 @@ Then in your shell's rc file, add the lines:
         end
 
 
+.. tab:: bash
+
+    .. code-block:: sh
+
+        if test -n "$KITTY_INSTALLATION_DIR"; then
+            export KITTY_SHELL_INTEGRATION="enabled"
+            source "$KITTY_INSTALLATION_DIR/shell-integration/bash/kitty.bash"
+        fi
+
 The value of :envvar:`KITTY_SHELL_INTEGRATION` is the same as that for
 :opt:`shell_integration`, except if you want to disable shell integration
 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
-need to add some code to the snippets above to check if :code:`KITTY_INSTALLATION_DIR`
-is empty and if so to set it to some hard coded location with the shell
-integration scripts that need to be copied onto the remote system.
+In a container, you will need to install the kitty shell integration scripts
+and make sure the :envvar:`KITTY_INSTALLATION_DIR` environment variable is set
+to point to the location of the scripts.
+
+Integration with other shells
+-------------------------------
+
+There exist third-party integrations to use these features for various other
+shells:
+
+* Jupyter console and IPython via a patch (:iss:`4475`)
+* `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__
 
 
 Notes for shell developers

docs/underlines.rst

@@ -1,24 +1,25 @@
 Colored and styled underlines
 ================================
 
-|kitty| supports colored and styled (wavy) underlines. This is of particular
-use in terminal editors such as vim and emacs to display red, wavy underlines
-under mis-spelled words and/or syntax errors. This is done by re-purposing some
-SGR escape codes that are not used in modern terminals (`CSI codes
-<https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_(Control_Sequence_Introducer)_sequences>`_)
+|kitty| supports colored and styled (wavy) underlines. This is of particular use
+in terminal based text editors such as :program:`vim` and :program:`emacs` to
+display red, wavy underlines under mis-spelled words and/or syntax errors. This
+is done by re-purposing some SGR escape codes that are not used in modern
+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:1m  # this is a straight underline
-    <ESC>[4:2m  # this is a double underline
-    <ESC>[4:3m  # this is a curly underline
-    <ESC>[4:4m  # this is a dotted underline (not implemented in kitty)
-    <ESC>[4:5m  # this is a dashed underline (not implemented in kitty)
-    <ESC>[4m    # this is a straight underline (for backwards compat)
-    <ESC>[24m   # this is no underline (for backwards compat)
+    <ESC>[4:0m  # no underline
+    <ESC>[4:1m  # straight underline
+    <ESC>[4:2m  # double underline
+    <ESC>[4:3m  # curly underline
+    <ESC>[4:4m  # dotted underline
+    <ESC>[4:5m  # dashed underline
+    <ESC>[4m    # straight 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
-color, if not, it should follow the foreground color.
+The underline color must remain the same under reverse video, if it has a color,
+if not, it should follow the foreground color.
 
-To detect support for this feature in a terminal emulator, query the terminfo database
-for the ``Su`` boolean capability.
+To detect support for this feature in a terminal emulator, query the terminfo
+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
-``SD`` escape code normally causes the text on screen to scroll down by the
-specified number of lines, with empty lines appearing at the top of the screen.
-This extension allows the new lines to be filled in from the scrollback buffer
+<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The ``SD``
+escape code normally causes the text on screen to scroll down by the specified
+number of lines, with empty lines appearing at the top of the screen. This
+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

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 # License: GPLv3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
 
+import os
 import subprocess
 from collections import defaultdict
 from typing import Any, DefaultDict, Dict, FrozenSet, List, Tuple, Union
@@ -42,7 +43,7 @@ def parse_flag(keymap: KeymapType, type_map: Dict[str, Any], command_class: str)
     lines = []
     for ch in type_map['flag']:
         attr, allowed_values = keymap[ch]
-        q = ' && '.join(f"g.{attr} != '{x}'" for x in allowed_values)
+        q = ' && '.join(f"g.{attr} != '{x}'" for x in sorted(allowed_values))
         lines.append(f'''
             case {attr}: {{
                 g.{attr} = screen->parser_buf[pos++] & 0xff;
@@ -67,7 +68,7 @@ def cmd_for_report(report_name: str, keymap: KeymapType, type_map: Dict[str, Any
         flag_fmt, flag_attrs = [], []
         cv = {'flag': 'c', 'int': 'i', 'uint': 'I'}[atype]
         for ch in type_map[atype]:
-            flag_fmt.append('s' + cv)
+            flag_fmt.append(f's{cv}')
             attr = keymap[ch][0]
             flag_attrs.append(f'"{attr}", {conv}g.{attr}')
         return ' '.join(flag_fmt), ', '.join(flag_attrs)
@@ -240,7 +241,7 @@ static inline void
 
 def write_header(text: str, path: str) -> None:
     with open(path, 'w') as f:
-        print(f'// This file is generated by {__file__} do not edit!', file=f, end='\n\n')
+        print(f'// This file is generated by {os.path.basename(__file__)} do not edit!', file=f, end='\n\n')
         print('#pragma once', file=f)
         print(text, file=f)
     subprocess.check_call(['clang-format', '-i', path])

gen-config.py

@@ -38,6 +38,8 @@ def main() -> None:
 
     from kittens.diff.options.definition import definition as kd
     write_output('kittens.diff', kd)
+    from kittens.ssh.options.definition import definition as sd
+    write_output('kittens.ssh', sd)
 
 
 if __name__ == '__main__':

gen-key-constants.py

@@ -238,7 +238,7 @@ def patch_file(path: str, what: str, text: str, start_marker: str = '/* ', end_m
             end = raw.index(end_q)
         except ValueError:
             raise SystemExit(f'Failed to find "{end_q}" in {path}')
-        raw = raw[:start] + start_q + '\n' + text + '\n' + raw[end:]
+        raw = f'{raw[:start]}{start_q}\n{text}\n{raw[end:]}'
         f.seek(0)
         f.truncate(0)
         f.write(raw)
@@ -368,7 +368,7 @@ def generate_ctrl_mapping() -> None:
         val = str(ctrl_mapping[k])
         items.append(val)
         if k in "\\'":
-            k = '\\' + k
+            k = f'\\{k}'
         mi.append(f"        case '{k}': return {val};")
 
     for line_items in chunks(items, 6):

gen-wcwidth.py

@@ -49,11 +49,10 @@ class_maps: Dict[str, Set[int]] = {}
 all_symbols: Set[int] = set()
 name_map: Dict[int, str] = {}
 word_search_map: DefaultDict[str, Set[int]] = defaultdict(set)
-zwj = 0x200d
 soft_hyphen = 0xad
 flag_codepoints = frozenset(range(0x1F1E6, 0x1F1E6 + 26))
 # See https://github.com/harfbuzz/harfbuzz/issues/169
-marks = set(emoji_skin_tone_modifiers) | {zwj} | flag_codepoints
+marks = set(emoji_skin_tone_modifiers) | flag_codepoints
 not_assigned = set(range(0, sys.maxunicode))
 property_maps: Dict[str, Set[int]] = defaultdict(set)
 
@@ -69,7 +68,6 @@ def parse_prop_list() -> None:
         property_maps[name] |= chars
     # see https://www.unicode.org/faq/unsup_char.html#3
     marks |= property_maps['Other_Default_Ignorable_Code_Point']
-    marks.add(soft_hyphen)
 
 
 def parse_ucd() -> None:
@@ -113,6 +111,12 @@ def parse_ucd() -> None:
                 marks.add(codepoint)
             elif category.startswith('S'):
                 all_symbols.add(codepoint)
+            elif category == 'Cf':
+                # we add Cf to marks as it contains things like tags and zero
+                # width chars. Not sure if *all* of Cf should be treated as
+                # combining chars, might need to add individual exceptions in
+                # the future.
+                marks.add(codepoint)
 
     with open('nerd-fonts-glyphs.txt') as f:
         for line in f:
@@ -382,9 +386,9 @@ def gen_ucd() -> None:
             ascii_range='false'
         )
         category_test(
-            'is_non_rendered_char', p, 'Cc Cs'.split(),
+            'is_non_rendered_char', p, 'Cc Cs Cf'.split(),
             'Other_Default_Ignorable_Code_Point and soft hyphen',
-            extra_chars=property_maps['Other_Default_Ignorable_Code_Point'] | {soft_hyphen},
+            extra_chars=property_maps['Other_Default_Ignorable_Code_Point'] | set(range(0xfe00, 0xfe0f + 1)),
             ascii_range='false'
         )
         category_test('is_word_char', p, {c for c in class_maps if c[0] in 'LN'}, 'L and N categories')

glfw/cocoa_init.m

@@ -264,6 +264,8 @@ display_reconfigured(CGDirectDisplayID display UNUSED, CGDisplayChangeSummaryFla
     }
 }
 
+static NSDictionary<NSString*,NSNumber*> *global_shortcuts = nil;
+
 @interface GLFWHelper : NSObject
 @end
 
@@ -280,6 +282,16 @@ display_reconfigured(CGDirectDisplayID display UNUSED, CGDisplayChangeSummaryFla
     (void)object;
 }
 
+// watch for settings change and rebuild global_shortcuts using key/value observing on NSUserDefaults
+- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change context:(void *)context
+{
+    (void)keyPath; (void)object; (void)change; (void)context;
+    if (global_shortcuts != nil) {
+        [global_shortcuts release];
+        global_shortcuts = nil;
+    }
+}
+
 @end // GLFWHelper
 
 // Delegate for application related notifications {{{
@@ -346,32 +358,49 @@ static GLFWapplicationwillfinishlaunchingfun finish_launching_callback = NULL;
         finish_launching_callback();
 }
 
-- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename {
-    (void)theApplication;
-    if (!filename || !_glfw.ns.file_open_callback) return NO;
-    const char *path = NULL;
+- (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename {
+    (void)sender;
+    if (!filename || !_glfw.ns.url_open_callback) return NO;
+    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;
-    return _glfw.ns.file_open_callback(path);
+    if (!url) return NO;
+    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);
     }
 }
 
@@ -379,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();
@@ -453,72 +481,293 @@ void* _glfwLoadLocalVulkanLoaderNS(void)
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
-static bool
-is_modified_tab(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    switch ((NSUInteger)modifierFlags) {
-        // No need to handle shift+tab, [shift]+option+tab
-        case NSEventModifierFlagShift:
-        case NSEventModifierFlagOption:
-        case (NSEventModifierFlagShift | NSEventModifierFlagOption):
-        // Do not intercept cmd+tab, shift+cmd+tab
-        case NSEventModifierFlagCommand:
-        case (NSEventModifierFlagShift | NSEventModifierFlagCommand):
-            return false;
-        default:
-            break;
-    }
-    // ctrl+whatever+tab, option+cmd+tab
-    if (
-            (
-                (modifierFlags & NSEventModifierFlagControl) ||
-                    modifierFlags == (NSEventModifierFlagOption | NSEventModifierFlagCommand)
-            ) && [event.charactersIgnoringModifiers isEqualToString:@"\t"]
-       ) return true;
-    // shift+whatever+tab
-    if (
-            (modifierFlags & NSEventModifierFlagShift) &&
-                [event.charactersIgnoringModifiers isEqualToString:@"\x19"]
-       ) return true;
-    return false;
-}
+/**
+ * Apple Symbolic HotKeys Ids
+ * To find this symbolic hot keys indices do:
+ * 1. open Terminal
+ * 2. restore defaults in System Preferences > Keyboard > Shortcuts
+ * 3. defaults read com.apple.symbolichotkeys > current.txt
+ * 4. enable/disable given symbolic hot key in System Preferences > Keyboard > Shortcuts
+ * 5. defaults read com.apple.symbolichotkeys | diff -C 5 current.txt -
+ * 6. restore defaults in System Preferences > Keyboard > Shortcuts
+ */
+typedef enum AppleShortcutNames {
+    // launchpad & dock
+    kSHKTurnDockHidingOnOrOff                   = 52,   // Opt, Cmd, D
+    kSHKShowLaunchpad                           = 160,  //
+
+    // display
+    kSHKDecreaseDisplayBrightness1              = 53,   // F14 (Fn)
+    kSHKDecreaseDisplayBrightness2              = 55,   // F14 (Fn, Ctrl)
+    kSHKIncreaseDisplayBrightness1              = 54,   // F15 (Fn)
+    kSHKIncreaseDisplayBrightness2              = 56,   // F15 (Fn, Ctrl)
+
+    // mission control
+    kSHKMissionControl                          = 32,   // Ctrl, Arrow Up
+    kSHKShowNotificationCenter                  = 163,  //
+    kSHKTurnDoNotDisturbOnOrOff                 = 175,  //
+    kSHKApplicationWindows                      = 33,   // Ctrl, Arrow Down
+    kSHKShowDesktop                             = 36,   // F11
+    kSHKMoveLeftASpace                          = 79,   // Ctrl, Arrow Left
+    kSHKMoveRightASpace                         = 81,   // Ctrl, Arrow Right
+    kSHKSwitchToDesktop1                        = 118,  // Ctrl, 1
+    kSHKSwitchToDesktop2                        = 119,  // Ctrl, 2
+    kSHKSwitchToDesktop3                        = 120,  // Ctrl, 3
+    kSHKSwitchToDesktop4                        = 121,  // Ctrl, 4
+    kSHKQuickNote                               = 190,  // Fn, Q
+
+    // keyboard
+    kSHKChangeTheWayTabMovesFocus               = 13,   // Ctrl, F7
+    kSHKTurnKeyboardAccessOnOrOff               = 12,   // Ctrl, F1
+    kSHKMoveFocusToTheMenuBar                   = 7,    // Ctrl, F2
+    kSHKMoveFocusToTheDock                      = 8,    // Ctrl, F3
+    kSHKMoveFocusToActiveOrNextWindow           = 9,    // Ctrl, F4
+    kSHKMoveFocusToTheWindowToolbar             = 10,   // Ctrl, F5
+    kSHKMoveFocusToTheFloatingWindow            = 11,   // Ctrl, F6
+    kSHKMoveFocusToNextWindow                   = 27,   // Cmd, `
+    kSHKMoveFocusToStatusMenus                  = 57,   // Ctrl, F8
+
+    // input sources
+    kSHKSelectThePreviousInputSource            = 60,   // Ctrl, Space bar
+    kSHKSelectNextSourceInInputMenu             = 61,   // Ctrl, Opt, Space bar
+
+    // screenshots
+    kSHKSavePictureOfScreenAsAFile              = 28,   // Shift, Cmd, 3
+    kSHKCopyPictureOfScreenToTheClipboard       = 29,   // Ctrl, Shift, Cmd, 3
+    kSHKSavePictureOfSelectedAreaAsAFile        = 30,   // Shift, Cmd, 4
+    kSHKCopyPictureOfSelectedAreaToTheClipboard = 31,   // Ctrl, Shift, Cmd, 4
+    kSHKScreenshotAndRecordingOptions           = 184,  // Shift, Cmd, 5
+
+    // spotlight
+    kSHKShowSpotlightSearch                     = 64,   // Cmd, Space bar
+    kSHKShowFinderSearchWindow                  = 65,   // Opt, Cmd, Space bar
+
+    // accessibility
+    kSHKTurnZoomOnOrOff                         = 15,   // Opt, Cmd, 8
+    kSHKTurnImageSmoothingOnOrOff               = 23,   // Opt, Cmd, Backslash "\"
+    kSHKZoomOut                                 = 19,   // Opt, Cmd, -
+    kSHKZoomIn                                  = 17,   // Opt, Cmd, =
+    kSHKTurnFocusFollowingOnOrOff               = 179,  //
+
+    kSHKIncreaseContrast                        = 25,   // Ctrl, Opt, Cmd, .
+    kSHKDecreaseContrast                        = 26,   // Ctrl, Opt, Cmd, ,
+
+    kSHKInvertColors                            = 21,   // Ctrl, Opt, Cmd, 8
+    kSHKTurnVoiceOverOnOrOff                    = 59,   // Cmd, F5
+    kSHKShowAccessibilityControls               = 162,  // Opt, Cmd, F5
+
+    // app shortcuts
+    kSHKShowHelpMenu                            = 98,   // Shift, Cmd, /
+
+    // deprecated (Not shown on macOS Monterey)
+    kSHKMoveFocusToTheWindowDrawer              = 51,   // Opt, Cmd, `
+    kSHKShowDashboard                           = 62,   // F12
+    kSHKLookUpInDictionary                      = 70,   // Shift, Cmd, E
+    kSHKHideAndShowFrontRow                     = 73,   // Cmd, Esc
+    kSHKActivateSpaces                          = 75,   // F8
+
+    // unknown
+    kSHKUnknown                                 = 0,    //
+} AppleShortcutNames;
 
 static bool
-is_cmd_period(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    if (modifierFlags != NSEventModifierFlagCommand) return false;
-    if ([event.charactersIgnoringModifiers isEqualToString:@"."]) return true;
-    return false;
+is_shiftable_shortcut(int scv) {
+    return scv == kSHKMoveFocusToActiveOrNextWindow || scv == kSHKMoveFocusToNextWindow;
 }
 
-static bool
-is_modified_special_key(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    // really one should use [[NSUserDefaults standardUserDefaults] valueForDefaultsDomain:@"com.apple.symbolichotkeys" key:@"AppleSymbolicHotKeys"]
-    // to get the list of global shortcuts and pass through the important ones,
-    // see https://stackoverflow.com/questions/21878482/what-do-the-parameter-values-in-applesymbolichotkeys-plist-dict-represent
-    // however given that in order to know which integers are which actions in that dict one needs reverse engineering
-    // see https://stackoverflow.com/questions/866056/how-do-i-programmatically-get-the-shortcut-keys-reserved-by-mac-os-x
-    // it's too much effort.
-    if ([event.charactersIgnoringModifiers length] != 1) return false;
-    const unichar ch = [event.charactersIgnoringModifiers characterAtIndex:0];
-    if (modifierFlags == (NSEventModifierFlagControl | NSEventModifierFlagShift)) {
-        switch (ch) {
-            case 0x1b:  // Esc
-            case NSF1FunctionKey: case NSF2FunctionKey: case NSF3FunctionKey: case NSF4FunctionKey:
-            case NSF5FunctionKey: case NSF6FunctionKey: case NSF7FunctionKey: case NSF8FunctionKey:
-            case NSF9FunctionKey: case NSF10FunctionKey: case NSF11FunctionKey: case NSF12FunctionKey:
-            case NSF13FunctionKey: case NSF14FunctionKey: case NSF15FunctionKey: case NSF16FunctionKey:
-            case NSF17FunctionKey: case NSF18FunctionKey: case NSF19FunctionKey:
-                return true;
+#define USEFUL_MODS(x) (x & (NSEventModifierFlagShift | NSEventModifierFlagOption | NSEventModifierFlagCommand | NSEventModifierFlagControl))
+
+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"];
+        if (symbolic_hotkeys) {
+            for (NSString *key in symbolic_hotkeys) {
+                id obj = symbolic_hotkeys[key];
+                if (![key isKindOfClass:[NSString class]] || ![obj isKindOfClass:[NSDictionary class]]) continue;
+                NSInteger sc = [key integerValue];
+                NSDictionary *sc_value = obj;
+                id enabled = [sc_value objectForKey:@"enabled"];
+                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]]) {
+                    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;
+                id p = [value objectForKey:@"parameters"];
+                if (!p || ![p isKindOfClass:[NSArray class]] || [(NSArray*)p count] < 2) continue;
+                NSArray<NSNumber*> *parameters = p;
+                NSInteger ch = [parameters[0] isKindOfClass:[NSNumber class]] ? [parameters[0] integerValue] : 0xffff;
+                NSInteger vk = [parameters[1] isKindOfClass:[NSNumber class]] ? [parameters[1] integerValue] : 0xffff;
+                NSEventModifierFlags mods = ([parameters count] > 2 && [parameters[2] isKindOfClass:[NSNumber class]]) ? [parameters[2] unsignedIntegerValue] : 0;
+                mods = USEFUL_MODS(mods);
+                static char buf[64];
+#define S(x, k) snprintf(buf, sizeof(buf) - 1, #x":%lx:%ld", (unsigned long)mods, (long)k)
+                if (ch == 0xffff) { if (vk == 0xffff) continue; S(v, vk); } else S(c, ch);
+                temp[@(buf)] = @(sc);
+                // the move to next window shortcuts also respond to the same shortcut + shift
+                if (is_shiftable_shortcut([key intValue]) && !(mods & NSEventModifierFlagShift)) {
+                    mods |= NSEventModifierFlagShift;
+                    if (ch == 0xffff) S(v, vk); else S(c, ch);
+                    temp[@(buf)] = @(sc);
+                }
+#undef S
+            }
         }
     }
-    switch (ch) {
-        case 0x1b:  // Esc
-            if (modifierFlags & (NSEventModifierFlagCommand | NSEventModifierFlagControl)) return true;
-            break;
-        case NSHelpFunctionKey:  // For some reason keyboards with an insert key have it mapped to help
-            if (!modifierFlags || modifierFlags == NSEventModifierFlagShift) return true;
-            break;
+
+    // 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); */
+}
+
+static int
+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 ([event.charactersIgnoringModifiers length] == 1) {
+        if (modifierFlags & NSEventModifierFlagShift) {
+            const uint32_t ch_without_shift = vk_to_unicode_key_with_current_layout([event keyCode]);
+            if (ch_without_shift < GLFW_FKEY_FIRST || ch_without_shift > GLFW_FKEY_LAST) {
+                LOOKUP(c, ch_without_shift);
+            }
+        }
+        const unichar ch = [event.charactersIgnoringModifiers characterAtIndex:0];
+        LOOKUP(c, ch);
+    }
+    unsigned short vk = [event keyCode];
+    if (vk != 0xffff) {
+        LOOKUP(v, vk);
+    }
+#undef LOOKUP
+    return kSHKUnknown;
+}
+
+static bool
+is_useful_apple_global_shortcut(int sc) {
+    switch(sc) {
+        // launchpad & dock
+        case kSHKTurnDockHidingOnOrOff:                   // Opt, Cmd, D
+        case kSHKShowLaunchpad:                           //
+
+        // display
+        case kSHKDecreaseDisplayBrightness1:              // F14 (Fn)
+        case kSHKDecreaseDisplayBrightness2:              // F14 (Fn, Ctrl)
+        case kSHKIncreaseDisplayBrightness1:              // F15 (Fn)
+        case kSHKIncreaseDisplayBrightness2:              // F14 (Fn, Ctrl)
+
+        // mission control
+        case kSHKMissionControl:                          // Ctrl, Arrow Up
+        case kSHKShowNotificationCenter:                  //
+        case kSHKTurnDoNotDisturbOnOrOff:                 //
+        case kSHKApplicationWindows:                      // Ctrl, Arrow Down
+        case kSHKShowDesktop:                             // F11
+        case kSHKMoveLeftASpace:                          // Ctrl, Arrow Left
+        case kSHKMoveRightASpace:                         // Ctrl, Arrow Right
+        case kSHKSwitchToDesktop1:                        // Ctrl, 1
+        case kSHKSwitchToDesktop2:                        // Ctrl, 2
+        case kSHKSwitchToDesktop3:                        // Ctrl, 3
+        case kSHKSwitchToDesktop4:                        // Ctrl, 4
+        case kSHKQuickNote:                               // Fn, Q
+
+        // keyboard
+        /* case kSHKChangeTheWayTabMovesFocus:               // Ctrl, F7 */
+        /* case kSHKTurnKeyboardAccessOnOrOff:               // Ctrl, F1 */
+        case kSHKMoveFocusToTheMenuBar:                   // Ctrl, F2
+        case kSHKMoveFocusToTheDock:                      // Ctrl, F3
+        case kSHKMoveFocusToActiveOrNextWindow:           // Ctrl, F4
+        /* case kSHKMoveFocusToTheWindowToolbar:             // Ctrl, F5 */
+        /* case kSHKMoveFocusToTheFloatingWindow:            // Ctrl, F6 */
+        case kSHKMoveFocusToNextWindow:                   // Cmd, `
+        case kSHKMoveFocusToStatusMenus:                  // Ctrl, F8
+
+        // input sources
+        case kSHKSelectThePreviousInputSource:            // Ctrl, Space bar
+        case kSHKSelectNextSourceInInputMenu:             // Ctrl, Opt, Space bar
+
+        // screenshots
+        /* case kSHKSavePictureOfScreenAsAFile:              // Shift, Cmd, 3 */
+        /* case kSHKCopyPictureOfScreenToTheClipboard:       // Ctrl, Shift, Cmd, 3 */
+        /* case kSHKSavePictureOfSelectedAreaAsAFile:        // Shift, Cmd, 4 */
+        /* case kSHKCopyPictureOfSelectedAreaToTheClipboard: // Ctrl, Shift, Cmd, 4 */
+        /* case kSHKScreenshotAndRecordingOptions:           // Shift, Cmd, 5 */
+
+        // spotlight
+        case kSHKShowSpotlightSearch:                     // Cmd, Space bar
+        case kSHKShowFinderSearchWindow:                  // Opt, Cmd, Space bar
+
+        // accessibility
+        /* case kSHKTurnZoomOnOrOff:                         // Opt, Cmd, 8 */
+        /* case kSHKTurnImageSmoothingOnOrOff:               // Opt, Cmd, Backslash "\" */
+        /* case kSHKZoomOut:                                 // Opt, Cmd, - */
+        /* case kSHKZoomIn:                                  // Opt, Cmd, = */
+        /* case kSHKTurnFocusFollowingOnOrOff:               // */
+        /* case kSHKIncreaseContrast:                        // Ctrl, Opt, Cmd, . */
+        /* case kSHKDecreaseContrast:                        // Ctrl, Opt, Cmd, , */
+        /* case kSHKInvertColors:                            // Ctrl, Opt, Cmd, 8 */
+        /* case kSHKTurnVoiceOverOnOrOff:                    // Cmd, F5 */
+        /* case kSHKShowAccessibilityControls:               // Opt, Cmd, F5 */
+
+        // app shortcuts
+        /* case kSHKShowHelpMenu:                            // Shift, Cmd, / */
+
+        // deprecated (Not shown on macOS Monterey)
+        /* case kSHKMoveFocusToTheWindowDrawer:              // Opt, Cmd, ` */
+        /* case kSHKShowDashboard:                           // F12 */
+        /* case kSHKLookUpInDictionary:                      // Shift, Cmd, E */
+        /* case kSHKHideAndShowFrontRow:                     // Cmd, Esc */
+        /* case kSHKActivateSpaces:                          // F8 */
+            return true;
+        default:
+            return false;
     }
-    return false;
 }
 
 GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
@@ -557,35 +806,76 @@ 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)
     {
-        NSEventModifierFlags modifierFlags = [event modifierFlags] & (NSEventModifierFlagShift | NSEventModifierFlagOption | NSEventModifierFlagCommand | NSEventModifierFlagControl);
-        if (is_modified_special_key(event, modifierFlags) || is_modified_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows various key presses, so route them explicitly
-            [[NSApp keyWindow].contentView keyDown:event];
-            return nil;
+        debug_key("---------------- key down -------------------\n");
+        debug_key("%s\n", [[event description] UTF8String]);
+        if (!_glfw.ignoreOSKeyboardProcessing) {
+            // first check if there is a global menu bar shortcut
+            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;
+            }
+            // now check if there is a useful apple shortcut
+            int global_shortcut = is_active_apple_global_shortcut(event);
+            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;
+            }
         }
-
-        return event;
+        last_keydown_shortcut_event.virtual_key_code = 0xffff;
+        NSWindow *kw = [NSApp keyWindow];
+        if (kw && kw.contentView) [kw.contentView keyDown:event];
+        else debug_key("keyDown ignored as no keyWindow present\n");
+        return nil;
     };
 
     NSEvent* (^keyup_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
     {
-        NSEventModifierFlags modifierFlags = [event modifierFlags] & (NSEventModifierFlagShift | NSEventModifierFlagOption | NSEventModifierFlagCommand | NSEventModifierFlagControl);
-        if (modifierFlags & NSEventModifierFlagCommand) {
-            // From https://cocoadev.github.io/GameKeyboardHandlingAlmost/
-            // This works around an AppKit bug, where key up events while holding
-            // down the command key don't get sent to the key window.
-            [[NSApp keyWindow] sendEvent:event];
-        }
-        if (is_modified_special_key(event, modifierFlags) || is_modified_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows various key presses, so route them explicitly
-            [[NSApp keyWindow].contentView keyUp:event];
+        debug_key("----------------- key up --------------------\n");
+        debug_key("%s\n", [[event description] UTF8String]);
+        if (last_keydown_shortcut_event.virtual_key_code != 0xffff && last_keydown_shortcut_event.virtual_key_code == [event keyCode]) {
+            // ignore as the corresponding key down event triggered a menu bar or macOS shortcut
+            last_keydown_shortcut_event.virtual_key_code = 0xffff;
+            debug_key("keyUp ignored as corresponds to previous keyDown that trigerred a shortcut\n");
             return nil;
         }
+        NSWindow *kw = [NSApp keyWindow];
+        if (kw && kw.contentView) [kw.contentView keyUp:event];
+        else debug_key("keyUp ignored as no keyWindow present\n");
+        return nil;
+    };
 
-        return event;
+    NSEvent* (^flags_changed_block)(NSEvent*) = ^ NSEvent* (NSEvent* event)
+    {
+        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");
+        return nil;
     };
 
     _glfw.ns.keyUpMonitor =
@@ -594,6 +884,9 @@ int _glfwPlatformInit(void)
     _glfw.ns.keyDownMonitor =
         [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskKeyDown
                                               handler:keydown_block];
+    _glfw.ns.flagsChangedMonitor =
+        [NSEvent addLocalMonitorForEventsMatchingMask:NSEventMaskFlagsChanged
+                                              handler:flags_changed_block];
 
     if (_glfw.hints.init.ns.chdir)
         changeToResourcesDirectory();
@@ -606,6 +899,13 @@ int _glfwPlatformInit(void)
     };
     [[NSUserDefaults standardUserDefaults] registerDefaults:defaults];
 
+    NSUserDefaults *apple_settings = [[NSUserDefaults alloc] initWithSuiteName:@"com.apple.symbolichotkeys"];
+    [apple_settings addObserver:_glfw.ns.helper
+                     forKeyPath:@"AppleSymbolicHotKeys"
+                        options:NSKeyValueObservingOptionNew
+                        context:NULL];
+    _glfw.ns.appleSettings = apple_settings;
+
     [[NSNotificationCenter defaultCenter]
         addObserver:_glfw.ns.helper
            selector:@selector(selectedKeyboardInputSourceChanged:)
@@ -661,6 +961,8 @@ void _glfwPlatformTerminate(void)
                     object:nil];
         [[NSNotificationCenter defaultCenter]
             removeObserver:_glfw.ns.helper];
+        if (_glfw.ns.appleSettings)
+            [_glfw.ns.appleSettings removeObserver:_glfw.ns.helper forKeyPath:@"AppleSymbolicHotKeys"];
         [_glfw.ns.helper release];
         _glfw.ns.helper = nil;
     }
@@ -669,10 +971,18 @@ void _glfwPlatformTerminate(void)
         [NSEvent removeMonitor:_glfw.ns.keyUpMonitor];
     if (_glfw.ns.keyDownMonitor)
         [NSEvent removeMonitor:_glfw.ns.keyDownMonitor];
+    if (_glfw.ns.flagsChangedMonitor)
+        [NSEvent removeMonitor:_glfw.ns.flagsChangedMonitor];
+
+    if (_glfw.ns.appleSettings != nil) {
+        [_glfw.ns.appleSettings release];
+        _glfw.ns.appleSettings = nil;
+    }
 
     free(_glfw.ns.clipboardString);
 
     _glfwTerminateNSGL();
+    if (global_shortcuts != nil) { [global_shortcuts release]; global_shortcuts = nil; }
 
     } // autoreleasepool
 }

glfw/cocoa_platform.h

@@ -64,10 +64,11 @@ typedef void* CVDisplayLinkRef;
  #define NSOpenGLContextParameterSurfaceOpacity NSOpenGLCPSurfaceOpacity
 #endif
 
+#define debug_key(...) if (_glfw.hints.init.debugKeyboard) { fprintf(stderr, __VA_ARGS__); fflush(stderr); }
 
 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*);
@@ -130,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;
 
@@ -152,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
@@ -173,8 +177,8 @@ typedef struct _GLFWlibraryNS
     IOHIDManagerRef     hidManager;
     id                  unicodeData;
     id                  helper;
-    id                  keyUpMonitor;
-    id                  keyDownMonitor;
+    id                  keyUpMonitor, keyDownMonitor, flagsChangedMonitor;
+    id                  appleSettings;
     id                  nibObjects;
 
     char                keyName[64];
@@ -198,8 +202,8 @@ typedef struct _GLFWlibraryNS
         _GLFWDisplayLinkNS entries[256];
         size_t count;
     } displayLinks;
-    // the callback to handle file open events
-    GLFWhandlefileopen file_open_callback;
+    // the callback to handle url open events
+    GLFWhandleurlopen url_open_callback;
 
 } _GLFWlibraryNS;
 
@@ -231,7 +235,6 @@ typedef struct _GLFWtimerNS
 
 } _GLFWtimerNS;
 
-
 void _glfwPollMonitorsNS(void);
 void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired);
 void _glfwRestoreVideoModeNS(_GLFWmonitor* monitor);
@@ -248,3 +251,4 @@ void _glfwShutdownCVDisplayLink(unsigned long long, void*);
 void _glfwCocoaPostEmptyEvent(void);
 void _glfw_create_cv_display_link(_GLFWDisplayLinkNS *entry);
 _GLFWDisplayLinkNS* _glfw_create_display_link(CGDirectDisplayID);
+uint32_t vk_to_unicode_key_with_current_layout(uint16_t keycode);

glfw/cocoa_window.m

@@ -32,11 +32,6 @@
 #include <float.h>
 #include <string.h>
 
-#if (MAC_OS_X_VERSION_MAX_ALLOWED < 101300)
-#define NSControlStateValueOn NSOnState
-#define NSControlStateValueOff NSOffState
-#define NSControlStateValueMixed NSMixedState
-#endif
 
 static const char*
 polymorphic_string_as_utf8(id string) {
@@ -259,7 +254,7 @@ is_pua_char(uint32_t ch) {
     return (0xE000 <= ch && ch <= 0xF8FF) || (0xF0000 <= ch && ch <= 0xFFFFF) || (0x100000 <= ch && ch <= 0x10FFFF);
 }
 
-static uint32_t
+uint32_t
 vk_to_unicode_key_with_current_layout(uint16_t keycode)
 {
     UInt32 dead_key_state = 0;
@@ -513,8 +508,6 @@ translateFlags(NSUInteger flags)
     return mods;
 }
 
-#define debug_key(...) if (_glfw.hints.init.debugKeyboard) { fprintf(stderr, __VA_ARGS__); fflush(stderr); }
-
 static const char*
 format_mods(int mods) {
     static char buf[128];
@@ -576,166 +569,11 @@ get_window_size_without_border_in_logical_pixels(_GLFWwindow *window) {
     return [window->ns.object contentRectForFrameRect:[window->ns.object frame]];
 }
 
-// Translate a GLFW keycode to a Cocoa modifier flag
-//
-static NSUInteger
-translateKeyToModifierFlag(uint32_t key)
-{
-    switch (key)
-    {
-        case GLFW_FKEY_LEFT_SHIFT:
-        case GLFW_FKEY_RIGHT_SHIFT:
-            return NSEventModifierFlagShift;
-        case GLFW_FKEY_LEFT_CONTROL:
-        case GLFW_FKEY_RIGHT_CONTROL:
-            return NSEventModifierFlagControl;
-        case GLFW_FKEY_LEFT_ALT:
-        case GLFW_FKEY_RIGHT_ALT:
-            return NSEventModifierFlagOption;
-        case GLFW_FKEY_LEFT_SUPER:
-        case GLFW_FKEY_RIGHT_SUPER:
-            return NSEventModifierFlagCommand;
-        case GLFW_FKEY_CAPS_LOCK:
-            return NSEventModifierFlagCapsLock;
-    }
-
-    return 0;
-}
-
 // Defines a constant for empty ranges in NSTextInputClient
 //
 static const NSRange kEmptyRange = { NSNotFound, 0 };
 
 
-// SecureKeyboardEntryController {{{
-@interface SecureKeyboardEntryController : NSObject
-
-@property (nonatomic, readonly) BOOL isDesired;
-@property (nonatomic, readonly, getter=isEnabled) BOOL enabled;
-
-+ (instancetype)sharedInstance;
-
-- (void)toggle;
-- (void)update;
-
-@end
-
-@implementation SecureKeyboardEntryController {
-    int _count;
-    BOOL _desired;
-}
-
-+ (instancetype)sharedInstance {
-    static id instance;
-    static dispatch_once_t onceToken;
-    dispatch_once(&onceToken, ^{
-        instance = [[self alloc] init];
-    });
-    return instance;
-}
-
-- (instancetype)init {
-    self = [super init];
-    if (self) {
-        _desired = false;
-
-        [[NSNotificationCenter defaultCenter] addObserver:self
-                                                 selector:@selector(applicationDidResignActive:)
-                                                     name:NSApplicationDidResignActiveNotification
-                                                   object:nil];
-        [[NSNotificationCenter defaultCenter] addObserver:self
-                                                 selector:@selector(applicationDidBecomeActive:)
-                                                     name:NSApplicationDidBecomeActiveNotification
-                                                   object:nil];
-        if ([NSApp isActive]) {
-            [self update];
-        }
-    }
-    return self;
-}
-
-#pragma mark - API
-
-- (void)toggle {
-    // Set _desired to the opposite of the current state.
-    _desired = !_desired;
-    debug_key("toggle called. Setting desired to %d", _desired);
-
-    // Try to set the system's state of secure input to the desired state.
-    [self update];
-}
-
-- (BOOL)isEnabled {
-    return !!IsSecureEventInputEnabled();
-}
-
-- (BOOL)isDesired {
-    return _desired;
-}
-
-#pragma mark - Notifications
-
-- (void)applicationDidResignActive:(NSNotification *)notification {
-    (void)notification;
-    if (_count > 0) {
-        debug_key("Application resigning active.");
-        [self update];
-    }
-}
-
-- (void)applicationDidBecomeActive:(NSNotification *)notification {
-    (void)notification;
-    if (self.isDesired) {
-        debug_key("Application became active.");
-        [self update];
-    }
-}
-
-#pragma mark - Private
-
-- (BOOL)allowed {
-    return [NSApp isActive];
-}
-
-- (void)update {
-    debug_key("Update secure keyboard entry. desired=%d active=%d\n",
-         (int)self.isDesired, (int)[NSApp isActive]);
-    const BOOL secure = self.isDesired && [self allowed];
-
-    if (secure && _count > 0) {
-        debug_key("Want to turn on secure input but it's already on\n");
-        return;
-    }
-
-    if (!secure && _count == 0) {
-        debug_key("Want to turn off secure input but it's already off\n");
-        return;
-    }
-
-    debug_key("Before: IsSecureEventInputEnabled returns %d ", (int)self.isEnabled);
-    if (secure) {
-        OSErr err = EnableSecureEventInput();
-        debug_key("EnableSecureEventInput err=%d ", (int)err);
-        if (err) {
-            debug_key("EnableSecureEventInput failed with error %d ", (int)err);
-        } else {
-            _count += 1;
-        }
-    } else {
-        OSErr err = DisableSecureEventInput();
-        debug_key("DisableSecureEventInput err=%d ", (int)err);
-        if (err) {
-            debug_key("DisableSecureEventInput failed with error %d ", (int)err);
-        } else {
-            _count -= 1;
-        }
-    }
-    debug_key("After: IsSecureEventInputEnabled returns %d\n", (int)self.isEnabled);
-}
-
-@end
-// }}}
-
 // Delegate for window related notifications {{{
 
 @interface GLFWWindowDelegate : NSObject
@@ -744,6 +582,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 }
 
 - (instancetype)initWithGlfwWindow:(_GLFWwindow *)initWindow;
+- (void)request_delayed_cursor_update:(id)sender;
 
 @end
 
@@ -854,6 +693,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
@@ -866,9 +708,11 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     _glfwInputWindowFocus(window, false);
     // IME is cancelled when losing the focus
     if ([window->ns.view hasMarkedText]) {
+        [[window->ns.view inputContext] discardMarkedText];
         [window->ns.view unmarkText];
         GLFWkeyevent dummy = {.action = GLFW_RELEASE, .ime_state = GLFW_IME_PREEDIT_CHANGED};
         _glfwInputKeyboard(window, &dummy);
+        _glfw.ns.text[0] = 0;
     }
 }
 
@@ -882,8 +726,54 @@ 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 {{{
+
+@interface GLFWTextInputContext : NSTextInputContext
+@end
+
+@implementation GLFWTextInputContext
+- (void)doCommandBySelector:(SEL)selector
+{
+    // interpretKeyEvents: May call insertText: or doCommandBySelector:.
+    // With the default macOS keybindings, pressing certain key combinations
+    // (e.g. Ctrl+/, Ctrl+Cmd+Down/Left/Right) will produce a beep sound.
+    debug_key("\n\tTextInputCtx: doCommandBySelector: (%s)\n", [NSStringFromSelector(selector) UTF8String]);
+}
+@end // }}}
 
 // Content view class for the GLFW window {{{
 
@@ -891,9 +781,11 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 {
     _GLFWwindow* window;
     NSTrackingArea* trackingArea;
+    GLFWTextInputContext* input_context;
     NSMutableAttributedString* markedText;
     NSRect markedRect;
     bool marked_text_cleared_by_insert;
+    int in_key_handler;
     NSString *input_source_at_last_key_event;
 }
 
@@ -911,9 +803,11 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     {
         window = initWindow;
         trackingArea = nil;
+        input_context = [[GLFWTextInputContext alloc] initWithClient:self];
         markedText = [[NSMutableAttributedString alloc] init];
         markedRect = NSMakeRect(0.0, 0.0, 0.0, 0.0);
         input_source_at_last_key_event = nil;
+        in_key_handler = 0;
 
         [self updateTrackingAreas];
         [self registerForDraggedTypes:@[NSPasteboardTypeFileURL, NSPasteboardTypeString]];
@@ -927,6 +821,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     [trackingArea release];
     [markedText release];
     if (input_source_at_last_key_event) [input_source_at_last_key_event release];
+    [input_context release];
     [super dealloc];
 }
 
@@ -1045,6 +940,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
@@ -1144,6 +1044,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];
@@ -1166,6 +1068,11 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     [super updateTrackingAreas];
 }
 
+- (NSTextInputContext *)inputContext
+{
+    return input_context;
+}
+
 static UInt32
 convert_cocoa_to_carbon_modifiers(NSUInteger flags) {
     UInt32 mods = 0;
@@ -1231,15 +1138,16 @@ is_ascii_control_char(char x) {
 #define UPDATE_PRE_EDIT_TEXT glfw_keyevent.text = [[markedText string] UTF8String]; glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED; _glfwInputKeyboard(window, &glfw_keyevent);
 
     const bool previous_has_marked_text = [self hasMarkedText];
-    NSTextInputContext *inpctx = [NSTextInputContext currentInputContext];
-    if (inpctx && (!input_source_at_last_key_event || ![input_source_at_last_key_event isEqualToString:inpctx.selectedKeyboardInputSource])) {
+    if (input_context && (!input_source_at_last_key_event || ![input_source_at_last_key_event isEqualToString:input_context.selectedKeyboardInputSource])) {
         if (input_source_at_last_key_event) {
             debug_key("Input source changed, clearing pre-edit text and resetting deadkey state\n");
             GLFWkeyevent dummy = {.action = GLFW_RELEASE, .ime_state = GLFW_IME_PREEDIT_CHANGED};
             window->ns.deadKeyState = 0;
             _glfwInputKeyboard(window, &dummy); // clear pre-edit text
+            [input_source_at_last_key_event release];
+            input_source_at_last_key_event = nil;
         }
-        input_source_at_last_key_event = [inpctx.selectedKeyboardInputSource retain];
+        input_source_at_last_key_event = [input_context.selectedKeyboardInputSource retain];
         [self unmarkText];
     }
 
@@ -1247,7 +1155,7 @@ is_ascii_control_char(char x) {
     const NSUInteger flags = [event modifierFlags];
     const int mods = translateFlags(flags);
     const uint32_t key = translateKey(keycode, true);
-    const bool process_text = !window->ns.textInputFilterCallback || window->ns.textInputFilterCallback(key, mods, keycode, flags) != 1;
+    const bool process_text = !_glfw.ignoreOSKeyboardProcessing && (!window->ns.textInputFilterCallback || window->ns.textInputFilterCallback(key, mods, keycode, flags) != 1);
     _glfw.ns.text[0] = 0;
     if (keycode == 0x33 /* backspace */ || keycode == 0x35 /* escape */) [self unmarkText];
     GLFWkeyevent glfw_keyevent = {.key = key, .native_key = keycode, .native_key_id = keycode, .action = GLFW_PRESS, .mods = mods};
@@ -1257,7 +1165,7 @@ is_ascii_control_char(char x) {
         // keyboard unicode data is not available.
         if (process_text) {
             // this will call insertText with the text for this event, if any
-            [self interpretKeyEvents:[NSArray arrayWithObject:event]];
+            [self interpretKeyEvents:@[event]];
         }
     } else {
         static UniChar text[256];
@@ -1284,8 +1192,10 @@ is_ascii_control_char(char x) {
                 keycode, safe_name_for_keycode(keycode), key, format_mods(mods), char_count, window->ns.deadKeyState, event.ARepeat);
         marked_text_cleared_by_insert = false;
         if (process_text) {
+            in_key_handler = 1;
             // this will call insertText which will fill up _glfw.ns.text
-            [self interpretKeyEvents:[NSArray arrayWithObject:event]];
+            [self interpretKeyEvents:@[event]];
+            in_key_handler = 0;
         } else {
             window->ns.deadKeyState = 0;
         }
@@ -1314,6 +1224,7 @@ is_ascii_control_char(char x) {
         }
         if (([self hasMarkedText] || previous_has_marked_text) && !_glfw.ns.text[0]) {
             // do not pass keys like BACKSPACE while there's pre-edit text, let IME handle it
+            debug_key("Ignoring key press as IME is active and it generated no text\n");
             return;
         }
     }
@@ -1329,35 +1240,60 @@ is_ascii_control_char(char x) {
         // insertText followed by setMarkedText
         UPDATE_PRE_EDIT_TEXT;
     }
-#undef CLEAR_PRE_EDIT_TEXT
-#undef UPDATE_PRE_EDIT_TEXT
 }
 
 - (void)flagsChanged:(NSEvent *)event
 {
     int action = GLFW_RELEASE;
-    const unsigned int modifierFlags =
-        [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
-    const uint32_t key = translateKey([event keyCode], false);
+    const char old_first_char = _glfw.ns.text[0];
+    _glfw.ns.text[0] = 0;
+    const NSUInteger modifierFlags = [event modifierFlags] & NSEventModifierFlagDeviceIndependentFlagsMask;
+    const uint32_t key = vk_code_to_functional_key_code([event keyCode]);
+    const unsigned int keycode = [event keyCode];
     const int mods = translateFlags(modifierFlags);
-    const NSUInteger keyFlag = translateKeyToModifierFlag(key);
+    const bool process_text = !_glfw.ignoreOSKeyboardProcessing && (!window->ns.textInputFilterCallback || window->ns.textInputFilterCallback(key, mods, keycode, modifierFlags) != 1);
+    const char *mod_name = "unknown";
 
-    if (keyFlag & modifierFlags)
-    {
-        int current_action = GLFW_RELEASE;
-        for (unsigned i = 0; i < arraysz(window->activated_keys); i++) {
-            if (window->activated_keys[i].key == key) {
-                current_action = window->activated_keys[i].action;
-                break;
-            }
-        }
-        if (current_action == GLFW_PRESS)
-            action = GLFW_RELEASE;
-        else
-            action = GLFW_PRESS;
+    switch(key) {
+        case GLFW_FKEY_CAPS_LOCK:
+            mod_name = "capslock";
+            action = modifierFlags & NSEventModifierFlagCapsLock ? GLFW_PRESS : GLFW_RELEASE; break;
+        case GLFW_FKEY_LEFT_SUPER:
+        case GLFW_FKEY_RIGHT_SUPER:
+            mod_name = "super";
+            action = modifierFlags & NSEventModifierFlagCommand ? GLFW_PRESS : GLFW_RELEASE; break;
+        case GLFW_FKEY_LEFT_CONTROL:
+        case GLFW_FKEY_RIGHT_CONTROL:
+            mod_name = "ctrl";
+            action = modifierFlags & NSEventModifierFlagControl ? GLFW_PRESS : GLFW_RELEASE; break;
+        case GLFW_FKEY_LEFT_ALT:
+        case GLFW_FKEY_RIGHT_ALT:
+            mod_name = "alt";
+            action = modifierFlags & NSEventModifierFlagOption ? GLFW_PRESS : GLFW_RELEASE; break;
+        case GLFW_FKEY_LEFT_SHIFT:
+        case GLFW_FKEY_RIGHT_SHIFT:
+            mod_name = "shift";
+            action = modifierFlags & NSEventModifierFlagShift ? GLFW_PRESS : GLFW_RELEASE; break;
+        default:
+            return;
     }
-
-    GLFWkeyevent glfw_keyevent = {.key = key, .native_key = [event keyCode], .native_key_id = [event keyCode], .action = action, .mods = mods};
+    GLFWkeyevent glfw_keyevent = {.key = key, .native_key = keycode, .native_key_id = keycode, .action = action, .mods = mods};
+    debug_key("\x1b[33mflagsChanged:\x1b[m modifier: %s native_key: 0x%x (%s) glfw_key: 0x%x %s\n",
+            mod_name, keycode, safe_name_for_keycode(keycode), key, format_mods(mods));
+    marked_text_cleared_by_insert = false;
+    if (process_text && input_context) {
+        // this will call insertText which will fill up _glfw.ns.text
+        in_key_handler = 2;
+        [input_context handleEvent:event];
+        in_key_handler = 0;
+        if (marked_text_cleared_by_insert) {
+            debug_key("Clearing pre-edit text because insertText called from flagsChanged\n");
+            CLEAR_PRE_EDIT_TEXT;
+            if (_glfw.ns.text[0]) glfw_keyevent.text = _glfw.ns.text;
+            else _glfw.ns.text[0] = old_first_char;
+        }
+    }
+    glfw_keyevent.ime_state = GLFW_IME_NONE;
     _glfwInputKeyboard(window, &glfw_keyevent);
 }
 
@@ -1374,6 +1310,9 @@ is_ascii_control_char(char x) {
     _glfwInputKeyboard(window, &glfw_keyevent);
 }
 
+#undef CLEAR_PRE_EDIT_TEXT
+#undef UPDATE_PRE_EDIT_TEXT
+
 - (void)scrollWheel:(NSEvent *)event
 {
     double deltaX = [event scrollingDeltaX];
@@ -1429,14 +1368,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];
-                _glfwInputDrop(window, "text/plain;charset=utf-8", path, strlen(path));
+                NSURL *url = (NSURL*)obj;
+                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));
@@ -1446,6 +1388,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;
 }
@@ -1472,8 +1415,19 @@ is_ascii_control_char(char x) {
         selectedRange:(NSRange)selectedRange
      replacementRange:(NSRange)replacementRange
 {
-    debug_key("\n\tsetMarkedText: %s selectedRange: (%lu, %lu) replacementRange: (%lu, %lu)\n", polymorphic_string_as_utf8(string), selectedRange.location, selectedRange.length, replacementRange.location, replacementRange.length);
-    if (string == nil) { [self unmarkText]; return; }
+    const char *s = polymorphic_string_as_utf8(string);
+    debug_key("\n\tsetMarkedText: %s selectedRange: (%lu, %lu) replacementRange: (%lu, %lu)\n", s, selectedRange.location, selectedRange.length, replacementRange.location, replacementRange.length);
+    if (string == nil || !s[0]) {
+        bool had_marked_text = [self hasMarkedText];
+        [self unmarkText];
+        if (had_marked_text && (!in_key_handler || in_key_handler == 2)) {
+            debug_key("Clearing pre-edit because setMarkedText called from %s\n", in_key_handler ? "flagsChanged" : "event loop");
+            GLFWkeyevent glfw_keyevent = {.ime_state = GLFW_IME_PREEDIT_CHANGED};
+            _glfwInputKeyboard(window, &glfw_keyevent);
+            _glfw.ns.text[0] = 0;
+        }
+        return;
+    }
     if ([string isKindOfClass:[NSAttributedString class]]) {
         if (((NSMutableAttributedString*)string).length == 0) { [self unmarkText]; return; }
         [markedText release];
@@ -1483,6 +1437,12 @@ is_ascii_control_char(char x) {
         [markedText release];
         markedText = [[NSMutableAttributedString alloc] initWithString:string];
     }
+    if (!in_key_handler || in_key_handler == 2) {
+        debug_key("Updating IME text in kitty from setMarkedText called from %s: %s\n", in_key_handler ? "flagsChanged" : "event loop", _glfw.ns.text);
+        GLFWkeyevent glfw_keyevent = {.text=[[markedText string] UTF8String], .ime_state = GLFW_IME_PREEDIT_CHANGED};
+        _glfwInputKeyboard(window, &glfw_keyevent);
+        _glfw.ns.text[0] = 0;
+    }
 }
 
 - (void)unmarkText
@@ -1491,15 +1451,23 @@ is_ascii_control_char(char x) {
 }
 
 void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
-    [w->ns.view updateIMEStateFor: ev->type 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 left:(CGFloat)ev->cursor.left top:(CGFloat)ev->cursor.top cellWidth:(CGFloat)ev->cursor.width cellHeight:(CGFloat)ev->cursor.height];
 }
 
 - (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];
+        [self unmarkText];
+        GLFWkeyevent glfw_keyevent = {.ime_state = GLFW_IME_PREEDIT_CHANGED};
+        _glfwInputKeyboard(window, &glfw_keyevent);
+        _glfw.ns.text[0] = 0;
+    }
     if (which != GLFW_IME_UPDATE_CURSOR_POSITION) return;
     left /= window->ns.xscale;
     top /= window->ns.yscale;
@@ -1543,14 +1511,28 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
 {
     const char *utf8 = polymorphic_string_as_utf8(string);
     debug_key("\n\tinsertText: %s replacementRange: (%lu, %lu)\n", utf8, replacementRange.location, replacementRange.length);
-    if ([self hasMarkedText]) {
+    if ([self hasMarkedText] && !is_ascii_control_char(utf8[0])) {
         [self unmarkText];
         marked_text_cleared_by_insert = true;
+        if (!in_key_handler) {
+            debug_key("Clearing pre-edit because insertText called from event loop\n");
+            GLFWkeyevent glfw_keyevent = {.ime_state = GLFW_IME_PREEDIT_CHANGED};
+            _glfwInputKeyboard(window, &glfw_keyevent);
+            _glfw.ns.text[0] = 0;
+        }
     }
     // insertText can be called multiple times for a single key event
     char *s = _glfw.ns.text + strnlen(_glfw.ns.text, sizeof(_glfw.ns.text));
     snprintf(s, sizeof(_glfw.ns.text) - (s - _glfw.ns.text), "%s", utf8);
     _glfw.ns.text[sizeof(_glfw.ns.text) - 1] = 0;
+    if ((!in_key_handler || in_key_handler == 2) && _glfw.ns.text[0]) {
+        if (!is_ascii_control_char(_glfw.ns.text[0])) {
+            debug_key("Sending text to kitty from insertText called from %s: %s\n", in_key_handler ? "flagsChanged" : "event loop", _glfw.ns.text);
+            GLFWkeyevent glfw_keyevent = {.text=_glfw.ns.text, .ime_state=GLFW_IME_COMMIT_TEXT};
+            _glfwInputKeyboard(window, &glfw_keyevent);
+        }
+        _glfw.ns.text[0] = 0;
+    }
 }
 
 - (void)doCommandBySelector:(SEL)selector
@@ -1597,19 +1579,6 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
 
 - (BOOL)validateMenuItem:(NSMenuItem *)item {
     if (item.action == @selector(performMiniaturize:)) return YES;
-    if (item.action == @selector(toggleSecureInput:)) {
-      SecureKeyboardEntryController *controller = [SecureKeyboardEntryController sharedInstance];
-      if (controller.isEnabled) {
-          if (controller.isDesired) {
-              item.state = NSControlStateValueOn;
-          } else {
-              item.state = NSControlStateValueMixed;
-          }
-      } else {
-          item.state = controller.isDesired ? NSControlStateValueOn : NSControlStateValueOff;
-      }
-      return YES;
-    }
     return [super validateMenuItem:item];
 }
 
@@ -1619,11 +1588,6 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
     else [super performMiniaturize:sender];
 }
 
-- (void)toggleSecureInput:(id)sender {
-    (void)sender;
-    [[SecureKeyboardEntryController sharedInstance] toggle];
-}
-
 - (BOOL)canBecomeKeyWindow
 {
     // Required for NSWindowStyleMaskBorderless windows
@@ -1637,8 +1601,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)
-            return;
+    if (glfw_window) {
+        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)];
@@ -1764,7 +1731,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)
     {
@@ -2449,7 +2420,7 @@ void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor UNUSED)
 bool _glfwPlatformIsFullscreen(_GLFWwindow* w, unsigned int flags) {
     NSWindow *window = w->ns.object;
     bool traditional = !(flags & 1);
-    if (traditional) { if(@available(macOS 11.0, *)) return w->ns.in_traditional_fullscreen; }
+    if (traditional) { if(@available(macOS 10.15.7, *)) return w->ns.in_traditional_fullscreen; }
     NSWindowStyleMask sm = [window styleMask];
     return sm & NSWindowStyleMaskFullScreen;
 }
@@ -2460,8 +2431,9 @@ bool _glfwPlatformToggleFullscreen(_GLFWwindow* w, unsigned int flags) {
     bool traditional = !(flags & 1);
     NSWindowStyleMask sm = [window styleMask];
     if (traditional) {
-        if (@available(macOS 11.0, *)) {
+        if (@available(macOS 10.15.7, *)) {
             // As of Big Turd NSWindowStyleMaskFullScreen is no longer useable
+            // Also no longer compatible after a minor release of macOS 10.15.7
             if (!w->ns.in_traditional_fullscreen) {
                 w->ns.pre_full_screen_style_mask = sm;
                 [window setStyleMask: NSWindowStyleMaskBorderless];
@@ -2510,25 +2482,35 @@ void _glfwPlatformSetClipboardString(const char* string)
 const char* _glfwPlatformGetClipboardString(void)
 {
     NSPasteboard* pasteboard = [NSPasteboard generalPasteboard];
+    free(_glfw.ns.clipboardString); _glfw.ns.clipboardString = NULL;
 
-    if (![[pasteboard types] containsObject:NSPasteboardTypeString])
-    {
-        _glfwInputError(GLFW_FORMAT_UNAVAILABLE,
-                        "Cocoa: Failed to retrieve string from pasteboard");
-        return NULL;
+    NSDictionary* options = @{NSPasteboardURLReadingFileURLsOnlyKey:@YES};
+    NSArray* objs = [pasteboard readObjectsForClasses:@[[NSURL class], [NSString class]] options:options];
+    if (objs) {
+        const NSUInteger count = [objs count];
+        if (count) {
+            NSMutableString *path_list = [NSMutableString stringWithCapacity:4096];  // auto-released
+            NSMutableString *text_list = [NSMutableString stringWithCapacity: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 appendString:@("\n")];
+                        [path_list appendString:@(url.fileSystemRepresentation)];
+                    }
+                } else if ([obj isKindOfClass:[NSString class]]) {
+                    if ([text_list length] > 0) [text_list appendString:@("\n")];
+                    [text_list appendString:obj];
+                }
+            }
+            const char *text = NULL;
+            if (path_list.length > 0) text = [path_list UTF8String];
+            else if (text_list.length > 0) text = [text_list UTF8String];
+            if (text) _glfw.ns.clipboardString = _glfw_strdup(text);
+        }
     }
-
-    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]);
-
+    if (!_glfw.ns.clipboardString) _glfwInputError(GLFW_PLATFORM_ERROR, "Cocoa: Failed to retrieve object from pasteboard");
     return _glfw.ns.clipboardString;
 }
 
@@ -2724,10 +2706,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;
-    _glfw.ns.file_open_callback = callback;
+    GLFWhandleurlopen prev = _glfw.ns.url_open_callback;
+    _glfw.ns.url_open_callback = callback;
     return prev;
 }
 

glfw/dbus_glfw.c

@@ -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;

glfw/glfw.py

@@ -67,7 +67,7 @@ class Env:
 
 def wayland_protocol_file_name(base: str, ext: str = 'c') -> str:
     base = os.path.basename(base).rpartition('.')[0]
-    return 'wayland-{}-client-protocol.{}'.format(base, ext)
+    return f'wayland-{base}-client-protocol.{ext}'
 
 
 def init_env(
@@ -80,7 +80,7 @@ def init_env(
 ) -> Env:
     ans = env.copy()
     ans.cflags.append('-fPIC')
-    ans.cppflags.append('-D_GLFW_' + module.upper())
+    ans.cppflags.append(f'-D_GLFW_{module.upper()}')
     ans.cppflags.append('-D_GLFW_BUILD_DLL')
 
     with open(os.path.join(base, 'source-info.json')) as f:
@@ -111,7 +111,7 @@ def init_env(
 
     elif module == 'cocoa':
         ans.cppflags.append('-DGL_SILENCE_DEPRECATION')
-        for f_ in 'Cocoa Carbon IOKit CoreFoundation CoreVideo'.split():
+        for f_ in 'Cocoa IOKit CoreFoundation CoreVideo'.split():
             ans.ldpaths.extend(('-framework', f_))
 
     elif module == 'wayland':
@@ -150,14 +150,14 @@ def build_wayland_protocols(
     for protocol in env.wayland_protocols:
         src = os.path.join(env.wayland_packagedir, protocol)
         if not os.path.exists(src):
-            raise SystemExit('The wayland-protocols package on your system is missing the {} protocol definition file'.format(protocol))
+            raise SystemExit(f'The wayland-protocols package on your system is missing the {protocol} protocol definition file')
         for ext in 'hc':
             dest = wayland_protocol_file_name(src, ext)
             dest = os.path.join(dest_dir, dest)
             if newer(dest, src):
                 q = 'client-header' if ext == 'h' else env.wayland_scanner_code
                 items.append(Command(
-                    'Generating {} ...'.format(emphasis(os.path.basename(dest))),
+                    f'Generating {emphasis(os.path.basename(dest))} ...',
                     [env.wayland_scanner, q, src, dest], lambda: True))
     if items:
         parallel_run(items)
@@ -174,7 +174,7 @@ class Arg:
             self.type = self.type + '*'
 
     def __repr__(self) -> str:
-        return 'Arg({}, {})'.format(self.type, self.name)
+        return f'Arg({self.type}, {self.name})'
 
 
 class Function:
@@ -233,7 +233,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)
@@ -277,7 +277,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 +292,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

@@ -1024,6 +1024,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 +1216,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 {
@@ -4119,6 +4130,9 @@ GLFWAPI GLFWwindowcontentscalefun glfwSetWindowContentScaleCallback(GLFWwindow*
  */
 GLFWAPI void glfwPostEmptyEvent(void);
 
+GLFWAPI bool glfwGetIgnoreOSKeyboardProcessing(void);
+GLFWAPI void glfwSetIgnoreOSKeyboardProcessing(bool enabled);
+
 /*! @brief Returns the value of an input option for the specified window.
  *
  *  This function returns the value of an input option for the specified window.

glfw/ibus_glfw.c

@@ -24,6 +24,17 @@
 //
 //========================================================================
 
+/* To test under X11 start IBUS as:
+ * ibus-daemon -drxR
+ * Setup the input sources you want with:
+ * ibus-setup
+ * Switch to the input source you want to test with:
+ * ibus engine name
+ * You can list available engines with:
+ * ibus list-engine
+ * Then run kitty as:
+ * GLFW_IM_MODULE=ibus kitty
+ */
 #define _GNU_SOURCE
 #include <stdio.h>
 #include <errno.h>
@@ -226,6 +237,7 @@ message_handler(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data)
             break;
         case 2:
             debug("IBUS: HidePreeditText\n");
+            send_text("", GLFW_IME_PREEDIT_CHANGED);
             break;
         case 3:
             debug("IBUS: ShowPreeditText\n");

glfw/init.c

@@ -227,6 +227,7 @@ GLFWAPI int glfwInit(monotonic_t start_time)
 
     memset(&_glfw, 0, sizeof(_glfw));
     _glfw.hints.init = _glfwInitHints;
+    _glfw.ignoreOSKeyboardProcessing = false;
 
     if (!_glfwPlatformInit())
     {

glfw/input.c

@@ -667,6 +667,14 @@ void _glfwCenterCursorInContentArea(_GLFWwindow* window)
 //////                        GLFW public API                       //////
 //////////////////////////////////////////////////////////////////////////
 
+GLFWAPI bool glfwGetIgnoreOSKeyboardProcessing(void) {
+    return _glfw.ignoreOSKeyboardProcessing;
+}
+
+GLFWAPI void glfwSetIgnoreOSKeyboardProcessing(bool enabled) {
+    _glfw.ignoreOSKeyboardProcessing = enabled;
+}
+
 GLFWAPI int glfwGetInputMode(GLFWwindow* handle, int mode)
 {
     _GLFWwindow* window = (_GLFWwindow*) handle;

glfw/internal.h

@@ -307,6 +307,7 @@ struct _GLFWwndconfig
     bool          scaleToMonitor;
     struct {
         bool      retina;
+        int       color_space;
         char      frameName[256];
     } ns;
     struct {
@@ -584,6 +585,8 @@ struct _GLFWlibrary
     _GLFWtls            contextSlot;
     _GLFWmutex          errorLock;
 
+    bool                ignoreOSKeyboardProcessing;
+
     struct {
         bool            available;
         void*           handle;

glfw/linux_desktop_settings.c

@@ -10,77 +10,118 @@
 #include <strings.h>
 #include <string.h>
 
-static const char *DESKTOP_SERVICE = "org.freedesktop.portal.Desktop";
-static const char *DESKTOP_PATH = "/org/freedesktop/portal/desktop";
-static const char *DESKTOP_INTERFACE = "org.freedesktop.portal.Settings";
-static const char *GNOME_DESKTOP_NAMESPACE = "org.gnome.desktop.interface";
+#define DESKTOP_SERVICE "org.freedesktop.portal.Desktop"
+#define DESKTOP_PATH "/org/freedesktop/portal/desktop"
+#define DESKTOP_INTERFACE "org.freedesktop.portal.Settings"
+#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
-parse_dbus_message_for_type(DBusMessage *const reply, const char *errmsg, const int type, void *value) {
-	DBusMessageIter iter[3];
-	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)
-    const char *name;
-    if (!parse_dbus_message_for_type(msg, "Failed to get cursor theme name from reply", DBUS_TYPE_STRING, &name)) return;
-    if (name && name[0]) {
-        gnome_cursor_theme_read = true;
-        strncpy(theme_name, name, sizeof(theme_name) - 1);
-        if (gnome_cursor_size_read) _glfwPlatformChangeCursorTheme();
+static void
+process_fdo_setting(const char *key, DBusMessageIter *value) {
+    if (strcmp(key, FDO_APPEARANCE_KEY) == 0) {
+        if (dbus_message_iter_get_arg_type(value) == DBUS_TYPE_UINT32) {
+            dbus_message_iter_get_basic(value, &appearance);
+            if (appearance > 2) appearance = 0;
+        }
     }
 }
 
-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) {
-    theme_size = 32;
-    DBusConnection *session_bus = glfw_dbus_session_bus();
-    if (session_bus) {
-        const char *theme_key = "cursor-theme";
-        call_read(session_bus, on_gnome_cursor_theme_read, GNOME_DESKTOP_NAMESPACE, theme_key);
-        const char *size_key = "cursor-size";
-        call_read(session_bus, on_gnome_cursor_size_read, GNOME_DESKTOP_NAMESPACE, size_key);
+process_gnome_setting(const char *key, DBusMessageIter *value) {
+    if (strcmp(key, "cursor-size") == 0) {
+        if (dbus_message_iter_get_arg_type(value) == DBUS_TYPE_INT32) {
+            int32_t sz;
+            dbus_message_iter_get_basic(value, &sz);
+            if (sz > 0 && sz != theme_size) {
+                theme_size = sz;
+                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 +141,55 @@ 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;
+                }
+            }
+            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;
-    if (is_gnome) get_from_gnome();
+    is_gnome = desktop && strstr(desktop, "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/window.c

@@ -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;

glfw/wl_client_side_decorations.c

@@ -102,13 +102,31 @@ 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) decs.which.buffer.a == q || decs.which.buffer.b == q
+    return Q(left) || Q(top) || Q(right) || Q(bottom);
+#undef Q
+}
+
 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);
+    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);
+    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 +305,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 +331,6 @@ 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.b) wl_buffer_destroy(decs.which.buffer.b); \
     memset(&decs.which.buffer, 0, sizeof(_GLFWWaylandBufferPair)); \
 }
     d(left); d(top); d(right); d(bottom);
@@ -352,11 +368,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 +428,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;

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,7 +98,6 @@ static void pointerHandleEnter(void* data UNUSED,
         if (!window)
             return;
     }
-
     window->wl.decorations.focus = focus;
     _glfw.wl.serial = serial;
     _glfw.wl.pointerFocus = window;
@@ -142,10 +143,15 @@ static void setCursor(GLFWCursorShape shape, _GLFWwindow* window)
 
     if (!image)
         return;
+    if (image->width % scale || image->height % scale) {
+        _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);
+    }
 
     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 +249,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);
@@ -331,20 +337,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)
-        x = -wl_fixed_to_double(value);
-    else if (axis == WL_POINTER_AXIS_VERTICAL_SCROLL)
-        y = -wl_fixed_to_double(value);
+    if (axis == WL_POINTER_AXIS_HORIZONTAL_SCROLL) {
+        if (window->wl.axis_discrete_count.x) {
+            window->wl.axis_discrete_count.x--;
+            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,
@@ -504,6 +573,10 @@ static void seatHandleCapabilities(void* data UNUSED,
     {
         wl_pointer_destroy(_glfw.wl.pointer);
         _glfw.wl.pointer = NULL;
+        if (_glfw.wl.cursorAnimationTimer) {
+            removeTimer(&_glfw.wl.eventLoopData, _glfw.wl.cursorAnimationTimer);
+            _glfw.wl.cursorAnimationTimer = 0;
+        }
     }
 
     if ((caps & WL_SEAT_CAPABILITY_KEYBOARD) && !_glfw.wl.keyboard)
@@ -515,6 +588,11 @@ 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) {
+            removeTimer(&_glfw.wl.eventLoopData, _glfw.wl.keyRepeatInfo.keyRepeatTimer);
+            _glfw.wl.keyRepeatInfo.keyRepeatTimer = 0;
+        }
     }
 }
 
@@ -571,7 +649,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);

glfw/wl_platform.h

@@ -127,6 +127,10 @@ typedef enum WaylandWindowState {
 
 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
 //
@@ -168,7 +172,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 +214,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

glfw/wl_text_input.c

@@ -47,7 +47,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,7 +84,7 @@ 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);
@@ -93,6 +93,9 @@ text_input_done(void *data UNUSED, struct zwp_text_input_v3 *txt_input UNUSED, u
     if (pending_pre_edit) {
         send_text(pending_pre_edit, GLFW_IME_PREEDIT_CHANGED);
         free(pending_pre_edit); pending_pre_edit = NULL;
+    } else {
+        // Clear pre-edit text
+        send_text(NULL, GLFW_IME_WAYLAND_DONE_EVENT);
     }
     if (pending_commit) {
         send_text(pending_commit, GLFW_IME_COMMIT_TEXT);
@@ -139,7 +142,20 @@ _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 {
+                if (pending_pre_edit) {
+                    // Clear pre-edit text
+                    send_text(NULL, GLFW_IME_PREEDIT_CHANGED);
+                    free(pending_pre_edit); pending_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: {

glfw/wl_window.c

@@ -147,6 +147,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,
@@ -234,7 +235,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 +247,14 @@ dispatchChangesAfterConfigure(_GLFWwindow *window, int32_t width, int32_t height
     }
 
     if (scale_changed) {
-        if (!size_changed)
-            resizeFramebuffer(window);
+        debug("Scale changed to %d in dispatchChangesAfterConfigure\n", window->wl.scale);
+        if (!size_changed) resizeFramebuffer(window);
         _glfwInputWindowContentScale(window, window->wl.scale, window->wl.scale);
     }
 
     _glfwInputWindowDamage(window);
+
+    return size_changed || scale_changed;
 }
 
 static void
@@ -269,24 +272,9 @@ xdgDecorationHandleConfigure(void* data,
                                          uint32_t mode)
 {
     _GLFWwindow* window = data;
-
-    bool has_server_side_decorations = (mode == ZXDG_TOPLEVEL_DECORATION_V1_MODE_SERVER_SIDE);
-    debug("XDG decoration configure event received: has_server_side_decorations: %d\n", has_server_side_decorations);
-    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");
+    window->wl.pending.decoration_mode = mode;
+    window->wl.pending_state |= PENDING_STATE_DECORATION;
+    debug("XDG decoration configure event received: has_server_side_decorations: %d\n", (mode == ZXDG_TOPLEVEL_DECORATION_V1_MODE_SERVER_SIDE));
 }
 
 static const struct zxdg_toplevel_decoration_v1_listener xdgDecorationListener = {
@@ -311,6 +299,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 +325,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);
@@ -416,7 +406,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 +448,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 +465,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;
-    set_csd_window_geometry(window, &width, &height);
-    dispatchChangesAfterConfigure(window, width, height);
-    debug("final window content size: %dx%d\n", window->wl.width, window->wl.height);
-    _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);
+
+    window->wl.pending.toplevel_states = new_states;
+    window->wl.pending.width = width;
+    window->wl.pending.height = height;
+    window->wl.pending_state |= PENDING_STATE_TOPLEVEL;
 }
 
 static void xdgToplevelHandleClose(void* data,
@@ -499,11 +484,64 @@ 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)
 {
+    _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->wl.surface_configured_once = true;
+            if (!width && !height && !new_states && !window->wl.decorations.serverSide && getenv("XAUTHORITY") && strstr(getenv("XAUTHORITY"), "mutter")) {
+                // https://github.com/kovidgoyal/kitty/issues/4802
+                debug("Ignoring first empty surface configure event on mutter.\n");
+                return;
+            }
+        }
+
+        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;
+    }
+
+    bool resized = false;
+    if (window->wl.pending_state) {
+        int width = window->wl.pending.width, height = window->wl.pending.height;
+        set_csd_window_geometry(window, &width, &height);
+        resized = dispatchChangesAfterConfigure(window, width, height);
+        if (window->wl.decorations.serverSide) {
+            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");
+
+    // if a resize happened there will be a commit at the next render frame so
+    // dont commit here, GNOME doesnt like it and its not really needed anyway
+    if (!resized) wl_surface_commit(window->wl.surface);
+    window->wl.pending_state = 0;
 }
 
 static const struct xdg_surface_listener xdgSurfaceListener = {
@@ -991,7 +1029,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.
@@ -1092,7 +1130,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)
@@ -1360,6 +1398,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,6 +1435,7 @@ 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);
     }
 }

glfw/xkb_glfw.c

@@ -33,7 +33,7 @@
 #include <X11/XKBlib.h>
 #endif
 
-#define debug(...) if (_glfw.hints.init.debugKeyboard) printf(__VA_ARGS__);
+#define debug(...) if (_glfw.hints.init.debugKeyboard) fprintf(stderr, __VA_ARGS__);
 
 #ifdef XKB_HAS_NO_UTF32
 #include "xkb-compat-shim.h"
@@ -827,7 +827,7 @@ glfw_xkb_key_from_ime(_GLFWIBUSKeyEvent *ev, bool handled_by_ime, bool failed) {
     xkb_keycode_t prev_handled_press = last_handled_press_keycode;
     last_handled_press_keycode = 0;
     bool is_release = ev->glfw_ev.action == GLFW_RELEASE;
-    debug("From IBUS: native_key: 0x%x name: %s is_release: %d\n", ev->glfw_ev.native_key, glfw_xkb_keysym_name(ev->glfw_ev.key), is_release);
+    debug("From IBUS: native_key: 0x%x name: %s is_release: %d handled_by_ime: %d\n", ev->glfw_ev.native_key, glfw_xkb_keysym_name(ev->glfw_ev.key), is_release, handled_by_ime);
     if (window && !handled_by_ime && !(is_release && ev->glfw_ev.native_key == (int) prev_handled_press)) {
         debug("↳ to application: glfw_keycode: 0x%x (%s) keysym: 0x%x (%s) action: %s %s text: %s\n",
             ev->glfw_ev.native_key, _glfwGetKeyName(ev->glfw_ev.native_key), ev->glfw_ev.key, glfw_xkb_keysym_name(ev->glfw_ev.key),

kittens/ask/main.py

@@ -4,13 +4,15 @@
 import os
 import sys
 from contextlib import suppress
-from typing import TYPE_CHECKING, Dict, List, NamedTuple, Optional, Tuple
+from typing import (
+    TYPE_CHECKING, Callable, Dict, List, NamedTuple, Optional, Tuple
+)
 
 from kitty.cli import parse_args
 from kitty.cli_stub import AskCLIOptions
 from kitty.constants import cache_dir
-from kitty.fast_data_types import wcswidth
-from kitty.typing import BossType, TypedDict
+from kitty.fast_data_types import truncate_point_for_length, wcswidth
+from kitty.typing import BossType, KeyEventType, TypedDict
 from kitty.utils import ScreenSize
 
 from ..tui.handler import Handler, result_handler
@@ -72,7 +74,7 @@ class HistoryCompleter:
 def option_text() -> str:
     return '''\
 --type -t
-choices=line,yesno,choices
+choices=line,yesno,choices,password
 default=line
 Type of input. Defaults to asking for a line of text.
 
@@ -90,11 +92,22 @@ be used for completions and via the browse history readline bindings.
 --choice -c
 type=list
 dest=choices
-A choice for the choices type. Every choice has the syntax: letter:text Where
-letter is the accelerator key and text is the corresponding text.  There can be
-an optional color specification after the letter to indicate what color it should
-be.
-For example: y:Yes and n;red:No
+A choice for the choices type. Can be specified multiple times. Every choice has
+the syntax: ``letter[;color]:text``. Where :italic:`letter` is the accelerator key
+and :italic:`text` is the corresponding text. There can be an optional color
+specification after the letter to indicate what color it should be.
+For example: :code:`y:Yes` and :code:`n;red:No`
+
+
+--default -d
+A default choice or text. If unspecified, it is :code:`y` for the type
+:code:`yesno`, the first choice for :code:`choices` and empty for others types.
+The default choice is selected when the user presses the :kbd:`Enter` key.
+
+
+--prompt -p
+default="> "
+The prompt to use when inputting a line of text or a password.
 '''
 
 
@@ -107,6 +120,7 @@ class Choice(NamedTuple):
     text: str
     idx: int
     color: str
+    letter: str
 
 
 class Range(NamedTuple):
@@ -118,27 +132,93 @@ class Range(NamedTuple):
         return y == self.y and self.start <= x <= self.end
 
 
+def truncate_at_space(text: str, width: int) -> Tuple[str, str]:
+    p = truncate_point_for_length(text, width)
+    if p < len(text):
+        i = text.rfind(' ', 0, p + 1)
+        if i > 0 and p - i < 12:
+            p = i + 1
+    return text[:p], text[p:]
+
+
+def extra_for(width: int, screen_width: int) -> int:
+    return max(0, screen_width - width) // 2 + 1
+
+
+class Password(Handler):
+
+    def __init__(self, cli_opts: AskCLIOptions, prompt: str) -> None:
+        self.cli_opts = cli_opts
+        self.prompt = prompt
+        from kittens.tui.line_edit import LineEdit
+        self.line_edit = LineEdit(is_password=True)
+
+    def initialize(self) -> None:
+        self.cmd.set_cursor_shape('beam')
+        self.draw_screen()
+
+    @Handler.atomic_update
+    def draw_screen(self) -> None:
+        self.cmd.clear_screen()
+        if self.cli_opts.message:
+            for line in self.cli_opts.message.splitlines():
+                self.print(line)
+            self.print()
+        self.line_edit.write(self.write, self.prompt)
+
+    def on_text(self, text: str, in_bracketed_paste: bool = False) -> None:
+        self.line_edit.on_text(text, in_bracketed_paste)
+        self.draw_screen()
+
+    def on_key(self, key_event: KeyEventType) -> None:
+        if self.line_edit.on_key(key_event):
+            self.draw_screen()
+            return
+        if key_event.matches('enter'):
+            self.quit_loop(0)
+        if key_event.matches('esc'):
+            self.quit_loop(1)
+
+    def on_resize(self, screen_size: ScreenSize) -> None:
+        self.screen_size = screen_size
+        self.draw_screen()
+
+    def on_interrupt(self) -> None:
+        self.quit_loop(1)
+    on_eot = on_interrupt
+
+    @property
+    def response(self) -> str:
+        if self._tui_loop.return_code == 0:
+            return self.line_edit.current_input
+        return ''
+
+
 class Choose(Handler):
     mouse_tracking = MouseTracking.buttons_only
 
     def __init__(self, cli_opts: AskCLIOptions) -> None:
         self.cli_opts = cli_opts
-        self.response = 'n' if cli_opts.type == 'yesno' else ''
-        self.allowed = frozenset('yn')
         self.choices: Dict[str, Choice] = {}
-        self.clickable_ranges: Dict[str, Range] = {}
-        if cli_opts.type != 'yesno':
+        self.clickable_ranges: Dict[str, List[Range]] = {}
+        if cli_opts.type == 'yesno':
+            self.allowed = frozenset('yn')
+        else:
             allowed = []
             for choice in cli_opts.choices:
-                color = 'green'
                 letter, text = choice.split(':', maxsplit=1)
+                color = ''
                 if ';' in letter:
                     letter, color = letter.split(';', maxsplit=1)
                 letter = letter.lower()
                 idx = text.lower().index(letter)
                 allowed.append(letter)
-                self.choices[letter] = Choice(text, idx, color)
+                self.choices[letter] = Choice(text, idx, color, letter)
             self.allowed = frozenset(allowed)
+        self.response = ''
+        self.response_on_accept = cli_opts.default or ''
+        if cli_opts.type in ('yesno', 'choices') and self.response_on_accept not in self.allowed:
+            self.response_on_accept = 'y' if cli_opts.type == 'yesno' else tuple(self.choices.keys())[0]
 
     def initialize(self) -> None:
         self.cmd.set_cursor_visible(False)
@@ -147,52 +227,164 @@ class Choose(Handler):
     def finalize(self) -> None:
         self.cmd.set_cursor_visible(True)
 
+    def draw_long_text(self, text: str) -> int:
+        y = 0
+        width = self.screen_size.cols - 2
+        while text:
+            t, text = truncate_at_space(text, width)
+            t = t.strip()
+            self.print(' ' * extra_for(wcswidth(t), width), styled(t, bold=True), sep='')
+            y += 1
+        return y
+
     @Handler.atomic_update
     def draw_screen(self) -> None:
         self.cmd.clear_screen()
-        y = 1
+        y = max(0, self.screen_size.rows // 2 - 2)
+        self.print(end='\r\n'*y)
         if self.cli_opts.message:
-            self.cmd.styled(self.cli_opts.message, bold=True)
-            y += wcswidth(self.cli_opts.message) // self.screen_size.cols
-        self.print()
+            for line in self.cli_opts.message.splitlines():
+                y += self.draw_long_text(line)
+        if self.screen_size.rows > 2:
+            self.print()
+            y += 1
         if self.cli_opts.type == 'yesno':
             self.draw_yesno(y)
         else:
             self.draw_choice(y)
 
-    def draw_choice(self, y: int) -> None:
-        x = 0
+    def draw_choice_boxes(self, y: int, *choices: Choice) -> None:
         self.clickable_ranges.clear()
+        width = self.screen_size.cols - 2
+        current_line_length = 0
+        current_line: List[Tuple[str, str]] = []
+        lines: List[List[Tuple[str, str]]] = []
+        sep, sep_sz = '  ', 2
+
+        for choice in choices:
+            self.clickable_ranges[choice.letter] = []
+            text = ' ' + choice.text[:choice.idx]
+            text += styled(choice.text[choice.idx], fg=choice.color or 'green')
+            text += choice.text[choice.idx + 1:] + ' '
+            sz = wcswidth(text)
+            if sz + sep_sz + current_line_length > width:
+                lines.append(current_line)
+                current_line = []
+                current_line_length = 0
+            current_line.append((choice.letter, text))
+            current_line_length += sz
+        if current_line:
+            lines.append(current_line)
+
+        def top(text: str) -> str:
+            return '╭' + '─' * wcswidth(text) + '╮'
+
+        def middle(text: str) -> str:
+            return f'│{text}│'
+
+        def bottom(text: str) -> str:
+            return '╰' + '─' * wcswidth(text) + '╯'
+
+        def highlight(text: str, only_edges: bool = False) -> str:
+            if only_edges:
+                return styled(text[0], fg='yellow') + text[1:-1] + styled(text[-1], fg='yellow')
+            return styled(text, fg='yellow')
+
+        def print_line(add_borders: Callable[[str], str], *items: Tuple[str, str], is_last: bool = False) -> None:
+            nonlocal y
+            texts = []
+            positions = []
+            x = 0
+            for (letter, text) in items:
+                positions.append((letter, x, wcswidth(text) + 2))
+                text = add_borders(text)
+                if letter == self.response_on_accept:
+                    text = highlight(text, only_edges=add_borders is middle)
+                text += sep
+                x += wcswidth(text)
+                texts.append(text)
+            line = ''.join(texts).rstrip()
+            offset = extra_for(wcswidth(line), width)
+            for (letter, x, sz) in positions:
+                x += offset
+                self.clickable_ranges[letter].append(Range(x, x + sz - 1, y))
+            self.print(' ' * offset, line, sep='', end='' if is_last else '\r\n')
+            y += 1
+
+        for boxed_line in lines:
+            print_line(top, *boxed_line)
+            print_line(middle, *boxed_line)
+            print_line(bottom, *boxed_line, is_last=boxed_line is lines[-1])
+
+    def draw_choice(self, y: int) -> None:
+        if y + 3 <= self.screen_size.rows:
+            self.draw_choice_boxes(y, *self.choices.values())
+            return
+        self.clickable_ranges.clear()
+        current_line = ''
+        current_ranges: Dict[str, int] = {}
+        width = self.screen_size.cols - 2
+
+        def commit_line(end: str = '\r\n') -> None:
+            nonlocal current_line, y
+            x = extra_for(wcswidth(current_line), width)
+            self.print(' ' * x + current_line, end=end)
+            for letter, sz in current_ranges.items():
+                self.clickable_ranges[letter] = [Range(x, x + sz - 3, y)]
+                x += sz
+            current_ranges.clear()
+            y += 1
+            current_line = ''
+
         for letter, choice in self.choices.items():
             text = choice.text[:choice.idx]
-            text += styled(choice.text[choice.idx], fg=choice.color)
+            text += styled(choice.text[choice.idx], fg=choice.color or 'green', underline='straight' if letter == self.response_on_accept else None)
             text += choice.text[choice.idx + 1:]
             text += '  '
             sz = wcswidth(text)
-            if sz + x >= self.screen_size.cols:
-                y += 1
-                x = 0
-                self.print()
-            self.clickable_ranges[letter] = Range(x, x + sz - 1, y)
-            x += sz
-            self.print(text, end='')
+            if sz + wcswidth(current_line) >= width:
+                commit_line()
+            current_line += text
+            current_ranges[letter] = sz
+        if current_line:
+            commit_line(end='')
 
     def draw_yesno(self, y: int) -> None:
-        self.clickable_ranges = {'y': Range(2, 4, y), 'n': Range(8, 9, y)}
-        self.print(' ', styled('Y', fg='green') + 'es', ' ', styled('N', fg='red') + 'o')
+        yes = styled('Y', fg='green') + 'es'
+        no = styled('N', fg='red') + 'o'
+        if y + 3 <= self.screen_size.rows:
+            self.draw_choice_boxes(y, Choice('Yes', 0, 'green', 'y'), Choice('No', 0, 'red', 'n'))
+            return
+        sep = ' ' * 3
+        text = yes + sep + no
+        w = wcswidth(text)
+        x = extra_for(w, self.screen_size.cols - 2)
+        nx = x + wcswidth(yes) + len(sep)
+        self.clickable_ranges = {'y': [Range(x, x + wcswidth(yes) - 1, y)], 'n': [Range(nx, nx + wcswidth(no) - 1, y)]}
+        self.print(' ' * x + text, end='')
 
     def on_text(self, text: str, in_bracketed_paste: bool = False) -> None:
         text = text.lower()
         if text in self.allowed:
             self.response = text
             self.quit_loop(0)
+        elif self.cli_opts.type == 'yesno':
+            self.on_interrupt()
+
+    def on_key(self, key_event: KeyEventType) -> None:
+        if key_event.matches('esc'):
+            self.on_interrupt()
+        elif key_event.matches('enter'):
+            self.response = self.response_on_accept
+            self.quit_loop(0)
 
     def on_click(self, ev: MouseEvent) -> None:
-        for letter, r in self.clickable_ranges.items():
-            if r.has_point(ev.cell_x, ev.cell_y):
-                self.response = letter
-                self.quit_loop(0)
-                break
+        for letter, ranges in self.clickable_ranges.items():
+            for r in ranges:
+                if r.has_point(ev.cell_x, ev.cell_y):
+                    self.response = letter
+                    self.quit_loop(0)
+                    return
 
     def on_resize(self, screen_size: ScreenSize) -> None:
         self.screen_size = screen_size
@@ -214,7 +406,7 @@ def main(args: List[str]) -> Response:
     except SystemExit as e:
         if e.code != 0:
             print(e.args[0])
-            input('Press enter to quit...')
+            input('Press Enter to quit')
         raise SystemExit(e.code)
 
     if cli_opts.type in ('yesno', 'choices'):
@@ -223,6 +415,15 @@ def main(args: List[str]) -> Response:
         loop.loop(handler)
         return {'items': items, 'response': handler.response}
 
+    prompt = cli_opts.prompt
+    if prompt[0] == prompt[-1] and prompt[0] in '\'"':
+        prompt = prompt[1:-1]
+    if cli_opts.type == 'password':
+        loop = Loop()
+        phandler = Password(cli_opts, prompt)
+        loop.loop(phandler)
+        return {'items': items, 'response': phandler.response}
+
     import readline as rl
     readline = rl
     from kitty.shell import init_readline
@@ -233,9 +434,16 @@ def main(args: List[str]) -> Response:
         if cli_opts.message:
             print(styled(cli_opts.message, bold=True))
 
-        prompt = '> '
         with suppress(KeyboardInterrupt, EOFError):
-            response = input(prompt)
+            if cli_opts.default:
+                def prefill_text() -> None:
+                    readline.insert_text(cli_opts.default or '')
+                    readline.redisplay()
+                readline.set_pre_input_hook(prefill_text)
+                response = input(prompt)
+                readline.set_pre_input_hook()
+            else:
+                response = input(prompt)
     return {'items': items, 'response': response}
 
 

kittens/broadcast/main.py

@@ -99,7 +99,7 @@ class Broadcast(Handler):
 
 
 OPTIONS = (MATCH_WINDOW_OPTION + '\n\n' + MATCH_TAB_OPTION.replace('--match -m', '--match-tab -t')).format
-help_text = 'Broadcast typed text to all kitty windows. By default text is sent to all windows, unless one of the matching options is specified'
+help_text = 'Broadcast typed text to kitty windows. By default text is sent to all windows, unless one of the matching options is specified'
 usage = '[initial text to send ...]'
 
 

kittens/clipboard/main.py

@@ -57,7 +57,7 @@ OPTIONS = r'''
 default=False
 type=bool-set
 Output the current contents of the clipboard to STDOUT. Note that by default
-kitty will prompt you asking to allow access to the clipboard. Can be controlled
+kitty will prompt for permission to access the clipboard. Can be controlled
 by :opt:`clipboard_control`.
 
 
@@ -93,7 +93,10 @@ def main(args: List[str]) -> NoReturn:
     data: Optional[bytes] = None
     if not sys.stdin.isatty():
         data = sys.stdin.buffer.read()
-        sys.stdin = open(os.ctermid())
+        try:
+            sys.stdin = open(os.ctermid())
+        except FileNotFoundError:
+            raise SystemExit('Not connected to a controlling terminal device, no /dev/tty')
     loop = Loop()
     handler = Clipboard(data, cli_opts)
     loop.loop(handler)

kittens/diff/collect.py

@@ -4,10 +4,14 @@
 import os
 import re
 from contextlib import suppress
+from fnmatch import fnmatch
 from functools import lru_cache
 from hashlib import md5
+from typing import (
+    TYPE_CHECKING, Dict, Iterator, List, Optional, Sequence, Set, Tuple, Union
+)
+
 from kitty.guess_mime_type import guess_type
-from typing import TYPE_CHECKING, Dict, List, Set, Optional, Iterator, Tuple, Union
 
 if TYPE_CHECKING:
     from .highlight import DiffHighlight  # noqa
@@ -32,12 +36,13 @@ class Segment:
         self.end_code: Optional[str] = None
 
     def __repr__(self) -> str:
-        return 'Segment(start={!r}, start_code={!r}, end={!r}, end_code={!r})'.format(
-            self.start, self.start_code, self.end, self.end_code)
+        return f'Segment(start={self.start!r}, start_code={self.start_code!r}, end={self.end!r}, end_code={self.end_code!r})'
 
 
 class Collection:
 
+    ignore_names: Tuple[str, ...] = ()
+
     def __init__(self) -> None:
         self.changes: Dict[str, str] = {}
         self.renames: Dict[str, str] = {}
@@ -102,26 +107,38 @@ def remote_hostname(path: str) -> Tuple[Optional[str], Optional[str]]:
 def resolve_remote_name(path: str, default: str) -> str:
     remote_dir, rh = remote_hostname(path)
     if remote_dir and rh:
-        return rh + ':' + os.path.relpath(path, remote_dir)
+        return f'{rh}:{os.path.relpath(path, remote_dir)}'
     return default
 
 
+def allowed_items(items: Sequence[str], ignore_patterns: Sequence[str]) -> Iterator[str]:
+    for name in items:
+        for pat in ignore_patterns:
+            if fnmatch(name, pat):
+                break
+        else:
+            yield name
+
+
+def walk(base: str, names: Set[str], pmap: Dict[str, str], ignore_names: Tuple[str, ...]) -> None:
+    for dirpath, dirnames, filenames in os.walk(base):
+        dirnames[:] = allowed_items(dirnames, ignore_names)
+        for filename in allowed_items(filenames, ignore_names):
+            path = os.path.abspath(os.path.join(dirpath, filename))
+            path_name_map[path] = name = os.path.relpath(path, base)
+            names.add(name)
+            pmap[name] = path
+
+
 def collect_files(collection: Collection, left: str, right: str) -> None:
     left_names: Set[str] = set()
     right_names: Set[str] = set()
     left_path_map: Dict[str, str] = {}
     right_path_map: Dict[str, str] = {}
 
-    def walk(base: str, names: Set[str], pmap: Dict[str, str]) -> None:
-        for dirpath, dirnames, filenames in os.walk(base):
-            for filename in filenames:
-                path = os.path.abspath(os.path.join(dirpath, filename))
-                path_name_map[path] = name = os.path.relpath(path, base)
-                names.add(name)
-                pmap[name] = path
+    walk(left, left_names, left_path_map, collection.ignore_names)
+    walk(right, right_names, right_path_map, collection.ignore_names)
 
-    walk(left, left_names, left_path_map)
-    walk(right, right_names, right_path_map)
     common_names = left_names & right_names
     changed_names = {n for n in common_names if data_for_path(left_path_map[n]) != data_for_path(right_path_map[n])}
     for n in changed_names:

kittens/diff/highlight.py

@@ -4,7 +4,10 @@
 import concurrent
 import os
 import re
-from typing import IO, Dict, Iterable, List, Optional, Tuple, Union, cast
+from concurrent.futures import ProcessPoolExecutor
+from typing import (
+    IO, Dict, Iterable, Iterator, List, Optional, Tuple, Union, cast
+)
 
 from pygments import highlight  # type: ignore
 from pygments.formatter import Formatter  # type: ignore
@@ -94,7 +97,7 @@ def highlight_data(code: str, filename: str, aliases: Optional[Dict[str, str]] =
         base, ext = os.path.splitext(filename)
         alias = aliases.get(ext[1:])
         if alias is not None:
-            filename = base + '.' + alias
+            filename = f'{base}.{alias}'
     try:
         lexer = get_lexer_for_filename(filename, stripnl=False)
     except ClassNotFound:
@@ -136,31 +139,46 @@ def highlight_for_diff(path: str, aliases: Dict[str, str]) -> DiffHighlight:
     return ans
 
 
+process_pool_executor: Optional[ProcessPoolExecutor] = None
+
+
+def get_highlight_processes() -> Iterator[int]:
+    if process_pool_executor is None:
+        return
+    for pid in process_pool_executor._processes:
+        yield pid
+
+
 def highlight_collection(collection: Collection, aliases: Optional[Dict[str, str]] = None) -> Union[str, Dict[str, DiffHighlight]]:
+    global process_pool_executor
     jobs = {}
     ans: Dict[str, DiffHighlight] = {}
     with get_process_pool_executor(prefer_fork=True) as executor:
+        process_pool_executor = executor
         for path, item_type, other_path in collection:
             if item_type != 'rename':
                 for p in (path, other_path):
                     if p:
                         is_binary = isinstance(data_for_path(p), bytes)
                         if not is_binary:
-                            jobs[executor.submit(highlight_for_diff, p, aliases)] = p
+                            jobs[executor.submit(highlight_for_diff, p, aliases or {})] = p
         for future in concurrent.futures.as_completed(jobs):
             path = jobs[future]
             try:
                 highlights = future.result()
             except Exception as e:
-                return f'Running syntax highlighting for {path} generated an exception: {e}'
+                import traceback
+                tb = traceback.format_exc()
+                return f'Running syntax highlighting for {path} generated an exception: {e} with traceback:\n{tb}'
             ans[path] = highlights
     return ans
 
 
 def main() -> None:
     # kitty +runpy "from kittens.diff.highlight import main; main()" file
-    from .options.types import defaults
     import sys
+
+    from .options.types import defaults
     initialize_highlighter()
     with open(sys.argv[-1]) as f:
         highlighted = highlight_data(f.read(), f.name, defaults.syntax_aliases)

kittens/diff/main.py

@@ -10,10 +10,11 @@ import tempfile
 import warnings
 from collections import defaultdict
 from contextlib import suppress
+from enum import Enum, auto
 from functools import partial
 from gettext import gettext as _
 from typing import (
-    Any, DefaultDict, Dict, Iterable, List, Optional, Tuple, Union
+    Any, DefaultDict, Dict, Iterable, Iterator, List, Optional, Tuple, Union
 )
 
 from kitty.cli import CONFIG_HELP, parse_args
@@ -44,7 +45,8 @@ from .search import BadRegex, Search
 
 try:
     from .highlight import (
-        DiffHighlight, highlight_collection, initialize_highlighter
+        DiffHighlight, get_highlight_processes, highlight_collection,
+        initialize_highlighter
     )
     has_highlighter = True
     DiffHighlight
@@ -54,8 +56,24 @@ except ImportError:
     def highlight_collection(collection: 'Collection', aliases: Optional[Dict[str, str]] = None) -> Union[str, Dict[str, 'DiffHighlight']]:
         return ''
 
+    def get_highlight_processes() -> Iterator[int]:
+        if has_highlighter:
+            yield -1
 
-INITIALIZING, COLLECTED, DIFFED, COMMAND, MESSAGE = range(5)
+
+class State(Enum):
+    initializing = auto()
+    collected = auto()
+    diffed = auto()
+    command = auto()
+    message = auto()
+
+
+class BackgroundWork(Enum):
+    none = auto()
+    collecting = auto()
+    diffing = auto()
+    highlighting = auto()
 
 
 def generate_diff(collection: Collection, context: int) -> Union[str, Dict[str, Patch]]:
@@ -76,7 +94,7 @@ class DiffHandler(Handler):
     image_manager_class = ImageManager
 
     def __init__(self, args: DiffCLIOptions, opts: DiffOptions, left: str, right: str) -> None:
-        self.state = INITIALIZING
+        self.state = State.initializing
         self.message = ''
         self.current_search_is_regex = True
         self.current_search: Optional[Search] = None
@@ -90,16 +108,20 @@ class DiffHandler(Handler):
         if self.current_context_count < 0:
             self.current_context_count = self.original_context_count = self.opts.num_context_lines
         self.highlighting_done = False
+        self.doing_background_work = BackgroundWork.none
         self.restore_position: Optional[Reference] = None
         for key_def, action in self.opts.key_definitions.items():
             self.add_shortcut(action, key_def)
 
+    def terminate(self, return_code: int = 0) -> None:
+        self.quit_loop(return_code)
+
     def perform_action(self, action: KeyAction) -> None:
         func, args = action
         if func == 'quit':
-            self.quit_loop(0)
+            self.terminate()
             return
-        if self.state <= DIFFED:
+        if self.state.value <= State.diffed.value:
             if func == 'scroll_by':
                 return self.scroll_lines(int(args[0] or 0))
             if func == 'scroll_to':
@@ -130,8 +152,9 @@ class DiffHandler(Handler):
     def create_collection(self) -> None:
 
         def collect_done(collection: Collection) -> None:
+            self.doing_background_work = BackgroundWork.none
             self.collection = collection
-            self.state = COLLECTED
+            self.state = State.collected
             self.generate_diff()
 
         def collect(left: str, right: str) -> None:
@@ -139,15 +162,17 @@ class DiffHandler(Handler):
             self.asyncio_loop.call_soon_threadsafe(collect_done, collection)
 
         self.asyncio_loop.run_in_executor(None, collect, self.left, self.right)
+        self.doing_background_work = BackgroundWork.collecting
 
     def generate_diff(self) -> None:
 
         def diff_done(diff_map: Union[str, Dict[str, Patch]]) -> None:
+            self.doing_background_work = BackgroundWork.none
             if isinstance(diff_map, str):
                 self.report_traceback_on_exit = diff_map
-                self.quit_loop(1)
+                self.terminate(1)
                 return
-            self.state = DIFFED
+            self.state = State.diffed
             self.diff_map = diff_map
             self.calculate_statistics()
             self.render_diff()
@@ -163,7 +188,7 @@ class DiffHandler(Handler):
                     initialize_highlighter(self.opts.pygments_style)
                 except StyleNotFound as e:
                     self.report_traceback_on_exit = str(e)
-                    self.quit_loop(1)
+                    self.terminate(1)
                     return
                 self.syntax_highlight()
 
@@ -172,13 +197,15 @@ class DiffHandler(Handler):
             self.asyncio_loop.call_soon_threadsafe(diff_done, diff_map)
 
         self.asyncio_loop.run_in_executor(None, diff, self.collection, self.current_context_count)
+        self.doing_background_work = BackgroundWork.diffing
 
     def syntax_highlight(self) -> None:
 
         def highlighting_done(hdata: Union[str, Dict[str, 'DiffHighlight']]) -> None:
+            self.doing_background_work = BackgroundWork.none
             if isinstance(hdata, str):
                 self.report_traceback_on_exit = hdata
-                self.quit_loop(1)
+                self.terminate(1)
                 return
             set_highlight_data(hdata)
             self.render_diff()
@@ -189,6 +216,7 @@ class DiffHandler(Handler):
             self.asyncio_loop.call_soon_threadsafe(highlighting_done, result)
 
         self.asyncio_loop.run_in_executor(None, highlight, self.collection, self.opts.syntax_aliases)
+        self.doing_background_work = BackgroundWork.highlighting
 
     def calculate_statistics(self) -> None:
         self.added_count = self.collection.added_count
@@ -265,10 +293,11 @@ class DiffHandler(Handler):
 
     def scroll_lines(self, amt: int = 1) -> None:
         new_pos = max(0, min(self.scroll_pos + amt, self.max_scroll_pos))
+        amt = new_pos - self.scroll_pos
         if new_pos == self.scroll_pos:
             self.cmd.bell()
             return
-        if abs(new_pos - self.scroll_pos) >= self.num_lines - 1:
+        if abs(amt) >= self.num_lines - 1:
             self.scroll_pos = new_pos
             self.draw_screen()
             return
@@ -304,7 +333,7 @@ class DiffHandler(Handler):
         self.create_collection()
 
     def enforce_cursor_state(self) -> None:
-        self.cmd.set_cursor_visible(self.state == COMMAND)
+        self.cmd.set_cursor_visible(self.state is State.command)
 
     def draw_lines(self, num: int, offset: int = 0) -> None:
         offset += self.scroll_pos
@@ -319,7 +348,7 @@ class DiffHandler(Handler):
                 text = line.text
                 if line.image_data is not None:
                     image_involved = True
-            self.write('\r\x1b[K' + text + '\x1b[0m')
+            self.write(f'\r\x1b[K{text}\x1b[0m')
             if self.current_search is not None:
                 self.current_search.highlight_line(self.write, lpos)
             if i < num - 1:
@@ -407,7 +436,7 @@ class DiffHandler(Handler):
 
     def draw_screen(self) -> None:
         self.enforce_cursor_state()
-        if self.state < DIFFED:
+        if self.state.value < State.diffed.value:
             self.cmd.clear_screen()
             self.write(_('Calculating diff, please wait...'))
             return
@@ -417,14 +446,14 @@ class DiffHandler(Handler):
         self.draw_status_line()
 
     def draw_status_line(self) -> None:
-        if self.state < DIFFED:
+        if self.state.value < State.diffed.value:
             return
         self.enforce_cursor_state()
         self.cmd.set_cursor_position(0, self.num_lines)
         self.cmd.clear_to_eol()
-        if self.state is COMMAND:
+        if self.state is State.command:
             self.line_edit.write(self.write)
-        elif self.state is MESSAGE:
+        elif self.state is State.message:
             self.cmd.styled(self.message, reverse=True)
         else:
             sp = f'{self.scroll_pos/self.max_scroll_pos:.0%}' if self.scroll_pos and self.max_scroll_pos else '0%'
@@ -437,7 +466,7 @@ class DiffHandler(Handler):
                 )
             else:
                 counts = styled(f'{len(self.current_search)} matches', fg=self.opts.margin_fg)
-            suffix = counts + '  ' + scroll_frac
+            suffix = f'{counts}  {scroll_frac}'
             prefix = styled(':', fg=self.opts.margin_fg)
             filler = self.screen_size.cols - wcswidth(prefix) - wcswidth(suffix)
             text = '{}{}{}'.format(prefix, ' ' * filler, suffix)
@@ -447,16 +476,16 @@ class DiffHandler(Handler):
         new_ctx = max(0, new_ctx)
         if new_ctx != self.current_context_count:
             self.current_context_count = new_ctx
-            self.state = COLLECTED
+            self.state = State.collected
             self.generate_diff()
             self.restore_position = self.current_position
             self.draw_screen()
 
     def start_search(self, is_regex: bool, is_backward: bool) -> None:
-        if self.state != DIFFED:
+        if self.state is not State.diffed:
             self.cmd.bell()
             return
-        self.state = COMMAND
+        self.state = State.command
         self.line_edit.clear()
         self.line_edit.add_text('?' if is_backward else '/')
         self.current_search_is_regex = is_regex
@@ -470,50 +499,50 @@ class DiffHandler(Handler):
         try:
             self.current_search = Search(self.opts, query[1:], self.current_search_is_regex, query[0] == '?')
         except BadRegex:
-            self.state = MESSAGE
+            self.state = State.message
             self.message = sanitize(_('Bad regex: {}').format(query[1:]))
             self.cmd.bell()
         else:
             if self.current_search(self.diff_lines, self.margin_size, self.screen_size.cols):
                 self.scroll_to_next_match(include_current=True)
             else:
-                self.state = MESSAGE
+                self.state = State.message
                 self.message = sanitize(_('No matches found'))
                 self.cmd.bell()
 
     def on_key_event(self, key_event: KeyEvent, in_bracketed_paste: bool = False) -> None:
         if key_event.text:
-            if self.state is COMMAND:
+            if self.state is State.command:
                 self.line_edit.on_text(key_event.text, in_bracketed_paste)
                 self.draw_status_line()
                 return
-            if self.state is MESSAGE:
-                self.state = DIFFED
+            if self.state is State.message:
+                self.state = State.diffed
                 self.draw_status_line()
                 return
         else:
-            if self.state is MESSAGE:
+            if self.state is State.message:
                 if key_event.type is not EventType.RELEASE:
-                    self.state = DIFFED
+                    self.state = State.diffed
                     self.draw_status_line()
                 return
-            if self.state is COMMAND:
+            if self.state is State.command:
                 if self.line_edit.on_key(key_event):
                     if not self.line_edit.current_input:
-                        self.state = DIFFED
+                        self.state = State.diffed
                     self.draw_status_line()
                     return
                 if key_event.matches('enter'):
-                    self.state = DIFFED
+                    self.state = State.diffed
                     self.do_search()
                     self.line_edit.clear()
                     self.draw_screen()
                     return
                 if key_event.matches('esc'):
-                    self.state = DIFFED
+                    self.state = State.diffed
                     self.draw_status_line()
                     return
-            if self.state >= DIFFED and self.current_search is not None and key_event.matches('esc'):
+            if self.state.value >= State.diffed.value and self.current_search is not None and key_event.matches('esc'):
                 self.current_search = None
                 self.draw_screen()
                 return
@@ -526,24 +555,24 @@ class DiffHandler(Handler):
     def on_resize(self, screen_size: ScreenSize) -> None:
         self.screen_size = screen_size
         self.set_scrolling_region()
-        if self.state > COLLECTED:
+        if self.state.value > State.collected.value:
             self.image_manager.delete_all_sent_images()
             self.render_diff()
         self.draw_screen()
 
     def on_interrupt(self) -> None:
-        self.quit_loop(1)
+        self.terminate(1)
 
     def on_eot(self) -> None:
-        self.quit_loop(1)
+        self.terminate(1)
 
 
 OPTIONS = partial('''\
 --context
 type=int
 default=-1
-Number of lines of context to show between changes. Negative values
-use the number set in diff.conf
+Number of lines of context to show between changes. Negative values use the
+number set in :file:`diff.conf`.
 
 
 --config
@@ -570,7 +599,7 @@ class ShowWarning:
 
 
 showwarning = ShowWarning()
-help_text = 'Show a side-by-side diff of the specified files/directories. You can also use ssh:hostname:remote-file-path to diff remote files.'
+help_text = 'Show a side-by-side diff of the specified files/directories. You can also use :italic:`ssh:hostname:remote-file-path` to diff remote files.'
 usage = 'file_or_directory_left file_or_directory_right'
 
 
@@ -626,6 +655,7 @@ def main(args: List[str]) -> None:
     opts = init_config(cli_opts)
     set_diff_command(opts.diff_cmd)
     lines_for_path.replace_tab_by = opts.replace_tab_by
+    Collection.ignore_names = tuple(opts.ignore_name)
     left, right = map(get_remote_file, (left, right))
     if os.path.isdir(left) != os.path.isdir(right):
         raise SystemExit('The items to be diffed should both be either directories or files. Comparing a directory to a file is not valid.')
@@ -639,9 +669,10 @@ def main(args: List[str]) -> None:
     for message in showwarning.warnings:
         from kitty.utils import safe_print
         safe_print(message, file=sys.stderr)
-    highlight_processes = getattr(highlight_collection, 'processes', ())
-    terminate_processes(tuple(highlight_processes))
-    terminate_processes(tuple(worker_processes))
+    if handler.doing_background_work is BackgroundWork.highlighting:
+        terminate_processes(tuple(get_highlight_processes()))
+    elif handler.doing_background_work == BackgroundWork.diffing:
+        terminate_processes(tuple(worker_processes))
     if loop.return_code != 0:
         if handler.report_traceback_on_exit:
             print(handler.report_traceback_on_exit, file=sys.stderr)

kittens/diff/options/definition.py

@@ -24,8 +24,8 @@ agr('diff', 'Diffing')
 opt('syntax_aliases', 'pyj:py pyi:py recipe:py',
     option_type='syntax_aliases',
     long_text='''
-File extension aliases for syntax highlight For example, to syntax highlight
-:file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc`
+File extension aliases for syntax highlight. For example, to syntax highlight
+:file:`file.xyz` as :file:`file.abc` use a setting of :code:`xyz:abc`.
 '''
     )
 
@@ -37,8 +37,9 @@ opt('num_context_lines', '3',
 opt('diff_cmd', 'auto',
     long_text='''
 The diff command to use. Must contain the placeholder :code:`_CONTEXT_` which
-will be replaced by the number of lines of context. The default is to search the
-system for either git or diff and use that, if found.
+will be replaced by the number of lines of context. The default special value
+:code:`auto` is to search the system for either :program:`git` or
+:program:`diff` and use that, if found.
 '''
     )
 
@@ -46,6 +47,21 @@ opt('replace_tab_by', '\\x20\\x20\\x20\\x20',
     option_type='python_string',
     long_text='The string to replace tabs with. Default is to use four spaces.'
     )
+
+opt('+ignore_name', '',
+    option_type='store_multiple',
+    add_to_default=False,
+    long_text='''
+A glob pattern that is matched against only the filename of files and directories. Matching
+files and directories are ignored when scanning the filesystem to look for files to diff.
+Can be specified multiple times to use multiple patterns. For example::
+
+   ignore_name .git
+   ignore_name *~
+   ignore_name *.pyc
+''',
+    )
+
 egr()  # }}}
 
 # colors {{{

kittens/diff/options/parse.py

@@ -1,7 +1,7 @@
 # generated by gen-config.py DO NOT edit
 
 import typing
-from kittens.diff.options.utils import parse_map, syntax_aliases
+from kittens.diff.options.utils import parse_map, store_multiple, syntax_aliases
 from kitty.conf.utils import merge_dicts, positive_int, python_string, to_color, to_color_or_none
 
 
@@ -37,6 +37,10 @@ class Parser:
     def hunk_margin_bg(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['hunk_margin_bg'] = to_color(val)
 
+    def ignore_name(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
+        for k, v in store_multiple(val, ans["ignore_name"]):
+            ans["ignore_name"][k] = v
+
     def margin_bg(self, val: str, ans: typing.Dict[str, typing.Any]) -> None:
         ans['margin_bg'] = to_color(val)
 
@@ -89,11 +93,12 @@ class Parser:
 
 def create_result_dict() -> typing.Dict[str, typing.Any]:
     return {
+        'ignore_name': {},
         'map': [],
     }
 
 
-actions = frozenset(('map',))
+actions: typing.FrozenSet[str] = frozenset(('map',))
 
 
 def merge_result_dicts(defaults: typing.Dict[str, typing.Any], vals: typing.Dict[str, typing.Any]) -> typing.Dict[str, typing.Any]:

kittens/diff/options/types.py

@@ -20,6 +20,7 @@ option_names = (  # {{{
  'highlight_removed_bg',
  'hunk_bg',
  'hunk_margin_bg',
+ 'ignore_name',
  'map',
  'margin_bg',
  'margin_fg',
@@ -64,6 +65,7 @@ class Options:
     syntax_aliases: typing.Dict[str, str] = {'pyj': 'py', 'pyi': 'py', 'recipe': 'py'}
     title_bg: Color = Color(255, 255, 255)
     title_fg: Color = Color(0, 0, 0)
+    ignore_name: typing.Dict[str, str] = {}
     map: typing.List[typing.Tuple[kitty.types.ParsedShortcut, kitty.conf.utils.KeyAction]] = []
     key_definitions: KittensKeyMap = {}
     config_paths: typing.Tuple[str, ...] = ()
@@ -116,6 +118,7 @@ class Options:
 
 
 defaults = Options()
+defaults.ignore_name = {}
 defaults.map = [
     # quit
     (ParsedShortcut(mods=0, key_name='q'), KeyAction('quit')),  # noqa

kittens/diff/options/utils.py

@@ -3,7 +3,7 @@
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 
-from typing import Any, Dict, Iterable, Tuple, Union
+from typing import Any, Container, Dict, Iterable, Tuple, Union
 
 from kitty.conf.utils import (
     KeyFuncWrapper, KittensKeyDefinition, parse_kittens_key
@@ -58,6 +58,12 @@ def syntax_aliases(raw: str) -> Dict[str, str]:
     return ans
 
 
+def store_multiple(val: str, current_val: Container[str]) -> Iterable[Tuple[str, str]]:
+    val = val.strip()
+    if val not in current_val:
+        yield val, val
+
+
 def parse_map(val: str) -> Iterable[KittensKeyDefinition]:
     x = parse_kittens_key(val, func_with_args.args_funcs)
     if x is not None:

kittens/diff/patch.py

@@ -153,7 +153,7 @@ class Hunk:
         if c.left_start + c.left_count != self.left_start + self.left_count:
             raise ValueError(f'Left side line mismatch {c.left_start + c.left_count} != {self.left_start + self.left_count}')
         if c.right_start + c.right_count != self.right_start + self.right_count:
-            raise ValueError(f'Left side line mismatch {c.right_start + c.right_count} != {self.right_start + self.right_count}')
+            raise ValueError(f'Right side line mismatch {c.right_start + c.right_count} != {self.right_start + self.right_count}')
         for c in self.chunks:
             c.finalize()
 
@@ -200,7 +200,7 @@ def parse_patch(raw: str) -> Patch:
         else:
             if current_hunk is None:
                 continue
-            q = line[0]
+            q = line[0] if line else ''
             if q == '+':
                 current_hunk.add_line()
             elif q == '-':
@@ -244,14 +244,14 @@ class Differ:
             except Exception as e:
                 return f'Running git diff for {left_path} vs. {right_path} generated an exception: {e}'
             if not ok:
-                return output + f'\nRunning git diff for {left_path} vs. {right_path} failed'
+                return f'{output}\nRunning git diff for {left_path} vs. {right_path} failed'
             left_lines = lines_for_path(left_path)
             right_lines = lines_for_path(right_path)
             try:
                 patch = parse_patch(output)
             except Exception:
                 import traceback
-                return traceback.format_exc() + f'\nParsing diff for {left_path} vs. {right_path} failed'
+                return f'{traceback.format_exc()}\nParsing diff for {left_path} vs. {right_path} failed'
             else:
                 ans[key] = patch
         return ans

kittens/diff/render.py

@@ -36,6 +36,8 @@ def images_supported() -> bool:
 
 class Ref:
 
+    __slots__: Tuple[str, ...] = ()
+
     def __setattr__(self, name: str, value: object) -> None:
         raise AttributeError("can't set attribute")
 
@@ -101,7 +103,7 @@ def human_readable(size: int, sep: str = ' ') -> str:
         s = s[:s.find(".")+2]
     if s.endswith('.0'):
         s = s[:-2]
-    return s + sep + suffix
+    return f'{s}{sep}{suffix}'
 
 
 def fit_in(text: str, count: int) -> str:
@@ -110,7 +112,7 @@ def fit_in(text: str, count: int) -> str:
         return text
     if count > 1:
         p = truncate_point_for_length(text, count - 1)
-    return text[:p] + '…'
+    return f'{text[:p]}…'
 
 
 def fill_in(text: str, sz: int) -> str:
@@ -127,8 +129,8 @@ def place_in(text: str, sz: int) -> str:
 def format_func(which: str) -> Callable[[str], str]:
     def formatted(text: str) -> str:
         fmt = formats[which]
-        return '\x1b[' + fmt + 'm' + text + '\x1b[0m'
-    formatted.__name__ = which + '_format'
+        return f'\x1b[{fmt}m{text}\x1b[0m'
+    formatted.__name__ = f'{which}_format'
     return formatted
 
 
@@ -148,8 +150,8 @@ highlight_map = {'remove': ('removed_highlight', 'removed'), 'add': ('added_high
 
 def highlight_boundaries(ltype: str) -> Tuple[str, str]:
     s, e = highlight_map[ltype]
-    start = '\x1b[' + formats[s] + 'm'
-    stop = '\x1b[' + formats[e] + 'm'
+    start = f'\x1b[{formats[s]}m'
+    stop = f'\x1b[{formats[e]}m'
     return start, stop
 
 

kittens/hints/main.py

@@ -9,8 +9,8 @@ from functools import lru_cache
 from gettext import gettext as _
 from itertools import repeat
 from typing import (
-    Any, Callable, Dict, Generator, Iterable, List, Optional, Pattern,
-    Sequence, Set, Tuple, Type, cast
+    Any, Callable, Dict, Generator, Iterable, Iterator, List, Optional,
+    Pattern, Sequence, Set, Tuple, Type, cast
 )
 
 from kitty.cli import parse_args
@@ -20,12 +20,14 @@ from kitty.fast_data_types import get_options, set_clipboard_string
 from kitty.key_encoding import KeyEvent
 from kitty.typing import BossType, KittyCommonOpts
 from kitty.utils import (
-    ScreenSize, resolve_custom_file, screen_size_function, set_primary_selection
+    ScreenSize, kitty_ansi_sanitizer_pat, resolve_custom_file,
+    screen_size_function, set_primary_selection
 )
 
 from ..tui.handler import Handler, result_handler
 from ..tui.loop import Loop
 from ..tui.operations import faint, styled
+from ..tui.utils import report_error, report_unhandled_error
 
 
 @lru_cache()
@@ -40,6 +42,9 @@ def kitty_common_opts() -> KittyCommonOpts:
 
 DEFAULT_HINT_ALPHABET = string.digits + string.ascii_lowercase
 DEFAULT_REGEX = r'(?m)^\s*(.+)\s*$'
+FILE_EXTENSION = r'\.(?:[a-zA-Z0-9]{2,7}|[ahcmo])(?!\.)'
+PATH_REGEX = fr'(?:\S*?/[\r\S]+)|(?:\S[\r\S]*{FILE_EXTENSION})\b'
+DEFAULT_LINENUM_REGEX = fr'(?P<path>{PATH_REGEX}):(?P<line>\d+)'
 
 
 class Mark:
@@ -60,6 +65,10 @@ class Mark:
         self.is_hyperlink = is_hyperlink
         self.group_id = group_id
 
+    def __repr__(self) -> str:
+        return (f'Mark(index={self.index!r}, start={self.start!r}, end={self.end!r},'
+                f' text={self.text!r}, groupdict={self.groupdict!r}, is_hyperlink={self.is_hyperlink!r}, group_id={self.group_id!r})')
+
 
 @lru_cache(maxsize=2048)
 def encode_hint(num: int, alphabet: str) -> str:
@@ -114,6 +123,9 @@ def render(text: str, current_input: str, all_marks: Sequence[Mark], ignore_mark
 
 class Hints(Handler):
 
+    use_alternate_screen = False  # disabled to avoid screen being blanked at exit causing flicker
+    overlay_ready_report_needed = True
+
     def __init__(self, text: str, all_marks: Sequence[Mark], index_map: Dict[int, Mark], args: HintsCLIOptions):
         self.text, self.index_map = text, index_map
         self.alphabet = args.alphabet or DEFAULT_HINT_ALPHABET
@@ -184,7 +196,7 @@ class Hints(Handler):
             self.current_input = self.current_input[:-1]
             self.current_text = None
             self.draw_screen()
-        elif key_event.matches('enter') and self.current_input:
+        elif (key_event.matches('enter') or key_event.matches('space')) and self.current_input:
             try:
                 idx = decode_hint(self.current_input, self.alphabet)
                 self.chosen.append(self.index_map[idx])
@@ -218,17 +230,17 @@ class Hints(Handler):
         self.write(self.current_text)
 
 
-def regex_finditer(pat: 'Pattern[str]', minimum_match_length: int, text: str) -> Generator[Tuple[int, int, Dict[str, str]], None, None]:
+def regex_finditer(pat: 'Pattern[str]', minimum_match_length: int, text: str) -> Iterator[Tuple[int, int, 're.Match[str]']]:
     has_named_groups = bool(pat.groupindex)
     for m in pat.finditer(text):
         s, e = m.span(0 if has_named_groups else pat.groups)
         while e > s + 1 and text[e-1] == '\0':
             e -= 1
         if e - s >= minimum_match_length:
-            yield s, e, m.groupdict()
+            yield s, e, m
 
 
-closing_bracket_map = {'(': ')', '[': ']', '{': '}', '<': '>', '*': '*', '"': '"', "'": "'"}
+closing_bracket_map = {'(': ')', '[': ']', '{': '}', '<': '>', '*': '*', '"': '"', "'": "'", "“": "”", "‘": "’"}
 opening_brackets = ''.join(closing_bracket_map)
 PostprocessorFunc = Callable[[str, int, int], Tuple[int, int]]
 postprocessor_map: Dict[str, PostprocessorFunc] = {}
@@ -271,9 +283,13 @@ def brackets(text: str, s: int, e: int) -> Tuple[int, int]:
     # Remove matching brackets
     if s < e <= len(text):
         before = text[s]
-        if before in '({[<' and text[e-1] == closing_bracket_map[before]:
-            s += 1
-            e -= 1
+        if before in '({[<':
+            q = closing_bracket_map[before]
+            if text[e-1] == q:
+                s += 1
+                e -= 1
+            elif text[e:e+1] == q:
+                s += 1
     return s, e
 
 
@@ -282,9 +298,13 @@ def quotes(text: str, s: int, e: int) -> Tuple[int, int]:
     # Remove matching quotes
     if s < e <= len(text):
         before = text[s]
-        if before in '\'"' and text[e-1] == before:
-            s += 1
-            e -= 1
+        if before in '\'"“‘':
+            q = closing_bracket_map[before]
+            if text[e-1] == q:
+                s += 1
+                e -= 1
+            elif text[e:e+1] == q:
+                s += 1
     return s, e
 
 
@@ -303,16 +323,22 @@ def ip(text: str, s: int, e: int) -> Tuple[int, int]:
     return s, e
 
 
-def mark(pattern: str, post_processors: Iterable[PostprocessorFunc], text: str, args: HintsCLIOptions) -> Generator[Mark, None, None]:
+def mark(pattern: str, post_processors: Iterable[PostprocessorFunc], text: str, args: HintsCLIOptions) -> Iterator[Mark]:
     pat = re.compile(pattern)
-    for idx, (s, e, groupdict) in enumerate(regex_finditer(pat, args.minimum_match_length, text)):
+    sanitize_pat = re.compile('[\r\n\0]')
+    for idx, (s, e, match_object) in enumerate(regex_finditer(pat, args.minimum_match_length, text)):
         try:
             for func in post_processors:
                 s, e = func(text, s, e)
         except InvalidMatch:
             continue
-
-        mark_text = re.sub('[\r\n\0]', '', text[s:e])
+        groupdict = match_object.groupdict()
+        for group_name in groupdict:
+            group_idx = pat.groupindex[group_name]
+            gs, ge = match_object.span(group_idx)
+            gs, ge = max(gs, s), min(ge, e)
+            groupdict[group_name] = sanitize_pat.sub('', text[gs:ge])
+        mark_text = sanitize_pat.sub('', text[s:e])
         yield Mark(idx, s, e, mark_text, groupdict)
 
 
@@ -348,7 +374,7 @@ def functions_for(args: HintsCLIOptions) -> Tuple[str, List[PostprocessorFunc]]:
         )
         post_processors.append(url)
     elif args.type == 'path':
-        pattern = r'(?:\S*?/[\r\S]+)|(?:\S[\r\S]*\.[a-zA-Z0-9\r]{2,7})'
+        pattern = PATH_REGEX
         post_processors.extend((brackets, quotes))
     elif args.type == 'line':
         pattern = '(?m)^\\s*(.+)[\\s\0]*$'
@@ -405,7 +431,7 @@ def parse_input(text: str) -> str:
 def linenum_marks(text: str, args: HintsCLIOptions, Mark: Type[Mark], extra_cli_args: Sequence[str], *a: Any) -> Generator[Mark, None, None]:
     regex = args.regex
     if regex == DEFAULT_REGEX:
-        regex = r'(?P<path>(?:\S*/\S+?)|(?:\S+[.][a-zA-Z0-9]{2,7})):(?P<line>\d+)'
+        regex = DEFAULT_LINENUM_REGEX
     yield from mark(regex, [brackets, quotes], text, args)
 
 
@@ -421,11 +447,7 @@ def load_custom_processor(customize_processing: str) -> Any:
     return runpy.run_path(custom_path, run_name='__main__')
 
 
-def remove_sgr(text: str) -> str:
-    return re.sub(r'\x1b\[.*?m', '', text)
-
-
-def process_hyperlinks(text: str) -> Tuple[str, Tuple[Mark, ...]]:
+def process_escape_codes(text: str) -> Tuple[str, Tuple[Mark, ...]]:
     hyperlinks: List[Mark] = []
     removed_size = idx = 0
     active_hyperlink_url: Optional[str] = None
@@ -448,6 +470,9 @@ def process_hyperlinks(text: str) -> Tuple[str, Tuple[Mark, ...]]:
     def process_hyperlink(m: 're.Match[str]') -> str:
         nonlocal removed_size, active_hyperlink_url, active_hyperlink_id, active_hyperlink_start_offset
         raw = m.group()
+        if not raw.startswith('\x1b]8'):
+            removed_size += len(raw)
+            return ''
         start = m.start() - removed_size
         removed_size += len(raw)
         if active_hyperlink_url is not None:
@@ -465,7 +490,7 @@ def process_hyperlinks(text: str) -> Tuple[str, Tuple[Mark, ...]]:
 
         return ''
 
-    text = re.sub(r'\x1b\]8.+?\x1b\\', process_hyperlink, text)
+    text = kitty_ansi_sanitizer_pat().sub(process_hyperlink, text)
     if active_hyperlink_url is not None:
         add_hyperlink(len(text))
     return text, tuple(hyperlinks)
@@ -473,8 +498,8 @@ def process_hyperlinks(text: str) -> Tuple[str, Tuple[Mark, ...]]:
 
 def run(args: HintsCLIOptions, text: str, extra_cli_args: Sequence[str] = ()) -> Optional[Dict[str, Any]]:
     try:
-        text = parse_input(remove_sgr(text))
-        text, hyperlinks = process_hyperlinks(text)
+        text = parse_input(text)
+        text, hyperlinks = process_escape_codes(text)
         pattern, post_processors = functions_for(args)
         if args.type == 'linenum':
             args.customize_processing = '::linenum::'
@@ -490,7 +515,7 @@ def run(args: HintsCLIOptions, text: str, extra_cli_args: Sequence[str] = ()) ->
             all_marks = tuple(mark(pattern, post_processors, text, args))
         if not all_marks:
             none_of = {'url': 'URLs', 'hyperlink': 'hyperlinks'}.get(args.type, 'matches')
-            input(_('No {} found, press Enter to quit.').format(none_of))
+            report_error(_('No {} found.').format(none_of))
             return None
 
         largest_index = all_marks[-1].index
@@ -502,11 +527,7 @@ def run(args: HintsCLIOptions, text: str, extra_cli_args: Sequence[str] = ()) ->
                 m.index = largest_index - m.index + offset
         index_map = {m.index: m for m in all_marks}
     except Exception:
-        import traceback
-        traceback.print_exc()
-        input('Press Enter to quit.')
-        raise SystemExit(1)
-
+        report_unhandled_error()
     return run_loop(args, text, all_marks, index_map, extra_cli_args)
 
 
@@ -515,10 +536,10 @@ OPTIONS = r'''
 --program
 type=list
 What program to use to open matched text. Defaults to the default open program
-for the operating system. Use a value of :file:`-` to paste the match into the
-terminal window instead. A value of :file:`@` will copy the match to the
-clipboard. A value of :file:`*` will copy the match to the primary selection
-(on systems that support primary selections). A value of :file:`default` will
+for the operating system. Use a value of :code:`-` to paste the match into the
+terminal window instead. A value of :code:`@` will copy the match to the
+clipboard. A value of :code:`*` will copy the match to the primary selection
+(on systems that support primary selections). A value of :code:`default` will
 run the default open program. Can be specified multiple times to run multiple
 programs.
 
@@ -528,22 +549,22 @@ default=url
 choices=url,regex,path,line,hash,word,linenum,hyperlink,ip
 The type of text to search for. A value of :code:`linenum` is special, it looks
 for error messages using the pattern specified with :option:`--regex`, which
-must have the named groups, :code:`path` and :code:`line`. If not specified,
+must have the named groups: :code:`path` and :code:`line`. If not specified,
 will look for :code:`path:line`. The :option:`--linenum-action` option
 controls where to display the selected error message, other options are ignored.
 
 
 --regex
 default={default_regex}
-The regular expression to use when :option:`kitty +kitten hints --type`=regex.
-The regular expression is in python syntax. If you specify a numbered group in
-the regular expression only the group will be matched. This allow you to match
-text ignoring a prefix/suffix, as needed. The default expression matches lines.
-To match text over multiple lines you should prefix the regular expression with
+The regular expression to use when option :option:`--type` is set to
+:code:`regex`, in python syntax. If you specify a numbered group in the regular
+expression, only the group will be matched. This allow you to match text
+ignoring a prefix/suffix, as needed. The default expression matches lines. To
+match text over multiple lines, you should prefix the regular expression with
 :code:`(?ms)`, which turns on MULTILINE and DOTALL modes for the regex engine.
-If you specify named groups and a :option:`kitty +kitten hints --program` then
-the program will be passed arguments corresponding to each named group of
-the form key=value.
+If you specify named groups and a :option:`--program`, then the program will be
+passed arguments corresponding to each named group of the form
+:code:`key=value`.
 
 
 --linenum-action
@@ -555,22 +576,22 @@ window, :code:`window` a new kitty window, :code:`tab` a new tab,
 :code:`os_window` a new OS window and :code:`background` run in the background.
 The actual action is whatever arguments are provided to the kitten, for
 example:
-:code:`kitty + kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
+:code:`kitty +kitten hints --type=linenum --linenum-action=tab vim +{line} {path}`
 will open the matched path at the matched line number in vim in
-a new kitty tab. Note that only when using :code:`self` are the special values for
-:option:`kitty +kitten hints --program` to copy/paste the text respected.
+a new kitty tab. Note that in order to use :option:`--program` to copy or paste
+text, you need to use the special value :code:`self`.
 
 
 --url-prefixes
 default=default
-Comma separated list of recognized URL prefixes. Defaults, to
-the list of prefixes defined in kitty.conf.
+Comma separated list of recognized URL prefixes. Defaults to the list of
+prefixes defined by the :opt:`url_prefixes` option in :file:`kitty.conf`.
 
 
 --word-characters
 Characters to consider as part of a word. In addition, all characters marked as
-alphanumeric in the unicode database will be considered as word characters.
-Defaults to the select_by_word_characters setting from kitty.conf.
+alphanumeric in the Unicode database will be considered as word characters.
+Defaults to the :opt:`select_by_word_characters` option from :file:`kitty.conf`.
 
 
 --minimum-match-length
@@ -581,26 +602,26 @@ The minimum number of characters to consider a match.
 
 --multiple
 type=bool-set
-Select multiple matches and perform the action on all of them together at the end.
-In this mode, press :kbd:`Esc` to finish selecting.
+Select multiple matches and perform the action on all of them together at the
+end. In this mode, press :kbd:`Esc` to finish selecting.
 
 
 --multiple-joiner
 default=auto
-String to use to join multiple selections when copying to the clipboard or
-inserting into the terminal. The special strings: "space", "newline", "empty",
-"json" and "auto" are interpreted as a space character, a newline an empty
-joiner, a JSON serialized list and an automatic choice, based on the type of
-text being selected. In addition, integers are interpreted as zero-based
-indices into the list of selections. You can use 0 for the first selection and
--1 for the last.
+String for joining multiple selections when copying to the clipboard or
+inserting into the terminal. The special values are: :code:`space` - a space
+character, :code:`newline` - a newline, :code:`empty` - an empty joiner,
+:code:`json` - a JSON serialized list, :code:`auto` - an automatic choice, based
+on the type of text being selected. In addition, integers are interpreted as
+zero-based indices into the list of selections. You can use :code:`0` for the
+first selection and :code:`-1` for the last.
 
 
 --add-trailing-space
 default=auto
 choices=auto,always,never
-Add trailing space after matched text. Defaults to auto, which adds the space
-when used together with :option:`--multiple`.
+Add trailing space after matched text. Defaults to :code:`auto`, which adds the
+space when used together with :option:`--multiple`.
 
 
 --hints-offset
@@ -611,45 +632,47 @@ greater than or equal to zero are respected.
 
 
 --alphabet
-The list of characters to use for hints. The default is to use numbers and lowercase
-English alphabets. Specify your preference as a string of characters. Note that
-unless you specify the hints offset as zero the first match will be highlighted with
-the second character you specify.
+The list of characters to use for hints. The default is to use numbers and
+lowercase English alphabets. Specify your preference as a string of characters.
+Note that you need to specify the :option:`--hints-offset` as zero to use the
+first character to highlight the first match, otherwise it will start with the
+second character by default.
 
 
 --ascending
 type=bool-set
-Have the hints increase from top to bottom instead of decreasing from top to bottom.
+Make the hints increase from top to bottom, instead of decreasing from top to
+bottom.
 
 
 --hints-foreground-color
 default=black
 type=str
-The foreground color for hints
+The foreground color for hints.
 
 
 --hints-background-color
 default=green
 type=str
-The background color for hints
+The background color for hints.
 
 
 --hints-text-color
 default=gray
 type=str
-The foreground color for text pointed to by the hints
+The foreground color for text pointed to by the hints.
 
 
 --customize-processing
-Name of a python file in the kitty config directory which will be imported to provide
-custom implementations for pattern finding and performing actions
-on selected matches. See {hints_url}
-for details. You can also specify absolute paths to load the script from elsewhere.
+Name of a python file in the kitty config directory which will be imported to
+provide custom implementations for pattern finding and performing actions
+on selected matches. You can also specify absolute paths to load the script from
+elsewhere. See {hints_url} for details.
 
 
 --window-title
-The window title for the hints window, default title is selected based on
-the type of text being hinted.
+The title for the hints window, default title is based on the type of text being
+hinted.
 '''.format(
     default_regex=DEFAULT_REGEX,
     line='{{line}}', path='{{path}}',
@@ -667,9 +690,7 @@ def main(args: List[str]) -> Optional[Dict[str, Any]]:
     text = ''
     if sys.stdin.isatty():
         if '--help' not in args and '-h' not in args:
-            print('You must pass the text to be hinted on STDIN', file=sys.stderr)
-            input(_('Press Enter to quit'))
-            return None
+            report_unhandled_error('You must pass the text to be hinted on STDIN')
     else:
         text = sys.stdin.buffer.read().decode('utf-8')
         sys.stdin = open(os.ctermid())
@@ -677,29 +698,33 @@ def main(args: List[str]) -> Optional[Dict[str, Any]]:
         opts, items = parse_hints_args(args[1:])
     except SystemExit as e:
         if e.code != 0:
-            print(e.args[0], file=sys.stderr)
-            input(_('Press Enter to quit'))
+            report_unhandled_error(e.args[0])
         return None
     if items and not (opts.customize_processing or opts.type == 'linenum'):
-        print('Extra command line arguments present: {}'.format(' '.join(items)), file=sys.stderr)
-        input(_('Press Enter to quit'))
+        report_unhandled_error('Extra command line arguments present: {}'.format(' '.join(items)))
     try:
         return run(opts, text, items)
     except Exception:
-        import traceback
-        traceback.print_exc()
-        input(_('Press Enter to quit'))
+        report_unhandled_error()
     return None
 
 
+def linenum_process_result(data: Dict[str, Any]) -> Tuple[str, int]:
+    lnum_pat = re.compile(r'(:\d+)$')
+    for match, g in zip(data['match'], data['groupdicts']):
+        path, line = g['path'], g['line']
+        if path and line:
+            m = lnum_pat.search(path)
+            if m is not None:
+                line = m.group(1)[1:]
+                path = path.rpartition(':')[0]
+            return os.path.expanduser(path), int(line)
+    return '', -1
+
+
 def linenum_handle_result(args: List[str], data: Dict[str, Any], target_window_id: int, boss: BossType, extra_cli_args: Sequence[str], *a: Any) -> None:
-    for m, g in zip(data['match'], data['groupdicts']):
-        if m:
-            path, line = g['path'], g['line']
-            path = os.path.expanduser(path.split(':')[-1])
-            line = int(line)
-            break
-    else:
+    path, line = linenum_process_result(data)
+    if not path:
         return
 
     cmd = [x.format(path=path, line=line) for x in extra_cli_args or ('vim', '+{line}', '{path}')]
@@ -720,7 +745,7 @@ def linenum_handle_result(args: List[str], data: Dict[str, Any], target_window_i
             else:
                 import shlex
                 text = ' '.join(shlex.quote(arg) for arg in cmd)
-                w.paste_bytes(text + '\r')
+                w.paste_bytes(f'{text}\r')
     elif action == 'background':
         import subprocess
         subprocess.Popen(cmd, cwd=data['cwd'])
@@ -730,7 +755,7 @@ def linenum_handle_result(args: List[str], data: Dict[str, Any], target_window_i
             }[action])(*cmd)
 
 
-@result_handler(type_of_input='screen-ansi')
+@result_handler(type_of_input='screen-ansi', has_ready_notification=Hints.overlay_ready_report_needed)
 def handle_result(args: List[str], data: Dict[str, Any], target_window_id: int, boss: BossType) -> None:
     if data['customize_processing']:
         m = load_custom_processor(data['customize_processing'])
@@ -772,7 +797,7 @@ def handle_result(args: List[str], data: Dict[str, Any], target_window_id: int,
         if program == '-':
             w = boss.window_id_map.get(target_window_id)
             if w is not None:
-                w.paste(joined_text())
+                w.paste_text(joined_text())
         elif program == '@':
             set_clipboard_string(joined_text())
         elif program == '*':

kittens/hyperlinked_grep/main.py

@@ -20,10 +20,13 @@ def write_hyperlink(write: Callable[[bytes], None], url: bytes, line: bytes, fra
 
 
 def main() -> None:
-    if not sys.stdout.isatty() and '--pretty' not in sys.argv:
+    if not sys.stdout.isatty() and '--pretty' not in sys.argv and '-p' not in sys.argv:
         os.execlp('rg', 'rg', *sys.argv[1:])
     cmdline = ['rg', '--pretty', '--with-filename'] + sys.argv[1:]
-    p = subprocess.Popen(cmdline, stdout=subprocess.PIPE)
+    try:
+        p = subprocess.Popen(cmdline, stdout=subprocess.PIPE)
+    except FileNotFoundError:
+        raise SystemExit('Could not find the rg executable in your PATH. Is ripgrep installed?')
     assert p.stdout is not None
     write: Callable[[bytes], None] = cast(Callable[[bytes], None], sys.stdout.buffer.write)
     sgr_pat = re.compile(br'\x1b\[.*?m')
@@ -56,7 +59,7 @@ def main() -> None:
                     write(line)
     except KeyboardInterrupt:
         p.send_signal(signal.SIGINT)
-    except EOFError:
+    except (EOFError, BrokenPipeError):
         pass
     finally:
         p.stdout.close()

kittens/icat/main.py

@@ -19,6 +19,7 @@ from kitty.cli import parse_args
 from kitty.cli_stub import IcatCLIOptions
 from kitty.constants import appname
 from kitty.guess_mime_type import guess_type
+from kitty.rgb import to_color
 from kitty.types import run_once
 from kitty.typing import GRT_f, GRT_t
 from kitty.utils import (
@@ -41,18 +42,31 @@ Horizontal alignment for the displayed image.
 
 
 --place
-Choose where on the screen to display the image. The image will
-be scaled to fit into the specified rectangle. The syntax for
-specifying rectangles is <:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>.
-All measurements are in cells (i.e. cursor positions) with the
-origin :italic:`(0, 0)` at the top-left corner of the screen.
+Choose where on the screen to display the image. The image will be scaled to fit
+into the specified rectangle. The syntax for specifying rectangles is
+<:italic:`width`>x<:italic:`height`>@<:italic:`left`>x<:italic:`top`>.
+All measurements are in cells (i.e. cursor positions) with the origin
+:italic:`(0, 0)` at the top-left corner of the screen.
 
 
 --scale-up
 type=bool-set
-When used in combination with :option:`--place` it will cause images that
-are smaller than the specified area to be scaled up to use as much
-of the specified area as possible.
+When used in combination with :option:`--place` it will cause images that are
+smaller than the specified area to be scaled up to use as much of the specified
+area as possible.
+
+
+--background
+default=none
+Specify a background color, this will cause transparent images to be composited
+on top of the specified color.
+
+
+--mirror
+default=none
+type=choices
+choices=none,horizontal,vertical,both
+Mirror the image about a horizontal or vertical axis or both.
 
 
 --clear
@@ -65,17 +79,18 @@ type=choices
 choices=detect,file,stream
 default=detect
 Which mechanism to use to transfer images to the terminal. The default is to
-auto-detect. :italic:`file` means to use a temporary file and :italic:`stream` means to
-send the data via terminal escape codes. Note that if you use the :italic:`file`
-transfer mode and you are connecting over a remote session then image display
-will not work.
+auto-detect. :italic:`file` means to use a temporary file and :italic:`stream`
+means to send the data via terminal escape codes. Note that if you use the
+:italic:`file` transfer mode and you are connecting over a remote session then
+image display will not work.
 
 
 --detect-support
 type=bool-set
 Detect support for image display in the terminal. If not supported, will exit
 with exit code 1, otherwise will exit with code 0 and print the supported
-transfer mode to stderr, which can be used with the :option:`--transfer-mode` option.
+transfer mode to stderr, which can be used with the :option:`--transfer-mode`
+option.
 
 
 --detection-timeout
@@ -87,17 +102,17 @@ detecting image display support.
 
 --print-window-size
 type=bool-set
-Print out the window size as :italic:`widthxheight` (in pixels) and quit. This is a
-convenience method to query the window size if using kitty icat from a
-scripting language that cannot make termios calls.
+Print out the window size as <:italic:`width`>x<:italic:`height`> (in pixels) and quit. This is a
+convenience method to query the window size if using :code:`kitty +kitten icat`
+from a scripting language that cannot make termios calls.
 
 
 --stdin
 type=choices
 choices=detect,yes,no
 default=detect
-Read image data from stdin. The default is to do it automatically, when STDIN is not a terminal,
-but you can turn it off or on explicitly, if needed.
+Read image data from STDIN. The default is to do it automatically, when STDIN is
+not a terminal, but you can turn it off or on explicitly, if needed.
 
 
 --silent
@@ -107,9 +122,9 @@ Do not print out anything to STDOUT during operation.
 
 --z-index -z
 default=0
-Z-index of the image. When negative, text will be displayed on top of the image. Use
-a double minus for values under the threshold for drawing images under cell background
-colors. For example, :code:`--1` evaluates as -1,073,741,825.
+Z-index of the image. When negative, text will be displayed on top of the image.
+Use a double minus for values under the threshold for drawing images under cell
+background colors. For example, :code:`--1` evaluates as -1,073,741,825.
 
 
 --loop -l
@@ -307,6 +322,9 @@ class ParsedOpts:
 
     place: Optional['Place'] = None
     z_index: int = 0
+    remove_alpha: str = ''
+    flip: bool = False
+    flop: bool = False
 
 
 def process(path: str, args: IcatCLIOptions, parsed_opts: ParsedOpts, is_tempfile: bool) -> bool:
@@ -316,9 +334,10 @@ def process(path: str, args: IcatCLIOptions, parsed_opts: ParsedOpts, is_tempfil
     available_height = parsed_opts.place.height * (ss.height // ss.rows) if parsed_opts.place else 10 * m.height
     needs_scaling = m.width > available_width or m.height > available_height
     needs_scaling = needs_scaling or args.scale_up
+    needs_conversion = needs_scaling or bool(parsed_opts.remove_alpha) or parsed_opts.flip or parsed_opts.flop
     file_removed = False
     use_number = 0
-    if m.fmt == 'png' and not needs_scaling:
+    if m.fmt == 'png' and not needs_conversion:
         outfile = path
         transmit_mode: 'GRT_t' = 't' if is_tempfile else 'f'
         fmt: 'GRT_f' = 100
@@ -328,13 +347,17 @@ def process(path: str, args: IcatCLIOptions, parsed_opts: ParsedOpts, is_tempfil
         fmt = 24 if m.mode == 'rgb' else 32
         transmit_mode = 't'
         if len(m) == 1 or args.loop == 0:
-            outfile, width, height = render_as_single_image(path, m, available_width, available_height, args.scale_up)
+            outfile, width, height = render_as_single_image(
+                path, m, available_width, available_height, args.scale_up,
+                remove_alpha=parsed_opts.remove_alpha, flip=parsed_opts.flip, flop=parsed_opts.flop)
         else:
             import struct
             use_number = max(1, struct.unpack('@I', os.urandom(4))[0])
             with NamedTemporaryFile() as f:
                 prefix = f.name
-            frame_data = render_image(path, prefix, m, available_width, available_height, args.scale_up)
+            frame_data = render_image(
+                path, prefix, m, available_width, available_height, args.scale_up,
+                remove_alpha=parsed_opts.remove_alpha, flip=parsed_opts.flip, flop=parsed_opts.flop)
             outfile, width, height = frame_data.frames[0].path, frame_data.width, frame_data.height
     show(
         outfile, width, height, parsed_opts.z_index, fmt, transmit_mode,
@@ -449,9 +472,8 @@ def process_single_item(
     file_removed = False
     try:
         if isinstance(item, bytes):
-            tf = NamedTemporaryFile(prefix='stdin-image-data-', delete=False)
-            tf.write(item)
-            tf.close()
+            with NamedTemporaryFile(prefix='stdin-image-data-', delete=False) as tf:
+                tf.write(item)
             item = tf.name
             is_tempfile = True
         if url_pat is not None and url_pat.match(item) is not None:
@@ -494,7 +516,12 @@ def main(args: List[str] = sys.argv) -> None:
     if cli_opts.print_window_size:
         screen_size_function.cache_clear()
         with open(os.ctermid()) as tty:
-            ss = screen_size_function(tty)()
+            try:
+                fd = tty.fileno()
+            except AttributeError:
+                # use default value for fd if ctermid is not available
+                fd = None
+            ss = screen_size_function(fd)()
         print(f'{ss.width}x{ss.height}', end='')
         raise SystemExit(0)
 
@@ -527,6 +554,13 @@ def main(args: List[str] = sys.argv) -> None:
         parsed_opts.z_index = parse_z_index(cli_opts.z_index)
     except Exception:
         raise SystemExit(f'Not a valid z-index specification: {cli_opts.z_index}')
+    if cli_opts.background != 'none':
+        ra = to_color(cli_opts.background)
+        if ra is None:
+            raise SystemExit(f'Not a valid color specification: {cli_opts.background}')
+        parsed_opts.remove_alpha = ra.as_sharp
+    parsed_opts.flip = cli_opts.mirror in ('both', 'vertical')
+    parsed_opts.flop = cli_opts.mirror in ('both', 'horizontal')
 
     if cli_opts.detect_support:
         if not detect_support(wait_for=cli_opts.detection_timeout, silent=True):
@@ -550,16 +584,26 @@ def main(args: List[str] = sys.argv) -> None:
             raise SystemExit(f'The --place option can only be used with a single image, not {items}')
         sys.stdout.buffer.write(b'\0337')  # save cursor
     url_pat = re.compile(r'(?:https?|ftp)://', flags=re.I)
+
+    def hold_if_needed(exit_code_or_msg: Union[int, str]) -> None:
+        if cli_opts.hold:
+            if isinstance(exit_code_or_msg, str):
+                print(exit_code_or_msg, file=sys.stderr, flush=True)
+                exit_code_or_msg = 1
+            with open(os.ctermid()) as tty, raw_mode(tty.fileno()):
+                tty.buffer.read(1)
+        raise SystemExit(exit_code_or_msg)
+
     for item in items:
         try:
             process_single_item(item, cli_opts, parsed_opts, url_pat)
         except NoImageMagick as e:
-            raise SystemExit(str(e))
+            hold_if_needed(str(e))
         except OutdatedImageMagick as e:
             print(e.detailed_error, file=sys.stderr)
-            raise SystemExit(str(e))
+            hold_if_needed(str(e))
         except ConvertFailed as e:
-            raise SystemExit(str(e))
+            hold_if_needed(str(e))
         except OpenFailed as e:
             errors.append(e)
     if parsed_opts.place:
@@ -567,11 +611,8 @@ def main(args: List[str] = sys.argv) -> None:
     if errors:
         for err in errors:
             print(err, file=sys.stderr)
-    if cli_opts.hold:
-        with open(os.ctermid()) as tty:
-            with raw_mode(tty.fileno()):
-                tty.buffer.read(1)
-    raise SystemExit(1 if errors else 0)
+    hold_if_needed(1 if errors else 0)
+    raise SystemExit()
 
 
 if __name__ == '__main__':

kittens/panel/main.py

@@ -85,9 +85,9 @@ def create_strut(
             '-id',
             str(int(win_id)), '-format', '_NET_WM_STRUT_PARTIAL', '32cccccccccccc',
             '-set', '_NET_WM_STRUT_PARTIAL',
-            '{left},{right},{top},{bottom},'
-            '{left_start_y},{left_end_y},{right_start_y},{right_end_y},'
-            '{top_start_x},{top_end_x},{bottom_start_x},{bottom_end_x}'.format(**locals())
+            f'{left},{right},{top},{bottom},'
+            f'{left_start_y},{left_end_y},{right_start_y},{right_end_y},'
+            f'{top_start_x},{top_end_x},{bottom_start_x},{bottom_end_x}'
     )
 
 

kittens/prewarm/main.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python
+# License: GPLv3 Copyright: 2022, Kovid Goyal <kovid at kovidgoyal.net>
+
+import io
+import json
+import os
+import select
+import signal
+import sys
+import time
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib import import_module
+from typing import (
+    IO, TYPE_CHECKING, Any, Dict, List, NoReturn, Optional, Union, cast
+)
+
+from kitty.child import remove_cloexec
+from kitty.constants import kitty_exe
+from kitty.entry_points import main as main_entry_point
+from kitty.fast_data_types import establish_controlling_tty, safe_pipe
+from kitty.shm import SharedMemory
+
+if TYPE_CHECKING:
+    from _typeshed import ReadableBuffer, WriteableBuffer
+
+
+hangup_events = select.POLLHUP
+error_events = select.POLLERR | select.POLLNVAL
+basic_events = hangup_events | error_events
+
+
+class PrewarmProcessFailed(Exception):
+    pass
+
+
+@dataclass
+class Child:
+    child_id: int
+    child_process_pid: int
+
+
+class PrewarmProcess:
+
+    def __init__(self, create_file_to_read_from_worker: bool = False) -> None:
+        self.from_worker_fd, self.in_worker_fd = safe_pipe()
+        self.children: Dict[int, Child] = {}
+        if create_file_to_read_from_worker:
+            os.set_blocking(self.from_worker_fd, True)
+            self.from_worker = open(self.from_worker_fd, mode='r', closefd=True)
+            self.from_worker_fd = -1
+
+    def take_from_worker_fd(self) -> int:
+        ans, self.from_worker_fd = self.from_worker_fd, -1
+        return ans
+
+    def __del__(self) -> None:
+        if self.from_worker_fd > -1:
+            os.close(self.from_worker_fd)
+            self.from_worker_fd = -1
+        if hasattr(self, 'from_worker'):
+            self.from_worker.close()
+            del self.from_worker
+        if self.worker_started:
+            import subprocess
+            self.process.stdin and self.process.stdin.close()
+            self.process.stdout and self.process.stdout.close()
+            try:
+                self.process.wait(timeout=1.0)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+            del self.process
+
+    @property
+    def worker_started(self) -> bool:
+        return self.in_worker_fd == -1
+
+    def ensure_worker(self) -> None:
+        if not self.worker_started:
+            import subprocess
+            self.process = subprocess.Popen(
+                [kitty_exe(), '+kitten', 'prewarm', str(self.in_worker_fd)], stdin=subprocess.PIPE, stdout=subprocess.PIPE, pass_fds=(self.in_worker_fd,))
+            os.close(self.in_worker_fd)
+            self.in_worker_fd = -1
+            assert self.process.stdin is not None and self.process.stdout is not None
+            self.write_to_process_fd = self.process.stdin.fileno()
+            self.read_from_process_fd = self.process.stdout.fileno()
+            os.set_blocking(self.write_to_process_fd, False)
+            os.set_blocking(self.read_from_process_fd, False)
+            self.poll = select.poll()
+            self.poll.register(self.process.stdout.fileno(), select.POLLIN | basic_events)
+
+    def poll_to_send(self, yes: bool = True) -> None:
+        if yes:
+            self.poll.register(self.write_to_process_fd, select.POLLOUT | basic_events)
+        else:
+            self.poll.unregister(self.write_to_process_fd)
+
+    def reload_kitty_config(self) -> None:
+        if self.worker_started:
+            self.send_to_prewarm_process('reload_kitty_config:\n')
+
+    def __call__(
+        self,
+        tty_fd: int,
+        argv: List[str],
+        cwd: str = '',
+        env: Optional[Dict[str, str]] = None,
+        stdin_data: Optional[Union[str, bytes]] = None
+    ) -> Child:
+        self.ensure_worker()
+        tty_name = os.ttyname(tty_fd)
+        if isinstance(stdin_data, str):
+            stdin_data = stdin_data.encode()
+        if env is None:
+            env = dict(os.environ)
+        cmd: Dict[str, Union[int, List[str], str, Dict[str, str]]] = {
+            'tty_name': tty_name, 'cwd': cwd or os.getcwd(), 'argv': argv, 'env': env,
+        }
+        total_size = 0
+        if stdin_data is not None:
+            cmd['stdin_size'] = len(stdin_data)
+            total_size += len(stdin_data)
+        data = json.dumps(cmd).encode()
+        total_size += len(data) + SharedMemory.num_bytes_for_size
+        with SharedMemory(size=total_size, unlink_on_exit=True) as shm:
+            shm.write_data_with_size(data)
+            if stdin_data:
+                shm.write(stdin_data)
+            shm.flush()
+            self.send_to_prewarm_process(f'fork:{shm.name}\n')
+            input_buf = b''
+            st = time.monotonic()
+            while time.monotonic() - st < 2:
+                for (fd, event) in self.poll.poll(0.2):
+                    if event & basic_events:
+                        raise PrewarmProcessFailed('Failed doing I/O with prewarm process')
+                    if fd == self.read_from_process_fd and event & select.POLLIN:
+                        d = os.read(self.read_from_process_fd, io.DEFAULT_BUFFER_SIZE)
+                        input_buf += d
+                        while (idx := input_buf.find(b'\n')) > -1:
+                            line = input_buf[:idx].decode()
+                            input_buf = input_buf[idx+1:]
+                            if line.startswith('CHILD:'):
+                                _, cid, pid = line.split(':')
+                                child = self.add_child(int(cid), int(pid))
+                                shm.unlink_on_exit = False
+                                return child
+                            if line.startswith('ERR:'):
+                                raise PrewarmProcessFailed(line.split(':', 1)[-1])
+        raise PrewarmProcessFailed('Timed out waiting for I/O with prewarm process')
+
+    def add_child(self, child_id: int, pid: int) -> Child:
+        self.children[child_id] = c = Child(child_id, pid)
+        return c
+
+    def send_to_prewarm_process(self, output_buf: Union[str, bytes] = b'', timeout: float = 2) -> None:
+        if isinstance(output_buf, str):
+            output_buf = output_buf.encode()
+        st = time.monotonic()
+        while time.monotonic() - st < timeout and output_buf:
+            self.poll_to_send(bool(output_buf))
+            for (fd, event) in self.poll.poll(0.2):
+                if event & basic_events:
+                    raise PrewarmProcessFailed('Failed doing I/O with prewarm process')
+                if fd == self.write_to_process_fd and event & select.POLLOUT:
+                    n = os.write(self.write_to_process_fd, output_buf)
+                    output_buf = output_buf[n:]
+        self.poll_to_send(False)
+        if output_buf:
+            raise PrewarmProcessFailed('Timed out waiting to write to prewarm process')
+
+    def mark_child_as_ready(self, child_id: int) -> bool:
+        c = self.children.pop(child_id, None)
+        if c is None:
+            return False
+        self.send_to_prewarm_process(f'ready:{child_id}\n')
+        return True
+
+
+def reload_kitty_config() -> None:
+    from kittens.tui.utils import kitty_opts
+    kitty_opts.clear_cached()
+    kitty_opts()
+
+
+def prewarm() -> None:
+    reload_kitty_config()
+    for kitten in ('hints', 'ssh', 'unicode_input', 'ask', 'show_error'):
+        import_module(f'kittens.{kitten}.main')
+
+
+class MemoryViewReadWrapperBytes(io.BufferedIOBase):
+
+    def __init__(self, mw: memoryview):
+        self.mw = mw
+        self.pos = 0
+
+    def detach(self) -> io.RawIOBase:
+        raise io.UnsupportedOperation('detach() not supported')
+
+    def read(self, size: Optional[int] = -1) -> bytes:
+        if size is None or size < 0:
+            size = max(0, len(self.mw) - self.pos)
+        oldpos = self.pos
+        self.pos = min(len(self.mw), self.pos + size)
+        if self.pos <= oldpos:
+            return b''
+        return bytes(self.mw[oldpos:self.pos])
+
+    def readinto(self, b: 'WriteableBuffer') -> int:
+        if not isinstance(b, memoryview):
+            b = memoryview(b)
+        b = b.cast('B')
+        data = self.read(len(b))
+        n = len(data)
+        b[:n] = data
+        return n
+    readinto1 = readinto
+
+    def readall(self) -> bytes:
+        return self.read()
+
+    def write(self, b: 'ReadableBuffer') -> int:
+        raise io.UnsupportedOperation('readonly stream')
+
+    def readable(self) -> bool:
+        return True
+
+
+class MemoryViewReadWrapper(io.TextIOWrapper):
+
+    def __init__(self, mw: memoryview):
+        super().__init__(cast(IO[bytes], MemoryViewReadWrapperBytes(mw)), encoding='utf-8', errors='replace')
+
+
+def child_main(cmd: Dict[str, Any], ready_fd: int) -> NoReturn:
+    cwd = cmd.get('cwd')
+    if cwd:
+        try:
+            os.chdir(cwd)
+        except OSError:
+            with suppress(OSError):
+                os.chdir('/')
+    os.setsid()
+    env = cmd.get('env')
+    if env is not None:
+        os.environ.clear()
+        os.environ.update(env)
+    argv = cmd.get('argv')
+    if argv:
+        sys.argv = list(argv)
+    poll = select.poll()
+    poll.register(ready_fd, select.POLLIN | select.POLLERR | select.POLLHUP)
+    poll.poll()
+    os.close(ready_fd)
+    tty_name = cmd.get('tty_name')
+    if tty_name:
+        sys.__stdout__.flush()
+        sys.__stderr__.flush()
+        establish_controlling_tty(tty_name, sys.__stdin__.fileno(), sys.__stdout__.fileno(), sys.__stderr__.fileno())
+    main_entry_point()
+    raise SystemExit(0)
+
+
+def fork(shm_address: str, ready_fd: int) -> int:
+    sz = pos = 0
+    with SharedMemory(name=shm_address, unlink_on_exit=True) as shm:
+        data = shm.read_data_with_size()
+        cmd = json.loads(data)
+        sz = cmd.get('stdin_size', 0)
+        if sz:
+            pos = shm.tell()
+            shm.unlink_on_exit = False
+
+    try:
+        child_pid = os.fork()
+    except OSError:
+        if sz:
+            with SharedMemory(shm_address, unlink_on_exit=True):
+                pass
+    if child_pid:
+        # master process
+        return child_pid
+    # child process
+    if shm.unlink_on_exit:
+        child_main(cmd, ready_fd)
+    else:
+        with SharedMemory(shm_address, unlink_on_exit=True) as shm:
+            stdin_data = memoryview(shm.mmap)[pos:pos + sz]
+            if stdin_data:
+                sys.stdin = MemoryViewReadWrapper(stdin_data)
+            try:
+                child_main(cmd, ready_fd)
+            finally:
+                stdin_data.release()
+                sys.stdin = sys.__stdin__
+
+
+def main(args: List[str] = sys.argv) -> None:
+    read_signal_fd, write_signal_fd = safe_pipe()
+    notify_child_death_fd = int(sys.argv[-1])
+    os.set_blocking(notify_child_death_fd, False)
+    signal.set_wakeup_fd(write_signal_fd)
+    signal.signal(signal.SIGCHLD, lambda *a: None)
+    signal.siginterrupt(signal.SIGCHLD, False)
+    prewarm()
+    stdin_fd = sys.__stdin__.fileno()
+    os.set_blocking(stdin_fd, False)
+    stdout_fd = sys.__stdout__.fileno()
+    os.set_blocking(stdout_fd, False)
+    poll = select.poll()
+    poll.register(stdin_fd, select.POLLIN | basic_events)
+    poll.register(read_signal_fd, select.POLLIN | basic_events)
+    input_buf = output_buf = child_death_buf = b''
+    child_ready_fds: Dict[int, int] = {}
+    child_id_map: Dict[int, int] = {}
+    self_pid = os.getpid()
+
+    def check_event(event: int, err_msg: str) -> None:
+        if event & hangup_events:
+            raise SystemExit(0)
+        if event & error_events:
+            raise SystemExit(err_msg)
+
+    def handle_input(event: int) -> None:
+        nonlocal input_buf, output_buf
+        check_event(event, 'Polling of STDIN failed')
+        if not (event & select.POLLIN):
+            return
+        d = os.read(stdin_fd, io.DEFAULT_BUFFER_SIZE)
+        if not d:
+            raise SystemExit(0)
+        input_buf += d
+        while (idx := input_buf.find(b'\n')) > -1:
+            line = input_buf[:idx].decode()
+            input_buf = input_buf[idx+1:]
+            cmd, _, payload = line.partition(':')
+            if cmd == 'reload_kitty_config':
+                reload_kitty_config()
+            elif cmd == 'ready':
+                child_id = int(payload)
+                cfd = child_ready_fds.pop(child_id)
+                if cfd is not None:
+                    os.write(cfd, b'1')
+                    os.close(cfd)
+            elif cmd == 'fork':
+                read_fd, write_fd = safe_pipe(False)
+                remove_cloexec(read_fd)
+                try:
+                    child_pid = fork(payload, read_fd)
+                except Exception as e:
+                    es = str(e).replace('\n', ' ')
+                    output_buf += f'ERR:{es}\n'.encode()
+                else:
+                    if os.getpid() == self_pid:
+                        child_id = len(child_id_map) + 1
+                        child_id_map[child_id] = child_pid
+                        child_ready_fds[child_id] = write_fd
+                        output_buf += f'CHILD:{child_id}:{child_pid}\n'.encode()
+                finally:
+                    if os.getpid() == self_pid:
+                        os.close(read_fd)
+            elif cmd == 'echo':
+                output_buf += f'{payload}\n'.encode()
+
+    def handle_output(event: int) -> None:
+        nonlocal output_buf
+        check_event(event, 'Polling of STDOUT failed')
+        if not (event & select.POLLOUT):
+            return
+        if output_buf:
+            n = os.write(stdout_fd, output_buf)
+            if not n:
+                raise SystemExit(0)
+            output_buf = output_buf[n:]
+        if not output_buf:
+            poll.unregister(stdout_fd)
+
+    def handle_notify_child_death(event: int) -> None:
+        nonlocal child_death_buf
+        check_event(event, 'Polling of notify child death fd failed')
+        if not (event & select.POLLOUT):
+            return
+        if child_death_buf:
+            n = os.write(notify_child_death_fd, child_death_buf)
+            if not n:
+                raise SystemExit(0)
+            child_death_buf = child_death_buf[n:]
+        if not child_death_buf:
+            poll.unregister(notify_child_death_fd)
+
+    def handle_signal(event: int) -> None:
+        nonlocal child_death_buf
+        check_event(event, 'Polling of signal fd failed')
+        if not (event & select.POLLIN):
+            return
+        d = os.read(read_signal_fd, io.DEFAULT_BUFFER_SIZE)
+        if not d:
+            raise SystemExit(0)
+        signals = set(bytearray(d))
+        if signal.SIGCHLD in signals:
+            while True:
+                try:
+                    pid, exit_status = os.waitpid(-1, os.WNOHANG)
+                except ChildProcessError:
+                    break
+                # a zero return means there is at least one child process
+                # existing and no exit status is available
+                if pid == 0:
+                    break
+                matched_child_id = -1
+                for child_id, child_pid in child_id_map.items():
+                    if child_pid == pid:
+                        matched_child_id = child_id
+                        break
+                if matched_child_id > -1:
+                    del child_id_map[matched_child_id]
+                    child_ready_fds.pop(matched_child_id, None)
+                    child_death_buf += f'{pid}\n'.encode()
+    try:
+        while True:
+            if output_buf:
+                poll.register(stdout_fd, select.POLLOUT | basic_events)
+            if child_death_buf:
+                poll.register(notify_child_death_fd, select.POLLOUT | basic_events)
+            for (q, event) in poll.poll():
+                if q == stdin_fd:
+                    handle_input(event)
+                elif q == stdout_fd:
+                    handle_output(event)
+                elif q == read_signal_fd:
+                    handle_signal(event)
+                elif q == notify_child_death_fd:
+                    handle_notify_child_death(event)
+    except (KeyboardInterrupt, EOFError, BrokenPipeError):
+        if os.getpid() == self_pid:
+            raise SystemExit(1)
+        raise
+    except Exception:
+        if os.getpid() == self_pid:
+            import traceback
+            traceback.print_exc()
+        raise
+    finally:
+        if os.getpid() == self_pid:
+            for fmd in child_ready_fds.values():
+                with suppress(OSError):
+                    os.close(fmd)
+
+
+if __name__ == '__main__':
+    main()