chore(release): prepare v0.17.2

.gitignore

@@ -1,5 +1,6 @@
 # Dependencies
 node_modules/
+/package-lock.json
 
 # Superpowers brainstorming
 .superpowers/
@@ -16,6 +17,8 @@ coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
+/main-entry.js
+/main-entry.js.map
 
 # Logs
 *.log

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.17.2 (2026-06-28)
+
+### Fixed
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+### Added
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+### Fixed
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
 ## v0.17.0 (2026-06-15)
 
 ### Changed

changes/log-export-local-date.md

@@ -1,5 +0,0 @@
-type: fixed
-area: logs
-
-- Fixed log filenames to use the user's local date so log export includes the current logs instead of stale prior-day logs around UTC midnight.
-- Expanded log export redaction to mask common PII and secrets, including IP addresses, emails, auth/cookie headers, yt-dlp cookie arguments, URL credentials, compound token/key/password fields, and signed YouTube media URL query strings.

changes/youtube-media-generation-reliability.md

@@ -1,7 +0,0 @@
-type: fixed
-area: youtube
-
-- Improved YouTube card media generation by sending safer ffmpeg request options for resolved streams and skipping stale stream maps, including cached YouTube files.
-- Added `youtube.mediaCache.mode` with `direct` and `background` modes so YouTube card audio/image extraction can optionally use a background yt-dlp media cache when direct stream extraction is unreliable; background mode now announces cache download start/readiness through queued overlay/OSD notifications, creates text-only cards while the cache downloads, queues media updates for the mined note IDs, fills audio/image fields once the cached file is ready, and caps background downloads at `youtube.mediaCache.maxHeight` 720p by default while honoring height changes between downloads.
-- Cleaned stale YouTube background media cache files on startup and before new background downloads, and stopped in-flight background downloads when switching back to direct mode.
-- Hardened YouTube media cache downloads with IPv4/extractor retry flags and made failed background downloads notify users and clear queued media updates instead of leaving them pending silently.

docs-site/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.17.2 (2026-06-28)
+
+**Fixed**
+- YouTube Background Cache: Fixed Windows YouTube background media cache startup for YouTube URLs opened directly in mpv, including resolved stream URLs when mpv still exposes the original YouTube playlist entry, so queued Anki media updates can append audio and images after the cache finishes.
+- YouTube Subtitle Picker: Manual subtitle picker requests now show an immediate configured notification while SubMiner probes tracks and opens the modal. Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## v0.17.1 (2026-06-27)
+
+**Added**
+- YouTube Media Cache Mode: Adds `youtube.mediaCache.mode` with `direct` and `background` options. Background mode uses a yt-dlp cache download when direct stream extraction is unreliable — creates a text-only card immediately, queues media updates for mined notes, and fills audio/image fields once the download finishes. Progress is announced via overlay/OSD notifications. Downloads are capped at 720p by default (`youtube.mediaCache.maxHeight`). Switching back to direct mode cancels any in-flight background download.
+
+**Fixed**
+- Log Export: Fixed log filenames to use the local date so exports around UTC midnight include the current day's logs rather than stale prior-day files. Expanded export redaction to mask IPs, emails, auth and cookie headers, yt-dlp cookie arguments, URL credentials, token/key/password fields, and signed YouTube media URL parameters.
+- YouTube Card Media: Improved media generation reliability by sending safer ffmpeg options for resolved streams and skipping stale stream maps (including cached YouTube files). Hardened background cache downloads with IPv4 and extractor retry flags; failed downloads now notify the user and clear queued media updates instead of leaving them silently pending. Stale background cache files are cleaned on startup and before each new download.
+
 ## v0.17.0 (2026-06-15)
 
 **Changed**

docs-site/configuration.md

@@ -1538,7 +1538,7 @@ Set defaults used by managed subtitle auto-selection and the `subminer` launcher
 | `mediaCache.mode`      | `direct` \| `background` | YouTube card audio/image extraction mode (default `direct`)                                      |
 | `mediaCache.maxHeight` | number                   | Maximum background cache download height. Set `0` for unlimited (default `720`)                  |
 
-`mediaCache.mode: "direct"` extracts card media from the active YouTube stream URL. `mediaCache.mode: "background"` starts a separate yt-dlp media download after YouTube playback has loaded. Playback and subtitle loading do not wait for that download. Use background mode if direct card media generation hits YouTube `403` errors from expiring stream URLs.
+`mediaCache.mode: "direct"` extracts card media from the active YouTube stream URL. `mediaCache.mode: "background"` starts a separate yt-dlp media download after YouTube playback has loaded, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. Playback and subtitle loading do not wait for that download. Use background mode if direct card media generation hits YouTube `403` errors from expiring stream URLs.
 
 Background cache downloads are capped by `mediaCache.maxHeight`, which defaults to 720p; set it to `0` to let yt-dlp choose the best available height. Downloads use IPv4 and yt-dlp retry flags to reduce YouTube throttling failures. SubMiner announces when the background cache download starts and when the cache is ready, using the configured notification surface; overlay and OSD messages queue until the overlay or mpv is ready. If you mine cards before the cache is ready, SubMiner creates the text fields immediately, queues the audio/image work for those note IDs, shows a status notification, and fills the media fields once the cached file is ready. If the cache download fails, SubMiner shows a failure notification, shows queued-card failure notifications, and clears the pending updates.
 

docs-site/youtube-integration.md

@@ -74,23 +74,27 @@ Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay
 - Select different primary and secondary tracks
 - Retry track loading if the auto-load failed or picked the wrong track
 
+SubMiner shows an "Opening YouTube subtitle picker..." status through your configured notification
+surface while it probes tracks and prepares the modal, then updates the subtitle download progress
+card to a success notification after the selected tracks load.
+
 The picker displays each track with its language, kind (manual/auto), and title when available.
 
 ## Subtitle Format Handling
 
 SubMiner handles several YouTube subtitle formats transparently:
 
-| Format | Handling |
-| ------ | -------- |
-| `srt`, `vtt` | Used directly (preferred for manual tracks) |
+| Format                 | Handling                                                 |
+| ---------------------- | -------------------------------------------------------- |
+| `srt`, `vtt`           | Used directly (preferred for manual tracks)              |
 | `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
-| Auto-generated VTT | Normalized to remove rolling-caption text duplication |
+| Auto-generated VTT     | Normalized to remove rolling-caption text duplication    |
 
 For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.
 
 ## Card Media Cache
 
-By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.
+By default, YouTube card audio and screenshots are extracted directly from mpv's active stream URLs. If generated card media fails with YouTube `403` errors, set `youtube.mediaCache.mode` to `"background"`. Background mode starts a separate `yt-dlp` media download after playback loads, including YouTube URLs opened directly in mpv and resolved stream URLs when mpv still exposes the original YouTube playlist entry. It creates text fields immediately, queues audio/image work for mined notes, and fills those fields once the local cache file is ready.
 
 Background cache downloads use IPv4 and retry flags to reduce YouTube throttling failures. If the background download still fails, SubMiner shows a cache failure notification, shows queued-card failure notifications, and clears those pending updates so cards are not left waiting silently.
 
@@ -101,13 +105,13 @@ Background cache downloads use IPv4 and retry flags to reduce YouTube throttling
 ```jsonc
 {
   "youtube": {
-    "primarySubLanguages": ["ja", "jpn"]
-  }
+    "primarySubLanguages": ["ja", "jpn"],
+  },
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
+| Option                | Type       | Description                                                                           |
+| --------------------- | ---------- | ------------------------------------------------------------------------------------- |
 | `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |
 
 ### Secondary Subtitle Languages
@@ -119,16 +123,16 @@ Secondary track selection uses the shared `secondarySub` config:
   "secondarySub": {
     "secondarySubLanguages": [],
     "autoLoadSecondarySub": false,
-    "defaultMode": "hover"
-  }
+    "defaultMode": "hover",
+  },
 }
 ```
 
-| Option | Type | Description |
-| ------ | ---- | ----------- |
-| `secondarySubLanguages` | `string[]` | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
-| `autoLoadSecondarySub` | `boolean` | Auto-detect and load a matching secondary track (default: `false`) |
-| `defaultMode` | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`) |
+| Option                  | Type                                 | Description                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `secondarySubLanguages` | `string[]`                           | Extra language codes (e.g. `["eng", "en"]`) used when auto-selecting a secondary track. Default is empty (`[]`). For YouTube, SubMiner always tries an English track first regardless of this list. |
+| `autoLoadSecondarySub`  | `boolean`                            | Auto-detect and load a matching secondary track (default: `false`)                                                                                                                                  |
+| `defaultMode`           | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`)                                                                                                                                   |
 
 Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.
 

