version 0.24.3

Since we are only sending the last command, it cannot have CSI
sequences in it anyway except in extremely contrived situations, so just
strip all ctrl chars out.

.github/FUNDING.yml

@@ -1,3 +1,4 @@
+github: kovidgoyal
 patreon: kovidgoyal
 liberapay: kovidgoyal
 custom: https://sw.kovidgoyal.net/kitty/support.html

.github/workflows/ci.py

@@ -30,28 +30,29 @@ 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'
-            ' 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 uuid-dev')
+        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 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:
-        if is_macos:
-            # needed for zlib for pillow, should not be needed after pillow 8.0
-            os.environ['PKG_CONFIG_PATH'] = '/usr/local/opt/zlib/lib/pkgconfig'
-        cmd = 'pip3 install Pillow pygments'
+        cmd = 'python3 -m pip install Pillow pygments'
         if sys.version_info[:2] < (3, 7):
-            cmd += ' importlib-resources'
+            cmd += ' importlib-resources dataclasses'
         run(cmd)
 
 
 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)
@@ -62,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())"')
@@ -79,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'])
 
@@ -114,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()
@@ -125,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.6
+                      pyver: 3.7
                       sanitize: 0
 
                     - python: b
-                      pyver: 3.7
+                      pyver: 3.8
                       sanitize: 1
 
                     - python: c
-                      pyver: 3.8
+                      pyver: 3.9
                       sanitize: 1
 
 
@@ -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

@@ -22,17 +22,12 @@ jobs:
         # a pull request then we can checkout the head.
         fetch-depth: 2
 
-    # If this run was triggered by a pull request event, then checkout
-    # the head of the pull request instead of the merge commit.
-    - run: git checkout HEAD^2
-      if: ${{ github.event_name == 'pull_request' }}
-
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v1
-      # Override language selection by uncommenting this and choosing your languages
-      # with:
-      #   languages: go, javascript, csharp, python, cpp, java
+      with:
+        languages: python, c
+        setup-python-dependencies: false
 
     - name: Build kitty
       run: python3 .github/workflows/ci.py build

.gitignore

@@ -19,3 +19,4 @@ __pycache__/
 /.mypy_cache
 .DS_Store
 bypy/b
+bypy/virtual-machines.conf

Brewfile

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

INSTALL.md

@@ -1,3 +1,3 @@
-To build from source: <https://sw.kovidgoyal.net/kitty/build/>
+[To build from source](https://sw.kovidgoyal.net/kitty/build/)
 
-Pre-built binaries: <https://sw.kovidgoyal.net/kitty/binary/>
+[Pre-built binaries](https://sw.kovidgoyal.net/kitty/binary/)

LICENSE

@@ -671,4 +671,4 @@ into proprietary programs.  If your program is a subroutine library, you
 may consider it more useful to permit linking proprietary applications with
 the library.  If this is what you want to do, use the GNU Lesser General
 Public License instead of this License.  But first, please read
-<https://www.gnu.org/philosophy/why-not-lgpl.html>.
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

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,5 +1,4 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2015, Kovid Goyal <kovid at kovidgoyal.net>
 
 import os
@@ -32,14 +31,16 @@ def runpy(args: List[str]) -> None:
 
 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)
+    try:
+        ret = subprocess.Popen(args[1:]).wait()
+    except KeyboardInterrupt:
+        pass
+    except FileNotFoundError:
+        print(f'Could not find {args[1]!r} to execute', file=sys.stderr)
+    except Exception as e:
+        print(e, file=sys.stderr)
+    from kitty.utils import hold_till_enter
+    hold_till_enter()
     raise SystemExit(ret)
 
 
@@ -48,6 +49,13 @@ def complete(args: List[str]) -> None:
     complete_main(args[1:], entry_points, namespaced_entry_points)
 
 
+def open_urls(args: List[str]) -> None:
+    setattr(sys, 'cmdline_args_for_open', True)
+    sys.argv = ['kitty'] + args[1:]
+    from kitty.main import main as kitty_main
+    kitty_main()
+
+
 def launch(args: List[str]) -> None:
     import runpy
     sys.argv = args[1:]
@@ -70,6 +78,27 @@ def launch(args: List[str]) -> None:
     runpy.run_path(exe, run_name='__main__')
 
 
+def shebang(args: List[str]) -> None:
+    script_path = args[1]
+    cmd = args[2:]
+    if cmd == ['__ext__']:
+        cmd = [os.path.splitext(script_path)[1][1:].lower()]
+    try:
+        f = open(script_path)
+    except FileNotFoundError:
+        raise SystemExit(f'The file {script_path} does not exist')
+    with f:
+        if f.read(2) == '#!':
+            line = f.readline().strip()
+            _plat = sys.platform.lower()
+            is_macos: bool = 'darwin' in _plat
+            if is_macos:
+                cmd = line.split(' ')
+            else:
+                cmd = line.split(' ', maxsplit=1)
+    os.execvp(cmd[0], cmd + [script_path])
+
+
 def run_kitten(args: List[str]) -> None:
     try:
         kitten = args[1]
@@ -105,10 +134,6 @@ 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,
@@ -116,24 +141,30 @@ entry_points = {
 namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
 namespaced_entry_points['hold'] = hold
 namespaced_entry_points['complete'] = complete
+namespaced_entry_points['runpy'] = runpy
+namespaced_entry_points['launch'] = launch
+namespaced_entry_points['open'] = open_urls
+namespaced_entry_points['kitten'] = run_kitten
+namespaced_entry_points['edit-config'] = edit_config_file
+namespaced_entry_points['shebang'] = shebang
 
 
 def setup_openssl_environment() -> None:
-    # Workaround for Linux distros that have still failed to get their heads
-    # out of their asses and implement a common location for SSL certificates.
-    # It's not that hard people, there exists a wonderful tool called the symlink
-    # See https://www.mobileread.com/forums/showthread.php?t=256095
-    if 'SSL_CERT_FILE' not in os.environ and 'SSL_CERT_DIR' not in os.environ:
-        if os.access('/etc/pki/tls/certs/ca-bundle.crt', os.R_OK):
-            os.environ['SSL_CERT_FILE'] = '/etc/pki/tls/certs/ca-bundle.crt'
-            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_FILE')
-        elif os.path.isdir('/etc/ssl/certs'):
-            os.environ['SSL_CERT_DIR'] = '/etc/ssl/certs'
-            setattr(sys, 'kitty_ssl_env_var', 'SSL_CERT_DIR')
+    # 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 'darwin' not in sys.platform.lower():
+    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)

build-terminfo

@@ -13,7 +13,7 @@ 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)
+        proc = subprocess.run(['tic', '-x', f'-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):

bypy/init_env.py

@@ -26,10 +26,11 @@ 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)
+    kitty_constants['cacerts_url'] = 'https://curl.haxx.se/ca/cacert.pem'
     return kitty_constants
 
 

bypy/linux.conf

@@ -1,3 +1,3 @@
-image 'https://partner-images.canonical.com/core/xenial/current/ubuntu-xenial-core-cloudimg-{}-root.tar.gz'
+image 'https://cloud-images.ubuntu.com/releases/bionic/release/ubuntu-18.04-server-cloudimg-{}.img'
 
 deps 'bison flex libxcursor-dev libxrandr-dev libxi-dev libxinerama-dev libgl1-mesa-dev libxcb-xkb-dev libfontconfig1-dev libdbus-1-dev'

bypy/linux/__main__.py

@@ -19,7 +19,11 @@ from bypy.freeze import (
 from bypy.utils import get_dll_path, mkdtemp, py_compile, walk
 
 j = os.path.join
-arch = 'x86_64' if is64bit else 'i686'
+machine = (os.uname()[4] or '').lower()
+if machine.startswith('arm64') or machine.startswith('aarch64'):
+    arch = 'arm64'
+else:
+    arch = 'x86_64' if is64bit else 'i686'
 self_dir = os.path.dirname(os.path.abspath(__file__))
 py_ver = '.'.join(map(str, python_major_minor_version()))
 iv = globals()['init_env']
@@ -29,12 +33,12 @@ kitty_constants = iv['kitty_constants']
 def binary_includes():
     return tuple(map(get_dll_path, (
             'expat', 'sqlite3', 'ffi', 'z', 'lzma', 'png16', 'lcms2', 'crypt',
-            'iconv', 'pcre', 'graphite2', 'glib-2.0', 'freetype',
+            'iconv', 'pcre', 'graphite2', 'glib-2.0', 'freetype', 'rsync',
             'harfbuzz', 'xkbcommon', 'xkbcommon-x11',
             'ncursesw', 'readline', 'brotlicommon', 'brotlienc', 'brotlidec'
         ))) + (
                 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),
         )
 
 
@@ -43,7 +47,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-')
@@ -92,9 +96,18 @@ def copy_libs(env):
         subprocess.check_call(['chrpath', '-d', dest])
 
 
+def add_ca_certs(env):
+    print('Downloading CA certs...')
+    from urllib.request import urlopen
+    cdata = urlopen(kitty_constants['cacerts_url']).read()
+    dest = os.path.join(env.lib_dir, 'cacert.pem')
+    with open(dest, 'wb') as f:
+        f.write(cdata)
+
+
 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)
@@ -106,8 +119,7 @@ def copy_python(env):
             shutil.copy2(y, env.py_dir)
 
     srcdir = j(srcdir, 'site-packages')
-    site_packages_dir = j(env.py_dir, 'site-packages')
-    import_site_packages(srcdir, site_packages_dir)
+    import_site_packages(srcdir, env.py_dir)
 
     pdir = os.path.join(env.lib_dir, 'kitty-extensions')
     os.makedirs(pdir, exist_ok=True)
@@ -175,11 +187,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'):
@@ -191,7 +203,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)
@@ -201,13 +213,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)))
 
 
@@ -220,6 +232,7 @@ def main():
     build_launcher(env)
     files = find_binaries(env)
     fix_permissions(files)
+    add_ca_certs(env)
     if not args.dont_strip:
         strip_binaries(files)
     if not args.skip_tests:

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-')
 
@@ -170,16 +170,35 @@ class Freeze(object):
         self.add_stdlib()
         self.add_misc_libraries()
         self.freeze_python()
+        self.add_ca_certs()
         if not self.dont_strip:
             self.strip_files()
         if not self.skip_tests:
             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
 
+    @flush
+    def add_ca_certs(self):
+        print('\nDownloading CA certs...')
+        from urllib.request import urlopen
+        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)
+
     @flush
     def strip_files(self):
         print('\nStripping files...')
@@ -187,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):
@@ -212,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/'):
+            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
 
@@ -229,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:
@@ -242,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))
@@ -252,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):
@@ -265,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
@@ -278,13 +297,14 @@ class Freeze(object):
                 'lcms2.2',
                 'crypto.1.1',
                 'ssl.1.1',
+                '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
@@ -310,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)
@@ -334,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])
@@ -423,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.
@@ -455,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
 
 
@@ -466,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

@@ -28,6 +28,15 @@
         }
     },
 
+    {
+        "name": "openssl",
+        "unix": {
+            "filename": "openssl-1.1.1i.tar.gz",
+            "hash": "sha256:e8be6a35fe41d10603c3cc635e93289ed00bf34b79671a3a4de64fcee00d5242",
+            "urls": ["https://www.openssl.org/source/{filename}"]
+        }
+    },
+
     {
         "name": "cmake",
         "os": "macos",
@@ -48,25 +57,22 @@
         }
     },
 
-
     {
         "name": "libxml2",
-        "os": "linux",
         "unix": {
-            "filename": "libxml2-2.9.10.tar.gz",
-            "hash": "sha256:aafee193ffb8fe0c82d4afef6ef91972cbaf5feea100edc2f262750611b4be1f",
+            "filename": "libxml2-2.9.12.tar.gz",
+            "hash": "sha256:c8d6681e38c56f172892c85ddc0852e1fd4b53b4209e7f4ebf17f7e2eae71d92",
             "urls": ["ftp://xmlsoft.org/libxml2/{filename}"]
         }
     },
 
-
     {
         "name": "xkbcommon",
         "os": "linux",
         "unix": {
             "filename": "libxkbcommon-1.0.3.tar.xz",
             "hash": "sha256:a2202f851e072b84e64a395212cbd976ee18a8ee602008b0bad02a13247dbc52",
-            "urls": ["http://xkbcommon.org/download/{filename}"]
+            "urls": ["https://xkbcommon.org/download/{filename}"]
         }
     },
 
@@ -90,15 +96,6 @@
         }
     },
 
-    {
-        "name": "openssl",
-        "unix": {
-            "filename": "openssl-1.1.1i.tar.gz",
-            "hash": "sha256:e8be6a35fe41d10603c3cc635e93289ed00bf34b79671a3a4de64fcee00d5242",
-            "urls": ["https://www.openssl.org/source/{filename}"]
-        }
-    },
-
     {
         "name": "ncurses",
         "os": "linux",
@@ -115,7 +112,7 @@
         "unix": {
             "filename": "readline-8.1.tar.gz",
             "hash": "sha256:f8ceb4ee131e3232226a17f51b164afc46cd0b9e6cef344be87c65962cb82b02",
-            "urls": ["http://ftp.gnu.org/gnu/readline/{filename}"]
+            "urls": ["https://ftp.gnu.org/gnu/readline/{filename}"]
         }
     },
 
@@ -128,6 +125,16 @@
         }
     },
 
+    {
+        "name": "librsync",
+        "unix": {
+            "filename": "librsync-2.3.2.tar.gz",
+            "hash": "sha256:ef8ce23df38d5076d25510baa2cabedffbe0af460d887d86c2413a1c2b0c676f",
+            "urls": ["https://github.com/librsync/librsync/releases/download/v2.3.2/{filename}"]
+        }
+    },
+
+
     {
         "name": "xcrypt",
         "os": "linux",
@@ -159,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"]
         }
     },
@@ -170,7 +177,7 @@
         "unix": {
             "filename": "libpng-1.6.37.tar.xz",
             "hash": "sha256:505e70834d35383537b6491e7ae8641f1a4bed1876dbfe361201fc80868d88ca",
-            "urls": ["http://downloads.sourceforge.net/sourceforge/libpng/{filename}"]
+            "urls": ["https://downloads.sourceforge.net/sourceforge/libpng/{filename}"]
         }
     },
 
@@ -189,7 +196,7 @@
         "unix": {
             "filename": "graphite2-1.3.14.tgz",
             "hash": "sha256:f99d1c13aa5fa296898a181dff9b82fb25f6cc0933dbaa7a475d8109bd54209d",
-            "urls": ["http://downloads.sourceforge.net/silgraphite/{filename}"]
+            "urls": ["https://downloads.sourceforge.net/silgraphite/{filename}"]
         }
     },
 
@@ -249,7 +256,7 @@
         "unix": {
             "filename": "fontconfig-2.13.1.tar.bz2",
             "hash": "sha256:f655dd2a986d7aa97e052261b36aa67b0a64989496361eca8d604e6414006741",
-            "urls": ["http://www.fontconfig.org/release/{filename}"]
+            "urls": ["https://www.fontconfig.org/release/{filename}"]
         }
     },
 
@@ -266,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}"]
         }
     },
@@ -276,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

@@ -5,6 +5,10 @@
  * Distributed under terms of the MIT license.
  */
 
+.italic {
+    font-style: italic;
+}
+
 .sidebar-logo {
     max-height: 128px;
 }
@@ -17,3 +21,16 @@
 .sidebar-tree a.current {
     font-style: italic;
 }
