How Help windows get lost on Intel Macs

Since macOS High Sierra, when they were last revamped, Help books managed by macOS have resumed their steady functional decline. Intermittent problems, from complete failure to work to missing contents, can usually be addressed by closing the Help window and trying again. But there’s one problem that can catch even the most experienced: the fact that Help windows on Intel Macs don’t open in front of others, or ‘in focus’. This problem seems to extend to some other transient accessory windows as well.

Although I’ve been moving away from Help books relying on AppKit’s NSHelpManager, some of mine such as Cirrus still use it. It’s not unusual for me to receive email from someone who has tried opening its Help book, but can’t find that window anywhere on their Mac, so presumes that its Help feature is broken.

Help Manager

Help Manager relies on four components:

a Help book constructed in XHTML with CSS according to rules laid down by Apple, put into a Help bundle and placed in the app’s internal Resources folder in /Contents/Resources/. This bundle conventionally has the extension .help, and UTI type com.apple.help;
the helpd service provided by macOS from /System/Library/PrivateFrameworks/HelpData.framework/Versions/A/Resources/helpd, to collate indexes and other information about Help books. This is run on demand, as a user process;
the Help Viewer app, at /System/Library/CoreServices/Help Viewer.app, to render and display Help books using WebKit;
the ~/Library/Caches/com.apple.helpd folder, containing indexes, databases and property lists maintained by helpd.

This top-level architecture has changed relatively little through versions of macOS from around 10.6, and last underwent substantial revision in High Sierra 10.13.4. Since then it appears to have changed little, although as you’ll see below, it may now involve SwiftUI somewhere along the way. The layout and contents of the com.apple.helpd folder have changed, though.

Misbehaviour

Because Help Viewer is dependent on so many different components, it’s likely to fail if any of those have a problem. There’s one persistent failure, though, that seems to have been repeatable for at least a year. To demonstrate this fully, you’ll need both an Intel and an Apple silicon Mac. If you’ve only got an Intel Mac, you can still experience it, although you’ll have to trust my word how this differs on Apple silicon.

On your Mac(s) open Disk Utility, size its main window quite large, and place it in the upper middle of the display. Then select the Disk Utility Help command in its Help menu. If that’s an Intel Mac, I’m confident that the Help window will at least be behind Disk Utility’s main window, and if you’re really unlucky you may have a job discovering it from among all other open windows.

If you can’t find it, there’s no point in repeating the menu command: the Help window won’t come to front, and because it’s actually owned by Help Viewer, it isn’t listed in Disk Utility’s Window menu either.

Now, if you have an Apple silicon Mac at the ready, repeat this on that system, and you’ll see that it behaves itself perfectly, and may well be much nippier in the process too.

Exemptions

Apps that don’t use Help Manager or Help Viewer are exempt from this behaviour. You can see that with several of my other apps, including Mints, which uses PDF, and DelightEd, using RTF. Their Help windows aren’t rendered by an external process like Help Viewer, so they should also perform much better, and don’t require helpd to register their Help books. The penalty is that they don’t have the same indexing and search features, and can’t work together with the Help books for other apps.

Cause

Opening a Help book results in a few very active seconds in the log, and the precise cause is hard to trace through all the noise. As you’d expect, log entries on Intel and Apple silicon Macs have much in common, particularly at the start. Intel Macs that have been in use for some years can generate hundreds of errors, as HelpData tries to check other Help pages during launch, but that appears to be unrelated.

Two intriguing entries from quite late in the process come from com.apple.AppKit, anything from 0.8 to over 3 seconds after the menu command:
Window SwiftUI.AppKitPanel 0x139016280 ordered front from a non-active application and may order beneath the active application’s windows.
order window front conditionally: d2 related: 0
“May order beneath the active application’s windows” is exactly what happens on Intel, and this also implies that Apple is well aware of the bug.

Towards the end of the sequence opening the Help window, there comes a clue as to what might differ between the two architectures. While Apple silicon Macs record WindowManager stating:
Ordering <private> above relative to <private> from: applicationOrderWindowAction
Intel Macs state the exact opposite:
Ordering <private> below relative to <private> from: applicationOrderWindowAction

Does someone have their above and below confused, perhaps?