main-entry.js

@@ -1,233 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_os_1 = __importDefault(require("node:os"));
-const node_child_process_1 = require("node:child_process");
-const electron_1 = require("electron");
-const help_1 = require("./cli/help");
-const main_entry_runtime_1 = require("./main-entry-runtime");
-const early_single_instance_1 = require("./main/early-single-instance");
-const main_entry_launch_config_1 = require("./main-entry-launch-config");
-const app_control_client_1 = require("./shared/app-control-client");
-const first_run_setup_plugin_1 = require("./main/runtime/first-run-setup-plugin");
-const windows_mpv_launch_1 = require("./main/runtime/windows-mpv-launch");
-const stats_daemon_entry_1 = require("./stats-daemon-entry");
-const fatal_error_1 = require("./main/fatal-error");
-const mpv_logging_args_1 = require("./shared/mpv-logging-args");
-const log_files_1 = require("./shared/log-files");
-const DEFAULT_TEXTHOOKER_PORT = 5174;
-function appendWindowsMpvLaunchLog(message, logRotation) {
-    if (!(0, log_files_1.isLogFileEnabled)('app')) {
-        return;
-    }
-    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 19);
-    (0, log_files_1.appendLogLine)(process.env.SUBMINER_APP_LOG?.trim() || (0, log_files_1.resolveDefaultLogFilePath)('app'), `[subminer] - ${timestamp} - INFO - [main:windows-mpv-launch] ${message}`, { rotation: logRotation });
-}
-function applySanitizedEnv(sanitizedEnv) {
-    if (sanitizedEnv.NODE_NO_WARNINGS) {
-        process.env.NODE_NO_WARNINGS = sanitizedEnv.NODE_NO_WARNINGS;
-    }
-    if (sanitizedEnv.VK_INSTANCE_LAYERS) {
-        process.env.VK_INSTANCE_LAYERS = sanitizedEnv.VK_INSTANCE_LAYERS;
-    }
-    else {
-        delete process.env.VK_INSTANCE_LAYERS;
-    }
-}
-function resolveBundledWindowsMpvPluginEntrypoint() {
-    return ((0, first_run_setup_plugin_1.resolvePackagedRuntimePluginPath)({
-        dirname: __dirname,
-        appPath: electron_1.app.getAppPath(),
-        resourcesPath: process.resourcesPath,
-    }) ?? undefined);
-}
-function buildInstalledWindowsMpvPluginMessage(pathValue, version) {
-    return [
-        'SubMiner detected an installed mpv plugin at:',
-        pathValue,
-        '',
-        "This mpv session will use the installed plugin. Remove it to use SubMiner's bundled runtime plugin automatically.",
-        `Detected plugin version: ${version ?? 'unknown or legacy'}`,
-    ].join('\n');
-}
-async function promptForWindowsLegacyMpvPluginRemoval(mpvPath, detection) {
-    const response = await electron_1.dialog.showMessageBox({
-        type: 'warning',
-        title: 'SubMiner mpv plugin detected',
-        message: buildInstalledWindowsMpvPluginMessage(detection.path ?? 'unknown path', detection.version),
-        detail: 'Remove the legacy SubMiner mpv plugin files from mpv before launching this video? This moves the files to the OS trash. SubMiner-managed playback will then use the bundled runtime plugin.',
-        buttons: ['Remove legacy plugin', 'Continue with installed plugin', 'Cancel'],
-        defaultId: 0,
-        cancelId: 2,
-    });
-    if (response.response === 2) {
-        return 'cancel';
-    }
-    if (response.response === 1) {
-        return 'continue';
-    }
-    const candidates = (0, first_run_setup_plugin_1.detectInstalledFirstRunPluginCandidates)({
-        platform: 'win32',
-        homeDir: node_os_1.default.homedir(),
-        appDataDir: electron_1.app.getPath('appData'),
-        mpvExecutablePath: mpvPath,
-    });
-    const result = await (0, first_run_setup_plugin_1.removeLegacyMpvPluginCandidates)({
-        candidates,
-        trashItem: (candidatePath) => electron_1.shell.trashItem(candidatePath),
-    });
-    if (result.ok) {
-        await electron_1.dialog.showMessageBox({
-            type: 'info',
-            title: 'Legacy mpv plugin removed',
-            message: 'Legacy mpv plugin removed. SubMiner-managed playback will use the bundled runtime plugin.',
-        });
-        return 'removed';
-    }
-    await electron_1.dialog.showMessageBox({
-        type: 'error',
-        title: 'Could not remove legacy mpv plugin',
-        message: 'Some legacy SubMiner mpv plugin files could not be moved to the trash.',
-        detail: result.failedPaths.map((failure) => `${failure.path}: ${failure.message}`).join('\n'),
-    });
-    return 'cancel';
-}
-function createWindowsRuntimePluginPolicy() {
-    return {
-        detectInstalledMpvPlugin: (mpvPath) => (0, first_run_setup_plugin_1.detectInstalledMpvPlugin)({
-            platform: 'win32',
-            homeDir: node_os_1.default.homedir(),
-            appDataDir: electron_1.app.getPath('appData'),
-            mpvExecutablePath: mpvPath,
-        }),
-        notifyInstalledPluginDetected: (detection) => {
-            if (!detection.installed || !detection.path)
-                return;
-            electron_1.dialog.showMessageBoxSync({
-                type: 'warning',
-                title: 'SubMiner mpv plugin detected',
-                message: buildInstalledWindowsMpvPluginMessage(detection.path, detection.version),
-            });
-        },
-        resolveInstalledPluginBeforeLaunch: (detection, mpvPath) => promptForWindowsLegacyMpvPluginRemoval(mpvPath, detection),
-    };
-}
-process.argv = (0, main_entry_runtime_1.normalizeStartupArgv)(process.argv, process.env);
-(0, main_entry_runtime_1.applyEarlyLinuxCommandLineSwitches)(electron_1.app.commandLine, process.argv);
-applySanitizedEnv((0, main_entry_runtime_1.sanitizeStartupEnv)(process.env));
-const userDataPath = (0, main_entry_runtime_1.configureEarlyAppPaths)(electron_1.app);
-const reportFatalError = (0, fatal_error_1.createFatalErrorReporter)({
-    showErrorBox: (title, details) => electron_1.dialog.showErrorBox(title, details),
-    consoleError: (message, error) => console.error(message, error),
-});
-(0, fatal_error_1.registerFatalErrorHandlers)({
-    reportFatalError,
-    exit: (code) => electron_1.app.exit(code),
-});
-function startMainProcess() {
-    const gotSingleInstanceLock = (0, early_single_instance_1.requestSingleInstanceLockEarly)(electron_1.app);
-    if (!gotSingleInstanceLock) {
-        electron_1.app.exit(0);
-        return;
-    }
-    try {
-        require('./main.js');
-    }
-    catch (error) {
-        reportFatalError(error, {
-            title: 'SubMiner startup failed',
-            context: 'SubMiner failed while loading the main process.',
-        });
-        electron_1.app.exit(1);
-    }
-}
-async function forwardStartupArgvViaAppControlIfAvailable() {
-    if (!(0, main_entry_runtime_1.shouldForwardStartupArgvViaAppControl)(process.argv, process.env)) {
-        return false;
-    }
-    const result = await (0, app_control_client_1.sendAppControlCommand)(process.argv, {
-        configDir: userDataPath,
-        timeoutMs: 500,
-    });
-    if (result.ok) {
-        electron_1.app.exit(0);
-        return true;
-    }
-    if (!result.unavailable) {
-        console.error(`SubMiner app-control handoff failed: ${result.error ?? 'unknown error'}`);
-        electron_1.app.exit(1);
-        return true;
-    }
-    return false;
-}
-async function runEntryProcess() {
-    if ((0, main_entry_runtime_1.shouldHandleHelpOnlyAtEntry)(process.argv, process.env)) {
-        const sanitizedEnv = (0, main_entry_runtime_1.sanitizeHelpEnv)(process.env);
-        process.env.NODE_NO_WARNINGS = sanitizedEnv.NODE_NO_WARNINGS;
-        if (!sanitizedEnv.VK_INSTANCE_LAYERS) {
-            delete process.env.VK_INSTANCE_LAYERS;
-        }
-        (0, help_1.printHelp)(DEFAULT_TEXTHOOKER_PORT);
-        process.exit(0);
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldHandleLaunchMpvAtEntry)(process.argv, process.env)) {
-        const sanitizedEnv = (0, main_entry_runtime_1.sanitizeLaunchMpvEnv)(process.env);
-        applySanitizedEnv(sanitizedEnv);
-        await electron_1.app.whenReady();
-        const configuredMpvLaunch = (0, main_entry_launch_config_1.readConfiguredWindowsMpvLaunch)(userDataPath);
-        const extraArgs = (0, main_entry_runtime_1.normalizeLaunchMpvExtraArgs)(process.argv);
-        (0, log_files_1.applyLogFileTogglesToEnv)(configuredMpvLaunch.logFiles);
-        const mpvLogPath = (0, log_files_1.isLogFileEnabled)('mpv')
-            ? process.env.SUBMINER_MPV_LOG?.trim() || (0, log_files_1.resolveDefaultLogFilePath)('mpv')
-            : '';
-        if (mpvLogPath) {
-            (0, log_files_1.pruneLogDirectoryForPath)(mpvLogPath, configuredMpvLaunch.logRotation);
-        }
-        const result = await (0, windows_mpv_launch_1.launchWindowsMpv)((0, main_entry_runtime_1.normalizeLaunchMpvTargets)(process.argv), (0, windows_mpv_launch_1.createWindowsMpvLaunchDeps)({
-            getEnv: (name) => process.env[name],
-            isAppControlServerAvailable: () => (0, app_control_client_1.isAppControlServerAvailable)({
-                configDir: userDataPath,
-                timeoutMs: 350,
-            }),
-            sendAppControlCommand: (argv) => (0, app_control_client_1.sendAppControlCommand)(argv, {
-                configDir: userDataPath,
-                timeoutMs: 1000,
-            }),
-            showError: (title, content) => {
-                electron_1.dialog.showErrorBox(title, content);
-            },
-            logInfo: (message) => appendWindowsMpvLaunchLog(message, configuredMpvLaunch.logRotation),
-        }), [...extraArgs, ...(0, mpv_logging_args_1.buildMpvLoggingArgs)(configuredMpvLaunch.logLevel, mpvLogPath, extraArgs)], process.execPath, resolveBundledWindowsMpvPluginEntrypoint(), configuredMpvLaunch.executablePath, configuredMpvLaunch.launchMode, createWindowsRuntimePluginPolicy(), configuredMpvLaunch.pluginRuntimeConfig);
-        electron_1.app.exit(result.ok ? 0 : 1);
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldHandleStatsDaemonCommandAtEntry)(process.argv, process.env)) {
-        await electron_1.app.whenReady();
-        const exitCode = await (0, stats_daemon_entry_1.runStatsDaemonControlFromProcess)(electron_1.app.getPath('userData'));
-        electron_1.app.exit(exitCode);
-        return;
-    }
-    if (await forwardStartupArgvViaAppControlIfAvailable()) {
-        return;
-    }
-    if ((0, main_entry_runtime_1.shouldDetachBackgroundLaunch)(process.argv, process.env)) {
-        const childArgs = (0, main_entry_runtime_1.hasTransportedStartupArgs)(process.env) ? [] : process.argv.slice(1);
-        const child = (0, node_child_process_1.spawn)(process.execPath, childArgs, {
-            detached: true,
-            stdio: 'ignore',
-            env: (0, main_entry_runtime_1.sanitizeBackgroundEnv)(process.env),
-        });
-        child.unref();
-        process.exit(0);
-        return;
-    }
-    startMainProcess();
-}
-void runEntryProcess().catch((error) => {
-    console.error('SubMiner app-control handoff failed:', error);
-    startMainProcess();
-});
-//# sourceMappingURL=main-entry.js.map

