The Dock and Stage Manager are perfect complements: the Dock primarily manages apps, while Stage Manager manages their windows. Used on their own, selecting any running app in the Dock brings the app and all its open windows to the front. What happens when you select one of the Cast in Stage Manager is that all the windows in that group are put on Stage, even though some of them may belong to apps in other groups. This makes Stage Manager more complicated, and some of its behaviours more unexpected. This article shows how windows and apps interact when Stage Manager is enabled.

To understand this, you’ll need a document-based app that doesn’t become undead, as I described in yesterday’s article about app states. Use an app like my free DelightEd, or StateTest2n provided in the test apps yesterday, from here: StateTest2f
Throughout this article, I’ll refer to that as app A.

Turn Stage Manager on in standard configuration, with

• Recent applications on
• Desktop items off
• Show windows from an application set to All at Once.

Window groups

Open that test app A, and with its single window open, click on another app’s windows in the Cast to bring them on Stage. Drag App A’s single window from the Cast to the Stage to join that group. Then, without closing its window, quit app A, open it again from the Dock, and not only does its single window reopen as you’d expect, but that window should be returned to the Stage, where it’s joined immediately by the other windows that were there just a moment ago.

Repeat that same sequence, but this time before you quit app A, close its single window. Then when you reopen app A, it’s put onto the Stage alone, rather than in the group it was with. That’s because closing its window breaks the persistence of that window grouping: Stage Manager groups windows, not apps.

To keep an app as part of a group, keep one of its windows open in that group. That should normally be a document window, rather than a File Open dialog (as displayed by some bundled apps like TextEdit), a splash screen, or About window. You can also repeat this using the StateTest2q app, which should behave the same so long as you don’t let it become undead.

Next you can demonstrate how Stage Manager works with apps using their bundle identifier (e.g. com.apple.Finder) and not the app’s path. For this you’ll need both my demo apps, StateTest2n and StateTest2q, as they share the same identifier.

First, open StateTest2n so that it opens its single window. Click on another item in the Cast to put that on Stage, and drag the window from StateTest2n to join that group, just as you did before. Then quit StateTest2n with its window still open, and switch what’s on Stage to a different group of windows. Now, instead of opening StateTest2n again, open StateTest2q. You’ll see that Stage Manager treats it as if it were StateTest2n, and recreates the group that had included StateTest2n. This is a significant observation should you ever run two different versions of the same app, with identical bundle identifiers, as Stage Manager will consider them to be the same apps.

One interesting aside about app behaviour in recent macOS is that Open and Save dialogs are separate per-app processes, which explains why they don’t work here in the same way that document windows do. To observe this, look in Activity Monitor for processes with names beginning Open and Save Panel Service.

Absent apps

Many document-based apps open an existing or new document on launch. These work well with Stage Manager, as this ensures they’re put straight on Stage, ready to be used or put into an existing group for a new workflow.

Other apps can be set to open without a document, or do so by default. These can work in one of two ways in Stage Manager: a few, like GraphicConverter 11, open without changing what’s on the Stage, at least until you open a document in them, when they take the Stage over and return whatever other windows were on Stage to the Cast. Others, like BBEdit and my free app Precize, are put straight on Stage on their own, which appears to be the more normal behaviour. I don’t understand why apps can behave in those different ways, although it could be the result of GraphicConverter opening a couple of floating toolbox windows instead of a document window.

Apps that don’t open a document window when they’re launched don’t get put into the Cast, as there’s nothing of theirs to put there. Switch to a different app on Stage, and they’re still running but not included in the Cast. To bring them on Stage, click on their icon in the Dock.

This behaviour can make drag and drop less appealing: for example, compressing a folder using Archive Utility puts that app’s single window on Stage immediately. Once that task is complete and Archive Utility quits automatically, the previous contents of the Stage are pulled back from the Cast and restored, which can appear annoying. Similar effects can be seen when emptying the Trash in the Finder.

Popbacks

A few apps can cause even stranger effects when they link internally between their own windows, and those windows are in different groups. My best example of this is when assigning tags to an article being edited in MarsEdit.

MarsEdit has two main types of window: the main window contains all the posts and pages of your blog, and each of those are written in individual editor windows. Dividing the main and an editor window between two different groups works well until you come to edit the tags for a post, as those refer back to the tags in use in the main window.

As you type the letters for a tag into the editor, Stage Manager switches to the main window to display a popup menu of possible tags. Once the tag is complete and entered, Stage Manager then switches back to the editor. This popback effect is surprising when you first see it, but hasn’t deterred me from dividing its windows. Again, this emphasises how Stage Manager manages windows not apps.

Summary

• Stage Manager manages windows; the Dock manages apps. They complement one another.
• To retain an app window within a group, keep its document window open within that group.
• To ensure an app window is restored to a group, quit that app with that document window still open.
• To open an app in its own group, close all its windows before quitting that app.
• Stage Manager recognises apps by their bundle identity. If you use two different versions with the same identity, it can become confusing.
• Most apps opening without a document window do so on an empty Stage. To add them to the cast, open a document window.
• A few apps that open without a document window open into the current Stage, but displace the windows there when the app opens a document window.
• Popbacks can occur when two windows from the same app are in different groups, but refer to one another. They’re distracting but harmless.