fix(subtitles): retry incomplete youtube fast-path fetches

[frogGuaGuaGuaGua]

Summary

• fall back to the slower YouTube POT/player-state subtitle path when the fast timedtext path returns empty or only a single text event before the player is ready
• keep the fast path for ready players with substantive subtitle events
• add regression tests for empty and first-line-only fast-path results

Why

On issue #1319, the reporter could still get timedtext 200 responses, but some videos showed loading forever, no subtitles, or only the first translated line. The current fetcher only retried when the fast path threw/returned null, so an unready-but-200 timedtext response could be accepted as final.

Fixes #1319

Validation

• SKIP_FREE_API=true pnpm vitest run src/utils/subtitles/__tests__/youtube-fetcher.test.ts
• pnpm eslint src/utils/subtitles/fetchers/youtube/index.ts src/utils/subtitles/__tests__/youtube-fetcher.test.ts
• pnpm tsc --noEmit
• git push pre-push checks: nx run @read-frog/extension:lint, nx run @read-frog/extension:type-check, nx run @read-frog/extension:test

---

Summary by cubic

Fallback to the POT/player-state path when YouTube’s fast timedtext returns empty or only the first line before the player is ready, preventing stalled or partial subtitles. Fixes #1319.

• Bug Fixes
  • Detect incomplete fast-path results (empty or single text event) on unready players and fall back to POT/player-state.
  • Include playerState in fast fetch and gate fallback via shouldFallbackFromFastPath.
  • Add regression tests for empty and first-line-only fast-path responses.

^{Written for commit 98db981. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 98db981

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@read-frog/extension	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Contributor trust score

42/100 — Moderate

This score estimates contributor familiarity with mengxi-ream/read-frog using public GitHub signals. It is advisory only and does not block merges automatically.

Outcome

• PR: fix(subtitles): retry incomplete youtube fast-path fetches #1320 — fix(subtitles): retry incomplete youtube fast-path fetches
• Author: @frogGuaGuaGuaGua
• Trust label: contrib-trust:moderate
• Maintainer review: not required
• Override label: add trust-check:skip to stop future trust automation updates

Score breakdown

Dimension	Score	Signals
Repo familiarity	21/35	commits in repo, merged PRs, reviews
Community standing	11/25	account age, followers, repo role
OSS influence	0/20	stars on owned non-fork repositories
PR track record	10/20	merge rate across resolved PRs in this repo

Signals used

• Repo commits: 10 (author commits reachable from the repository default branch)
• Repo PR history: merged 11, open 5, closed-unmerged 10
• Repo reviews: 0
• PR changed lines: 133 (+130 / -3)
• Repo permission: write
• Followers: 0
• Account age: 0 months
• Owned non-fork repos considered: max 0, total 0 (none)

Policy

• Low-score review threshold: < 30
• Auto-close: score < 20 and changed lines > 1000
• Policy version: v1.1

Updated automatically when the PR changes or when a maintainer reruns the workflow.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98db9811e6

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Don’t force fallback on valid single-cue subtitles

This fallback condition treats any fast-path response with one text event as incomplete when playerState < 1, but single-cue captions are valid for short videos. In that case fetch() now always enters the slow fallback path and waits through waitForPlayerState retries before refetching, which introduces avoidable latency (and extra failure surface) even though the fast-path data is already complete.

Useful? React with 👍 / 👎.

[cubic-dev-ai]

No issues found across 3 files