release/release-notes.md

@@ -0,0 +1,28 @@
+## Highlights
+
+### Fixed
+
+- **YouTube Background Cache:** Fixed Windows background media cache startup for YouTube URLs opened directly in mpv.
+  - Resolved stream URLs are now tracked even when mpv still exposes the original YouTube playlist entry.
+  - Queued Anki media updates can append audio and images after the cache finishes instead of staying text-only.
+
+- **YouTube Subtitle Picker Notifications:** Manual subtitle picker requests now show immediate status while SubMiner probes tracks and opens the modal.
+  - Subtitle download progress is replaced with a transient success notification after tracks load.
+
+## What's Changed
+
+- feat(youtube): notify on manual picker open and show success after track load by @ksyasuda in #133
+- fix(youtube): recover source URL for background media cache on direct mpv open by @ksyasuda in #132
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.zip`
+- Windows: `SubMiner-*.exe` and `SubMiner-*-win.zip`
+- Optional extras: `subminer-assets.tar.gz` and the `subminer` launcher
+
+Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.

scripts/build-changelog.ts

@@ -108,15 +108,11 @@ function renderPrereleaseBaseVersionMarker(version: string): string {
 }
 
 function extractPrereleaseBaseVersionMarker(notes: string): string | null {
-  return (
-    /<!--\s*prerelease-base-version:\s*(\d+\.\d+\.\d+)\s*-->/u.exec(notes)?.[1] ?? null
-  );
+  return /<!--\s*prerelease-base-version:\s*(\d+\.\d+\.\d+)\s*-->/u.exec(notes)?.[1] ?? null;
 }
 
 function stripPrereleaseMetadata(notes: string): string {
-  return notes
-    .replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '')
-    .trim();
+  return notes.replace(/<!--\s*prerelease-base-version:\s*\d+\.\d+\.\d+\s*-->\s*/u, '').trim();
 }
 
 function resolveReusablePrereleaseNotes(notes: string, version: string): string | undefined {

src/anki-integration.test.ts

@@ -768,6 +768,98 @@ test('AnkiIntegration reports partial queued YouTube media updates separately fr
   );
 });
 
+test('AnkiIntegration queues YouTube media updates against recovered source URLs', async () => {
+  const updatedNotes: Array<{ noteId: number; fields: Record<string, string> }> = [];
+  const storedMedia: string[] = [];
+
+  const integration = new AnkiIntegration(
+    {
+      fields: {
+        image: 'Picture',
+      },
+      media: {
+        imageFormat: 'jpg',
+      },
+    },
+    {} as never,
+    {
+      currentVideoPath: 'https://rr1---sn.example.googlevideo.com/videoplayback?expire=1777777777',
+      currentSubStart: 10,
+      currentSubEnd: 12,
+      currentTimePos: 11,
+    } as never,
+    () => undefined,
+    undefined,
+    undefined,
+    undefined,
+    {},
+    undefined,
+    undefined,
+    async () => null,
+    () => true,
+    () => 'https://www.youtube.com/watch?v=abc123',
+  );
+
+  const internals = integration as unknown as {
+    client: {
+      notesInfo: (noteIds: number[]) => Promise<unknown[]>;
+      updateNoteFields: (noteId: number, fields: Record<string, string>) => Promise<void>;
+      storeMediaFile: (filename: string) => Promise<void>;
+    };
+    mediaGenerator: {
+      generateAudio: () => Promise<Buffer>;
+      generateScreenshot: () => Promise<Buffer>;
+    };
+    queuePendingYoutubeMediaUpdateForNote: (job: {
+      noteId: number;
+      noteInfo: { noteId: number; fields: Record<string, { value: string }> };
+      label: string | number;
+    }) => Promise<boolean>;
+    showNotification: () => Promise<void>;
+  };
+  internals.client = {
+    notesInfo: async (noteIds) =>
+      noteIds.map((noteId) => ({
+        noteId,
+        fields: {
+          SentenceAudio: { value: '' },
+          Picture: { value: '' },
+        },
+      })),
+    updateNoteFields: async (noteId, fields) => {
+      updatedNotes.push({ noteId, fields });
+    },
+    storeMediaFile: async (filename) => {
+      storedMedia.push(filename);
+    },
+  };
+  internals.mediaGenerator = {
+    generateAudio: async () => Buffer.from('audio'),
+    generateScreenshot: async () => Buffer.from('image'),
+  };
+  internals.showNotification = async () => undefined;
+
+  const queued = await internals.queuePendingYoutubeMediaUpdateForNote({
+    noteId: 404,
+    noteInfo: {
+      noteId: 404,
+      fields: {
+        SentenceAudio: { value: '' },
+        Picture: { value: '' },
+      },
+    },
+    label: 'resolved source',
+  });
+  await integration.handleYoutubeMediaCacheReady('https://youtu.be/abc123', '/tmp/media.mkv');
+
+  assert.equal(queued, true);
+  assert.equal(updatedNotes.length, 1);
+  assert.equal(updatedNotes[0]?.noteId, 404);
+  assert.match(updatedNotes[0]?.fields.SentenceAudio ?? '', /^\[sound:audio_/);
+  assert.match(updatedNotes[0]?.fields.Picture ?? '', /^<img src="image_/);
+  assert.equal(storedMedia.length, 2);
+});
+
 test('AnkiIntegration does not use mpv stream indexes for ready cached YouTube audio', async () => {
   const audioCalls: Array<{ path: string; audioStreamIndex?: number }> = [];
 

src/anki-integration.ts

@@ -239,6 +239,9 @@ export class AnkiIntegration {
   private getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null =
     null;
   private shouldRequireRemoteMediaCache: (() => boolean) | null = null;
+  private getYoutubeMediaSourceUrl:
+    | (() => Promise<string | null | undefined> | string | null | undefined)
+    | null = null;
   private pendingYoutubeMediaQueue: PendingYoutubeMediaQueue;
 
   constructor(
@@ -257,6 +260,7 @@ export class AnkiIntegration {
     overlayNotificationCallback?: (payload: OverlayNotificationPayload) => void,
     getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'],
     shouldRequireRemoteMediaCache?: () => boolean,
+    getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined,
   ) {
     this.config = normalizeAnkiIntegrationConfig(config);
     this.aiConfig = { ...aiConfig };
@@ -271,6 +275,7 @@ export class AnkiIntegration {
     this.recordCardsMinedCallback = recordCardsMined ?? null;
     this.getCachedMediaPath = getCachedMediaPath ?? null;
     this.shouldRequireRemoteMediaCache = shouldRequireRemoteMediaCache ?? null;
+    this.getYoutubeMediaSourceUrl = getYoutubeMediaSourceUrl ?? null;
     this.pendingYoutubeMediaQueue = this.createPendingYoutubeMediaQueue();
     this.knownWordCache = this.createKnownWordCache(knownWordCacheStatePath);
     this.pollingRunner = this.createPollingRunner();
@@ -356,7 +361,7 @@ export class AnkiIntegration {
           ),
       },
       getConfig: () => this.config,
-      getCurrentVideoPath: () => this.mpvClient.currentVideoPath,
+      getCurrentVideoPath: () => this.getCurrentYoutubeMediaSourceUrl(),
       getCachedMediaPath: this.getCachedMediaPath,
       shouldRequireRemoteMediaCache: () => this.shouldRequireRemoteMediaCache?.() === true,
       getSubtitleMediaRange: (context) => this.getSubtitleMediaRange(context),
@@ -474,6 +479,7 @@ export class AnkiIntegration {
       getMpvClient: () => this.mpvClient,
       ...(this.getCachedMediaPath ? { getCachedMediaPath: this.getCachedMediaPath } : {}),
       shouldRequireRemoteMediaCache: () => this.shouldRequireRemoteMediaCache?.() === true,
+      getYoutubeMediaSourceUrl: () => this.getCurrentYoutubeMediaSourceUrl(),
       queuePendingYoutubeMediaUpdate: (job) => this.queuePendingYoutubeMediaUpdate(job),
       getDeck: () => this.config.deck,
       client: {
@@ -945,6 +951,14 @@ export class AnkiIntegration {
     return this.pendingYoutubeMediaQueue.queueFromNote(job);
   }
 
+  private async getCurrentYoutubeMediaSourceUrl(): Promise<string> {
+    return (
+      trimToNonEmptyString(await this.getYoutubeMediaSourceUrl?.()) ??
+      trimToNonEmptyString(this.mpvClient.currentVideoPath) ??
+      ''
+    );
+  }
+
   async handleYoutubeMediaCacheReady(
     sourceUrl: string,
     cachedPath: string,

src/anki-integration/card-creation.ts

@@ -28,6 +28,14 @@ function shouldGenerateImage(config: AnkiConnectConfig): boolean {
   return config.media?.generateImage !== false;
 }
 
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 export interface CardCreationNoteInfo {
   noteId: number;
   fields: Record<string, { value: string }>;
@@ -90,6 +98,7 @@ interface CardCreationDeps {
   getMpvClient: () => MpvClient;
   getCachedMediaPath?: MediaGenerationInputResolverOptions['getCachedMediaPath'];
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   queuePendingYoutubeMediaUpdate?: (job: PendingYoutubeMediaUpdate) => void;
   getDeck?: () => string | undefined;
   client: CardCreationClient;
@@ -705,7 +714,9 @@ export class CardCreationService {
         const label = sentence.length > 30 ? sentence.substring(0, 30) + '...' : sentence;
         if (shouldQueuePendingYoutubeMedia) {
           this.deps.queuePendingYoutubeMediaUpdate?.({
-            sourceUrl: mpvClient.currentVideoPath,
+            sourceUrl:
+              trimToNonEmptyString(await this.deps.getYoutubeMediaSourceUrl?.()) ??
+              mpvClient.currentVideoPath,
             noteId,
             startTime,
             endTime,

src/anki-integration/note-field-utils.ts

@@ -2,7 +2,10 @@ export interface NoteFieldValueInfo {
   fields: Record<string, { value: string }>;
 }
 
-export function getNoteFieldValue(noteInfo: NoteFieldValueInfo, preferredName: string): string | null {
+export function getNoteFieldValue(
+  noteInfo: NoteFieldValueInfo,
+  preferredName: string,
+): string | null {
   const resolvedFieldName = Object.keys(noteInfo.fields).find(
     (fieldName) => fieldName.toLowerCase() === preferredName.toLowerCase(),
   );

src/anki-integration/pending-youtube-media-queue.ts

@@ -32,7 +32,7 @@ export interface PendingYoutubeMediaQueueDeps {
     'generateAudio' | 'generateScreenshot' | 'generateAnimatedImage'
   >;
   getConfig: () => AnkiConnectConfig;
-  getCurrentVideoPath: () => string | undefined;
+  getCurrentVideoPath: () => Promise<string | undefined> | string | undefined;
   getCachedMediaPath: MediaGenerationInputResolverOptions['getCachedMediaPath'] | null;
   shouldRequireRemoteMediaCache: () => boolean;
   getSubtitleMediaRange: (context?: SubtitleMiningContext) => {
@@ -104,7 +104,7 @@ export class PendingYoutubeMediaQueue {
     context?: SubtitleMiningContext;
     label: string | number;
   }): Promise<boolean> {
-    const sourceUrl = trimToNonEmptyString(this.deps.getCurrentVideoPath());
+    const sourceUrl = trimToNonEmptyString(await this.deps.getCurrentVideoPath());
     const getCachedMediaPath = this.deps.getCachedMediaPath;
     if (!sourceUrl || this.deps.shouldRequireRemoteMediaCache() !== true || !getCachedMediaPath) {
       return false;

src/core/services/anki-jimaku.ts

@@ -45,6 +45,7 @@ export interface AnkiJimakuIpcRuntimeOptions {
     kind: 'audio' | 'video',
   ) => Promise<string | null>;
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   showDesktopNotification: (title: string, options: { body?: string; icon?: string }) => void;
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
   createFieldGroupingCallback: () => (
@@ -114,6 +115,7 @@ export function registerAnkiJimakuIpcRuntime(
           options.showOverlayNotification,
           options.getCachedMediaPath,
           options.shouldRequireRemoteMediaCache,
+          options.getYoutubeMediaSourceUrl,
         );
         integration.start();
         options.setAnkiIntegration(integration);

src/core/services/overlay-runtime-init.ts

@@ -30,6 +30,7 @@ type CreateAnkiIntegrationArgs = {
     kind: 'audio' | 'video',
   ) => Promise<string | null>;
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
 };
 
 export type OverlayWindowTrackerOptions = {
@@ -72,6 +73,7 @@ function createDefaultAnkiIntegration(args: CreateAnkiIntegrationArgs): AnkiInte
     args.showOverlayNotification,
     args.getCachedMediaPath,
     args.shouldRequireRemoteMediaCache,
+    args.getYoutubeMediaSourceUrl,
   );
 }
 
@@ -144,6 +146,7 @@ export function initializeOverlayRuntime(
       kind: 'audio' | 'video',
     ) => Promise<string | null>;
     shouldRequireRemoteMediaCache?: () => boolean;
+    getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
     shouldStartAnkiIntegration?: () => boolean;
     createAnkiIntegration?: (args: CreateAnkiIntegrationArgs) => AnkiIntegrationLike;
     backendOverride: string | null;
@@ -183,6 +186,7 @@ export function initializeOverlayAnkiIntegration(options: {
     kind: 'audio' | 'video',
   ) => Promise<string | null>;
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   shouldStartAnkiIntegration?: () => boolean;
   createAnkiIntegration?: (args: CreateAnkiIntegrationArgs) => AnkiIntegrationLike;
 }): boolean {
@@ -221,6 +225,9 @@ export function initializeOverlayAnkiIntegration(options: {
     ...(options.shouldRequireRemoteMediaCache
       ? { shouldRequireRemoteMediaCache: options.shouldRequireRemoteMediaCache }
       : {}),
+    ...(options.getYoutubeMediaSourceUrl
+      ? { getYoutubeMediaSourceUrl: options.getYoutubeMediaSourceUrl }
+      : {}),
   });
   if (options.shouldStartAnkiIntegration?.() !== false) {
     integration.start();

src/main.ts

@@ -348,6 +348,7 @@ import {
   shouldAutoOpenFirstRunSetup,
 } from './main/runtime/first-run-setup-service';
 import { createYoutubeFlowRuntime } from './main/runtime/youtube-flow';
+import { createYoutubeMediaCachePlaybackRuntime } from './main/runtime/youtube-media-cache-playback';
 import { createYoutubePlaybackRuntime } from './main/runtime/youtube-playback-runtime';
 import {
   clearYoutubePrimarySubtitleNotificationTimer,
@@ -533,7 +534,6 @@ import { shouldSuppressVisibleOverlayRaiseForSeparateWindow } from './main/runti
 import {
   isSameYoutubeMediaPath,
   isYoutubeMediaPath,
-  isYoutubePlaybackActive,
   shouldUseCachedYoutubeParsedCues,
 } from './main/runtime/youtube-playback';
 import { createYomitanProfilePolicy } from './main/runtime/yomitan-profile-policy';
@@ -1220,6 +1220,18 @@ const youtubeMediaCache = createYoutubeMediaCacheService({
   logInfo: (message) => logger.info(message),
   logWarn: (message) => logger.warn(message),
 });
+const youtubeMediaCachePlaybackRuntime = createYoutubeMediaCachePlaybackRuntime({
+  getMediaCacheConfig: () => getResolvedConfig().youtube.mediaCache,
+  requestMpvProperty: async (name) => {
+    const client = appState.mpvClient;
+    if (!client) return null;
+    return await client.requestProperty(name);
+  },
+  startYoutubeMediaCache: (url, options) => {
+    youtubeMediaCache.start(url, options);
+  },
+  logWarn: (message) => logger.warn(message),
+});
 const waitForYoutubeMpvConnected = createWaitForMpvConnectedHandler({
   getMpvClient: () => appState.mpvClient,
   now: () => Date.now(),
@@ -1683,10 +1695,35 @@ const youtubePrimarySubtitleNotificationRuntime = createYoutubePrimarySubtitleNo
 });
 
 function isYoutubePlaybackActiveNow(): boolean {
-  return isYoutubePlaybackActive(
-    appState.currentMediaPath,
-    appState.mpvClient?.currentVideoPath ?? null,
-  );
+  return Boolean(getCurrentYoutubeMediaCacheSourceUrlSnapshot());
+}
+
+function getCurrentYoutubeMediaCacheSourceUrlSnapshot(): string | null {
+  const currentMediaPath = appState.currentMediaPath?.trim() || null;
+  if (isYoutubeMediaPath(currentMediaPath)) {
+    return currentMediaPath;
+  }
+
+  const currentVideoPath = appState.mpvClient?.currentVideoPath?.trim() || null;
+  if (isYoutubeMediaPath(currentVideoPath)) {
+    return currentVideoPath;
+  }
+
+  return youtubeMediaCachePlaybackRuntime.getActiveYoutubeSourceUrlSnapshot();
+}
+
+async function getCurrentYoutubeMediaCacheSourceUrl(): Promise<string | null> {
+  const currentMediaPath = appState.currentMediaPath?.trim() || null;
+  if (isYoutubeMediaPath(currentMediaPath)) {
+    return currentMediaPath;
+  }
+
+  const currentVideoPath = appState.mpvClient?.currentVideoPath?.trim() || null;
+  if (isYoutubeMediaPath(currentVideoPath)) {
+    return currentVideoPath;
+  }
+
+  return await youtubeMediaCachePlaybackRuntime.getActiveYoutubeSourceUrl();
 }
 
 function shouldRequireYoutubeMediaCacheForCurrentPlayback(): boolean {
@@ -1702,13 +1739,16 @@ async function getCachedYoutubeMediaPathForCurrentPlayback(
   if (getResolvedConfig().youtube.mediaCache.mode !== 'background') {
     return null;
   }
-  if (!isYoutubePlaybackActiveNow()) {
+  const cacheSourceUrl = isYoutubeMediaPath(currentVideoPath)
+    ? currentVideoPath
+    : await getCurrentYoutubeMediaCacheSourceUrl();
+  if (!cacheSourceUrl) {
     return null;
   }
   // mpv can expose the resolved stream URL here while the cache key uses the original page URL.
   // Keep the active-cache fallback so current playback can still resolve the ready cached file.
   return (
-    (await youtubeMediaCache.getCachedMediaPath(currentVideoPath)) ??
+    (await youtubeMediaCache.getCachedMediaPath(cacheSourceUrl)) ??
     (await youtubeMediaCache.getActiveCachedMediaPath())
   );
 }
@@ -4442,6 +4482,7 @@ const {
         subtitlePrefetchRuntime.cancelPendingInit();
       }
       youtubePrimarySubtitleNotificationRuntime.handleMediaPathChange(path);
+      void youtubeMediaCachePlaybackRuntime.handleMediaPathChange(path);
       if (path) {
         ensureImmersionTrackerStarted();
         void subtitlePrefetchRuntime.refreshSubtitlePrefetchFromActiveTrack();
@@ -5815,6 +5856,7 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       getCachedMediaPath: (currentVideoPath, kind) =>
         getCachedYoutubeMediaPathForCurrentPlayback(currentVideoPath, kind),
       shouldRequireRemoteMediaCache: () => shouldRequireYoutubeMediaCacheForCurrentPlayback(),
+      getYoutubeMediaSourceUrl: () => getCurrentYoutubeMediaCacheSourceUrl(),
       showDesktopNotification,
       showOverlayNotification,
       createFieldGroupingCallback: () => createFieldGroupingCallback(),
@@ -6294,6 +6336,7 @@ const { initializeOverlayRuntime: initializeOverlayRuntimeHandler } =
       getCachedMediaPath: (currentVideoPath, kind) =>
         getCachedYoutubeMediaPathForCurrentPlayback(currentVideoPath, kind),
       shouldRequireRemoteMediaCache: () => shouldRequireYoutubeMediaCacheForCurrentPlayback(),
+      getYoutubeMediaSourceUrl: () => getCurrentYoutubeMediaCacheSourceUrl(),
       shouldStartAnkiIntegration: () =>
         !(appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs)),
     },

src/main/dependencies.ts

@@ -128,6 +128,7 @@ export interface AnkiJimakuIpcRuntimeServiceDepsParams {
   getKnownWordCacheStatePath: AnkiJimakuIpcRuntimeOptions['getKnownWordCacheStatePath'];
   getCachedMediaPath?: AnkiJimakuIpcRuntimeOptions['getCachedMediaPath'];
   shouldRequireRemoteMediaCache?: AnkiJimakuIpcRuntimeOptions['shouldRequireRemoteMediaCache'];
+  getYoutubeMediaSourceUrl?: AnkiJimakuIpcRuntimeOptions['getYoutubeMediaSourceUrl'];
   showDesktopNotification: AnkiJimakuIpcRuntimeOptions['showDesktopNotification'];
   showOverlayNotification?: (payload: OverlayNotificationPayload) => void;
   createFieldGroupingCallback: AnkiJimakuIpcRuntimeOptions['createFieldGroupingCallback'];
@@ -323,6 +324,9 @@ export function createAnkiJimakuIpcRuntimeServiceDeps(
     ...(params.shouldRequireRemoteMediaCache
       ? { shouldRequireRemoteMediaCache: params.shouldRequireRemoteMediaCache }
       : {}),
+    ...(params.getYoutubeMediaSourceUrl
+      ? { getYoutubeMediaSourceUrl: params.getYoutubeMediaSourceUrl }
+      : {}),
     showDesktopNotification: params.showDesktopNotification,
     showOverlayNotification: params.showOverlayNotification,
     createFieldGroupingCallback: params.createFieldGroupingCallback,

src/main/main-wiring.test.ts

@@ -50,6 +50,16 @@ test('media path changes clear rendered subtitle state without clearing same-you
   );
 });
 
+test('media path changes start the YouTube media cache coordinator', () => {
+  const source = readMainSource();
+  const actionBlock = source.match(
+    /updateCurrentMediaPath:\s*\(path\)\s*=>\s*\{(?<body>[\s\S]*?)\n    restoreMpvSubVisibility:/,
+  )?.groups?.body;
+
+  assert.ok(actionBlock);
+  assert.match(actionBlock, /youtubeMediaCachePlaybackRuntime\.handleMediaPathChange\(path\);/);
+});
+
 test('same media path updates do not reset autoplay ready fallback state', () => {
   const source = readMainSource();
   const actionBlock = source.match(

src/main/runtime/configured-status-notification.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
   getPlaybackFeedbackNotificationOptions,
+  getYoutubeFlowStatusNotificationOptions,
   notifyConfiguredStatus,
 } from './configured-status-notification';
 import { createOverlayNotificationDelivery } from './overlay-notification-delivery';
@@ -226,6 +227,36 @@ test('playback feedback options reuse subtitle mode notification ids', () => {
   assert.deepEqual(getPlaybackFeedbackNotificationOptions('Secondary subtitle track: English'), {});
 });
 
+test('youtube flow status options route picker opening as one-shot configured status', () => {
+  assert.deepEqual(getYoutubeFlowStatusNotificationOptions('Opening YouTube subtitle picker...'), {
+    id: 'youtube-subtitles-status',
+    title: 'YouTube subtitles',
+    variant: 'info',
+    persistent: false,
+    desktop: true,
+  });
+});
+
+test('youtube flow status options route loaded messages as transient success', () => {
+  assert.deepEqual(getYoutubeFlowStatusNotificationOptions('Subtitles loaded.'), {
+    id: 'youtube-subtitles-status',
+    title: 'YouTube subtitles',
+    variant: 'success',
+    persistent: false,
+    desktop: true,
+  });
+  assert.deepEqual(
+    getYoutubeFlowStatusNotificationOptions('Primary and secondary subtitles loaded.'),
+    {
+      id: 'youtube-subtitles-status',
+      title: 'YouTube subtitles',
+      variant: 'success',
+      persistent: false,
+      desktop: true,
+    },
+  );
+});
+
 test('notifyConfiguredStatus falls back to desktop if overlay is unavailable', () => {
   const calls: string[] = [];
 

src/main/runtime/configured-status-notification.ts

@@ -31,6 +31,25 @@ export function getPlaybackFeedbackNotificationOptions(
   return {};
 }
 
+export function getYoutubeFlowStatusNotificationOptions(
+  message: string,
+): ConfiguredStatusNotificationOptions {
+  const success =
+    message === 'Subtitles loaded.' || message === 'Primary and secondary subtitles loaded.';
+  const progress =
+    message.startsWith('Downloading subtitles') ||
+    message.startsWith('Loading subtitles') ||
+    message.startsWith('Getting subtitles') ||
+    message === 'Opening YouTube video';
+  return {
+    id: 'youtube-subtitles-status',
+    title: 'YouTube subtitles',
+    variant: success ? 'success' : progress ? 'progress' : 'info',
+    persistent: progress,
+    desktop: !progress,
+  };
+}
+
 export function notifyConfiguredStatus(
   message: string,
   deps: ConfiguredStatusNotificationDeps,

src/main/runtime/overlay-notifications-runtime.ts

@@ -22,6 +22,7 @@ import { withConfiguredOverlayNotificationPosition } from './overlay-notificatio
 import { createOverlayNotificationDelivery } from './overlay-notification-delivery';
 import {
   getPlaybackFeedbackNotificationOptions,
+  getYoutubeFlowStatusNotificationOptions,
   notifyConfiguredStatus,
   type ConfiguredStatusNotificationOptions,
 } from './configured-status-notification';
@@ -206,18 +207,7 @@ export function createOverlayNotificationsRuntime(deps: OverlayNotificationsRunt
   }
 
   function showYoutubeFlowStatusNotification(message: string): void {
-    const progress =
-      message.startsWith('Downloading subtitles') ||
-      message.startsWith('Loading subtitles') ||
-      message.startsWith('Getting subtitles') ||
-      message === 'Opening YouTube video';
-    showConfiguredStatusNotification(message, {
-      id: 'youtube-subtitles-status',
-      title: 'YouTube subtitles',
-      variant: progress ? 'progress' : 'info',
-      persistent: progress,
-      desktop: !progress,
-    });
+    showConfiguredStatusNotification(message, getYoutubeFlowStatusNotificationOptions(message));
   }
 
   function getOverlayLoadingOsdController(): ReturnType<typeof createOverlayLoadingOsdController> {

src/main/runtime/overlay-runtime-options-main-deps.ts

@@ -43,6 +43,7 @@ export function createBuildInitializeOverlayRuntimeMainDepsHandler(deps: {
   getKnownWordCacheStatePath: () => string;
   getCachedMediaPath?: OverlayRuntimeOptionsMainDeps['getCachedMediaPath'];
   shouldRequireRemoteMediaCache?: OverlayRuntimeOptionsMainDeps['shouldRequireRemoteMediaCache'];
+  getYoutubeMediaSourceUrl?: OverlayRuntimeOptionsMainDeps['getYoutubeMediaSourceUrl'];
   shouldStartAnkiIntegration: () => boolean;
   bindOverlayOwner?: () => void;
   releaseOverlayOwner?: () => void;
@@ -83,6 +84,9 @@ export function createBuildInitializeOverlayRuntimeMainDepsHandler(deps: {
     ...(deps.shouldRequireRemoteMediaCache
       ? { shouldRequireRemoteMediaCache: deps.shouldRequireRemoteMediaCache }
       : {}),
+    ...(deps.getYoutubeMediaSourceUrl
+      ? { getYoutubeMediaSourceUrl: deps.getYoutubeMediaSourceUrl }
+      : {}),
     shouldStartAnkiIntegration: () => deps.shouldStartAnkiIntegration(),
     bindOverlayOwner: deps.bindOverlayOwner,
     releaseOverlayOwner: deps.releaseOverlayOwner,

src/main/runtime/overlay-runtime-options.ts

@@ -42,6 +42,7 @@ type OverlayRuntimeOptions = {
     kind: 'audio' | 'video',
   ) => Promise<string | null>;
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   shouldStartAnkiIntegration: () => boolean;
   bindOverlayOwner?: () => void;
   releaseOverlayOwner?: () => void;
@@ -81,6 +82,7 @@ export function createBuildInitializeOverlayRuntimeOptionsHandler(deps: {
     kind: 'audio' | 'video',
   ) => Promise<string | null>;
   shouldRequireRemoteMediaCache?: () => boolean;
+  getYoutubeMediaSourceUrl?: () => Promise<string | null | undefined> | string | null | undefined;
   shouldStartAnkiIntegration: () => boolean;
   bindOverlayOwner?: () => void;
   releaseOverlayOwner?: () => void;
@@ -111,6 +113,9 @@ export function createBuildInitializeOverlayRuntimeOptionsHandler(deps: {
     ...(deps.shouldRequireRemoteMediaCache
       ? { shouldRequireRemoteMediaCache: deps.shouldRequireRemoteMediaCache }
       : {}),
+    ...(deps.getYoutubeMediaSourceUrl
+      ? { getYoutubeMediaSourceUrl: deps.getYoutubeMediaSourceUrl }
+      : {}),
     shouldStartAnkiIntegration: deps.shouldStartAnkiIntegration,
     bindOverlayOwner: deps.bindOverlayOwner,
     releaseOverlayOwner: deps.releaseOverlayOwner,

src/main/runtime/youtube-flow.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import path from 'node:path';
 import test from 'node:test';
 import { createYoutubeFlowRuntime } from './youtube-flow';
+import type { YoutubeTrackProbeResult } from '../../core/services/youtube/track-probe';
 import type { YoutubePickerOpenPayload, YoutubeTrackOption } from '../../types';
 
 const primaryTrack: YoutubeTrackOption = {
@@ -20,6 +21,66 @@ const secondaryTrack: YoutubeTrackOption = {
   label: 'English (manual)',
 };
 
+test('youtube flow announces manual picker opening before probing tracks', async () => {
+  const osdMessages: string[] = [];
+  let resolveProbe: (probe: YoutubeTrackProbeResult) => void = () => {};
+  const probePromise = new Promise<YoutubeTrackProbeResult>((resolve) => {
+    resolveProbe = resolve;
+  });
+
+  const runtime = createYoutubeFlowRuntime({
+    probeYoutubeTracks: async () => await probePromise,
+    acquireYoutubeSubtitleTracks: async () => new Map(),
+    acquireYoutubeSubtitleTrack: async () => ({ path: '/tmp/unused.vtt' }),
+    openPicker: async (payload) => {
+      queueMicrotask(() => {
+        void runtime.resolveActivePicker({
+          sessionId: payload.sessionId,
+          action: 'continue-without-subtitles',
+          primaryTrackId: null,
+          secondaryTrackId: null,
+        });
+      });
+      return true;
+    },
+    pauseMpv: () => {},
+    resumeMpv: () => {},
+    sendMpvCommand: () => {},
+    requestMpvProperty: async () => null,
+    refreshCurrentSubtitle: () => {},
+    startTokenizationWarmups: async () => {},
+    waitForTokenizationReady: async () => {},
+    waitForAnkiReady: async () => {},
+    wait: async () => {},
+    waitForPlaybackWindowReady: async () => {},
+    waitForOverlayGeometryReady: async () => {},
+    focusOverlayWindow: () => {},
+    showMpvOsd: (text) => {
+      osdMessages.push(text);
+    },
+    reportSubtitleFailure: (message) => {
+      throw new Error(message);
+    },
+    warn: (message) => {
+      throw new Error(message);
+    },
+    log: () => {},
+    getYoutubeOutputDir: () => '/tmp',
+  });
+
+  const pending = runtime.openManualPicker({ url: 'https://example.com' });
+  await Promise.resolve();
+
+  assert.deepEqual(osdMessages, ['Opening YouTube subtitle picker...']);
+
+  resolveProbe({
+    videoId: 'video123',
+    title: 'Video 123',
+    tracks: [],
+  });
+  await pending;
+});
+
 test('youtube flow can open a manual picker session and load the selected subtitles', async () => {
   const commands: Array<Array<string | number>> = [];
   const focusOverlayCalls: string[] = [];
@@ -126,6 +187,7 @@ test('youtube flow can open a manual picker session and load the selected subtit
   assert.equal(openedPayloads[0]?.defaultSecondaryTrackId, secondaryTrack.id);
   assert.ok(waits.includes(150));
   assert.deepEqual(osdMessages, [
+    'Opening YouTube subtitle picker...',
     'Getting subtitles...',
     'Downloading subtitles...',
     'Loading subtitles...',

src/main/runtime/youtube-flow.ts

@@ -755,6 +755,8 @@ export function createYoutubeFlowRuntime(deps: YoutubeFlowDeps) {
     url: string;
     mode?: YoutubeFlowMode;
   }): Promise<void> => {
+    deps.showMpvOsd('Opening YouTube subtitle picker...');
+
     let probe: YoutubeTrackProbeResult;
     try {
       probe = await deps.probeYoutubeTracks(input.url);

src/main/runtime/youtube-media-cache-playback.test.ts

@@ -0,0 +1,175 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createYoutubeMediaCachePlaybackRuntime } from './youtube-media-cache-playback';
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return { promise, resolve };
+}
+
+test('youtube media cache starts when mpv reports a youtube path in background mode', async () => {
+  const starts: Array<{ url: string; maxHeight: number }> = [];
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode: 'background', maxHeight: 480 }),
+    startYoutubeMediaCache: (url, options) => {
+      starts.push({ url, maxHeight: options.maxHeight ?? 0 });
+    },
+    logWarn: () => {},
+  });
+
+  await runtime.handleMediaPathChange('https://www.youtube.com/watch?v=abc123');
+
+  assert.deepEqual(starts, [
+    {
+      url: 'https://www.youtube.com/watch?v=abc123',
+      maxHeight: 480,
+    },
+  ]);
+});
+
+test('youtube media cache starts from original playlist url when mpv path is a resolved stream', async () => {
+  const starts: string[] = [];
+  const propertyRequests: string[] = [];
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode: 'background', maxHeight: 720 }),
+    requestMpvProperty: async (name) => {
+      propertyRequests.push(name);
+      if (name === 'playlist-playing-pos') {
+        return 0;
+      }
+      if (name === 'playlist') {
+        return [{ filename: 'https://www.youtube.com/watch?v=abc123' }];
+      }
+      return null;
+    },
+    startYoutubeMediaCache: (url) => {
+      starts.push(url);
+    },
+    logWarn: () => {},
+  });
+
+  await runtime.handleMediaPathChange(
+    'https://rr1---sn.example.googlevideo.com/videoplayback?expire=1777777777',
+  );
+
+  assert.deepEqual(propertyRequests, ['playlist-playing-pos', 'playlist']);
+  assert.deepEqual(starts, ['https://www.youtube.com/watch?v=abc123']);
+  assert.equal(await runtime.getActiveYoutubeSourceUrl(), 'https://www.youtube.com/watch?v=abc123');
+});
+
+test('youtube media cache can recover playlist source from current playlist marker', async () => {
+  const starts: string[] = [];
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode: 'background', maxHeight: 720 }),
+    requestMpvProperty: async (name) => {
+      if (name === 'playlist-playing-pos') {
+        return -1;
+      }
+      if (name === 'playlist') {
+        return [
+          {
+            filename: 'https://example.com/other.mp4',
+          },
+          {
+            filename: 'https://youtu.be/abc123',
+            current: true,
+          },
+        ];
+      }
+      return null;
+    },
+    startYoutubeMediaCache: (url) => {
+      starts.push(url);
+    },
+    logWarn: () => {},
+  });
+
+  await runtime.handleMediaPathChange(
+    'https://rr1---sn.example.googlevideo.com/videoplayback?expire=1777777777',
+  );
+
+  assert.deepEqual(starts, ['https://youtu.be/abc123']);
+  assert.equal(await runtime.getActiveYoutubeSourceUrl(), 'https://youtu.be/abc123');
+});
+
+test('youtube media source getter awaits in-flight playlist recovery', async () => {
+  const starts: string[] = [];
+  const playlist = createDeferred<unknown>();
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode: 'background', maxHeight: 720 }),
+    requestMpvProperty: async (name) => {
+      if (name === 'playlist-playing-pos') {
+        return 0;
+      }
+      if (name === 'playlist') {
+        return await playlist.promise;
+      }
+      return null;
+    },
+    startYoutubeMediaCache: (url) => {
+      starts.push(url);
+    },
+    logWarn: () => {},
+  });
+
+  const pathChange = runtime.handleMediaPathChange(
+    'https://rr1---sn.example.googlevideo.com/videoplayback?expire=1777777777',
+  );
+  const sourceUrl = runtime.getActiveYoutubeSourceUrl();
+
+  playlist.resolve([{ filename: 'https://www.youtube.com/watch?v=abc123' }]);
+
+  assert.equal(await sourceUrl, 'https://www.youtube.com/watch?v=abc123');
+  await pathChange;
+  assert.deepEqual(starts, ['https://www.youtube.com/watch?v=abc123']);
+});
+
+test('youtube media cache ignores non-youtube paths and direct mode', async () => {
+  const starts: string[] = [];
+  const propertyRequests: string[] = [];
+  let mode: 'direct' | 'background' = 'background';
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode, maxHeight: 720 }),
+    requestMpvProperty: async (name) => {
+      propertyRequests.push(name);
+      return [
+        {
+          filename: 'https://www.youtube.com/watch?v=abc123',
+          current: true,
+        },
+      ];
+    },
+    startYoutubeMediaCache: (url) => {
+      starts.push(url);
+    },
+    logWarn: () => {},
+  });
+
+  await runtime.handleMediaPathChange('/tmp/video.mkv');
+  mode = 'direct';
+  await runtime.handleMediaPathChange('https://youtu.be/abc123');
+
+  assert.deepEqual(propertyRequests, []);
+  assert.deepEqual(starts, []);
+});
+
+test('youtube media cache logs synchronous start failures from path changes', async () => {
+  const warnings: string[] = [];
+  const runtime = createYoutubeMediaCachePlaybackRuntime({
+    getMediaCacheConfig: () => ({ mode: 'background', maxHeight: 720 }),
+    startYoutubeMediaCache: () => {
+      throw new Error('yt-dlp missing');
+    },
+    logWarn: (message) => {
+      warnings.push(message);
+    },
+  });
+
+  await runtime.handleMediaPathChange('https://youtu.be/abc123');
+
+  assert.deepEqual(warnings, ['Failed to start YouTube media cache: yt-dlp missing']);
+});

src/main/runtime/youtube-media-cache-playback.ts

@@ -0,0 +1,179 @@
+import type { YoutubeMediaCacheMode } from '../../types/integrations';
+import { isYoutubeMediaPath } from './youtube-playback';
+
+type PlaylistEntry = {
+  filename: string;
+  current: boolean;
+  playing: boolean;
+};
+
+export interface YoutubeMediaCachePlaybackRuntimeDeps {
+  getMediaCacheConfig: () => {
+    mode: YoutubeMediaCacheMode;
+    maxHeight?: number;
+  };
+  requestMpvProperty?: (name: string) => Promise<unknown>;
+  startYoutubeMediaCache: (
+    url: string,
+    options: {
+      mode: YoutubeMediaCacheMode;
+      maxHeight?: number;
+    },
+  ) => void;
+  logWarn: (message: string) => void;
+}
+
+function trimToNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizePlaylistIndex(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function isGoogleVideoStreamPath(mediaPath: string): boolean {
+  try {
+    const parsed = new URL(mediaPath);
+    const host = parsed.hostname.toLowerCase();
+    return host === 'googlevideo.com' || host.endsWith('.googlevideo.com');
+  } catch {
+    return false;
+  }
+}
+
+function normalizePlaylistEntries(raw: unknown): PlaylistEntry[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  return raw.map((entry) => {
+    const item = (entry ?? {}) as {
+      filename?: unknown;
+      current?: unknown;
+      playing?: unknown;
+    };
+    return {
+      filename: trimToNonEmptyString(item.filename) ?? '',
+      current: item.current === true,
+      playing: item.playing === true,
+    };
+  });
+}
+
+function resolvePlaylistEntry(
+  playlist: PlaylistEntry[],
+  playingPosValue: unknown,
+): PlaylistEntry | null {
+  if (playlist.length === 0) {
+    return null;
+  }
+
+  const playingPos = normalizePlaylistIndex(playingPosValue);
+  if (playingPos !== null && playingPos < playlist.length) {
+    return playlist[playingPos] ?? null;
+  }
+
+  return playlist.find((entry) => entry.current || entry.playing) ?? null;
+}
+
+async function requestMpvPropertySafely(
+  deps: YoutubeMediaCachePlaybackRuntimeDeps,
+  name: string,
+): Promise<unknown> {
+  if (!deps.requestMpvProperty) {
+    return null;
+  }
+  try {
+    return await deps.requestMpvProperty(name);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveYoutubeSourceFromPlaylist(
+  deps: YoutubeMediaCachePlaybackRuntimeDeps,
+): Promise<string | null> {
+  const [playingPosValue, playlistValue] = await Promise.all([
+    requestMpvPropertySafely(deps, 'playlist-playing-pos'),
+    requestMpvPropertySafely(deps, 'playlist'),
+  ]);
+  const playlistEntry = resolvePlaylistEntry(
+    normalizePlaylistEntries(playlistValue),
+    playingPosValue,
+  );
+  return playlistEntry?.filename && isYoutubeMediaPath(playlistEntry.filename)
+    ? playlistEntry.filename
+    : null;
+}
+
+async function resolveYoutubeSourceUrl(
+  deps: YoutubeMediaCachePlaybackRuntimeDeps,
+  mediaPath: string,
+): Promise<string | null> {
+  const directPath = trimToNonEmptyString(mediaPath);
+  if (directPath && isYoutubeMediaPath(directPath)) {
+    return directPath;
+  }
+  if (!directPath || !isGoogleVideoStreamPath(directPath)) {
+    return null;
+  }
+  return await resolveYoutubeSourceFromPlaylist(deps);
+}
+
+export function createYoutubeMediaCachePlaybackRuntime(deps: YoutubeMediaCachePlaybackRuntimeDeps) {
+  let activeYoutubeSourceUrl: string | null = null;
+  let activeYoutubeSourceUrlPromise: Promise<string | null> | null = null;
+  let generation = 0;
+
+  const handleMediaPathChange = async (mediaPath: string): Promise<void> => {
+    const currentGeneration = ++generation;
+    const config = deps.getMediaCacheConfig();
+    if (config.mode !== 'background') {
+      activeYoutubeSourceUrl = null;
+      activeYoutubeSourceUrlPromise = Promise.resolve(null);
+      return;
+    }
+
+    if (!isYoutubeMediaPath(mediaPath)) {
+      activeYoutubeSourceUrl = null;
+    }
+
+    const sourceUrlPromise = resolveYoutubeSourceUrl(deps, mediaPath);
+    activeYoutubeSourceUrlPromise = sourceUrlPromise.then((sourceUrl) =>
+      currentGeneration === generation ? sourceUrl : null,
+    );
+
+    const sourceUrl = await sourceUrlPromise;
+    if (currentGeneration !== generation) {
+      return;
+    }
+
+    activeYoutubeSourceUrl = sourceUrl;
+    if (!sourceUrl) {
+      return;
+    }
+
+    try {
+      deps.startYoutubeMediaCache(sourceUrl, {
+        mode: config.mode,
+        maxHeight: config.maxHeight,
+      });
+    } catch (error) {
+      deps.logWarn(
+        `Failed to start YouTube media cache: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  };
+
+  return {
+    getActiveYoutubeSourceUrl: async (): Promise<string | null> =>
+      activeYoutubeSourceUrlPromise ?? activeYoutubeSourceUrl,
+    getActiveYoutubeSourceUrlSnapshot: (): string | null => activeYoutubeSourceUrl,
+    handleMediaPathChange,
+  };
+}

