DEV Community

NEE
NEE

Posted on

Deep Dive into SwiftWork (Part 2): Event Timeline — Visualizing 18 Event Types

#swift #swiftui #visualization #performance

Post 1 covered how AgentBridge converts the SDK's AsyncStream<SDKMessage> into [AgentEvent]. This post looks at what [AgentEvent] becomes — how TimelineView renders 18 event types, handles scroll behavior, and stays smooth when the event count gets large.

TimelineView Structure

TimelineView is the main body of the workspace, filling all the space between the sidebar and the input box. Its view hierarchy is shallow:

TimelineView
  ├── ScrollView
  │   ├── topPlaceholder (virtualization spacer)
  │   ├── LazyVStack
  │   │   └── ForEach(virtualizedEvents) → eventView(for:)
  │   ├── bottomPlaceholder (virtualization spacer)
  │   ├── StreamingTextView (streaming text)
  │   └── bottom-anchor (scroll anchor)
  └── returnToBottomButton (return to bottom)
Enter fullscreen mode Exit fullscreen mode

When there are no events, an empty state is shown: "Send a message to start a conversation with the Agent." When events exist, it enters a ScrollViewReader + LazyVStack structure.

Event Dispatch: 18 Types to 8 Views

eventView(for:) is the core of event dispatch. 18 AgentEventType values map to 8 views:

@ViewBuilder
private func eventView(for event: AgentEvent) -> some View {
    switch event.type {
    case .userMessage:       UserMessageView(event: event)
    case .partialMessage:    EmptyView()
    case .assistant:         AssistantMessageView(event: event)
    case .toolUse:           toolCardView(for: event)
    case .toolResult,
         .toolProgress:      pairedToolEventView(for: event)
    case .result:            ResultView(event: event)
    case .system:            systemOrThinking(event: event)
    case .hookStarted, .hookProgress, .hookResponse,
         .taskStarted, .taskProgress, .authStatus,
         .filesPersisted, .localCommandOutput,
         .promptSuggestion, .toolUseSummary:
                             SystemEventView(event: event)
    case .unknown:           UnknownEventView(event: event)
    }
}
Enter fullscreen mode Exit fullscreen mode

A few dispatch logic decisions worth noting:

partialMessage renders as EmptyView. Streaming text does not go through ForEach(events) — it is rendered separately by StreamingTextView below the LazyVStack. The reason was covered in Post 1: partialMessage only accumulates in streamingText and never enters the events array. This avoids the flickering and performance overhead caused by frequent insertions and deletions in ForEach.

toolUse goes through toolCardView, while toolResult/toolProgress go through pairedToolEventView. If the toolContentMap has a matching entry (meaning a paired toolUse has already been received), toolUse renders as ToolCardView, and the paired toolResult/toolProgress renders as EmptyView — because their content is already merged into the card. If there is no match in toolContentMap (e.g., incomplete historical event loading), it falls back to simple ToolCallView/ToolResultView.

The system type needs to distinguish between "thinking" and ordinary system events. The systemOrThinking method checks the subtype in metadata:

private func systemOrThinking(event: AgentEvent) -> some View {
    let subtype = event.metadata["subtype"] as? String ?? ""
    let isLastEvent = agentBridge.events.last?.id == event.id
    if (subtype == "init" || subtype == "status") && isLastEvent {
        ThinkingView()              // spinning gear + "Thinking..."
    } else if subtype == "init" || subtype == "status" {
        ThinkingView(isActive: false) // checkmark + "Agent responded"
    } else if let isError = event.metadata["isError"] as? Bool, isError {
        SystemEventView(event: event, isError: true)  // red error bar
    } else {
        SystemEventView(event: event)  // normal system message
    }
}
Enter fullscreen mode Exit fullscreen mode

Only the last init/status event shows the spinning animation. Historical events display a static "Agent responded" state. This prevents all historical thinking states from spinning endlessly.

Design of Each Event View

UserMessageView — Right-Aligned Blue Bubble 

