buttons: long-press detector with staged thresholds

Closes the §6.7 reset-button countdown TODO from the bubble-hwd
commit. NewLongPress wraps a Reader and emits Stage events as a held
press crosses configured durations. Releases before a threshold are
silent; releases after at least one threshold emit a Released stage
so countdown UIs can revert cleanly.

Wires onto the §6.7 'hold reset to factory-reset' flow:

  NewLongPress(ctx, r, Reset, []time.Duration{
    2*time.Second,  // amber LED
    5*time.Second,  // red LED
    10*time.Second, // factory reset
  })

The watcher runs as a goroutine, drops Stage events when a slow
consumer would block (we never want to stall the input loop on UI
rendering), and closes its output channel on ctx cancellation.

Tests cover staged emission, Up-before-threshold (silent), Up-after-
threshold (Released), wrong-button filtering, ctx cancellation, and
empty-thresholds. 6 new tests, all green; vet + gofmt clean.

Author: claude

backend/internal/buttons/longpress.go

@@ -0,0 +1,190 @@
+package buttons
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// LongPress is a stateful watcher that consumes raw Down/Up events
+// from a Reader and emits "the user has been holding this button for
+// at least this long" notifications at configurable thresholds.
+//
+// DESIGN.md §6.7 needs this for the reset-button factory-reset
+// countdown: 2-5 s shows amber LED feedback, 5-10 s shows red,
+// >10 s triggers the actual reset. We model that as a list of
+// thresholds; the watcher emits a Stage event each time the press
+// crosses one. Releases (Up) before a threshold cancel the press.
+//
+// The watcher runs as a background goroutine; callers consume from
+// Stages() until ctx is cancelled. Multi-button setups instantiate
+// one LongPress per button.
+type LongPress struct {
+	button     Button
+	thresholds []time.Duration
+
+	out  chan Stage
+	now  func() time.Time
+	stop chan struct{}
+
+	mu     sync.Mutex
+	closed bool
+}
+
+// Stage is emitted when a held press crosses a configured threshold.
+// Released indicates the user let go before reaching this Stage —
+// always emitted with the highest reached threshold so callers can
+// undo any countdown UI they were showing.
+type Stage struct {
+	Button   Button
+	Index    int           // 0-based position in the configured thresholds
+	Hold     time.Duration // how long the press has been active
+	Released bool          // true if the user let go before/at this stage
+}
+
+// NewLongPress wires a LongPress watcher to the given Reader. The
+// watcher reads from r.Events() in a goroutine and writes Stage
+// events to the returned channel. Stop the watcher by cancelling
+// ctx; the channel is closed afterward.
+//
+// Thresholds must be in strictly ascending order. An empty list
+// disables the watcher (it forwards no Stages but still cleans up
+// on ctx cancellation).
+func NewLongPress(ctx context.Context, r Reader, button Button, thresholds []time.Duration) *LongPress {
+	lp := &LongPress{
+		button:     button,
+		thresholds: thresholds,
+		out:        make(chan Stage, 16),
+		now:        time.Now,
+		stop:       make(chan struct{}),
+	}
+	go lp.loop(ctx, r)
+	return lp
+}
+
+// Stages returns the channel of emitted Stage events. Closed when
+// the watcher exits (ctx cancellation).
+func (l *LongPress) Stages() <-chan Stage { return l.out }
+
+// SetClock overrides the time source for tests.
+func (l *LongPress) SetClock(f func() time.Time) {
+	l.mu.Lock()
+	l.now = f
+	l.mu.Unlock()
+}
+
+func (l *LongPress) loop(ctx context.Context, r Reader) {
+	defer l.close()
+
+	var (
+		pressedAt time.Time
+		lastStage = -1
+		timer     *time.Timer
+		timerCh   <-chan time.Time
+	)
+
+	resetTimer := func() {
+		if timer != nil {
+			timer.Stop()
+			timer = nil
+			timerCh = nil
+		}
+	}
+	scheduleNext := func() {
+		resetTimer()
+		next := lastStage + 1
+		if next >= len(l.thresholds) {
+			return
+		}
+		l.mu.Lock()
+		now := l.now()
+		l.mu.Unlock()
+		fireAt := pressedAt.Add(l.thresholds[next])
+		delay := fireAt.Sub(now)
+		if delay < 0 {
+			delay = 0
+		}
+		timer = time.NewTimer(delay)
+		timerCh = timer.C
+	}
+
+	emit := func(s Stage) {
+		select {
+		case l.out <- s:
+		default:
+			// Drop if consumer is slow; we don't want to block the loop.
+		}
+	}
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case ev, ok := <-r.Events():
+			if !ok {
+				return
+			}
+			if ev.Button != l.button {
+				continue
+			}
+			switch ev.Kind {
+			case Down:
+				if !pressedAt.IsZero() {
+					// Already pressed (event repeat?). Ignore.
+					continue
+				}
+				l.mu.Lock()
+				pressedAt = l.now()
+				l.mu.Unlock()
+				lastStage = -1
+				scheduleNext()
+			case Up:
+				if pressedAt.IsZero() {
+					continue
+				}
+				if lastStage >= 0 {
+					// Notify caller of release at the highest reached stage
+					// so UI countdowns can revert.
+					l.mu.Lock()
+					hold := l.now().Sub(pressedAt)
+					l.mu.Unlock()
+					emit(Stage{
+						Button:   l.button,
+						Index:    lastStage,
+						Hold:     hold,
+						Released: true,
+					})
+				}
+				resetTimer()
+				pressedAt = time.Time{}
+				lastStage = -1
+			}
+		case <-timerCh:
+			if pressedAt.IsZero() {
+				resetTimer()
+				continue
+			}
+			next := lastStage + 1
+			l.mu.Lock()
+			hold := l.now().Sub(pressedAt)
+			l.mu.Unlock()
+			emit(Stage{
+				Button: l.button,
+				Index:  next,
+				Hold:   hold,
+			})
+			lastStage = next
+			scheduleNext()
+		}
+	}
+}
+
+func (l *LongPress) close() {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if l.closed {
+		return
+	}
+	l.closed = true
+	close(l.out)
+}

