zsh: add 'fastSyntaxHighlighting'

modules/misc/news/2026/06/2026-06-22_13-02-38.nix

@@ -0,0 +1,9 @@
+{ config, ... }:
+{
+  time = "2026-06-22T13:02:38+00:00";
+  condition = config.programs.zsh.enable;
+  message = ''
+    A new module has been added: `programs.zsh.fastSyntaxHighlighting`.
+    This is an alternative implementation of syntax highlighting for Zsh.
+  '';
+}

modules/programs/zsh/default.nix

@@ -82,6 +82,46 @@ in
           };
         };
       };
+
+      fastSyntaxHighlightingModule = types.submodule {
+        options = {
+          enable = mkEnableOption "zsh fast syntax highlighting";
+
+          package = lib.mkPackageOption pkgs "zsh-fast-syntax-highlighting" { };
+
+          theme = mkOption {
+            type = types.nullOr types.str;
+            default = null;
+            example = "clean";
+            description = ''
+              If non-null, Home Manager will run {command}`fast-theme -q`
+              with this value to select the theme. `fast-theme` persists the
+              selected theme in fast-syntax-highlighting's work directory, so
+              setting this option back to `null` stops Home Manager from
+              invoking {command}`fast-theme` but does not reset an already
+              persisted theme. Run {command}`fast-theme -r` manually to clear
+              upstream state.
+
+              See [upstream's documentation](https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/THEME_GUIDE.md)
+            '';
+          };
+
+          settings = mkOption {
+            type = types.attrsOf types.str;
+            default = { };
+            example = {
+              use_brackets = "0";
+              "chroma-," = "→chroma/-precommand.ch";
+              "chroma-comma" = "→chroma/-precommand.ch";
+            };
+            description = ''
+              Custom values to add to `FAST_HIGHLIGHT`, like custom chroma
+              configuration (see [upstream's documentation](https://github.com/zdharma-continuum/fast-syntax-highlighting/blob/master/CHROMA_GUIDE.adoc)
+              and its [built-in chromas](https://github.com/zdharma-continuum/fast-syntax-highlighting/tree/master/%E2%86%92chroma)).
+            '';
+          };
+        };
+      };
     in
     {
       programs.zsh = {
@@ -191,6 +231,12 @@ in
           description = "Options related to zsh-syntax-highlighting.";
         };
 
+        fastSyntaxHighlighting = mkOption {
+          type = fastSyntaxHighlightingModule;
+          default = { };
+          description = "Options related to zsh-fast-syntax-highlighting.";
+        };
+
         autosuggestion = {
           enable = mkOption {
             type = types.bool;
@@ -421,6 +467,16 @@ in
                 - config.xdg.cacheHome (XDG cache directory)
               '';
             }
+            {
+              assertion =
+                lib.count (x: x) [
+                  cfg.syntaxHighlighting.enable
+                  cfg.fastSyntaxHighlighting.enable
+                ] <= 1;
+              message = ''
+                Only one Zsh syntax highlighter can be enabled at a time.
+              '';
+            }
           ];
 
           warnings =
@@ -630,6 +686,22 @@ in
                   )}
                 ''
             ))
+
+            (lib.mkIf cfg.fastSyntaxHighlighting.enable (
+              mkOrder 1200
+                # Load zsh-fast-syntax-highlighting after all custom widgets have been created
+                ''
+                  source ${cfg.fastSyntaxHighlighting.package}/share/zsh/plugins/fast-syntax-highlighting/fast-syntax-highlighting.plugin.zsh
+                  ${lib.optionalString (cfg.fastSyntaxHighlighting.theme != null) ''
+                    fast-theme -q ${cfg.fastSyntaxHighlighting.theme}
+                  ''}
+                  ${lib.concatStringsSep "\n" (
+                    lib.mapAttrsToList (
+                      name: value: "FAST_HIGHLIGHT+=(${lib.escapeShellArg name} ${lib.escapeShellArg value})"
+                    ) cfg.fastSyntaxHighlighting.settings
+                  )}
+                ''
+            ))
           ];
 
           home.file."${dotDirRel}/.zshrc".text = cfg.initContent;

tests/darwinScrublist.nix

@@ -218,6 +218,7 @@ let
     "zoxide"
     "zplug"
     "zsh"
+    "zsh-fast-syntax-highlighting"
     "zsh-history-substring-search"
     # keep-sorted end
   ];

tests/modules/programs/zsh/conflicting-highlighters.nix

@@ -0,0 +1,13 @@
+{
+  programs.zsh = {
+    enable = true;
+    syntaxHighlighting.enable = true;
+    fastSyntaxHighlighting.enable = true;
+  };
+
+  test.asserts.assertions.expected = [
+    ''
+      Only one Zsh syntax highlighter can be enabled at a time.
+    ''
+  ];
+}

tests/modules/programs/zsh/default.nix

@@ -1,6 +1,7 @@
 {
   zsh-abbr = ./zsh-abbr.nix;
   zsh-aliases = ./aliases.nix;
+  zsh-conflicting-highlighters = ./conflicting-highlighters.nix;
   zsh-dotdir-absolute = import ./dotdir.nix "absolute";
   zsh-dotdir-default = import ./dotdir.nix "default";
   zsh-dotdir-path-normalization-abs-no-slash = import ./dotdir.nix "abs-no-slash";
@@ -12,6 +13,8 @@
   zsh-dotdir-path-normalization-abs-space = import ./dotdir.nix "abs-space";
   zsh-dotdir-relative = import ./dotdir.nix "relative";
   zsh-dotdir-shell-variable = import ./dotdir.nix "shell-variable";
+  zsh-fast-syntax-highlighting = ./fast-syntax-highlighting.nix;
+  zsh-fast-syntax-highlighting-options = ./fast-syntax-highlighting-options.nix;
   zsh-history-ignore-pattern = ./history-ignore-pattern.nix;
   zsh-history-path-absolute = import ./history-path.nix "absolute";
   zsh-history-path-default = import ./history-path.nix "default";

tests/modules/programs/zsh/fast-syntax-highlighting-options.nix

@@ -0,0 +1,19 @@
+{
+  programs.zsh = {
+    enable = true;
+    fastSyntaxHighlighting = {
+      enable = true;
+      theme = "default";
+      settings = {
+        "chroma-," = "→chroma/-precommand.ch";
+        "chroma-comma" = "→chroma/-precommand.ch";
+      };
+    };
+  };
+
+  nmt.script = ''
+    assertFileContains home-files/.zshrc "fast-theme -q default"
+    assertFileContains home-files/.zshrc "FAST_HIGHLIGHT+=(chroma-, '→chroma/-precommand.ch')"
+    assertFileContains home-files/.zshrc "FAST_HIGHLIGHT+=(chroma-comma '→chroma/-precommand.ch')"
+  '';
+}

tests/modules/programs/zsh/fast-syntax-highlighting.nix

@@ -0,0 +1,13 @@
+{
+  programs.zsh = {
+    enable = true;
+    fastSyntaxHighlighting = {
+      enable = true;
+    };
+  };
+
+  nmt.script = ''
+    assertFileContains home-files/.zshrc "source @zsh-fast-syntax-highlighting@/share/zsh/plugins/fast-syntax-highlighting/fast-syntax-highlighting.plugin.zsh"
+    assertFileNotRegex home-files/.zshrc "fast-theme"
+  '';
+}