+
+details > summary {
+    color: var(--color-link);
+    cursor: pointer;
+    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/_static/custom.js

@@ -22,7 +22,7 @@ function scroll_sidebar_node_into_view(a) {
         a = a.offsetParent;
         if (!a || a == ss) break;
     }
-    ss.scrollTop = pos;
+    ss.scrollTo({top: pos, behavior: 'instant'});
 }
 
 function mark_current_link(sidebar_tree, a, onload) {

docs/actions.rst

@@ -4,6 +4,7 @@ Mappable actions
 .. highlight:: conf
 
 The actions described below can be mapped to any key press or mouse action
-using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`.
+using the ``map`` and ``mouse_map`` directives in :file:`kitty.conf`. For
+configuration examples, see the default shortcut links for each action.
 
 .. include:: /generated/actions.rst

docs/basic.rst

@@ -11,16 +11,20 @@ windows are:
 Scrolling
 ~~~~~~~~~~~~~~
 
-========================    =======================
+=========================   =======================
 Action                      Shortcut
-========================    =======================
-Scroll line up              :sc:`scroll_line_up` (also :kbd:`⌥+⌘+⇞` and :kbd:`⌘+↑` on macOS)
-Scroll line down            :sc:`scroll_line_down` (also :kbd:`⌥+⌘+⇟` and :kbd:`⌘+↓` on macOS)
-Scroll page up              :sc:`scroll_page_up` (also :kbd:`⌘+⇞` on macOS)
-Scroll page down            :sc:`scroll_page_down` (also :kbd:`⌘+⇟` on macOS)
-Scroll to top               :sc:`scroll_home` (also :kbd:`⌘+↖` on macOS)
-Scroll to bottom            :sc:`scroll_end` (also :kbd:`⌘+↘` on macOS)
-========================    =======================
+=========================   =======================
+Line up                     :sc:`scroll_line_up` (also :kbd:`⌥+⌘+⇞` and :kbd:`⌘+↑` on macOS)
+Line down                   :sc:`scroll_line_down` (also :kbd:`⌥+⌘+⇟` and :kbd:`⌘+↓` on macOS)
+Page up                     :sc:`scroll_page_up` (also :kbd:`⌘+⇞` on macOS)
+Page down                   :sc:`scroll_page_down` (also :kbd:`⌘+⇟` on macOS)
+Top                         :sc:`scroll_home` (also :kbd:`⌘+↖` on macOS)
+Bottom                      :sc:`scroll_end` (also :kbd:`⌘+↘` on macOS)
+Previous shell prompt       :sc:`scroll_to_previous_prompt` (see :ref:`shell_integration`)
+Next shell prompt           :sc:`scroll_to_next_prompt` (see :ref:`shell_integration`)
+Browse scrollback in less   :sc:`show_scrollback`
+Browse last cmd output      :sc:`show_last_command_output` (see :ref:`shell_integration`)
+=========================   =======================
 
 Tabs
 ~~~~~~~~~~~
@@ -30,8 +34,8 @@ Action                      Shortcut
 ========================    =======================
 New tab                     :sc:`new_tab` (also :kbd:`⌘+t` on macOS)
 Close tab                   :sc:`close_tab` (also :kbd:`⌘+w` on macOS)
-Next tab                    :sc:`next_tab` (also :kbd:`^+⇥` and :kbd:`⇧+⌘+]` on macOS)
-Previous tab                :sc:`previous_tab` (also :kbd:`⇧+^+⇥` and :kbd:`⇧+⌘+[` on macOS)
+Next tab                    :sc:`next_tab` (also :kbd:`⌃+⇥` and :kbd:`⇧+⌘+]` on macOS)
+Previous tab                :sc:`previous_tab` (also :kbd:`⇧+⌃+⇥` and :kbd:`⇧+⌘+[` on macOS)
 Next layout                 :sc:`next_layout`
 Move tab forward            :sc:`move_tab_forward`
 Move tab backward           :sc:`move_tab_backward`
@@ -53,6 +57,8 @@ Previous window             :sc:`previous_window`
 Move window forward         :sc:`move_window_forward`
 Move window backward        :sc:`move_window_backward`
 Move window to top          :sc:`move_window_to_top`
+Visually focus window       :sc:`focus_visible_window`
+Visually swap window        :sc:`swap_with_window`
 Focus specific window       :sc:`first_window`, :sc:`second_window` ... :sc:`tenth_window`
                             (also :kbd:`⌘+1`, :kbd:`⌘+2` ... :kbd:`⌘+9` on macOS)
                             (clockwise from the top-left)
@@ -71,8 +77,11 @@ 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.
+``nth_window`` will focus the nth window for positive numbers (starting from
+zero) and the previously active windows for negative numbers.
+
+To switch to the nth OS window, you can define ``nth_os_window``. Only positive
+numbers are accepted, starting from one.
 
 .. _detach_window:
 
@@ -118,15 +127,15 @@ Paste from selection                :sc:`paste_from_selection`
 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 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`
-Reload :file:`kitty.conf`           :sc:`reload_config_file` (also :kbd:`^+⌘+f5` on macOS)
-Debug :file:`kitty.conf`            :sc:`debug_config` (also :kbd:`⌘+option+f6` on macOS)
+Input unicode character             :sc:`input_unicode_character` (also :kbd:`⌃+⌘+space` on macOS)
+Open URL in web browser             :sc:`open_url`
+Reset the terminal                  :sc:`reset_terminal` (also :kbd:`⌥+⌘+r` on macOS)
+Reload :file:`kitty.conf`           :sc:`reload_config_file` (also :kbd:`⌃+⌘+,` on macOS)
+Debug :file:`kitty.conf`            :sc:`debug_config` (also :kbd:`⌥+⌘+,` on macOS)
 Pass current selection to program   :sc:`pass_selection_to_program`
-Edit |kitty| config file            :sc:`edit_config_file`
+Edit |kitty| config file            :sc:`edit_config_file` (also :kbd:`⌘+,` on macOS)
 Open a |kitty| shell                :sc:`kitty_shell`
 Increase background opacity         :sc:`increase_background_opacity`
 Decrease background opacity         :sc:`decrease_background_opacity`

docs/binary.rst

@@ -22,6 +22,11 @@ The binaries will be installed in the standard location for your OS,
 Linux. The installer only touches files in that directory. To update kitty,
 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
+   :file:`/usr/bin` or wherever.
+
 
 Manually installing
 ---------------------
@@ -48,8 +53,10 @@ particular desktop, but it should work for most major desktop environments.
     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 path to the kitty 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
 
 .. note::
     If you use the venerable `stow <https://www.gnu.org/software/stow/>`_
@@ -63,6 +70,25 @@ particular desktop, but it should work for most major desktop environments.
 Customizing the installation
 --------------------------------
 
+.. _nightly:
+
+* You can install the latest nightly kitty build with ``installer``:
+
+  .. parsed-literal::
+     :class: pre
+
+     |ins| \\
+         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
+
+     |ins| \\
+         installer=nightly dest=/some/other/location
+
 * You can specify a different install location, with ``dest``:
 
   .. parsed-literal::
@@ -88,6 +114,7 @@ Customizing the installation
      |ins| \\
          installer=/path/to/dmg or tarball
 
+
 Uninstalling
 ----------------
 

docs/build.rst

@@ -5,10 +5,14 @@ Build from source
   :alt: Build status
   :target: https://github.com/kovidgoyal/kitty/actions?query=workflow%3ACI
 
+.. highlight:: sh
 
 |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
+   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
@@ -30,6 +34,7 @@ Run-time dependencies:
 * ``zlib``
 * ``libpng``
 * ``liblcms2``
+* ``librsync``
 * ``freetype`` (not needed on macOS)
 * ``fontconfig`` (not needed on macOS)
 * ``libcanberra`` (not needed on macOS)
@@ -41,10 +46,20 @@ 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 ``-dev`` packages for:
-  ``libdbus-1-dev``, ``libxcursor-dev``, ``libxrandr-dev``, ``libxi-dev``, ``libxinerama-dev``,
-  ``libgl1-mesa-dev``, ``libxkbcommon-x11-dev``, ``libfontconfig-dev``, ``libx11-xcb-dev``,
-  ``liblcms2-dev``, and ``libpython3-dev``, 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``
+  - ``libxrandr-dev``
+  - ``libxi-dev``
+  - ``libxinerama-dev``
+  - ``libgl1-mesa-dev``
+  - ``libxkbcommon-x11-dev``
+  - ``libfontconfig-dev``
+  - ``libx11-xcb-dev``
+  - ``liblcms2-dev``
+  - ``libpython3-dev``
+  - ``librsync-dev``
 
 
 Install and run from source
@@ -84,13 +99,18 @@ you might have to rebuild the app.
    `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>`_.
 
+.. note::
+   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
 -------------------------------------------
 
@@ -105,7 +125,9 @@ make them available in the newly spawned shell.
 Then proceed with ``make`` or ``make app`` according to the platform specific instructions above.
 
 
-Note for Linux/macOS packagers
+.. _packagers:
+
+Notes for Linux/macOS packagers
 ----------------------------------
 
 The released |kitty| source code is available as a `tarball`_ from
@@ -125,10 +147,21 @@ with :file:`linux-package/bin/kitty`.  All the files needed to run kitty will be
 installed. You can choose a different staging area, by passing the ``--prefix``
 argument to :file:`setup.py`.
 
-You should probably split |kitty| into two packages, :file:`kitty-terminfo` that
-installs the terminfo file and :file:`kitty` that installs the main program.
-This allows users to install the terminfo file on servers into which they ssh,
-without needing to install all of |kitty|.
+You should probably split |kitty| into three packages:
+
+:code:`kitty-terminfo`
+    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
+    :file:`/usr/share/kitty/shell-integration`
+
+:code:`kitty`
+    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|.
 
 .. note::
    You need a couple of extra dependencies to build linux-package.
@@ -140,10 +173,30 @@ without needing to install all of |kitty|.
    ``python -m pip -r docs/requirements.txt``.
 
 This applies to creating packages for |kitty| for macOS package managers such as
-brew or MacPorts as well.
+Homebrew or MacPorts as well.
 
 
-.. note::
+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
-   ``python3 setup.py linux-package --update-check-interval=0``
+   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. For a package, it might make more sense
+   to distribute the shell integration scripts into the system-wide shell
+   vendor locations. The shell integration files are found in the
+   :file:`shell-integration` directory. Copy them to the system wide shell
+   vendor locations for each shell, and use::
+
+       ./setup.py linux-package --shell-integration=enabled\ no-rc
+
+   This will prevent kitty from modifying the user's shell environment to load
+   the integration scripts.

docs/changelog.rst

@@ -4,8 +4,432 @@ 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
+
+   A demo video
+   ~~~~~~~~~~~~~~~~
+
+   A new video showcasing some of kitty's many productivity enhancing features.
+
+   .. raw:: html
+
+        <video controls width="640" height="360" poster="../_static/poster.png">
+            <source src="https://download.calibre-ebook.com/videos/kitty.mp4" type="video/mp4">
+            <source src="https://download.calibre-ebook.com/videos/kitty.webm" type="video/webm">
+        </video>
+
+   .. rst-class:: caption caption-text
+
+       Watch kitty in action!
+
+
+Shell integration
+~~~~~~~~~~~~~~~~~~~~~
+
+kitty automatically integrates with common shells to allow browsing the
+output of the previous command in a pager by pressing
+:sc:`show_last_command_output`, jumping to previous prompt locations in the
+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.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]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Integrate kitty closely with common shells such as zsh, fish and bash.
+  This allows lots of niceties such as jumping to previous prompts, opening the
+  output of the last command in a new window, etc. See :ref:`shell_integration`
+  for details. Packagers please read :ref:`packagers`.
+
+- A new shortcut :sc:`focus_visible_window` to visually focus a window using
+  the keyboard. Pressing it causes numbers to appear over each visible window
+  and you can press the number to focus the corresponding window (:iss:`4110`)
+
+- A new facility :opt:`window_logo_path` to draw an arbitrary PNG image as
+  logo in the corner of a kitty window (:pull:`4167`)
+
+- Allow rendering the cursor with a *reverse video* effect. See :opt:`cursor`
+  for details (:iss:`126`)
+
+- Allow rendering the mouse selection with a *reverse video* effect. See
+  :opt:`selection_foreground` (:iss:`646`)
+
+- A new option :opt:`tab_bar_align` to draw the tab bar centered or right
+  aligned (:iss:`3946`)
+
+- Allow the user to supply a custom Python function to draw tab bar. See
+  :opt:`tab_bar_style`
+
+- A new remote control command to :program:`change the tab color <kitty @
+  set-tab-color>` (:iss:`1287`)
+
+- A new remote control command to :program:`visually select a window <kitty @
+  select-window>` (:iss:`4165`)
+
+- Add support for reporting mouse events with pixel co-ordinates using the
+  ``SGR_PIXEL_PROTOCOL`` introduced in xterm 359
+
+- When programs ask to read from the clipboard prompt, ask the user to allow
+  the request by default instead of denying it by default. See
+  :opt:`clipboard_control` for details (:iss:`4022`)
+
+- A new mappable action ``swap_with_window`` to swap the current window with another window in the tab, visually
+
+- A new :program:`remote control command <kitty @ set-enabled-layouts>` to change
+  the enabled layouts in a tab (:iss:`4129`)
+
+- A new option :opt:`bell_path` to specify the path to a sound file
+  to use as the bell sound
+
+- A new option :opt:`exe_search_path` to modify the locations kitty searches
+  for executables to run (:iss:`4324`)
+
+- broadcast kitten: Show a "fake" cursor in all windows being broadcast too
+  (:iss:`4225`)
+
+- Allow defining :opt:`aliases <action_alias>` for more general actions, not just kittens
+  (:pull:`4260`)
+
+- Fix a regression that caused :option:`kitty --title` to not work when
+  opening new OS windows using :option:`kitty --single-instance` (:iss:`3893`)
+
+- icat kitten: Fix display of JPEG images that are rotated via EXIF data and
+  larger than available screen size (:iss:`3949`)
+
+- macOS: Fix SIGUSR1 quitting kitty instead of reloading the config file (:iss:`3952`)
+
+- Launch command: Allow specifying the OS window title
+
+- broadcast kitten: Allow broadcasting :kbd:`ctrl+c` (:pull:`3956`)
+
+- Fix space ligatures not working with Iosevka for some characters in the
+  Enclosed Alphanumeric Supplement (:iss:`3954`)
+
+- hints kitten: Fix a regression that caused using the default open program
+  to trigger open actions instead of running the program (:iss:`3968`)
+
+- Allow deleting environment variables in :opt:`env` by specifying
+  just the variable name, without a value
+
+- Fix :opt:`active_tab_foreground` not being honored when :opt:`tab_bar_style`
+  is ``slant`` (:iss:`4053`)
+
+- When a :opt:`tab_bar_background` is specified it should extend to the edges
+  of the OS window (:iss:`4054`)
+
+- Linux: Fix IME with fcitx5 not working after fcitx5 is restarted
+  (:pull:`4059`)
+
+- Various improvements to IME integration (:iss:`4219`)
+
+- Remote file transfer: Fix transfer not working if custom ssh port or identity
+  is specified on the command line (:iss:`4067`)
+
+- Unicode input kitten: Implement scrolling when more results are found than
+  the available display space (:pull:`4068`)
+
+- Allow middle clicking on a tab to close it (:iss:`4151`)
+
+- The command line option ``--watcher`` has been deprecated in favor of the
+  :opt:`watcher` option in :file:`kitty.conf`. It has the advantage of
+  applying to all windows, not just the initially created ones. Note that
+  ``--watcher`` now also applies to all windows, not just initially created ones.
+
+- **Backward incompatibility**: No longer turn on the kitty extended keyboard
+  protocol's disambiguate mode when the client sends the XTMODKEYS escape code.
+  Applications must use the dedicated escape code to turn on the protocol.
+  (:iss:`4075`)
+
+- Fix soft hyphens not being preserved when round tripping text through the
+  terminal
+
+- macOS: Fix :kbd:`ctrl+shift` with :kbd:`Esc` or :kbd:`F1` - :kbd:`F12` not working
+  (:iss:`4109`)
+
+- macOS: Fix :opt:`resize_in_steps` not working correctly on high DPI screens
+  (:iss:`4114`)
+
+- Fix the :program:`resize OS Windows <kitty @ resize-os-window>` setting a
+  slightly incorrect size on high DPI screens (:iss:`4114`)
+
+- :program:`kitty @ launch` - when creating tabs with the ``--match`` option create
+  the tab in the OS Window containing the result of the match rather than
+  the active OS Window (:iss:`4126`)
+
+- Linux X11: Add support for 10bit colors (:iss:`4150`)
+
+- Fix various issues with changing :opt:`tab_bar_background` by remote control
+  (:iss:`4152`)
+
+- A new option :opt:`tab_bar_margin_color` to control the color of the tab bar
+  margins
+
+- A new option :opt:`visual_bell_color` to customize the color of the visual bell
+  (:pull:`4181`)
+
+- Add support for OSC 777 based desktop notifications
+
+- Wayland: Fix pasting from applications that use a MIME type of "text/plain"
+  rather than "text/plain;charset=utf-8" not working (:iss:`4183`)
+
+- A new mappable action to close windows with a confirmation (:iss:`4195`)
+
+- When remembering OS window sizes for full screen windows use the size before
+  the window became fullscreen (:iss:`4221`)
+
+- macOS: Fix keyboard input not working after toggling fullscreen till the
+  window is clicked in
+
+- A new mappable action ``nth_os_window`` to to focus the specified nth OS
+  window. (:pull:`4316`)
+
+- macOS: The kitty window can be scrolled by the mouse wheel when OS window not
+  in focus. (:pull:`4371`)
+
+- macOS: Light or dark system appearance can be specified in
+  :opt:`macos_titlebar_color` and used in kitty themes. (:pull:`4378`)
+
+
+0.23.1 [2021-08-17]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- macOS: Fix themes kitten failing to download themes because of missing SSL
+  root certificates (:iss:`3936`)
+
+- A new option :opt:`clipboard_max_size` to control the maximum size
+  of data that kitty will transmit to the system clipboard on behalf of
+  programs running inside it (:iss:`3937`)
+
+- When matching windows/tabs in kittens or using remote control, allow matching
+  by recency. ``recent:0`` matches the active window/tab, ``recent:1`` matches
+  the previous window/tab and so on
+
+- themes kitten: Fix only the first custom theme file being loaded correctly
+  (:iss:`3938`)
+
+
 0.23.0 [2021-08-16]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new :doc:`themes kitten </kittens/themes>` to easily change kitty themes.
   Choose from almost two hundred themes in the `kitty themes repository
@@ -51,7 +475,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.22.2 [2021-08-02]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Fix a long standing bug that could cause kitty windows to stop
   updating, that got worse in the previous release (:iss:`3890` and
@@ -62,7 +486,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.22.1 [2021-07-31]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix a regression in the previous release that broke ``kitty --help`` (:iss:`3869`)
 
@@ -85,9 +509,9 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 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
@@ -155,7 +579,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.21.2 [2021-06-28]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new :opt:`adjust_baseline` option to adjust the vertical alignment of text
   inside a line (:pull:`3734`)
@@ -198,7 +622,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.21.1 [2021-06-14]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Fix a regression in the previous release that broke rendering of
   strikeout (:iss:`3717`)
@@ -211,7 +635,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.21.0 [2021-06-12]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow reloading the :file:`kitty.conf` config file by pressing
   :sc:`reload_config_file`. (:iss:`1292`)
@@ -243,7 +667,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Unicode input kitten: Fix a regression in 0.20.0 that broke keyboard handling
   when the NumLock or CapsLock modifiers were engaged. (:iss:`3587`)
 
-- Fix a regression in 0.20.0 that sent incorrect bytes for the :kbd:`F1-F4` keys
+- Fix a regression in 0.20.0 that sent incorrect bytes for the :kbd:`F1`-:kbd:`F4` keys
   in rmkx mode (:iss:`3586`)
 
 - macOS: When the Apple Color Emoji font lacks an emoji glyph search for it in other
@@ -304,7 +728,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.20.3 [2021-05-06]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Distribute universal binaries with both ARM and Intel architectures
 
@@ -325,7 +749,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.20.2 [2021-04-28]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new protocol extension to :ref:`unscroll <unscroll>` text from the
   scrollback buffer onto the screen. Useful, for example, to restore
@@ -365,7 +789,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.20.1 [2021-04-19]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - icat: Fix some broken GIF images with no frame delays not being animated
   (:iss:`3498`)
@@ -378,7 +802,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.20.0 [2021-04-19]
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Support display of animated images ``kitty +kitten icat animation.gif``. See
   :ref:`animation_protocol` for details on animation support in the kitty
@@ -502,7 +926,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.19.3 [2020-12-19]
--------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Happy holidays to all kitty users!
 
@@ -564,7 +988,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.19.2 [2020-11-13]
--------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new :doc:`kittens/query_terminal` kitten to easily query the running kitty
   via escape codes to detect its version, and the values of
@@ -607,7 +1031,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.19.1 [2020-10-06]
--------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - hints kitten: Add an ``ip`` type for easy selection of IP addresses
   (:pull:`3009`)
@@ -619,7 +1043,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.19.0 [2020-10-04]
--------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add support for `hyperlinks from terminal programs
   <https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>`_.
@@ -691,7 +1115,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.18.3 [2020-08-11]
--------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - hints kitten: Allow customizing hint colors (:pull:`2894`)
 
@@ -712,7 +1136,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.18.2 [2020-07-28]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - X11: Improve handling of multiple keyboards. Now pressing a modifier key in
   one keyboard and a normal key in another works (:iss:`2362`). Don't rebuild
@@ -777,13 +1201,13 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.18.1 [2020-06-23]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Fix for diff kitten not working with python 3.8 (:iss:`2780`)
 
 
 0.18.0 [2020-06-20]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow multiple overlay windows per normal window
 
@@ -834,7 +1258,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.17.4 [2020-05-09]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow showing the name of the current layout and the number of windows
   in tab titles (:iss:`2634`)
@@ -861,7 +1285,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.17.3 [2020-04-23]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow individually setting margins and padding for each edge (left, right,
   top, bottom). Margins can also be controlled per window via remote control
@@ -915,7 +1339,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Fix :option:`--title` not being applied at window creation time (:iss:`2570`)
 
 0.17.2 [2020-03-29]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add a :option:`launch --watcher` option that allows defining callbacks
   that are called for various events in the window's life-cycle (:iss:`2440`)
@@ -946,7 +1370,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.17.1 [2020-03-24]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix :opt:`cursor_underline_thickness` not working (:iss:`2465`)
 
@@ -961,7 +1385,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.17.0 [2020-03-24]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - :ref:`splits_layout` to arrange windows in arbitrary splits
   (:iss:`2308`)
@@ -1052,7 +1476,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.16.0 [2020-01-28]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new :doc:`marks` feature that allows highlighting and scrolling to arbitrary
   text in the terminal window.
@@ -1099,7 +1523,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   them. (:iss:`2310`)
 
 0.15.1 [2019-12-21]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix a crash/incorrect rendering when detaching a window in some circumstances
   (:iss:`2173`)
@@ -1124,7 +1548,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.15.0 [2019-11-27]
---------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add a new action :ref:`detach_window <detach_window>` that can be used to move the current
   window into a different tab (:iss:`1310`)
@@ -1174,7 +1598,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.6 [2019-09-25]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Fix a regression in the previous release that caused a crash when
   pressing a unprintable key, such as the POWER key (:iss:`1997`)
@@ -1184,7 +1608,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.5 [2019-09-23]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Implement a hack to (mostly) preserve tabs when cat-ting a file with them and then
   copying the text or passing screen contents to another program (:iss:`1829`)
@@ -1207,7 +1631,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Use selection foreground color for underlines as well (:iss:`1982`)
 
 0.14.4 [2019-08-31]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - hints kitten: Add a :option:`kitty +kitten hints --alphabet` option to
   control what alphabets are used for hints (:iss:`1879`)
@@ -1246,7 +1670,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.3 [2019-07-29]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Remote control: Add a command `kitty @ scroll-window` to scroll windows
 
@@ -1301,7 +1725,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.2 [2019-06-09]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option :opt:`placement_strategy` to control how the cell area is
   aligned inside the window when the window size is not an exact multiple
@@ -1343,7 +1767,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.1 [2019-05-29]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option :opt:`command_on_bell` to run an arbitrary command when
   a bell occurs (:iss:`1660`)
@@ -1378,7 +1802,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.14.0 [2019-05-24]
----------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: The default behavior of the Option key has changed. It now generates
   unicode characters rather than acting as the :kbd:`Alt` modifier. See
@@ -1513,7 +1937,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   characters not working well (:iss:`1616`)
 
 0.13.3 [2019-01-19]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - icat kitten: Add a ``--stdin`` option to control if image data is read from
   STDIN (:iss:`1308`)
@@ -1551,7 +1975,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.13.2 [2019-01-04]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add a new option :opt:`tab_title_template` to control how tab titles
   are formatted. In particular the template can be used to display
@@ -1593,7 +2017,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.13.1 [2018-12-06]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix passing input via the pipe action to a program without a window not
   working.
@@ -1606,7 +2030,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   be properly unwrapped (:iss:`1206`)
 
 0.13.0 [2018-12-05]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option :opt:`scrollback_pager_history_size` to tell kitty to store
   extended scrollback to use when viewing the scrollback buffer in a pager
@@ -1703,7 +2127,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   and slash characters in short URLs (:iss:`1201`)
 
 0.12.3 [2018-09-29]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - macOS: Fix kitty window not being rendered on macOS Mojave until the window is
   moved or resized at least once (:iss:`887`)
@@ -1712,7 +2136,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.12.2 [2018-09-24]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new ``last_used_layout`` function that can be mapped to a shortcut to
   switch to the previously used window layout (:iss:`870`)
@@ -1779,7 +2203,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   mouse to malfunction when using multiple kitty windows (:iss:`1002`)
 
 0.12.1 [2018-09-08]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add a new ``--start-in-fullscreen`` command line flag to start
   kitty in full screen mode (:iss:`856`)
@@ -1822,7 +2246,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   a bug in the 0.12.0 macOS package
 
 0.12.0 [2018-09-01]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Preserve the mouse selection even when the contents of the screen are
   scrolled or overwritten provided the new text does not intersect the
@@ -1832,7 +2256,8 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   using standard keyboards) via `IBus
   <https://github.com/ibus/ibus/wiki/ReadMe>`_ (:iss:`469`)
 
-- Implement completion for the kitty command in bash and zsh
+- Implement completion for the kitty command in bash and zsh. See
+  :ref:`shell_integration`.
 
 - Render the text under the cursor in a fixed color, configurable via
   the option :opt:`cursor_text_color` (:iss:`126`)
@@ -1896,7 +2321,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.11.3 [2018-07-10]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Draw only the minimum borders needed for inactive windows. That is only the borders
   that separate the inactive window from a neighbor. Note that setting
@@ -1930,7 +2355,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.11.2 [2018-07-01]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Linux: Allow using XKB key names to bind shortcuts to keys not supported by GLFW (:pull:`665`)
 
@@ -1967,7 +2392,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.11.1 [2018-06-17]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - diff kitten: Implement searching for text in the diff (:iss:`574`)
 
@@ -1995,7 +2420,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.11.0 [2018-06-12]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new tab bar style "fade" in which each tab's edges fade into the background.
   See :opt:`tab_bar_style` and :opt:`tab_fade` for details. The old look can be
@@ -2086,7 +2511,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.10.1 [2018-05-24]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add a kitten to easily ssh into servers that automatically copies the
   terminfo files over. ``kitty +kitten ssh myserver``.
@@ -2111,7 +2536,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.10.0 [2018-05-21]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A diff kitten to show side-by-side diffs with syntax highlighting and support
   for images. See :doc:`diff kitten <kittens/diff>`.
@@ -2161,7 +2586,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.9.1 [2018-05-05]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Show a bell symbol on the tab if a bell occurs in one of the windows in the tab and
   the window is not the currently focused window
@@ -2229,7 +2654,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.9.0 [2018-04-15]
-------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A new kitty command shell to allow controlling kitty via commands. Press
   `ctrl+shift+escape` to run the shell.
@@ -2273,7 +2698,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.8.4 [2018-03-31]
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix presence of XDG_CONFIG_DIRS and absence of XDG_CONFIG_HOME preventing
   kitty from starting
@@ -2283,7 +2708,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.8.3 [2018-03-29]
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix a regression that broke the visual bell and invert screen colors escape
   code
@@ -2308,7 +2733,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.8.2 [2018-03-17]
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow extending existing selections by right clicking
 
@@ -2331,7 +2756,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 - Fix a crash when getting the contents of the scrollback buffer as text
 
 0.8.1 [2018-03-09]
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Extend kitty's remote control feature to work over both UNIX and TCP sockets,
   so now you can control kitty from across the internet, if you want to.
@@ -2363,7 +2788,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.8.0 [2018-02-24]
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - A framework for kittens, that is, small terminal programs designed to run
   inside kitty and extend its capabilities. Examples include unicode input and
@@ -2408,7 +2833,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
   new window/tab.
 
 0.7.1 [2018-01-31]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option to adjust the width of character cells
 
@@ -2420,7 +2845,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.7.0 [2018-01-24]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Allow controlling kitty from the shell prompt/scripts. You can
   open/close/rename windows and tabs and even send input to specific windows.
@@ -2465,7 +2890,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.6.1 [2017-12-28]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option to fade the text in inactive windows
 
@@ -2493,7 +2918,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.6.0 [2017-12-18]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Support background transparency via the background_opacity option. Provided
   that your OS/window manager supports transparency, you can now have kitty
@@ -2544,7 +2969,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.5.1 [2017-12-01]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add an option to control the thickness of lines in box drawing characters
 
@@ -2561,7 +2986,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.5.0 [2017-11-19]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Add support for ligature fonts such as Fira Code, Hasklig, etc. kitty now
   uses harfbuzz for text shaping which allow it to support advanced OpenType
@@ -2595,7 +3020,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.4.2 [2017-10-23]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Fix a regression in 0.4.0 that broke custom key mappings
 
@@ -2606,7 +3031,7 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 
 
 0.4.0 [2017-10-22]
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 - Support for drawing arbitrary raster graphics (images) in the terminal via a
   new graphics protocol. kitty can draw images with full 32-bit color using both

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, Optional, Tuple
 
 from docutils import nodes
 from docutils.parsers.rst.roles import set_classes
@@ -21,14 +21,14 @@ from pygments.lexer import RegexLexer, bygroups  # type: ignore
 from pygments.token import (  # type: ignore
     Comment, Keyword, Literal, Name, Number, String, Whitespace
 )
-from sphinx import addnodes, version_info  # type: ignore
-from sphinx.util.logging import getLogger  # type: ignore
+from sphinx import addnodes, version_info
+from sphinx.util.logging import getLogger
 
 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 {{{
@@ -59,6 +59,7 @@ extensions = [
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
     'sphinx_copybutton',
     'sphinx_inline_tabs',
     "sphinxext.opengraph",
@@ -98,13 +99,10 @@ rst_prolog = '''
 .. |kitty| replace:: *kitty*
 .. |version| replace:: VERSION
 .. _tarball: https://github.com/kovidgoyal/kitty/releases/download/vVERSION/kitty-VERSION.tar.xz
-.. role:: green
 .. role:: italic
-.. role:: bold
-.. role:: cyan
-.. role:: title
 
 '''.replace('VERSION', str_version)
+smartquotes_action = 'qe'  # educate quotes and ellipses but not dashes
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -170,25 +168,16 @@ 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, List]:
-    ' 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(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+def commit_role(
+    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 commit '
     try:
         commit_id = subprocess.check_output(
@@ -228,7 +217,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 @'))
@@ -236,7 +226,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
@@ -245,12 +236,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='^'))
@@ -264,7 +255,7 @@ def write_remote_control_protocol_docs() -> None:  # {{{
     )
     field_pat = re.compile(r'\s*([a-zA-Z0-9_+]+)\s*:\s*(.+)')
 
-    def format_cmd(p: Callable, name: str, cmd: RemoteCommand) -> None:
+    def format_cmd(p: Callable[..., None], name: str, cmd: RemoteCommand) -> None:
         p(name)
         p('-' * 80)
         lines = (cmd.__doc__ or '').strip().splitlines()
@@ -304,7 +295,7 @@ def write_remote_control_protocol_docs() -> None:  # {{{
 
 # config file docs {{{
 
-class ConfLexer(RegexLexer):
+class ConfLexer(RegexLexer):  # type: ignore
     name = 'Conf'
     aliases = ['conf']
     filenames = ['*.conf']
@@ -343,7 +334,7 @@ class ConfLexer(RegexLexer):
     }
 
 
-class SessionLexer(RegexLexer):
+class SessionLexer(RegexLexer):  # type: ignore
     name = 'Session'
     aliases = ['session']
     filenames = ['*.session']
@@ -359,7 +350,9 @@ class SessionLexer(RegexLexer):
     }
 
 
-def link_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []) -> Tuple[List, List]:
+def link_role(
+    name: str, rawtext: str, text: str, lineno: int, inliner: Any, options: Any = {}, content: Any = []
+) -> Tuple[List[nodes.reference], List[nodes.problematic]]:
     text = text.replace('\n', ' ')
     m = re.match(r'(.+)\s+<(.+?)>', text)
     if m is None:
@@ -373,19 +366,6 @@ def link_role(name: str, rawtext: str, text: str, lineno: int, inliner: Any, opt
     return [node], []
 
 
-def expand_opt_references(conf_name: str, text: str) -> str:
-    conf_name += '.'
-
-    def expand(m: Match) -> 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]] = {}
 
@@ -408,7 +388,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
 
 
@@ -419,23 +399,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
@@ -464,6 +454,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)
@@ -514,7 +513,8 @@ def setup(app: Any) -> None:
     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
+    inline_tabs = app.extensions['sphinx_inline_tabs']
+    inline_tabs.parallel_read_safe = inline_tabs.parallel_write_safe = True

docs/conf.rst

@@ -7,10 +7,11 @@ kitty.conf
 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 open the config file within kitty by pressing :sc:`edit_config_file` (:kbd:`⌘+,` on macOS).
 You can reload the config file within kitty by pressing
-:sc:`reload_config_file` or sending kitty the ``SIGUSR1`` signal.  You can also
-display the current configuration by pressing the :sc:`debug_config` key.
+: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:
 
@@ -24,12 +25,14 @@ character. This works only if the ``#`` character is the first character
 in the line.
 
 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. For example::
 
      include other.conf
+     globinclude kitty.d/**/*.conf
 
 
 .. note:: Syntax highlighting for :file:`kitty.conf` in vim is available via

docs/deccara.rst

