Progress bar completion percentage desynchronized from actual work in Bubble Tea

[A-kirami]

I'm working on a concurrent download manager using Bubble Tea and running into a weird progress bar synchronization issue. The bars complete at different percentages depending on how fast my workers finish, which suggests I'm missing something fundamental about progress reporting.

The Symptom:

// Simulate download function
func simulateDownload(m *Model, name string, total int) {
	for i := 0; i <= total; i++ {
		select {
		case <-m.Ctx.Done():
			return
		default:
			m.UpdateProgress(name, i)
			time.Sleep(10 * time.Millisecond) // Changing the time here will affect the final outcome of the progress bar.
		}
	}
}

When I adjust the time.Sleep duration in my progress updater:

• Sleep(10ms) →
• Sleep(50ms) →
• Sleep(200ms) →

What I've Verified:
✔ All worker goroutines complete their tasks
✔ Progress messages make it to Bubble Tea
✔ The math in my percentage calculation looks correct

Core Question:
How should I properly synchronize:

1. Actual work completion with progress reporting?
2. Concurrent updates with Bubble Tea's render cycle?

I suspect this is either:
a) A timing issue between my workers and the TUI, or
b) That I'm using SetPercent incorrectly for concurrent scenarios

Has anyone implemented something similar? Would especially appreciate:

• Patterns for coordinating multiple progress updaters
• How to avoid render cycle conflicts
• Best practices for "true" percentage reporting

Here's a minimal example demonstrating the problem:

Code

package main

import (
	"context"
	"fmt"
	"io"
	"strings"
	"sync"
	"time"

	"github.com/charmbracelet/bubbles/list"
	"github.com/charmbracelet/bubbles/progress"
	tea "github.com/charmbracelet/bubbletea"
)

// Download item structure
type DownloadItem struct {
	Name     string
	Progress progress.Model
	Total    int
	Current  int
	Err      error
}

// List item structure
type DownloadListItem struct {
	Name     string
	Progress progress.Model
	Total    int
	Current  int
	Err      error
}

func (i DownloadListItem) Title() string {
	progress := float64(i.Current) / float64(i.Total)
	progressStr := fmt.Sprintf("%.1f%%", progress*100)
	if i.Err != nil {
		return fmt.Sprintf("❌ %s (%s) - Error: %v", i.Name, progressStr, i.Err)
	}
	return fmt.Sprintf("⏳ %s (%s)", i.Name, progressStr)
}

func (i DownloadListItem) Description() string {
	return i.Progress.View()
}

func (i DownloadListItem) FilterValue() string { return i.Name }

// Download delegate
type DownloadDelegate struct{}

func (d DownloadDelegate) Height() int                               { return 2 }
func (d DownloadDelegate) Spacing() int                              { return 1 }
func (d DownloadDelegate) Update(msg tea.Msg, m *list.Model) tea.Cmd { return nil }
func (d DownloadDelegate) Render(w io.Writer, m list.Model, index int, item list.Item) {
	dl, ok := item.(DownloadListItem)
	if !ok {
		return
	}
	title := dl.Title()
	desc := dl.Description()
	fmt.Fprintf(w, "%s\n%s", title, desc)
}

// Main model
type Model struct {
	Items        map[string]*DownloadItem
	ItemOrder    []string
	DownloadList list.Model
	Width        int
	program      *tea.Program
	Ctx          context.Context
	Cancel       context.CancelFunc
}

func NewModel() *Model {
	ctx, cancel := context.WithCancel(context.Background())

	// Create download list
	downloadDelegate := DownloadDelegate{}
	downloadList := list.New([]list.Item{}, downloadDelegate, 0, 0)
	downloadList.Title = "Download Progress"
	downloadList.SetShowHelp(false)

	return &Model{
		Items:        make(map[string]*DownloadItem),
		ItemOrder:    []string{},
		DownloadList: downloadList,
		Ctx:          ctx,
		Cancel:       cancel,
	}
}

