Should we add a usage example somewhere? This feature is rather hard to comprehend.

The feature was hard to fully comprehend even before I made it more complex :-(

Adding some examples would definitely help, and it would be even better to slightly restructure the description of this feature. I'll see if I can come up with a better description.

BTW. Some other things I noticed (for different PRs):

1. The list of supported browsers on macOS is not complete, we should at least add support for Microsoft Edge and possibly other popular non-mainstream browsers like Brave and Chromium.
2. The table below the description of webbrowser.register is not correct for macOS, e.g. "chrome" is registered as MacOSXOSAScript("google chrome") and not Chrome('chrome')

1. The list of supported browsers on macOS is not complete, we should at least add support for Microsoft Edge and possibly other popular non-mainstream browsers like Brave and Chromium.

Not limited to macOS, but from the Plausible trial in July, here are the most popular browsers of people visiting docs.python.org:

Also not limited to macOS, here are the most popular desktop browsers used worldwide, from statscounter:

And visitors to usa.gov sites (json), for macOS:

"Macintosh": {
"Safari": 260849550,
"Chrome": 201103500,
"Firefox": 16103981,
"Edge": 2024170,
"Mozilla Compatible Agent": 2018923,
"Opera": 552767,
"YaBrowser": 36155,
"Whale Browser": 15131,
"DuckDuckGo Browser": 5801,
"Coc Coc": 10339,
"SeaMonkey": 4535,
"Aloha Browser": 3174,
"Maxthon": 4181,
"Mozilla": 2253,
"Internet Explorer": 5163,
"Waterfox": 1837,
"PaleMoon": 139,
"(not set)": 215,
"Vivaldi": 748
},

Given how the mac launchers work, I think it would also be sensible for $BROWSER to accept application names, as the standard way to launch a URL with browser is e.g. open -a 'Google Chrome' URL (equivalent for tell application in current osascript implementation).

e.g.

if shutil.which(cmd[0]):
  # on the command-line
  GenericBrowser
else:
  # maybe check if app exists?
  OSAScript(app_name)

I'm not sure what the right backward-compatibility story is, or if that's appropriate if $BROWSER is a standard env expected to point to a shell executable.