@@ -11,7 +11,7 @@ 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>`_
+: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*.
 

docs/faq.rst

@@ -6,21 +6,22 @@ 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?
@@ -51,6 +52,9 @@ type it each time::
 
     alias ssh="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::
@@ -124,9 +128,7 @@ to choose a new color theme. Simply run::
 
 And choose your theme from the list.
 
-Additionally, You can use the
-`OSC terminal escape codes <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands>`_
-to set colors or you can define keyboard shortcuts to set colors, for example::
+You can also define keyboard shortcuts to set colors, for example::
 
     map f1 set_colors --configured /path/to/some/config/file/colors.conf
 
@@ -134,10 +136,9 @@ Or you can enable :doc:`remote control <remote-control>` for |kitty| and use :re
 The shortcut mapping technique has the same syntax as the remote control
 command, for details, see :ref:`at_set-colors`.
 
-A list of pre-made color themes for kitty is available at:
-`kitty-themes <https://github.com/dexpota/kitty-themes>`_
-
-Examples of using OSC escape codes to set colors::
+Additionally, You can use the
+`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:
     printf '\x1b]10;#ff0000\x1b\\'
@@ -192,14 +193,23 @@ 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, so that every character needs to be rendered only once.
-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.
+|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.
 
-If your font is not listed in ``kitty list-fonts`` it means that it is not
+.. 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::
+
+        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
+
+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
@@ -227,7 +237,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?
@@ -236,7 +246,42 @@ 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!
+-------------------------------
+
+There are many alternate icons available, click on an icon to visit its
+homepage:
+
+.. image:: https://github.com/k0nserv/kitty-icon/raw/main/icon_512x512.png
+   :target: https://github.com/k0nserv/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/DinkDonk/kitty-icon/raw/main/kitty-dark.png
+   :target: https://github.com/DinkDonk/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/DinkDonk/kitty-icon/raw/main/kitty-light.png
+   :target: https://github.com/DinkDonk/kitty-icon
+   :width: 256
+
+.. image:: https://github.com/hristost/kitty-alternative-icon/raw/main/kitty_icon.png
+   :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`
+#. Drag :file:`kitty.icns` onto the application icon in the kitty info pane
+#. Delete the icon cache and restart Dock::
+
+    $ rm /var/folders/*/*/*/com.apple.dock.iconcache; killall Dock
 
 
 How do I map key presses in kitty to different keys in the terminal program?
@@ -260,7 +305,7 @@ How do I open a new window or tab with the same working directory as the current
 In :file:`kitty.conf` add the following::
 
     map f1 launch --cwd=current
-    map f2  launch --cwd=current --type=tab
+    map f2 launch --cwd=current --type=tab
 
 Pressing :kbd:`F1` will open a new kitty window with the same working directory
 as the current window. The :doc:`launch command <launch>` is very powerful,
@@ -297,8 +342,7 @@ 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
+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.
@@ -306,6 +350,9 @@ If you still want to use tmux, read on.
 Image display will not work, see `tmux issue
 <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`).
+
 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
@@ -352,3 +399,28 @@ 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
 to the OS immediately.