src/main/runtime/youtube-playback-runtime.ts

@@ -130,14 +130,13 @@ export function createYoutubePlaybackRuntime(deps: YoutubePlaybackRuntimeDeps) {
       if (deps.startYoutubeMediaCache) {
         void new Promise<void>((resolve) => {
           resolve(deps.startYoutubeMediaCache?.(request.url));
-        })
-          .catch((error) => {
-            deps.logWarn(
-              `Failed to start YouTube media cache: ${
-                error instanceof Error ? error.message : String(error)
-              }`,
-            );
-          });
+        }).catch((error) => {
+          deps.logWarn(
+            `Failed to start YouTube media cache: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        });
       }
 
       await deps.runYoutubePlaybackFlow({

src/renderer/overlay-notifications.test.ts

@@ -384,6 +384,92 @@ test('overlay notification renderer updates same-id progress without replacing t
   }
 });
 
+test('overlay notification renderer auto-dismisses same-id terminal update after persistent progress', () => {
+  const originalDocument = Object.getOwnPropertyDescriptor(globalThis, 'document');
+  const originalWindow = Object.getOwnPropertyDescriptor(globalThis, 'window');
+  const stack = createFakeElement();
+  let nextTimerId = 1;
+  const timers = new Map<number, { callback: () => void; delayMs: number }>();
+
+  Object.defineProperty(globalThis, 'document', {
+    configurable: true,
+    writable: true,
+    value: {
+      createElement: (tagName: string) => createFakeElement(tagName),
+    },
+  });
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    writable: true,
+    value: {
+      clearTimeout: (id: number) => {
+        timers.delete(id);
+      },
+      setTimeout: (callback: () => void, delayMs: number) => {
+        const id = nextTimerId;
+        nextTimerId += 1;
+        timers.set(id, { callback, delayMs });
+        return id;
+      },
+    },
+  });
+
+  try {
+    const renderer = createOverlayNotificationRenderer({
+      dom: {
+        overlayNotificationStack: stack,
+      },
+      state: {
+        isOverOverlayNotification: false,
+      },
+    } as never);
+
+    renderer.show({
+      id: 'youtube-subtitles-status',
+      title: 'YouTube subtitles',
+      body: 'Downloading subtitles...',
+      variant: 'progress',
+      persistent: true,
+    });
+    const card = stack.children[0];
+    if (!card) {
+      assert.fail('Expected overlay notification card.');
+    }
+
+    renderer.show({
+      id: 'youtube-subtitles-status',
+      title: 'YouTube subtitles',
+      body: 'Subtitles loaded.',
+      variant: 'success',
+      persistent: false,
+    });
+
+    const autoDismissTimer = [...timers.values()].find((timer) => timer.delayMs === 3000);
+    assert.ok(autoDismissTimer, 'Expected terminal update to schedule an auto-dismiss timer.');
+    assert.equal(stack.children[0], card);
+    assert.equal(
+      findChildByClass(card, 'overlay-notification-body')?.textContent,
+      'Subtitles loaded.',
+    );
+    assert.equal(card.classList.contains('success'), true);
+
+    autoDismissTimer.callback();
+
+    assert.equal(card.classList.contains('leaving'), true);
+  } finally {
+    if (originalDocument) {
+      Object.defineProperty(globalThis, 'document', originalDocument);
+    } else {
+      delete (globalThis as { document?: unknown }).document;
+    }
+    if (originalWindow) {
+      Object.defineProperty(globalThis, 'window', originalWindow);
+    } else {
+      delete (globalThis as { window?: unknown }).window;
+    }
+  }
+});
+
 test('overlay notification cards use larger display dimensions', () => {
   assert.match(
     overlayNotificationCss,