struct UserMessageView: View {
    let event: AgentEvent
    var body: some View {
        HStack {
            Spacer()
            Text(event.content)
                .padding(.horizontal, 12)
                .padding(.vertical, 8)
                .background(.blue.opacity(0.15))
                .clipShape(RoundedRectangle(cornerRadius: 12))
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

User messages are right-aligned with a semi-transparent blue background and rounded rectangle. This matches the ChatGPT message layout.

AssistantMessageView — Left Vertical Line + Markdown 

struct AssistantMessageView: View {
    let event: AgentEvent
    var body: some View {
        HStack(alignment: .top, spacing: 0) {
            RoundedRectangle(cornerRadius: 1)
                .fill(Color.secondary.opacity(0.3))
                .frame(width: 2)
                .padding(.trailing, 8)
            MarkdownContentView(markdown: event.content)
            Spacer()
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

A gray vertical line on the left serves as a visual separator, and the content is rendered using MarkdownContentView. This component handles Markdown parsing, code highlighting, and long text folding — Post 4 will cover it in detail.

ThinkingView — Spinning Gear Animation 

struct ThinkingView: View {
    var isActive: Bool = true
    @State private var isAnimating = false

    var body: some View {
        HStack(spacing: 8) {
            if isActive {
                Image(systemName: "gearshape")
                    .rotationEffect(.degrees(isAnimating ? 360 : 0))
                    .animation(.linear(duration: 1).repeatForever(autoreverses: false),
                               value: isAnimating)
                Text("Thinking...")
            } else {
                Image(systemName: "checkmark.circle")
                Text("Agent responded")
            }
            Spacer()
        }
        .onAppear { if isActive { isAnimating = true } }
    }
}
Enter fullscreen mode Exit fullscreen mode

isActive controls two states: a spinning gear indicates active thinking, and a green checkmark indicates thinking is complete. onAppear triggers the animation, and it does not re-trigger when the view scrolls off-screen and back.

ResultView — Execution Result + Statistics 

struct ResultView: View {
    let event: AgentEvent
    // Extract durationMs, totalCostUsd, numTurns from metadata
    var body: some View {
        HStack(spacing: 4) {
            Image(systemName: statusIcon)  // checkmark.circle / pause.circle / xmark.circle
                .foregroundStyle(statusColor)
            Text(subtype)  // success / cancelled / error
        }
        // Below: duration | turns | cost
        HStack(spacing: 12) {
            Label("\(duration)ms", systemImage: "clock")
            Label("\(turns) turns", systemImage: "arrow.triangle.2.circlepath")
            Label(String(format: "$%.4f", cost), systemImage: "dollarsign.circle")
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The Result event displays a summary of execution statistics — duration in milliseconds, number of conversation turns, and cost in US dollars. Errors are highlighted with a red background.

SystemEventView — System Messages and Error Alerts 

struct SystemEventView: View {
    let event: AgentEvent
    let isError: Bool

    var body: some View {
        HStack(spacing: 4) {
            if isError {
                RoundedRectangle(cornerRadius: 1).fill(Color.red).frame(width: 3)
                Image(systemName: "exclamationmark.triangle.fill").foregroundStyle(.red)
            } else {
                Image(systemName: "info.circle").foregroundStyle(.secondary)
            }
            Text(event.content)
        }
        .background(isError ? Color.red.opacity(0.08) : Color.clear)
    }
}
Enter fullscreen mode Exit fullscreen mode

Normal system messages appear as a single line of gray text with an info icon. Error messages add a red left bar, red background, and warning icon.

Scroll Behavior: Follow Latest vs Manual Browse

An Agent continuously produces events during execution. Users typically want to see the latest events (auto-scroll to bottom), but sometimes want to scroll up and review history. These two needs conflict.

SwiftWork uses ScrollModeManager to manage switching between two modes:

enum ScrollMode {
    case followLatest    // Auto-follow the latest event
    case manualBrowse    // User manually browses history
}

@MainActor
@Observable
final class ScrollModeManager {
    var scrollMode: ScrollMode = .followLatest

    var showReturnToBottomButton: Bool {
        scrollMode == .manualBrowse
    }

    private let nearBottomThreshold: CGFloat = 96
    private let scrollUpThreshold: CGFloat = 16
    private var cumulativeUpwardDelta: CGFloat = 0
}
Enter fullscreen mode Exit fullscreen mode

Auto-follow condition: When the user is within 96pt of the bottom, the mode automatically switches back to followLatest. Each time a new event arrives, TimelineView auto-scrolls to the bottom.

Switch to manual browse condition: When the user scrolls up more than 16pt, the mode switches to manualBrowse. At this point, new events no longer trigger auto-scrolling, and a "return to bottom" button appears in the lower-right corner.

// TimelineView.swift
.onChange(of: agentBridge.events.count) { _, newCount in
    updateVisibleRangeForCount(newCount)
    if scrollModeManager.scrollMode == .followLatest {
        scrollToLast(proxy: proxy)
    }
}
.onChange(of: agentBridge.streamingText) { _, _ in
    if scrollModeManager.scrollMode == .followLatest {
        scrollToLast(proxy: proxy)
    }
}
Enter fullscreen mode Exit fullscreen mode

Two onChange handlers listen for event count changes and streaming text changes. Auto-scrolling only happens in followLatest mode.

Return to bottom button: When tapped, it switches back to followLatest, updates visibleRange to the latest 50 events, and animates the scroll to the bottom:

Button {
    scrollModeManager.returnToBottom()
    let total = agentBridge.events.count
    let lower = max(0, total - 50)
    visibleRange = lower..<total
    withAnimation {
        proxy.scrollTo("bottom-anchor", anchor: .bottom)
    }
}
Enter fullscreen mode Exit fullscreen mode

Virtualization: Render Only the Visible Range

When the event count exceeds a few hundred, rendering everything causes LazyVStack to create a large number of views, leading to dropped frames during scrolling. SwiftWork uses visibleRange + renderBuffer for virtualization — only rendering events within approximately ±20 of the visible area.

@MainActor
final class TimelineVirtualizationManager {
    let renderBuffer = 20

    func eventsToRender(visibleRange: Range<Int>, allEvents: [AgentEvent]) -> [AgentEvent] {
        guard !allEvents.isEmpty else { return [] }
        let lower = max(0, visibleRange.lowerBound - renderBuffer)
        let upper = min(allEvents.count, visibleRange.upperBound + renderBuffer)
        guard lower < upper else { return [] }
        return Array(allEvents[lower..<upper])
    }
}
Enter fullscreen mode Exit fullscreen mode

What gets passed to ForEach is not agentBridge.events, but virtualizedEvents — a subset trimmed by virtualization:

private var virtualizedEvents: [AgentEvent] {
    let allEvents = agentBridge.events
    if allEvents.isEmpty { return [] }
    if visibleRange.isEmpty {
        let upper = allEvents.count
        let lower = max(0, upper - 50)
        return virtualizationManager.eventsToRender(visibleRange: lower..<upper, allEvents: allEvents)
    }
    return virtualizationManager.eventsToRender(visibleRange: visibleRange, allEvents: allEvents)
}
Enter fullscreen mode Exit fullscreen mode

Clipped regions are replaced with spacers to maintain accurate scrollbar positioning:

private var topPlaceholder: some View {
    let upper = max(0, visibleRange.lowerBound - virtualizationManager.renderBuffer)
    return Group {
        if upper > 0 && !visibleRange.isEmpty {
            Spacer().frame(height: CGFloat(upper) * estimatedRowHeight)
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

estimatedRowHeight is set to 80pt — an empirical value around which most event views fall. It does not need to be exact; it just needs to keep the scrollbar position roughly correct.

When visibleRange Gets Updated

visibleRange is updated at several key moments:

  1. Initial load (.task(id: agentBridge.events.first?.id)): set to the last 50 events
  2. New event arrives (.onChange(of: events.count)): if in followLatest mode, the sliding window keeps the latest 50 events
  3. Return to bottom: reset to the latest 50 events

Currently, dynamic visibleRange updates during scrolling are not implemented — when the user scrolls up to browse a large number of historical events, visibleRange does not follow the scroll position. This is a known limitation that could be addressed in the future using onAppear/onDisappear callbacks or ScrollView offset monitoring.

Initial Scroll: Fixing First-Load Flash

When the event list first loads, SwiftUI's ScrollView starts rendering from the top by default. If a session has hundreds of events, the user first sees the top events, then a flash as it jumps to the bottom. This flash appears every time the user switches sessions.

SwiftWork's solution: delay scrolling to the bottom by 150ms, waiting for LazyVStack to complete its first-screen render:

.task(id: agentBridge.events.first?.id) {
    hasCompletedInitialScroll = false
    guard !agentBridge.events.isEmpty else { return }
    scrollModeManager.scrollMode = .followLatest
    visibleRange = 0..<0
    try? await Task.sleep(for: .milliseconds(150))
    guard !Task.isCancelled else { return }
    let total = agentBridge.events.count
    let lower = max(0, total - 50)
    visibleRange = lower..<total
    withAnimation {
        proxy.scrollTo("bottom-anchor", anchor: .bottom)
    }
    hasCompletedInitialScroll = true
}
Enter fullscreen mode Exit fullscreen mode

The hasCompletedInitialScroll flag controls subsequent scroll mode switching — before the initial scroll completes, onChange(of: scrollPositionId) does not trigger mode switching, avoiding interference.

Summary

TimelineView's design can be summarized as three subsystems:

Subsystem Problem Solved Implementation
Event dispatch 18 types to 8 views eventView(for:) + ViewBuilder
Scroll control Auto-follow vs manual browse ScrollModeManager + scrollPosition
Virtualization Render performance with many events visibleRange + renderBuffer + placeholders

Event dispatch is pure view logic — selecting the corresponding view component based on event.type. Scroll control and virtualization are performance concerns unique to TimelineView, unrelated to the SDK integration layer.

The next post covers the Tool Card system — how the ToolRenderable protocol gives each tool its own renderer, and how ToolRendererRegistry enables adding new tool types without modifying the timeline code.

Deep Dive into SwiftWork Series:

GitHub: SwiftWork | Open Agent SDK

Top comments (0)