chore: release v1.89.2

.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Skills shared by Baoyu for improving daily work efficiency",
-    "version": "1.89.0"
+    "version": "1.89.2"
   },
   "plugins": [
     {

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 English | [中文](./CHANGELOG.zh.md)
 
+## 1.89.1 - 2026-04-01
+
+### Features
+- `baoyu-chrome-cdp`: add `gracefulKillChrome` that waits for Chrome to exit and release its port; fix `killChrome` to use `exitCode`/`signalCode` instead of `.killed` for reliable process state detection
+- `baoyu-fetch`: auto-detect login state before extraction in interaction wait mode
+
+### Maintenance
+- Sync vendor baoyu-chrome-cdp across CDP skills
+- `baoyu-url-to-markdown`: sync vendor baoyu-fetch with login auto-detect
+
 ## 1.89.0 - 2026-03-31
 
 ### Features

CHANGELOG.zh.md

@@ -2,6 +2,16 @@
 
 [English](./CHANGELOG.md) | 中文
 
+## 1.89.1 - 2026-04-01
+
+### 新功能
+- `baoyu-chrome-cdp`：新增 `gracefulKillChrome`，等待 Chrome 进程退出并释放端口；修复 `killChrome` 使用 `exitCode`/`signalCode` 替代 `.killed` 以更可靠地检测进程状态
+- `baoyu-fetch`：在交互等待模式下自动检测登录状态，未登录时提示用户先登录再提取内容
+
+### 维护
+- 同步 vendor baoyu-chrome-cdp 至所有 CDP 技能
+- `baoyu-url-to-markdown`：同步 vendor baoyu-fetch 的登录自动检测功能
+
 ## 1.89.0 - 2026-03-31
 
 ### 新功能

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.89.0**.
+Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.89.2**.
 
 ## Architecture
 

packages/baoyu-chrome-cdp/src/index.test.ts

@@ -11,6 +11,7 @@ import {
   discoverRunningChromeDebugPort,
   findChromeExecutable,
   findExistingChromeDebugPort,
+  gracefulKillChrome,
   getFreePort,
   openPageSession,
   resolveSharedChromeProfileDir,
@@ -110,6 +111,44 @@ async function stopProcess(child: ChildProcess | null): Promise<void> {
   await new Promise((resolve) => child.once("exit", resolve));
 }
 
+async function startPortHoldingProcess(port: number): Promise<ChildProcess> {
+  const child = spawn(
+    process.execPath,
+    [
+      "-e",
+      `
+        const http = require("node:http");
+        const port = Number(process.argv[1]);
+        const server = http.createServer((_req, res) => res.end("ok"));
+        server.listen(port, "127.0.0.1", () => process.stdout.write("ready\\n"));
+        setInterval(() => {}, 1000);
+      `,
+      String(port),
+    ],
+    {
+      stdio: ["ignore", "pipe", "ignore"],
+    },
+  );
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Timed out waiting for child server to start.")), 3_000);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.stdout?.once("data", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    child.once("exit", () => {
+      clearTimeout(timer);
+      reject(new Error("Child server exited before becoming ready."));
+    });
+  });
+
+  return child;
+}
+
 test("getFreePort honors a fixed environment override and otherwise allocates a TCP port", async (t) => {
   useEnv(t, { TEST_FIXED_PORT: "45678" });
   assert.equal(await getFreePort("TEST_FIXED_PORT"), 45678);
@@ -305,3 +344,19 @@ test("waitForChromeDebugPort retries until the debug endpoint becomes available"
 
   assert.equal(websocketUrl, `ws://127.0.0.1:${port}/devtools/browser/demo`);
 });
+
+test("gracefulKillChrome waits for the Chrome process to exit and release its port", async (t) => {
+  const port = await getFreePort();
+  const child = await startPortHoldingProcess(port);
+  t.after(async () => { await stopProcess(child); });
+
+  assert.equal(await waitForChromeDebugPort(port, 1_000).catch(() => null), null);
+
+  await gracefulKillChrome(child, port, 4_000);
+
+  assert.ok(child.exitCode !== null || child.signalCode !== null);
+  assert.equal(
+    await fetch(`http://127.0.0.1:${port}`).then(() => true).catch(() => false),
+    false,
+  );
+});

packages/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

packages/baoyu-fetch/src/commands/convert.ts

@@ -399,6 +399,22 @@ export async function runConvertCommand(options: ConvertCommandOptions): Promise
       if (restored) logger.info(`Restored ${adapter.name} session cookies from sidecar.`);
     }
 
