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

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)

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)
    }
}

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
    }
}

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))
        }
    }
}

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()
        }
    }
}

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 } }
    }
}

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")
        }
    }
}

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)
    }
}

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
}

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)
    }
}

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)
    }
}

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])
    }
}

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)
}

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)
        }
    }
}

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:

Initial load (.task(id: agentBridge.events.first?.id)): set to the last 50 events
New event arrives (.onChange(of: events.count)): if in followLatest mode, the sliding window keeps the latest 50 events
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
}

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:

Part 0: Building a macOS Agent Workbench with SwiftUI
Part 1: SDK Integration — Bridging AsyncStream to SwiftUI
Part 2: Event Timeline — Visualizing 18 Event Types
Part 3: Tool Card — An Extensible Tool Visualization System
Part 4: Data Layer and Services — SwiftData, State Restore, Markdown Rendering

GitHub: SwiftWork | Open Agent SDK

推荐订阅源

DEV Community