feat: warn on uncertain episode availability

internal/domain/playback.go

@@ -15,16 +15,17 @@ type PlaybackService interface {
 }
 
 type WatchPageData struct {
-	WatchData       WatchData
-	Anime           Anime
-	Episodes        []CanonicalEpisode
-	CurrentEpID     string
-	WatchlistStatus string
-	WatchlistIDs    []int64
-	Seasons         []SeasonEntry
-	User            *User
-	CurrentPath     string
-	Error           string
+	WatchData                  WatchData
+	Anime                      Anime
+	Episodes                   []CanonicalEpisode
+	CurrentEpID                string
+	WatchlistStatus            string
+	WatchlistIDs               []int64
+	Seasons                    []SeasonEntry
+	User                       *User
+	CurrentPath                string
+	Error                      string
+	EpisodeAvailabilityWarning string
 }
 
 type WatchData struct {

internal/playback/handler/watch_page_test.go

@@ -106,3 +106,32 @@ func TestHandleWatchPagePreservesPartialDataOnPlaybackFailure(t *testing.T) {
 		t.Fatalf("expected partial episode list instead of empty state, got:\n%s", body)
 	}
 }
+
+func TestHandleWatchPageRendersEpisodeAvailabilityWarningModal(t *testing.T) {
+	t.Parallel()
+
+	data := baseWatchPageData()
+	data.EpisodeAvailabilityWarning = "Episode availability may be incomplete or out of date. Continue only if you understand that the episode list and audio availability may be uncertain."
+	router := newWatchPageRouter(t, &PlaybackHandler{
+		svc: &watchPagePlaybackService{data: data},
+	})
+
+	req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/anime/123/watch?ep=1", nil)
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+	body := rec.Body.String()
+	for _, want := range []string{
+		`data-episode-availability-warning`,
+		`Episode availability is uncertain`,
+		`Continue anyway`,
+		data.EpisodeAvailabilityWarning,
+	} {
+		if !strings.Contains(body, want) {
+			t.Fatalf("watch page missing %q in body:\n%s", want, body)
+		}
+	}
+}

internal/playback/watch_data.go

@@ -6,12 +6,15 @@ import (
 	"sort"
 	"strconv"
 	"strings"
+	"time"
 
 	"mal/integrations/jikan"
 	"mal/internal/domain"
 	"mal/internal/observability"
 )
 
+const episodeAvailabilityUncertainWarning = "Episode availability may be incomplete or out of date. Continue only if you understand that the episode list and audio availability may be uncertain."
+
 func (s *playbackService) BuildWatchData(ctx context.Context, animeID int, titleCandidates []string, episode string, mode string, userID string) (domain.WatchPageData, error) {
 	anime, err := s.jikan.GetAnimeByID(ctx, animeID)
 	if err != nil {
@@ -51,6 +54,7 @@ func (s *playbackService) BuildWatchData(ctx context.Context, animeID int, title
 	}
 	watchData := buildWatchDataPayload(animeData, animeID, episode, startTime, eps.Episodes, modeSources, mode, from, segments)
 	pageData := buildWatchPageData(animeData, eps.Episodes, episode, watchlistStatus, watchlistIDs, seasons, watchData)
+	pageData.EpisodeAvailabilityWarning = episodeAvailabilityWarning(eps, time.Now())
 	if len(modeSources) == 0 {
 		return pageData, fmt.Errorf("no streams found")
 	}
@@ -96,6 +100,23 @@ func buildWatchPageData(anime domain.Anime, episodes []domain.CanonicalEpisode,
 	}
 }
 
+func episodeAvailabilityWarning(episodeList domain.CanonicalEpisodeList, now time.Time) string {
+	if episodeList.FailureCount > 0 {
+		return episodeAvailabilityUncertainWarning
+	}
+	if episodeList.NextRefreshAt == "" {
+		return ""
+	}
+	nextRefresh, err := time.Parse(time.RFC3339, episodeList.NextRefreshAt)
+	if err != nil {
+		return ""
+	}
+	if nextRefresh.After(now) {
+		return ""
+	}
+	return episodeAvailabilityUncertainWarning
+}
+
 func buildSearchTitles(anime domain.Anime, titleCandidates []string) []string {
 	seen := map[string]struct{}{}
 	out := make([]string, 0, 3+len(anime.TitleSynonyms)+len(titleCandidates))

internal/playback/watch_data_test.go

@@ -1,7 +1,9 @@
 package playback
 
 import (
+	"mal/internal/domain"
 	"testing"
+	"time"
 )
 
 func TestFallbackModes(t *testing.T) {
@@ -33,3 +35,57 @@ func TestFallbackModes(t *testing.T) {
 		})
 	}
 }