+    if (options.waitMode === "interaction" && adapter.checkLogin) {
+      await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
+      const preLogin = await adapter.checkLogin(context);
+      if (preLogin.state !== "logged_in") {
+        didLogin = true;
+        await waitForInteraction(adapter, context, {
+          type: "wait_for_interaction",
+          kind: "login",
+          provider: preLogin.provider ?? adapter.name,
+          prompt: `Please sign in to ${adapter.name === "x" ? "X" : adapter.name} in the opened Chrome window. Extraction will continue automatically once login is detected.`,
+          reason: preLogin.reason ?? `Not logged in to ${adapter.name}`,
+          requiresVisibleBrowser: true,
+        }, options);
+      }
+    }
+
     if (options.waitMode === "force") {
       await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
       await waitForForceResume(adapter, context, options);

skills/baoyu-danger-gemini-web/scripts/vendor/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

skills/baoyu-danger-x-to-markdown/scripts/vendor/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

skills/baoyu-post-to-wechat/SKILL.md

@@ -352,7 +352,7 @@ WECHAT_APP_SECRET=<user_input>
 | Field | If Missing |
 |-------|------------|
 | Title | Prompt: "Enter title, or press Enter to auto-generate from content" |
-| Summary | Prompt: "Enter summary, or press Enter to auto-generate (recommended for SEO)" |
+| Summary | Use fallback chain: frontmatter `description` → frontmatter `summary` → prompt user or auto-generate |
 | Author | Use fallback chain: CLI `--author` → frontmatter `author` → EXTEND.md `default_author` |
 
 **Auto-Generation Logic**:

skills/baoyu-post-to-wechat/scripts/vendor/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

skills/baoyu-post-to-weibo/scripts/vendor/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

skills/baoyu-post-to-x/scripts/vendor/baoyu-chrome-cdp/src/index.ts

@@ -478,7 +478,7 @@ export function killChrome(chrome: ChildProcess): void {
     chrome.kill("SIGTERM");
   } catch {}
   setTimeout(() => {
-    if (!chrome.killed) {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
       try {
         chrome.kill("SIGKILL");
       } catch {}
@@ -486,6 +486,37 @@ export function killChrome(chrome: ChildProcess): void {
   }, 2_000).unref?.();
 }
 
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
 export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
   let targetId: string;
   let createdTarget = false;

skills/baoyu-url-to-markdown/scripts/vendor/baoyu-fetch/src/commands/convert.ts

@@ -399,6 +399,22 @@ export async function runConvertCommand(options: ConvertCommandOptions): Promise
       if (restored) logger.info(`Restored ${adapter.name} session cookies from sidecar.`);
     }
 
+    if (options.waitMode === "interaction" && adapter.checkLogin) {
+      await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
+      const preLogin = await adapter.checkLogin(context);
+      if (preLogin.state !== "logged_in") {
+        didLogin = true;
+        await waitForInteraction(adapter, context, {
+          type: "wait_for_interaction",
+          kind: "login",
+          provider: preLogin.provider ?? adapter.name,
+          prompt: `Please sign in to ${adapter.name === "x" ? "X" : adapter.name} in the opened Chrome window. Extraction will continue automatically once login is detected.`,
+          reason: preLogin.reason ?? `Not logged in to ${adapter.name}`,
+          requiresVisibleBrowser: true,
+        }, options);
+      }
+    }
+
     if (options.waitMode === "force") {
       await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
       await waitForForceResume(adapter, context, options);

skills/baoyu-youtube-transcript/scripts/main.test.ts

@@ -2,7 +2,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 
 import { findTranscript, parseTranscriptJson3, parseWebVtt } from "./transcript.ts";
-import { buildTranscriptListFromYtDlp, resolveVideoSource, selectYtDlpTrack } from "./youtube.ts";
+import { buildTranscriptListFromYtDlp, fetchTranscriptWithFallback, resolveVideoSource, selectYtDlpTrack } from "./youtube.ts";
 
 test("selectYtDlpTrack prefers json3 over xml and vtt", () => {
   const track = selectYtDlpTrack([
@@ -123,3 +123,61 @@ test("resolveVideoSource falls back to yt-dlp only after fallback-eligible error
   assert.equal(fallbackCalled, true);
   assert.equal(source.transcripts[0].languageCode, "en");
 });
+
+test("fetchTranscriptWithFallback retries with yt-dlp when InnerTube transcript payload is empty", async () => {
+  const warnings: string[] = [];
+  let fallbackCalled = false;
+  const result = await fetchTranscriptWithFallback(
+    "video12345ab",
+    {
+      kind: "innertube",
+      data: { videoDetails: { title: "Primary" } },
+      transcripts: [{
+        language: "English",
+        languageCode: "en",
+        isGenerated: false,
+        isTranslatable: false,
+        baseUrl: "https://www.youtube.com/api/timedtext?v=video12345ab&lang=en&fmt=json3",
+        translationLanguages: [],
+      }],
+    },
+    {
+      languages: ["en"],
+      translate: "",
+      excludeGenerated: false,
+      excludeManual: false,
+    },
+    async (info) => {
+      if (info.baseUrl.includes("youtube.com/api/timedtext")) {
+        return { snippets: [], language: info.language, languageCode: info.languageCode };
+      }
+      return {
+        snippets: [{ text: "Recovered subtitle", start: 0, duration: 2 }],
+        language: info.language,
+        languageCode: info.languageCode,
+      };
+    },
+    async () => {
+      fallbackCalled = true;
+      return {
+        kind: "yt-dlp",
+        info: { title: "Fallback" },
+        transcripts: [{
+          language: "English",
+          languageCode: "en",
+          isGenerated: false,
+          isTranslatable: false,
+          baseUrl: "https://example.com/subtitles.en.json3",
+          translationLanguages: [],
+        }],
+      };
+    },
+    (message) => warnings.push(message)
+  );
+
+  assert.equal(fallbackCalled, true);
+  assert.equal(result.source.kind, "yt-dlp");
+  assert.equal(result.snippets.length, 1);
+  assert.equal(result.snippets[0].text, "Recovered subtitle");
+  assert.match(warnings[0] || "", /Retrying with yt-dlp fallback/);
+});

skills/baoyu-youtube-transcript/scripts/main.ts

@@ -13,13 +13,13 @@ import {
   registerVideoDir,
   resolveBaseDir,
 } from "./storage.ts";
-import { findTranscript, formatListOutput, formatMarkdown, formatSrt, segmentIntoSentences } from "./transcript.ts";
+import { formatListOutput, formatMarkdown, formatSrt, segmentIntoSentences } from "./transcript.ts";
 import type { Options, Sentence, Snippet, VideoMeta, VideoResult } from "./types.ts";
 import {
   buildVideoMeta,
   buildVideoMetaFromYtDlp,
   downloadCoverImage,
-  fetchTranscriptSnippets,
+  fetchTranscriptWithFallback,
   fetchVideoSource,
   getThumbnailUrls,
   getYtDlpThumbnailUrls,
@@ -31,10 +31,12 @@ async function fetchAndCache(
   baseDir: string,
   opts: Options
 ): Promise<{ meta: VideoMeta; snippets: Snippet[]; sentences: Sentence[]; videoDir: string }> {
-  const source = await fetchVideoSource(videoId);
-  const requestedLanguages = source.kind === "yt-dlp" && opts.translate ? [opts.translate] : opts.languages;
-  const transcript = findTranscript(source.transcripts, requestedLanguages, opts.excludeGenerated, opts.excludeManual);
-  const result = await fetchTranscriptSnippets(transcript, source.kind === "yt-dlp" ? undefined : opts.translate || undefined);
+  const initialSource = await fetchVideoSource(videoId);
+  const { source, transcript, snippets, language, languageCode } = await fetchTranscriptWithFallback(
+    videoId,
+    initialSource,
+    opts
+  );
   const description = source.kind === "yt-dlp"
     ? source.info.description || ""
     : source.data?.videoDetails?.shortDescription || "";
@@ -42,21 +44,21 @@ async function fetchAndCache(
     ? Number(source.info.duration || 0)
     : parseInt(source.data?.videoDetails?.lengthSeconds || "0");
   const chapters = parseChapters(description, duration);
-  const language = {
-    code: result.languageCode,
-    name: result.language,
+  const languageMeta = {
+    code: languageCode,
+    name: language,
     isGenerated: transcript.isGenerated,
   };
   const meta = source.kind === "yt-dlp"
-    ? buildVideoMetaFromYtDlp(source.info, videoId, language, chapters)
-    : buildVideoMeta(source.data, videoId, language, chapters);
+    ? buildVideoMetaFromYtDlp(source.info, videoId, languageMeta, chapters)
+    : buildVideoMeta(source.data, videoId, languageMeta, chapters);
 
   const videoDir = registerVideoDir(videoId, slugify(meta.channel), slugify(meta.title), baseDir);
   ensureDir(join(videoDir, "meta.json"));
 
-  writeFileSync(join(videoDir, "transcript-raw.json"), JSON.stringify(result.snippets, null, 2));
+  writeFileSync(join(videoDir, "transcript-raw.json"), JSON.stringify(snippets, null, 2));
 
-  const sentences = segmentIntoSentences(result.snippets);
+  const sentences = segmentIntoSentences(snippets);
   writeFileSync(join(videoDir, "transcript-sentences.json"), JSON.stringify(sentences, null, 2));
 
   const imagePath = join(videoDir, "imgs", "cover.jpg");
@@ -69,7 +71,7 @@ async function fetchAndCache(
 
   writeFileSync(join(videoDir, "meta.json"), JSON.stringify(meta, null, 2));
 
-  return { meta, snippets: result.snippets, sentences, videoDir };
+  return { meta, snippets, sentences, videoDir };
 }
 
 async function processVideo(videoId: string, opts: Options): Promise<VideoResult> {

skills/baoyu-youtube-transcript/scripts/youtube.ts

@@ -2,12 +2,13 @@ import { spawnSync } from "child_process";
 import { writeFileSync } from "fs";
 
 import { makeError, normalizeError, normalizePublishDate, shouldTryAlternateClient, shouldTryYtDlpFallback } from "./shared.ts";
-import { parseTranscriptPayload } from "./transcript.ts";
+import { findTranscript, parseTranscriptPayload } from "./transcript.ts";
 import type {
   Chapter,
   InnerTubeClient,
   InnerTubeSession,
   LanguageMeta,
+  Options,
   Snippet,
   TranscriptInfo,
   VideoMeta,
@@ -219,6 +220,68 @@ export async function fetchTranscriptSnippets(
   };
 }
 
+function buildYtDlpVideoSource(videoId: string, info: YtDlpInfo): VideoSource {
+  const transcripts = buildTranscriptListFromYtDlp(info);
+  if (!transcripts.length) throw makeError(`Transcripts disabled for ${videoId}`, "TRANSCRIPTS_DISABLED");
+  return { kind: "yt-dlp", info, transcripts };
+}
+
+function getRequestedLanguages(
+  source: VideoSource,
+  opts: Pick<Options, "languages" | "translate">
+): string[] {
+  return source.kind === "yt-dlp" && opts.translate ? [opts.translate] : opts.languages;
+}
+
+export async function fetchTranscriptWithFallback(
+  videoId: string,
+  source: VideoSource,
+  opts: Pick<Options, "languages" | "translate" | "excludeGenerated" | "excludeManual">,
+  fetchSnippets: (
+    info: TranscriptInfo,
+    translateTo?: string
+  ) => Promise<{ snippets: Snippet[]; language: string; languageCode: string }> = fetchTranscriptSnippets,
+  fetchFallbackSource: (videoId: string) => Promise<VideoSource> | VideoSource = (requestedVideoId) =>
+    buildYtDlpVideoSource(requestedVideoId, fetchYtDlpInfo(requestedVideoId)),
+  logWarning: (message: string) => void = (message) => console.error(message)
+): Promise<{
+  source: VideoSource;
+  transcript: TranscriptInfo;
+  snippets: Snippet[];
+  language: string;
+  languageCode: string;
+}> {
+  const transcript = findTranscript(
+    source.transcripts,
+    getRequestedLanguages(source, opts),
+    opts.excludeGenerated,
+    opts.excludeManual
+  );
+  const result = await fetchSnippets(transcript, source.kind === "yt-dlp" ? undefined : opts.translate || undefined);
+  if (result.snippets.length > 0) return { source, transcript, ...result };
+
+  if (source.kind === "yt-dlp") {
+    throw makeError(`Transcript fetch returned empty snippets for ${videoId}`, "EMPTY_TRANSCRIPT");
+  }
+
+  logWarning(`Warning (${videoId}): Transcript fetch returned empty snippets. Retrying with yt-dlp fallback.`);
+  const fallbackSource = await fetchFallbackSource(videoId);
+  const fallbackTranscript = findTranscript(
+    fallbackSource.transcripts,
+    getRequestedLanguages(fallbackSource, opts),
+    opts.excludeGenerated,
+    opts.excludeManual
+  );
+  const fallbackResult = await fetchSnippets(
+    fallbackTranscript,
+    fallbackSource.kind === "yt-dlp" ? undefined : opts.translate || undefined
+  );
+  if (!fallbackResult.snippets.length) {
+    throw makeError(`Transcript fetch returned empty snippets for ${videoId} after yt-dlp fallback`, "EMPTY_TRANSCRIPT");
+  }
+  return { source: fallbackSource, transcript: fallbackTranscript, ...fallbackResult };
+}
+
 export function detectYtDlpCommand(): { command: string; args: string[]; label: string } | null {
   if (cachedYtDlpCommand !== undefined) return cachedYtDlpCommand;
   const candidates = [
@@ -366,10 +429,7 @@ export async function resolveVideoSource(
     const normalized = normalizeError(error);
     if (!shouldTryYtDlpFallback(normalized)) throw normalized;
     logWarning(`Warning (${videoId}): ${normalized.message}. Retrying with yt-dlp fallback.`);
-    const info = fetchFallback(videoId);
-    const transcripts = buildTranscriptListFromYtDlp(info);
-    if (!transcripts.length) throw makeError(`Transcripts disabled for ${videoId}`, "TRANSCRIPTS_DISABLED");
-    return { kind: "yt-dlp", info, transcripts };
+    return buildYtDlpVideoSource(videoId, fetchFallback(videoId));
   }
 }