[dxnnystyles]

What this changes

• adds signpost intervals for surface transitions, including interrupted ones
• adds events for panel prepare + trim
• keeps overhead minimal when recording is off
• documents how to measure everything in Instruments

Closes #14

Why

The motion timings were already defined, but there wasn't a way to measure the actual transitions in Instruments. This adds that without changing how the animations behave.

How it was tested

• swift test --disable-sandbox — 196 passed

• python3 -I Tests/test_bridge.py — 24 passed

• Universal Release build passed

• Project regeneration completed successfully; generated Xcode project updated.

• Checked on macOS 26.5 with Instruments

• git diff --check passed

• Captured 12 transition intervals in Instruments, all with matching starts + ends

• Tested opening, collapsing, and switching features mid-transition

Profiling used a Release-optimized build with the Debug command channel enabled for repeatable interactions.

Animated transitions measured around 0.64–1.22s from commit to completion. The longest overlapped with two later transitions, so I couldn't confirm what caused the delay.

No before/after screenshots are included because the change adds instrumentation without changing the visual interface.

Accessibility and motion

• No controls or animation behavior changed; this only adds instrumentation.

Privacy and security

• No new permissions, network requests, or user data collection.
• No tokens, personal paths, or private data in code or logs.

[argahv]

Thanks, this is a clean way in, and the measurements in the description are really helpful. A couple of things against #14's criteria:

• Superseded transitions (Sources/NotchFlow/AppModel.swift:792). Each interval only ends in its own .removed completion, so a transition interrupted by a newer one isn't closed or marked when it's replaced. Its interval runs on through the transitions that took over, which probably explains the 0.64–1.22 s intervals and the long one overlapping two later transitions. #14 asked for these to end correctly using the transition counter. For example, end with a superseded flag from windows?.isLatest(transition), or end the previous open interval when a newer transition begins.
• Intervals that never end (line 798). When the completion is held back (Mission Control, occlusion), the 0.9 s fallback trims the panel but leaves the interval open. Ending it there too, marked as a fallback, with a flag so it only ends once, would keep the Instruments numbers clean.
• Small: emitEvent with a static name already does nothing when recording is off, so the if signposter.isEnabled guards in WindowManager.swift (lines 235 and 266) can go.

[dxnnystyles]

thanks for pointing these out! superseded transitions now close their intervals, and the fallback closes them too. added a registry so each interval can only end once + removed the extra isEnabled guards. lifecycle tests, full suite, + Release build passed. the fallback path is test-covered but hasn't been captured in Instruments yet.