feat(overlay): add gradual fade effect for aging caption lines

Updated the overlay sink and state to apply a gradual fade from white to gray for completed caption lines over their display lifetime. The `FinalMarkup` method replaces plain `FinalText`, generating Pango markup with decreasing brightness. A periodic refresh timer (200 ms) recalculates colors and expiry, improving visual clarity of line recency. README updated to document the new fade behavior.

src/output/overlay/overlay_gtk.go

@@ -215,7 +215,7 @@ static gboolean captioneer_apply_update(gpointer data) {
 	CaptioneerOverlay *overlay = update->overlay;
 
 	overlay->final_visible = update->final_text[0] != '\0';
-	gtk_label_set_text(GTK_LABEL(overlay->final_label), update->final_text);
+	gtk_label_set_markup(GTK_LABEL(overlay->final_label), update->final_text);
 	gtk_widget_set_visible(overlay->final_label, overlay->final_visible);
 
 	overlay->preview_visible = update->preview_text[0] != '\0';
@@ -449,6 +449,8 @@ import (
 	"tea.chunkbyte.com/kato/captioneer/src/config"
 )
 
+const finalFadeRefreshInterval = 200 * time.Millisecond
+
 type Sink struct {
 	native       *C.CaptioneerOverlay
 	finalTimeout time.Duration
@@ -500,29 +502,27 @@ func (s *Sink) Publish(event captions.Event) error {
 		s.stopFinalTimer()
 	}
 	if event.Kind == captions.Final {
-		s.scheduleFinalExpiry(now)
+		s.scheduleFinalRefresh(now)
 	}
 	s.postState()
 	return nil
 }
 
-func (s *Sink) expireFinal() {
+func (s *Sink) refreshFinals() {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if s.closed {
 		return
 	}
 	now := time.Now()
-	changed := s.state.ExpireFinal(now)
+	s.state.ExpireFinal(now)
 	s.finalTimer = nil
-	s.scheduleFinalExpiry(now)
-	if changed {
-		s.postState()
-	}
+	s.scheduleFinalRefresh(now)
+	s.postState()
 }
 
 func (s *Sink) postState() {
-	finalText := C.CString(s.state.FinalText())
+	finalText := C.CString(s.state.FinalMarkup(time.Now(), s.finalTimeout))
 	previewText := C.CString(s.state.Provisional)
 	defer C.free(unsafe.Pointer(finalText))
 	defer C.free(unsafe.Pointer(previewText))
@@ -536,16 +536,24 @@ func (s *Sink) stopFinalTimer() {
 	}
 }
 
-func (s *Sink) scheduleFinalExpiry(now time.Time) {
-	expiresAt := s.state.NextFinalExpiry()
-	if expiresAt.IsZero() {
+func (s *Sink) scheduleFinalRefresh(now time.Time) {
+	if len(s.state.Finals) == 0 {
 		return
 	}
-	delay := expiresAt.Sub(now)
+	if s.state.NextFinalExpiry().IsZero() && !s.state.NeedsFadeRefresh(now, s.finalTimeout) {
+		return
+	}
+
+	nextRefresh := now.Add(finalFadeRefreshInterval)
+	expiresAt := s.state.NextFinalExpiry()
+	if !expiresAt.IsZero() && expiresAt.Before(nextRefresh) {
+		nextRefresh = expiresAt
+	}
+	delay := nextRefresh.Sub(now)
 	if delay < 0 {
 		delay = 0
 	}
-	s.finalTimer = time.AfterFunc(delay, s.expireFinal)
+	s.finalTimer = time.AfterFunc(delay, s.refreshFinals)
 }
 
 func (s *Sink) Run() error {

src/output/overlay/state.go

@@ -1,15 +1,22 @@
 package overlay
 
 import (
+	"fmt"
+	"html"
 	"strings"
 	"time"
 
 	"tea.chunkbyte.com/kato/captioneer/src/captions"
 )
 
-const maxVisibleFinalLines = 6
+const (
+	maxVisibleFinalLines    = 6
+	oldestLineBrightness    = 0.65
+	defaultLineFadeDuration = 3 * time.Second
+)
 
 type finalLine struct {
+	CreatedAt time.Time
 	Text      string
 	ExpiresAt time.Time
 }
@@ -28,7 +35,7 @@ func (s *viewState) Apply(event captions.Event, now time.Time, finalTimeout time
 		if text == "" {
 			return
 		}
-		line := finalLine{Text: text}
+		line := finalLine{CreatedAt: now, Text: text}
 		if finalTimeout > 0 {
 			line.ExpiresAt = now.Add(finalTimeout)
 		}
@@ -66,9 +73,53 @@ func (s viewState) FinalText() string {
 	return strings.Join(lines, "\n")
 }
 
+func (s viewState) FinalMarkup(now time.Time, lineLifetime time.Duration) string {
+	fadeDuration := lineLifetime
+	if fadeDuration <= 0 {
+		fadeDuration = defaultLineFadeDuration
+	}
+
+	var markup strings.Builder
+	for i, line := range s.Finals {
+		if i > 0 {
+			markup.WriteByte('\n')
+		}
+		brightness := lineBrightness(now.Sub(line.CreatedAt), fadeDuration)
+		channel := int(brightness*255 + 0.5)
+		fmt.Fprintf(&markup, `<span foreground="#%02X%02X%02X">`, channel, channel, channel)
+		markup.WriteString(html.EscapeString(line.Text))
+		markup.WriteString("</span>")
+	}
+	return markup.String()
+}
+
+func (s viewState) NeedsFadeRefresh(now time.Time, lineLifetime time.Duration) bool {
+	fadeDuration := lineLifetime
+	if fadeDuration <= 0 {
+		fadeDuration = defaultLineFadeDuration
+	}
+	for _, line := range s.Finals {
+		if now.Sub(line.CreatedAt) < fadeDuration {
+			return true
+		}
+	}
+	return false
+}
+
 func (s viewState) NextFinalExpiry() time.Time {
 	if len(s.Finals) == 0 {
 		return time.Time{}
 	}
 	return s.Finals[0].ExpiresAt
 }
+
+func lineBrightness(age, fadeDuration time.Duration) float64 {
+	if age <= 0 || fadeDuration <= 0 {
+		return 1
+	}
+	progress := float64(age) / float64(fadeDuration)
+	if progress > 1 {
+		progress = 1
+	}
+	return 1 - progress*(1-oldestLineBrightness)
+}

src/output/overlay/state_test.go

@@ -61,3 +61,16 @@ func TestViewStateZeroTimeoutDoesNotExpire(t *testing.T) {
 		t.Fatal("zero-timeout caption expired")
 	}
 }
+
+func TestViewStateFinalMarkupFadesAndEscapesText(t *testing.T) {
+	now := time.Unix(100, 0)
+	var state viewState
+	state.Apply(captions.Event{Kind: captions.Final, Text: "<hello & goodbye>"}, now, 3*time.Second)
+
+	if got := state.FinalMarkup(now, 3*time.Second); got != `<span foreground="#FFFFFF">&lt;hello &amp; goodbye&gt;</span>` {
+		t.Fatalf("new line markup = %q", got)
+	}
+	if got := state.FinalMarkup(now.Add(3*time.Second), 3*time.Second); got != `<span foreground="#A6A6A6">&lt;hello &amp; goodbye&gt;</span>` {
+		t.Fatalf("old line markup = %q", got)
+	}
+}