func (m *Model) Init() tea.Cmd {
	return nil
}

func (m *Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
	var cmds []tea.Cmd

	switch msg := msg.(type) {
	case tea.KeyMsg:
		if msg.String() == "ctrl+c" {
			m.Cancel()
			return m, tea.Quit
		}

	case tea.WindowSizeMsg:
		m.Width = msg.Width - 4
		for _, item := range m.Items {
			item.Progress.Width = m.Width
		}
		m.DownloadList.SetWidth(msg.Width - 4)
		m.DownloadList.SetHeight(msg.Height - 4)

	case progressMsg:
		item, exists := m.Items[msg.itemName]
		if !exists {
			item = &DownloadItem{
				Name:     msg.itemName,
				Progress: progress.New(progress.WithDefaultGradient()),
				Total:    1,
			}
			item.Progress.Width = m.Width
			m.Items[msg.itemName] = item
		}

		item.Current = int(msg.ratio * float64(item.Total))
		cmds = append(cmds, item.Progress.SetPercent(msg.ratio))
		m.updateDownloadList()

	case progress.FrameMsg:
		for _, item := range m.Items {
			progressModel, cmd := item.Progress.Update(msg)
			item.Progress = progressModel.(progress.Model)
			cmds = append(cmds, cmd)
		}
	}

	return m, tea.Batch(cmds...)
}

func (m *Model) View() string {
	var s strings.Builder
	s.WriteString("\n")
	s.WriteString(m.DownloadList.View())
	s.WriteString("\n\n")
	s.WriteString("Press Ctrl+C to exit")
	return s.String()
}

type progressMsg struct {
	itemName string
	ratio    float64
}

func (m *Model) AddDownloadItem(name string, totalFiles int) {
	item := &DownloadItem{
		Name:     name,
		Progress: progress.New(progress.WithDefaultGradient()),
		Total:    totalFiles,
		Current:  0,
	}
	if m.Width > 0 {
		item.Progress.Width = m.Width
	}
	m.Items[name] = item
	m.ItemOrder = append(m.ItemOrder, name)
	m.updateDownloadList()
}

func (m *Model) UpdateProgress(name string, current int) {
	if item, exists := m.Items[name]; exists {
		ratio := float64(current) / float64(item.Total)
		m.program.Send(progressMsg{
			itemName: name,
			ratio:    ratio,
		})
	}
}

func (m *Model) updateDownloadList() {
	items := make([]list.Item, 0, len(m.Items))
	for _, name := range m.ItemOrder {
		if item, exists := m.Items[name]; exists {
			items = append(items, DownloadListItem{
				Name:     item.Name,
				Progress: item.Progress,
				Total:    item.Total,
				Current:  item.Current,
				Err:      item.Err,
			})
		}
	}
	m.DownloadList.SetItems(items)
}

func (m *Model) SetProgram(p *tea.Program) {
	m.program = p
}

// Simulate download function
func simulateDownload(m *Model, name string, total int) {
	for i := 0; i <= total; i++ {
		select {
		case <-m.Ctx.Done():
			return
		default:
			m.UpdateProgress(name, i)
			time.Sleep(10 * time.Millisecond) // Changing the time here will affect the final outcome of the progress bar.
		}
	}
}

func main() {
	m := NewModel()
	p := tea.NewProgram(m)
	m.SetProgram(p)

	// Start simulated downloads
	go func() {
		var wg sync.WaitGroup
		for i := 1; i <= 3; i++ {
			wg.Add(1)
			go func(id int) {
				defer wg.Done()
				name := fmt.Sprintf("Download Task %d", id)
				m.AddDownloadItem(name, 10)
				simulateDownload(m, name, 10)
			}(i)
		}
		wg.Wait()
	}()

	if _, err := p.Run(); err != nil {
		fmt.Printf("Error: %v", err)
	}
}

Thanks in advance for any insights! This has me stumped after several hours of tweaking.