native macOS codings agent orchestrator
chore(shelf): add long-term performance signposts
After the perf push that landed in 0fe682cb, several diagnostic signposts
proved valuable enough to keep around — they cost nothing when no
Instruments session is attached but make future regressions much easier
to localize on the Points of Interest timeline.
What this commit adds:
- SupaLogger: signposter is now created with the well-known
`"PointsOfInterest"` category so events surface in Apple's stock
Points of Interest instrument without any custom subsystem filter
(signpost names already carry origin granularity).
- ShelfView.body / ShelfSpineView.body event markers — sanity-check
body invocation cadence across animation transitions.
- ShelfOpenBookView.onDisappear event — pairs with the existing
onAppear interval so any future change to subtree mount/unmount
cadence shows as a count delta.
- GhosttyTerminalView.makeNSView / updateNSView intervals plus a
dismantleNSView event override — counts and times the
NSViewRepresentable lifecycle, the layer where book-switch teardown
cost is most directly observable.
Behavioural deltas: none — this is pure observability.
+66
-24
+7
supacode/Features/Shelf/Views/ShelfOpenBookView.swift
+7
supacode/Features/Shelf/Views/ShelfOpenBookView.swift
···
68
68
state.syncFocus(windowIsKey: activity.isKeyWindow, windowIsVisible: activity.isVisible)
69
69
}
70
70
}
71
+
.onDisappear {
72
+
// Long-term diagnostic — pairs with `OpenBook.onAppear` so that
73
+
// any future regression in the per-book-switch teardown/remount
74
+
// cadence shows up as a count delta on the Points of Interest
75
+
// timeline.
76
+
shelfLogger.event("OpenBook.onDisappear")
77
+
}
71
78
.onChange(of: state.tabManager.selectedTabId) { _, _ in
72
79
shelfLogger.interval("OpenBook.onChange.selectedTabId") {
73
80
if shouldAutoFocusTerminal {
+8
supacode/Features/Shelf/Views/ShelfSpineView.swift
+8
supacode/Features/Shelf/Views/ShelfSpineView.swift
···
1
1
import Sharing
2
2
import SwiftUI
3
3
4
+
private let shelfLogger = SupaLogger("Shelf")
5
+
4
6
/// Vertical spine rendering for a single book on the Shelf.
5
7
///
6
8
/// Phase 3 scope: header with book-level notification dot, a vertical
···
42
44
@Environment(GhosttyShortcutManager.self) private var ghosttyShortcuts
43
45
44
46
var body: some View {
47
+
// Body-invocation counter signpost. With ~10 spines visible during
48
+
// a book switch, the trace can multiply this event count by spine
49
+
// count to estimate per-click body work. Emitted as a no-arg event
50
+
// (instant timeline marker) so it imposes no work even when
51
+
// Instruments isn't attached.
52
+
let _ = shelfLogger.event("ShelfSpineView.body")
45
53
VStack(spacing: 0) {
46
54
headerButton
47
55
tabList
+6
-4
supacode/Features/Shelf/Views/ShelfView.swift
+6
-4
supacode/Features/Shelf/Views/ShelfView.swift
···
29
29
@Environment(\.surfaceBackgroundOpacity) private var surfaceBackgroundOpacity
30
30
31
31
var body: some View {
32
-
// Note: `body` is a `@ViewBuilder` getter so we can't add a
33
-
// `defer`-based signpost interval directly here. Body-level cost is
34
-
// already visible via the SwiftUI instrument's "View Body" track —
35
-
// signposts in this file focus on user-input moments instead.
32
+
// Body-invocation counter. The @ViewBuilder getter rules out a
33
+
// `defer`-based interval, but a fire-and-forget event marker is a
34
+
// simple expression and has no impact on the rendered tree. Each
35
+
// marker corresponds to one full body re-evaluation — useful for
36
+
// sanity-checking how often the root re-renders during animation.
37
+
let _ = shelfLogger.event("ShelfView.body")
36
38
let state = store.state
37
39
let books = state.orderedShelfBooks()
38
40
let openBookID = state.openShelfBookID
+34
-16
supacode/Infrastructure/Ghostty/GhosttyTerminalView.swift
+34
-16
supacode/Infrastructure/Ghostty/GhosttyTerminalView.swift
···
11
11
}
12
12
13
13
func makeNSView(context: Context) -> GhosttySurfaceScrollView {
14
-
let view = GhosttySurfaceScrollView(surfaceView: surfaceView, hostKind: hostKind)
15
-
view.pinnedSize = pinnedSize
16
-
terminalHostLogger.info(
17
-
"[CanvasExit] hostMake wrapper=\(view.debugIdentifier) host=\(hostKind.rawValue) "
18
-
+ "surface=\(surfaceView.debugIdentifierForLogging) "
19
-
+ "pinned=\(pinnedSize != nil)"
20
-
)
21
-
return view
14
+
// Wrap in a signpost interval so the cost of NSView construction
15
+
// (allocating the scroll view, attaching the Metal-backed surface)
16
+
// shows up on the Points of Interest timeline. Frequency tells us
17
+
// how often `.id(worktree.id)` on `ShelfOpenBookView` is forcing a
18
+
// wholesale teardown/recreate on book switching — total time tells
19
+
// us if AppKit/Metal initialization is on the hot path.
20
+
return terminalHostLogger.interval("Ghostty.makeNSView") {
21
+
let view = GhosttySurfaceScrollView(surfaceView: surfaceView, hostKind: hostKind)
22
+
view.pinnedSize = pinnedSize
23
+
terminalHostLogger.info(
24
+
"[CanvasExit] hostMake wrapper=\(view.debugIdentifier) host=\(hostKind.rawValue) "
25
+
+ "surface=\(surfaceView.debugIdentifierForLogging) "
26
+
+ "pinned=\(pinnedSize != nil)"
27
+
)
28
+
return view
29
+
}
22
30
}
23
31
24
32
func updateNSView(_ view: GhosttySurfaceScrollView, context: Context) {
25
-
view.pinnedSize = pinnedSize
26
-
terminalHostLogger.info(
27
-
"[CanvasExit] hostUpdate wrapper=\(view.debugIdentifier) host=\(hostKind.rawValue) "
28
-
+ "surface=\(surfaceView.debugIdentifierForLogging) "
29
-
+ "pinned=\(pinnedSize != nil) "
30
-
+ "attached=\(view.isSurfaceAttachedToDocumentView)"
31
-
)
32
-
view.ensureSurfaceAttached()
33
+
terminalHostLogger.interval("Ghostty.updateNSView") {
34
+
view.pinnedSize = pinnedSize
35
+
terminalHostLogger.info(
36
+
"[CanvasExit] hostUpdate wrapper=\(view.debugIdentifier) host=\(hostKind.rawValue) "
37
+
+ "surface=\(surfaceView.debugIdentifierForLogging) "
38
+
+ "pinned=\(pinnedSize != nil) "
39
+
+ "attached=\(view.isSurfaceAttachedToDocumentView)"
40
+
)
41
+
view.ensureSurfaceAttached()
42
+
}
43
+
}
44
+
45
+
static func dismantleNSView(_ view: GhosttySurfaceScrollView, coordinator: Void) {
46
+
// Pairs with `Ghostty.makeNSView` on the timeline so the interval
47
+
// count of `make` minus `dismantle` gives a live count of attached
48
+
// surface wrappers — and frequency confirms whether each book
49
+
// switch tears down the wrapper layer.
50
+
terminalHostLogger.event("Ghostty.dismantleNSView")
33
51
}
34
52
}
+11
-4
supacode/Support/SupaLogger.swift
+11
-4
supacode/Support/SupaLogger.swift
···
8
8
/// Signposter for emitting `os_signpost` intervals/events visible in
9
9
/// Instruments. Signposts are essentially zero-cost when no Instruments
10
10
/// session is attached (a single TLS read), so they are always live —
11
-
/// no DEBUG gating. Intervals show up under the logger's category in
12
-
/// the os_signpost track of any trace template that includes it
13
-
/// (Animation Hitches and SwiftUI both do).
11
+
/// no DEBUG gating.
12
+
///
13
+
/// The signposter uses the well-known `"PointsOfInterest"` category
14
+
/// regardless of the logger's own `category` so that intervals and
15
+
/// events automatically surface in Apple's **Points of Interest**
16
+
/// instrument (the discoverable, "just drag it in" track most people
17
+
/// will reach for). The signpost `name:` argument carries the actual
18
+
/// origin (e.g. `"OpenBook.onAppear"`, `"focusSelectedTab"`) so source
19
+
/// granularity is preserved — only the routing category differs from
20
+
/// the regular log channel.
14
21
let signposter: OSSignposter
15
22
16
23
init(_ category: String) {
···
19
26
#if !DEBUG
20
27
self.logger = Logger(subsystem: subsystem, category: category)
21
28
#endif
22
-
self.signposter = OSSignposter(subsystem: subsystem, category: category)
29
+
self.signposter = OSSignposter(subsystem: subsystem, category: "PointsOfInterest")
23
30
}
24
31
25
32
func debug(_ message: String) {