backend/internal/buttons/longpress_test.go

@@ -0,0 +1,152 @@
+package buttons
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestLongPressEmitsStagesInOrder(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, []time.Duration{
+		50 * time.Millisecond,
+		120 * time.Millisecond,
+		250 * time.Millisecond,
+	})
+
+	r.Down(Reset)
+
+	var got []Stage
+	deadline := time.After(800 * time.Millisecond)
+loop:
+	for len(got) < 3 {
+		select {
+		case s := <-lp.Stages():
+			got = append(got, s)
+		case <-deadline:
+			break loop
+		}
+	}
+	r.Up(Reset)
+
+	if len(got) != 3 {
+		t.Fatalf("got %d stages, want 3: %+v", len(got), got)
+	}
+	for i, s := range got {
+		if s.Released {
+			t.Errorf("stage %d should not be released", i)
+		}
+		if s.Index != i {
+			t.Errorf("stage %d Index = %d, want %d", i, s.Index, i)
+		}
+		if s.Button != Reset {
+			t.Errorf("stage %d Button = %s", i, s.Button)
+		}
+	}
+}
+
+func TestLongPressUpBeforeFirstThresholdEmitsNothing(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, []time.Duration{500 * time.Millisecond})
+	r.Down(Reset)
+	time.Sleep(20 * time.Millisecond)
+	r.Up(Reset)
+
+	select {
+	case s := <-lp.Stages():
+		t.Fatalf("expected no stages, got %+v", s)
+	case <-time.After(200 * time.Millisecond):
+		// Good.
+	}
+}
+
+func TestLongPressReleaseAfterStageEmitsReleased(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, []time.Duration{
+		50 * time.Millisecond,
+		500 * time.Millisecond,
+	})
+	r.Down(Reset)
+
+	// Wait for the first stage to fire.
+	first := <-lp.Stages()
+	if first.Released {
+		t.Fatal("first stage should not be Released")
+	}
+
+	r.Up(Reset)
+
+	released := <-lp.Stages()
+	if !released.Released {
+		t.Fatalf("expected Released=true, got %+v", released)
+	}
+	if released.Index != 0 {
+		t.Errorf("Released Index = %d, want 0 (highest reached)", released.Index)
+	}
+}
+
+func TestLongPressIgnoresOtherButtons(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, []time.Duration{30 * time.Millisecond})
+	r.Down(Mode1)
+	r.Up(Mode1)
+
+	select {
+	case s := <-lp.Stages():
+		t.Fatalf("unexpected stage from non-Reset button: %+v", s)
+	case <-time.After(80 * time.Millisecond):
+	}
+}
+
+func TestLongPressCancelClosesChannel(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, []time.Duration{50 * time.Millisecond})
+	cancel()
+
+	// Channel should close within a beat.
+	select {
+	case _, ok := <-lp.Stages():
+		if ok {
+			t.Error("expected closed channel after cancel")
+		}
+	case <-time.After(200 * time.Millisecond):
+		t.Fatal("Stages channel did not close after cancel")
+	}
+}
+
+func TestLongPressEmptyThresholdsIsHarmless(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	r := NewMock()
+	defer r.Stop()
+
+	lp := NewLongPress(ctx, r, Reset, nil)
+	r.Down(Reset)
+	r.Up(Reset)
+
+	select {
+	case s := <-lp.Stages():
+		t.Fatalf("expected no stages, got %+v", s)
+	case <-time.After(60 * time.Millisecond):
+	}
+}