Add Layout Helper with optional window thumbnails

[kiteretsu903]

Draft pending #1904 and the independent placement coordinator included in #1903. This branch includes those prerequisites, without the Fit feature. It is rebased onto current main and no longer depends on closed #1902.

Adds an opt-in Layout Helper that offers other windows for the remaining regions after a supported snap. Drag-to-snap is the primary trigger; keyboard/menu actions and denser grids have separate settings. Stage Manager disables the helper.

Layout and selection

• Available regions are derived from the completed snap and eligible visible windows. A retained window can occupy a rectangular union of cells: for example, a retained right-half window plus a new top-left snap should leave only the bottom-left region to fill.

• Mere overlap does not permanently mark a region occupied. Window identity, current geometry, and visibility matter, including when several windows belong to the same application.

• Users can choose a candidate or navigate with the keyboard. Escape, an outside click, invalidation of the anchor, or disappearance of the target cancels or updates the session rather than applying a stale selection.

• Placement uses the application's actual supported size, including fixed-size and constrained windows. It does not assume every candidate can exactly fill a cell.

• Animation cancellation and obsolete pending writes complete the selection exactly once. Candidate exclusion uses retained window identities, and disappeared catalog requests fail instead of leaving selection pending.

• A cancelled minimized-window restore retains its original frame only while the window remains at its known original/prepared geometry; a later user move supersedes it.

Thumbnails and responsiveness

Icon/title candidates work without Screen Recording permission. Optional thumbnails require macOS 14 or later and capture permission, and fall back when unavailable or unsuccessful. Candidate preparation and capture are bounded; existing candidate views and the scroll position are retained as results arrive. Late capture results are ignored once their session is obsolete.

Implementation and dependencies

Layout/occupancy, candidate selection, and placement are separated from capture/cache ownership within this feature. Activity monitoring starts and stops with the feature. The implementation reuses shared verified placement, synchronized previews, and Glass material support; thumbnails and animation are optional at runtime. Placement reads current application constraints and verifies the current attempt, without learning or retaining size limits. Preview-only size tracking is outside this change. Dividers are a separate feature.

Validation

The shared Glass geometry tests also passed after correcting an assertion that mixed a new material’s model frame with its parent’s previous rendered frame. Model and presentation geometry are now checked separately, with a bounded requirement for rendered samples. This follow-up changes tests only.

The current branch passed a signed Debug build and all 685 XCTest tests, including real placement-service cancellation and restoration-history regressions. Abandoned restore history now retains actual constrained and partial preparation frames; a newer Rectangle action invalidates it even if the window returns to the same tile. These new history cases are unit-tested; the earlier native minimized-window checks described below were not rerun in this pass. Earlier native acceptance on macOS 27.2 / Apple silicon passed cold candidate loading, selection with animation off/on, fixed-size/constrained/minimized windows, Escape and disabled/closed-candidate cancellation, retained-right-half plus top-left placement, and real thumbnail capture followed by cancellation. A native minimized-window failure exposed transient AX identity reads during restoration; retained windows now use their accepted identity, with fresh process and WindowServer geometry validation. The failing native case passes after that fix.

The tests use an isolated AppKit fixture with actual AX/WindowServer placement and native candidate-card actions. Installed application and preference state were restored and verified. The native icons/title fallback and candidate placement also passed with a test-only unavailable-permission result; the system TCC grant was not revoked. These results do not claim Intel or older-macOS execution. The demo below predates the standalone rebase.

An earlier physical-input acceptance run used global macOS mouse and keyboard events. Clicking the fixture candidate card completed verified placement without moving the anchor; Escape dismissed the next helper session without placing its candidate. The installed binary, saved preferences, and pointer position were restored afterward.

This replaces the corresponding part of #1890.

Demo

09-layout-helper.mp4

Window animation is disabled. Recorded with the combined build and only this feature and its required visual options enabled.

Settings