| name | mosaic-debugging |
| description | Debug logging, Debug menu, runtime pitfalls, typing-latency-sensitive paths, SwiftUI list snapshot boundaries, OS-version repros, and local visual iteration for mosaic. Use when adding debug probes, diagnosing UI/runtime issues, touching terminal rendering, tab/sidebar list views, drag/drop UTTypes, or using the Debug menu. |
mosaic Debugging
Debug event log
When adding debug event instrumentation, put events (keys, mouse, focus, splits, tabs) in the unified DEBUG build log. This is not a blanket requirement to add logs to every new code path. Most temporary probes should be added only during the dogfood debug loop and removed before merge.
tail -f "$(cat /tmp/mosaic-last-debug-log-path 2>/dev/null || echo /tmp/mosaic-debug.log)"
- Untagged Debug app:
/tmp/mosaic-debug.log
- Tagged Debug app (
./scripts/reload.sh --tag <tag>): /tmp/mosaic-debug-<tag>.log
reload.sh writes the current path to /tmp/mosaic-last-debug-log-pathreload.sh writes the selected dev CLI path to /tmp/mosaic-last-cli-pathreload.sh updates /tmp/mosaic-cli and $HOME/.local/bin/mosaic-dev to that CLI- Implementation:
Packages/macOS/MosaicDebugLog/Sources/MosaicDebugLog/DebugEventLog.swift
- App shim:
Sources/App/DebugLogging.swift
- Free function
mosaicDebugLog("message") logs with timestamp and appends to file in real time from mosaic code
- The package implementation and app shim are
#if DEBUG; all call sites must be wrapped in #if DEBUG / #endif
- 500-entry ring buffer;
MosaicDebugLog.DebugEventLog.shared.dump() writes full buffer to file
- Key events logged in
AppDelegate.swift (monitor, performKeyEquivalent)
- Mouse/UI events logged inline in views (ContentView, BrowserPanelView, etc.)
- Focus events:
focus.panel, focus.bonsplit, focus.firstResponder, focus.moveFocus
- Bonsplit events:
tab.select, tab.close, tab.dragStart, tab.drop, pane.focus, pane.drop, divider.dragStart
Debug menu
The app has a Debug menu in the macOS menu bar only in DEBUG builds. Use it for visual iteration.
- Debug > Debug Windows contains panels for tuning layout, colors, and behavior. Entries are alphabetical with no dividers.
- To add a debug toggle or visual option: create an
NSWindowController subclass with a shared singleton, add it to the "Debug Windows" menu in Sources/mosaicApp.swift, and add a SwiftUI view with @AppStorage bindings for live changes.
- When the user says "debug menu" or "debug window", they mean this menu, not
defaults write.
Runtime pitfalls
- Custom UTTypes for drag-and-drop must be declared in
Resources/Info.plist under UTExportedTypeDeclarations.
- Do not add an app-level display link or manual
ghostty_surface_draw loop; rely on Ghostty wakeups/renderer to avoid typing lag.
WindowTerminalHostView.hitTest() is typing-latency-sensitive. All divider/sidebar/drag routing is gated to pointer events only. Do not add work outside the isPointerEvent guard.TabItemView uses Equatable conformance plus .equatable() to skip body re-evaluation during typing. Do not add environment/store/binding reads without updating equality and the call site.TerminalSurface.forceRefresh() is called on every keystroke. Do not add allocations, file I/O, or formatting there.SurfaceSearchOverlay must be mounted from GhosttySurfaceScrollView in Sources/GhosttyTerminalView.swift, not from SwiftUI panel containers.- List subtrees with
LazyVStack, LazyHStack, List, or ForEach must pass immutable row snapshots plus closures below the boundary. Do not pass observable stores into row views.
- Functions called from SwiftUI
body must not mutate state or schedule store writes.
- Foundation, SwiftUI, AttributeGraph, and WebKit semantics can change between macOS major versions. Test on the reporter's macOS before declaring a user repro disproven.
Detailed references
