Skip to content

Settings: change page as one transition with the window frame - #197

Merged
mblauberg merged 10 commits into
mainfrom
lane/transitions
Nov 4, 2026
Merged

mblauberg merged 10 commits into
mainfrom
lane/transitions

Conversation

@mblauberg

@mblauberg mblauberg commented Nov 4, 2026 •

Copy link
Copy Markdown
Owner

Summary

Settings now changes page the way System Settings does. Switching a tab, a Mouse segment, or an app's page (and Back) is one transition. The old page fades out and the new one fades in while the window frame moves to the new height. Both run in one NSAnimationContext group with one duration and curve. The page stays against the top: the toolbar and strip hold still, and the window's bottom edge covers or uncovers the page.

  • PaneTransition (new, owned by SettingsTabs) is the only code that moves the window frame. A page change first snapshots the page with cacheDisplay, leaving the window background clear. It then makes the change, lays out and measures once, and runs one group with three parts:

    • the frame moves with window.animator().setFrame;
    • the snapshot fades out;
    • the tab view fades in, using an explicit opacity animation from 0.

    The duration is animationResizeTime held between 0.2 and 0.35 s, with ease-in-ease-out timing. During the flight the tab view is pinned to the top at the new height and its bottom constraints are released. Without that, it took the new height before the window did and the page slid with the frame.

  • Tabs: transitionOptions = [] (the toolbar style is unchanged). A toolbar click goes through tabView(_:willSelect:) / didSelect, and a request goes through open. preferredContentSizeDidChange no longer calls super, so the tab controller doesn't size the window as well. fitWindow is gone; fittedFrame() measures exactly as before.

  • Mouse segments go through MouseTab.transition. An app's page, its segments and Back go through SettingsContext.transition, and a request for an app's page is applied in the same transition as the tab.

  • In-pane growth (refit(), preferredContentSizeDidChange) calls fit(). It uses the same frame animation with no fade, and retargets a flight already under way.

  • A hidden window and Reduce Motion change at once: no snapshot, no fade, and the frame is set directly.

  • PaneForm hides the grouped form's scroll background. It looks the same: light and dark captures of every pane are pixel-identical with and without it. Without it, cacheDisplay drew that background lighter than the window's desktop-tinted one, so the first frame of a fade flashed.

Closes #196