+
+Why does kitty sometimes start slowly on my Linux system?
+-------------------------------------------------------------------------------------------
+
+|kitty| takes no longer (within 100ms) to start than other similar GPU terminal
+emulators, (and may be faster than some). If |kitty| occasionally takes a long
+time to start, it could be a power management issue with the graphics card. On
+a multi-GPU system (which many modern laptops are, having a power efficient GPU
+that's built into the processor and a power hungry dedicated one that's usually
+off), even if the answer of the GPU will only be "don't use me".
+
+For example, if you have a system with an AMD CPU and an NVIDIA GPU, and you
+know that you want to use the lower powered card to save battery life and
+because kitty does not require a powerful GPU to function, you can choose not
+to wake up the dedicated card, which has been reported on at least one system
+(:iss:`4292`) to take ≈2 seconds, by running |kitty| as::
+
+    MESA_LOADER_DRIVER_OVERRIDE=radeonsi __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json kitty
+
+The correct command will depend on your situation and hardware.
+``__EGL_VENDOR_LIBRARY_FILENAMES`` instructs the GL dispatch library to use
+: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`.

docs/file-transfer-protocol.rst

@@ -0,0 +1,535 @@
+File transfer over the TTY
+===============================
+
+There are sometimes situations where the TTY is the only convenient pipe
+between two connected systems, for example, nested SSH sessions, a serial
+line, etc. In such scenarios, it is useful to be able to transfer files
+over the TTY.
+
+This protocol provides the ability to transfer regular files, directories and
+links (both symbolic and hard) preserving most of their metadata. It can
+optionally use compression and transmit only binary diffs to speed up
+transfers. However, since all data is base64 encoded for transmission over the
+TTY, this protocol will never be competitive with more direct file transfer
+mechanisms.
+
+Overall design
+----------------
+
+The basic design of this protocol is around transfer "sessions". Since
+untrusted software should not be able to read/write to another machines
+filesystem, a session must be approved by the user in the terminal emulator
+before any actual data is transmitted, unless a :ref:`pre-shared password is
+provided <bypass_auth>`.
+
+There can be either send or receive sessions. In send sessions files are sent
+from remote client to the terminal emulator and vice versa for receive sessions.
+Every session basically consists of sending metadata for the files first and
+then sending the actual data. The session is a series of commands, every command
+carrying the session id (which should be a random unique-ish identifier, to
+avoid conflicts). The session is bi-directional with commands going both to and
+from the terminal emulator. Every command in a session also carries an
+``action`` field that specifies what the command does. The remaining fields in
+the command are dependent on the nature of the command.
+
+Let's look at some simple examples of sessions to get a feel for the protocol.
+
+
+Sending files to the computer running the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The client starts by sending a start send command::
+
+    → action=send id=someid
+
+It then waits for a status message from the terminal either
+allowing the transfer or refusing it. Until this message is received
+the client is not allowed to send any more commands for the session.
+The terminal emulator should drop a session if it receives any commands
+before sending an ``OK`` response. If the user accepts the transfer,
+the terminal will send::
+
+    ← action=status id=someid status=OK
+
+Or if the transfer is refused::
+
+    ← action=status id=someid status=EPERM:User refused the transfer
+
+The client then sends one or more ``file`` commands with the metadata of the file it wants
+to transfer::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination
+    → action=file id=someid file_id=f2 name=/path/to/destination2 ftype=directory
+
+The terminal responds with either ``OK`` for directories or ``STARTED`` for
+files::
+
+    ← action=status id=someid file_id=f1 status=STARTED
+    ← action=status id=someid file_id=f2 status=OK
+
+If there was an error with the file, for example, if the terminal does not have
+permission to write to the specified location, it will instead respond with an
+error, such as::
+
+    ← action=status id=someid file_id=f1 status=EPERM:No permission
+
+The client sends data for files using ``data`` commands. It does not need to
+wait for the ``STARTED`` from the terminal for this, the terminal must discard data
+for files that are not ``STARTED``. Data for a file is sent in individual
+chunks of no larger than ``4096`` bytes. For example::
+
+
+    → action=data id=someid file_id=f1 data=chunk of bytes
+    → action=data id=someid file_id=f1 data=chunk of bytes
+    ...
+    → action=end_data id=someid file_id=f1 data=chunk of bytes
+
+The sequence of data transmission for a file is ended with an ``end_data``
+command. After each data packet is received the terminal replies with
+an acknowledgement of the form::
+
+    ← action=status id=someid file_id=f1 status=PROGRESS size=bytes written
+
+After ``end_data`` the terminal replies with::
+
+    ← action=status id=someid file_id=f1 status=OK size=bytes written
+
+If an error occurs while writing the data, the terminal replies with an error
+code and ignores further commands about that file, for example::
+
+    ← action=status id=someid file_id=f1 status=EIO:Failed to write to file
+
+Once the client has finished sending as many files as it wants to, it ends
+the session with::
+
+    → action=finish id=someid
+
+At this point the terminal commits the session, applying file metadata,
+creating links, etc. If any errors occur it responds with an error message,
+such as::
+
+    ← action=status id=someid status=Some error occurred
+
+
+Receiving files from the computer running terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The client starts by sending a start receive command::
+
+    → action=receive id=someid size=num_of_paths
+
+It then sends a list of ``num_of_paths`` paths it is interested in
+receiving::
+
+    → action=file id=someid file_id=f1 name=/some/path
+    → action=file id=someid file_id=f2 name=/some/path2
+    ...
+
+The client must then wait for responses from the terminal emulator. It
+is an error to send anymore commands to to the terminal until an ``OK``
+response is received from the terminal. The terminal wait for the user to accept
+the request. If accepted, it sends::
+
+    ← action=status id=someid status=OK
+
+If permission is denied it sends::
+
+    ← action=status id=someid status=EPERM:User refused the transfer
+
+The terminal then sends the metadata for all requested files. If any of them
+are directories, it traverses the directories recursively, listing all files.
+Note that symlinks must not be followed, but sent as symlinks::
+
+    ← action=file id=someid file_id=f1 mtime=XXX permissions=XXX name=/absolute/path status=file_id1 size=size_in_bytes file_type=type parent=file_id of parent
+    ← action=file id=someid file_id=f1 mtime=XXX permissions=XXX name=/absolute/path2 status=file_id2 size=size_in_bytes file_type=type parent=file_id of parent
+    ...
+
+Here the ``file_id`` field is set to the ``file_id`` value sent from the client
+and the ``status`` field is set to the actual file id for each file. This is
+because a file query sent from the client can result in multiple actual files if
+it is a directory. The ``parent`` field is the actual ``file_id`` of the directory
+containing this file and is set for entries that are generated from client
+requests that match directories. This allows the client to build an unambiguous picture
+of the file tree.
+
+Once all the files are listed, the terminal sends an ``OK`` response that also
+specifies the absolute path to the home directory for the user account running
+the terminal::
+
+    ← action=status id=someid status=OK name=/path/to/home
+
+If an error occurs while listing any of the files asked for by the client,
+the terminal will send an error response like::
+
+    ← action=status id=someid file_id=f1 status=ENOENT: Does not exist
+
+Here, ``file_id`` is the same as was sent by the client in its initial query.
+
+Now, the client can send requests for file data using the paths sent by the
+terminal emulator::
+
+    → action=file id=someid file_id=f1 name=/some/path
+    ...
+
+The terminal emulator replies with the data for the files, as a sequence of
+``data`` commands each with a chunk of data no larger than ``4096`` bytes,
+for each file (the terminal emulator should send the data for
+one file at a time)::
+
+
+    ← action=data id=someid file_id=f1 data=chunk of bytes
+    ...
+    ← action=end_data id=someid file_id=f1 data=chunk of bytes
+
+If any errors occur reading file data, the terminal emulator sends an error
+message for the file, for example::
+
+    ← action=status id=someid file_id=f1 status=EIO:Could not read
+
+Once the client is done reading data for all the files it expects, it
+terminates the session with::
+
+    → action=finished id=someid
+
+Canceling a session
+----------------------
+
+A client can decide to cancel a session at any time (for example if the user
+presses :kbd:`ctrl+c`). To cancel a session it sends a ``cancel`` action to the
+terminal emulator::
+
+    → action=cancel id=someid
+
+The terminal emulator drops the session and sends a cancel acknowledgement::
+
+    ← action=status id=someid status=CANCELED
+
+The client **must** wait for the canceled response from the emulator discarding
+any other responses till the cancel is received. If it does not wait, after
+it quits the responses might end up being printed to screen.
+
+Quieting responses from the terminal
+-------------------------------------
+
+The above protocol includes lots of messages from the terminal acknowledging
+receipt of data, granting permission etc., acknowledging cancel requests, etc.
+For extremely simple clients like shell scripts, it might be useful to suppress
+these responses, which can be done by adding the ``quiet`` key to the start
+session command::
+
+    → action=send id=someid quiet=1
+
+The key can take the values ``1`` - meaning suppress acknowledgement responses
+or ``2`` - meaning suppress all responses including errors. Only actual data
+responses are sent. Note that in particular this means acknowledgement of
+permission for the transfer to go ahead is suppressed, so this is typically
+useful only with :ref:`bypass_auth`.
+
+.. _file_metadata:
+
+File metadata
+-----------------
+
+File metadata includes file paths, permissions and modification times. They are
+somewhat tricky as different operating systems support different kinds of
+metadata. This specification defines a common minimum set which should work
+across most operating systems.
+
+File paths
+    File paths must be valid UTF-8 encoded POSIX paths (i.e. using the forward slash
+    ``/`` as a separator). Linux systems allow non UTF-8 file paths, these
+    are not supported. A leading ``~/`` means a path is relative to the
+    ``HOME`` directory. All path must be either absolute (i.e. with a leading
+    ``/``) or relative to the HOME directory. Individual components of the
+    path must be no longer than 255 UTF-8 bytes. Total path length must be no
+    more than 4096 bytes. Paths from Windows systems must use the forward slash
+    as the separator, the first path component must be the drive letter with a
+    colon. For example: :file:`C:\some\file.txt` is represented as
+    :file:`/C:/some/file.txt`. For maximum portability, the following
+    characters *should* be omitted from paths (however implementations are free
+    to try to support them returning errors for non-representable paths)::
+
+        \ * : < > ? | /
+
+File modification times
+    Must be represented as the number of nanoseconds since the UNIX epoch. An
+    individual file system may not store file metadata with this level of
+    accuracy in which case it should use the closest possible approximation.
+
+File permissions
+    Represented as a number with the usual UNIX read, write and execute bits.
+    In addition, the sticky, set-group-id and set-user-id bits may be present.
+    Implementations should make a best effort to preserve as many bits as
+    possible. On Windows, there is only a read-only bit. When reading file
+    metadata all the ``WRITE`` bits should be set if the read only bit is clear
+    and cleared if it is set. When writing files, the read-only bit should be
+    set if the bit indicating write permission for the user is clear. The other
+    UNIX bits must be ignored when writing. When reading, all the ``READ`` bits
+    should always be set and all the ``EXECUTE`` bits should be set if the file is
+    directly executable by the Windows Operating system. There is no attempt to
+    map Window's ACLs to permission bits.
+
+
+Symbolic and hard links
+---------------------------
+
+Symbolic and hard links can be preserved by this protocol.
+
+.. note::
+   In the following when target paths of symlinks are sent as actual paths, they must be
+   encoded in the same way as discussed in :ref:`file_metadata`. It is up to
+   the receiving side to translate them into appropriate paths for the local
+   operating system. This may not always be possible, in which case either the
+   symlink should not be created or a broken symlink should be created.
+
+
+Sending links to the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When sending files to the terminal emulator, the file command has the form::
+
+    → action=file id=someid file_id=f1 name=/path/to/link file_type=link
+    → action=file id=someid file_id=f2 name=/path/to/symlink file_type=symlink
+
+Then, when the client is sending data for the files, for hardlinks, the data
+will be the ``file_id`` of the target file (assuming the target file is also
+being transmitted, otherwise the hard link should be transmitted as a plain
+file)::
+
+    → action=end_data id=someid file_id=f1 data=target_file_id_encoded_as_utf8
+
+For symbolic links, the data is a little more complex. If the symbolic link is
+to a destination being transmitted, the data has the form::
+
+    → action=end_data id=someid file_id=f1 data=fid:target_file_id_encoded_as_utf8
+    → action=end_data id=someid file_id=f1 data=fid_abs:target_file_id_encoded_as_utf8
+
+The ``fid_abs`` form is used if the symlink uses an absolute path, ``fid`` if
+it uses a relative path. If the symlink is to a destination that is not being
+transmitted, then the prefix ``path:`` and the actual path in the symlink is
+transmitted.
+
+Receiving links from the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When receiving files from the terminal emulator, link data is transmitted in
+two parts. First when the emulator sends the initial file listing to the
+client, the ``file_type`` is set to the link type and the ``data`` field is set
+to file_id of the target file if the target file is included in the listing.
+For example::
+
+    ← action=file id=someid file_id=f1 status=file_id1 ...
+    ← action=file id=someid file_id=f1 status=file_id2 file_type=symlink data=file_id1 ...
+
+Here the rest of the metadata has been left out for clarity. Notice that the
+second file is symlink whose ``data`` field is set to the file id of the first
+file (the value of the ``status`` field of the first file). The same technique
+is used for hard links.
+
+The client should not request data for hard links, instead creating them
+directly after transmission is complete. For symbolic links the terminal
+must send the actual symbolic link target as a UTF-8 encoded path in the
+data field. The client can use this path either as-is (when the target is not
+a transmitted file) or to decide whether to create the symlink with a relative
+or absolute path when the target is a transmitted file.
+
+
+Transmitting binary deltas
+-----------------------------
+
+Repeated transfer of large files that have only changed a little between
+the receiving and sending side can be sped up significantly by transmitting
+binary deltas of only the changed portions. This protocol has built-in support
+for doing that. This support uses the `rsync algorithm
+<https://github.com/librsync/librsync>`__. In this algorithm first the
+receiving side sends a file signature that contains hashes of blocks
+in the file. Then the sending side sends only those blocks that have changed.
+The receiving side applies these deltas to the file to update it till it matches
+the file on the sending side.
+
+The modification to the basic protocol consists of setting the
+``transmission_type`` key to ``rsync`` when requesting a file. This triggers
+transmission of signatures and deltas instead of file data. The details are
+different for sending and receiving.
+
+Sending to the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When sending the metadata of the file it wants to transfer, the client adds the
+``transmission_type`` key::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination transmission_type=rsync
+
+The ``STARTED`` response from the terminal will have ``transmission_type`` set
+to ``rsync`` if the file exists and the terminal is able to send signature data::
+
+    ← action=status id=someid file_id=f1 status=STARTED transmission_type=rsync
+
+The terminal then transmits the signature using ``data`` commands::
+
+    ← action=data id=someid file_id=f1 data=...
+    ...
+    ← action=end_data id=someid file_id=f1 data=...
+
+Once the client receives and processes the full signature, it transmits the
+file delta to the terminal as ``data`` commands::
+
+    → action=data id=someid file_id=f1 data=...
+    → action=data id=someid file_id=f1 data=...
+    ...
+    → action=end_data id=someid file_id=f1 data=...
+
+The terminal then uses this delta to update the file.
+
+Receiving from the terminal emulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the client requests file data from the terminal emulator, it can
+add the ``transmission_type=rsync`` key to indicate it will be sending
+a signature for that file::
+
+    → action=file id=someid file_id=f1 name=/some/path transmission_type=rsync
+
+The client then sends the signature using ``data`` commands::
+
+    → action=data id=someid file_id=f1 data=...
+    ...
+    → action=end_data id=someid file_id=f1 data=...
+
+After receiving the signature the terminal replies with the delta as a series
+of ``data`` commands::
+
+    ← action=data id=someid file_id=f1 data=...
+    ...
+    ← action=end_data id=someid file_id=f1 data=...
+
+The client then uses this delta to update the file.
+
+The format of signatures and deltas
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These come from `librsync <https://github.com/librsync/librsync>`__. If this
+specification gains wider adoption, these formats should be documented here.
+
+Compression
+--------------
+
+Individual files can be transmitted compressed if needed.
+Currently, only :rfc:`1950` ZLIB based deflate compression is
+supported, which is specified using the ``compression=zlib`` key when
+requesting a file. For example when sending files to the terminal emulator,
+when sending the file metadata the ``compression`` key can also be
+specified::
+
+    → action=file id=someid file_id=f1 name=/path/to/destination compression=zlib
+
+Similarly when receiving files from the terminal emulator, the final file
+command that the client sends to the terminal requesting the start of the
+transfer of data for the file can include the ``compression`` key::
+
+    → action=file id=someid file_id=f1 name=/some/path compression=zlib
+
+.. _bypass_auth:
+
+Bypassing explicit user authorization
+------------------------------------------
+
+In order to bypass the requirement of interactive user authentication,
+this protocol has the ability to use a pre-shared secret (password).
+When initiating a transfer session the client sends a hash of the password and
+the session id::
+
+    → action=send id=someid bypass=sha256:hash_value
+
+For example, suppose that the session id is ``mysession`` and the
+shared secret is ``mypassword``. Then the value of the ``bypass``
+key above is ``sha256:SHA256("mysession" + ";" + "mypassword")``, which
+is::
+
+    → action=send id=mysession bypass=sha256:192bd215915eeaa8c2b2a4c0f8f851826497d12b30036d8b5b1b4fc4411caf2c
+
+The value of ``bypass`` is of the form ``hash_function_name : hash_value``
+(without spaces). Currently, only the SHA256 hash function is supported.
+
+.. warning::
+   Hashing does not effectively hide the value of the password. So this
+   functionality should only be used in secure/trusted contexts. While there
+   exist hash functions harder to compute than SHA256, they are unsuitable as
+   they will introduce a lot of latency to starting a session and in any case
+   there is no mathematical proof that **any** hash function is not brute-forceable.
+
+Encoding of transfer commands as escape codes
+------------------------------------------------
+
+Transfer commands are encoded as ``OSC`` escape codes of the form::
+
+    <OSC> 5113 ; key=value ; key=value ... <ST>
+
+Here ``OSC`` is the bytes ``0x1b 0x5d`` and ``ST`` is the bytes
+``0x1b 0x5c``. Keys are words containing only the characters ``[a-zA-Z0-9_]``
+and ``value`` is arbitrary data, whose encoding is dependent on the value of
+``key``. Unknown keys **must** be ignored when decoding a command.
+The number ``5113`` is a constant and is unused by any known OSC codes. It is
+the numeralization of the word ``file``.
+
+
+.. table:: The keys and value types for this protocol
+    :align: left
+
+    ================= ======== ============== =======================================================================
+    Key               Key name Value type     Notes
+    ================= ======== ============== =======================================================================
+    action            ac       enum           send, file, data, end_data, receive, cancel, status, finish
+    compression       zip      enum           none, zlib
+    file_type         ft       enum           regular, directory, symlink, link
+    transmission_type tt       enum           simple, rsync
+    id                id       safe_string    A unique-ish value, to avoid collisions
+    file_id           fid      safe_string    Must be unique per file in a session
+    bypass            pw       safe_string    hash of the bypass password and the session id
+    quiet             q        integer        0 - verbose, 1 - only errors, 2 - totally silent
+    mtime             mod      integer        the modification time of file in nanoseconds since the UNIX epoch
+    permissions       prm      integer        the UNIX file permissions bits
+    size              sz       integer        size in bytes
+    name              n        base64_string  The path to a file
+    status            st       base64_string  Status messages
+    parent            pr       safe_string    The file id of the parent directory
+    data              d        base64_bytes   Binary data
+    ================= ======== ============== =======================================================================
+
+The ``Key name`` is the actual serialized name of the key sent in the escape
+code. So for example, ``permissions=123`` is serialized as ``prm=123``. This
+is done to reduce overhead.
+
+The value types are:
+
+enum
+    One from a permitted set of values, for example::
+
+        ac=file
+
+safe_string
+    A string consisting only of characters from the set ``[0-9a-zA-Z_:.,/!@#$%^&*()[]{}~`?"'\\|=+-]``
+    Note that the semi-colon is missing from this set.
+
+integer
+    A base-10 number composed of the characters ``[0-9]`` with a possible
+    leading ``-`` sign
+
+base64_string
+    A base64 encoded UTF-8 string using the standard base64 encoding
+
+base64_bytes
+    Binary data encoded using the standard base64 encoding
+
+
+An example of serializing an escape code is shown below::
+
+    action=send id=test name=somefile size=3 data=01 02 03
+
+becomes::
+
+    <OSC> 5113 ; ac=send ; id=test ; n=c29tZWZpbGU= ; sz=3 ; d=AQID <ST>
+
+Here ``c29tZWZpbGU`` is the base64 encoded form of somefile and ``AQID`` is the
+base64 encoded form of the bytes ``0x01 0x02 0x03``. The spaces in the encoded
+form are present for clarity and should be ignored.

docs/glossary.rst

@@ -32,7 +32,7 @@ Glossary
       top of an existing kitty window, entirely covering it. Overlays are used
       throught kitty, for example, to display the :ref:`the scrollback buffer <scrollback>`,
       to display :doc:`hints </kittens/hints>`, for :doc:`unicode input
-      </kittens/unicode-input>` etc.
+      </kittens/unicode_input>` etc.
 
    hyperlinks
       Terminals can have hyperlinks, just like the internet. In kitty you can
@@ -52,6 +52,10 @@ Variables that influence kitty behavior
    files. Defaults to :file:`~/.config/kitty`. For full details of the config
    directory lookup mechanism see, :option:`kitty --config`.
 
+.. envvar:: KITTY_CACHE_DIRECTORY
+
+   Controls where kitty stores cache files. Defaults to :file:`~/.cache/kitty`
+   or :file:`~/Library/Caches/kitty` on macOS.
 
 .. envvar:: VISUAL
 
@@ -63,6 +67,17 @@ Variables that influence kitty behavior
 
    Same as :envvar:`VISUAL`. Used if :envvar:`VISUAL` is not set.
 
+.. envvar:: GLFW_IM_MODULE
+
+   Set this to ``ibus`` to enable support for IME under X11.
+
+.. envvar:: KITTY_WAYLAND_DETECT_MODIFIERS
+
+   When set to a non-empty value, kitty attempts to autodiscover XKB modifiers
+   under Wayland. This is useful if using non-standard modifers like hyper. It
+   is possible for the autodiscovery to fail; the default Wayland XKB mappings
+   are used in this case. See :pull:`3943` for details.
+
 
 Variables that kitty sets when running child programs
 
@@ -101,6 +116,11 @@ Variables that kitty sets when running child programs
    Path to a directory containing the kitty terminfo database.
 
 
+.. envvar:: KITTY_INSTALLATION_DIR
+
+   Path to the kitty installation directory.
+
+
 .. envvar:: COLORTERM
 
    Set to the value ``truecolor`` to indicate that kitty supports 16 million
@@ -133,3 +153,9 @@ Variables that kitty sets when running child programs
 
    Set with the values of some common kitty options when running
    kittens, so kittens can use them without needing to load kitty.conf.
+
+
+.. envvar:: KITTY_SHELL_INTEGRATION
+
+   Set when enabling :ref:`shell_integration`. It is automatically removed by
+   the shell integration scripts.

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::
 
@@ -40,7 +39,14 @@ Some programs and libraries that use the kitty graphics protocol:
 * `ctx.graphics <https://ctx.graphics/>`_ - Library for drawing graphics
 * `timg <https://github.com/hzeller/timg>`_ - a terminal image and video viewer
 * `notcurses <https://github.com/dankamongmen/notcurses>`_ - C library for terminal graphics with bindings for C++, Rust and Python
-* `rasterm <https://github.com/BourgeoisBear/rasterm>`_  - Go library to display images in the the terminal
+* `rasterm <https://github.com/BourgeoisBear/rasterm>`_  - Go library to display images in the terminal
+* `chafa <https://github.com/hpjansson/chafa>`_  - a terminal image viewer
+* `hologram.nvim <https://github.com/edluffy/hologram.nvim>`_  - view images inside nvim
+
+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>`_
 
 
 Getting the window size
@@ -103,7 +109,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'))
@@ -223,7 +229,7 @@ and can take the values:
 Value of `t`          Meaning
 ==================    ============
 ``d``                 Direct (the data is transmitted within the escape code itself)
-``f``                 A simple file
+``f``                 A simple file (regular files only, not named pipes or similar)
 ``t``                 A temporary file, the terminal emulator will delete the file after reading the pixel data. For security reasons
                       the terminal emulator should only delete the file if it
                       is in a known temporary directory, such as :file:`/tmp`,
@@ -238,6 +244,10 @@ Value of `t`          Meaning
                       close it on Windows.
 ==================    ============
 
+When opening files, the terminal emulator must follow symlinks. In case of
+symlink loops or too many symlinks, it should fail and respond with an error,
+similar to reporting any other kind of I/O error.
+
 Local client
 ^^^^^^^^^^^^^^
 
@@ -316,9 +326,9 @@ 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.
 
-While as of May 2020, kitty is the only terminal emulator to support this
-graphics protocol, we intend that any terminal emulator that wishes to support
-it can. To check if a terminal emulator supports the graphics protocol the best way
+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

docs/index.rst

@@ -14,12 +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
+   * Uses threaded rendering for :iss:`absolutely minimal latency <2701#issuecomment-636497270>`
    * Performance tradeoffs can be :ref:`tuned <conf-kitty-performance>`
 
 .. tab:: Capable
@@ -36,8 +37,9 @@ kitty
 
 .. tab:: Composable
 
-   * Programmble tabs, :ref:`splits <splits_layout>` and multiple :doc:`layouts <layouts>` to manage windows
-   * Browse the :ref:`entire history <scrollback>` or the output from the last command comfortably in pagers and editors
+   * Programmable tabs, :ref:`splits <splits_layout>` and multiple :doc:`layouts <layouts>` to manage windows
+   * Browse the :ref:`entire history <scrollback>` or the :sc:`output from the last command <show_last_command_output>`
+     comfortably in pagers and editors
    * Edit or download :doc:`remote files <kittens/remote_file>` in an existing SSH session
 
 .. tab:: Cross-platform
@@ -55,12 +57,18 @@ kitty
    * Lots more in :doc:`protocol-extensions`
 
 
-.. figure:: screenshots/screenshot.png
-    :alt: Screenshot, showing three programs in the 'Tall' layout
-    :align: center
-    :width: 100%
+.. only:: dirhtml
 
-    Screenshot, showing vim, tig and git running in |kitty| with the 'Tall' layout
+    .. raw:: html
+
+        <video controls width="640" height="360" poster="_static/poster.png">
+            <source src="https://download.calibre-ebook.com/videos/kitty.mp4" type="video/mp4">
+            <source src="https://download.calibre-ebook.com/videos/kitty.webm" type="video/webm">
+        </video>
+
+    .. rst-class:: caption caption-text
+
+        Watch kitty in action!
 
 
 To get started see :doc:`quickstart`.

docs/installer.py

@@ -20,10 +20,16 @@ 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__
@@ -73,9 +79,11 @@ class Reporter:  # {{{
 # }}}
 
 
-def get_latest_release_data():
+def get_release_data(relname='latest'):
     print('Checking for latest release on GitHub...')
-    req = urllib.Request('https://api.github.com/repos/kovidgoyal/kitty/releases/latest', headers={'Accept': 'application/vnd.github.v3+json'})
+    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:
@@ -90,7 +98,8 @@ def get_latest_release_data():
         else:
             if name.endswith('.txz'):
                 if is64bit:
-                    if name.endswith('-x86_64.txz'):
+                    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'):
@@ -184,19 +193,22 @@ def main(dest=None, launch=True, installer=None):
             dest = '/Applications'
         else:
             dest = os.path.expanduser('~/.local')
-    machine = os.uname()[4]
-    if machine and machine.lower().startswith('arm'):
+    if is_linux_arm and not is_linux_arm64:
         raise SystemExit(
-            'You are running on an ARM system. The kitty binaries are only'
-            ' available for x86 systems. You will have to build from'
+            '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_latest_release_data()
+        url, size = get_release_data()
         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 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:
@@ -227,7 +239,7 @@ def script_launch():
     main(**kwargs)
 
 
-def update_intaller_wrapper():
+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')
@@ -244,6 +256,6 @@ def update_intaller_wrapper():
 if __name__ == '__main__' and from_file:
     main()
 elif __name__ == 'update_wrapper':
-    update_intaller_wrapper()
+    update_installer_wrapper()
 elif __name__ == 'script_launch':
     script_launch()

docs/installer.sh

@@ -25,6 +25,268 @@ echo Using python executable: $python
 $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
+
+
+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()
+
 # HEREDOC_END
 # }}}
 INSTALLER_HEREDOC

docs/keyboard-protocol.rst

@@ -32,6 +32,13 @@ You can see this protocol with all enhancements in action by running::
 
 inside the kitty terminal to report key events.
 
+In addition to kitty, this protocol is also implemented in:
+
+* The `foot terminal <https://codeberg.org/dnkl/foot/issues/319>`__
+* The `notcurses library
+  <https://github.com/dankamongmen/notcurses/issues/2131>`__
+* The `kakoune text editor <https://github.com/mawww/kakoune/issues/4103>`__
+
 .. versionadded:: 0.20.0
 
 Quickstart
@@ -66,10 +73,11 @@ key, such as ``97`` for the :kbd:`a` key, or one of the numbers from the
 modifiers pressed for the key event. The encoding is described in the
 :ref:`modifiers` section.
 
-The second form is used for a few functional keys, such as the :kbd:`Home, End,
-Arrow keys and F1-F4`, they are enumerated in the :ref:`functional` table below.
-Note that if no modifiers are present the parameters are omitted entirely
-giving an escape code of the form ``CSI [ABCDEFHPQRS]``.
+The second form is used for a few functional keys, such as the :kbd:`Home`,
+:kbd:`End`, :kbd:`Arrow` keys and :kbd:`F1` ... :kbd:`F4`, they are enumerated in
+the :ref:`functional` table below.  Note that if no modifiers are present the
+parameters are omitted entirely giving an escape code of the form ``CSI
+[ABCDEFHPQRS]``.
 
 If you want support for more advanced features such as repeat and release
 events, alternate keys for shortcut matching et cetera, these can be turned on
@@ -142,11 +150,13 @@ sub-field for the shifted key, like this::
 Modifiers
 ~~~~~~~~~~~~~~
 
-This protocol supports six modifier keys, :kbd:`shift, alt, ctrl, super, hyper
-and meta` as well as :kbd:`num_lock and caps_lock`. Here :kbd:`super` is either
-the *Windows/Linux* key or the *Cmd* key on mac keyboards. :kbd:`hyper` and
-:kbd:`meta` are typically present only on X11 based systems with special XKB
-rules. Modifiers are encoded as a bit field with::
+This protocol supports six modifier keys, :kbd:`shift`, :kbd:`alt`,
+:kbd:`ctrl`, :kbd:`super`, :kbd:`hyper`, :kbd:`meta`, :kbd:`num_lock` and
+:kbd:`caps_lock`. Here :kbd:`super` is either the *Windows/Linux* key or the
+:kbd:`command` key on mac keyboards. The :kbd:`alt` key is the :kbd:`option`
+key on mac keyboards. :kbd:`hyper` and :kbd:`meta` are typically present only
+on X11/Wayland based systems with special XKB rules. Modifiers are encoded as a
+bit field with::
 
     shift     0b1         (1)
     alt       0b10        (2)
@@ -209,9 +219,9 @@ Non-Unicode keys
 
 There are many keys that don't correspond to letters from human languages, and
 thus aren't represented in Unicode. Think of functional keys, such as
-:kbd:`Escape, Play, Pause, F1, Home, etc`. These are encoded using Unicode code
-points from the Private Use Area (``57344 - 63743``). The mapping of key
-names to code points for these keys is in the
+:kbd:`Escape`, :kbd:`Play`, :kbd:`Pause`, :kbd:`F1`, :kbd:`Home`, etc. These
+are encoded using Unicode code points from the Private Use Area (``57344 -
+63743``). The mapping of key names to code points for these keys is in the
 :ref:`Functional key definition table below <functional>`.
 
 
@@ -277,11 +287,6 @@ oldest entry from the stack must be evicted.
    the editor would have to somehow know what the keyboard mode of the main
    screen is and restore to that mode on exit.
 
-.. note:: In the interests of interoperation, the XTerm specific sequences
-   `CSI > 4; 1 m` and `CSI > 4; 0 m` are treated as `CSI > 1 u` and `CSI < 1 u`.
-   These codes cause XTerm to use the CSI u encoding for more keys and are therefore
-   treated as similar to the disambiguate progressive enhancement.
-
 .. _disambiguate:
 
 Disambiguate escape codes
@@ -293,8 +298,8 @@ encodings overlapping with other control codes. For instance, pressing the
 start of an escape code. Similarly pressing the key :kbd:`alt+[` will generate
 the bytes used for CSI control codes.
 
-Turning on this flag will cause the terminal to report the :kbd:`Esc, alt+key,
-ctrl+key, ctrl+alt+key, shift+alt+key` keys using ``CSI u`` sequences instead
+Turning on this flag will cause the terminal to report the :kbd:`Esc`, :kbd:`alt+key`,
+:kbd:`ctrl+key`, :kbd:`ctrl+alt+key`, :kbd:`shift+alt+key` keys using ``CSI u`` sequences instead
 of legacy ones. Here key is any ASCII key as described in :ref:`legacy_text`.
 Additionally, all keypad keys will be reported as separate keys with ``CSI u``
 encoding, using dedicated numbers from the :ref:`table below <functional>`.
@@ -309,7 +314,7 @@ This makes it very easy to parse key events in an application. In particular,
 :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
 delivered as a ``CSI u`` escape code. This has the nice side effect of making it
 much easier to integrate into the application event loop. The only exceptions
-are the :kbd:`Enter, Tab and Backspace` keys which still generate the same
+are the :kbd:`Enter`, :kbd:`Tab` and :kbd:`Backspace` keys which still generate the same
 bytes as in legacy mode this is to allow the user to type and execute commands
 in the shell such as ``reset`` after a program that sets this mode crashes
 without clearing it.
@@ -349,8 +354,8 @@ only key events are sent. If the text is needed as well, combine with the
 Report associated text enhancement below.
 
 Additionally, with this mode, events for pressing modifier keys are reported.
-Note that *all* keys are reported as escape codes, including :kbd:`Enter, Tab,
-Backspace` etc.
+Note that *all* keys are reported as escape codes, including :kbd:`Enter`,
+:kbd:`Tab`, :kbd:`Backspace` etc.
 
 .. _report_text:
 
@@ -436,6 +441,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
@@ -462,10 +468,11 @@ distinguish these, use the :ref:`disambiguate <disambiguate>` flag.
 Legacy text keys
 ~~~~~~~~~~~~~~~~~~~
 
-For legacy compatibility, the keys
-:kbd:`a-z 0-9 \` - = [ ] \ ; ' , . /` with the modifiers
-:kbd:`shift, alt, ctrl, shift+alt, ctrl+alt` are output using the
-following algorithm:
+For legacy compatibility, the keys :kbd:`a`-:kbd:`z` :kbd:`0`-:kbd:`9`
+:kbd:`\`` :kbd:`-` :kbd:`=` :kbd:`[` :kbd:`]` :kbd:`\\` :kbd:`;` :kbd:`'`
+:kbd:`,` :kbd:`.` :kbd:`/` with the modifiers :kbd:`shift`, :kbd:`alt`,
+:kbd:`ctrl`, :kbd:`shift+alt`, :kbd:`ctrl+alt` are output using the following
+algorithm:
 
 #. If the :kbd:`alt` key is pressed output the byte for ``ESC (0x1b)``
 #. If the :kbd:`ctrl` modifier is pressed map the key using the table
@@ -637,8 +644,8 @@ specification.
 * Incorrectly encoding shifted keys when shift modifier is used, for instance,
   for :kbd:`ctrl+shift+i` is encoded as :kbd:`ctrl+I`.
 
-* No way to have non-conflicting escape codes for :kbd:`alt+letter,
-  ctrl+letter, ctrl+alt+letter` key presses
+* No way to have non-conflicting escape codes for :kbd:`alt+letter`,
+  :kbd:`ctrl+letter`, :kbd:`ctrl+alt+letter` key presses
 
 * No way to specify both shifted and unshifted keys for robust shortcut
   matching (think matching :kbd:`ctrl+shift+equal` and :kbd:`ctrl+plus`)

docs/kittens/custom.rst

@@ -88,11 +88,41 @@ function, telling kitty what kind of input your kitten would like. For example:
 
 
 This will send the plain text of the active window to the kitten's
-:file:`STDIN`. For text with formatting escape codes, use ``ansi``
-instead. If you want line wrap markers as well, use ``screen-ansi``
-or just ``screen``. For the scrollback buffer as well, use
-``history``, ``ansi-history`` or ``screen-history``. To get
-the currently selected text, use ``selection``.
+: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
+
+    =========================== =======================================================================================================
+    Keyword                     Type of :file:`STDIN` input
+    =========================== =======================================================================================================
+    ``text``                    Plain text of active window
+    ``ansi``                    Formatted text of active window
+    ``screen``                  Plain text of active window with line wrap markers
+    ``screen-ansi``             Formatted text of active window with line wrap markers
+
+    ``history``                 Plain text of active window and its scrollback
+    ``ansi-history``            Formatted text of active window and its scrollback
+    ``screen-history``          Plain text of active window and its scrollback with line wrap markers
+    ``screen-ansi-history``     Formatted text of active window and its scrollback with line wrap markers
+
+    ``output``                  Plain text of the output from the last run command
+    ``output-screen``           Plain text of the output from the last run command with wrap markers
+    ``output-ansi``             Formatted text of the output from the last run command
+    ``output-screen-ansi``      Formatted text of the output from the last run command with wrap markers
+
+    ``selection``               The text currently selected with the mouse
+    =========================== =======================================================================================================
+
+In addition to ``output``, that gets the output of the last run command,
+``last_visited_output`` gives the output of the command last jumped to
+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.
 
 
 Using kittens to script kitty, without any terminal UI
@@ -104,7 +134,7 @@ terminal program, you can tell the kittens system to run the
 
 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.
+equivalent to the builtin :ac:`toggle_layout` action.
 
 Create a file in the kitty config folder, :file:`~/.config/kitty/zoom_toggle.py`
 
@@ -295,7 +325,7 @@ Kittens created by kitty users
 `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

@@ -35,7 +35,7 @@ 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 macOS kitty app).
+included in the official kitty binary builds).
 
 
 Usage
@@ -67,14 +67,14 @@ Keyboard controls
 =========================   ===========================
 Action                      Shortcut
 =========================   ===========================
-Quit                        :kbd:`q, Ctrl+c, Esc`
-Scroll line up              :kbd:`k, up`
-Scroll line down            :kbd:`j, 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, PgDn`
+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`
@@ -85,8 +85,8 @@ Restore default context     :kbd:`=`
 Search forwards             :kbd:`/`
 Search backwards            :kbd:`?`
 Clear search                :kbd:`Esc`
-Scroll to next match        :kbd:`>, .`
-Scroll to previous match    :kbd:`<, ,`
+Scroll to next match        :kbd:`>`, :kbd:`.`
+Scroll to previous match    :kbd:`<`, :kbd:`,`
 =========================   ===========================
 
 

docs/kittens/hints.rst

@@ -33,10 +33,16 @@ 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>`.
 
+.. 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
 create mappings in :file:`kitty.conf` to select various different text
-snippets. See :sc:`insert_selected_path` for examples.
+snippets. See :sc:`insert_selected_path <insert_selected_path>` for examples.
 
 
 Completely customizing the matching and actions of the kitten
@@ -93,7 +99,8 @@ 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:`kitten_alias` option in :file:`kitty.conf`, creating aliases
+    you can use the :opt:`action_alias` option in :file:`kitty.conf`, creating aliases
     that have common sets of options. For example::
 
-        kitten_alias myhints hints --alphabet qfjdkslaureitywovmcxzpq1234567890
+        action_alias myhints kitten hints --alphabet qfjdkslaureitywovmcxzpq1234567890
+        map f1 myhints --customize-processing custom-hints.py

docs/kittens/hyperlinked_grep.rst

@@ -3,7 +3,7 @@ Hyperlinked grep
 
 
 This kitten allows you to search your files using `ripgrep
-<https://www.google.com/search?q=ripgrep>`_ and open the results
+<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.
 
@@ -45,17 +45,31 @@ 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 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
+    :file:`hg` somewhere in your ``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 rg's autocompletion with a fish "wrapper" function in your :file:`config.fish`:
+
+    .. code-block:: sh
+
+        function hg --wraps rg; kitty +kitten hyperlinked_grep $argv; end
 
 To learn more about kitty's powerful framework for customizing URL click
 actions, :doc:`see here </open_actions>`.

docs/kittens/icat.rst

@@ -35,6 +35,18 @@ Then you can simply use ``icat image.png`` to view images.
 
 The ``icat`` kitten has various command line arguments to allow it to be used
 from inside other programs to display images. In particular, :option:`--place`,
-:option:`--detect-support` 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:`../graphics-protocol` in the program instead.  Nowadays there are many
+libraries that have support for it.
+
 
 .. include:: /generated/cli-kitten-icat.rst

docs/kittens/remote_file.rst

@@ -22,12 +22,15 @@ transferred to the remote computer. Note that this happens without needing
 to install *any* special software on the server, beyond ``ls`` that supports
 hyperlinks.
 
+.. 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
-   |kitty| to detect and follow a nested SSH session robustly.
+   |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

docs/kittens/themes.rst

@@ -7,6 +7,11 @@ of almost two hundred pre-built themes available at `kitty-themes
 
     kitty +kitten themes
 
+
+.. image:: ../screenshots/themes.png
+   :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.
@@ -45,11 +50,18 @@ choose that theme once for your changes to be applied.
 Contributing new themes
 -------------------------
 
-If you wish to contribute a new theme to the kitty theme repository, simply
-go to `kitty-themes <https://github.com/kovidgoyal/kitty-themes>`_ and open a pull request
-asking to add your contributions to the repository. Use the file
-:download:`template.conf <https://github.com/kovidgoyal/kitty-themes/raw/master/template.conf>` as
-a template when creating your theme.
+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
+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>`_
+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.
 
 
 Changing the theme non-interactively
@@ -58,7 +70,7 @@ 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::
 
-    kitty +kitten theme --reload-in=all Dimmed Monokai
+    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.

docs/kittens/transfer.rst

@@ -0,0 +1,97 @@
+Transfer files
+================
+
+.. _rsync: https://en.wikipedia.org/wiki/Rsync
+
+.. warning::
+   This kitten is currently experimental, use with care.
+
+Transfer files to and from remote computers over the ``TTY`` device itself.
+This means that file transfer works over nested SSH sessions, serial links,
+etc. Anywhere you have a terminal device, you can transfer files.
+
+.. image:: ../screenshots/transfer.png
+   :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.
+
+.. 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>`.
+
+.. versionadded:: 0.24.0
+
+
+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.
+
+To send a file from the local computer to the remote computer, simply run::
+
+    kitty +kitten transfer /path/to/local/file /path/to/destination/on/remote/computer
+
+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::
+
+    kitty +kitten transfer --direction=receive /path/to/remote/file /path/to/destination/on/local/computer
+
+Multiple files and even directories can be transferred::
+
+    kitty +kitten transfer file1 dir1 destination/
+
+Here :file:`file1` will be copied inside :file:`destination` and :file:`dir1`
+will be recursively copied into :file:`destination`. Note the trailing slash on
+:file:`destination`. This tells kitty the destination is a directory. While not
+strictly necessary (kitty will infer the need for a destination directory from
+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.
+
+
+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:
+
+#. 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.
+
+.. warning:: Using a password to bypass confirmation means any software running
+   on the remote machine could potentially learn that password and use it to
+   gain full access to your computer. Also anyone that can intercept the data
+   stream between your computer and the remote machine can also learn this
+   password. So use it only with secure connections to trusted computers.
+
+
+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.
+
+
+.. include:: ../generated/cli-kitten-transfer.rst

docs/kittens/unicode_input.rst

@@ -23,9 +23,9 @@ 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.
 
-You can switch between modes using either the function keys or by pressing
-:kbd:`Ctrl+[` and :kbd:`Ctrl+]` or by pressing :kbd:`Ctrl+Tab` and
-:kbd:`Ctrl+Shift+Tab`.
+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+]`
+or by pressing :kbd:`Ctrl+Tab` and :kbd:`Ctrl+Shift+Tab`.
 
 
 .. include:: ../generated/cli-kitten-unicode_input.rst

docs/kittens_intro.rst

@@ -9,11 +9,12 @@ Extend with kittens
 
    kittens/icat
    kittens/diff
-   kittens/unicode-input
+   kittens/unicode_input
    kittens/themes
    kittens/hints
    kittens/remote_file
    kittens/hyperlinked_grep
+   kittens/transfer
    kittens/custom
    kittens/*
 
@@ -31,7 +32,7 @@ Some prominent kittens:
     images
 
 
-:doc:`Unicode Input <kittens/unicode-input>`
+:doc:`Unicode Input <kittens/unicode_input>`
     Easily input arbitrary unicode characters in |kitty| by name or hex code.
 
 
@@ -45,6 +46,11 @@ Some prominent kittens:
     the filename.
 
 
+:doc:`Transfer files <kittens/transfer>`
+    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>`_
     and open the results directly in your favorite editor in the terminal,

docs/launch.rst

@@ -38,6 +38,18 @@ To pass the contents of the current screen and scrollback to the started process
 
 There are many more powerful options, refer to the complete list below.
 
+.. note::
+    To avoid duplicating launch actions with frequently used parameters, you can
+    use :opt:`action_alias` to define launch action aliases. For example::
+
+        action_alias launch_tab launch --cwd=current --type=tab
+        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 piping environment
 --------------------------
 
@@ -83,12 +95,20 @@ the command line:
 ``@cursor-y``
     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::
 
     map f1 launch my-program @active-kitty-window-id
 
 
+.. _watchers:
+
 Watching launched windows
 ---------------------------
 
@@ -103,7 +123,7 @@ functions for the events you are interested in, for example:
         # Here data will contain old_geometry and new_geometry
 
     def on_focus_change(boss, window, data):
-        # Here data kill contain focused
+        # Here data will contain focused
 
     def on_close(boss, window, data):
         # called when window is closed, typically when the program running in
@@ -112,7 +132,7 @@ functions for the events you are interested in, for example:
 
 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
-mapping that contains event dependent data. Some useful methods and attributes
+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,
@@ -130,6 +150,7 @@ this **may not** be the value of ``PATH`` inside a shell, as shell startup scrip
 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.
+See :opt:`exe_search_path` for details and how to control this.
 
 Syntax reference
 ------------------

docs/layouts.rst

@@ -128,30 +128,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`::
 
+    # 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`.
+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 ``--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
 
@@ -236,6 +253,8 @@ action, for example::
    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 resizing increment (a positive integer that defaults to 1).

docs/open_actions.rst

@@ -58,6 +58,12 @@ some special variables, documented below:
 ``FRAGMENT``
     The fragment (unquoted), if any of the URL or the empty string.
 
+
+.. note::
+   You can use the :opt:`action_alias` option just as in kitty.conf to
+   define aliases for frequently used actions.
+
+
 .. _matching_criteria:
 
 Matching criteria
@@ -94,3 +100,69 @@ 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::
+
+    open -a kitty.app file_or_url ... (on macOS only)
+    or
+    kitty +open file_or_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 kitty config directory, just like
+the :file:`open-actions.conf` file above. For example:
+
+.. code:: conf
+
+    # Open script files based on their shebangs
+    protocol file
+    ext sh,command,tool
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH {SHELL}
+
+    # Open shell specific script files
+    protocol file
+    ext fish,bash,zsh
+    action launch --hold --type=os-window kitty +shebang $FILE_PATH __ext__
+
+    # Open directories
+    protocol file
+    mime inode/directory
+    action launch --type=os-window --cwd $FILE_PATH
+
+    # Open text files without fragments in the editor
+    protocol file
+    mime text/*
+    action launch --type=os-window $EDITOR $FILE_PATH
+
+    # Open image files with icat
+    protocol file
+    mime image/*
+    action launch --type=os-window kitty +kitten icat --hold $FILE_PATH
+
+    # Open ssh URLs with ssh command
+    protocol ssh
+    action launch --type=os-window ssh $URL

docs/overview.rst

@@ -79,7 +79,7 @@ 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
 <kittens/diff>`.
@@ -191,8 +191,10 @@ Mouse features
   platforms with a primary clipboard).
 * You can middle click to paste from the primary clipboard (on platforms
   with a primary clipboard).
+* You can right click while holding :kbd:`ctrl+shift` to open the output
+  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.
+  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>`.
@@ -242,15 +244,30 @@ 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` for details.
+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>`_.
+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` features, you can use the :opt:`scrollback_pager_history_size`
-option.
+:sc:`show_scrollback <show_scrollback>` features, you can use the
+:opt:`scrollback_pager_history_size` option.
+
+
+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
+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.
+
+.. toctree::
+   :hidden:
+
+   shell-integration
 
 .. _cpbuf:
 

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

@@ -26,6 +26,7 @@ please do so by opening issues in the `GitHub
    underlines
    graphics-protocol
    keyboard-protocol
+   file-transfer-protocol
    desktop-notifications
    unscroll
    color-stack

docs/shell-integration.rst

@@ -0,0 +1,288 @@
+.. _shell_integration:
+
+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
+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.
+
+.. versionadded:: 0.24.0
+
+Features
+-------------
+
+* Open the output of the last command in a pager such as :program:`less`
+  (:sc:`show_last_command_output`)
+
+* Jump to the previous/next prompt in the scrollback
+  (:sc:`scroll_to_previous_prompt` /  :sc:`scroll_to_next_prompt`)
+
+* 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
+  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
+
+* The text cursor is changed to a bar when editing commands at the shell prompt
+
+* Glitch free window resizing even with complex prompts. Achieved by erasing
+  the prompt on resize and allowing the shell to redraw it cleanly.
+
+* Sophisticated completion for the :program:`kitty` command in the shell.
+
+* When confirming a quit command if a window is sitting at a shell prompt,
+  it is optionally, not counted (see :opt:`confirm_os_window_close`)
+
+
+Configuration
+---------------
+
+Shell integration is controlled by the :opt:`shell_integration` option. By
+default, all shell integration is 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. 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 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
+
+no-title
+    Turn off setting the kitty window/tab title based on shell state.
+    Note that for the ``fish`` shell kitty relies on fish's native title
+    setting functionality instead.
+
+no-prompt-mark
+    Turn off marking of prompts. This disables jumping to prompt, browsing
+    output of last command and click to move cursor functionality.
+
+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`:
+
+.. code:: conf
+
+    mouse_map right press ungrabbed mouse_select_command_output
+
+Now, when you right click on the output, the entire output is selected, ready
+to be copied.
+
+The feature to jump to previous prompts (
+:sc:`scroll_to_previous_prompt` and :sc:`scroll_to_next_prompt`) and mouse
+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
+
+    map f1 show_last_visited_command_output
+
+Now, pressing :kbd:`F1` will cause the output of the last jumped to command or
+the last mouse clicked command output to be opened in a pager for easy browsing.
+
+In addition, You can define shortcut to get the first command output on screen.
+For example, define the following in :file:`kitty.conf`:
+
+.. code:: conf
+
+    map f1 show_first_command_output_on_screen
+
+Now, pressing :kbd:`F1` will cause the output of the first command output on
+screen to be opened in a pager.
+
+You can also add shortcut to scroll to the last jumped position. For example,
+define the following in :file:`kitty.conf`:
+
+.. code:: conf
+
+    map f1 scroll_to_prompt 0
+
+
+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.
+
+
+.. 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:: fish
+
+    For fish, to make it automatically load the integration code provided by
+    kitty, the integration script directory path is prepended to the
+    ``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
+    ``ENV`` to load the shell integrtion 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.
+
+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
+code used for each shell below:
+
+.. raw:: html
+
+    <details>
+    <summary>Click to toggle shell integration code</summary>
+
+.. tab:: zsh
+
+    .. literalinclude:: ../shell-integration/zsh/kitty-integration
+        :language: zsh
+
+
+.. tab:: fish
+
+    .. literalinclude:: ../shell-integration/fish/vendor_conf.d/kitty-shell-integration.fish
+        :language: fish
+        :force:
+
+.. tab:: bash
+
+    .. literalinclude:: ../shell-integration/bash/kitty.bash
+        :language: bash
+
+.. raw:: html
+
+   </details>
+
+
+.. _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.
+For such systems, you should setup manual shell integration by adding some code
+to your shells startup files to load the shell integration script.
+
+First, in :file:`kitty.conf` set:
+
+.. code-block:: conf
+
+    shell_integration disabled
+
+Then in your shell's rc file, add the lines:
+
+.. tab:: zsh
+
+    .. code-block:: sh
+
+        if test -n "$KITTY_INSTALLATION_DIR"; then
+            export KITTY_SHELL_INTEGRATION="enabled"
+            autoload -Uz -- "$KITTY_INSTALLATION_DIR"/shell-integration/zsh/kitty-integration
+            kitty-integration
+            unfunction kitty-integration
+        fi
+
+.. tab:: fish
+
+    .. code-block:: fish
+
+        if set -q KITTY_INSTALLATION_DIR
+            set --global KITTY_SHELL_INTEGRATION enabled
+            source "$KITTY_INSTALLATION_DIR/shell-integration/fish/vendor_conf.d/kitty-shell-integration.fish"
+            set --prepend fish_complete_path "$KITTY_INSTALLATION_DIR/shell-integration/fish/vendor_completions.d"
+        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 :envvar:`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.
+
+
+Integration with other shells
+-------------------------------
+
+There exist third-party integrations to use these features for various other shells:
+
+* Jupyter console via a patch (:iss:`4475`)
+* `xonsh <https://github.com/xonsh/xonsh/issues/4623>`__
+
+
+Notes for shell developers
+-----------------------------
+
+The protocol used for marking the prompt is very simple. You should consider
+adding it to your shell as a builtin. Many modern terminals make use of it, for
+example: kitty, iTerm2, WezTerm, DomTerm
+
+Just before starting to draw the PS1 prompt send the escape code::
+
+    <OSC>133;A<ST>
+
+Just before starting to draw the PS2 prompt send the escape code::
+
+    <OSC>133;A;k=s<ST>
+
+Just before running a command/program, send the escape code::
+
+    <OSC>133;C<ST>
+
+Here ``<OSC>`` is the bytes ``0x1b 0x5d`` and ``<ST>`` is the bytes ``0x1b
+0x5c``. This is exactly what is needed for shell integration in kitty. For the
+full protocol, that also marks the command region, see `the iTerm2 docs
+<https://iterm2.com/documentation-escape-codes.html>`_.

docs/support.html

@@ -1,7 +1,12 @@
 <style>
+#support-buttons {
+    display: flex;
+    flex-wrap: wrap;
+}
+
 .support-button {
+    box-sizing: border-box;
     border-radius: 6px;
-    box-shadow: rgb(255, 246, 175) 0px 1px 0px 0px;
     display: inline-block;
     cursor: pointer;
     color: rgb(51, 51, 51);
@@ -10,15 +15,16 @@
     font-weight: bold;
     padding: 8px 24px;
     text-decoration: none;
+    margin-left: 1em;
+    outline: 0;
+    border-width: 0;
 }
 
 .support-button:hover {
-    transform: scale(1.5);
+    transform: scale(1.2);
+    border: solid 1px rgb(92, 184, 92);
 }
 
-.support-button {
-    outline: 0;
-}
 .support-button:visited {
     color: rgb(51, 51, 51);
     outline: 0;
@@ -30,28 +36,34 @@
 }
 
 #paypal input[type=submit] {
-    background: linear-gradient(rgb(255, 236, 100) 5%, rgb(255, 171, 35) 100%) rgb(255, 236, 100);
-    border: 1px solid rgb(255, 171, 35);
+    background: linear-gradient(rgb(92, 184, 92) 5%, rgb(62, 142, 62) 100%) rgb(92, 184, 92);
+    padding-top: 10px; padding-bottom: 10px;
+    color: rgb(51, 51, 51);
+    border: 1px solid rgb(92, 184, 92);
 }
 
-#liberapay a {
+a.support-button {
     background: linear-gradient(rgb(92, 184, 92) 5%, rgb(62, 142, 62) 100%) rgb(92, 184, 92);
-    border: 1px solid rgb(62, 142, 62);
     color: rgb(51, 51, 51);
 }
 
-#patreon a {
-    background: linear-gradient(rgb(11, 100, 163) 5%, rgb(5, 45, 73) 100%) rgb(11, 100, 163);
-    border: 1px solid rgb(5, 45, 73);
-    color: #eee;
-}
 </style>
 
 <div id="support-buttons">
+
+<div id="github">
+    <a class="support-button" href="https://github.com/sponsors/kovidgoyal">Patronage via GitHub</a>
+</div>
+
+
 <div id="patreon">
     <a class="support-button" href="https://www.patreon.com/bePatron?u=917933">Patronage via Patreon</a>
 </div>
 
+<div id="liberapay">
+    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</a>
+</div>
+
 <div>
     <form id="paypal" action="https://www.paypal.com/cgi-bin/webscr" method="post" title="Contribute to support calibre development">
         <input type="hidden" name="cmd" value="_s-xclick" />
@@ -61,9 +73,5 @@
     </form>
 </div>
 
-<div id="liberapay">
-    <a class="support-button" href="https://liberapay.com/kovidgoyal/donate">Patronage via Liberapay</a>
-</div>
-
 </div>
 

docs/support.rst

@@ -1,5 +1,5 @@
-Support kitty development
-===========================
+Support kitty development ❤️
+==============================
 
 My goal with |kitty| is to move the stagnant terminal ecosystem forward.  To that
 end kitty has many foundational features, such as: :doc:`image support
@@ -7,7 +7,7 @@ end kitty has many foundational features, such as: :doc:`image support
 :doc:`various enhancements to the terminal protocol <protocol-extensions>`,
 etc. These features allow the development of rich terminal applications, such
 as :doc:`Side-by-side diff <kittens/diff>` and :doc:`Unicode input
-<kittens/unicode-input>`.
+<kittens/unicode_input>`.
 
 If you wish to support this mission and see the terminal ecosystem evolve,
 consider donating so that I can devote more time to |kitty| development.
@@ -15,8 +15,7 @@ I have personally written `almost all kitty code
 <https://github.com/kovidgoyal/kitty/graphs/contributors>`_.
 
 You can choose to make either a one-time payment via PayPal or become a
-*patron* of kitty development via the Patreon or Liberapay services
-below:
+*patron* of kitty development via one of the services below:
 
 
 .. raw:: html

docs/underlines.rst

@@ -13,8 +13,8 @@ To set the underline style::
     <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>[4:4m  # this is a dotted underline
+    <ESC>[4:5m  # this is a dashed underline
     <ESC>[4m    # this is a straight underline (for backwards compat)
     <ESC>[24m   # this is no underline (for backwards compat)
 

docs/unscroll.rst

@@ -32,3 +32,7 @@ See `discussion here
 <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>`_

gen-apc-parsers.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # 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
@@ -43,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;
@@ -68,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)
@@ -241,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

@@ -1,14 +1,41 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 
+import re
+from typing import List
+
 from kitty.conf.generate import write_output
 
 
+def patch_color_list(path: str, colors: List[str], name: str, spc: str = '    ') -> None:
+    with open(path, 'r+') as f:
+        raw = f.read()
+        nraw = re.sub(
+            fr'(# {name}_COLORS_START).+?(\s+# {name}_COLORS_END)',
+            r'\1' + f'\n{spc}' + f'\n{spc}'.join(map(lambda x: f'{x!r},', sorted(colors))) + r'\2',
+            raw, flags=re.DOTALL | re.MULTILINE)
+        if nraw != raw:
+            f.seek(0)
+            f.truncate()
+            f.write(nraw)
+
+
 def main() -> None:
     from kitty.options.definition import definition
     write_output('kitty', definition)
+    nullable_colors = []
+    all_colors = []
+    for opt in definition.iter_all_options():
+        if callable(opt.parser_func):
+            if opt.parser_func.__name__ in ('to_color_or_none', 'cursor_text_color'):
+                nullable_colors.append(opt.name)
+                all_colors.append(opt.name)
+            elif opt.parser_func.__name__ in ('to_color', 'titlebar_color', 'macos_titlebar_color'):
+                all_colors.append(opt.name)
+    patch_color_list('kitty/rc/set_colors.py', nullable_colors, 'NULLABLE')
+    patch_color_list('kittens/themes/collection.py', all_colors, 'ALL', ' ' * 8)
+
     from kittens.diff.options.definition import definition as kd
     write_output('kittens.diff', kd)
 

gen-key-constants.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 import string
@@ -239,13 +238,13 @@ 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)
 
 
-def serialize_dict(x: dict) -> str:
+def serialize_dict(x: Dict[Any, Any]) -> str:
     return pformat(x, indent=4).replace('{', '{\n ', 1)
 
 
@@ -349,7 +348,7 @@ def generate_legacy_text_key_maps() -> None:
     patch_file('kitty_tests/keys.py', 'legacy letter tests', '\n'.join(tests), start_marker='# ', end_marker='')
 
 
-def chunks(lst: List, n: int) -> Any:
+def chunks(lst: List[Any], n: int) -> Any:
     """Yield successive n-sized chunks from lst."""
     for i in range(0, len(lst), n):
         yield lst[i:i + n]
@@ -369,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

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2017, Kovid Goyal <kovid at kovidgoyal.net>
 
 import os
@@ -50,10 +49,25 @@ 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))
-marks = set(emoji_skin_tone_modifiers) | {zwj} | flag_codepoints
+# See https://github.com/harfbuzz/harfbuzz/issues/169
+marks = set(emoji_skin_tone_modifiers) | flag_codepoints
 not_assigned = set(range(0, sys.maxunicode))
+property_maps: Dict[str, Set[int]] = defaultdict(set)
+
+
+def parse_prop_list() -> None:
+    global marks
+    for line in get_data('ucd/PropList.txt'):
+        if line.startswith('#'):
+            continue
+        cp_or_range, rest = line.split(';', 1)
+        chars = parse_range_spec(cp_or_range.strip())
+        name = rest.strip().split()[0]
+        property_maps[name] |= chars
+    # see https://www.unicode.org/faq/unsup_char.html#3
+    marks |= property_maps['Other_Default_Ignorable_Code_Point']
 
 
 def parse_ucd() -> None:
@@ -97,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:
@@ -213,7 +233,7 @@ def parse_eaw() -> None:
         if eaw == 'A':
             ambiguous |= chars
             seen |= chars
-        elif eaw == 'W' or eaw == 'F':
+        elif eaw in ('W', 'F'):
             doublewidth |= chars
             seen |= chars
     doublewidth |= set(range(0x3400, 0x4DBF + 1)) - seen
@@ -234,15 +254,15 @@ def get_ranges(items: List[int]) -> Generator[Union[int, Tuple[int, int]], None,
             yield a, b
 
 
-def write_case(spec: Union[Tuple, int], p: Callable) -> None:
+def write_case(spec: Union[Tuple[int, ...], int], p: Callable[..., None]) -> None:
     if isinstance(spec, tuple):
         p('\t\tcase 0x{:x} ... 0x{:x}:'.format(*spec))
     else:
-        p('\t\tcase 0x{:x}:'.format(spec))
+        p(f'\t\tcase 0x{spec:x}:')
 
 
 @contextmanager
-def create_header(path: str, include_data_types: bool = True) -> Generator[Callable, None, None]:
+def create_header(path: str, include_data_types: bool = True) -> Generator[Callable[..., None], None, None]:
     with open(path, 'w') as f:
         p = partial(print, file=f)
         p('// unicode data, built from the unicode standard on:', date.today())
@@ -282,7 +302,7 @@ def gen_emoji() -> None:
 
 def category_test(
     name: str,
-    p: Callable,
+    p: Callable[..., None],
     classes: Iterable[str],
     comment: str,
     use_static: bool = False,
@@ -312,7 +332,7 @@ def category_test(
     p('\treturn false;\n}\n')
 
 
-def codepoint_to_mark_map(p: Callable, mark_map: List[int]) -> Dict[int, int]:
+def codepoint_to_mark_map(p: Callable[..., None], mark_map: List[int]) -> Dict[int, int]:
     p('\tswitch(c) { // {{{')
     rmap = {c: m for m, c in enumerate(mark_map)}
     for spec in get_ranges(mark_map):
@@ -336,10 +356,10 @@ def classes_to_regex(classes: Iterable[str], exclude: str = '') -> Iterable[str]
 
     def as_string(codepoint: int) -> str:
         if codepoint < 256:
-            return r'\x{:02x}'.format(codepoint)
+            return fr'\x{codepoint:02x}'
         if codepoint <= 0xffff:
-            return r'\u{:04x}'.format(codepoint)
-        return r'\U{:08x}'.format(codepoint)
+            return fr'\u{codepoint:04x}'
+        return fr'\U{codepoint:08x}'
 
     for spec in get_ranges(list(chars)):
         if isinstance(spec, tuple):
@@ -354,16 +374,21 @@ def gen_ucd() -> None:
         p('#include "unicode-data.h"')
         category_test(
                 'is_combining_char', p,
-                {c for c in class_maps if c.startswith('M')},
-                'M category (marks)',
-                # See https://github.com/harfbuzz/harfbuzz/issues/169
-                extra_chars=emoji_skin_tone_modifiers | {zwj},
+                (),
+                'Combining and default ignored characters',
+                extra_chars=marks,
                 least_check_return='false'
         )
         category_test(
-            'is_ignored_char', p, 'Cc Cf Cs'.split(),
+            'is_ignored_char', p, 'Cc Cs'.split(),
             'Control characters and non-characters',
-            extra_chars=non_characters, exclude={zwj},
+            extra_chars=non_characters,
+            ascii_range='false'
+        )
+        category_test(
+            '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'] | 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')
@@ -378,15 +403,19 @@ def gen_ucd() -> None:
         p('combining_type mark_for_codepoint(char_type c) {')
         rmap = codepoint_to_mark_map(p, mark_map)
         p('}\n')
-        with open('kitty/unicode-data.h') as f:
-            unicode_data = f.read()
-        m = re.search(r'^#define VS15 (\d+)', unicode_data, re.M)
-        if m is not None:
-            expected = int(m.group(1))
-        if rmap[0xfe0e] != expected:
-            raise ValueError('The mark for 0xfe0e has changed, you have to update VS15 to {} and VS16 to {} in unicode-data.h'.format(
-                rmap[0xfe0e], rmap[0xfe0f]
-            ))
+        with open('kitty/unicode-data.h', 'r+') as f:
+            raw = f.read()
+            f.seek(0)
+            raw, num = re.subn(
+                r'^// START_KNOWN_MARKS.+?^// END_KNOWN_MARKS',
+                '// START_KNOWN_MARKS\nstatic const combining_type '
+                f'VS15 = {rmap[0xfe0e]}, VS16 = {rmap[0xfe0f]};'
+                '\n// END_KNOWN_MARKS', raw, flags=re.MULTILINE | re.DOTALL)
+            if not num:
+                raise SystemExit('Faile dto patch mark definitions in unicode-data.h')
+            f.truncate()
+            f.write(raw)
+
     with open('kittens/hints/url_regex.py', 'w') as f:
         f.write('# generated by gen-wcwidth.py, do not edit\n\n')
         f.write("url_delimiters = '{}'  # noqa".format(''.join(classes_to_regex(cz, exclude='\n\r'))))
@@ -496,7 +525,7 @@ def gen_names() -> None:
 def gen_wcwidth() -> None:
     seen: Set[int] = set()
 
-    def add(p: Callable, comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
+    def add(p: Callable[..., None], comment: str, chars_: Union[Set[int], FrozenSet[int]], ret: int) -> None:
         chars = chars_ - seen
         seen.update(chars)
         p(f'\t\t// {comment} ({len(chars)} codepoints)' + ' {{' '{')
@@ -537,6 +566,7 @@ def gen_wcwidth() -> None:
 
 
 parse_ucd()
+parse_prop_list()
 parse_emoji()
 parse_eaw()
 gen_ucd()

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,22 +481,293 @@ void* _glfwLoadLocalVulkanLoaderNS(void)
 //////                       GLFW platform API                      //////
 //////////////////////////////////////////////////////////////////////////
 
+/**
+ * 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_ctrl_tab(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    if (
-            (modifierFlags == NSEventModifierFlagControl &&
-                [event.charactersIgnoringModifiers isEqualToString:@"\t"]) ||
-            (modifierFlags == (NSEventModifierFlagControl | NSEventModifierFlagShift) &&
-                [event.charactersIgnoringModifiers isEqualToString:@"\x19"])
-       ) return true;
-    return false;
+is_shiftable_shortcut(int scv) {
+    return scv == kSHKMoveFocusToActiveOrNextWindow || scv == kSHKMoveFocusToNextWindow;
+}
+
+#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
+            }
+        }
+    }
+
+    // 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_cmd_period(NSEvent *event, NSEventModifierFlags modifierFlags) {
-    if (modifierFlags != NSEventModifierFlagCommand) return false;
-    if ([event.charactersIgnoringModifiers isEqualToString:@"."]) return true;
-    return false;
+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;
+    }
 }
 
 GLFWAPI GLFWapplicationshouldhandlereopenfun glfwSetApplicationShouldHandleReopen(GLFWapplicationshouldhandlereopenfun callback) {
@@ -507,33 +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] & NSEventModifierFlagDeviceIndependentFlagsMask;
-        if (is_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows Ctrl+Tab to cycle between views
-            [[NSApp keyWindow].contentView keyDown:event];
+        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] & NSEventModifierFlagDeviceIndependentFlagsMask;
-        if (modifierFlags & NSEventModifierFlagCommand) {
-            // From http://cocoadev.com/index.pl?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_ctrl_tab(event, modifierFlags) || is_cmd_period(event, modifierFlags)) {
-            // Cocoa swallows Ctrl+Tab to cycle between views
-            [[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 =
@@ -542,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();
@@ -554,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:)
@@ -609,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;
     }
@@ -617,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_monitor.m

@@ -61,7 +61,7 @@ getDisplayName(CGDirectDisplayID displayID, NSScreen* screen)
     io_service_t service;
     CFDictionaryRef info;
 
-    if (IOServiceGetMatchingServices(kIOMainPortDefault,
+    if (IOServiceGetMatchingServices(0,
                                      IOServiceMatching("IODisplayConnect"),
                                      &it) != 0)
     {
@@ -259,7 +259,7 @@ static double getFallbackRefreshRate(CGDirectDisplayID displayID)
     io_iterator_t it;
     io_service_t service;
 
-    if (IOServiceGetMatchingServices(kIOMainPortDefault,
+    if (IOServiceGetMatchingServices(0,
                                      IOServiceMatching("IOFramebuffer"),
                                      &it) != 0)
     {

glfw/cocoa_platform.h

@@ -39,9 +39,6 @@ typedef void* CVDisplayLinkRef;
 // NOTE: Many Cocoa enum values have been renamed and we need to build across
 //       SDK versions where one is unavailable or the other deprecated
 //       We use the newer names in code and these macros to handle compatibility
-#if (MAC_OS_X_VERSION_MAX_ALLOWED < 120000) // Before macOS 12 Monterey
-  #define kIOMainPortDefault kIOMasterPortDefault
-#endif
 #if MAC_OS_X_VERSION_MAX_ALLOWED < 101200
  #define NSBitmapFormatAlphaNonpremultiplied NSAlphaNonpremultipliedBitmapFormat
  #define NSEventMaskAny NSAnyEventMask
@@ -67,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*);
@@ -133,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;
 
@@ -155,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
@@ -176,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];
@@ -201,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;
 
@@ -234,7 +235,6 @@ typedef struct _GLFWtimerNS
 
 } _GLFWtimerNS;
 
-
 void _glfwPollMonitorsNS(void);
 void _glfwSetVideoModeNS(_GLFWmonitor* monitor, const GLFWvidmode* desired);
 void _glfwRestoreVideoModeNS(_GLFWmonitor* monitor);
@@ -251,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,12 +32,17 @@
 #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) {
+    if (string == nil) return "(nil)";
+    NSString* characters;
+    if ([string isKindOfClass:[NSAttributedString class]])
+        characters = [string string];
+    else
+        characters = (NSString*) string;
+    return [characters UTF8String];
+}
 
 static uint32_t
 vk_code_to_functional_key_code(uint8_t key_code) {  // {{{
@@ -249,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;
@@ -503,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];
@@ -561,30 +564,9 @@ translateKey(uint16_t vk_key, bool apply_keymap)
     return ans;
 }
 
-// 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;
+static NSRect
+get_window_size_without_border_in_logical_pixels(_GLFWwindow *window) {
+    return [window->ns.object contentRectForFrameRect:[window->ns.object frame]];
 }
 
 // Defines a constant for empty ranges in NSTextInputClient
@@ -592,135 +574,6 @@ translateKeyToModifierFlag(uint32_t key)
 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
@@ -729,6 +582,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 }
 
 - (instancetype)initWithGlfwWindow:(_GLFWwindow *)initWindow;
+- (void)request_delayed_cursor_update:(id)sender;
 
 @end
 
@@ -766,7 +620,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
         _glfwInputWindowMaximize(window, maximized);
     }
 
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
     const NSRect fbRect = [window->ns.view convertRectToBacking:contentRect];
 
     if (fbRect.size.width != window->ns.fbWidth ||
@@ -839,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
@@ -849,6 +706,14 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
     showCursor(window);
 
     _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;
+    }
 }
 
 - (void)windowDidChangeScreen:(NSNotification *)notification
@@ -861,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 {{{
 
@@ -870,8 +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;
 }
 
@@ -889,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]];
@@ -905,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];
 }
 
@@ -1023,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
@@ -1088,7 +1010,7 @@ static const NSRange kEmptyRange = { NSNotFound, 0 };
 - (void)viewDidChangeBackingProperties
 {
     if (!window) return;
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
     const NSRect fbRect = [window->ns.view convertRectToBacking:contentRect];
 
     if (fbRect.size.width != window->ns.fbWidth ||
@@ -1122,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];
@@ -1144,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;
@@ -1205,39 +1134,40 @@ is_ascii_control_char(char x) {
 
 - (void)keyDown:(NSEvent *)event
 {
+#define CLEAR_PRE_EDIT_TEXT glfw_keyevent.text = NULL; glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED; _glfwInputKeyboard(window, &glfw_keyevent);
+#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];
-    bool input_source_changed = false;
-    NSTextInputContext *inpctx = [NSTextInputContext currentInputContext];
-    if (inpctx && (!input_source_at_last_key_event || ![input_source_at_last_key_event isEqualToString:inpctx.selectedKeyboardInputSource])) {
-        input_source_at_last_key_event = [inpctx.selectedKeyboardInputSource retain];
-        input_source_changed = true;
+    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 = [input_context.selectedKeyboardInputSource retain];
+        [self unmarkText];
     }
 
     const unsigned int keycode = [event keyCode];
     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;
-    [self unmarkText];
+    const bool process_text = !_glfw.ignoreOSKeyboardProcessing && (!window->ns.textInputFilterCallback || window->ns.textInputFilterCallback(key, mods, keycode, flags) != 1);
     _glfw.ns.text[0] = 0;
-    GLFWkeyevent glfw_keyevent = {.key = key, .native_key = keycode, .action = GLFW_PRESS, .mods = mods};
+    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};
     if (!_glfw.ns.unicodeData) {
         // Using the cocoa API for key handling is disabled, as there is no
         // reliable way to handle dead keys using it. Only use it if the
         // 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 {
-        if (input_source_changed) {
-            debug_key("Input source changed, clearing pre-edit text and resetting deadkey state\n");
-            glfw_keyevent.text = NULL;
-            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
-            window->ns.deadKeyState = 0;
-            _glfwInputKeyboard(window, &glfw_keyevent); // clear pre-edit text
-        }
-
         static UniChar text[256];
         UniCharCount char_count = 0;
         const bool in_compose_sequence = window->ns.deadKeyState != 0;
@@ -1260,76 +1190,110 @@ is_ascii_control_char(char x) {
         }
         debug_key("\x1b[31mPress:\x1b[m native_key: 0x%x (%s) glfw_key: 0x%x %schar_count: %lu deadKeyState: %u repeat: %d ",
                 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;
         }
         if (window->ns.deadKeyState && (char_count == 0 || keycode == 0x75)) {
             // 0x75 is the delete key which needs to be ignored during a compose sequence
-            glfw_keyevent.text = [[markedText string] UTF8String];
             debug_key("Sending pre-edit text for dead key (text: %s markedText: %s).\n", format_text(_glfw.ns.text), glfw_keyevent.text);
-            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
-            _glfwInputKeyboard(window, &glfw_keyevent); // update pre-edit text
+            UPDATE_PRE_EDIT_TEXT;
             return;
         }
         if (in_compose_sequence) {
             debug_key("Clearing pre-edit text at end of compose sequence\n");
-            glfw_keyevent.text = NULL;
-            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
-            _glfwInputKeyboard(window, &glfw_keyevent); // clear pre-edit text
+            CLEAR_PRE_EDIT_TEXT;
         }
     }
     if (is_ascii_control_char(_glfw.ns.text[0])) _glfw.ns.text[0] = 0;  // don't send text for ascii control codes
-    debug_key("text: %s glfw_key: %s marked_text: %s\n",
+    debug_key("text: %s glfw_key: %s marked_text: (%s)\n",
             format_text(_glfw.ns.text), _glfwGetKeyName(key), [[markedText string] UTF8String]);
+    bool bracketed_ime = false;
     if (!window->ns.deadKeyState) {
         if ([self hasMarkedText]) {
-            glfw_keyevent.text = [[markedText string] UTF8String];
-            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
-            _glfwInputKeyboard(window, &glfw_keyevent); // update pre-edit text
+            if (!marked_text_cleared_by_insert) {
+                UPDATE_PRE_EDIT_TEXT;
+            } else bracketed_ime = true;
         } else if (previous_has_marked_text) {
-            glfw_keyevent.text = NULL;
-            glfw_keyevent.ime_state = GLFW_IME_PREEDIT_CHANGED;
-            _glfwInputKeyboard(window, &glfw_keyevent); // clear pre-edit text
+            CLEAR_PRE_EDIT_TEXT;
         }
         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;
         }
     }
+    if (bracketed_ime) {
+        // insertText followed by setMarkedText
+        CLEAR_PRE_EDIT_TEXT;
+    }
     glfw_keyevent.text = _glfw.ns.text;
     glfw_keyevent.ime_state = GLFW_IME_NONE;
     add_alternate_keys(&glfw_keyevent, event);
     _glfwInputKeyboard(window, &glfw_keyevent);
+    if (bracketed_ime) {
+        // insertText followed by setMarkedText
+        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], .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);
 }
 
@@ -1339,13 +1303,16 @@ is_ascii_control_char(char x) {
     const uint32_t key = translateKey(keycode, true);
     const int mods = translateFlags([event modifierFlags]);
 
-    GLFWkeyevent glfw_keyevent = {.key = key, .native_key = keycode, .action = GLFW_RELEASE, .mods = mods};
+    GLFWkeyevent glfw_keyevent = {.key = key, .native_key = keycode, .native_key_id = keycode, .action = GLFW_RELEASE, .mods = mods};
     add_alternate_keys(&glfw_keyevent, event);
     debug_key("\x1b[32mRelease:\x1b[m native_key: 0x%x (%s) glfw_key: 0x%x %s\n",
             keycode, safe_name_for_keycode(keycode), key, format_mods(mods));
     _glfwInputKeyboard(window, &glfw_keyevent);
 }
 
+#undef CLEAR_PRE_EDIT_TEXT
+#undef UPDATE_PRE_EDIT_TEXT
+
 - (void)scrollWheel:(NSEvent *)event
 {
     double deltaX = [event scrollingDeltaX];
@@ -1401,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 appendFormat:@("file://%s"), url.fileSystemRepresentation];
+                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));
@@ -1418,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;
 }
@@ -1444,12 +1415,34 @@ is_ascii_control_char(char x) {
         selectedRange:(NSRange)selectedRange
      replacementRange:(NSRange)replacementRange
 {
-    (void)selectedRange; (void)replacementRange;
-    [markedText release];
-    if ([string isKindOfClass:[NSAttributedString class]])
+    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];
         markedText = [[NSMutableAttributedString alloc] initWithAttributedString:string];
-    else
+    } else {
+        if (((NSString*)string).length == 0) { [self unmarkText]; return; }
+        [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
@@ -1458,26 +1451,35 @@ 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
 {
-    (void) which;
+    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;
     cellWidth /= window->ns.xscale;
     cellHeight /= window->ns.yscale;
-    debug_key("updateIMEState: %f, %f, %f, %f\n", left, top, cellWidth, cellHeight);
+    debug_key("updateIMEPosition: left=%f, top=%f, width=%f, height=%f\n", left, top, cellWidth, cellHeight);
     const NSRect frame = [window->ns.view frame];
     const NSRect rectInView = NSMakeRect(left,
                                          frame.size.height - top - cellHeight,
                                          cellWidth, cellHeight);
     markedRect = [window->ns.object convertRectToScreen: rectInView];
+    if (_glfwPlatformWindowFocused(window)) [[window->ns.view inputContext] invalidateCharacterCoordinates];
 }
 
 - (NSArray*)validAttributesForMarkedText
@@ -1507,21 +1509,35 @@ void _glfwPlatformUpdateIMEState(_GLFWwindow *w, const GLFWIMEUpdateEvent *ev) {
 
 - (void)insertText:(id)string replacementRange:(NSRange)replacementRange
 {
-    (void)replacementRange;
-    NSString* characters;
-    if ([string isKindOfClass:[NSAttributedString class]])
-        characters = [string string];
-    else
-        characters = (NSString*) string;
+    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] && !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", [characters UTF8String]);
+    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
 {
-    (void)selector;
+    debug_key("\n\tdoCommandBySelector: (%s)\n", [NSStringFromSelector(selector) UTF8String]);
 }
 
 @end
@@ -1563,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];
 }
 
@@ -1585,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
@@ -1603,9 +1601,19 @@ 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)];
     [super toggleFullScreen:sender];
+    [self setResizeIncrements:original];
+    // When the window decoration is hidden, toggling fullscreen causes the style mask to be changed,
+    // and causes the first responder to be cleared.
+    if (glfw_window && !glfw_window->decorated && glfw_window->ns.view) [self makeFirstResponder:glfw_window->ns.view];
 }
 
 @end
@@ -1809,8 +1817,7 @@ void _glfwPlatformSetWindowIcon(_GLFWwindow* window UNUSED,
 
 void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos)
 {
-    const NSRect contentRect =
-        [window->ns.object contentRectForFrameRect:[window->ns.object frame]];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
 
     if (xpos)
         *xpos = (int)contentRect.origin.x;
@@ -1820,7 +1827,7 @@ void _glfwPlatformGetWindowPos(_GLFWwindow* window, int* xpos, int* ypos)
 
 void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y)
 {
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
     const NSRect dummyRect = NSMakeRect(x, _glfwTransformYNS(y + contentRect.size.height - 1), 0, 0);
     const NSRect frameRect = [window->ns.object frameRectForContentRect:dummyRect];
     [window->ns.object setFrameOrigin:frameRect.origin];
@@ -1828,7 +1835,7 @@ void _glfwPlatformSetWindowPos(_GLFWwindow* window, int x, int y)
 
 void _glfwPlatformGetWindowSize(_GLFWwindow* window, int* width, int* height)
 {
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
 
     if (width)
         *width = (int)contentRect.size.width;
@@ -1845,8 +1852,9 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
     }
     else
     {
-        NSRect contentRect =
-            [window->ns.object contentRectForFrameRect:[window->ns.object frame]];
+        // Disable window resizing in fullscreen.
+        if ([window->ns.object styleMask] & NSWindowStyleMaskFullScreen || window->ns.in_traditional_fullscreen) return;
+        NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
         contentRect.origin.y += contentRect.size.height - height;
         contentRect.size = NSMakeSize(width, height);
         [window->ns.object setFrame:[window->ns.object frameRectForContentRect:contentRect]
@@ -1879,15 +1887,18 @@ void _glfwPlatformSetWindowAspectRatio(_GLFWwindow* window, int numer, int denom
 
 void _glfwPlatformSetWindowSizeIncrements(_GLFWwindow* window, int widthincr, int heightincr)
 {
-    if (widthincr != GLFW_DONT_CARE && heightincr != GLFW_DONT_CARE)
-        [window->ns.object setResizeIncrements:NSMakeSize(widthincr, heightincr)];
-    else
+    if (widthincr != GLFW_DONT_CARE && heightincr != GLFW_DONT_CARE) {
+        float xscale = 1, yscale = 1;
+        _glfwPlatformGetWindowContentScale(window, &xscale, &yscale);
+        [window->ns.object setResizeIncrements:NSMakeSize(widthincr / xscale, heightincr / yscale)];
+    } else {
         [window->ns.object setResizeIncrements:NSMakeSize(1.0, 1.0)];
+    }
 }
 
 void _glfwPlatformGetFramebufferSize(_GLFWwindow* window, int* width, int* height)
 {
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
     const NSRect fbRect = [window->ns.view convertRectToBacking:contentRect];
 
     if (width)
@@ -1900,7 +1911,7 @@ void _glfwPlatformGetWindowFrameSize(_GLFWwindow* window,
                                      int* left, int* top,
                                      int* right, int* bottom)
 {
-    const NSRect contentRect = [window->ns.view frame];
+    const NSRect contentRect = get_window_size_without_border_in_logical_pixels(window);
     const NSRect frameRect = [window->ns.object frameRectForContentRect:contentRect];
 
     if (left)
@@ -1918,7 +1929,7 @@ void _glfwPlatformGetWindowFrameSize(_GLFWwindow* window,
 void _glfwPlatformGetWindowContentScale(_GLFWwindow* window,
                                         float* xscale, float* yscale)
 {
-    const NSRect points = [window->ns.view frame];
+    const NSRect points = get_window_size_without_border_in_logical_pixels(window);
     const NSRect pixels = [window->ns.view convertRectToBacking:points];
 
     if (xscale)
@@ -2402,14 +2413,23 @@ void _glfwPlatformSetCursor(_GLFWwindow* window, _GLFWcursor* cursor UNUSED)
         updateCursorImage(window);
 }
 
+bool _glfwPlatformIsFullscreen(_GLFWwindow* w, unsigned int flags) {
+    NSWindow *window = w->ns.object;
+    bool traditional = !(flags & 1);
+    if (traditional) { if(@available(macOS 10.15.7, *)) return w->ns.in_traditional_fullscreen; }
+    NSWindowStyleMask sm = [window styleMask];
+    return sm & NSWindowStyleMaskFullScreen;
+}
+
 bool _glfwPlatformToggleFullscreen(_GLFWwindow* w, unsigned int flags) {
     NSWindow *window = w->ns.object;
     bool made_fullscreen = true;
     bool traditional = !(flags & 1);
     NSWindowStyleMask sm = [window styleMask];
     if (traditional) {
-        if (@available(macOS 10.16, *)) {
+        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];
@@ -2422,9 +2442,6 @@ bool _glfwPlatformToggleFullscreen(_GLFWwindow* w, unsigned int flags) {
                 [[NSApplication sharedApplication] setPresentationOptions: NSApplicationPresentationDefault];
                 w->ns.in_traditional_fullscreen = false;
             }
-            // for some reason despite calling this selector, the window doesnt actually get keyboard focus till you click on it.
-            // presumably a bug with NSWindowStyleMaskBorderless windows
-            [window performSelector:@selector(makeKeyAndOrderFront:) withObject:nil afterDelay:0];
         } else {
             bool in_fullscreen = sm & NSWindowStyleMaskFullScreen;
             if (!(in_fullscreen)) {
@@ -2437,6 +2454,12 @@ bool _glfwPlatformToggleFullscreen(_GLFWwindow* w, unsigned int flags) {
             }
             [window setStyleMask: sm];
         }
+        // Changing the style mask causes the first responder to be cleared
+        [window makeFirstResponder:w->ns.view];
+        // If the dock and menubar are hidden going from maximized to fullscreen doesnt change the window size
+        // and macOS forgets to trigger windowDidResize, so call it ourselves
+        NSNotification *notification = [NSNotification notificationWithName:NSWindowDidResizeNotification object:window];
+        [w->ns.delegate performSelector:@selector(windowDidResize:) withObject:notification afterDelay:0];
     } else {
         bool in_fullscreen = sm & NSWindowStyleMaskFullScreen;
         if (in_fullscreen) made_fullscreen = false;
@@ -2669,10 +2692,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

@@ -6,7 +6,7 @@ import json
 import os
 import re
 import sys
-from typing import Callable, Dict, List, Optional, Tuple
+from typing import Callable, Dict, List, NamedTuple, Optional, Sequence, Tuple
 
 _plat = sys.platform.lower()
 is_linux = 'linux' in _plat
@@ -14,9 +14,23 @@ is_openbsd = 'openbsd' in _plat
 base = os.path.dirname(os.path.abspath(__file__))
 
 
+class CompileKey(NamedTuple):
+    src: str
+    dest: str
+
+
+class Command(NamedTuple):
+    desc: str
+    cmd: Sequence[str]
+    is_newer_func: Callable[[], bool]
+    on_success: Callable[[], None] = lambda: None
+    key: Optional[CompileKey] = None
+    keyfile: Optional[str] = None
+
+
 class Env:
 
-    cc: str = ''
+    cc: List[str] = []
     cppflags: List[str] = []
     cflags: List[str] = []
     ldflags: List[str] = []
@@ -33,11 +47,12 @@ class Env:
     wayland_protocols: Tuple[str, ...] = ()
 
     def __init__(
-        self, cc: str = '', cppflags: List[str] = [], cflags: List[str] = [], ldflags: List[str] = [],
+        self, cc: List[str] = [], cppflags: List[str] = [], cflags: List[str] = [], ldflags: List[str] = [],
         library_paths: Dict[str, List[str]] = {}, ldpaths: Optional[List[str]] = None, ccver: Tuple[int, int] = (0, 0)
     ):
         self.cc, self.cppflags, self.cflags, self.ldflags, self.library_paths = cc, cppflags, cflags, ldflags, library_paths
-        self.ldpaths, self.ccver = [] if ldpaths is None else ldpaths, ccver
+        self.ldpaths = ldpaths or []
+        self.ccver = ccver
 
     def copy(self) -> 'Env':
         ans = Env(self.cc, list(self.cppflags), list(self.cflags), list(self.ldflags), dict(self.library_paths), list(self.ldpaths), self.ccver)
@@ -52,13 +67,20 @@ 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(env: Env, pkg_config: Callable, pkg_version: Callable, at_least_version: Callable, test_compile: Callable, module: str = 'x11') -> Env:
+def init_env(
+    env: Env,
+    pkg_config: Callable[..., List[str]],
+    pkg_version: Callable[[str], Tuple[int, int]],
+    at_least_version: Callable[..., None],
+    test_compile: Callable[..., bool],
+    module: str = 'x11'
+) -> 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:
@@ -89,7 +111,7 @@ def init_env(env: Env, pkg_config: Callable, pkg_version: Callable, at_least_ver
 
     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':
@@ -117,21 +139,26 @@ def init_env(env: Env, pkg_config: Callable, pkg_version: Callable, at_least_ver
     return ans
 
 
-def build_wayland_protocols(env: Env, Command: Callable, parallel_run: Callable, emphasis: Callable, newer: Callable, dest_dir: str) -> None:
+def build_wayland_protocols(
+    env: Env,
+    parallel_run: Callable[[List[Command]], None],
+    emphasis: Callable[[str], str],
+    newer: Callable[..., bool],
+    dest_dir: str
+) -> None:
     items = []
     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))),
-                    [env.wayland_scanner, q, src, dest],
-                    lambda: True, None, None, None))
+                    f'Generating {emphasis(os.path.basename(dest))} ...',
+                    [env.wayland_scanner, q, src, dest], lambda: True))
     if items:
         parallel_run(items)
 
@@ -147,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:
@@ -206,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)
@@ -250,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*);
@@ -265,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

@@ -1245,6 +1245,10 @@ typedef struct GLFWkeyevent
     //   A value of GLFW_IME_PREEDIT_CHANGED means the pre-edit text for the input event has been changed.
     //   A value of GLFW_IME_COMMIT_TEXT means the text should be committed.
     GLFWIMEState ime_state;
+
+    // For internal use only. On Linux it is the actual keycode reported by the windowing system, in contrast
+    // to native_key which can be the result of a compose operation. On macOS it is the same as native_key.
+    uint32_t native_key_id;
 } GLFWkeyevent;
 
 /*! @brief The function pointer type for error callbacks.
@@ -2752,6 +2756,7 @@ GLFWAPI void glfwWindowHintString(int hint, const char* value);
  */
 GLFWAPI GLFWwindow* glfwCreateWindow(int width, int height, const char* title, GLFWmonitor* monitor, GLFWwindow* share);
 GLFWAPI bool glfwToggleFullscreen(GLFWwindow *window, unsigned int flags);
+GLFWAPI bool glfwIsFullscreen(GLFWwindow *window, unsigned int flags);
 
 /*! @brief Destroys the specified window and its context.
  *
@@ -4114,6 +4119,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/glx_context.c

@@ -48,7 +48,7 @@ static int getGLXFBConfigAttrib(GLXFBConfig fbconfig, int attrib)
 }
 
 static GLXFBConfig*
-choose_fb_config(const _GLFWfbconfig* desired, bool trust_window_bit, int *nelements) {
+choose_fb_config(const _GLFWfbconfig* desired, bool trust_window_bit, int *nelements, bool use_best_color_depth) {
     int attrib_list[64];
     int pos = 0;
 #define ATTR(x, y) { attrib_list[pos++] = x; attrib_list[pos++] = y; }
@@ -59,10 +59,16 @@ choose_fb_config(const _GLFWfbconfig* desired, bool trust_window_bit, int *nelem
     if (_glfw.glx.ARB_multisample && desired->samples > 0) ATTR(GLX_SAMPLES, desired->samples);
     if (desired->depthBits != GLFW_DONT_CARE) ATTR(GLX_DEPTH_SIZE, desired->depthBits);
     if (desired->stencilBits != GLFW_DONT_CARE) ATTR(GLX_STENCIL_SIZE, desired->stencilBits);
-    if (desired->redBits != GLFW_DONT_CARE) ATTR(GLX_RED_SIZE, desired->redBits);
-    if (desired->greenBits != GLFW_DONT_CARE) ATTR(GLX_GREEN_SIZE, desired->greenBits);
-    if (desired->blueBits != GLFW_DONT_CARE) ATTR(GLX_BLUE_SIZE, desired->blueBits);
-    if (desired->alphaBits != GLFW_DONT_CARE) ATTR(GLX_ALPHA_SIZE, desired->alphaBits);
+    if (use_best_color_depth) {
+        // we just ask for the highest available R+G+B+A color depth. This hopefully
+        // works with 10bit (r=10, g=10, b=19, a=2) visuals
+        ATTR(GLX_RED_SIZE, 1); ATTR(GLX_GREEN_SIZE, 1); ATTR(GLX_BLUE_SIZE, 1); ATTR(GLX_ALPHA_SIZE, 1);
+    } else {
+        if (desired->redBits != GLFW_DONT_CARE) ATTR(GLX_RED_SIZE, desired->redBits);
+        if (desired->greenBits != GLFW_DONT_CARE) ATTR(GLX_GREEN_SIZE, desired->greenBits);
+        if (desired->blueBits != GLFW_DONT_CARE) ATTR(GLX_BLUE_SIZE, desired->blueBits);
+        if (desired->alphaBits != GLFW_DONT_CARE) ATTR(GLX_ALPHA_SIZE, desired->alphaBits);
+    }
     if (desired->accumRedBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_RED_SIZE, desired->accumRedBits);
     if (desired->accumGreenBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_GREEN_SIZE, desired->accumGreenBits);
     if (desired->accumBlueBits != GLFW_DONT_CARE) ATTR(GLX_ACCUM_BLUE_SIZE, desired->accumBlueBits);
@@ -96,11 +102,15 @@ static bool chooseGLXFBConfig(const _GLFWfbconfig* desired,
     vendor = glXGetClientString(_glfw.x11.display, GLX_VENDOR);
     if (vendor && strcmp(vendor, "Chromium") == 0)
         trustWindowBit = false;
-    nativeConfigs = choose_fb_config(desired, trustWindowBit, &nativeCount);
+    nativeConfigs = choose_fb_config(desired, trustWindowBit, &nativeCount, false);
     if (!nativeConfigs || !nativeCount)
     {
-        _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: No GLXFBConfigs returned");
-        return false;
+        nativeConfigs = choose_fb_config(desired, trustWindowBit, &nativeCount, true);
+
+        if (!nativeConfigs || !nativeCount) {
+            _glfwInputError(GLFW_API_UNAVAILABLE, "GLX: No GLXFBConfigs returned");
+            return false;
+        }
     }
     for (i = 0;  i < nativeCount;  i++)
     {

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>
@@ -49,6 +60,70 @@ enum Capabilities {
     IBUS_CAP_SURROUNDING_TEXT   = 1 << 5
 };
 
+typedef enum
+{
+    IBUS_SHIFT_MASK    = 1 << 0,
+    IBUS_LOCK_MASK     = 1 << 1,
+    IBUS_CONTROL_MASK  = 1 << 2,
+    IBUS_MOD1_MASK     = 1 << 3,
+    IBUS_MOD2_MASK     = 1 << 4,
+    IBUS_MOD3_MASK     = 1 << 5,
+    IBUS_MOD4_MASK     = 1 << 6,
+    IBUS_MOD5_MASK     = 1 << 7,
+    IBUS_BUTTON1_MASK  = 1 << 8,
+    IBUS_BUTTON2_MASK  = 1 << 9,
+    IBUS_BUTTON3_MASK  = 1 << 10,
+    IBUS_BUTTON4_MASK  = 1 << 11,
+    IBUS_BUTTON5_MASK  = 1 << 12,
+
+    /* The next few modifiers are used by XKB, so we skip to the end.
+     * Bits 15 - 23 are currently unused. Bit 29 is used internally.
+     */
+
+    /* ibus mask */
+    IBUS_HANDLED_MASK  = 1 << 24,
+    IBUS_FORWARD_MASK  = 1 << 25,
+    IBUS_IGNORED_MASK  = IBUS_FORWARD_MASK,
+
+    IBUS_SUPER_MASK    = 1 << 26,
+    IBUS_HYPER_MASK    = 1 << 27,
+    IBUS_META_MASK     = 1 << 28,
+
+    IBUS_RELEASE_MASK  = 1 << 30,
+
+    IBUS_MODIFIER_MASK = 0x5f001fff
+} IBusModifierType;
+
+
+static uint32_t
+ibus_key_state_from_glfw(unsigned int glfw_modifiers, int action) {
+    uint32_t ans = action == GLFW_RELEASE ? IBUS_RELEASE_MASK : 0;
+#define M(g, i) if(glfw_modifiers & GLFW_MOD_##g) ans |= i
+    M(SHIFT, IBUS_SHIFT_MASK);
+    M(CAPS_LOCK, IBUS_LOCK_MASK);
+    M(CONTROL, IBUS_CONTROL_MASK);
+    M(ALT, IBUS_MOD1_MASK);
+    M(NUM_LOCK, IBUS_MOD2_MASK);
+    M(SUPER, IBUS_MOD4_MASK);
+    /* To do: figure out how to get super/hyper/meta */
+#undef M
+    return ans;
+}
+
+static unsigned int
+glfw_modifiers_from_ibus_state(uint32_t ibus_key_state) {
+    unsigned int ans = 0;
+#define M(g, i) if(ibus_key_state & i) ans |= GLFW_MOD_##g
+    M(SHIFT, IBUS_SHIFT_MASK);
+    M(CAPS_LOCK, IBUS_LOCK_MASK);
+    M(CONTROL, IBUS_CONTROL_MASK);
+    M(ALT, IBUS_MOD1_MASK);
+    M(NUM_LOCK, IBUS_MOD2_MASK);
+    M(SUPER, IBUS_MOD4_MASK);
+    /* To do: figure out how to get super/hyper/meta */
+#undef M
+    return ans;
+}
 
 static bool
 test_env_var(const char *name, const char *val) {
@@ -106,6 +181,29 @@ get_ibus_text_from_message(DBusMessage *msg) {
     return text;
 }
 
+static void
+handle_ibus_forward_key_event(DBusMessage *msg) {
+    uint32_t keysym, keycode, state;
+    DBusMessageIter iter;
+    dbus_message_iter_init(msg, &iter);
+
+    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_UINT32) return;
+    dbus_message_iter_get_basic(&iter, &keysym);
+    dbus_message_iter_next(&iter);
+
+    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_UINT32) return;
+    dbus_message_iter_get_basic(&iter, &keycode);
+    dbus_message_iter_next(&iter);
+
+    if (dbus_message_iter_get_arg_type(&iter) != DBUS_TYPE_UINT32) return;
+    dbus_message_iter_get_basic(&iter, &state);
+
+    int mods = glfw_modifiers_from_ibus_state(state);
+
+    debug("IBUS: ForwardKeyEvent: keysym=%x, keycode=%x, state=%x, glfw_mods=%x\n", keysym, keycode, state, mods);
+    glfw_xkb_forwarded_key_from_ime(keysym, mods);
+}
+
 static void
 send_text(const char *text, GLFWIMEState ime_state) {
     _GLFWwindow *w = _glfwFocusedWindow();
@@ -126,7 +224,7 @@ message_handler(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data)
     _GLFWIBUSData *ibus = (_GLFWIBUSData*)user_data;
     (void)ibus;
     const char *text;
-    switch(glfw_dbus_match_signal(msg, IBUS_INPUT_INTERFACE, "CommitText", "UpdatePreeditText", "HidePreeditText", "ShowPreeditText", NULL)) {
+    switch(glfw_dbus_match_signal(msg, IBUS_INPUT_INTERFACE, "CommitText", "UpdatePreeditText", "HidePreeditText", "ShowPreeditText", "ForwardKeyEvent", NULL)) {
         case 0:
             text = get_ibus_text_from_message(msg);
             debug("IBUS: CommitText: '%s'\n", text ? text : "(nil)");
@@ -134,19 +232,53 @@ message_handler(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data)
             break;
         case 1:
             text = get_ibus_text_from_message(msg);
-            send_text(text, GLFW_IME_PREEDIT_CHANGED);
             debug("IBUS: UpdatePreeditText: '%s'\n", text ? text : "(nil)");
+            send_text(text, GLFW_IME_PREEDIT_CHANGED);
             break;
         case 2:
             debug("IBUS: HidePreeditText\n");
+            send_text("", GLFW_IME_PREEDIT_CHANGED);
             break;
         case 3:
             debug("IBUS: ShowPreeditText\n");
             break;
+        case 4:
+            handle_ibus_forward_key_event(msg);
+            break;
     }
     return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
 }
 
+static DBusHandlerResult
+ibus_on_owner_change(DBusConnection* conn UNUSED, DBusMessage* msg, void* user_data) {
+    if (dbus_message_is_signal(msg, "org.freedesktop.DBus", "NameOwnerChanged")) {
+        const char* name;
+        const char* old_owner;
+        const char* new_owner;
+
+        if (!dbus_message_get_args(msg, NULL,
+            DBUS_TYPE_STRING, &name,
+            DBUS_TYPE_STRING, &old_owner,
+            DBUS_TYPE_STRING, &new_owner,
+            DBUS_TYPE_INVALID
+        )) {
+            return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+        }
+
+        if (strcmp(name, "org.freedesktop.IBus") != 0) {
+            return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+        }
+
+        _GLFWIBUSData* ibus = (_GLFWIBUSData*) user_data;
+        ibus->name_owner_changed = true;
+
+        return DBUS_HANDLER_RESULT_HANDLED;
+
+    }
+
+    return DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
+}
+
 static const char*
 get_ibus_address_file_name(void) {
     const char *addr;
@@ -243,6 +375,8 @@ input_context_created(DBusMessage *msg, const char* errmsg, void *data) {
     free((void*)ibus->input_ctx_path);
     ibus->input_ctx_path = _glfw_strdup(path);
     if (!ibus->input_ctx_path) return;
+    dbus_bus_add_match(ibus->conn, "type='signal',interface='org.freedesktop.DBus', member='NameOwnerChanged'", NULL);
+    dbus_connection_add_filter(ibus->conn, ibus_on_owner_change, ibus, free);
     dbus_bus_add_match(ibus->conn, "type='signal',interface='org.freedesktop.IBus.InputContext'", NULL);
     DBusObjectPathVTable ibus_vtable = {.message_function = message_handler};
     dbus_connection_try_register_object_path(ibus->conn, ibus->input_ctx_path, &ibus_vtable, ibus, NULL);
@@ -285,6 +419,7 @@ glfw_connect_to_ibus(_GLFWIBUSData *ibus) {
     if (ibus->inited) return;
     if (!test_env_var("GLFW_IM_MODULE", "ibus")) return;
     ibus->inited = true;
+    ibus->name_owner_changed = false;
     setup_connection(ibus);
 }
 
@@ -306,13 +441,12 @@ glfw_ibus_terminate(_GLFWIBUSData *ibus) {
 static bool
 check_connection(_GLFWIBUSData *ibus) {
     if (!ibus->inited) return false;
-    if (ibus->conn && dbus_connection_get_is_connected(ibus->conn)) {
-        return ibus->ok;
-    }
+    if (ibus->conn && dbus_connection_get_is_connected(ibus->conn) && !ibus->name_owner_changed) return ibus->ok;
     struct stat s;
+    ibus->name_owner_changed = false;
     if (stat(ibus->address_file_name, &s) != 0 || s.st_mtime != ibus->address_file_mtime) {
         if (!read_ibus_address(ibus)) return false;
-        setup_connection(ibus);
+        return setup_connection(ibus);
     }
     return false;
 }
@@ -344,56 +478,6 @@ glfw_ibus_set_cursor_geometry(_GLFWIBUSData *ibus, int x, int y, int w, int h) {
     }
 }
 
-typedef enum
-{
-    IBUS_SHIFT_MASK    = 1 << 0,
-    IBUS_LOCK_MASK     = 1 << 1,
-    IBUS_CONTROL_MASK  = 1 << 2,
-    IBUS_MOD1_MASK     = 1 << 3,
-    IBUS_MOD2_MASK     = 1 << 4,
-    IBUS_MOD3_MASK     = 1 << 5,
-    IBUS_MOD4_MASK     = 1 << 6,
-    IBUS_MOD5_MASK     = 1 << 7,
-    IBUS_BUTTON1_MASK  = 1 << 8,
-    IBUS_BUTTON2_MASK  = 1 << 9,
-    IBUS_BUTTON3_MASK  = 1 << 10,
-    IBUS_BUTTON4_MASK  = 1 << 11,
-    IBUS_BUTTON5_MASK  = 1 << 12,
-
-    /* The next few modifiers are used by XKB, so we skip to the end.
-     * Bits 15 - 23 are currently unused. Bit 29 is used internally.
-     */
-
-    /* ibus mask */
-    IBUS_HANDLED_MASK  = 1 << 24,
-    IBUS_FORWARD_MASK  = 1 << 25,
-    IBUS_IGNORED_MASK  = IBUS_FORWARD_MASK,
-
-    IBUS_SUPER_MASK    = 1 << 26,
-    IBUS_HYPER_MASK    = 1 << 27,
-    IBUS_META_MASK     = 1 << 28,
-
-    IBUS_RELEASE_MASK  = 1 << 30,
-
-    IBUS_MODIFIER_MASK = 0x5f001fff
-} IBusModifierType;
-
-
-static uint32_t
-ibus_key_state(unsigned int glfw_modifiers, int action) {
-    uint32_t ans = action == GLFW_RELEASE ? IBUS_RELEASE_MASK : 0;
-#define M(g, i) if(glfw_modifiers & GLFW_MOD_##g) ans |= i
-    M(SHIFT, IBUS_SHIFT_MASK);
-    M(CAPS_LOCK, IBUS_LOCK_MASK);
-    M(CONTROL, IBUS_CONTROL_MASK);
-    M(ALT, IBUS_MOD1_MASK);
-    M(NUM_LOCK, IBUS_MOD2_MASK);
-    M(SUPER, IBUS_MOD4_MASK);
-    /* To do: figure out how to get super/hyper/meta */
-#undef M
-    return ans;
-}
-
 void
 key_event_processed(DBusMessage *msg, const char* errmsg, void *data) {
     uint32_t handled = 0;
@@ -422,7 +506,7 @@ ibus_process_key(const _GLFWIBUSKeyEvent *ev_, _GLFWIBUSData *ibus) {
     // Put the key's text in a field IN the structure, for proper serialization.
     if (ev->glfw_ev.text) strncpy(ev->__embedded_text, ev->glfw_ev.text, sizeof(ev->__embedded_text) - 1);
     ev->glfw_ev.text = NULL;
-    uint32_t state = ibus_key_state(ev->glfw_ev.mods, ev->glfw_ev.action);
+    uint32_t state = ibus_key_state_from_glfw(ev->glfw_ev.mods, ev->glfw_ev.action);
     if (!glfw_dbus_call_method_with_reply(
             ibus->conn, IBUS_SERVICE, ibus->input_ctx_path, IBUS_INPUT_INTERFACE, "ProcessKeyEvent",
             3000, key_event_processed, ev,

glfw/ibus_glfw.h

@@ -32,7 +32,7 @@
 #include <xkbcommon/xkbcommon.h>
 
 typedef struct {
-    bool ok, inited;
+    bool ok, inited, name_owner_changed;
     time_t address_file_mtime;
     DBusConnection *conn;
     const char *input_ctx_path, *address_file_name, *address;

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

@@ -274,11 +274,11 @@ static bool parseMapping(_GLFWmapping* mapping, const char* string)
 //////////////////////////////////////////////////////////////////////////
 
 static void
-set_key_action(_GLFWwindow *window, uint32_t key, int val, int idx) {
+set_key_action(_GLFWwindow *window, const GLFWkeyevent *ev, int action, int idx) {
     const unsigned sz = arraysz(window->activated_keys);
     if (idx < 0) {
         for (unsigned i = 0; i < sz; i++) {
-            if (window->activated_keys[i].key == 0) {
+            if (window->activated_keys[i].native_key_id == 0) {
                 idx = i;
                 break;
             }
@@ -286,18 +286,18 @@ set_key_action(_GLFWwindow *window, uint32_t key, int val, int idx) {
         if (idx < 0) {
             idx = sz - 1;
             memmove(window->activated_keys, window->activated_keys + 1, sizeof(window->activated_keys[0]) * (sz - 1));
-            window->activated_keys[sz - 1].key = key;
+            window->activated_keys[sz - 1].native_key_id = 0;
         }
     }
-    if (val == GLFW_RELEASE) {
+    if (action == GLFW_RELEASE) {
         memset(window->activated_keys + idx, 0, sizeof(window->activated_keys[0]));
         if (idx < (int)sz - 1) {
             memmove(window->activated_keys + idx, window->activated_keys + idx + 1, sizeof(window->activated_keys[0]) * (sz - 1 - idx));
             memset(window->activated_keys + sz - 1, 0, sizeof(window->activated_keys[0]));
         }
     } else {
-        window->activated_keys[idx].key = key;
-        window->activated_keys[idx].action = val;
+        window->activated_keys[idx] = *ev;
+        window->activated_keys[idx].text = NULL;
     }
 }
 
@@ -305,30 +305,39 @@ set_key_action(_GLFWwindow *window, uint32_t key, int val, int idx) {
 //
 void _glfwInputKeyboard(_GLFWwindow* window, GLFWkeyevent* ev)
 {
-    if (ev->key > 0)
+    if (ev->native_key_id > 0)
     {
         bool repeated = false;
         int idx = -1;
         int current_action = GLFW_RELEASE;
         const unsigned sz = arraysz(window->activated_keys);
         for (unsigned i = 0; i < sz; i++) {
-            if (window->activated_keys[i].key == ev->key) {
+            if (window->activated_keys[i].native_key_id == ev->native_key_id) {
                 idx = i;
                 current_action = window->activated_keys[i].action;
                 break;
             }
         }
 
-        if (ev->action == GLFW_RELEASE && current_action == GLFW_RELEASE)
-            return;
+        if (ev->action == GLFW_RELEASE) {
+            if (current_action == GLFW_RELEASE) return;
+            if (idx > -1) {
+                const GLFWkeyevent *press_event = window->activated_keys + idx;
+                if (press_event->action == GLFW_PRESS || press_event->action == GLFW_REPEAT) {
+                    // Compose sequences under X11 give a different key value for press and release events
+                    // but we want the same key value so override it.
+                    ev->native_key = press_event->native_key;
+                    ev->key = press_event->key;
+                    ev->shifted_key = press_event->shifted_key;
+                    ev->alternate_key = press_event->alternate_key;
+                }
+            }
+        }
 
         if (ev->action == GLFW_PRESS && current_action == GLFW_PRESS)
             repeated = true;
 
-        if (ev->action == GLFW_RELEASE && window->stickyKeys)
-            set_key_action(window, ev->key, _GLFW_STICK, idx);
-        else
-            set_key_action(window, ev->key, ev->action, idx);
+        set_key_action(window, ev, (ev->action == GLFW_RELEASE && window->stickyKeys) ? _GLFW_STICK : ev->action, idx);
 
         if (repeated)
             ev->action = GLFW_REPEAT;
@@ -658,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;
@@ -823,7 +840,8 @@ GLFWAPI GLFWKeyAction glfwGetKey(GLFWwindow* handle, uint32_t key)
     if (current_action == _GLFW_STICK)
     {
         // Sticky mode: release key now
-        set_key_action(window, key, GLFW_RELEASE, idx);
+        GLFWkeyevent ev = {0};
+        set_key_action(window, &ev, GLFW_RELEASE, idx);
         current_action = GLFW_PRESS;
     }
 

glfw/internal.h

@@ -402,11 +402,6 @@ struct _GLFWcontext
     _GLFWcontextOSMesa osmesa;
 };
 
-typedef struct GLFWKeyState {
-    uint32_t key;
-    char action;
-} GLFWKeyState;
-
 // Window and context structure
 //
 struct _GLFWwindow
@@ -437,7 +432,7 @@ struct _GLFWwindow
     bool                lockKeyMods;
     int                 cursorMode;
     char                mouseButtons[GLFW_MOUSE_BUTTON_LAST + 1];
-    GLFWKeyState        activated_keys[16];
+    GLFWkeyevent        activated_keys[16];
     // Virtual cursor position when cursor is disabled
     double              virtualCursorPosX, virtualCursorPosY;
     bool                rawMouseMotion;
@@ -589,6 +584,8 @@ struct _GLFWlibrary
     _GLFWtls            contextSlot;
     _GLFWmutex          errorLock;
 
+    bool                ignoreOSKeyboardProcessing;
+
     struct {
         bool            available;
         void*           handle;
@@ -717,6 +714,7 @@ void _glfwPlatformSetWindowMonitor(_GLFWwindow* window, _GLFWmonitor* monitor,
                                    int xpos, int ypos, int width, int height,
                                    int refreshRate);
 bool _glfwPlatformToggleFullscreen(_GLFWwindow *w, unsigned int flags);
+bool _glfwPlatformIsFullscreen(_GLFWwindow *w, unsigned int flags);
 int _glfwPlatformWindowFocused(_GLFWwindow* window);
 int _glfwPlatformWindowOccluded(_GLFWwindow* window);
 int _glfwPlatformWindowIconified(_GLFWwindow* window);

glfw/linux_notify.c

@@ -35,10 +35,10 @@ notification_created(DBusMessage *msg, const char* errmsg, void *data) {
         if (data) free(data);
         return;
     }
-    uint32_t notification_id;
-    if (!glfw_dbus_get_args(msg, "Failed to get Notification uid", DBUS_TYPE_UINT32, &notification_id, DBUS_TYPE_INVALID)) return;
+    uint32_t id;
+    if (!glfw_dbus_get_args(msg, "Failed to get Notification uid", DBUS_TYPE_UINT32, &id, DBUS_TYPE_INVALID)) return;
     NotificationCreatedData *ncd = (NotificationCreatedData*)data;
-    if (ncd->callback) ncd->callback(ncd->next_id, notification_id, ncd->data);
+    if (ncd->callback) ncd->callback(ncd->next_id, id, ncd->data);
     if (data) free(data);
 }
 
@@ -46,12 +46,12 @@ static DBusHandlerResult
 message_handler(DBusConnection *conn UNUSED, DBusMessage *msg, void *user_data UNUSED) {
     /* printf("session_bus message_handler invoked interface: %s member: %s\n", dbus_message_get_interface(msg), dbus_message_get_member(msg)); */
     if (dbus_message_is_signal(msg, NOTIFICATIONS_IFACE, "ActionInvoked")) {
-        uint32_t notification_id;
+        uint32_t id;
         const char *action;
         if (glfw_dbus_get_args(msg, "Failed to get args from ActionInvoked notification signal",
-                    DBUS_TYPE_UINT32, &notification_id, DBUS_TYPE_STRING, &action, DBUS_TYPE_INVALID)) {
+                    DBUS_TYPE_UINT32, &id, DBUS_TYPE_STRING, &action, DBUS_TYPE_INVALID)) {
             if (activated_handler) {
-                activated_handler(notification_id, action);
+                activated_handler(id, action);
                 return DBUS_HANDLER_RESULT_HANDLED;
             }
         }

glfw/window.c

@@ -1058,6 +1058,10 @@ GLFWAPI bool glfwToggleFullscreen(GLFWwindow* wh, unsigned int flags) {
     return false;
 }
 
+GLFWAPI bool glfwIsFullscreen(GLFWwindow* wh, unsigned int flags) {
+    return _glfwPlatformIsFullscreen((_GLFWwindow*)wh, flags);
+}
+
 GLFWAPI void glfwSetWindowUserPointer(GLFWwindow* handle, void* pointer)
 {
     _GLFWwindow* window = (_GLFWwindow*) handle;

glfw/wl_init.c

@@ -331,20 +331,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,
@@ -571,7 +634,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

@@ -212,6 +212,11 @@ typedef struct _GLFWwindowWayland
 
     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;
 
 } _GLFWwindowWayland;
 
@@ -230,7 +235,7 @@ typedef struct _GLFWWaylandDataOffer
     size_t idx;
     bool is_self_offer;
     bool is_primary;
-    const char *plain_text_mime, *mime_for_drop;
+    const char *mime_for_drop;
     uint32_t source_actions;
     uint32_t dnd_action;
     struct wl_surface *surface;

glfw/wl_text_input.c

@@ -25,20 +25,20 @@ static void commit(void) {
 }
 
 static void
-text_input_enter(void *data UNUSED, struct zwp_text_input_v3 *text_input UNUSED, struct wl_surface *surface UNUSED) {
+text_input_enter(void *data UNUSED, struct zwp_text_input_v3 *txt_input, struct wl_surface *surface UNUSED) {
     debug("text-input: enter event\n");
-    if (text_input) {
-        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);
+    if (txt_input) {
+        zwp_text_input_v3_enable(txt_input);
+        zwp_text_input_v3_set_content_type(txt_input, ZWP_TEXT_INPUT_V3_CONTENT_HINT_NONE, ZWP_TEXT_INPUT_V3_CONTENT_PURPOSE_TERMINAL);
         commit();
     }
 }
 
 static void
-text_input_leave(void *data UNUSED, struct zwp_text_input_v3 *text_input UNUSED, struct wl_surface *surface UNUSED) {
+text_input_leave(void *data UNUSED, struct zwp_text_input_v3 *txt_input, struct wl_surface *surface UNUSED) {
     debug("text-input: leave event\n");
-    if (text_input) {
-        zwp_text_input_v3_disable(text_input);
+    if (txt_input) {
+        zwp_text_input_v3_disable(txt_input);
         commit();
     }
 }
@@ -57,7 +57,7 @@ send_text(const char *text, GLFWIMEState ime_state) {
 static void
 text_input_preedit_string(
         void                     *data UNUSED,
-        struct zwp_text_input_v3 *text_input UNUSED,
+        struct zwp_text_input_v3 *txt_input UNUSED,
         const char               *text,
         int32_t                  cursor_begin,
         int32_t                  cursor_end
@@ -68,7 +68,7 @@ text_input_preedit_string(
 }
 
 static void
-text_input_commit_string(void *data UNUSED, struct zwp_text_input_v3 *text_input UNUSED, const char *text) {
+text_input_commit_string(void *data UNUSED, struct zwp_text_input_v3 *txt_input UNUSED, const char *text) {
     debug("text-input: commit_string event: text: %s\n", text);
     free(pending_commit);
     pending_commit = text ? _glfw_strdup(text) : NULL;
@@ -77,14 +77,14 @@ text_input_commit_string(void *data UNUSED, struct zwp_text_input_v3 *text_input
 static void
 text_input_delete_surrounding_text(
         void *data UNUSED,
-        struct zwp_text_input_v3 *zwp_text_input_v3 UNUSED,
+        struct zwp_text_input_v3 *txt_input UNUSED,
         uint32_t before_length,
         uint32_t after_length) {
     debug("text-input: delete_surrounding_text event: before_length: %u after_length: %u\n", before_length, after_length);
 }
 
 static void
-text_input_done(void *data UNUSED, struct zwp_text_input_v3 *zwp_text_input_v3 UNUSED, uint32_t serial UNUSED) {
+text_input_done(void *data UNUSED, struct zwp_text_input_v3 *txt_input UNUSED, uint32_t serial UNUSED) {
     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);

glfw/wl_window.c

@@ -413,9 +413,15 @@ static void setFullscreen(_GLFWwindow* window, _GLFWmonitor* monitor, bool on)
     setIdleInhibitor(window, on);
 }
 
+
+bool
+_glfwPlatformIsFullscreen(_GLFWwindow *window, unsigned int flags UNUSED) {
+    return window->wl.toplevel_states & TOPLEVEL_STATE_FULLSCREEN;
+}
+
 bool
 _glfwPlatformToggleFullscreen(_GLFWwindow *window, unsigned int flags UNUSED) {
-    bool already_fullscreen = window->wl.toplevel_states & TOPLEVEL_STATE_FULLSCREEN;
+    bool already_fullscreen = _glfwPlatformIsFullscreen(window, flags);
     setFullscreen(window, NULL, !already_fullscreen);
     return !already_fullscreen;
 }
@@ -890,9 +896,9 @@ void _glfwPlatformSetWindowSize(_GLFWwindow* window, int width, int height)
     if (width != window->wl.width || height != window->wl.height) {
         window->wl.user_requested_content_size.width = width;
         window->wl.user_requested_content_size.height = height;
-        int32_t width = 0, height = 0;
-        set_csd_window_geometry(window, &width, &height);
-        window->wl.width = width; window->wl.height = height;
+        int32_t w = 0, h = 0;
+        set_csd_window_geometry(window, &w, &h);
+        window->wl.width = w; window->wl.height = h;
         resizeFramebuffer(window);
         ensure_csd_resources(window);
         wl_surface_commit(window->wl.surface);
@@ -1561,11 +1567,6 @@ static void mark_primary_selection_offer(void *data UNUSED, struct zwp_primary_s
 
 static void
 set_offer_mimetype(_GLFWWaylandDataOffer* offer, const char* mime) {
-    if (strcmp(mime, "text/plain;charset=utf-8") == 0) {
-        offer->plain_text_mime = "text/plain;charset=utf-8";
-    } else if (!offer->plain_text_mime && strcmp(mime, "text/plain")) {
-        offer->plain_text_mime = "text/plain";
-    }
     if (strcmp(mime, clipboard_mime()) == 0) {
         offer->is_self_offer = true;
     }
@@ -1666,9 +1667,9 @@ static void drag_enter(void *data UNUSED, struct wl_data_device *wl_data_device
             while (window)
             {
                 if (window->wl.surface == surface) {
-                    for (size_t x = 0; x < d->mimes_count; x++) {
-                        int prio = _glfwInputDrop(window, d->mimes[x], NULL, 0);
-                        if (prio > format_priority) d->mime_for_drop = d->mimes[x];
+                    for (size_t j = 0; j < d->mimes_count; j++) {
+                        int prio = _glfwInputDrop(window, d->mimes[j], NULL, 0);
+                        if (prio > format_priority) d->mime_for_drop = d->mimes[j];
                     }
                     break;
                 }
@@ -1694,8 +1695,8 @@ static void drop(void *data UNUSED, struct wl_data_device *wl_data_device UNUSED
     for (size_t i = 0; i < arraysz(_glfw.wl.dataOffers); i++) {
         if (_glfw.wl.dataOffers[i].offer_type == DRAG_AND_DROP && _glfw.wl.dataOffers[i].mime_for_drop) {
             size_t sz = 0;
-            char *data = read_data_offer(_glfw.wl.dataOffers[i].id, _glfw.wl.dataOffers[i].mime_for_drop, &sz);
-            if (data) {
+            char *d = read_data_offer(_glfw.wl.dataOffers[i].id, _glfw.wl.dataOffers[i].mime_for_drop, &sz);
+            if (d) {
                 // We dont do finish as this requires version 3 for wl_data_device_manager
                 // which then requires more work with calling set_actions for drag and drop to function
                 // wl_data_offer_finish(_glfw.wl.dataOffers[i].id);
@@ -1704,13 +1705,13 @@ static void drop(void *data UNUSED, struct wl_data_device *wl_data_device UNUSED
                 while (window)
                 {
                     if (window->wl.surface == _glfw.wl.dataOffers[i].surface) {
-                        _glfwInputDrop(window, _glfw.wl.dataOffers[i].mime_for_drop, data, sz);
+                        _glfwInputDrop(window, _glfw.wl.dataOffers[i].mime_for_drop, d, sz);
                         break;
                     }
                     window = window->next;
                 }
 
-                free(data);
+                free(d);
             }
             destroy_data_offer(&_glfw.wl.dataOffers[i]);
             break;
@@ -1814,16 +1815,38 @@ void _glfwPlatformSetClipboardString(const char* string)
     wl_callback_add_listener(callback, &clipboard_copy_callback_listener, _glfw.wl.dataSourceForClipboard);
 }
 
+static bool
+offer_has_mime(const _GLFWWaylandDataOffer *d, const char *mime) {
+    for (unsigned i = 0; i < d->mimes_count; i++) {
+        if (strcmp(d->mimes[i], mime) == 0) return true;
+    }
+    return false;
+}
+
+static const char*
+plain_text_mime_for_offer(const _GLFWWaylandDataOffer *d) {
+#define A(x) if (offer_has_mime(d, x)) return x;
+    A("text/plain;charset=utf-8");
+    A("text/plain");
+    A("UTF8_STRING");
+    A("STRING");
+#undef A
+    return NULL;
+}
+
 const char* _glfwPlatformGetClipboardString(void)
 {
     for (size_t i = 0; i < arraysz(_glfw.wl.dataOffers); i++) {
         _GLFWWaylandDataOffer *d = _glfw.wl.dataOffers + i;
-        if (d->id && d->offer_type == CLIPBOARD && d->plain_text_mime) {
+        if (d->id && d->offer_type == CLIPBOARD) {
             if (d->is_self_offer) return _glfw.wl.clipboardString;
-            free(_glfw.wl.pasteString);
-            size_t sz = 0;
-            _glfw.wl.pasteString = read_data_offer(d->id, d->plain_text_mime, &sz);
-            return _glfw.wl.pasteString;
+            const char *mime = plain_text_mime_for_offer(d);
+            if (mime) {
+                free(_glfw.wl.pasteString);
+                size_t sz = 0;
+                _glfw.wl.pasteString = read_data_offer(d->id, mime, &sz);
+                return _glfw.wl.pasteString;
+            }
         }
     }
     return NULL;
@@ -1871,13 +1894,14 @@ const char* _glfwPlatformGetPrimarySelectionString(void)
 
     for (size_t i = 0; i < arraysz(_glfw.wl.dataOffers); i++) {
         _GLFWWaylandDataOffer *d = _glfw.wl.dataOffers + i;
-        if (d->id && d->is_primary && d->offer_type == PRIMARY_SELECTION && d->plain_text_mime) {
-            if (d->is_self_offer) {
-                return _glfw.wl.primarySelectionString;
+        if (d->id && d->is_primary && d->offer_type == PRIMARY_SELECTION) {
+            if (d->is_self_offer) return _glfw.wl.primarySelectionString;
+            const char *mime = plain_text_mime_for_offer(d);
+            if (mime) {
+                free(_glfw.wl.pasteString);
+                _glfw.wl.pasteString = read_primary_selection_offer(d->id, mime);
+                return _glfw.wl.pasteString;
             }
-            free(_glfw.wl.pasteString);
-            _glfw.wl.pasteString = read_primary_selection_offer(d->id, d->plain_text_mime);
-            return _glfw.wl.pasteString;
         }
     }
     return NULL;

glfw/x11_window.c

@@ -343,6 +343,11 @@ set_fullscreen(_GLFWwindow *window, bool on) {
     }
 }
 
+bool
+_glfwPlatformIsFullscreen(_GLFWwindow *window, unsigned int flags UNUSED) {
+    return is_window_fullscreen(window);
+}
+
 bool
 _glfwPlatformToggleFullscreen(_GLFWwindow *window, unsigned int flags UNUSED) {
     bool already_fullscreen = is_window_fullscreen(window);

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"
@@ -383,22 +383,162 @@ glfw_xkb_update_masks(_GLFWXKBData *xkb) {
 #define xkb_glfw_load_keymap(keymap, map_str) keymap = xkb_keymap_new_from_string(xkb->context, map_str, XKB_KEYMAP_FORMAT_TEXT_V1, 0);
 #define xkb_glfw_load_state(keymap, state) state = xkb_state_new(keymap);
 
+typedef struct {
+    struct xkb_state *state;
+    int failed;
+    xkb_mod_mask_t used_mods;
+    xkb_mod_mask_t shift, control, capsLock, numLock, alt, super, meta, hyper;
+
+    /* Combination modifiers to try */
+    int try_shift;
+    xkb_keycode_t shift_keycode;
+} modifier_mapping_algorithm_t;
+
+/* Algorithm for mapping virtual modifiers to real modifiers:
+ *   1. create new state
+ *   2. for each key in keymap
+ *      a. send key down to state
+ *      b. if it affected exactly one bit in modifier map
+ *         i) get keysym
+ *         ii) if keysym matches one of the known modifiers, save it for that modifier
+ *         iii) if modifier is latched, send key up and key down to toggle again
+ *      c. send key up to reset the state
+ *   3. if shift key found in step 2, run step 2 with all shift+key for each key
+ *   4. if shift, control, alt and super are not all found, declare failure
+ *   5. if failure, use static mapping from xkbcommon-names.h
+ *
+ * Step 3 is needed because many popular keymaps map meta to alt+shift.
+ *
+ * We could do better by constructing a system of linear equations, but it should not be
+ * needed in any sane system. We could also use this algorithm with X11, but X11
+ * provides XkbVirtualModsToReal which is guaranteed to be accurate, while this
+ * algorithm is only a heuristic.
+ *
+ * We don't touch level3 or level5 modifiers.
+ */
+static void modifier_mapping_algorithm( struct xkb_keymap *keymap UNUSED, xkb_keycode_t key, void *data ) {
+    modifier_mapping_algorithm_t *algorithm = ( modifier_mapping_algorithm_t * )data;
+    if ( algorithm->failed )
+        return;
+
+    if ( algorithm->try_shift ) {
+        if ( key == algorithm->shift_keycode ) return;
+        xkb_state_update_key( algorithm->state, algorithm->shift_keycode, XKB_KEY_DOWN );
+    }
+
+    enum xkb_state_component changed_type = xkb_state_update_key( algorithm->state, key, XKB_KEY_DOWN );
+    if ( changed_type & ( XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED | XKB_STATE_MODS_LOCKED ) ) {
+        xkb_mod_mask_t mods = xkb_state_serialize_mods( algorithm->state,
+                                                        algorithm->try_shift ? XKB_STATE_MODS_EFFECTIVE : ( XKB_STATE_MODS_DEPRESSED | XKB_STATE_MODS_LATCHED | XKB_STATE_MODS_LOCKED ) );
+
+        const xkb_keysym_t *keysyms;
+        int num_keysyms = xkb_state_key_get_syms( algorithm->state, key, &keysyms );
+        /* We can handle exactly one keysym with exactly one bit set in the implementation
+         * below; with a lot more gymnastics, we could set up an 8x8 linear system and solve
+         * for each modifier in case there are some modifiers that are only present in
+         * combination with others, but it is not worth the effort. */
+        if ( num_keysyms == 1 && mods && ( mods & ( mods-1 ) ) == 0 ) {
+#define S2( k, a )                                                      \
+            do {                                                        \
+                if ( keysyms[0] == XKB_KEY_##k##_L || keysyms[0] == XKB_KEY_##k##_R ) { \
+                    if ( !algorithm->a )                                \
+                        algorithm->a = mods;                            \
+                    else if ( algorithm->a != mods )                    \
+                        algorithm->failed = 1;                          \
+                }                                                       \
+            } while ( 0 )
+#define S1( k, a ) if ( ( keysyms[0] == XKB_KEY_##k ) && !algorithm->a ) algorithm->a = mods
+            S2( Shift, shift );
+            S2( Control, control );
+            S1( Caps_Lock, capsLock );
+            S1( Shift_Lock, numLock );
+            S2( Alt, alt );
+            S2( Super, super );
+            S2( Meta, meta );
+            S2( Hyper, hyper );
+#undef S1
+#undef S2
+        }
+        if ( !algorithm->shift_keycode && ( keysyms[0] == XKB_KEY_Shift_L || keysyms[0] == XKB_KEY_Shift_R ) )
+            algorithm->shift_keycode = key;
+
+        /* If this is a lock, then up and down to remove lock state*/
+        if ( changed_type & XKB_STATE_MODS_LOCKED ) { /* What should we do for LATCHED here? */
+            xkb_state_update_key( algorithm->state, key, XKB_KEY_UP );
+            xkb_state_update_key( algorithm->state, key, XKB_KEY_DOWN );
+        }
+    }
+    xkb_state_update_key( algorithm->state, key, XKB_KEY_UP );
+
+    if ( algorithm->try_shift ) {
+        xkb_state_update_key( algorithm->state, algorithm->shift_keycode, XKB_KEY_UP );
+    }
+}
+
+static int local_modifier_mapping(_GLFWXKBData *xkb) {
+    modifier_mapping_algorithm_t algorithm;
+
+    algorithm.failed = 0;
+    algorithm.used_mods = 0;
+    algorithm.shift = algorithm.control = algorithm.capsLock = algorithm.numLock = algorithm.alt = algorithm.super = algorithm.meta = algorithm.hyper = 0;
+    algorithm.try_shift = 0;
+    algorithm.shift_keycode = 0;
+
+    algorithm.state = xkb_state_new( xkb->keymap );
+    if ( algorithm.state != NULL )
+    {
+        xkb_keymap_key_for_each( xkb->keymap, &modifier_mapping_algorithm, &algorithm );
+        if ( !algorithm.shift_keycode )
+            algorithm.failed = 1;
+
+        if ( !( algorithm.shift && algorithm.control && algorithm.alt && algorithm.super && algorithm.meta && algorithm.hyper )
+             && !algorithm.failed  ) {
+            algorithm.try_shift = 1;
+            xkb_keymap_key_for_each( xkb->keymap, &modifier_mapping_algorithm, &algorithm );
+        }
+        xkb_state_unref( algorithm.state );
+        if ( !algorithm.failed && !( algorithm.shift && algorithm.control && algorithm.alt && algorithm.super ) )
+            algorithm.failed = 1;     /* must have found at least those 4 modifiers */
+    }
+
+    if ( !algorithm.failed ) {
+#define S( a ) xkb->a##Idx = XKB_MOD_INVALID; xkb->a##Mask = 0
+        S(control); S(shift); S(capsLock); S(alt); S(super); S(hyper); S(meta); S(numLock);
+#undef S
+
+        unsigned indx, shifted, used_bits = 0;
+        for (indx = 0, shifted = 1; indx < 32; ++indx, shifted <<= 1) {
+#define S( a ) if ( (xkb->a##Idx == XKB_MOD_INVALID) && !( used_bits & shifted ) && algorithm.a == shifted  ) xkb->a##Idx = indx, xkb->a##Mask = shifted, used_bits |= shifted
+            S(control); S(shift); S(capsLock); S(alt); S(super); S(hyper); S(meta); S(numLock);
+#undef S
+        }
+    }
+
+    if ( algorithm.failed )
+        debug( "Wayland modifier autodetection algorithm failed; using defaults\n" );
+    return !algorithm.failed;
+}
+
 static void
 glfw_xkb_update_masks(_GLFWXKBData *xkb) {
     // Should find better solution under Wayland
-    // See https://github.com/kovidgoyal/kitty/pull/3430 for discussion
+    // See https://github.com/kovidgoyal/kitty/pull/3943 for discussion
 
+    if ( getenv( "KITTY_WAYLAND_DETECT_MODIFIERS" ) == NULL || !local_modifier_mapping( xkb ) ) {
 #define S( a ) xkb->a##Idx = XKB_MOD_INVALID; xkb->a##Mask = 0
-    S(hyper); S(meta);
+        S(hyper); S(meta);
 #undef S
 #define S(a, n) xkb->a##Idx = xkb_keymap_mod_get_index(xkb->keymap, n); xkb->a##Mask = 1 << xkb->a##Idx;
-    S(control, XKB_MOD_NAME_CTRL);
-    S(shift, XKB_MOD_NAME_SHIFT);
-    S(capsLock, XKB_MOD_NAME_CAPS);
-    S(numLock, XKB_MOD_NAME_NUM);
-    S(alt, XKB_MOD_NAME_ALT);
-    S(super, XKB_MOD_NAME_LOGO);
+        S(control, XKB_MOD_NAME_CTRL);
+        S(shift, XKB_MOD_NAME_SHIFT);
+        S(capsLock, XKB_MOD_NAME_CAPS);
+        S(numLock, XKB_MOD_NAME_NUM);
+        S(alt, XKB_MOD_NAME_ALT);
+        S(super, XKB_MOD_NAME_LOGO);
 #undef S
+    }
+    debug("Modifier indices alt: 0x%x super: 0x%x hyper: 0x%x meta: 0x%x numlock: 0x%x shift: 0x%x capslock: 0x%x control: 0x%x\n",
+          xkb->altIdx, xkb->superIdx, xkb->hyperIdx, xkb->metaIdx, xkb->numLockIdx, xkb->shiftIdx, xkb->capsLockIdx, xkb->controlIdx);
 }
 
 #endif
@@ -687,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),
@@ -702,6 +842,19 @@ glfw_xkb_key_from_ime(_GLFWIBUSKeyEvent *ev, bool handled_by_ime, bool failed) {
       last_handled_press_keycode = ev->glfw_ev.native_key;
 }
 
+void
+glfw_xkb_forwarded_key_from_ime(xkb_keysym_t keysym, unsigned int glfw_mods) {
+    _GLFWwindow *w = _glfwFocusedWindow();
+    if (w && w->callbacks.keyboard) {
+        GLFWkeyevent fake_ev = {.action = GLFW_PRESS};
+        fake_ev.native_key = keysym;
+        fake_ev.key = glfw_key_for_sym(keysym);
+        fake_ev.mods = glfw_mods;
+        fake_ev.ime_state = GLFW_IME_NONE;
+        w->callbacks.keyboard((GLFWwindow*) w, &fake_ev);
+    }
+}
+
 static bool
 is_switch_layout_key(xkb_keysym_t xkb_sym) {
     return xkb_sym == XKB_KEY_ISO_First_Group || xkb_sym == XKB_KEY_ISO_Last_Group || xkb_sym == XKB_KEY_ISO_Next_Group || xkb_sym == XKB_KEY_ISO_Prev_Group || xkb_sym == XKB_KEY_Mode_switch;
@@ -713,7 +866,7 @@ glfw_xkb_handle_key_event(_GLFWwindow *window, _GLFWXKBData *xkb, xkb_keycode_t
     const xkb_keysym_t *syms, *clean_syms, *default_syms;
     xkb_keysym_t xkb_sym, shifted_xkb_sym = XKB_KEY_NoSymbol, alternate_xkb_sym = XKB_KEY_NoSymbol;
     xkb_keycode_t code_for_sym = xkb_keycode, ibus_keycode = xkb_keycode;
-    GLFWkeyevent glfw_ev = {.action = GLFW_PRESS};
+    GLFWkeyevent glfw_ev = {.action = GLFW_PRESS, .native_key_id = xkb_keycode};
 #ifdef _GLFW_WAYLAND
     code_for_sym += 8;
 #else

glfw/xkb_glfw.h

@@ -98,3 +98,4 @@ void glfw_xkb_handle_key_event(_GLFWwindow *window, _GLFWXKBData *xkb, xkb_keyco
 int glfw_xkb_keysym_from_name(const char *name, bool case_sensitive);
 void glfw_xkb_update_ime_state(_GLFWwindow *w, _GLFWXKBData *xkb, const GLFWIMEUpdateEvent *ev);
 void glfw_xkb_key_from_ime(_GLFWIBUSKeyEvent *ev, bool handled_by_ime, bool failed);
+void glfw_xkb_forwarded_key_from_ime(xkb_keysym_t keysym, unsigned int glfw_mods);

kittens/ask/main.py

@@ -1,20 +1,23 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
 
 import os
 import sys
 from contextlib import suppress
-from typing import TYPE_CHECKING, List, 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.typing import BossType
+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 result_handler
-from ..tui.operations import alternate_screen, styled
-from ..tui.utils import get_key_press
+from ..tui.handler import Handler, result_handler
+from ..tui.loop import Loop, MouseEvent
+from ..tui.operations import MouseTracking, alternate_screen, styled
 
 if TYPE_CHECKING:
     import readline
@@ -94,48 +97,248 @@ 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
+
+
+--default -d
+A default choice or text. If unspecified, it is "y" for :code:`yesno`, the first choice
+for :code:`choices` and empty for others. The default choice is selected when the user
+presses the Enter key.
 '''
 
 
-try:
-    from typing import TypedDict
-except ImportError:
-    TypedDict = dict
-
-
 class Response(TypedDict):
     items: List[str]
     response: Optional[str]
 
 
-def choice(cli_opts: AskCLIOptions, items: List[str]) -> Response:
-    with alternate_screen():
-        if cli_opts.message:
-            print(styled(cli_opts.message, bold=True))
-        print()
-        allowed = ''
-        for choice in cli_opts.choices:
-            color = 'green'
-            letter, text = choice.split(':', maxsplit=1)
-            if ';' in letter:
-                letter, color = letter.split(';', maxsplit=1)
-            letter = letter.lower()
-            idx = text.lower().index(letter)
-            allowed += letter
-            print(text[:idx], styled(text[idx], fg=color), text[idx + 1:], sep='', end='  ')
-        print()
-        response = get_key_press(allowed, '')
-        return {'items': items, 'response': response}
+class Choice(NamedTuple):
+    text: str
+    idx: int
+    color: str
+    letter: str
 
 
-def yesno(cli_opts: AskCLIOptions, items: List[str]) -> Response:
-    with alternate_screen():
-        if cli_opts.message:
-            print(styled(cli_opts.message, bold=True))
-        print()
-        print(' ', styled('Y', fg='green') + 'es', ' ', styled('N', fg='red') + 'o')
-        response = get_key_press('yn', 'n')
-        return {'items': items, 'response': response}
+class Range(NamedTuple):
+    start: int
+    end: int
+    y: int
+
+    def has_point(self, x: int, y: int) -> bool:
+        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 Choose(Handler):
+    mouse_tracking = MouseTracking.buttons_only
+
+    def __init__(self, cli_opts: AskCLIOptions) -> None:
+        self.cli_opts = cli_opts
+        self.choices: Dict[str, Choice] = {}
+        self.clickable_ranges: Dict[str, List[Range]] = {}
+        if cli_opts.type == 'yesno':
+            self.allowed = frozenset('yn')
+        else:
+            allowed = []
+            for choice in cli_opts.choices:
+                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, 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)
+        self.draw_screen()
+
+    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 = max(0, self.screen_size.rows // 2 - 2)
+        self.print(end='\r\n'*y)
+        if self.cli_opts.message:
+            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_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 or 'green', underline='straight' if letter == self.response_on_accept else None)
+            text += choice.text[choice.idx + 1:]
+            text += '  '
+            sz = wcswidth(text)
+            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:
+        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, 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
+        self.draw_screen()
+
+    def on_interrupt(self) -> None:
+        self.quit_loop(1)
+    on_eot = on_interrupt
 
 
 def main(args: List[str]) -> Response:
@@ -152,15 +355,16 @@ def main(args: List[str]) -> Response:
             input('Press enter to quit...')
         raise SystemExit(e.code)
 
-    if cli_opts.type == 'yesno':
-        return yesno(cli_opts, items)
-    if cli_opts.type == 'choices':
-        return choice(cli_opts, items)
+    if cli_opts.type in ('yesno', 'choices'):
+        loop = Loop()
+        handler = Choose(cli_opts)
+        loop.loop(handler)
+        return {'items': items, 'response': handler.response}
 
     import readline as rl
     readline = rl
     from kitty.shell import init_readline
-    init_readline(readline)
+    init_readline()
     response = None
 
     with alternate_screen(), HistoryCompleter(cli_opts.name):
@@ -169,7 +373,15 @@ def main(args: List[str]) -> Response:
 
         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

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2020, Kovid Goyal <kovid at kovidgoyal.net>
 
 import sys
@@ -12,6 +11,7 @@ from kitty.cli_stub import BroadcastCLIOptions
 from kitty.key_encoding import encode_key_event
 from kitty.rc.base import MATCH_TAB_OPTION, MATCH_WINDOW_OPTION
 from kitty.remote_control import create_basic_command, encode_send
+from kitty.short_uuid import uuid4
 from kitty.typing import KeyEventType, ScreenSize
 
 from ..tui.handler import Handler
@@ -20,18 +20,27 @@ from ..tui.loop import Loop
 from ..tui.operations import RESTORE_CURSOR, SAVE_CURSOR, styled
 
 
+def session_command(payload: Dict[str, Any], start: bool = True) -> bytes:
+    payload = payload.copy()
+    payload['data'] = 'session:' + ('start' if start else 'end')
+    send = create_basic_command('send-text', payload, no_response=True)
+    return encode_send(send)
+
+
 class Broadcast(Handler):
 
     def __init__(self, opts: BroadcastCLIOptions, initial_strings: List[str]) -> None:
         self.opts = opts
         self.initial_strings = initial_strings
-        self.payload = {'exclude_active': True, 'data': '', 'match': opts.match_tab, 'match_tab': opts.match_tab}
+        self.payload = {'exclude_active': True, 'data': '', 'match': opts.match, 'match_tab': opts.match_tab, 'session_id': uuid4()}
         self.line_edit = LineEdit()
+        self.session_started = False
         if not opts.match and not opts.match_tab:
             self.payload['all'] = True
 
     def initialize(self) -> None:
-        self.print('Type the text to broadcast below, press', styled('Ctrl+c', fg='yellow'), 'to quit:')
+        self.write_broadcast_session()
+        self.print('Type the text to broadcast below, press', styled('Ctrl+Esc', fg='yellow'), 'to quit:')
         for x in self.initial_strings:
             self.write_broadcast_text(x)
         self.write(SAVE_CURSOR)
@@ -51,7 +60,9 @@ class Broadcast(Handler):
         self.commit_line()
 
     def on_interrupt(self) -> None:
-        self.quit_loop(0)
+        self.write_broadcast_text('\x03')
+        self.line_edit.clear()
+        self.commit_line()
 
     def on_eot(self) -> None:
         self.write_broadcast_text('\x04')
@@ -65,6 +76,9 @@ class Broadcast(Handler):
             self.line_edit.clear()
             self.write(SAVE_CURSOR)
             return
+        if key_event.matches('ctrl+esc'):
+            self.quit_loop(0)
+            return
 
         ek = encode_key_event(key_event)
         ek = standard_b64encode(ek.encode('utf-8')).decode('ascii')
@@ -79,6 +93,10 @@ class Broadcast(Handler):
         send = create_basic_command('send-text', payload, no_response=True)
         self.write(encode_send(send))
 
+    def write_broadcast_session(self, start: bool = True) -> None:
+        self.session_started = start
+        self.write(session_command(self.payload, start))
+
 
 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'
@@ -98,11 +116,16 @@ def main(args: List[str]) -> Optional[Dict[str, Any]]:
             input(_('Press Enter to quit'))
         return None
 
-    print('Type text to be broadcast below, Ctrl-C to quit:', end='\r\n')
     sys.stdout.flush()
     loop = Loop()
     handler = Broadcast(opts, items)
-    loop.loop(handler)
+    try:
+        loop.loop(handler)
+    finally:
+        if handler.session_started:
+            sys.stdout.buffer.write(session_command(handler.payload, False))
+            sys.stdout.buffer.flush()
+    return None
 
 
 if __name__ == '__main__':

kittens/choose/main.c

@@ -55,7 +55,7 @@ create_job(size_t i, size_t blocksz, GlobalData *global) {
     if (ans->start >= global->haystack_count) ans->count = 0;
     else ans->count = global->haystack_count - ans->start;
     ans->max_haystack_len = 0;
-    for (size_t i = ans->start; i < ans->start + ans->count; i++) ans->max_haystack_len = MAX(ans->max_haystack_len, global->haystack[i].haystack_len);
+    for (size_t j = ans->start; j < ans->start + ans->count; j++) ans->max_haystack_len = MAX(ans->max_haystack_len, global->haystack[j].haystack_len);
     if (ans->count > 0) {
         ans->workspace = alloc_workspace(ans->max_haystack_len, global);
         if (!ans->workspace) { free(ans); return NULL; }

kittens/choose/main.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python3
-# vim:fileencoding=utf-8
 # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>
 
 import sys

kittens/choose/match.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-# vim:fileencoding=utf-8
 # License: GPLv3 Copyright: 2021, Kovid Goyal <kovid at kovidgoyal.net>
 
 from typing import Iterable, List, Union