+
+func TestEpisodeAvailabilityWarning(t *testing.T) {
+	now := time.Date(2026, time.June, 27, 11, 0, 0, 0, time.UTC)
+	tests := []struct {
+		name string
+		list domain.CanonicalEpisodeList
+		want string
+	}{
+		{
+			name: "fresh availability does not warn",
+			list: domain.CanonicalEpisodeList{
+				Episodes:      []domain.CanonicalEpisode{{Number: 1, HasSub: true}},
+				LastSuccessAt: "2026-06-27T10:00:00Z",
+				NextRefreshAt: "2026-06-27T12:00:00Z",
+			},
+		},
+		{
+			name: "stale availability warns",
+			list: domain.CanonicalEpisodeList{
+				Episodes:      []domain.CanonicalEpisode{{Number: 1, HasSub: true}},
+				LastSuccessAt: "2026-06-27T09:00:00Z",
+				NextRefreshAt: "2026-06-27T10:00:00Z",
+			},
+			want: episodeAvailabilityUncertainWarning,
+		},
+		{
+			name: "retrying availability warns",
+			list: domain.CanonicalEpisodeList{
+				Episodes:      []domain.CanonicalEpisode{{Number: 1, HasSub: true}},
+				NextRefreshAt: "2026-06-27T11:05:00Z",
+				RetryUntilAt:  "2026-06-27T11:30:00Z",
+				FailureCount:  1,
+			},
+			want: episodeAvailabilityUncertainWarning,
+		},
+		{
+			name: "failed availability warns",
+			list: domain.CanonicalEpisodeList{
+				Episodes:     []domain.CanonicalEpisode{{Number: 1, HasSub: true}},
+				FailureCount: 3,
+			},
+			want: episodeAvailabilityUncertainWarning,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := episodeAvailabilityWarning(tt.list, now)
+			if got != tt.want {
+				t.Fatalf("episodeAvailabilityWarning() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}

static/app.ts

@@ -3,6 +3,7 @@ import "./toast";
 import "./htmx";
 import "./dropdown";
 import "./anime";
+import "./episode_availability_warning";
 import "./search";
 import "./dedupe";
 import "./watchlist";

static/episode_availability_warning.ts

@@ -0,0 +1,23 @@
+import { closestFocusable, onReady } from "./utils";
+
+const initEpisodeAvailabilityWarning = (): void => {
+  onReady(() => {
+    const dialog = document.querySelector<HTMLElement>("[data-episode-availability-warning]");
+    const continueButton = document.querySelector<HTMLButtonElement>(
+      "[data-episode-availability-warning-continue]",
+    );
+    if (!dialog || !continueButton) {
+      return;
+    }
+
+    document.body.classList.add("overflow-hidden");
+    closestFocusable(dialog)?.focus();
+
+    continueButton.addEventListener("click", () => {
+      dialog.remove();
+      document.body.classList.remove("overflow-hidden");
+    });
+  });
+};
+
+initEpisodeAvailabilityWarning();

templates/renderer_test.go

@@ -138,6 +138,30 @@ func TestTopPicksTemplateRendersRecommendationRationale(t *testing.T) {
 	}
 }
 
+func TestAnimeEpisodeCountTemplateDoesNotRenderAvailabilityStatus(t *testing.T) {
+	r, err := ProvideRenderer()
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var buf bytes.Buffer
+	err = r.ExecuteFragment(&buf, "anime.gohtml", "anime_episode_count", map[string]any{
+		"Items": map[string]any{
+			"Count":      3,
+			"Label":      "Available episodes",
+			"Status":     "Retrying soon",
+			"StatusTone": "warning",
+		},
+	})
+	if err != nil {
+		t.Fatalf("ExecuteFragment error: %v", err)
+	}
+	body := buf.String()
+	if strings.Contains(body, "Retrying soon") || strings.Contains(body, "data-episode-availability-status") {
+		t.Fatalf("anime episode count should not expose availability status:\n%s", body)
+	}
+}
+
 func TestWatchTemplateEscapesJSONDataAttributes(t *testing.T) {
 	r, err := ProvideRenderer()
 	if err != nil {

templates/watch.gohtml

@@ -16,6 +16,23 @@
 {{$rangeStart := episodeRangeStart $currentEpNum 100}}
 {{$rangeEnd := min (add $rangeStart 99) $totalEpisodes}}
 
+{{if .EpisodeAvailabilityWarning}}
+<div data-episode-availability-warning class="fixed inset-0 z-100 flex items-center justify-center bg-black/70 px-4" role="dialog" aria-modal="true" aria-labelledby="episode-availability-warning-title">
+  <div class="w-full max-w-md bg-background shadow-card ring-1 ring-black/10">
+    <div class="border-b border-border-light px-5 py-4">
+      <h2 id="episode-availability-warning-title" class="text-base font-medium text-foreground">Episode availability is uncertain</h2>
+    </div>
+    <div class="flex flex-col gap-4 px-5 py-5">
+      <p class="text-sm leading-6 text-foreground-muted">{{.EpisodeAvailabilityWarning}}</p>
+      <div class="flex justify-end gap-3">
+        <a href="/anime/{{$anime.MalID}}" class="inline-flex items-center justify-center bg-background-button px-4 py-2 text-sm text-foreground-muted transition-colors hover:bg-background-button-hover hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-accent">Go back</a>
+        <button type="button" data-episode-availability-warning-continue class="inline-flex items-center justify-center bg-accent px-4 py-2 text-sm text-white transition-opacity hover:opacity-90 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-accent">Continue anyway</button>
+      </div>
+    </div>
+  </div>
+</div>
+{{end}}
+
 <div id="watch-layout" class="flex h-full flex-col gap-6 overflow-y-auto lg:grid lg:grid-cols-[minmax(0,min(calc(100%_-_24rem_-_3rem),calc((100dvh-10.5rem)*16/9)))_24rem] lg:items-start lg:gap-x-12 lg:gap-y-0 lg:overflow-hidden">
   <div class="min-w-0">
     <div id="video-player-container">