Acceptance criteria

  1. Tabs run a single animation. The frame and the fade start on the same frame and end within one frame of each other. There is no second resize, and nothing is clipped or stretched (table below).
  2. Segments and app pages use the same path and show the same frame and fade numbers.
  3. Top-anchored. In every frame of every scenario, the toolbar and strip band (top 220 px) is at the same offset as frame 0. The form band keeps a 0 px offset, first against the old page and then against the new one; it never drifts. Two frames in one run are the exception, see the note below.
  4. Same height cross-fades only. The frame animates only when the target frame differs (window.frame != target). App open and Back differ by 6 pt, and they cross-fade over about 10 frames while the height moves 6 pt.
  5. Reduce Motion gives .instant: no snapshot, and the frame is set directly. This is unit-tested; the filmstrip doesn't cover it.
  6. Opening. The first show runs while the window is hidden, so it is instant. A hidden window never animates (unit-tested).
  7. In-pane growth uses the same non-blocking frame animation with the page pinned to the top, so the bottom edge uncovers or covers the page. No frame shows the page squeezed or overflowing.
  8. One owner. A test fails if any other file in PureMouseSettingsUI calls setFrame( or setContentSize(, uses .crossfade, or if SettingsTabs calls super.preferredContentSizeDidChange.
  9. Sizing unchanged. The same measuredSize / LazyPane.maxHeight(on:) path and the same 600 pt cap. The existing sizing tests pass, and every final frame is pixel-identical to a fresh capture of that pane.
  10. Filmstrips were taken before and after on the spare Mac (numbers below). The contact sheets are with the chair, to attach.

Review fixes

  • The incoming page has an interactive model alpha during its fade; the snapshot ignores hit testing and accessibility.

  • Every in-flight refit rechecks visibility and Reduce Motion and lands immediately when needed, restoring pins and removing the snapshot. Closing also cleans up the flight.

  • A refit uses the remaining time on the original flight, so the frame ends with the fade; stale completion callbacks cannot land a newer flight.

  • Verified with swift build && swift test --filter PureMouseSettingsTests (244 tests, Swift 6.4); deterministic tests cover retargeting, policy changes, stale completions, close cleanup, and snapshot input.

  • Reentrant fitting now coalesces measurement requests before retargeting; a regression test confirms cancelled frame completions cannot release the pins early.

Follow-up review fixes (c6b933d)

  • P1 — first-frame flash: the incoming view keeps alphaValue == 1 for hit testing while its layer stays at opacity 0 during the swap. The final model opacity and explicit 0→1 fade are installed atomically, with backwards fill and a layer-local start time from the Core Animation clock. A commit during layout cannot expose the incoming page before its fade is attached.
  • P2 — cancelled resize completion: frame retargets carry generation tokens. Fade and frame animations start in the same transaction with separate completion groups; pins are released only after both the fade and the latest frame animation finish. A cancelled original resize cannot land its replacement.
  • P3 — repeated navigation: show(nil), empty requests, same-tab/segment requests and sheet-only requests on the current page skip the cross-fade. App requests transition only when the resolved app page changes, preserving the current segment when repeated. Navigation consumed during layout joins the original transition.
  • Checks: swift build && swift test --filter PureMouseSettingsTests passed: 249 tests in 27 suites, Swift 6.4.2 locally. Regression coverage includes input while visually hidden, a commit during the swap, frame-only cancellation before replacement completion, both fade/frame completion orders, no-op navigation and repeated app requests. git diff --check passed. Swift 6.3-compatible syntax retained; CI supplies the 6.3 check.
  • Scope and visual evidence: six files within Sources/PureMouseSettingsUI, Tests/PureMouseSettingsTests and docs/ui-design.md; pane sizes and the 600 pt cap unchanged. No Settings, menu or daemon executable launched. The earlier filmstrip evidence above predates this follow-up; the chair will verify these visuals on the spare Mac.

How checked

  • swift build && swift test --filter PureMouseSettingsTests passed: 238 tests in 27 suites, Swift 6.4 locally.
  • New PaneTransitionTests cover:
    • style: hidden or Reduce Motion gives .instant, and the duration is clamped;
    • a hidden window takes the new height at once, with no snapshot left behind and the top edge fixed;
    • nested changes join, and a change measures only once;
    • fit is ignored mid-change;
    • nothing to measure leaves the frame alone;
    • SettingsTabs.open in a hidden window lands on each pane's height, and on the cap for a tall pane;
    • one owner, checked in the source.
  • Visual: the filmstrip hook was run on the spare Mac (macOS 27, light), in a sandbox with a temporary config and a stub daemon, across 6 scenarios. Each run captures about 60 frames over 1 s from a background thread. The installed app was not touched.

Footprint

No daemon or menu bar app changes. Settings adds no polling or timers: one snapshot bitmap exists only for the length of a page change.

Docs

  • docs/ui-design.md:
    • Settings window: the page-change rule.
    • Implementation, Sizing: fittedFrame().
    • Implementation, Transitions (new): who owns the frame and how.
  • docs/development.md: the filmstrip runs on a background thread, writes frames.txt, and takes PUREMOUSE_DEV_FILMSTRIP_SECONDS. It also notes how to read a frame caught between two sizes.
Agent evidence

Before (main plus the hook):

  • The tab switch's frame jumps inside a main-thread stall, then a 600 ms cross-fade runs at the new size.
  • Buttons→Apps cross-fades at the old size, then snaps smaller at about 600 ms.
  • Segments and app open/Back swap and resize within a single frame (for example, Scrolling→Pointer goes 1312→780 px in one frame at 60 ms).

After (final code, run after11). Window height is in pixels at 2x. Frame 0 is before the change, and times are in ms from the start of the change on the main thread. "Fade" uses ink and difference measures against the first and last frames. In every scenario the fade's first frame is the frame's first moving frame (±1), and both settle on the same frame.

Scenario First changed frame Height over time Fade Settled
General→Mouse (tab) 009 @139 1164→1168→1188→1244→1294→1332→1344→1346 009–019 019 @339
Buttons→Apps (tab) 006 @101 1344→1318→1260→1186→1118→1078→1064 006–018 018 @302
Buttons→Scrolling (segment) 007 @120 1346→1342→1332→1324→1316→1312 007–019 019 @320
Scrolling→Pointer (segment) 005 @77 1310→1266→1162→1070→952→840→786→780 005–024 024 @386
Apps→Excel (app page) 007 @121 1064→1066→1070→1074→1076 007–019 019 @321
Excel→Apps (Back) 006 @86 1076→1072→1068→1066→1064 006–017 017 @273
  • In the first changed frame, the snapshot differs from the frame before it by a mean of 0.07–0.27 grey levels. The tab case is higher only because the toolbar selection changes. No frame shows both pages at full strength.
  • The final frame matches a fresh PUREMOUSE_DEV_CAPTURE of the target pane: mean difference 0.000 in 5 of 6 scenarios. Back to Apps differs by a uniform 0.96 grey level with no pixel off by more than 16, and the before run shows the same, so it is the window background's tint at a different position.
  • Note: 3 of about 360 frames (Scrolling→Pointer 015 and Buttons→Apps 006 and 011) have transparent rows along the image's top or bottom edge. In the first, title, toolbar and page are all offset together inside the image. These look like the window-server capture catching the window between two sizes, not the page moving. The neighbouring frames are aligned.
  • Iterations, before the final design passed:
    • a snapshot drawn from the frame view didn't match the desktop-tinted background, so I switched to a clear-background content snapshot and PaneForm's hidden scroll background;
    • animator().alphaValue from a value set in the same pass ran from 1 to 1, so I switched to an explicit CABasicAnimation from 0;
    • a frame drawn between the swap and the animation showed both pages, so the tab view is now held at 0 from begin and kept there under a forwards-filled animation until it lands.

It looks the same, and lets a snapshot of the page match the window, whose background is tinted by the desktop.
Tabs, Mouse segments and an app's page (and Back) go through PaneTransition: the old page is snapshotted, the change is laid out and measured, and one animation group moves the frame while the snapshot fades out and the new page fades in. The tab view is pinned to the top while the frame moves, so nothing slides. In-pane growth moves the frame the same way, without a fade. A hidden window and Reduce Motion change at once. The tab controller's own cross-fade and window sizing are off, and fitWindow is gone.
@mblauberg mblauberg changed the title Add Settings transition filmstrip capture Settings: change page as one transition with the window frame Nov 4, 2026
@mblauberg
mblauberg marked this pull request as ready for review November 4, 2026 04:23
@mblauberg
mblauberg merged commit 914a2fb into main Nov 4, 2026
2 checks passed
@mblauberg
mblauberg deleted the lane/transitions branch November 4, 2026 06:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Settings: one transition for page changes, content and window together

1 participant