I did som digging on this.

Workaround

Anywhere in .zshrc, add this line:

function whatis() { if [[ -v THEFD ]]; then :; else command whatis "$@"; fi; }

Explanation:

The lag is caused by calls to whatis, which the highlighter calls when highlighting whatis and man commands. whatis typically takes a few seconds or so to execute, so the terminal will be blocked for that time.

The line above declares a function, which will have precedence over the system whatis command. The function returns immediately if called from within the syntax highlighter (by testing if variable THEFD exists, which happens to be present in the syntax highlighter where the whatis calls are made). Otherwise, e.g. when calling whatis from the terminal, the function dispatches the system whatis command.

Some more info for anyone trying to fix this

The whatis calls are made in file /:chroma/-whatis.ch, function -fast-whatis-chroma-callback(), as exec {THEFD}< <( [...] LANG=C whatis [...] ). This command doesn’t block though. It however stores a file descriptor for the output of the command to $THEFD. This file descriptor is read from in file/function -fast-zts-read-all with the sysread command - this is the call that will actually block.

An easy quick-fix would be to simply disable syntax highlighting of the man and whatis commands for macOS.

@lucax88x , @londbell My workaround is only expected to work for freezing behaviour when colorizing the man commands (and as a consequence, the whatis command).

For any significant lags when other commands are colorized, there is probably something else that fast-syntax-highlighting does upon colorizing that specific command that is blocking for some time.

To solve such problems, you could try to disable syntax highlighting entirely for that specific command, e.g. trying the suggestion by @Aloxaf above.

For anyone wanting to find a better fix

For anyone wanting to trouble-shoot lag when highlighting other commands than man/whatis, to try to find a workaround that doesn’t involve disabling highlighting for that command, this is the best solution I found:

# new shell without loading the typical zsh startup files:
zsh -f

# manually load the highlighter (you might need to change the path):
_zfst_file="/opt/homebrew/opt/zsh-fast-syntax-highlighting/share/zsh-fast-syntax-highlighting/fast-syntax-highlighting.plugin.zsh"
[[ -f "$_zfst_file" ]] && source "$_zfst_file" && fast-theme -q free

# load zsh's profiler module:
zmodload zsh/zprof

# here: start typing the misbehaving command, so the lag/blocking behaviour is triggered. Wait it out. 
man cow  # replace with misbehaving command

# save profiling results:
zprof > zprof.txt

Copy-paste the above to the terminal without the comments, otherwise zsh will yield an error for the #'s since we’re using the default shell options.

Now check zprof.txt. It will list the executed functions ordered by execution time, with the longest-running first: this will have been numbered 1) by zprof. The function indicated there will probably be some top-level function, so check the breakdown of 1) slightly further down. There you’ll see the specific highligter function that caused the lag.

E.g. for the lagging man command:

$ grep ' 1)' -B 2 zprof.txt

# output:
num  calls                time                       self            name
-----------------------------------------------------------------------------------
 1)    2        9045.14  4522.57   99.72%   9045.14  4522.57   99.72%  -fast-zts-read-all
--

       2/2      9045.14  4522.57   99.72%   9045.14  4522.57             -fast-whatis-chroma-callback [6]
 1)    2        9045.14  4522.57   99.72%   9045.14  4522.57   99.72%  -fast-zts-read-all

So: the lag (9 seconds) happened in the function -fast-zts-read-all, who’s break-down shows that it was the call to -fast-whatis-chroma-callback that caused the lag. Hence, further investigation/profiling should be done on this function.

Another workround is disable highlight for man command

FAST_HIGHLIGHT[chroma-man]=

unfortunately this plugin is REALLY slow in OSX, even with a m1pro max.

when I try to input something like

git checkout branch/

it starts freezing for full seconds

The workaround from @LeuschkeTressa did not fix it.

This issue also occurs on Ubuntu varieties (I’m using Kubuntu 23.04). 👍 to @LeuschkeTressa - his workaround does fix the man freezing for me.

I switched to zsh-syntax-highlighting because it works for me.