Decide stack creation, foreground selection, and reset behavior (v2)#84

Draft type: native feasibility gate followed by a global setting implementation. Source: feedback point 8. Release scope: v2. Sam requested a Settings option for the foreground and return-to-stack behavior. Sam confirmed that the setting applies globally and that showing windows on top means exposing every window's title bar.

What to build

Explain the current documented stack creation rules and define the new foreground setting. Keep accepted stack creation behavior unchanged rather than introducing new automatic grouping in this issue. Provide a Settings choice for keeping a selected member in front or returning it to the normal stack order after focus leaves. Apply the choice globally to all stacks. Keep every window's title bar visible in every stack foreground mode. Keeping one member in front must not cover another member's title bar. Explicit title-bar maximization is a separate temporary state governed by issue #88, not a stack foreground mode. It may cover stack mates until restore, after which the title-bar visibility rule applies again. Default to restoring normal stack order when focus leaves. The optional Keep mode retains the selected member until another member in the same stack is selected, or that member leaves or closes. Selection means receiving keyboard focus through an explicit window selection or navigation action, including overview selection. Save the global mode across Miri and engine restarts, but clear retained foreground selections and show normal stack order after restart. The initial startup focus snapshot does not reapply a retained selection.

Acceptance criteria

• Explain current stack creation and automatic behavior with concrete examples.
• Describe existing automatic behavior and explicit stack actions without adding new automatic grouping rules.
• The Settings choice applies globally to all stacks, rather than independently per window, stack, or application.
• Separate keyboard focus, foreground stack order, and global always-on-top behavior.
• Settings offers the foreground persistence choice Sam requested.
• The default mode restores normal stack order when focus leaves.
• Keep mode retains the selected member after focus leaves, until another member is selected or the retained member leaves or closes.
• The mode persists across Miri and engine restarts, while retained foreground selections reset to normal order.
• Startup observation does not activate stack apps or treat the initial focus snapshot as a new explicit selection.
• Every stack foreground mode exposes every member's title bar at the top of that window.
• A retained foreground member does not obscure another member's title bar.
• Explicit double-click maximization follows issue #88's accepted covering behavior and restores title-bar visibility when the window returns to its stack.
• The show-title-bars behavior is distinct from keeping one application globally always on top.
• Overview selection counts as selecting its chosen member, while cancellation restores the previous state where possible.
• Moving a whole column preserves its retained member while the engine keeps running.
• Closing or removing the retained member clears that selection without stealing keyboard focus.
• The native prototype proves title-bar visibility in both modes before Keep mode is exposed as working.

Existing policy

The accepted overflow policy raises the focused member and returns it to its overlapped place when focus leaves. It records a windowless-Finder ordering limitation. The accepted global setting adds the optional Keep mode while retaining that default return behavior. The earlier proposal to omit a foreground setting is superseded by Sam's request for that setting. Foreground order inside a stack is separate from global always-on-top behavior. The global scope and title-bar meaning are accepted. The default, release conditions, and restart behavior are accepted. The title-bar-preserving geometry is an engineering investigation, not a settled native implementation.

Verification

Verify focus changes, overview selection and cancellation, mixed-application stacks, membership changes, display moves, and restarts. Record native frames, visible title bars, WindowServer order, and keyboard focus separately.

Related work

Issue #42 records existing overflow behavior. Issue #80 adds the overview.

Blocked by

Complete task 08a (proof sub-task of #84)'s native foreground-layout proof before implementing or exposing Keep mode. Default-mode and configuration work can be prepared independently, without claiming the new native behavior passes.