chore(release): prepare 0.15.0-beta.3

CI runners don't have Claude Code installed, so the regen step in the
prerelease workflow died on 'claude CLI not found'. Mirror the stable
release model: generate prerelease-notes.md locally (claude -p), commit
it, and have CI just verify and reference the committed file.

.github/workflows/prerelease.yml

@@ -47,6 +47,13 @@ jobs:
       - name: Build (TypeScript check)
         run: bun run typecheck
 
+      - name: Install Lua
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y lua5.4
+          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
+          lua -v
+
       - name: Test suite (source)
         run: bun run test:fast
 
@@ -362,8 +369,12 @@ jobs:
         id: version
         run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Generate prerelease notes from pending fragments
-        run: bun run changelog:prerelease-notes --version "${{ steps.version.outputs.VERSION }}"
+      - name: Verify committed prerelease notes
+        run: |
+          if [ ! -s release/prerelease-notes.md ]; then
+            echo "::error::release/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
+            exit 1
+          fi
 
       - name: Publish Prerelease
         env:

.gitignore

@@ -10,6 +10,7 @@ dist/
 release/*
 !release/
 !release/release-notes.md
+!release/prerelease-notes.md
 build/yomitan/
 coverage/
 

Makefile

@@ -20,9 +20,10 @@ MACOS_APP_DIR ?= $(HOME)/Applications
 MACOS_APP_DEST ?= $(MACOS_APP_DIR)/SubMiner.app
 
 # If building from source, the AppImage will typically land in release/.
-APPIMAGE_SRC := $(firstword $(wildcard release/SubMiner-*.AppImage))
-MACOS_APP_SRC := $(firstword $(wildcard release/*.app release/*/*.app))
-MACOS_ZIP_SRC := $(firstword $(wildcard release/SubMiner-*.zip))
+APPIMAGE_SRC = $(firstword $(wildcard release/SubMiner-*.AppImage))
+MACOS_APP_SRC = $(firstword $(wildcard release/*.app release/*/*.app))
+MACOS_ZIP_SRC = $(firstword $(wildcard release/SubMiner-*.zip))
+PRERELEASE_NOTES := release/prerelease-notes.md
 
 UNAME_S := $(shell uname -s 2>/dev/null || echo Unknown)
 ifeq ($(OS),Windows_NT)
@@ -161,7 +162,15 @@ build-launcher:
 
 clean:
 	@printf '%s\n' "[INFO] Removing build artifacts"
-	@rm -rf dist release
+	@if [ -f "$(PRERELEASE_NOTES)" ]; then \
+		PRERELEASE_NOTES_BACKUP="$$(mktemp -t subminer-prerelease-notes.XXXXXX)" && \
+		cp "$(PRERELEASE_NOTES)" "$$PRERELEASE_NOTES_BACKUP" && \
+		rm -rf dist release && \
+		install -d release && \
+		mv "$$PRERELEASE_NOTES_BACKUP" "$(PRERELEASE_NOTES)"; \
+	else \
+		rm -rf dist release; \
+	fi
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 
 generate-config: ensure-bun

README.md

@@ -217,12 +217,13 @@ Download the latest DMG or ZIP from [GitHub Releases](https://github.com/ksyasud
 Also download the `subminer` launcher (recommended):
 
 ```bash
-sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer \
-	&& sudo chmod +x /usr/local/bin/subminer
+mkdir -p ~/.local/bin
+curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o ~/.local/bin/subminer \
+	&& chmod +x ~/.local/bin/subminer
 ```
 
 > [!NOTE]
-> The `subminer` launcher uses a [Bun](https://bun.sh) shebang. First-run setup can optionally install Bun and the launcher into an existing writable PATH directory.
+> The `subminer` launcher uses a [Bun](https://bun.sh) shebang. First-run setup can optionally install Bun and the launcher into an existing writable PATH directory. Make sure `~/.local/bin` is on your PATH before installing there.
 
 </details>
 

changes/auto-update.md

@@ -1,4 +1,4 @@
 type: added
 area: updater
 
-- Added tray and `subminer -u` update checks for SubMiner releases, including app update prompts, launcher/support asset updates, checksum verification, configurable update notifications, and an opt-in prerelease update channel for beta/RC testing.
+- Added tray and `subminer -u` update checks for SubMiner releases, including app update prompts, launcher updates, Linux rofi theme updates, checksum verification, configurable update notifications, and an opt-in prerelease update channel for beta/RC testing.

changes/character-dictionary-resolution-cache.md

@@ -0,0 +1,4 @@
+type: fixed
+area: character-dictionary
+
+- Reused cached character-dictionary media matches so loading a title with an existing snapshot no longer sends another AniList search request.

changes/controller-config-enables-input.md

@@ -0,0 +1,6 @@
+type: fixed
+area: overlay
+
+- Controller config and debug shortcuts now stay closed while controller support is disabled and show a notice to enable `controller.enabled` manually.
+- Controller binding rows now start learn mode from the edit pencil, so clicking edit and pressing a controller button saves the remap.
+- Controller remaps are now saved per controller profile, binding badges also start learn mode, and row reset buttons restore individual bindings to their defaults.

changes/fix-anilist-timepos-threshold.md

@@ -0,0 +1,6 @@
+type: fixed
+area: anilist
+
+- Used fresh mpv time-position, duration, and subtitle timing events for AniList post-watch threshold checks so progress updates still fire when playback reaches or skips past the watched threshold.
+- Prefer season-specific AniList search results for multi-season files before falling back to the base title.
+- Show a clear AniList message when the matched season is not in Planning or Watching instead of silently queueing an impossible progress update.

changes/fix-macos-overlay-layering.md

@@ -0,0 +1,10 @@
+type: fixed
+area: overlay
+
+- Hid the macOS visible overlay when mpv is no longer the foreground target so other apps and Spaces are not covered by SubMiner subtitles.
+- Kept the macOS overlay layered above active mpv while stats mouse passthrough is enabled, and treated the frontmost mpv app as the focus signal.
+- Opened the stats overlay inactive on macOS so it appears over fullscreen mpv instead of switching back to SubMiner's original desktop.
+- Preserved the active mpv focus state through transient macOS helper misses so subtitles do not flicker while mpv remains foreground.
+- Kept fullscreen macOS overlays stable when mpv remains frontmost but window geometry temporarily disappears from the macOS window APIs.
+- Released the macOS overlay when the helper reports mpv is no longer foreground so other apps are no longer covered.
+- Reduced macOS window-tracker background work by preferring the compiled helper and slowing polls while mpv is stably focused.

changes/fix-macos-overlay-minimize-tracking.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed macOS overlay tracking so transient mpv window misses no longer hide the overlay; minimizing mpv still hides it.

changes/fix-macos-overlay-passthrough.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed macOS overlay passthrough so mpv controls remain clickable before hovering subtitle bars.

changes/fix-subsync-modal-window.md

@@ -0,0 +1,4 @@
+type: fixed
+area: overlay
+
+- Fixed subtitle sync modal opens so macOS no longer flashes and hides the first modal attempt or leaves stale modal state after syncing.

changes/linux-direct-launcher-update.md

@@ -0,0 +1,5 @@
+type: fixed
+area: updater
+
+- Made Linux `subminer -u` perform release updates from the launcher, independent of any running tray app instance, while reporting `up to date` without downloading assets when the latest release is not newer.
+- Limited support asset updates to the Linux rofi theme.

changes/linux-launcher-shim.md

@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Fixed Linux first-run launcher installs by building the packaged launcher with a valid Bun shebang.

changes/linux-updater-error-event.md

@@ -0,0 +1,4 @@
+type: fixed
+area: updater
+
+- Stopped Linux tray update checks from invoking the native Electron updater, using GitHub release metadata/assets instead so checks do not crash the tray app.

changes/macos-local-bin-launcher.md

@@ -0,0 +1,4 @@
+type: fixed
+area: setup
+
+- First-run setup now recognizes installed macOS launchers in Homebrew or user PATH dirs, while manual setup installs avoid Homebrew-owned directories.

changes/macos-manual-update-required.md

@@ -0,0 +1,4 @@
+type: fixed
+area: updater
+
+- Fixed tray update checks for builds that cannot install native app updates, showing a manual install message instead of a restart prompt that cannot apply the update.

changes/macos-update-dialog-focus.md

@@ -0,0 +1,4 @@
+type: fixed
+area: updater
+
+- Bring macOS update dialogs to the front when `subminer --update` is run from the launcher.

changes/make-install-fresh-appimage.md

@@ -0,0 +1,4 @@
+type: fixed
+area: build
+
+- Fixed one-shot `make clean build install` flows so install picks up the AppImage built earlier in the same make invocation.

changes/native-updater-crash.md

@@ -0,0 +1,4 @@
+type: fixed
+area: updates
+
+- Kept signed macOS app updates on the native updater path while preventing eager Squirrel install checks before the user confirms restart.

changes/prerelease-notes-reuse.md

@@ -0,0 +1,4 @@
+type: changed
+area: release
+
+- Prerelease note generation now reuses existing reviewed prerelease notes and asks Claude to merge only new fragment material, while `make clean` preserves `release/prerelease-notes.md`.

changes/setup-background-command.md

@@ -0,0 +1,4 @@
+type: fixed
+area: launcher
+
+- Fixed `subminer app --setup` so it opens the setup flow when SubMiner is already running in the background.

changes/setup-finish-quit.md

@@ -0,0 +1,4 @@
+type: fixed
+area: setup
+
+- Quit standalone setup app launches after first-run setup finishes, returning the terminal instead of leaving the app process open.

changes/tray-modal-lifecycle.md

@@ -3,9 +3,8 @@ area: tray
 
 - Kept the tray app running when closing tray-launched Yomitan settings.
 - Kept tray-launched Yomitan settings loading from blocking other tray actions.
-- Removed the default native app menu from Yomitan settings so File > Quit cannot put the tray app into a stuck quit state.
+- Replaced the default native Yomitan settings menu with a close-only menu so closing settings does not quit the tray app.
+- Added an in-page close button for Yomitan settings on Hyprland, where native window controls are not available.
 - Disabled Yomitan's embedded popup preview in the tray-launched settings window to avoid renderer hangs during normal sidebar navigation.
-- Skipped heavy Yomitan settings startup preview, storage, dictionary, and Anki controllers when launched from SubMiner to avoid renderer hangs with large dictionary databases.
-- Cached Yomitan settings dictionary metadata after explicit loads to avoid repeated large IndexedDB reads.
 - Serialized copied Yomitan extension refreshes so startup cannot race itself and leave extension loading in an error state.
 - Fixed tray-launched session help focus handling so the modal can close without mpv running.

config.example.jsonc

@@ -138,7 +138,8 @@
         "axisIndex": 4, // Raw axis index captured for this analog controller action.
         "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
       } // Axis binding descriptor used for popup page jumps. Use Alt+C learn mode or set a raw axis descriptor manually.
-    } // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+    }, // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+    "profiles": {} // Per-controller binding and button-index overrides keyed by the controller id reported by the Gamepad API.
   }, // Gamepad support for the visible overlay while keyboard-only mode is active.
 
   // ==========================================

docs-site/anilist-integration.md

@@ -17,8 +17,8 @@ AniList integration is opt-in. To enable it:
 {
   "anilist": {
     "enabled": true,
-    "accessToken": ""
-  }
+    "accessToken": "",
+  },
 }
 ```
 
@@ -37,20 +37,20 @@ SubMiner monitors playback and triggers an AniList progress update when an episo
 The update flow:
 
 1. **Title detection** -- SubMiner extracts the anime title, season, and episode number from the media filename. It tries [`guessit`](https://github.com/guessit-io/guessit) first for accurate parsing, then falls back to an internal filename parser if guessit is unavailable.
-2. **AniList search** -- The detected title is searched against the AniList GraphQL API. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
-3. **Progress check** -- SubMiner fetches your current list entry for the matched media. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
+2. **AniList search** -- The detected title is searched against the AniList GraphQL API. For season 2 and later files, SubMiner searches the season-specific title first, then falls back to the base title. SubMiner picks the best match by comparing titles (romaji, English, native) and filtering by episode count.
+3. **Progress check** -- SubMiner fetches your current list entry for the matched media. The media must already be in Planning or Watching; otherwise SubMiner shows an MPV message explaining that the update is not possible. If your recorded progress already meets or exceeds the detected episode, the update is skipped.
 4. **Mutation** -- A `SaveMediaListEntry` mutation sets the new progress and marks the entry as `CURRENT`.
 
 ## Update Queue and Retry
 
 Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
 
-| Parameter | Value |
-| --- | --- |
-| Initial backoff | 30 seconds |
-| Maximum backoff | 6 hours |
-| Maximum attempts | 8 |
-| Queue capacity | 500 items |
+| Parameter        | Value      |
+| ---------------- | ---------- |
+| Initial backoff  | 30 seconds |
+| Maximum backoff  | 6 hours    |
+| Maximum attempts | 8          |
+| Queue capacity   | 500 items  |
 
 After 8 failed attempts, the update is moved to a dead-letter queue and no longer retried automatically. The queue is persisted across restarts so no updates are lost if SubMiner exits before a retry succeeds.
 
@@ -85,36 +85,37 @@ All AniList API calls go through a shared rate limiter that enforces a sliding w
       "collapsibleSections": {
         "description": false,
         "characterInformation": false,
-        "voicedBy": false
-      }
-    }
-  }
+        "voicedBy": false,
+      },
+    },
+  },
 }
 ```
 
-| Option | Values | Description |
-| --- | --- | --- |
-| `enabled` | `true`, `false` | Enable AniList post-watch progress updates (default: `false`) |
-| `accessToken` | string | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
-| `characterDictionary.enabled` | `true`, `false` | Enable auto-sync of the merged character dictionary from AniList (default: `false`) |
-| `characterDictionary.maxLoaded` | number | Number of recent media snapshots kept in the merged dictionary (default: `3`) |
-| `characterDictionary.profileScope` | `"all"`, `"active"` | Apply dictionary to all Yomitan profiles or only the active one |
-| `characterDictionary.collapsibleSections.*` | `true`, `false` | Control which dictionary entry sections start expanded |
+| Option                                      | Values              | Description                                                                                                  |
+| ------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `enabled`                                   | `true`, `false`     | Enable AniList post-watch progress updates (default: `false`)                                                |
+| `accessToken`                               | string              | Explicit AniList access token override; when blank, SubMiner uses the stored encrypted token (default: `""`) |
+| `characterDictionary.enabled`               | `true`, `false`     | Enable auto-sync of the merged character dictionary from AniList (default: `false`)                          |
+| `characterDictionary.maxLoaded`             | number              | Number of recent media snapshots kept in the merged dictionary (default: `3`)                                |
+| `characterDictionary.profileScope`          | `"all"`, `"active"` | Apply dictionary to all Yomitan profiles or only the active one                                              |
+| `characterDictionary.collapsibleSections.*` | `true`, `false`     | Control which dictionary entry sections start expanded                                                       |
 
 See the [Character Dictionary](/character-dictionary) page for full details on the character dictionary feature, including name generation, matching, auto-sync lifecycle, and dictionary entry format.
 
 ## CLI Commands
 
-| Command | Description |
-| --- | --- |
-| `--anilist-setup` | Open AniList setup/auth flow helper window |
-| `--anilist-status` | Print current token resolution state and retry queue counters |
-| `--anilist-logout` | Clear stored AniList token from local persisted state |
-| `--anilist-retry-queue` | Process one ready retry queue item immediately |
+| Command                 | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `--anilist-setup`       | Open AniList setup/auth flow helper window                    |
+| `--anilist-status`      | Print current token resolution state and retry queue counters |
+| `--anilist-logout`      | Clear stored AniList token from local persisted state         |
+| `--anilist-retry-queue` | Process one ready retry queue item immediately                |
 
 ## Troubleshooting
 
 - **Updates not triggering:** Confirm `anilist.enabled` is `true`. SubMiner requires at least 85% of the episode watched and a minimum of 10 minutes. Short episodes or partial watches will not trigger an update.
+- **Update not possible:** Add the season to your AniList Planning or Watching list first. SubMiner will not create new AniList list entries automatically.
 - **Wrong episode or title matched:** Detection quality is best when `guessit` is installed and on your `PATH`. Without it, SubMiner falls back to internal filename parsing which can be less accurate with unusual naming conventions.
 - **Token issues:** Run `--anilist-status` to check token state. If the token is invalid or expired, run `--anilist-setup` or `--anilist-logout` and re-authenticate.
 - **Updates failing repeatedly:** Run `--anilist-status` to see retry queue counters. Items that fail 8 times are moved to the dead-letter queue. Check network connectivity and AniList API status.

docs-site/character-dictionary.md

@@ -35,7 +35,7 @@ Character dictionary sync is disabled by default. To turn it on:
 ```
 
 ::: tip
-The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached snapshot.
+The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
 :::
 
 ::: warning
@@ -139,7 +139,7 @@ When `characterDictionary.enabled` is `true`, SubMiner runs an auto-sync routine
 5. **importing** — Push the ZIP into Yomitan. Waits for Yomitan mutation readiness (7-second timeout per operation).
 6. **ready** — Dictionary is live. Character names will match on the next subtitle line.
 
-**State tracking** is persisted in `character-dictionaries/auto-sync-state.json`:
+**State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.
 
 ```jsonc
 {

docs-site/configuration.md

@@ -608,8 +608,12 @@ Important behavior:
 - Controller input is only active while keyboard-only mode is enabled.
 - Keyboard-only mode continues to work normally without a controller.
 - By default SubMiner uses the first connected controller.
+- Fresh installs keep controller support disabled until you set `controller.enabled` to `true`.
 - `Alt+C` opens the controller config modal by default, and you can remap that shortcut through `shortcuts.openControllerSelect`.
-- Click `Learn`, then press the next fresh button, trigger, or stick direction you want to bind for that overlay action.
+- The `Alt+C` config modal and `Alt+Shift+C` debug modal stay closed while controller support is disabled.
+- Click the binding badge, edit pencil, or `Learn`, then press the next fresh button, trigger, or stick direction you want to bind for that overlay action.
+- Click the reset button beside the edit pencil to restore one binding to the built-in default.
+- Learned bindings are saved under `controller.profiles` for the selected controller id. Global `controller.bindings` remains the fallback for controllers without a profile.
 - `Alt+Shift+C` opens the debug modal by default, and you can remap that shortcut through `shortcuts.openControllerDebug`.
 - The debug modal shows raw axes/button values plus a ready-to-copy `buttonIndices` config block.
 - `controller.buttonIndices` is a semantic reference/legacy mapping. Changing it does not rewrite the raw numeric descriptor values already stored under `controller.bindings`.
@@ -658,6 +662,15 @@ Important behavior:
       "rightStickHorizontal": { "kind": "axis", "axisIndex": 3, "dpadFallback": "none" },
       "rightStickVertical": { "kind": "axis", "axisIndex": 4, "dpadFallback": "none" },
     },
+    "profiles": {
+      "Xbox Wireless Controller": {
+        "label": "Xbox Wireless Controller",
+        "bindings": {
+          "toggleLookup": { "kind": "button", "buttonIndex": 0 },
+          "mineCard": { "kind": "button", "buttonIndex": 2 },
+        },
+      },
+    },
   },
 }
 ```
@@ -678,7 +691,7 @@ Default logical mapping:
 - `L3`: toggle mpv pause
 - `L2` / `R2`: unbound by default
 
-Discrete bindings may use raw button indices or raw axis directions, and analog bindings use raw axis indices with optional D-pad fallback. The `Alt+C` learn flow writes those descriptors for you, so manual edits are only needed when you want to script or copy exact mappings.
+Discrete bindings may use raw button indices or raw axis directions, and analog bindings use raw axis indices with optional D-pad fallback. The `Alt+C` learn flow writes those descriptors under `controller.profiles["<controller id>"]` for the selected controller. Manual edits are only needed when you want to script or copy exact mappings.
 
 If you bind a discrete action to an axis manually, include `direction`:
 
@@ -692,15 +705,15 @@ If you bind a discrete action to an axis manually, include `direction`:
 }
 ```
 
-Treat `controller.buttonIndices` as reference-only unless you are still using legacy semantic bindings or copying values from the debug modal. Updating `controller.buttonIndices` alone does not rewrite the hardcoded raw numeric values already present in `controller.bindings`. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.
+Treat `controller.buttonIndices` as reference-only unless you are still using legacy semantic bindings or copying values from the debug modal. Updating `controller.buttonIndices` alone does not rewrite the hardcoded raw numeric values already present in `controller.bindings` or `controller.profiles.*.bindings`. If you need a real remap, prefer the `Alt+C` learn flow so both the source and the descriptor shape stay correct.
 
 If you choose to bind `L2` or `R2` manually, set `triggerInputMode` to `analog` and tune `triggerDeadzone` when your controller reports triggers as analog values instead of digital pressed/not-pressed buttons. `auto` accepts either style and remains the default.
 
-If your controller reports non-standard raw button numbers, override `controller.buttonIndices` using values from the `Alt+Shift+C` debug modal.
+If one controller reports non-standard raw button numbers, override `controller.profiles["<controller id>"].buttonIndices` using values from the `Alt+Shift+C` debug modal. Use global `controller.buttonIndices` only when the mapping should apply to every controller without a profile.
 
 If you update this controller documentation or the generated controller examples, run `bun run docs:test` and `bun run docs:build` before merging.
 
-Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing, and `buttonIndices` to match your controller. See [config.example.jsonc](/config.example.jsonc) for the full generated comments for every controller field.
+Tune `scrollPixelsPerSecond`, `horizontalJumpPixels`, deadzones, repeat timing, and profile `buttonIndices` to match your controller. See [config.example.jsonc](/config.example.jsonc) for the full generated comments for every controller field.
 
 ### Manual Card Update Shortcuts
 

docs-site/installation.md

@@ -155,11 +155,11 @@ chmod +x ~/.local/bin/SubMiner.AppImage
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
 chmod +x ~/.local/bin/subminer
 
-# Download launcher support assets used for bundled runtime plugin injection
+# Download the optional Linux rofi theme
 wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
 tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
-mkdir -p ~/.local/share/SubMiner/plugin/subminer
-cp -R /tmp/plugin/subminer/. ~/.local/share/SubMiner/plugin/subminer/
+mkdir -p ~/.local/share/SubMiner/themes
+cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
 ```
 
 The `subminer` launcher is the recommended way to use SubMiner on Linux. It ensures mpv is launched with the correct IPC socket, SubMiner defaults, and the bundled runtime plugin so you don't need to configure `mpv.conf` or install a global mpv plugin.
@@ -174,7 +174,9 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies launcher/support asset downloads against `SHA256SUMS.txt`. If the launcher is installed in a protected path such as `/usr/local/bin/subminer`, SubMiner does not elevate itself; it shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead.
+SubMiner verifies launcher and Linux rofi theme downloads against `SHA256SUMS.txt`. If the launcher is installed in a protected path such as `/usr/local/bin/subminer`, SubMiner does not elevate itself; it shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead.
+
+On Linux, `subminer -u` performs this update from the launcher process, so it does not need to start or IPC into the tray app.
 
 ### From Source
 
@@ -240,7 +242,7 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies launcher/support asset downloads against `SHA256SUMS.txt`. If `/usr/local/bin/subminer` is protected, SubMiner shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead of elevating itself.
+SubMiner verifies launcher downloads against `SHA256SUMS.txt`. If `/usr/local/bin/subminer` is protected, SubMiner shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead of elevating itself.
 
 ::: warning Bun required for the launcher
 The `subminer` launcher uses a Bun shebang (`#!/usr/bin/env bun`), so [Bun](https://bun.sh) must be installed and available on `PATH`. Install Bun if you haven't already: `curl -fsSL https://bun.sh/install | bash`.
@@ -269,7 +271,7 @@ Build and install the launcher alongside the app:
 make install-macos
 ```
 
-This builds the `subminer` launcher into `dist/launcher/subminer` and installs it to `~/.local/bin/subminer` along with the app bundle and rofi theme. To install to `/usr/local/bin` instead (already on the default macOS `PATH`):
+This builds the `subminer` launcher into `dist/launcher/subminer` and installs it to `~/.local/bin/subminer` along with the app bundle. To install to `/usr/local/bin` instead (already on the default macOS `PATH`):
 
 ```bash
 sudo make install-macos PREFIX=/usr/local

docs-site/launcher-script.md

@@ -109,6 +109,8 @@ Use `subminer <subcommand> -h` for command-specific help.
 | `--log-level`         | Logger verbosity (`debug`, `info`, `warn`, `error`)                  |
 | `--dev`, `--debug`    | Enable app dev-mode (not tied to log level)                          |
 
+On Linux, `subminer -u` updates from the launcher process itself. It can check and replace the AppImage, launcher, and rofi theme even when SubMiner is already running in the tray.
+
 With default plugin settings (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`), explicit start flags are usually unnecessary.
 
 ## Logging

docs-site/mining-workflow.md

@@ -65,7 +65,7 @@ With a gamepad connected and keyboard-only mode enabled, the full mining loop wo
 6. **Close** — press `B` to dismiss the Yomitan popup and return to subtitle navigation.
 7. **Pause/resume** — press `L3` (left stick click) to toggle mpv pause at any time.
 
-The controller and keyboard can be used interchangeably — switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.
+After controller support is enabled, the controller and keyboard can be used interchangeably — switching mid-session is seamless. Toggle keyboard-only mode on or off with `Y` on the controller.
 
 See [Usage — Controller Support](/usage#controller-support) for setup details and [Configuration — Controller Support](/configuration#controller-support) for the full mapping and tuning options.
 

docs-site/public/config.example.jsonc

@@ -138,7 +138,8 @@
         "axisIndex": 4, // Raw axis index captured for this analog controller action.
         "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
       } // Axis binding descriptor used for popup page jumps. Use Alt+C learn mode or set a raw axis descriptor manually.
-    } // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+    }, // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+    "profiles": {} // Per-controller binding and button-index overrides keyed by the controller id reported by the Gamepad API.
   }, // Gamepad support for the visible overlay while keyboard-only mode is active.
 
   // ==========================================

docs-site/usage.md

@@ -283,13 +283,14 @@ SubMiner supports gamepad/controller input for couch-friendly usage via the Chro
 ### Getting Started
 
 1. Connect a controller before or after launching SubMiner.
-2. Enable keyboard-only mode — press `Y` on the controller (default binding) or use the overlay keybinding.
+2. Set `controller.enabled` to `true` in your config.
 3. Press `Alt+C` in the overlay by default to pick the controller you want to save and remap any action inline.
-4. Click `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
-5. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
-6. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
+4. Enable keyboard-only mode — press `Y` on the controller (default binding) or use the overlay keybinding.
+5. Click the binding badge, edit pencil, or `Learn` on the overlay action you want, then press the matching button, trigger, or stick direction on the controller.
+6. Use the left stick to navigate subtitle tokens and scroll the popup; use the right stick vertically for popup page jumps.
+7. Press `A` to look up the selected word, `X` to mine a card, `B` to close the popup.
 
-By default SubMiner uses the first connected controller. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline, and `Alt+Shift+C` opens the live debug modal with raw axes/button values for non-standard pads. Both shortcuts can be changed through `shortcuts.openControllerSelect` and `shortcuts.openControllerDebug`.
+By default SubMiner uses the first connected controller after controller support is enabled. `Alt+C` opens the controller config modal, where you can save the preferred controller and remap bindings inline per controller. The reset button beside each edit pencil restores that binding to its built-in default for the selected controller. `Alt+Shift+C` opens the live debug modal with raw axes/button values for non-standard pads. Both modals stay closed while `controller.enabled` is false, and both shortcuts can be changed through `shortcuts.openControllerSelect` and `shortcuts.openControllerDebug`.
 
 ### Default Button Mapping
 
@@ -316,7 +317,7 @@ By default SubMiner uses the first connected controller. `Alt+C` opens the contr
 
 Learn mode ignores already-held inputs and waits for the next fresh button press or axis direction, which avoids accidental captures when you open the modal mid-input.
 
-All button and axis mappings are configurable under the `controller` config block. See [Configuration — Controller Support](/configuration#controller-support) for the full options.
+All button and axis mappings are configurable under the `controller` config block. Learned remaps are saved under `controller.profiles` for the selected controller id. See [Configuration — Controller Support](/configuration#controller-support) for the full options.
 
 ## Keybindings
 

docs/RELEASING.md

@@ -55,7 +55,13 @@
    `bun run build`
    When validating packaged updater output, confirm the platform build writes
    `*.yml` and `*.blockmap` files under `release/`.
-5. Commit the prerelease prep. Do not run `bun run changelog:build`.
+5. Commit the prerelease prep (package.json version bump + the generated
+   `release/prerelease-notes.md`). CI does not regenerate notes — it uses the
+   committed file — so review it before committing. If you add more
+   `changes/*.md` fragments for a later beta/RC, rerun
+   `bun run changelog:prerelease-notes --version <version>`; the generator uses
+   the existing prerelease notes as the baseline and asks Claude to merge only
+   the new fragment material. Do not run `bun run changelog:build`.
 6. Tag the commit: `git tag v<version>`.
 7. Push commit + tag.
 
@@ -67,11 +73,11 @@ Notes:
 - Supported prerelease channels are `beta` and `rc`, with versions like `0.11.3-beta.1` and `0.11.3-rc.1`.
 - Pass `--date` explicitly when you want the release stamped with the local cut date; otherwise the generator uses the current ISO date, which can roll over to the next UTC day late at night.
 - `changelog:check` now rejects tag/package version mismatches.
-- `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files.
+- `changelog:prerelease-notes` also rejects tag/package version mismatches and writes `release/prerelease-notes.md` without mutating tracked changelog files. When that file already exists, the generator includes it in the Claude prompt so later beta/RC notes reuse the reviewed text instead of starting over.
 - `changelog:build` generates `CHANGELOG.md` + `release/release-notes.md` (both polished by `claude -p`) and removes the released `changes/*.md` fragments. The CHANGELOG keeps internal notes inside a `<details><summary>Internal changes</summary>` collapse; the release notes drop them entirely.
 - The release workflow no longer auto-runs `changelog:build`. If pending `changes/*.md` fragments are present on a tag-based run, CI exits with a clear `::error::` pointing at the local fix. Run `bun run changelog:build --version <version>` locally, commit the polished output, then tag.
 - Do not tag while `changes/*.md` fragments still exist.
-- Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut.
+- Prerelease tags intentionally keep `changes/*.md` fragments in place so multiple prereleases can reuse the same cumulative pending notes until the final stable cut. `make clean` preserves `release/prerelease-notes.md` while deleting generated build artifacts.
 - If you need to repair a published release body (for example, a prior version’s section was omitted), regenerate notes from `CHANGELOG.md` and re-edit the release with `gh release edit --notes-file`.
 - Prerelease tags are handled by `.github/workflows/prerelease.yml`, which always publishes a GitHub prerelease with all current release platforms and never runs the AUR sync job.
 - Tagged release workflow now also attempts to update `subminer-bin` on the AUR after GitHub Release publication.

launcher/commands/command-modules.test.ts

@@ -241,36 +241,36 @@ test('dictionary command returns after app handoff starts', () => {
   assert.equal(handled, true);
 });
 
-test('update command forwards launcher path and waits for response', async () => {
+test('update command runs direct Linux release update without launching Electron', async () => {
   const context = createContext();
   context.args.update = true;
-  const forwarded: string[][] = [];
-  const responses: string[] = [];
+  const calls: string[] = [];
 
   const handled = await runUpdateCommand(context, {
-    createTempDir: () => '/tmp/subminer-update-test',
-    joinPath: (...parts) => parts.join('/'),
-    runAppCommandCaptureOutput: (_appPath, appArgs) => {
-      forwarded.push(appArgs);
-      return { status: 0, stdout: '', stderr: '' };
+    runAppCommandCaptureOutput: () => {
+      throw new Error('unexpected Electron launch');
     },
-    waitForUpdateResponse: async (responsePath) => {
-      responses.push(responsePath);
-      return { ok: true, status: 'up-to-date', version: '0.15.0' };
+    runDirectReleaseUpdate: async (request) => {
+      calls.push(`direct:${request.appPath}:${request.launcherPath}:${request.channel}`);
+      return {
+        appImage: { status: 'not-found' },
+        launcher: { status: 'updated' },
+        supportAssets: [{ status: 'skipped' }],
+      };
+    },
+    readMainConfig: () => null,
+    log: (level, _configured, message) => {
+      calls.push(`${level}:${message}`);
     },
   });
 
   assert.equal(handled, true);
-  assert.deepEqual(forwarded, [
-    [
-      '--update',
-      '--update-launcher-path',
-      '/tmp/subminer',
-      '--update-response-path',
-      '/tmp/subminer-update-test/response.json',
-    ],
+  assert.deepEqual(calls, [
+    'direct:/tmp/subminer.app:/tmp/subminer:stable',
+    'info:AppImage update: not-found',
+    'info:Launcher update: updated',
+    'info:Rofi theme update: skipped',
   ]);
-  assert.deepEqual(responses, ['/tmp/subminer-update-test/response.json']);
 });
 
 test('stats command launches attached app command with response path', async () => {

launcher/commands/update-command.test.ts

@@ -0,0 +1,140 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runUpdateCommand } from './update-command';
+import type { LauncherCommandContext } from './context';
+
+function makeContext(overrides: Partial<LauncherCommandContext> = {}): LauncherCommandContext {
+  return {
+    args: {
+      update: true,
+      logLevel: 'warn',
+    } as LauncherCommandContext['args'],
+    scriptPath: '/home/kyle/.local/bin/subminer',
+    scriptName: 'subminer',
+    mpvSocketPath: '/tmp/subminer.sock',
+    pluginRuntimeConfig: {} as LauncherCommandContext['pluginRuntimeConfig'],
+    appPath: '/home/kyle/.local/bin/SubMiner.AppImage',
+    launcherJellyfinConfig: {} as LauncherCommandContext['launcherJellyfinConfig'],
+    processAdapter: {
+      platform: () => 'linux',
+    } as LauncherCommandContext['processAdapter'],
+    ...overrides,
+  };
+}
+
+test('runUpdateCommand updates directly on Linux without launching Electron', async () => {
+  const calls: string[] = [];
+
+  const handled = await runUpdateCommand(makeContext(), {
+    runAppCommandCaptureOutput: () => {
+      throw new Error('unexpected Electron launch');
+    },
+    runDirectReleaseUpdate: async (request) => {
+      calls.push(`direct:${request.appPath}:${request.launcherPath}:${request.channel}`);
+      return {
+        appImage: { status: 'updated' },
+        launcher: { status: 'updated' },
+        supportAssets: [{ status: 'skipped' }],
+      };
+    },
+    readMainConfig: () => ({ updates: { channel: 'prerelease' } }),
+    log: (level, _configured, message) => {
+      calls.push(`${level}:${message}`);
+    },
+  });
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, [
+    'direct:/home/kyle/.local/bin/SubMiner.AppImage:/home/kyle/.local/bin/subminer:prerelease',
+    'info:AppImage update: updated',
+    'info:Launcher update: updated',
+    'info:Rofi theme update: skipped',
+  ]);
+});
+
+test('runUpdateCommand skips Linux asset replacement when release is not newer', async () => {
+  const calls: string[] = [];
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (url: string) => {
+    calls.push(`fetch:${url}`);
+    if (!url.endsWith('/releases')) {
+      throw new Error(`unexpected asset fetch: ${url}`);
+    }
+    return {
+      ok: true,
+      status: 200,
+      json: async () => [
+        {
+          tag_name: 'v0.14.0',
+          prerelease: false,
+          draft: false,
+          assets: [
+            {
+              name: 'SHA256SUMS.txt',
+              browser_download_url: 'https://example.test/SHA256SUMS.txt',
+            },
+            {
+              name: 'SubMiner.AppImage',
+              browser_download_url: 'https://example.test/SubMiner.AppImage',
+            },
+          ],
+        },
+      ],
+      text: async () => '',
+      arrayBuffer: async () => new ArrayBuffer(0),
+    };
+  }) as typeof fetch;
+
+  try {
+    const handled = await runUpdateCommand(makeContext(), {
+      runAppCommandCaptureOutput: () => {
+        throw new Error('unexpected Electron launch');
+      },
+      readMainConfig: () => null,
+      log: (level, _configured, message) => {
+        calls.push(`${level}:${message}`);
+      },
+    });
+
+    assert.equal(handled, true);
+    assert.deepEqual(calls, [
+      'fetch:https://api.github.com/repos/ksyasuda/SubMiner/releases',
+      'info:AppImage update: up to date',
+      'info:Launcher update: up to date',
+      'info:Rofi theme update: up to date',
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('runUpdateCommand keeps app-mediated update path on non-Linux', async () => {
+  const calls: string[] = [];
+
+  const handled = await runUpdateCommand(
+    makeContext({
+      processAdapter: {
+        platform: () => 'darwin',
+      } as LauncherCommandContext['processAdapter'],
+      appPath: '/Applications/SubMiner.app/Contents/MacOS/SubMiner',
+    }),
+    {
+      createTempDir: () => '/tmp/subminer-update-test',
+      joinPath: (...parts) => parts.join('/'),
+      runAppCommandCaptureOutput: (appPath, appArgs) => {
+        calls.push(`app:${appPath}:${appArgs.join(' ')}`);
+        return { status: 0, stdout: '', stderr: '' };
+      },
+      waitForUpdateResponse: async () => ({ ok: true, status: 'up-to-date' }),
+      removeDir: (targetPath) => {
+        calls.push(`remove:${targetPath}`);
+      },
+    },
+  );
+
+  assert.equal(handled, true);
+  assert.deepEqual(calls, [
+    'app:/Applications/SubMiner.app/Contents/MacOS/SubMiner:--update --update-launcher-path /home/kyle/.local/bin/subminer --update-response-path /tmp/subminer-update-test/response.json',
+    'remove:/tmp/subminer-update-test',
+  ]);
+});

launcher/commands/update-command.ts

@@ -1,10 +1,27 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import packageJson from '../../package.json';
 import { runAppCommandCaptureOutput } from '../mpv.js';
+import { log as launcherLog } from '../log.js';
 import { nowMs } from '../time.js';
 import { sleep } from '../util.js';
 import type { LauncherCommandContext } from './context.js';
+import { readLauncherMainConfigObject } from '../config/shared-config-reader.js';
+import type { UpdateChannel } from '../../src/types/config.js';
+import { updateAppImageFromRelease } from '../../src/main/runtime/update/appimage-updater.js';
+import { updateLauncherFromRelease } from '../../src/main/runtime/update/launcher-updater.js';
+import {
+  compareSemverLike,
+  fetchLatestStableRelease,
+  fetchReleaseAssetBuffer,
+  fetchReleaseAssetText,
+  findReleaseAsset,
+  parseReleaseVersion,
+  parseSha256Sums,
+  type FetchLike,
+} from '../../src/main/runtime/update/release-assets.js';
+import { updateSupportAssetsFromRelease } from '../../src/main/runtime/update/support-assets.js';
 
 type UpdateCommandResponse = {
   ok: boolean;
@@ -13,6 +30,18 @@ type UpdateCommandResponse = {
   error?: string;
 };
 
+type DirectReleaseUpdateRequest = {
+  appPath: string;
+  launcherPath: string;
+  channel: UpdateChannel;
+};
+
+type DirectReleaseUpdateResult = {
+  appImage: { status: string; command?: string; message?: string };
+  launcher: { status: string; command?: string; message?: string };
+  supportAssets: Array<{ status: string; command?: string; message?: string }>;
+};
+
 type UpdateCommandDeps = {
   createTempDir: (prefix: string) => string;
   joinPath: (...parts: string[]) => string;
@@ -22,9 +51,95 @@ type UpdateCommandDeps = {
   ) => { status: number; stdout: string; stderr: string; error?: Error };
   waitForUpdateResponse: (responsePath: string) => Promise<UpdateCommandResponse>;
   removeDir: (targetPath: string) => void;
+  runDirectReleaseUpdate: (
+    request: DirectReleaseUpdateRequest,
+  ) => Promise<DirectReleaseUpdateResult>;
+  readMainConfig: () => Record<string, unknown> | null;
+  log: typeof launcherLog;
 };
 
 const UPDATE_RESPONSE_TIMEOUT_MS = 10 * 60 * 1000;
+const CURRENT_VERSION = packageJson.version;
+
+function getFetchForLauncherUpdater(): FetchLike {
+  return globalThis.fetch.bind(globalThis) as FetchLike;
+}
+
+async function runDirectReleaseUpdate(
+  request: DirectReleaseUpdateRequest,
+): Promise<DirectReleaseUpdateResult> {
+  const fetchForUpdater = getFetchForLauncherUpdater();
+  const release = await fetchLatestStableRelease({
+    fetch: fetchForUpdater,
+    channel: request.channel,
+  });
+  const releaseVersion = parseReleaseVersion(release);
+  if (releaseVersion && compareSemverLike(releaseVersion, CURRENT_VERSION) <= 0) {
+    return {
+      appImage: { status: 'up-to-date' },
+      launcher: { status: 'up-to-date' },
+      supportAssets: [{ status: 'up-to-date' }],
+    };
+  }
+
+  const sumsAsset = release ? findReleaseAsset(release, 'SHA256SUMS.txt') : null;
+  const sha256Sums =
+    sumsAsset && release
+      ? parseSha256Sums(
+          await fetchReleaseAssetText(fetchForUpdater, sumsAsset.browser_download_url),
+        )
+      : new Map<string, string>();
+  const downloadAsset = (url: string) => fetchReleaseAssetBuffer(fetchForUpdater, url);
+
+  const [appImage, launcher, supportAssets] = await Promise.all([
+    updateAppImageFromRelease({
+      release,
+      sha256Sums,
+      appImagePath: request.appPath,
+      downloadAsset,
+    }),
+    updateLauncherFromRelease({
+      release,
+      sha256Sums,
+      launcherPath: request.launcherPath,
+      downloadAsset,
+    }),
+    updateSupportAssetsFromRelease({
+      release,
+      sha256Sums,
+      downloadAsset,
+    }),
+  ]);
+
+  return { appImage, launcher, supportAssets };
+}
+
+function readUpdateChannel(root: Record<string, unknown> | null): UpdateChannel {
+  const updates =
+    root?.updates && typeof root.updates === 'object' && !Array.isArray(root.updates)
+      ? (root.updates as Record<string, unknown>)
+      : null;
+  return updates?.channel === 'prerelease' ? 'prerelease' : 'stable';
+}
+
+function logUpdateResult(
+  label: string,
+  result: { status: string; command?: string; message?: string },
+  configuredLogLevel: NonNullable<LauncherCommandContext['args']['logLevel']>,
+  deps: Pick<UpdateCommandDeps, 'log'>,
+): void {
+  const displayStatus = result.status === 'up-to-date' ? 'up to date' : result.status;
+  deps.log('info', configuredLogLevel, `${label} update: ${displayStatus}`);
+  if (result.command) {
+    deps.log(
+      'warn',
+      configuredLogLevel,
+      `${label} update requires manual command: ${result.command}`,
+    );
+  } else if (result.message) {
+    deps.log('warn', configuredLogLevel, `${label} update note: ${result.message}`);
+  }
+}
 
 const defaultDeps: UpdateCommandDeps = {
   createTempDir: (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix)),
@@ -47,6 +162,9 @@ const defaultDeps: UpdateCommandDeps = {
   removeDir: (targetPath) => {
     fs.rmSync(targetPath, { recursive: true, force: true });
   },
+  runDirectReleaseUpdate,
+  readMainConfig: readLauncherMainConfigObject,
+  log: launcherLog,
 };
 
 export async function runUpdateCommand(
@@ -59,6 +177,21 @@ export async function runUpdateCommand(
     return false;
   }
 
+  if (context.processAdapter.platform() === 'linux') {
+    const result = await resolvedDeps.runDirectReleaseUpdate({
+      appPath,
+      launcherPath: scriptPath,
+      channel: readUpdateChannel(resolvedDeps.readMainConfig()),
+    });
+    const logLevel = args.logLevel ?? 'warn';
+    logUpdateResult('AppImage', result.appImage, logLevel, resolvedDeps);
+    logUpdateResult('Launcher', result.launcher, logLevel, resolvedDeps);
+    for (const supportResult of result.supportAssets) {
+      logUpdateResult('Rofi theme', supportResult, logLevel, resolvedDeps);
+    }
+    return true;
+  }
+
   const tempDir = resolvedDeps.createTempDir('subminer-update-');
   const responsePath = resolvedDeps.joinPath(tempDir, 'response.json');
 

package.json

@@ -2,7 +2,7 @@
   "name": "subminer",
   "productName": "SubMiner",
   "desktopName": "SubMiner.desktop",
-  "version": "0.14.0",
+  "version": "0.15.0-beta.3",
   "description": "All-in-one sentence mining overlay with AnkiConnect and dictionary integration",
   "packageManager": "bun@1.3.5",
   "main": "dist/main-entry.js",
@@ -15,7 +15,7 @@
     "test-yomitan-parser:electron": "bun run build:yomitan && bun build scripts/test-yomitan-parser.ts --format=cjs --target=node --outfile dist/scripts/test-yomitan-parser.js --external electron && env -u ELECTRON_RUN_AS_NODE electron dist/scripts/test-yomitan-parser.js",
     "build:yomitan": "bun scripts/build-yomitan.mjs",
     "build:assets": "bun scripts/prepare-build-assets.mjs",
-    "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --outfile=dist/launcher/subminer",
+    "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --banner='#!/usr/bin/env bun' --outfile=dist/launcher/subminer",
     "build:stats": "cd stats && bun run build",
     "dev:stats": "cd stats && bun run dev",
     "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:launcher && bun run build:assets",
@@ -47,8 +47,8 @@
     "test:config:smoke:dist": "bun test dist/config/path-resolution.test.js",
     "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
-    "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
-    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts stats/src/styles/globals.test.ts",
+    "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
+    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts stats/src/styles/globals.test.ts",
     "test:core:dist": "bun test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
     "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
     "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
@@ -70,7 +70,7 @@
     "test:launcher": "bun run test:launcher:src",
     "test:core": "bun run test:core:src",
     "test:subtitle": "bun run test:subtitle:src",
-    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/card-creation-manual-update.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/prerelease-workflow.test.ts src/ci-workflow.test.ts scripts/build-changelog.test.ts scripts/electron-builder-after-pack.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
+    "test:fast": "bun run test:config:src && bun run test:core:src && bun run test:docs:kb && bun test src/main-entry-runtime.test.ts src/anki-integration.test.ts src/anki-integration/card-creation-manual-update.test.ts src/anki-integration/anki-connect-proxy.test.ts src/anki-integration/field-grouping-workflow.test.ts src/anki-integration/field-grouping.test.ts src/anki-integration/field-grouping-merge.test.ts src/release-workflow.test.ts src/prerelease-workflow.test.ts src/ci-workflow.test.ts scripts/build-changelog.test.ts scripts/electron-builder-after-pack.test.ts scripts/get-mpv-window-macos.test.ts scripts/mkv-to-readme-video.test.ts scripts/run-coverage-lane.test.ts scripts/update-aur-package.test.ts && bun test src/core/services/immersion-tracker/__tests__/query.test.ts src/core/services/immersion-tracker/__tests__/query-split-modules.test.ts && bun run tsc && bun test dist/main/runtime/registry.test.js",
     "generate:config-example": "bun run src/generate-config-example.ts",
     "verify:config-example": "bun run src/verify-config-example.ts",
     "start": "bun run build && electron . --start",

release/prerelease-notes.md

@@ -0,0 +1,44 @@
+> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.
+
+## Highlights
+### Added
+
+**Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
+
+**First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
+
+### Fixed
+
+**macOS Overlay:** Significantly improved overlay focus and stability — the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is also fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
+
+**Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
+
+**Controller:** Controller config and debug shortcuts now stay closed while controller support is disabled, with a notice to enable `controller.enabled`. Learn mode can be entered from the edit pencil or binding badge, remaps are saved per controller profile, and individual bindings can be reset to their defaults.
+
+**AniList Progress:** Progress threshold checks now use fresh playback position data, so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
+
+**Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
+
+**Updater — Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists.
+
+**Updater — macOS:** Update dialogs now come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native updater path without triggering premature Squirrel install checks.
+
+**Setup — macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, returning control to the terminal.
+
+**Launcher — Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
+
+**Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
+
+**Build — Linux Install:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
+
+## Installation
+
+See the README and docs/installation guide for full setup steps.
+
+## Assets
+
+- Linux: `SubMiner.AppImage`
+- macOS: `SubMiner-*.dmg` and `SubMiner-*.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`.

release/release-notes.md

@@ -1,50 +0,0 @@
-## Highlights
-### Added
-
-- **Character Dictionary:** Added AniList-based selection to resolve character dictionary mismatches, with series-scoped overrides that replace stale entries. Available via `subminer dictionary --candidates` / `--select` and a default `Ctrl+Alt+A` in-app shortcut.
-- **Subtitle Bar Toggle:** Added a `V` shortcut and mpv binding to toggle the primary subtitle bar independently of mpv's native subtitle display.
-- **Texthooker:** Added `subminer texthooker -o` and a tray menu item to open the local texthooker page in the default browser.
-
-### Changed
-
-- **mpv Plugin Setup:** Managed launches now inject the bundled plugin automatically. The setup flow can trash detected legacy global plugin files before launch, and legacy global install entrypoints have been removed so regular mpv playback is unaffected.
-- **Tray Menu:** Replaced "Open Overlay" with "Open Help," which opens the session help modal.
-- **Stats Exclusions:** Vocabulary exclusions now persist in the immersion database and migrate existing browser-local exclusions on first load.
-- **Config Defaults:** Disabled texthooker startup, subtitle, and annotation websocket servers by default. Fresh installs now use a Japanese font stack, transparent subtitle backgrounds, stronger text shadows, and teal N4/fourth-band coloring for primary subtitles. Yomitan popup auto-pause remains enabled.
-- **Config Example:** The generated example config now lists every built-in keybinding default.
-
-### Fixed
-
-- **Subtitle Annotations — Grammar Filtering:** Suppressed N+1, JLPT, frequency, and name styling on grammar-only tokens: standalone interjections (`あ`, katakana variants), kana grammar helpers (`ことに`), auxiliary inflection fragments (`れる`, `れた`), polite copula tails (`です`, `じゃないですか`), standalone particles matched by known-word decks, and existence verbs (`ある`/`有る`). Known-word highlighting is preserved where applicable.
-- **Subtitle Annotations — Color Priority:** Fixed token color priority so typography settings are preserved, JLPT colors no longer override higher-priority known-word or frequency colors, JLPT underlines persist at their correct color after dictionary lookups and when a token also carries known-word or frequency annotations, and frequency highlighting works correctly for ordinal prefix-noun tokens like `第二`.
-- **Subtitle Annotations — Other:** Stopped kana-only tokens from being selected as N+1 targets; preserved Yomitan compound tokens so known component words no longer color a larger unknown word green; kept annotation prefetch running after immediate cache-hit renders; added a brightness lift for annotated token hover states when hover backgrounds are transparent; accepted `subtitleStyle.hoverBackground` as an alias for `subtitleStyle.hoverTokenBackgroundColor`; refreshed the current subtitle after successful card mining so newly known words recolor immediately.
-- **Subtitle Bar:** Changed `v` to cycle the primary subtitle bar through visible, hover, and hidden modes with OSD feedback. Added `subtitleStyle.primaryDefaultMode` to set the startup visibility default independently from secondary subtitles.
-- **Tokenizer:** Now uses Yomitan `wordClasses` metadata for part-of-speech filtering, and backfills blank MeCab POS fields during parser enrichment.
-- **Overlay (Linux):** Fixed multi-line subtitle copy timing out after the prompt; follow-up number-row digits are now accepted for multi-line mining even when the original shortcut modifiers are still held.
-- **Overlay (Hyprland):** Fixed fullscreen transitions so overlay geometry refreshes on mpv fullscreen changes, topmost stacking is reasserted, and hover pause works correctly after resize/toggle cycles. Overlay windows now align precisely to mpv bounds with floating decoration disabled; the stats overlay is opaque to prevent mpv bleed-through at the top edge; overlay windows no longer pin across workspaces.
-- **Overlay (macOS):** Kept the overlay visible and interactive during transient tracker refreshes while mpv is the active tracked window, and kept it behind unrelated foreground windows while remaining above mpv.
-- **Overlay:** Keyboard-only Yomitan popup shortcuts now take precedence over overlay keybindings like `j`; the browser focus outline is hidden so focused overlays no longer show a yellow/orange viewport border.
-- **Default Keybindings:** Fixed replay/next subtitle keybindings — session help moved to `Ctrl/Cmd+/`, freeing `Ctrl+Shift+H` and `Ctrl+Shift+L` for subtitle playback controls. `Ctrl+Shift+L` now correctly reaches play-next-subtitle, and play-next resumes from a paused state before pausing again at the subtitle end.
-- **Anki:** Manual clipboard subtitle updates preserve existing word audio while replacing sentence audio, animated-image media, and expression fields — even when audio overwrite is configured off.
-- **AniList:** Post-watch progress checks now run on time-position updates using the fresh mpv position; manual mark-watched forces a progress sync; missing episode metadata is filled from the filename parser. Duplicate writes during concurrent checks are prevented, and manual watched marks are preserved when sync fails.
-- **AniList (Linux):** Retried safeStorage availability after transient keyring failures so tokens can load and save once the keyring becomes available. Prevented config reload from opening the setup window during playback when token storage cannot be resolved, and stopped the setup flow from reporting success when token persistence fails.
-- **mpv:** Stopped mpv from holding SubMiner subprocesses during shutdown, preventing desktop crash notifications on video close. Kept the overlay alive across same-media buffering reloads to avoid duplicate startup gates and AniSkip lookups; playlist navigation now reuses the running overlay without repeating the pause-until-ready warmup gate.
-- **Launcher:** Managed playback now exits the background SubMiner app when the video closes; explicit background launches remain persistent.
-- **Stats:** Background mode routes through the isolated stats daemon; app startup defers to an already-running daemon instead of failing when the port is already in use. Fixed recent session detail pages showing "Media not found" before lifetime media summaries are available.
-- **Jellyfin:** Improved setup with recent server selection and inline authentication feedback. Added a tray toggle for runtime-only cast discovery.
-
-### Docs
-
-- Improved the docs homepage with canonical URLs and a cleaner sitemap.
-
-## Installation
-
-See the README and docs/installation guide for full setup steps.
-
-## Assets
-
-- Linux: `SubMiner.AppImage`
-- macOS: `SubMiner-*.dmg` and `SubMiner-*.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.test.ts

@@ -509,6 +509,72 @@ test('writePrereleaseNotesForVersion writes cumulative beta notes without mutati
   }
 });
 
+test('writePrereleaseNotesForVersion reuses existing prerelease notes when adding new fragments', async () => {
+  const { writePrereleaseNotesForVersion } = await loadModule();
+  const workspace = createWorkspace('prerelease-reuse-existing-notes');
+  const projectRoot = path.join(workspace, 'SubMiner');
+  const existingNotes = [
+    '> This is a prerelease build for testing. Stable changelog and docs-site updates remain pending until the final stable release.',
+    '',
+    '## Highlights',
+    '### Added',
+    '- Overlay: Previous beta entry.',
+    '',
+    '## Installation',
+    '',
+    'See the README and docs/installation guide for full setup steps.',
+    '',
+    '## Assets',
+    '',
+    '- Linux: `SubMiner.AppImage`',
+    '',
+  ].join('\n');
+
+  fs.mkdirSync(path.join(projectRoot, 'changes'), { recursive: true });
+  fs.mkdirSync(path.join(projectRoot, 'release'), { recursive: true });
+  fs.writeFileSync(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'subminer', version: '0.11.3-beta.2' }, null, 2),
+    'utf8',
+  );
+  fs.writeFileSync(path.join(projectRoot, 'release', 'prerelease-notes.md'), existingNotes, 'utf8');
+  fs.writeFileSync(
+    path.join(projectRoot, 'changes', '001.md'),
+    ['type: fixed', 'area: launcher', '', '- Fixed launcher prerelease packaging.'].join('\n'),
+    'utf8',
+  );
+
+  try {
+    const stub = recordingRunClaude((input) => {
+      if (!input.includes('Overlay: Previous beta entry.')) {
+        return '### Fixed\n- Launcher: Added only the latest fix.';
+      }
+      return [
+        '### Added',
+        '- Overlay: Previous beta entry.',
+        '',
+        '### Fixed',
+        '- Launcher: Added only the latest fix.',
+      ].join('\n');
+    });
+
+    const outputPath = writePrereleaseNotesForVersion({
+      cwd: projectRoot,
+      version: '0.11.3-beta.2',
+      deps: { runClaude: stub.runClaude },
+    });
+
+    assert.equal(stub.calls.length, 1, 'prerelease should issue exactly one Claude call');
+    assert.match(stub.calls[0]!.input, /EXISTING PRERELEASE NOTES/);
+
+    const prereleaseNotes = fs.readFileSync(outputPath, 'utf8');
+    assert.match(prereleaseNotes, /- Overlay: Previous beta entry\./);
+    assert.match(prereleaseNotes, /- Launcher: Added only the latest fix\./);
+  } finally {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  }
+});
+
 test('writePrereleaseNotesForVersion supports rc prereleases', async () => {
   const { writePrereleaseNotesForVersion } = await loadModule();
   const workspace = createWorkspace('prerelease-rc-notes');

scripts/build-changelog.ts

@@ -290,6 +290,7 @@ function serializeFragmentsForPrompt(
   mode: PolishMode,
   version: string,
   date?: string,
+  existingReleaseNotes?: string,
 ): string {
   const header: string[] = [`MODE: ${mode}`, `VERSION: ${version}`];
   if (date) {
@@ -307,7 +308,11 @@ function serializeFragmentsForPrompt(
     ].join('\n');
   });
 
-  return [...header, '', ...fragmentBlocks].join('\n\n');
+  const existingNotesBlock = existingReleaseNotes?.trim()
+    ? ['EXISTING PRERELEASE NOTES', existingReleaseNotes.trim()]
+    : [];
+
+  return [...header, '', ...existingNotesBlock, '', ...fragmentBlocks].join('\n\n');
 }
 
 function validatePolishedOutput(
@@ -340,10 +345,11 @@ function polishFragmentsWithClaude(
     mode: PolishMode;
     version: string;
     date?: string;
+    existingReleaseNotes?: string;
     deps?: ChangelogFsDeps;
   },
 ): string {
-  const { mode, version, date } = options;
+  const { mode, version, date, existingReleaseNotes } = options;
   const runClaude = options.deps?.runClaude ?? defaultRunClaude;
 
   const filtered =
@@ -361,8 +367,18 @@ function polishFragmentsWithClaude(
     );
   }
 
+  const reuseInstructions = existingReleaseNotes?.trim()
+    ? [
+        '## Existing Prerelease Notes',
+        '',
+        'The input includes EXISTING PRERELEASE NOTES before the fragment list. Reuse those highlight bullets as the baseline, preserve their meaning and wording where possible, then merge in only new or changed fragment material. Deduplicate instead of restating existing bullets. Output only the final highlights body using the section headings above; do not include the prerelease disclaimer, Installation, or Assets sections.',
+        '',
+      ].join('\n')
+    : '';
   const prompt =
-    POLISH_PROMPT_INSTRUCTIONS + serializeFragmentsForPrompt(filtered, mode, version, date);
+    POLISH_PROMPT_INSTRUCTIONS +
+    reuseInstructions +
+    serializeFragmentsForPrompt(filtered, mode, version, date, existingReleaseNotes);
   const output = runClaude(prompt, CLAUDE_CLI_ARGS);
   return validatePolishedOutput(output, mode, hasInternalFragments);
 }
@@ -780,6 +796,8 @@ export function writePrereleaseNotesForVersion(options?: ChangelogOptions): stri
   verifyRequestedVersionMatchesPackageVersion(options ?? {});
 
   const cwd = options?.cwd ?? process.cwd();
+  const existsSync = options?.deps?.existsSync ?? fs.existsSync;
+  const readFileSync = options?.deps?.readFileSync ?? fs.readFileSync;
   const version = resolveVersion(options ?? {});
   if (!isSupportedPrereleaseVersion(version)) {
     throw new Error(
@@ -792,9 +810,14 @@ export function writePrereleaseNotesForVersion(options?: ChangelogOptions): stri
     throw new Error('No changelog fragments found in changes/.');
   }
 
+  const prereleaseNotesPath = path.join(cwd, PRERELEASE_NOTES_PATH);
+  const existingReleaseNotes = existsSync(prereleaseNotesPath)
+    ? readFileSync(prereleaseNotesPath, 'utf8')
+    : undefined;
   const changes = polishFragmentsWithClaude(fragments, {
     mode: 'release-notes',
     version,
+    existingReleaseNotes,
     deps: options?.deps,
   });
   return writeReleaseNotesFile(cwd, changes, options?.deps, {

scripts/get-mpv-window-macos.swift

@@ -7,7 +7,7 @@
 //  It works with both bundled and unbundled mpv installations.
 //
 //  Usage: swift get-mpv-window-macos.swift
-//  Output: "x,y,width,height" or "not-found"
+//  Output: "x,y,width,height,focused", "minimized", "active", "inactive", or "not-found"
 //
 
 import Cocoa
@@ -25,6 +25,18 @@ private struct WindowState {
     let focused: Bool
 }
 
+private struct FrontmostApplicationState {
+    let pid: pid_t
+    let isMpv: Bool
+}
+
+private enum WindowLookupResult {
+    case visible(WindowState)
+    case minimized
+    case active
+    case inactive
+}
+
 private let targetMpvSocketPath: String? = {
     guard CommandLine.arguments.count > 1 else {
         return nil
@@ -141,11 +153,44 @@ private func geometryFromAXWindow(_ axWindow: AXUIElement) -> WindowGeometry? {
     return geometry
 }
 
-private func frontmostApplicationPid() -> pid_t? {
-    NSWorkspace.shared.frontmostApplication?.processIdentifier
+private func frontmostApplicationState() -> FrontmostApplicationState? {
+    guard let app = NSWorkspace.shared.frontmostApplication else {
+        return nil
+    }
+
+    return FrontmostApplicationState(
+        pid: app.processIdentifier,
+        isMpv: app.localizedName.map(normalizedMpvName) ?? false
+    )
 }
 
-private func windowStateFromAccessibilityAPI() -> WindowState? {
+private func isFocusedMpvWindow(ownerPid: pid_t, frontmost: FrontmostApplicationState?) -> Bool {
+    guard let frontmost = frontmost else {
+        return false
+    }
+
+    if frontmost.pid == ownerPid {
+        return true
+    }
+
+    return frontmost.isMpv && windowHasTargetSocket(ownerPid)
+}
+
+private func isFrontmostTargetMpv(_ frontmost: FrontmostApplicationState?) -> Bool {
+    guard let frontmost = frontmost, frontmost.isMpv else {
+        return false
+    }
+
+    if windowHasTargetSocket(frontmost.pid) {
+        return true
+    }
+
+    // When macOS says mpv is frontmost but geometry APIs miss, keep the
+    // overlay stable even if ps cannot expose the socket argument.
+    return targetMpvSocketPath != nil
+}
+
+private func windowStateFromAccessibilityAPI() -> WindowLookupResult? {
     let runningApps = NSWorkspace.shared.runningApplications.filter { app in
         guard let name = app.localizedName else {
             return false
@@ -153,7 +198,8 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
         return normalizedMpvName(name)
     }
 
-    let frontmostPid = frontmostApplicationPid()
+    let frontmost = frontmostApplicationState()
+    var foundMinimizedTargetWindow = false
 
     for app in runningApps {
         let appElement = AXUIElementCreateApplication(app.processIdentifier)
@@ -168,14 +214,12 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
         }
 
         for window in windows {
-            var minimizedRef: CFTypeRef?
-            let minimizedStatus = AXUIElementCopyAttributeValue(window, kAXMinimizedAttribute as CFString, &minimizedRef)
-            if minimizedStatus == .success, let minimized = minimizedRef as? Bool, minimized {
+            var windowPid: pid_t = 0
+            if AXUIElementGetPid(window, &windowPid) != .success {
                 continue
             }
 
-            var windowPid: pid_t = 0
-            if AXUIElementGetPid(window, &windowPid) != .success {
+            if windowPid != app.processIdentifier {
                 continue
             }
 
@@ -183,15 +227,28 @@ private func windowStateFromAccessibilityAPI() -> WindowState? {
                 continue
             }
 
+            var minimizedRef: CFTypeRef?
+            let minimizedStatus = AXUIElementCopyAttributeValue(window, kAXMinimizedAttribute as CFString, &minimizedRef)
+            if minimizedStatus == .success, let minimized = minimizedRef as? Bool, minimized {
+                foundMinimizedTargetWindow = true
+                continue
+            }
+
             if let geometry = geometryFromAXWindow(window) {
-                return WindowState(
-                    geometry: geometry,
-                    focused: frontmostPid == windowPid
+                return .visible(
+                    WindowState(
+                        geometry: geometry,
+                        focused: isFocusedMpvWindow(ownerPid: windowPid, frontmost: frontmost)
+                    )
                 )
             }
         }
     }
 
+    if foundMinimizedTargetWindow {
+        return .minimized
+    }
+
     return nil
 }
 
@@ -200,7 +257,7 @@ private func windowStateFromCoreGraphics() -> WindowState? {
     // Use on-screen layer-0 windows to avoid off-screen helpers/shadows.
     let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
     let windowList = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] ?? []
-    let frontmostPid = frontmostApplicationPid()
+    let frontmost = frontmostApplicationState()
 
     for window in windowList {
         guard let ownerName = window[kCGWindowOwnerName as String] as? String,
@@ -243,17 +300,43 @@ private func windowStateFromCoreGraphics() -> WindowState? {
 
         return WindowState(
             geometry: geometry,
-            focused: frontmostPid == ownerPid
+            focused: isFocusedMpvWindow(ownerPid: ownerPid, frontmost: frontmost)
         )
     }
 
     return nil
 }
 
-if let window = windowStateFromAccessibilityAPI() ?? windowStateFromCoreGraphics() {
-    print(
-        "\(window.geometry.x),\(window.geometry.y),\(window.geometry.width),\(window.geometry.height),\(window.focused ? 1 : 0)"
-    )
+private let lookupResult: WindowLookupResult? = {
+    if let axResult = windowStateFromAccessibilityAPI() {
+        return axResult
+    }
+    if let cgWindow = windowStateFromCoreGraphics() {
+        return .visible(cgWindow)
+    }
+    let frontmost = frontmostApplicationState()
+    if isFrontmostTargetMpv(frontmost) {
+        return .active
+    }
+    if frontmost != nil {
+        return .inactive
+    }
+    return nil
+}()
+
+if let result = lookupResult {
+    switch result {
+    case .visible(let window):
+        print(
+            "\(window.geometry.x),\(window.geometry.y),\(window.geometry.width),\(window.geometry.height),\(window.focused ? 1 : 0)"
+        )
+    case .minimized:
+        print("minimized")
+    case .active:
+        print("active")
+    case .inactive:
+        print("inactive")
+    }
 } else {
     print("not-found")
 }

scripts/get-mpv-window-macos.test.ts

@@ -0,0 +1,94 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+const source = readFileSync('scripts/get-mpv-window-macos.swift', 'utf8');
+
+test('minimized Accessibility windows are validated by PID and socket before reporting minimized', () => {
+  const minimizedAssignmentIndex = source.indexOf('foundMinimizedTargetWindow = true');
+  assert.notEqual(minimizedAssignmentIndex, -1);
+
+  const loopStartIndex = source.lastIndexOf('for window in windows', minimizedAssignmentIndex);
+  assert.notEqual(loopStartIndex, -1);
+
+  const pidExtractionIndex = source.indexOf(
+    'AXUIElementGetPid(window, &windowPid)',
+    loopStartIndex,
+  );
+  const appPidMatchIndex = source.indexOf('windowPid != app.processIdentifier', loopStartIndex);
+  const socketCheckIndex = source.indexOf('if !windowHasTargetSocket(windowPid)', loopStartIndex);
+
+  assert.ok(
+    pidExtractionIndex > loopStartIndex && pidExtractionIndex < minimizedAssignmentIndex,
+    'window PID must be extracted before accepting a minimized window',
+  );
+  assert.ok(
+    appPidMatchIndex > pidExtractionIndex && appPidMatchIndex < minimizedAssignmentIndex,
+    'window PID must match the owning app before accepting a minimized window',
+  );
+  assert.ok(
+    socketCheckIndex > appPidMatchIndex && socketCheckIndex < minimizedAssignmentIndex,
+    'target socket must be validated before accepting a minimized window',
+  );
+});
+
+test('focused mpv window follows the frontmost mpv app signal', () => {
+  const focusHelperIndex = source.indexOf('private func isFocusedMpvWindow');
+  assert.notEqual(focusHelperIndex, -1);
+
+  const nextFunctionIndex = source.indexOf('\nprivate func ', focusHelperIndex + 1);
+  const focusHelperBody = source.slice(focusHelperIndex, nextFunctionIndex);
+
+  assert.ok(
+    focusHelperBody.includes('frontmost.pid == ownerPid'),
+    'matching frontmost PID should mark the mpv window focused',
+  );
+  assert.ok(
+    focusHelperBody.includes('frontmost.isMpv && windowHasTargetSocket(ownerPid)'),
+    'frontmost mpv app should mark the target mpv window focused even when PIDs differ',
+  );
+  assert.ok(
+    source.includes('focused: isFocusedMpvWindow(ownerPid: windowPid, frontmost: frontmost)'),
+    'Accessibility path should use the shared focused mpv helper',
+  );
+  assert.ok(
+    source.includes('focused: isFocusedMpvWindow(ownerPid: ownerPid, frontmost: frontmost)'),
+    'CoreGraphics path should use the shared focused mpv helper',
+  );
+});
+
+test('frontmost mpv app emits active state when geometry lookup misses', () => {
+  assert.ok(
+    /case\s+\.active:/.test(source),
+    'helper should expose an active state without window geometry',
+  );
+  assert.ok(
+    source.includes('if windowHasTargetSocket(frontmost.pid)'),
+    'active state should still accept a matching target socket when available',
+  );
+  assert.ok(
+    source.includes('return targetMpvSocketPath != nil'),
+    'active state should preserve frontmost mpv even if command-line socket detection fails',
+  );
+  assert.ok(
+    source.includes('return .active'),
+    'lookup should preserve active mpv state after geometry lookup misses',
+  );
+  assert.ok(source.includes('print("active")'), 'active state should be printed for the tracker');
+});
+
+test('frontmost non-mpv app emits inactive state when geometry lookup misses', () => {
+  assert.ok(
+    /case\s+\.inactive:/.test(source),
+    'helper should expose an inactive state without window geometry',
+  );
+  assert.ok(
+    source.includes('if frontmost != nil'),
+    'helper should distinguish a known non-mpv frontmost app from an unknown miss',
+  );
+  assert.ok(source.includes('return .inactive'), 'known non-mpv focus should return inactive');
+  assert.ok(
+    source.includes('print("inactive")'),
+    'inactive state should be printed for the tracker',
+  );
+});

src/config/config.test.ts

@@ -1453,6 +1453,104 @@ test('parses descriptor-based controller bindings', () => {
   });
 });
 
+test('parses controller profiles as per-gamepad binding overrides', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "controller": {
+        "buttonIndices": {
+          "buttonSouth": 0,
+          "leftTrigger": 6
+        },
+        "bindings": {
+          "toggleLookup": { "kind": "button", "buttonIndex": 0 },
+          "quitMpv": "leftTrigger"
+        },
+        "profiles": {
+          "8BitDo SN30": {
+            "label": "8BitDo SN30",
+            "bindings": {
+              "toggleLookup": { "kind": "button", "buttonIndex": 11 },
+              "leftStickVertical": { "kind": "axis", "axisIndex": 7, "dpadFallback": "none" }
+            }
+          },
+          "Xbox Wireless Controller": {
+            "buttonIndices": {
+              "leftTrigger": 8
+            },
+            "bindings": {
+              "quitMpv": "leftTrigger"
+            }
+          }
+        }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+  const config = service.getConfig();
+
+  assert.deepEqual(config.controller.profiles['8BitDo SN30']?.bindings.toggleLookup, {
+    kind: 'button',
+    buttonIndex: 11,
+  });
+  assert.deepEqual(config.controller.profiles['8BitDo SN30']?.bindings.closeLookup, {
+    kind: 'button',
+    buttonIndex: 1,
+  });
+  assert.deepEqual(config.controller.profiles['8BitDo SN30']?.bindings.leftStickVertical, {
+    kind: 'axis',
+    axisIndex: 7,
+    dpadFallback: 'none',
+  });
+  assert.deepEqual(config.controller.profiles['Xbox Wireless Controller']?.bindings.quitMpv, {
+    kind: 'button',
+    buttonIndex: 8,
+  });
+  assert.equal(
+    config.controller.profiles['Xbox Wireless Controller']?.buttonIndices.leftTrigger,
+    8,
+  );
+  assert.deepEqual(config.controller.bindings.quitMpv, { kind: 'button', buttonIndex: 6 });
+});
+
+test('rejects reserved controller profile ids from config', () => {
+  const dir = makeTempDir();
+  fs.writeFileSync(
+    path.join(dir, 'config.jsonc'),
+    `{
+      "controller": {
+        "profiles": {
+          "__proto__": { "label": "polluted" },
+          "constructor": { "label": "ctor" },
+          "prototype": { "label": "proto" },
+          "pad-1": { "label": "Pad 1" }
+        }
+      }
+    }`,
+    'utf-8',
+  );
+
+  const service = new ConfigService(dir);
+  const config = service.getConfig();
+  const warnings = service.getWarnings();
+
+  assert.equal(Object.hasOwn(config.controller.profiles, '__proto__'), false);
+  assert.equal(Object.hasOwn(config.controller.profiles, 'constructor'), false);
+  assert.equal(Object.hasOwn(config.controller.profiles, 'prototype'), false);
+  assert.equal(config.controller.profiles['pad-1']?.label, 'Pad 1');
+  assert.equal(
+    warnings.some((warning) => warning.path === 'controller.profiles.constructor'),
+    true,
+  );
+  assert.equal(
+    warnings.some((warning) => warning.path === 'controller.profiles.prototype'),
+    true,
+  );
+});
+
 test('controller descriptor config rejects malformed binding objects', () => {
   const dir = makeTempDir();
   fs.writeFileSync(

src/config/definitions/defaults-core.ts

@@ -74,6 +74,7 @@ export const CORE_DEFAULT_CONFIG: Pick<
       rightStickHorizontal: { kind: 'axis', axisIndex: 3, dpadFallback: 'none' },
       rightStickVertical: { kind: 'axis', axisIndex: 4, dpadFallback: 'none' },
     },
+    profiles: {},
   },
   shortcuts: {
     toggleVisibleOverlayGlobal: 'Alt+Shift+O',

src/config/definitions/options-core.ts

@@ -239,6 +239,13 @@ export function buildCoreConfigOptionRegistry(
       description:
         'Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.',
     },
+    {
+      path: 'controller.profiles',
+      kind: 'object',
+      defaultValue: defaultConfig.controller.profiles,
+      description:
+        'Per-controller binding and button-index overrides keyed by the controller id reported by the Gamepad API.',
+    },
     ...discreteBindings.flatMap((binding) => [
       {
         path: `controller.bindings.${binding.id}`,

src/config/resolve/controller.ts

@@ -0,0 +1,423 @@
+import type {
+  ControllerAxisBinding,
+  ControllerAxisDirection,
+  ControllerButtonBinding,
+  ControllerButtonIndicesConfig,
+  ControllerDpadFallback,
+  ResolvedControllerAxisBinding,
+  ResolvedControllerBindingsConfig,
+  ResolvedControllerDiscreteBinding,
+} from '../../types/runtime';
+import { ResolveContext } from './context';
+import { asBoolean, asNumber, asString, isObject } from './shared';
+
+const CONTROLLER_BUTTON_BINDINGS = [
+  'none',
+  'select',
+  'buttonSouth',
+  'buttonEast',
+  'buttonNorth',
+  'buttonWest',
+  'leftShoulder',
+  'rightShoulder',
+  'leftStickPress',
+  'rightStickPress',
+  'leftTrigger',
+  'rightTrigger',
+] as const;
+
+const CONTROLLER_AXIS_BINDINGS = [
+  'leftStickX',
+  'leftStickY',
+  'rightStickX',
+  'rightStickY',
+] as const;
+
+const CONTROLLER_AXIS_INDEX_BY_BINDING: Record<ControllerAxisBinding, number> = {
+  leftStickX: 0,
+  leftStickY: 1,
+  rightStickX: 3,
+  rightStickY: 4,
+};
+
+const CONTROLLER_BUTTON_INDEX_KEY_BY_BINDING: Record<
+  Exclude<ControllerButtonBinding, 'none'>,
+  keyof Required<ControllerButtonIndicesConfig>
+> = {
+  select: 'select',
+  buttonSouth: 'buttonSouth',
+  buttonEast: 'buttonEast',
+  buttonNorth: 'buttonNorth',
+  buttonWest: 'buttonWest',
+  leftShoulder: 'leftShoulder',
+  rightShoulder: 'rightShoulder',
+  leftStickPress: 'leftStickPress',
+  rightStickPress: 'rightStickPress',
+  leftTrigger: 'leftTrigger',
+  rightTrigger: 'rightTrigger',
+};
+
+const CONTROLLER_AXIS_FALLBACK_BY_SLOT = {
+  leftStickHorizontal: 'horizontal',
+  leftStickVertical: 'vertical',
+  rightStickHorizontal: 'none',
+  rightStickVertical: 'none',
+} as const satisfies Record<string, ControllerDpadFallback>;
+
+const CONTROLLER_BUTTON_INDEX_KEYS = [
+  'select',
+  'buttonSouth',
+  'buttonEast',
+  'buttonNorth',
+  'buttonWest',
+  'leftShoulder',
+  'rightShoulder',
+  'leftStickPress',
+  'rightStickPress',
+  'leftTrigger',
+  'rightTrigger',
+] as const;
+
+const CONTROLLER_DISCRETE_BINDING_KEYS = [
+  'toggleLookup',
+  'closeLookup',
+  'toggleKeyboardOnlyMode',
+  'mineCard',
+  'quitMpv',
+  'previousAudio',
+  'nextAudio',
+  'playCurrentAudio',
+  'toggleMpvPause',
+] as const;
+
+const CONTROLLER_AXIS_BINDING_KEYS = [
+  'leftStickHorizontal',
+  'leftStickVertical',
+  'rightStickHorizontal',
+  'rightStickVertical',
+] as const;
+
+const RESERVED_CONTROLLER_PROFILE_IDS = new Set(['__proto__', 'constructor', 'prototype']);
+
+type ControllerBindingsTarget = Required<ResolvedControllerBindingsConfig>;
+type ControllerButtonIndicesTarget = Required<ControllerButtonIndicesConfig>;
+
+function isControllerAxisDirection(value: unknown): value is ControllerAxisDirection {
+  return value === 'negative' || value === 'positive';
+}
+
+function isControllerDpadFallback(value: unknown): value is ControllerDpadFallback {
+  return value === 'none' || value === 'horizontal' || value === 'vertical';
+}
+
+function resolveLegacyDiscreteBinding(
+  value: ControllerButtonBinding,
+  buttonIndices: Required<ControllerButtonIndicesConfig>,
+): ResolvedControllerDiscreteBinding {
+  if (value === 'none') {
+    return { kind: 'none' };
+  }
+  return {
+    kind: 'button',
+    buttonIndex: buttonIndices[CONTROLLER_BUTTON_INDEX_KEY_BY_BINDING[value]],
+  };
+}
+
+function resolveLegacyAxisBinding(
+  value: ControllerAxisBinding,
+  slot: keyof typeof CONTROLLER_AXIS_FALLBACK_BY_SLOT,
+): ResolvedControllerAxisBinding {
+  return {
+    kind: 'axis',
+    axisIndex: CONTROLLER_AXIS_INDEX_BY_BINDING[value],
+    dpadFallback: CONTROLLER_AXIS_FALLBACK_BY_SLOT[slot],
+  };
+}
+
+function parseDiscreteBindingObject(value: unknown): ResolvedControllerDiscreteBinding | null {
+  if (!isObject(value) || typeof value.kind !== 'string') return null;
+  if (value.kind === 'none') {
+    return { kind: 'none' };
+  }
+  if (value.kind === 'button') {
+    return typeof value.buttonIndex === 'number' &&
+      Number.isInteger(value.buttonIndex) &&
+      value.buttonIndex >= 0
+      ? { kind: 'button', buttonIndex: value.buttonIndex }
+      : null;
+  }
+  if (value.kind === 'axis') {
+    return typeof value.axisIndex === 'number' &&
+      Number.isInteger(value.axisIndex) &&
+      value.axisIndex >= 0 &&
+      isControllerAxisDirection(value.direction)
+      ? { kind: 'axis', axisIndex: value.axisIndex, direction: value.direction }
+      : null;
+  }
+  return null;
+}
+
+function parseAxisBindingObject(
+  value: unknown,
+  slot: keyof typeof CONTROLLER_AXIS_FALLBACK_BY_SLOT,
+): ResolvedControllerAxisBinding | null {
+  if (isObject(value) && value.kind === 'none') {
+    return { kind: 'none' };
+  }
+  if (!isObject(value) || value.kind !== 'axis') return null;
+  if (
+    typeof value.axisIndex !== 'number' ||
+    !Number.isInteger(value.axisIndex) ||
+    value.axisIndex < 0
+  ) {
+    return null;
+  }
+  if (value.dpadFallback !== undefined && !isControllerDpadFallback(value.dpadFallback)) {
+    return null;
+  }
+  return {
+    kind: 'axis',
+    axisIndex: value.axisIndex,
+    dpadFallback: value.dpadFallback ?? CONTROLLER_AXIS_FALLBACK_BY_SLOT[slot],
+  };
+}
+
+function applyControllerButtonIndices(
+  source: unknown,
+  target: ControllerButtonIndicesTarget,
+  pathPrefix: string,
+  warn: ResolveContext['warn'],
+): void {
+  if (!isObject(source)) return;
+
+  for (const key of CONTROLLER_BUTTON_INDEX_KEYS) {
+    const value = asNumber(source[key]);
+    if (value !== undefined && value >= 0 && Number.isInteger(value)) {
+      target[key] = value;
+    } else if (source[key] !== undefined) {
+      warn(`${pathPrefix}.${key}`, source[key], target[key], 'Expected non-negative integer.');
+    }
+  }
+}
+
+function applyControllerBindings(
+  source: unknown,
+  target: ControllerBindingsTarget,
+  buttonIndices: ControllerButtonIndicesTarget,
+  pathPrefix: string,
+  warn: ResolveContext['warn'],
+): void {
+  if (!isObject(source)) return;
+
+  for (const key of CONTROLLER_DISCRETE_BINDING_KEYS) {
+    const bindingValue = source[key];
+    const legacyValue = asString(bindingValue);
+    if (
+      legacyValue !== undefined &&
+      CONTROLLER_BUTTON_BINDINGS.includes(
+        legacyValue as (typeof CONTROLLER_BUTTON_BINDINGS)[number],
+      )
+    ) {
+      target[key] = resolveLegacyDiscreteBinding(
+        legacyValue as ControllerButtonBinding,
+        buttonIndices,
+      );
+      continue;
+    }
+    const parsedObject = parseDiscreteBindingObject(bindingValue);
+    if (parsedObject) {
+      target[key] = parsedObject;
+    } else if (bindingValue !== undefined) {
+      warn(
+        `${pathPrefix}.${key}`,
+        bindingValue,
+        target[key],
+        "Expected legacy controller button name or binding object with kind 'none', 'button', or 'axis'.",
+      );
+    }
+  }
+
+  for (const key of CONTROLLER_AXIS_BINDING_KEYS) {
+    const bindingValue = source[key];
+    const legacyValue = asString(bindingValue);
+    if (
+      legacyValue !== undefined &&
+      CONTROLLER_AXIS_BINDINGS.includes(legacyValue as (typeof CONTROLLER_AXIS_BINDINGS)[number])
+    ) {
+      target[key] = resolveLegacyAxisBinding(legacyValue as ControllerAxisBinding, key);
+      continue;
+    }
+    if (legacyValue === 'none') {
+      target[key] = { kind: 'none' };
+      continue;
+    }
+    const parsedObject = parseAxisBindingObject(bindingValue, key);
+    if (parsedObject) {
+      target[key] = parsedObject;
+    } else if (bindingValue !== undefined) {
+      warn(
+        `${pathPrefix}.${key}`,
+        bindingValue,
+        target[key],
+        "Expected legacy controller axis name ('none' allowed) or binding object with kind 'axis'.",
+      );
+    }
+  }
+}
+
+export function applyControllerConfig(context: ResolveContext): void {
+  const { src, resolved, warn } = context;
+  if (!isObject(src.controller)) return;
+
+  const enabled = asBoolean(src.controller.enabled);
+  if (enabled !== undefined) {
+    resolved.controller.enabled = enabled;
+  } else if (src.controller.enabled !== undefined) {
+    warn(
+      'controller.enabled',
+      src.controller.enabled,
+      resolved.controller.enabled,
+      'Expected boolean.',
+    );
+  }
+
+  const preferredGamepadId = asString(src.controller.preferredGamepadId);
+  if (preferredGamepadId !== undefined) {
+    resolved.controller.preferredGamepadId = preferredGamepadId;
+  }
+
+  const preferredGamepadLabel = asString(src.controller.preferredGamepadLabel);
+  if (preferredGamepadLabel !== undefined) {
+    resolved.controller.preferredGamepadLabel = preferredGamepadLabel;
+  }
+
+  const smoothScroll = asBoolean(src.controller.smoothScroll);
+  if (smoothScroll !== undefined) {
+    resolved.controller.smoothScroll = smoothScroll;
+  } else if (src.controller.smoothScroll !== undefined) {
+    warn(
+      'controller.smoothScroll',
+      src.controller.smoothScroll,
+      resolved.controller.smoothScroll,
+      'Expected boolean.',
+    );
+  }
+
+  const triggerInputMode = asString(src.controller.triggerInputMode);
+  if (
+    triggerInputMode === 'auto' ||
+    triggerInputMode === 'digital' ||
+    triggerInputMode === 'analog'
+  ) {
+    resolved.controller.triggerInputMode = triggerInputMode;
+  } else if (src.controller.triggerInputMode !== undefined) {
+    warn(
+      'controller.triggerInputMode',
+      src.controller.triggerInputMode,
+      resolved.controller.triggerInputMode,
+      "Expected 'auto', 'digital', or 'analog'.",
+    );
+  }
+
+  const boundedNumberKeys = [
+    'scrollPixelsPerSecond',
+    'horizontalJumpPixels',
+    'repeatDelayMs',
+    'repeatIntervalMs',
+  ] as const;
+  for (const key of boundedNumberKeys) {
+    const value = asNumber(src.controller[key]);
+    if (value !== undefined && Math.floor(value) > 0) {
+      resolved.controller[key] = Math.floor(value) as (typeof resolved.controller)[typeof key];
+    } else if (src.controller[key] !== undefined) {
+      warn(
+        `controller.${key}`,
+        src.controller[key],
+        resolved.controller[key],
+        'Expected positive number.',
+      );
+    }
+  }
+
+  const deadzoneKeys = ['stickDeadzone', 'triggerDeadzone'] as const;
+  for (const key of deadzoneKeys) {
+    const value = asNumber(src.controller[key]);
+    if (value !== undefined && value >= 0 && value <= 1) {
+      resolved.controller[key] = value as (typeof resolved.controller)[typeof key];
+    } else if (src.controller[key] !== undefined) {
+      warn(
+        `controller.${key}`,
+        src.controller[key],
+        resolved.controller[key],
+        'Expected number between 0 and 1.',
+      );
+    }
+  }
+
+  applyControllerButtonIndices(
+    src.controller.buttonIndices,
+    resolved.controller.buttonIndices,
+    'controller.buttonIndices',
+    warn,
+  );
+  applyControllerBindings(
+    src.controller.bindings,
+    resolved.controller.bindings,
+    resolved.controller.buttonIndices,
+    'controller.bindings',
+    warn,
+  );
+
+  if (isObject(src.controller.profiles)) {
+    for (const [profileId, rawProfile] of Object.entries(src.controller.profiles)) {
+      if (RESERVED_CONTROLLER_PROFILE_IDS.has(profileId)) {
+        warn(
+          `controller.profiles.${profileId}`,
+          rawProfile,
+          undefined,
+          'Reserved profile id is not allowed.',
+        );
+        continue;
+      }
+      if (!isObject(rawProfile)) {
+        warn(
+          `controller.profiles.${profileId}`,
+          rawProfile,
+          undefined,
+          'Expected controller profile object.',
+        );
+        continue;
+      }
+
+      const label = asString(rawProfile.label);
+      if (rawProfile.label !== undefined && label === undefined) {
+        warn(
+          `controller.profiles.${profileId}.label`,
+          rawProfile.label,
+          profileId,
+          'Expected string.',
+        );
+      }
+
+      const profile = {
+        label: label ?? profileId,
+        buttonIndices: structuredClone(resolved.controller.buttonIndices),
+        bindings: structuredClone(resolved.controller.bindings),
+      };
+      applyControllerButtonIndices(
+        rawProfile.buttonIndices,
+        profile.buttonIndices,
+        `controller.profiles.${profileId}.buttonIndices`,
+        warn,
+      );
+      applyControllerBindings(
+        rawProfile.bindings,
+        profile.bindings,
+        profile.buttonIndices,
+        `controller.profiles.${profileId}.bindings`,
+        warn,
+      );
+      resolved.controller.profiles[profileId] = profile;
+    }
+  }
+}

src/config/resolve/core-domains.ts

@@ -1,150 +1,7 @@
-import type {
-  ControllerAxisBinding,
-  ControllerAxisBindingConfig,
-  ControllerAxisDirection,
-  ControllerButtonBinding,
-  ControllerButtonIndicesConfig,
-  ControllerDpadFallback,
-  ControllerDiscreteBindingConfig,
-  ResolvedControllerAxisBinding,
-  ResolvedControllerDiscreteBinding,
-} from '../../types/runtime';
 import { ResolveContext } from './context';
+import { applyControllerConfig } from './controller';
 import { asBoolean, asNumber, asString, isObject } from './shared';
 
-const CONTROLLER_BUTTON_BINDINGS = [
-  'none',
-  'select',
-  'buttonSouth',
-  'buttonEast',
-  'buttonNorth',
-  'buttonWest',
-  'leftShoulder',
-  'rightShoulder',
-  'leftStickPress',
-  'rightStickPress',
-  'leftTrigger',
-  'rightTrigger',
-] as const;
-
-const CONTROLLER_AXIS_BINDINGS = [
-  'leftStickX',
-  'leftStickY',
-  'rightStickX',
-  'rightStickY',
-] as const;
-
-const CONTROLLER_AXIS_INDEX_BY_BINDING: Record<ControllerAxisBinding, number> = {
-  leftStickX: 0,
-  leftStickY: 1,
-  rightStickX: 3,
-  rightStickY: 4,
-};
-
-const CONTROLLER_BUTTON_INDEX_KEY_BY_BINDING: Record<
-  Exclude<ControllerButtonBinding, 'none'>,
-  keyof Required<ControllerButtonIndicesConfig>
-> = {
-  select: 'select',
-  buttonSouth: 'buttonSouth',
-  buttonEast: 'buttonEast',
-  buttonNorth: 'buttonNorth',
-  buttonWest: 'buttonWest',
-  leftShoulder: 'leftShoulder',
-  rightShoulder: 'rightShoulder',
-  leftStickPress: 'leftStickPress',
-  rightStickPress: 'rightStickPress',
-  leftTrigger: 'leftTrigger',
-  rightTrigger: 'rightTrigger',
-};
-
-const CONTROLLER_AXIS_FALLBACK_BY_SLOT = {
-  leftStickHorizontal: 'horizontal',
-  leftStickVertical: 'vertical',
-  rightStickHorizontal: 'none',
-  rightStickVertical: 'none',
-} as const satisfies Record<string, ControllerDpadFallback>;
-
-function isControllerAxisDirection(value: unknown): value is ControllerAxisDirection {
-  return value === 'negative' || value === 'positive';
-}
-
-function isControllerDpadFallback(value: unknown): value is ControllerDpadFallback {
-  return value === 'none' || value === 'horizontal' || value === 'vertical';
-}
-
-function resolveLegacyDiscreteBinding(
-  value: ControllerButtonBinding,
-  buttonIndices: Required<ControllerButtonIndicesConfig>,
-): ResolvedControllerDiscreteBinding {
-  if (value === 'none') {
-    return { kind: 'none' };
-  }
-  return {
-    kind: 'button',
-    buttonIndex: buttonIndices[CONTROLLER_BUTTON_INDEX_KEY_BY_BINDING[value]],
-  };
-}
-
-function resolveLegacyAxisBinding(
-  value: ControllerAxisBinding,
-  slot: keyof typeof CONTROLLER_AXIS_FALLBACK_BY_SLOT,
-): ResolvedControllerAxisBinding {
-  return {
-    kind: 'axis',
-    axisIndex: CONTROLLER_AXIS_INDEX_BY_BINDING[value],
-    dpadFallback: CONTROLLER_AXIS_FALLBACK_BY_SLOT[slot],
-  };
-}
-
-function parseDiscreteBindingObject(value: unknown): ResolvedControllerDiscreteBinding | null {
-  if (!isObject(value) || typeof value.kind !== 'string') return null;
-  if (value.kind === 'none') {
-    return { kind: 'none' };
-  }
-  if (value.kind === 'button') {
-    return typeof value.buttonIndex === 'number' &&
-      Number.isInteger(value.buttonIndex) &&
-      value.buttonIndex >= 0
-      ? { kind: 'button', buttonIndex: value.buttonIndex }
-      : null;
-  }
-  if (value.kind === 'axis') {
-    return typeof value.axisIndex === 'number' &&
-      Number.isInteger(value.axisIndex) &&
-      value.axisIndex >= 0 &&
-      isControllerAxisDirection(value.direction)
-      ? { kind: 'axis', axisIndex: value.axisIndex, direction: value.direction }
-      : null;
-  }
-  return null;
-}
-
-function parseAxisBindingObject(
-  value: unknown,
-  slot: keyof typeof CONTROLLER_AXIS_FALLBACK_BY_SLOT,
-): ResolvedControllerAxisBinding | null {
-  if (isObject(value) && value.kind === 'none') {
-    return { kind: 'none' };
-  }
-  if (!isObject(value) || value.kind !== 'axis') return null;
-  if (
-    typeof value.axisIndex !== 'number' ||
-    !Number.isInteger(value.axisIndex) ||
-    value.axisIndex < 0
-  ) {
-    return null;
-  }
-  if (value.dpadFallback !== undefined && !isControllerDpadFallback(value.dpadFallback)) {
-    return null;
-  }
-  return {
-    kind: 'axis',
-    axisIndex: value.axisIndex,
-    dpadFallback: value.dpadFallback ?? CONTROLLER_AXIS_FALLBACK_BY_SLOT[slot],
-  };
-}
-
 export function applyCoreDomainConfig(context: ResolveContext): void {
   const { src, resolved, warn } = context;
 
@@ -245,203 +102,7 @@ export function applyCoreDomainConfig(context: ResolveContext): void {
     }
   }
 
-  if (isObject(src.controller)) {
-    const enabled = asBoolean(src.controller.enabled);
-    if (enabled !== undefined) {
-      resolved.controller.enabled = enabled;
-    } else if (src.controller.enabled !== undefined) {
-      warn(
-        'controller.enabled',
-        src.controller.enabled,
-        resolved.controller.enabled,
-        'Expected boolean.',
-      );
-    }
-
-    const preferredGamepadId = asString(src.controller.preferredGamepadId);
-    if (preferredGamepadId !== undefined) {
-      resolved.controller.preferredGamepadId = preferredGamepadId;
-    }
-
-    const preferredGamepadLabel = asString(src.controller.preferredGamepadLabel);
-    if (preferredGamepadLabel !== undefined) {
-      resolved.controller.preferredGamepadLabel = preferredGamepadLabel;
-    }
-
-    const smoothScroll = asBoolean(src.controller.smoothScroll);
-    if (smoothScroll !== undefined) {
-      resolved.controller.smoothScroll = smoothScroll;
-    } else if (src.controller.smoothScroll !== undefined) {
-      warn(
-        'controller.smoothScroll',
-        src.controller.smoothScroll,
-        resolved.controller.smoothScroll,
-        'Expected boolean.',
-      );
-    }
-
-    const triggerInputMode = asString(src.controller.triggerInputMode);
-    if (
-      triggerInputMode === 'auto' ||
-      triggerInputMode === 'digital' ||
-      triggerInputMode === 'analog'
-    ) {
-      resolved.controller.triggerInputMode = triggerInputMode;
-    } else if (src.controller.triggerInputMode !== undefined) {
-      warn(
-        'controller.triggerInputMode',
-        src.controller.triggerInputMode,
-        resolved.controller.triggerInputMode,
-        "Expected 'auto', 'digital', or 'analog'.",
-      );
-    }
-
-    const boundedNumberKeys = [
-      'scrollPixelsPerSecond',
-      'horizontalJumpPixels',
-      'repeatDelayMs',
-      'repeatIntervalMs',
-    ] as const;
-    for (const key of boundedNumberKeys) {
-      const value = asNumber(src.controller[key]);
-      if (value !== undefined && Math.floor(value) > 0) {
-        resolved.controller[key] = Math.floor(value) as (typeof resolved.controller)[typeof key];
-      } else if (src.controller[key] !== undefined) {
-        warn(
-          `controller.${key}`,
-          src.controller[key],
-          resolved.controller[key],
-          'Expected positive number.',
-        );
-      }
-    }
-
-    const deadzoneKeys = ['stickDeadzone', 'triggerDeadzone'] as const;
-    for (const key of deadzoneKeys) {
-      const value = asNumber(src.controller[key]);
-      if (value !== undefined && value >= 0 && value <= 1) {
-        resolved.controller[key] = value as (typeof resolved.controller)[typeof key];
-      } else if (src.controller[key] !== undefined) {
-        warn(
-          `controller.${key}`,
-          src.controller[key],
-          resolved.controller[key],
-          'Expected number between 0 and 1.',
-        );
-      }
-    }
-
-    if (isObject(src.controller.buttonIndices)) {
-      const buttonIndexKeys = [
-        'select',
-        'buttonSouth',
-        'buttonEast',
-        'buttonNorth',
-        'buttonWest',
-        'leftShoulder',
-        'rightShoulder',
-        'leftStickPress',
-        'rightStickPress',
-        'leftTrigger',
-        'rightTrigger',
-      ] as const;
-
-      for (const key of buttonIndexKeys) {
-        const value = asNumber(src.controller.buttonIndices[key]);
-        if (value !== undefined && value >= 0 && Number.isInteger(value)) {
-          resolved.controller.buttonIndices[key] = value;
-        } else if (src.controller.buttonIndices[key] !== undefined) {
-          warn(
-            `controller.buttonIndices.${key}`,
-            src.controller.buttonIndices[key],
-            resolved.controller.buttonIndices[key],
-            'Expected non-negative integer.',
-          );
-        }
-      }
-    }
-
-    if (isObject(src.controller.bindings)) {
-      const buttonBindingKeys = [
-        'toggleLookup',
-        'closeLookup',
-        'toggleKeyboardOnlyMode',
-        'mineCard',
-        'quitMpv',
-        'previousAudio',
-        'nextAudio',
-        'playCurrentAudio',
-        'toggleMpvPause',
-      ] as const;
-
-      for (const key of buttonBindingKeys) {
-        const bindingValue = src.controller.bindings[key];
-        const legacyValue = asString(bindingValue);
-        if (
-          legacyValue !== undefined &&
-          CONTROLLER_BUTTON_BINDINGS.includes(
-            legacyValue as (typeof CONTROLLER_BUTTON_BINDINGS)[number],
-          )
-        ) {
-          resolved.controller.bindings[key] = resolveLegacyDiscreteBinding(
-            legacyValue as ControllerButtonBinding,
-            resolved.controller.buttonIndices,
-          );
-          continue;
-        }
-        const parsedObject = parseDiscreteBindingObject(bindingValue);
-        if (parsedObject) {
-          resolved.controller.bindings[key] = parsedObject;
-        } else if (bindingValue !== undefined) {
-          warn(
-            `controller.bindings.${key}`,
-            bindingValue,
-            resolved.controller.bindings[key],
-            "Expected legacy controller button name or binding object with kind 'none', 'button', or 'axis'.",
-          );
-        }
-      }
-
-      const axisBindingKeys = [
-        'leftStickHorizontal',
-        'leftStickVertical',
-        'rightStickHorizontal',
-        'rightStickVertical',
-      ] as const;
-
-      for (const key of axisBindingKeys) {
-        const bindingValue = src.controller.bindings[key];
-        const legacyValue = asString(bindingValue);
-        if (
-          legacyValue !== undefined &&
-          CONTROLLER_AXIS_BINDINGS.includes(
-            legacyValue as (typeof CONTROLLER_AXIS_BINDINGS)[number],
-          )
-        ) {
-          resolved.controller.bindings[key] = resolveLegacyAxisBinding(
-            legacyValue as ControllerAxisBinding,
-            key,
-          );
-          continue;
-        }
-        if (legacyValue === 'none') {
-          resolved.controller.bindings[key] = { kind: 'none' };
-          continue;
-        }
-        const parsedObject = parseAxisBindingObject(bindingValue, key);
-        if (parsedObject) {
-          resolved.controller.bindings[key] = parsedObject;
-        } else if (bindingValue !== undefined) {
-          warn(
-            `controller.bindings.${key}`,
-            bindingValue,
-            resolved.controller.bindings[key],
-            "Expected legacy controller axis name ('none' allowed) or binding object with kind 'axis'.",
-          );
-        }
-      }
-    }
-  }
+  applyControllerConfig(context);
 
   if (Array.isArray(src.keybindings)) {
     resolved.keybindings = src.keybindings.filter(

src/core/services/anilist/anilist-update-queue.test.ts

@@ -32,10 +32,16 @@ test('anilist update queue enqueues, snapshots, and dequeues success', () => {
   const loggerState = createLogger();
   const queue = createAnilistUpdateQueue(queueFile, loggerState.logger);
 
-  queue.enqueue('k1', 'Demo', 1);
+  queue.enqueue('k1', 'Demo', 1, 2);
   const snapshot = queue.getSnapshot(Number.MAX_SAFE_INTEGER);
   assert.deepEqual(snapshot, { pending: 1, ready: 1, deadLetter: 0 });
-  assert.equal(queue.nextReady(Number.MAX_SAFE_INTEGER)?.key, 'k1');
+  assert.deepEqual(
+    {
+      key: queue.nextReady(Number.MAX_SAFE_INTEGER)?.key,
+      season: queue.nextReady(Number.MAX_SAFE_INTEGER)?.season,
+    },
+    { key: 'k1', season: 2 },
+  );
 
   queue.markSuccess('k1');
   assert.deepEqual(queue.getSnapshot(Number.MAX_SAFE_INTEGER), {

src/core/services/anilist/anilist-update-queue.ts

@@ -9,6 +9,7 @@ const MAX_ITEMS = 500;
 export interface AnilistQueuedUpdate {
   key: string;
   title: string;
+  season?: number | null;
   episode: number;
   createdAt: number;
   attemptCount: number;
@@ -28,7 +29,7 @@ export interface AnilistRetryQueueSnapshot {
 }
 
 export interface AnilistUpdateQueue {
-  enqueue: (key: string, title: string, episode: number) => void;
+  enqueue: (key: string, title: string, episode: number, season?: number | null) => void;
   nextReady: (nowMs?: number) => AnilistQueuedUpdate | null;
   markSuccess: (key: string) => void;
   markFailure: (key: string, reason: string, nowMs?: number) => void;
@@ -106,7 +107,7 @@ export function createAnilistUpdateQueue(
   load();
 
   return {
-    enqueue(key: string, title: string, episode: number): void {
+    enqueue(key: string, title: string, episode: number, season: number | null = null): void {
       const existing = pending.find((item) => item.key === key);
       if (existing) {
         return;
@@ -117,6 +118,7 @@ export function createAnilistUpdateQueue(
       pending.push({
         key,
         title,
+        season,
         episode,
         createdAt: Date.now(),
         attemptCount: 0,

src/core/services/anilist/anilist-updater.test.ts

@@ -265,6 +265,125 @@ test('updateAnilistPostWatchProgress skips when progress already reached', async
   }
 });
 
+test('updateAnilistPostWatchProgress returns non-retryable error when media is not planning or watching', async () => {
+  const originalFetch = globalThis.fetch;
+  let call = 0;
+  globalThis.fetch = (async () => {
+    call += 1;
+    if (call === 1) {
+      return createJsonResponse({
+        data: {
+          Page: {
+            media: [{ id: 33, episodes: 12, title: { english: 'Missing Show' } }],
+          },
+        },
+      });
+    }
+    return createJsonResponse({
+      data: {
+        Media: { id: 33, mediaListEntry: null },
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Missing Show', 2);
+    assert.equal(result.status, 'error');
+    assert.equal(result.retryable, false);
+    assert.match(result.message, /not in your AniList Planning or Watching list/i);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('updateAnilistPostWatchProgress prefers season-specific AniList matches', async () => {
+  const originalFetch = globalThis.fetch;
+  const searchTerms: string[] = [];
+  let call = 0;
+  globalThis.fetch = (async (_input, init) => {
+    call += 1;
+    const body = JSON.parse(String(init?.body)) as { variables?: Record<string, unknown> };
+    if (call === 1) {
+      searchTerms.push(String(body.variables?.search));
+      return createJsonResponse({
+        data: {
+          Page: {
+            media: [
+              { id: 202, episodes: 12, title: { english: 'Demo Show Season 2' } },
+              { id: 101, episodes: 12, title: { english: 'Demo Show' } },
+            ],
+          },
+        },
+      });
+    }
+    if (call === 2) {
+      assert.equal(body.variables?.mediaId, 202);
+      return createJsonResponse({
+        data: {
+          Media: { id: 202, mediaListEntry: null },
+        },
+      });
+    }
+    return createJsonResponse({
+      data: {
+        SaveMediaListEntry: { progress: 2, status: 'CURRENT' },
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Demo Show', 2, {
+      season: 2,
+    });
+    assert.deepEqual(searchTerms, ['Demo Show Season 2']);
+    assert.equal(result.status, 'error');
+    assert.equal(result.retryable, false);
+    assert.match(result.message, /not in your AniList Planning or Watching list/i);
+    assert.equal(call, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('updateAnilistPostWatchProgress does not update rewatching entries', async () => {
+  const originalFetch = globalThis.fetch;
+  let call = 0;
+  globalThis.fetch = (async () => {
+    call += 1;
+    if (call === 1) {
+      return createJsonResponse({
+        data: {
+          Page: {
+            media: [{ id: 44, episodes: 12, title: { english: 'Rewatch Show' } }],
+          },
+        },
+      });
+    }
+    if (call === 2) {
+      return createJsonResponse({
+        data: {
+          Media: { id: 44, mediaListEntry: { progress: 0, status: 'REPEATING' } },
+        },
+      });
+    }
+    return createJsonResponse({
+      data: {
+        SaveMediaListEntry: { progress: 2, status: 'CURRENT' },
+      },
+    });
+  }) as typeof fetch;
+
+  try {
+    const result = await updateAnilistPostWatchProgress('token', 'Rewatch Show', 2);
+    assert.equal(result.status, 'error');
+    assert.equal(result.retryable, false);
+    assert.match(result.message, /marked repeating on AniList/i);
+    assert.equal(call, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test('updateAnilistPostWatchProgress returns error when search fails', async () => {
   const originalFetch = globalThis.fetch;
   globalThis.fetch = (async () =>

src/core/services/anilist/anilist-updater.ts

@@ -18,10 +18,12 @@ export interface AnilistMediaGuess {
 export interface AnilistPostWatchUpdateResult {
   status: 'updated' | 'skipped' | 'error';
   message: string;
+  retryable?: boolean;
 }
 
 export interface AnilistPostWatchUpdateOptions {
   rateLimiter?: AnilistRateLimiter;
+  season?: number | null;
 }
 
 interface AnilistGraphQlError {
@@ -156,6 +158,28 @@ function normalizeTitle(text: string): string {
   return text.trim().toLowerCase().replace(/\s+/g, ' ');
 }
 
+function titleMentionsSeason(title: string, season: number): boolean {
+  const normalized = normalizeTitle(title);
+  return (
+    normalized.includes(`season ${season}`) ||
+    normalized.includes(`s${String(season).padStart(2, '0')}`) ||
+    normalized.includes(`s${season}`)
+  );
+}
+
+function buildSearchCandidates(title: string, season: number | null | undefined): string[] {
+  const trimmed = title.trim();
+  if (!trimmed) return [];
+  const candidates =
+    typeof season === 'number' &&
+    Number.isInteger(season) &&
+    season > 1 &&
+    !titleMentionsSeason(trimmed, season)
+      ? [`${trimmed} Season ${season}`, trimmed]
+      : [trimmed];
+  return candidates.filter((candidate, index, all) => all.indexOf(candidate) === index);
+}
+
 async function anilistGraphQl<T>(
   accessToken: string,
   query: string,
@@ -226,6 +250,15 @@ function pickBestSearchResult(
   return { id: selected.id, title: selectedTitle };
 }
 
+function isUpdateableListStatus(status: string | null | undefined): boolean {
+  return status === 'CURRENT' || status === 'PLANNING';
+}
+
+function formatListStatus(status: string | null | undefined): string {
+  if (!status) return 'not in your AniList Planning or Watching list';
+  return `marked ${status.toLowerCase().replace(/_/g, ' ')} on AniList`;
+}
+
 export async function guessAnilistMediaInfo(
   mediaPath: string | null,
   mediaTitle: string | null,
@@ -279,27 +312,42 @@ export async function updateAnilistPostWatchProgress(
   episode: number,
   options: AnilistPostWatchUpdateOptions = {},
 ): Promise<AnilistPostWatchUpdateResult> {
-  const searchResponse = await anilistGraphQl<AnilistSearchData>(
-    accessToken,
-    `
-      query ($search: String!) {
-        Page(perPage: 5) {
-          media(search: $search, type: ANIME) {
-            id
-            episodes
-            title {
-              romaji
-              english
-              native
+  let media: NonNullable<NonNullable<AnilistSearchData['Page']>['media']> = [];
+  let searchError: string | null = null;
+  let pickTitle = title;
+  const searchCandidates = buildSearchCandidates(title, options.season);
+  for (const search of searchCandidates) {
+    const searchResponse = await anilistGraphQl<AnilistSearchData>(
+      accessToken,
+      `
+        query ($search: String!) {
+          Page(perPage: 5) {
+            media(search: $search, type: ANIME) {
+              id
+              episodes
+              title {
+                romaji
+                english
+                native
+              }
             }
           }
         }
-      }
-    `,
-    { search: title },
-    options,
-  );
-  const searchError = firstErrorMessage(searchResponse);
+      `,
+      { search },
+      options,
+    );
+    searchError = firstErrorMessage(searchResponse);
+    if (searchError) {
+      break;
+    }
+    media = searchResponse.data?.Page?.media ?? [];
+    if (media.length > 0) {
+      pickTitle = search;
+      break;
+    }
+  }
+
   if (searchError) {
     return {
       status: 'error',
@@ -307,8 +355,7 @@ export async function updateAnilistPostWatchProgress(
     };
   }
 
-  const media = searchResponse.data?.Page?.media ?? [];
-  const picked = pickBestSearchResult(title, episode, media);
+  const picked = pickBestSearchResult(pickTitle, episode, media);
   if (!picked) {
     return { status: 'error', message: 'AniList search returned no matches.' };
   }
@@ -337,7 +384,16 @@ export async function updateAnilistPostWatchProgress(
     };
   }
 
-  const currentProgress = entryResponse.data?.Media?.mediaListEntry?.progress ?? 0;
+  const entry = entryResponse.data?.Media?.mediaListEntry ?? null;
+  if (!entry || !isUpdateableListStatus(entry.status)) {
+    return {
+      status: 'error',
+      retryable: false,
+      message: `AniList update not possible: "${picked.title}" is ${formatListStatus(entry?.status)}. Add it to Planning or Watching, then mark watched again.`,
+    };
+  }
+
+  const currentProgress = entry.progress ?? 0;
   if (typeof currentProgress === 'number' && currentProgress >= episode) {
     return {
       status: 'skipped',

src/core/services/cli-command.test.ts

@@ -130,8 +130,8 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     openYomitanSettingsDelayed: (delayMs) => {
       calls.push(`openYomitanSettingsDelayed:${delayMs}`);
     },
-    openFirstRunSetup: () => {
-      calls.push('openFirstRunSetup');
+    openFirstRunSetup: (force?: boolean) => {
+      calls.push(`openFirstRunSetup:${force === true ? 'force' : 'default'}`);
     },
     setVisibleOverlayVisible: (visible) => {
       calls.push(`setVisibleOverlayVisible:${visible}`);
@@ -247,6 +247,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     log: (message) => {
       calls.push(`log:${message}`);
     },
+    logDebug: (message) => {
+      calls.push(`debug:${message}`);
+    },
     warn: (message) => {
       calls.push(`warn:${message}`);
     },
@@ -358,13 +361,23 @@ test('handleCliCommand processes --start for second-instance when overlay runtim
   );
 });
 
+test('handleCliCommand forces setup open for second-instance setup command', () => {
+  const { deps, calls } = createDeps();
+
+  handleCliCommand(makeArgs({ setup: true }), 'second-instance', deps);
+
+  assert.ok(calls.includes('openFirstRunSetup:force'));
+  assert.ok(calls.includes('debug:Opened first-run setup flow.'));
+});
+
 test('handleCliCommand opens first-run setup window for --setup', () => {
   const { deps, calls } = createDeps();
 
   handleCliCommand(makeArgs({ setup: true }), 'initial', deps);
 
-  assert.ok(calls.includes('openFirstRunSetup'));
-  assert.ok(calls.includes('log:Opened first-run setup flow.'));
+  assert.ok(calls.includes('openFirstRunSetup:force'));
+  assert.ok(calls.includes('debug:Opened first-run setup flow.'));
+  assert.equal(calls.includes('log:Opened first-run setup flow.'), false);
   assert.equal(calls.includes('openYomitanSettingsDelayed:1000'), false);
 });
 

src/core/services/cli-command.ts

@@ -41,7 +41,7 @@ export interface CliCommandServiceDeps {
   initializeOverlayRuntime: () => void;
   toggleVisibleOverlay: () => void;
   togglePrimarySubtitleBar: () => void;
-  openFirstRunSetup: () => void;
+  openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettingsDelayed: (delayMs: number) => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
@@ -106,6 +106,7 @@ export interface CliCommandServiceDeps {
   getMultiCopyTimeoutMs: () => number;
   showMpvOsd: (text: string) => void;
   log: (message: string) => void;
+  logDebug: (message: string) => void;
   warn: (message: string) => void;
   error: (message: string, err: unknown) => void;
 }
@@ -157,7 +158,7 @@ interface MiningCliRuntime {
 }
 
 interface UiCliRuntime {
-  openFirstRunSetup: () => void;
+  openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettings: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
@@ -211,6 +212,7 @@ export interface CliCommandDepsRuntimeOptions {
   getMultiCopyTimeoutMs: () => number;
   schedule: (fn: () => void, delayMs: number) => unknown;
   log: (message: string) => void;
+  logDebug: (message: string) => void;
   warn: (message: string) => void;
   error: (message: string, err: unknown) => void;
 }
@@ -286,6 +288,7 @@ export function createCliCommandDepsRuntime(
     getMultiCopyTimeoutMs: options.getMultiCopyTimeoutMs,
     showMpvOsd: options.mpv.showOsd,
     log: options.log,
+    logDebug: options.logDebug,
     warn: options.warn,
     error: options.error,
   };
@@ -378,8 +381,8 @@ export function handleCliCommand(
   } else if (args.togglePrimarySubtitleBar) {
     deps.togglePrimarySubtitleBar();
   } else if (args.setup) {
-    deps.openFirstRunSetup();
-    deps.log('Opened first-run setup flow.');
+    deps.openFirstRunSetup(true);
+    deps.logDebug('Opened first-run setup flow.');
   } else if (args.settings) {
     deps.openYomitanSettingsDelayed(1000);
   } else if (args.show || args.showVisibleOverlay) {

src/core/services/ipc.test.ts

@@ -83,6 +83,7 @@ function createControllerConfigFixture() {
       rightStickHorizontal: { kind: 'axis' as const, axisIndex: 3, dpadFallback: 'none' as const },
       rightStickVertical: { kind: 'axis' as const, axisIndex: 4, dpadFallback: 'none' as const },
     },
+    profiles: {},
   };
 }
 
@@ -218,6 +219,9 @@ test('createIpcDepsRuntime wires AniList handlers', async () => {
     getMainWindow: () => null,
     getVisibleOverlayVisibility: () => false,
     onOverlayModalClosed: () => {},
+    onOverlayMouseInteractionChanged: (active) => {
+      calls.push(`overlay-interaction:${active}`);
+    },
     openYomitanSettings: () => {},
     quitApp: () => {},
     toggleVisibleOverlay: () => {},
@@ -281,6 +285,7 @@ test('createIpcDepsRuntime wires AniList handlers', async () => {
   assert.deepEqual(deps.getAnilistStatus(), { tokenStatus: 'resolved' });
   deps.clearAnilistToken();
   deps.openAnilistSetup();
+  deps.onOverlayMouseInteractionChanged?.(true, null);
   assert.deepEqual(deps.getAnilistQueueStatus(), {
     pending: 1,
     ready: 0,
@@ -298,10 +303,37 @@ test('createIpcDepsRuntime wires AniList handlers', async () => {
   assert.deepEqual(await deps.playPlaylistBrowserIndex(2), { ok: true, message: 'play' });
   assert.deepEqual(await deps.removePlaylistBrowserIndex(2), { ok: true, message: 'remove' });
   assert.deepEqual(await deps.movePlaylistBrowserIndex(2, -1), { ok: true, message: 'move' });
-  assert.deepEqual(calls, ['clearAnilistToken', 'openAnilistSetup', 'retryAnilistQueueNow']);
+  assert.deepEqual(calls, [
+    'clearAnilistToken',
+    'openAnilistSetup',
+    'overlay-interaction:true',
+    'retryAnilistQueueNow',
+  ]);
   assert.equal(deps.getPlaybackPaused(), true);
 });
 
+test('registerIpcHandlers maps setIgnoreMouseEvents to overlay interaction active state', () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const calls: string[] = [];
+
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      onOverlayMouseInteractionChanged: (active) => {
+        calls.push(`overlay-interaction:${active}`);
+      },
+    }),
+    registrar,
+  );
+
+  const handler = handlers.on.get(IPC_CHANNELS.command.setIgnoreMouseEvents);
+  assert.equal(typeof handler, 'function');
+
+  handler?.({}, true, { forward: true });
+  handler?.({}, false, {});
+
+  assert.deepEqual(calls, ['overlay-interaction:false', 'overlay-interaction:true']);
+});
+
 test('registerIpcHandlers runs AniList update after manual mark watched succeeds', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const calls: string[] = [];
@@ -944,6 +976,58 @@ test('registerIpcHandlers awaits saveControllerPreference through request-respon
   ]);
 });
 
+test('registerIpcHandlers accepts per-controller profile config updates', async () => {
+  const { registrar, handlers } = createFakeIpcRegistrar();
+  const controllerSaves: unknown[] = [];
+  registerIpcHandlers(
+    createRegisterIpcDeps({
+      saveControllerConfig: async (update) => {
+        controllerSaves.push(update);
+      },
+    }),
+    registrar,
+  );
+
+  const saveHandler = handlers.handle.get(IPC_CHANNELS.command.saveControllerConfig);
+  assert.ok(saveHandler);
+
+  const update = {
+    profiles: {
+      'pad-1': {
+        label: 'Pad One',
+        buttonIndices: {
+          buttonSouth: 11,
+        },
+        bindings: {
+          toggleLookup: { kind: 'button', buttonIndex: 11 },
+          leftStickHorizontal: { kind: 'axis', axisIndex: 6, dpadFallback: 'horizontal' },
+        },
+      },
+    },
+  };
+  await saveHandler({}, update);
+  assert.deepEqual(controllerSaves, [update]);
+
+  await assert.rejects(async () => {
+    await saveHandler(
+      {},
+      {
+        profiles: {
+          'pad-1': {
+            bindings: {
+              toggleLookup: { kind: 'axis', axisIndex: 0 },
+            },
+          },
+        },
+      },
+    );
+  }, /Invalid controller config payload/);
+
+  await assert.rejects(async () => {
+    await saveHandler({}, JSON.parse('{"profiles":{"__proto__":{"label":"polluted"}}}'));
+  }, /Invalid controller config payload/);
+});
+
 test('registerIpcHandlers validates dispatchSessionAction payloads', async () => {
   const { registrar, handlers } = createFakeIpcRegistrar();
   const dispatched: SessionActionDispatchRequest[] = [];

src/core/services/ipc.ts

@@ -44,6 +44,10 @@ export interface IpcServiceDeps {
     modal: OverlayHostedModal,
     senderWindow: ElectronBrowserWindow | null,
   ) => void;
+  onOverlayMouseInteractionChanged?: (
+    active: boolean,
+    senderWindow: ElectronBrowserWindow | null,
+  ) => void;
   openYomitanSettings: () => void;
   quitApp: () => void;
   toggleDevTools: () => void;
@@ -175,6 +179,10 @@ export interface IpcDepsRuntimeOptions {
     modal: OverlayHostedModal,
     senderWindow: ElectronBrowserWindow | null,
   ) => void;
+  onOverlayMouseInteractionChanged?: (
+    active: boolean,
+    senderWindow: ElectronBrowserWindow | null,
+  ) => void;
   openYomitanSettings: () => void;
   quitApp: () => void;
   toggleVisibleOverlay: () => void;
@@ -233,6 +241,7 @@ export function createIpcDepsRuntime(options: IpcDepsRuntimeOptions): IpcService
   return {
     onOverlayModalClosed: options.onOverlayModalClosed,
     onOverlayModalOpened: options.onOverlayModalOpened,
+    onOverlayMouseInteractionChanged: options.onOverlayMouseInteractionChanged,
     openYomitanSettings: options.openYomitanSettings,
     quitApp: options.quitApp,
     toggleDevTools: () => {
@@ -349,6 +358,7 @@ export function registerIpcHandlers(deps: IpcServiceDeps, ipc: IpcMainRegistrar
       if (senderWindow && !senderWindow.isDestroyed()) {
         senderWindow.setIgnoreMouseEvents(ignore, parsedOptions);
       }
+      deps.onOverlayMouseInteractionChanged?.(!ignore, senderWindow);
     },
   );
 

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

@@ -547,7 +547,7 @@ test('initializeOverlayRuntime hides overlay windows when tracker loses the targ
   assert.deepEqual(calls, ['hide-visible', 'hide-modal', 'sync-shortcuts']);
 });
 
-test('initializeOverlayRuntime hides visible overlay on Windows tracker loss when target is not minimized', () => {
+test('initializeOverlayRuntime refreshes visible overlay on tracker loss when target is not minimized', () => {
   const calls: string[] = [];
   const tracker = {
     onGeometryChange: null as ((...args: unknown[]) => void) | null,
@@ -600,7 +600,7 @@ test('initializeOverlayRuntime hides visible overlay on Windows tracker loss whe
   calls.length = 0;
   tracker.onWindowLost?.();
 
-  assert.deepEqual(calls, ['hide-visible', 'sync-shortcuts']);
+  assert.deepEqual(calls, ['update-visible']);
 });
 
 test('initializeOverlayRuntime restores overlay bounds and visibility when tracker finds the target window again', () => {

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

@@ -105,10 +105,14 @@ export function initializeOverlayRuntime(options: {
     };
     windowTracker.onWindowLost = () => {
       options.releaseOverlayOwner?.();
-      for (const window of options.getOverlayWindows()) {
-        window.hide();
+      if (windowTracker.isTargetWindowMinimized()) {
+        for (const window of options.getOverlayWindows()) {
+          window.hide();
+        }
+        options.syncOverlayShortcuts();
+        return;
       }
-      options.syncOverlayShortcuts();
+      options.updateVisibleOverlayVisibility();
     };
     windowTracker.onWindowFocusChange = () => {
       if (options.isVisibleOverlayVisible()) {

src/core/services/overlay-visibility.test.ts

@@ -42,6 +42,11 @@ function createMainWindowRecorder() {
     setAlwaysOnTop: (flag: boolean) => {
       calls.push(`always-on-top:${flag}`);
     },
+    setVisibleOnAllWorkspaces: (flag: boolean, options?: { visibleOnFullScreen?: boolean }) => {
+      calls.push(
+        `all-workspaces:${flag}:${options?.visibleOnFullScreen === true ? 'fullscreen' : 'plain'}`,
+      );
+    },
     setIgnoreMouseEvents: (ignore: boolean, options?: { forward?: boolean }) => {
       calls.push(`mouse-ignore:${ignore}:${options?.forward === true ? 'forward' : 'plain'}`);
     },
@@ -538,11 +543,12 @@ test('forced passthrough still shows tracked overlay while bound to mpv on Windo
   assert.ok(calls.includes('sync-windows-z-order'));
 });
 
-test('forced mouse passthrough drops macOS tracked overlay below higher-priority windows', () => {
+test('forced mouse passthrough keeps macOS tracked overlay above active mpv', () => {
   const { window, calls } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {
     isTracking: () => true,
     getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => true,
   };
 
   updateVisibleOverlayVisibility({
@@ -571,8 +577,53 @@ test('forced mouse passthrough drops macOS tracked overlay below higher-priority
     forceMousePassthrough: true,
   } as never);
 
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(!calls.includes('always-on-top:false'));
+});
+
+test('forced mouse passthrough still hides macOS tracked overlay when mpv loses foreground', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+  };
+
+  window.show();
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+    forceMousePassthrough: true,
+  } as never);
+
   assert.ok(calls.includes('mouse-ignore:true:forward'));
   assert.ok(calls.includes('always-on-top:false'));
+  assert.ok(calls.includes('all-workspaces:false:plain'));
+  assert.ok(calls.includes('hide'));
   assert.ok(!calls.includes('ensure-level'));
   assert.ok(!calls.includes('enforce-order'));
 });
@@ -883,7 +934,7 @@ test('visible overlay stays hidden while a modal window is active', () => {
   assert.ok(!calls.includes('update-bounds'));
 });
 
-test('macOS tracked visible overlay stays interactive without passively stealing focus', () => {
+test('macOS tracked visible overlay starts click-through without passively stealing focus', () => {
   const { window, calls } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {
     isTracking: () => true,
@@ -915,12 +966,53 @@ test('macOS tracked visible overlay stays interactive without passively stealing
     isWindowsPlatform: false,
   } as never);
 
-  assert.ok(calls.includes('mouse-ignore:false:plain'));
-  assert.ok(calls.includes('show'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('show-inactive'));
+  assert.ok(!calls.includes('show'));
   assert.ok(!calls.includes('focus'));
 });
 
-test('macOS keeps active mpv overlay visible and interactive during tracker refresh', () => {
+test('macOS tracked visible overlay remains click-through even if the overlay had focus', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => true,
+  };
+
+  setFocused(true);
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(!calls.includes('focus'));
+});
+
+test('macOS keeps active mpv overlay visible and click-through during tracker refresh', () => {
   const { window, calls } = createMainWindowRecorder();
   const osdMessages: string[] = [];
   const tracker: WindowTrackerStub = {
@@ -961,7 +1053,7 @@ test('macOS keeps active mpv overlay visible and interactive during tracker refr
 
   assert.ok(calls.includes('update-bounds'));
   assert.ok(calls.includes('sync-layer'));
-  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
   assert.ok(calls.includes('ensure-level'));
   assert.ok(calls.includes('enforce-order'));
   assert.ok(calls.includes('sync-shortcuts'));
@@ -969,7 +1061,7 @@ test('macOS keeps active mpv overlay visible and interactive during tracker refr
   assert.deepEqual(osdMessages, []);
 });
 
-test('macOS tracked overlay releases topmost level when mpv loses foreground', () => {
+test('macOS tracked overlay hides when mpv loses foreground', () => {
   const { window, calls } = createMainWindowRecorder();
   const tracker: WindowTrackerStub = {
     isTracking: () => true,
@@ -977,6 +1069,9 @@ test('macOS tracked overlay releases topmost level when mpv loses foreground', (
     isTargetWindowFocused: () => false,
   };
 
+  window.show();
+  calls.length = 0;
+
   updateVisibleOverlayVisibility({
     visibleOverlayVisible: true,
     mainWindow: window as never,
@@ -1006,14 +1101,202 @@ test('macOS tracked overlay releases topmost level when mpv loses foreground', (
   assert.ok(calls.includes('sync-layer'));
   assert.ok(calls.includes('mouse-ignore:true:forward'));
   assert.ok(calls.includes('always-on-top:false'));
-  assert.ok(calls.includes('show'));
+  assert.ok(calls.includes('all-workspaces:false:plain'));
+  assert.ok(calls.includes('hide'));
   assert.ok(calls.includes('sync-shortcuts'));
   assert.ok(!calls.includes('ensure-level'));
   assert.ok(!calls.includes('enforce-order'));
   assert.ok(!calls.includes('focus'));
+  assert.ok(!calls.includes('show'));
+});
+
+test('macOS keeps tracked overlay visible while overlay interaction is active after mpv loses foreground', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+  };
+
+  window.show();
+  setFocused(false);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    overlayInteractionActive: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('update-bounds'));
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('always-on-top:false'));
   assert.ok(!calls.includes('hide'));
 });
 
+test('macOS lets an active overlay receive mouse input instead of forcing passthrough', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+  };
+
+  window.show();
+  setFocused(false);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    overlayInteractionActive: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(!calls.includes('mouse-ignore:true:forward'));
+  assert.ok(!calls.includes('hide'));
+});
+
+test('macOS focuses an active overlay so lookup trigger keys reach it', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => false,
+  };
+
+  window.show();
+  setFocused(false);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    overlayInteractionActive: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    isWindowsPlatform: false,
+  } as never);
+
+  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('focus'));
+  assert.ok(!calls.includes('hide'));
+});
+
+test('macOS tracked overlay passively reappears when mpv regains foreground', () => {
+  const { window, calls } = createMainWindowRecorder();
+  let targetFocused = false;
+  const tracker: WindowTrackerStub = {
+    isTracking: () => true,
+    getGeometry: () => ({ x: 0, y: 0, width: 1280, height: 720 }),
+    isTargetWindowFocused: () => targetFocused,
+  };
+
+  window.show();
+  calls.length = 0;
+
+  const run = () =>
+    updateVisibleOverlayVisibility({
+      visibleOverlayVisible: true,
+      mainWindow: window as never,
+      windowTracker: tracker as never,
+      trackerNotReadyWarningShown: false,
+      setTrackerNotReadyWarningShown: () => {},
+      updateVisibleOverlayBounds: () => {
+        calls.push('update-bounds');
+      },
+      ensureOverlayWindowLevel: () => {
+        calls.push('ensure-level');
+      },
+      syncPrimaryOverlayWindowLayer: () => {
+        calls.push('sync-layer');
+      },
+      enforceOverlayLayerOrder: () => {
+        calls.push('enforce-order');
+      },
+      syncOverlayShortcuts: () => {
+        calls.push('sync-shortcuts');
+      },
+      isMacOSPlatform: true,
+      isWindowsPlatform: false,
+    } as never);
+
+  run();
+  assert.ok(calls.includes('hide'));
+
+  calls.length = 0;
+  targetFocused = true;
+  run();
+
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('show-inactive'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(!calls.includes('show'));
+  assert.ok(!calls.includes('focus'));
+});
+
 test('macOS preserves an already visible active mpv overlay while tracker is temporarily not ready', () => {
   const { window, calls } = createMainWindowRecorder();
   const osdMessages: string[] = [];
@@ -1060,7 +1343,7 @@ test('macOS preserves an already visible active mpv overlay while tracker is tem
 
   assert.equal(trackerWarning, false);
   assert.ok(calls.includes('sync-layer'));
-  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
   assert.ok(calls.includes('ensure-level'));
   assert.ok(calls.includes('sync-shortcuts'));
   assert.ok(!calls.includes('hide'));
@@ -1101,7 +1384,8 @@ test('forced mouse passthrough keeps macOS tracked overlay passive while visible
   } as never);
 
   assert.ok(calls.includes('mouse-ignore:true:forward'));
-  assert.ok(calls.includes('show'));
+  assert.ok(calls.includes('show-inactive'));
+  assert.ok(!calls.includes('show'));
   assert.ok(!calls.includes('focus'));
 });
 
@@ -1390,7 +1674,7 @@ test('macOS preserves visible overlay during transient tracker loss with retaine
   assert.deepEqual(osdMessages, []);
   assert.ok(calls.includes('update-bounds'));
   assert.ok(calls.includes('sync-layer'));
-  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
   assert.ok(calls.includes('ensure-level'));
   assert.ok(calls.includes('enforce-order'));
   assert.ok(calls.includes('sync-shortcuts'));
@@ -1398,6 +1682,156 @@ test('macOS preserves visible overlay during transient tracker loss with retaine
   assert.ok(!calls.includes('show'));
 });
 
+test('macOS hides visible overlay during tracker loss after mpv loses foreground', () => {
+  const { window, calls } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => false,
+    getGeometry: () => null,
+    isTargetWindowFocused: () => false,
+    isTargetWindowMinimized: () => false,
+  };
+
+  window.show();
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    showOverlayLoadingOsd: () => {
+      calls.push('loading-osd');
+    },
+  } as never);
+
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('always-on-top:false'));
+  assert.ok(calls.includes('all-workspaces:false:plain'));
+  assert.ok(calls.includes('hide'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('ensure-level'));
+  assert.ok(!calls.includes('enforce-order'));
+  assert.ok(!calls.includes('loading-osd'));
+});
+
+test('macOS keeps a focused overlay visible during tracker loss', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => false,
+    getGeometry: () => null,
+    isTargetWindowFocused: () => false,
+    isTargetWindowMinimized: () => false,
+  };
+
+  window.show();
+  setFocused(true);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    showOverlayLoadingOsd: () => {
+      calls.push('loading-osd');
+    },
+  } as never);
+
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:true:forward'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('hide'));
+  assert.ok(!calls.includes('loading-osd'));
+});
+
+test('macOS keeps an interactive overlay visible during tracker loss even when Electron focus drops', () => {
+  const { window, calls, setFocused } = createMainWindowRecorder();
+  const tracker: WindowTrackerStub = {
+    isTracking: () => false,
+    getGeometry: () => null,
+    isTargetWindowFocused: () => false,
+    isTargetWindowMinimized: () => false,
+  };
+
+  window.show();
+  setFocused(false);
+  calls.length = 0;
+
+  updateVisibleOverlayVisibility({
+    visibleOverlayVisible: true,
+    overlayInteractionActive: true,
+    mainWindow: window as never,
+    windowTracker: tracker as never,
+    trackerNotReadyWarningShown: false,
+    setTrackerNotReadyWarningShown: () => {},
+    updateVisibleOverlayBounds: () => {
+      calls.push('update-bounds');
+    },
+    ensureOverlayWindowLevel: () => {
+      calls.push('ensure-level');
+    },
+    syncPrimaryOverlayWindowLayer: () => {
+      calls.push('sync-layer');
+    },
+    enforceOverlayLayerOrder: () => {
+      calls.push('enforce-order');
+    },
+    syncOverlayShortcuts: () => {
+      calls.push('sync-shortcuts');
+    },
+    isMacOSPlatform: true,
+    showOverlayLoadingOsd: () => {
+      calls.push('loading-osd');
+    },
+  } as never);
+
+  assert.ok(calls.includes('sync-layer'));
+  assert.ok(calls.includes('mouse-ignore:false:plain'));
+  assert.ok(calls.includes('ensure-level'));
+  assert.ok(calls.includes('enforce-order'));
+  assert.ok(calls.includes('sync-shortcuts'));
+  assert.ok(!calls.includes('always-on-top:false'));
+  assert.ok(!calls.includes('hide'));
+  assert.ok(!calls.includes('loading-osd'));
+});
+
 test('macOS suppresses immediate repeat loading OSD after tracker recovery until cooldown expires', () => {
   const { window } = createMainWindowRecorder();
   const osdMessages: string[] = [];

src/core/services/overlay-visibility.ts

@@ -15,6 +15,17 @@ function setOverlayWindowOpacity(window: BrowserWindow, opacity: number): void {
   opacityCapableWindow.setOpacity?.(opacity);
 }
 
+function releaseOverlayWindowLevel(window: BrowserWindow): void {
+  window.setAlwaysOnTop(false);
+  const allWorkspacesWindow = window as BrowserWindow & {
+    setVisibleOnAllWorkspaces?: (
+      visible: boolean,
+      options?: { visibleOnFullScreen?: boolean },
+    ) => void;
+  };
+  allWorkspacesWindow.setVisibleOnAllWorkspaces?.(false, { visibleOnFullScreen: false });
+}
+
 function clearPendingWindowsOverlayReveal(window: BrowserWindow): void {
   const pendingTimeout = pendingWindowsOverlayRevealTimeoutByWindow.get(window);
   if (!pendingTimeout) {
@@ -52,6 +63,7 @@ export function updateVisibleOverlayVisibility(args: {
   visibleOverlayVisible: boolean;
   modalActive?: boolean;
   forceMousePassthrough?: boolean;
+  overlayInteractionActive?: boolean;
   mainWindow: BrowserWindow | null;
   windowTracker: BaseWindowTracker | null;
   lastKnownWindowsForegroundProcessName?: string | null;
@@ -78,6 +90,7 @@ export function updateVisibleOverlayVisibility(args: {
   }
 
   const mainWindow = args.mainWindow;
+  const overlayInteractionActive = args.overlayInteractionActive === true;
 
   if (args.modalActive) {
     if (args.isWindowsPlatform) {
@@ -93,16 +106,34 @@ export function updateVisibleOverlayVisibility(args: {
     const forceMousePassthrough = args.forceMousePassthrough === true;
     const wasVisible = mainWindow.isVisible();
     const isVisibleOverlayFocused =
-      typeof mainWindow.isFocused === 'function' && mainWindow.isFocused();
+      overlayInteractionActive ||
+      (typeof mainWindow.isFocused === 'function' && mainWindow.isFocused());
+    const windowTracker = args.windowTracker;
+    const canReportMacOSTargetMinimized =
+      args.isMacOSPlatform && typeof windowTracker?.isTargetWindowMinimized === 'function';
+    const isTrackedMacOSTargetMinimized =
+      canReportMacOSTargetMinimized && windowTracker?.isTargetWindowMinimized() === true;
+    const trackedMacOSTargetFocused = args.windowTracker?.isTargetWindowFocused?.();
+    const hasTransientMacOSTrackerLoss =
+      args.isMacOSPlatform &&
+      canReportMacOSTargetMinimized &&
+      !!windowTracker &&
+      !windowTracker.isTracking() &&
+      !isTrackedMacOSTargetMinimized &&
+      trackedMacOSTargetFocused !== false &&
+      mainWindow.isVisible();
     const isTrackedMacOSTargetFocused =
-      !args.isMacOSPlatform || !args.windowTracker
+      hasTransientMacOSTrackerLoss || !args.isMacOSPlatform || !args.windowTracker
         ? true
-        : (args.windowTracker.isTargetWindowFocused?.() ?? true);
+        : (trackedMacOSTargetFocused ?? true);
     const shouldReleaseMacOSOverlayLevel =
       args.isMacOSPlatform &&
       !!args.windowTracker &&
+      !hasTransientMacOSTrackerLoss &&
       !isVisibleOverlayFocused &&
       !isTrackedMacOSTargetFocused;
+    // Renderer hover tracking temporarily disables this for subtitle and popup interaction.
+    const shouldUseMacOSMousePassthrough = args.isMacOSPlatform && !overlayInteractionActive;
     const shouldDefaultToPassthrough =
       args.isWindowsPlatform || forceMousePassthrough || shouldReleaseMacOSOverlayLevel;
     const windowsForegroundProcessName =
@@ -127,6 +158,7 @@ export function updateVisibleOverlayVisibility(args: {
       (args.windowTracker.isTracking() || args.windowTracker.getGeometry() !== null);
     const shouldForcePassiveReshow = args.isWindowsPlatform && !wasVisible;
     const shouldIgnoreMouseEvents =
+      shouldUseMacOSMousePassthrough ||
       forceMousePassthrough ||
       (shouldDefaultToPassthrough && (!isVisibleOverlayFocused || shouldForcePassiveReshow));
     const shouldBindTrackedWindowsOverlay = args.isWindowsPlatform && !!args.windowTracker;
@@ -143,14 +175,22 @@ export function updateVisibleOverlayVisibility(args: {
       mainWindow.setIgnoreMouseEvents(false);
     }
 
+    if (shouldReleaseMacOSOverlayLevel) {
+      releaseOverlayWindowLevel(mainWindow);
+      if (wasVisible) {
+        mainWindow.hide();
+      }
+      return false;
+    }
+
     if (shouldBindTrackedWindowsOverlay) {
       // On Windows, z-order is enforced by the OS via the owner window mechanism
       // (SetWindowLongPtr GWLP_HWNDPARENT). The overlay is always above mpv
       // without any manual z-order management.
-    } else if (!forceMousePassthrough && !shouldReleaseMacOSOverlayLevel) {
+    } else if (!forceMousePassthrough || args.isMacOSPlatform) {
       args.ensureOverlayWindowLevel(mainWindow);
     } else {
-      mainWindow.setAlwaysOnTop(false);
+      releaseOverlayWindowLevel(mainWindow);
     }
     if (!wasVisible) {
       const hasWebContents =
@@ -163,16 +203,20 @@ export function updateVisibleOverlayVisibility(args: {
         // skip — ready-to-show hasn't fired yet; the onWindowContentReady
         // callback will trigger another visibility update when the renderer
         // has painted its first frame.
-      } else if (args.isWindowsPlatform && shouldIgnoreMouseEvents) {
-        setOverlayWindowOpacity(mainWindow, 0);
+      } else if ((args.isWindowsPlatform || args.isMacOSPlatform) && shouldIgnoreMouseEvents) {
+        if (args.isWindowsPlatform) {
+          setOverlayWindowOpacity(mainWindow, 0);
+        }
         mainWindow.showInactive();
         mainWindow.setIgnoreMouseEvents(true, { forward: true });
-        scheduleWindowsOverlayReveal(
-          mainWindow,
-          shouldBindTrackedWindowsOverlay
-            ? (window) => args.syncWindowsOverlayToMpvZOrder?.(window)
-            : undefined,
-        );
+        if (args.isWindowsPlatform) {
+          scheduleWindowsOverlayReveal(
+            mainWindow,
+            shouldBindTrackedWindowsOverlay
+              ? (window) => args.syncWindowsOverlayToMpvZOrder?.(window)
+              : undefined,
+          );
+        }
       } else {
         if (args.isWindowsPlatform) {
           setOverlayWindowOpacity(mainWindow, 0);
@@ -193,6 +237,16 @@ export function updateVisibleOverlayVisibility(args: {
       args.syncWindowsOverlayToMpvZOrder?.(mainWindow);
     }
 
+    if (
+      args.isMacOSPlatform &&
+      overlayInteractionActive &&
+      !forceMousePassthrough &&
+      typeof mainWindow.isFocused === 'function' &&
+      !mainWindow.isFocused()
+    ) {
+      mainWindow.focus();
+    }
+
     if (!args.isWindowsPlatform && !args.isMacOSPlatform && !forceMousePassthrough) {
       mainWindow.focus();
     }
@@ -200,6 +254,11 @@ export function updateVisibleOverlayVisibility(args: {
     return !shouldReleaseMacOSOverlayLevel;
   };
 
+  const shouldEnforceVisibleOverlayLayerOrder = (shouldEnforceLayerOrder: boolean): boolean =>
+    shouldEnforceLayerOrder &&
+    !args.isWindowsPlatform &&
+    (!args.forceMousePassthrough || args.isMacOSPlatform === true);
+
   const maybeShowOverlayLoadingOsd = (): void => {
     if (!args.isMacOSPlatform || !args.showOverlayLoadingOsd) {
       return;
@@ -242,7 +301,7 @@ export function updateVisibleOverlayVisibility(args: {
     }
     args.syncPrimaryOverlayWindowLayer('visible');
     const shouldEnforceLayerOrder = showPassiveVisibleOverlay();
-    if (shouldEnforceLayerOrder && !args.forceMousePassthrough && !args.isWindowsPlatform) {
+    if (shouldEnforceVisibleOverlayLayerOrder(shouldEnforceLayerOrder)) {
       args.enforceOverlayLayerOrder();
     }
     args.syncOverlayShortcuts();
@@ -274,9 +333,18 @@ export function updateVisibleOverlayVisibility(args: {
   const hasRetainedTrackedGeometry = args.windowTracker.getGeometry() !== null;
   const hasActiveMacOSTargetSignal =
     args.isMacOSPlatform && (args.windowTracker.isTargetWindowFocused?.() ?? false);
+  const hasActiveMacOSOverlaySignal = args.isMacOSPlatform && overlayInteractionActive;
+  const canReportMacOSTargetMinimized =
+    args.isMacOSPlatform && typeof args.windowTracker.isTargetWindowMinimized === 'function';
+  const isTrackedMacOSTargetMinimized =
+    canReportMacOSTargetMinimized && args.windowTracker.isTargetWindowMinimized();
   const shouldPreserveTransientTrackedOverlay =
     (args.isMacOSPlatform &&
-      (hasRetainedTrackedGeometry || (mainWindow.isVisible() && hasActiveMacOSTargetSignal))) ||
+      !isTrackedMacOSTargetMinimized &&
+      (hasRetainedTrackedGeometry ||
+        (mainWindow.isVisible() && hasActiveMacOSOverlaySignal) ||
+        (mainWindow.isVisible() && hasActiveMacOSTargetSignal) ||
+        (canReportMacOSTargetMinimized && mainWindow.isVisible()))) ||
     (args.isWindowsPlatform &&
       typeof args.windowTracker.isTargetWindowMinimized === 'function' &&
       !args.windowTracker.isTargetWindowMinimized());
@@ -292,7 +360,7 @@ export function updateVisibleOverlayVisibility(args: {
     }
     args.syncPrimaryOverlayWindowLayer('visible');
     const shouldEnforceLayerOrder = showPassiveVisibleOverlay();
-    if (shouldEnforceLayerOrder && !args.forceMousePassthrough && !args.isWindowsPlatform) {
+    if (shouldEnforceVisibleOverlayLayerOrder(shouldEnforceLayerOrder)) {
       args.enforceOverlayLayerOrder();
     }
     args.syncOverlayShortcuts();

src/core/services/overlay-window-input.ts

@@ -66,15 +66,16 @@ export function handleOverlayWindowBlurred(options: {
   isOverlayVisible: (kind: OverlayWindowKind) => boolean;
   ensureOverlayWindowLevel: () => void;
   moveWindowTop: () => void;
-  onWindowsVisibleOverlayBlur?: () => void;
+  onVisibleOverlayBlur?: () => void;
   platform?: NodeJS.Platform;
 }): boolean {
   const platform = options.platform ?? process.platform;
   if (platform === 'win32' && options.kind === 'visible') {
-    options.onWindowsVisibleOverlayBlur?.();
+    options.onVisibleOverlayBlur?.();
     return false;
   }
   if (platform === 'darwin' && options.kind === 'visible') {
+    options.onVisibleOverlayBlur?.();
     return false;
   }
 

src/core/services/overlay-window.test.ts

@@ -136,14 +136,14 @@ test('handleOverlayWindowBlurred notifies Windows visible overlay blur callback
     moveWindowTop: () => {
       calls.push('move-top');
     },
-    onWindowsVisibleOverlayBlur: () => {
-      calls.push('windows-visible-blur');
+    onVisibleOverlayBlur: () => {
+      calls.push('visible-blur');
     },
     platform: 'win32',
   });
 
   assert.equal(handled, false);
-  assert.deepEqual(calls, ['windows-visible-blur']);
+  assert.deepEqual(calls, ['visible-blur']);
 });
 
 test('handleOverlayWindowBlurred skips macOS visible overlay restacking after focus loss', () => {
@@ -166,7 +166,7 @@ test('handleOverlayWindowBlurred skips macOS visible overlay restacking after fo
   assert.deepEqual(calls, []);
 });
 
-test('handleOverlayWindowBlurred leaves Windows callback inactive on macOS visible overlay blur', () => {
+test('handleOverlayWindowBlurred notifies macOS visible overlay blur callback without restacking', () => {
   const calls: string[] = [];
 
   const handled = handleOverlayWindowBlurred({
@@ -179,14 +179,14 @@ test('handleOverlayWindowBlurred leaves Windows callback inactive on macOS visib
     moveWindowTop: () => {
       calls.push('move-top');
     },
-    onWindowsVisibleOverlayBlur: () => {
-      calls.push('windows-visible-blur');
+    onVisibleOverlayBlur: () => {
+      calls.push('visible-blur');
     },
     platform: 'darwin',
   });
 
   assert.equal(handled, false);
-  assert.deepEqual(calls, []);
+  assert.deepEqual(calls, ['visible-blur']);
 });
 
 test('handleOverlayWindowBlurred preserves active visible/modal window stacking', () => {

src/core/services/overlay-window.ts

@@ -180,7 +180,7 @@ export function createOverlayWindow(
       moveWindowTop: () => {
         window.moveTop();
       },
-      onWindowsVisibleOverlayBlur:
+      onVisibleOverlayBlur:
         kind === 'visible' ? () => options.onVisibleWindowBlurred?.() : undefined,
     });
   });

src/core/services/startup.test.ts

@@ -358,3 +358,89 @@ test('runAppReadyRuntime loads Yomitan before auto-initializing overlay runtime'
   assert.ok(calls.indexOf('init-overlay') !== -1);
   assert.ok(calls.indexOf('load-yomitan') < calls.indexOf('init-overlay'));
 });
+
+test('runAppReadyRuntime reuses guarded Yomitan loader after scheduling startup warmups', async () => {
+  const calls: string[] = [];
+
+  await runAppReadyRuntime({
+    ensureDefaultConfigBootstrap: () => {
+      calls.push('bootstrap');
+    },
+    loadSubtitlePosition: () => {
+      calls.push('load-subtitle-position');
+    },
+    resolveKeybindings: () => {
+      calls.push('resolve-keybindings');
+    },
+    createMpvClient: () => {
+      calls.push('create-mpv');
+    },
+    reloadConfig: () => {
+      calls.push('reload-config');
+    },
+    getResolvedConfig: () => ({
+      websocket: { enabled: false },
+      annotationWebsocket: { enabled: false },
+      texthooker: { launchAtStartup: false },
+    }),
+    getConfigWarnings: () => [],
+    logConfigWarning: () => {},
+    setLogLevel: () => {
+      calls.push('set-log-level');
+    },
+    initRuntimeOptionsManager: () => {
+      calls.push('init-runtime-options');
+    },
+    setSecondarySubMode: () => {
+      calls.push('set-secondary-sub-mode');
+    },
+    defaultSecondarySubMode: 'hover',
+    defaultWebsocketPort: 0,
+    defaultAnnotationWebsocketPort: 0,
+    defaultTexthookerPort: 0,
+    hasMpvWebsocketPlugin: () => false,
+    startSubtitleWebsocket: () => {},
+    startAnnotationWebsocket: () => {},
+    startTexthooker: () => {},
+    log: () => {
+      calls.push('log');
+    },
+    createMecabTokenizerAndCheck: async () => {},
+    createSubtitleTimingTracker: () => {
+      calls.push('subtitle-timing');
+    },
+    createImmersionTracker: () => {
+      calls.push('immersion');
+    },
+    startJellyfinRemoteSession: async () => {},
+    loadYomitanExtension: async () => {
+      calls.push('load-yomitan-direct');
+    },
+    ensureYomitanExtensionLoaded: async () => {
+      calls.push('load-yomitan-guarded');
+    },
+    handleFirstRunSetup: async () => {
+      calls.push('first-run');
+    },
+    prewarmSubtitleDictionaries: async () => {},
+    startBackgroundWarmups: () => {
+      calls.push('warmups');
+    },
+    texthookerOnlyMode: false,
+    shouldAutoInitializeOverlayRuntimeFromConfig: () => false,
+    setVisibleOverlayVisible: () => {
+      calls.push('visible-overlay');
+    },
+    initializeOverlayRuntime: () => {
+      calls.push('init-overlay');
+    },
+    handleInitialArgs: () => {
+      calls.push('handle-initial-args');
+    },
+    shouldUseMinimalStartup: () => false,
+    shouldSkipHeavyStartup: () => false,
+  });
+
+  assert.equal(calls.includes('load-yomitan-direct'), false);
+  assert.equal(calls.includes('load-yomitan-guarded'), true);
+});

src/core/services/startup.ts

@@ -131,6 +131,7 @@ export interface AppReadyRuntimeDeps {
   createImmersionTracker?: () => void;
   startJellyfinRemoteSession?: () => Promise<void>;
   loadYomitanExtension: () => Promise<void>;
+  ensureYomitanExtensionLoaded?: () => Promise<void>;
   handleFirstRunSetup: () => Promise<void>;
   prewarmSubtitleDictionaries?: () => Promise<void>;
   startBackgroundWarmups: () => void;
@@ -215,6 +216,8 @@ export function isAutoUpdateEnabledRuntime(
 export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<void> {
   const now = deps.now ?? (() => Date.now());
   const startupStartedAtMs = now();
+  const ensureYomitanExtensionReady =
+    deps.ensureYomitanExtensionLoaded ?? deps.loadYomitanExtension;
   deps.ensureDefaultConfigBootstrap();
   if (deps.shouldRunHeadlessInitialCommand?.()) {
     deps.reloadConfig();
@@ -224,7 +227,7 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
     } else {
       deps.createMpvClient();
       deps.createSubtitleTimingTracker();
-      await deps.loadYomitanExtension();
+      await ensureYomitanExtensionReady();
       deps.initializeOverlayRuntime();
       deps.handleInitialArgs();
     }
@@ -237,18 +240,10 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
     return;
   }
 
-  if (deps.shouldSkipHeavyStartup?.()) {
-    await deps.loadYomitanExtension();
-    deps.reloadConfig();
-    await deps.handleFirstRunSetup();
-    deps.handleInitialArgs();
-    return;
-  }
-
   deps.logDebug?.('App-ready critical path started.');
 
   if (deps.shouldSkipHeavyStartup?.()) {
-    await deps.loadYomitanExtension();
+    await ensureYomitanExtensionReady();
     deps.reloadConfig();
     await deps.handleFirstRunSetup();
     deps.handleInitialArgs();
@@ -319,12 +314,12 @@ export async function runAppReadyRuntime(deps: AppReadyRuntimeDeps): Promise<voi
   if (deps.texthookerOnlyMode) {
     deps.log('Texthooker-only mode enabled; skipping overlay window.');
   } else if (deps.shouldAutoInitializeOverlayRuntimeFromConfig()) {
-    await deps.loadYomitanExtension();
+    await ensureYomitanExtensionReady();
     deps.setVisibleOverlayVisible(true);
     deps.initializeOverlayRuntime();
   } else {
     deps.log('Overlay runtime deferred: waiting for explicit overlay command.');
-    await deps.loadYomitanExtension();
+    await ensureYomitanExtensionReady();
   }
 
   await deps.handleFirstRunSetup();

src/core/services/stats-window-runtime.ts

@@ -9,6 +9,8 @@ type StatsWindowLevelController = Pick<BrowserWindow, 'setAlwaysOnTop' | 'moveTo
   Partial<Pick<BrowserWindow, 'setVisibleOnAllWorkspaces' | 'setFullScreenable'>>;
 
 type StatsWindowBoundsController = Pick<BrowserWindow, 'getBounds' | 'getContentBounds'>;
+type StatsWindowPresentationController = Pick<BrowserWindow, 'show' | 'focus'> &
+  Partial<Pick<BrowserWindow, 'showInactive'>>;
 
 function isBareToggleKeyInput(input: Electron.Input, toggleKey: string): boolean {
   return (
@@ -104,6 +106,23 @@ export function promoteStatsWindowLevel(
   window.moveTop();
 }
 
+export function presentStatsWindow(
+  window: StatsWindowPresentationController,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform === 'darwin') {
+    if (window.showInactive) {
+      window.showInactive();
+    } else {
+      window.show();
+    }
+    return;
+  }
+
+  window.show();
+  window.focus();
+}
+
 export function buildStatsWindowLoadFileOptions(apiBaseUrl?: string): {
   query: Record<string, string>;
 } {

src/core/services/stats-window.test.ts

@@ -3,6 +3,7 @@ import test from 'node:test';
 import {
   buildStatsWindowLoadFileOptions,
   buildStatsWindowOptions,
+  presentStatsWindow,
   promoteStatsWindowLevel,
   resolveStatsWindowOuterBoundsForContent,
   shouldHideStatsWindowForInput,
@@ -230,3 +231,45 @@ test('promoteStatsWindowLevel raises stats above overlay level on Windows', () =
 
   assert.deepEqual(calls, ['always-on-top:true:screen-saver:2', 'move-top']);
 });
+
+test('presentStatsWindow shows inactive on macOS to stay on the fullscreen mpv Space', () => {
+  const calls: string[] = [];
+
+  presentStatsWindow(
+    {
+      show: () => {
+        calls.push('show');
+      },
+      showInactive: () => {
+        calls.push('show-inactive');
+      },
+      focus: () => {
+        calls.push('focus');
+      },
+    } as never,
+    'darwin',
+  );
+
+  assert.deepEqual(calls, ['show-inactive']);
+});
+
+test('presentStatsWindow shows and focuses on non-macOS platforms', () => {
+  const calls: string[] = [];
+
+  presentStatsWindow(
+    {
+      show: () => {
+        calls.push('show');
+      },
+      showInactive: () => {
+        calls.push('show-inactive');
+      },
+      focus: () => {
+        calls.push('focus');
+      },
+    } as never,
+    'linux',
+  );
+
+  assert.deepEqual(calls, ['show', 'focus']);
+});

src/core/services/stats-window.ts

@@ -5,6 +5,7 @@ import { IPC_CHANNELS } from '../../shared/ipc/contracts.js';
 import {
   buildStatsWindowLoadFileOptions,
   buildStatsWindowOptions,
+  presentStatsWindow,
   promoteStatsWindowLevel,
   resolveStatsWindowOuterBoundsForContent,
   shouldHideStatsWindowForInput,
@@ -49,14 +50,13 @@ function showStatsWindow(window: BrowserWindow, options: StatsWindowOptions): vo
   const bounds = options.resolveBounds();
   let placementBounds = syncStatsWindowBounds(window, bounds);
   promoteStatsWindowLevel(window);
-  window.show();
+  presentStatsWindow(window);
   placementBounds = syncStatsWindowBounds(window, bounds) ?? placementBounds;
   if (
     !ensureHyprlandWindowFloatingByTitle({ title: STATS_WINDOW_TITLE, bounds: placementBounds })
   ) {
     placementBounds = syncStatsWindowBounds(window, bounds) ?? placementBounds;
   }
-  window.focus();
   options.onVisibilityChanged?.(true);
   promoteStatsWindowLevel(window);
 }

src/core/services/yomitan-extension-loader.test.ts

@@ -9,6 +9,7 @@ import {
   ensureExtensionCopyAsync,
   shouldCopyYomitanExtension,
 } from './yomitan-extension-copy';
+import { withSuppressedYomitanExtensionWarnings } from './yomitan-extension-loader';
 
 function makeTempDir(prefix: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
@@ -19,6 +20,66 @@ function writeFile(filePath: string, content: string): void {
   fs.writeFileSync(filePath, content, 'utf-8');
 }
 
+test('suppresses Yomitan contextMenus extension load warnings only while loading', async () => {
+  const emitted: string[] = [];
+  const warningProcess = {
+    emitWarning: (warning: string | Error, options?: { type?: string }) => {
+      const message = warning instanceof Error ? warning.message : warning;
+      emitted.push(`${options?.type ?? ''}:${message}`);
+    },
+  } as Pick<NodeJS.Process, 'emitWarning'>;
+
+  await withSuppressedYomitanExtensionWarnings(async () => {
+    warningProcess.emitWarning(
+      "Warnings loading extension:\nPermission 'contextMenus' is unknown.",
+      {
+        type: 'ExtensionLoadWarning',
+      },
+    );
+    warningProcess.emitWarning('Other extension warning', { type: 'ExtensionLoadWarning' });
+    return null;
+  }, warningProcess);
+
+  warningProcess.emitWarning("Permission 'contextMenus' is unknown.", {
+    type: 'ExtensionLoadWarning',
+  });
+
+  assert.deepEqual(emitted, [
+    'ExtensionLoadWarning:Other extension warning',
+    "ExtensionLoadWarning:Permission 'contextMenus' is unknown.",
+  ]);
+});
+
+test('suppressed Yomitan warning wrapper is re-entrant safe', async () => {
+  const emitted: string[] = [];
+  const warningProcess = {
+    emitWarning: (warning: string | Error, options?: { type?: string }) => {
+      const message = warning instanceof Error ? warning.message : warning;
+      emitted.push(`${options?.type ?? ''}:${message}`);
+    },
+  } as Pick<NodeJS.Process, 'emitWarning'>;
+  const originalEmitWarning = warningProcess.emitWarning;
+
+  await withSuppressedYomitanExtensionWarnings(async () => {
+    await withSuppressedYomitanExtensionWarnings(async () => {
+      warningProcess.emitWarning("Permission 'contextMenus' is unknown.", {
+        type: 'ExtensionLoadWarning',
+      });
+      warningProcess.emitWarning('Nested warning', { type: 'ExtensionLoadWarning' });
+    }, warningProcess);
+    warningProcess.emitWarning("Permission 'contextMenus' is unknown.", {
+      type: 'ExtensionLoadWarning',
+    });
+    warningProcess.emitWarning('Outer warning', { type: 'ExtensionLoadWarning' });
+  }, warningProcess);
+
+  assert.equal(warningProcess.emitWarning, originalEmitWarning);
+  assert.deepEqual(emitted, [
+    'ExtensionLoadWarning:Nested warning',
+    'ExtensionLoadWarning:Outer warning',
+  ]);
+});
+
 test('shouldCopyYomitanExtension detects popup runtime script drift', () => {
   const tempRoot = makeTempDir('subminer-yomitan-copy-');
   const sourceDir = path.join(tempRoot, 'source');
@@ -185,10 +246,7 @@ test('ensureExtensionCopyAsync shares an in-flight refresh for the same copied e
     assert.equal(results[0].copied, true);
     assert.equal(results[1].copied, true);
     assert.equal(
-      fs.readFileSync(
-        path.join(targetDir, 'js', 'pages', 'settings', 'settings-main.js'),
-        'utf8',
-      ),
+      fs.readFileSync(path.join(targetDir, 'js', 'pages', 'settings', 'settings-main.js'), 'utf8'),
       'new settings code',
     );
   } finally {

src/core/services/yomitan-extension-loader.ts

@@ -29,6 +29,85 @@ export interface YomitanExtensionLoaderDeps {
   setYomitanSession: (session: Session | null) => void;
 }
 
+type WarningProcess = Pick<NodeJS.Process, 'emitWarning'>;
+
+const suppressedWarningState = new WeakMap<
+  WarningProcess,
+  {
+    count: number;
+    originalEmitWarning: WarningProcess['emitWarning'];
+  }
+>();
+
+function getWarningType(warning: string | Error, args: unknown[]): string | undefined {
+  if (typeof warning !== 'string') {
+    return warning.name;
+  }
+  const firstArg = args[0];
+  if (typeof firstArg === 'string') {
+    return firstArg;
+  }
+  if (firstArg && typeof firstArg === 'object' && 'type' in firstArg) {
+    const type = (firstArg as { type?: unknown }).type;
+    return typeof type === 'string' ? type : undefined;
+  }
+  return undefined;
+}
+
+function shouldSuppressYomitanExtensionWarning(warning: string | Error, args: unknown[]): boolean {
+  const message = warning instanceof Error ? warning.message : warning;
+  return (
+    getWarningType(warning, args) === 'ExtensionLoadWarning' &&
+    message.includes("Permission 'contextMenus' is unknown.")
+  );
+}
+
+export async function withSuppressedYomitanExtensionWarnings<T>(
+  run: () => Promise<T>,
+  warningProcess: WarningProcess = process,
+): Promise<T> {
+  const existingState = suppressedWarningState.get(warningProcess);
+  if (existingState) {
+    existingState.count++;
+    try {
+      return await run();
+    } finally {
+      existingState.count--;
+      if (existingState.count === 0) {
+        warningProcess.emitWarning = existingState.originalEmitWarning;
+        suppressedWarningState.delete(warningProcess);
+      }
+    }
+  }
+
+  const originalEmitWarning = warningProcess.emitWarning;
+  const state = {
+    count: 1,
+    originalEmitWarning,
+  };
+  suppressedWarningState.set(warningProcess, state);
+  warningProcess.emitWarning = ((warning: string | Error, ...args: unknown[]) => {
+    if (shouldSuppressYomitanExtensionWarning(warning, args)) {
+      return;
+    }
+    return (originalEmitWarning as (...emitArgs: unknown[]) => void).call(
+      warningProcess,
+      warning,
+      ...args,
+    );
+  }) as typeof process.emitWarning;
+
+  try {
+    return await run();
+  } finally {
+    state.count--;
+    if (state.count === 0) {
+      warningProcess.emitWarning = originalEmitWarning;
+      suppressedWarningState.delete(warningProcess);
+    }
+  }
+}
+
 export async function loadYomitanExtension(
   deps: YomitanExtensionLoaderDeps,
 ): Promise<Extension | null> {
@@ -79,9 +158,20 @@ export async function loadYomitanExtension(
       return null;
     }
 
-    const extensionCopy = await ensureExtensionCopyAsync(extPath, deps.userDataPath);
+    let extensionCopy: { copied: boolean; targetDir: string };
+    try {
+      extensionCopy = await ensureExtensionCopyAsync(extPath, deps.userDataPath);
+    } catch (error) {
+      logger.error('Failed to copy Yomitan extension:', {
+        error,
+        extensionPath: extPath,
+        userDataPath: deps.userDataPath,
+      });
+      clearRuntimeState();
+      return null;
+    }
     if (extensionCopy.copied) {
-      logger.info(`Copied yomitan extension to ${extensionCopy.targetDir}`);
+      logger.debug(`Copied yomitan extension to ${extensionCopy.targetDir}`);
     }
     extPath = extensionCopy.targetDir;
   }
@@ -91,13 +181,15 @@ export async function loadYomitanExtension(
 
   try {
     const extensions = targetSession.extensions;
-    const extension = extensions
-      ? await extensions.loadExtension(extPath, {
-          allowFileAccess: true,
-        })
-      : await targetSession.loadExtension(extPath, {
-          allowFileAccess: true,
-        });
+    const extension = await withSuppressedYomitanExtensionWarnings(() =>
+      extensions
+        ? extensions.loadExtension(extPath, {
+            allowFileAccess: true,
+          })
+        : targetSession.loadExtension(extPath, {
+            allowFileAccess: true,
+          }),
+    );
     deps.setYomitanExtension(extension);
     return extension;
   } catch (err) {

src/core/services/yomitan-settings.test.ts

@@ -2,27 +2,101 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 
 import {
+  buildYomitanSettingsCloseButtonScript,
+  buildYomitanSettingsWindowMenuTemplate,
   buildYomitanSettingsUrl,
   configureYomitanSettingsWindowChrome,
   destroyYomitanSettingsWindow,
+  installYomitanSettingsCloseButton,
   showYomitanSettingsWindow,
+  shouldInstallYomitanSettingsCloseButton,
 } from './yomitan-settings';
 
-test('yomitan settings window removes default app menu quit action', () => {
+test('yomitan settings window uses a close-only menu without app quit', () => {
   const calls: string[] = [];
 
   configureYomitanSettingsWindowChrome({
+    isDestroyed: () => false,
+    close: () => calls.push('close'),
     setAutoHideMenuBar: (hide: boolean) => calls.push(`auto-hide:${hide}`),
     setMenu: (menu: unknown) => calls.push(`menu:${menu === null ? 'null' : 'custom'}`),
-  } as never);
+  } as never, (template) => {
+    calls.push(`menu-label:${template[0]?.label ?? ''}`);
+    const submenu = template[0]?.submenu;
+    assert.ok(Array.isArray(submenu));
+    const closeItem = submenu[0];
+    assert.equal(closeItem?.label, 'Close');
+    assert.notEqual(closeItem?.role, 'quit');
+    closeItem?.click?.({} as never, {} as never, {} as never);
+    return { id: 'settings-menu' } as never;
+  });
 
-  assert.deepEqual(calls, ['auto-hide:true', 'menu:null']);
+  assert.deepEqual(calls, ['auto-hide:false', 'menu-label:File', 'close', 'menu:custom']);
+});
+
+test('yomitan settings close menu skips destroyed windows', () => {
+  const calls: string[] = [];
+  const template = buildYomitanSettingsWindowMenuTemplate({
+    isDestroyed: () => true,
+    close: () => calls.push('close'),
+  } as never);
+  const submenu = template[0]?.submenu;
+  assert.ok(Array.isArray(submenu));
+  submenu[0]?.click?.({} as never, {} as never, {} as never);
+  assert.deepEqual(calls, []);
+});
+
+test('yomitan settings close button script installs an idempotent in-page close control', () => {
+  const script = buildYomitanSettingsCloseButtonScript();
+
+  assert.match(script, /subminer-yomitan-settings-close/);
+  assert.match(script, /aria-label', 'Close Yomitan settings'/);
+  assert.match(script, /window\.close\(\)/);
+  assert.match(script, /getElementById\(buttonId\)/);
+});
+
+test('yomitan settings close button only installs for Hyprland sessions', () => {
+  assert.equal(
+    shouldInstallYomitanSettingsCloseButton('linux', { HYPRLAND_INSTANCE_SIGNATURE: 'hypr' }),
+    true,
+  );
+  assert.equal(
+    shouldInstallYomitanSettingsCloseButton('linux', { HYPRLAND_INSTANCE_SIGNATURE: '' }),
+    false,
+  );
+  assert.equal(
+    shouldInstallYomitanSettingsCloseButton('darwin', { HYPRLAND_INSTANCE_SIGNATURE: 'hypr' }),
+    false,
+  );
+  assert.equal(
+    shouldInstallYomitanSettingsCloseButton('win32', { HYPRLAND_INSTANCE_SIGNATURE: 'hypr' }),
+    false,
+  );
+});
+
+test('yomitan settings close button injection skips non-Hyprland windows', () => {
+  const calls: string[] = [];
+
+  installYomitanSettingsCloseButton(
+    {
+      isDestroyed: () => false,
+      webContents: {
+        executeJavaScript: () => {
+          calls.push('execute');
+          return Promise.resolve();
+        },
+      },
+    } as never,
+    { platform: 'darwin', env: { HYPRLAND_INSTANCE_SIGNATURE: 'hypr' } },
+  );
+
+  assert.deepEqual(calls, []);
 });
 
 test('yomitan settings URL disables the embedded popup preview', () => {
   assert.equal(
     buildYomitanSettingsUrl('abc123'),
-    'chrome-extension://abc123/settings.html?popup-preview=false&subminer-settings-safe=true',
+    'chrome-extension://abc123/settings.html?popup-preview=false',
   );
 });
 

src/core/services/yomitan-settings.ts

@@ -1,8 +1,8 @@
 import electron from 'electron';
-import type { BrowserWindow, Extension, Session } from 'electron';
+import type { BrowserWindow, Extension, Menu, MenuItemConstructorOptions, Session } from 'electron';
 import { createLogger } from '../../logger';
 
-const { BrowserWindow: ElectronBrowserWindow, session } = electron;
+const { BrowserWindow: ElectronBrowserWindow, Menu: ElectronMenu, session } = electron;
 const logger = createLogger('main:yomitan-settings');
 
 export interface OpenYomitanSettingsWindowOptions {
@@ -13,15 +13,127 @@ export interface OpenYomitanSettingsWindowOptions {
   onWindowClosed?: () => void;
 }
 
-export function configureYomitanSettingsWindowChrome(
-  settingsWindow: Pick<BrowserWindow, 'setAutoHideMenuBar' | 'setMenu'>,
+type YomitanSettingsWindowMenuOwner = Pick<BrowserWindow, 'close' | 'isDestroyed'>;
+
+type HyprlandSessionEnv = {
+  HYPRLAND_INSTANCE_SIGNATURE?: string;
+};
+
+export interface InstallYomitanSettingsCloseButtonOptions {
+  platform?: NodeJS.Platform;
+  env?: HyprlandSessionEnv;
+}
+
+export function shouldInstallYomitanSettingsCloseButton(
+  platform: NodeJS.Platform = process.platform,
+  env: HyprlandSessionEnv = process.env,
+): boolean {
+  return platform === 'linux' && Boolean(env.HYPRLAND_INSTANCE_SIGNATURE);
+}
+
+export function buildYomitanSettingsWindowMenuTemplate(
+  settingsWindow: YomitanSettingsWindowMenuOwner,
+): MenuItemConstructorOptions[] {
+  return [
+    {
+      label: 'File',
+      submenu: [
+        {
+          label: 'Close',
+          accelerator: process.platform === 'darwin' ? 'Command+W' : 'Ctrl+W',
+          click: () => {
+            if (!settingsWindow.isDestroyed()) {
+              settingsWindow.close();
+            }
+          },
+        },
+      ],
+    },
+  ];
+}
+
+export function buildYomitanSettingsCloseButtonScript(): string {
+  return `
+(() => {
+  const buttonId = 'subminer-yomitan-settings-close';
+  const styleId = 'subminer-yomitan-settings-close-style';
+  if (document.getElementById(buttonId)) {
+    return;
+  }
+  if (!document.getElementById(styleId)) {
+    const style = document.createElement('style');
+    style.id = styleId;
+    style.textContent = \`
+      #\${buttonId} {
+        position: fixed;
+        top: 10px;
+        left: 10px;
+        z-index: 2147483647;
+        width: 32px;
+        height: 32px;
+        display: grid;
+        place-items: center;
+        padding: 0;
+        border: 1px solid rgba(255, 255, 255, 0.28);
+        border-radius: 4px;
+        background: rgba(24, 24, 24, 0.92);
+        color: #f2f2f2;
+        font: 22px/1 system-ui, sans-serif;
+        cursor: pointer;
+      }
+      #\${buttonId}:hover {
+        background: rgba(54, 54, 54, 0.96);
+        border-color: rgba(255, 255, 255, 0.5);
+      }
+      #\${buttonId}:focus-visible {
+        outline: 2px solid #8ab4f8;
+        outline-offset: 2px;
+      }
+    \`;
+    document.head.appendChild(style);
+  }
+  const button = document.createElement('button');
+  button.id = buttonId;
+  button.type = 'button';
+  button.title = 'Close';
+  button.setAttribute('aria-label', 'Close Yomitan settings');
+  button.textContent = '\\u00d7';
+  button.addEventListener('click', () => {
+    window.close();
+  });
+  document.body.appendChild(button);
+})();
+`;
+}
+
+export function installYomitanSettingsCloseButton(
+  settingsWindow: Pick<BrowserWindow, 'isDestroyed' | 'webContents'>,
+  options: InstallYomitanSettingsCloseButtonOptions = {},
 ): void {
-  settingsWindow.setAutoHideMenuBar(true);
-  settingsWindow.setMenu(null);
+  if (settingsWindow.isDestroyed()) {
+    return;
+  }
+  if (!shouldInstallYomitanSettingsCloseButton(options.platform, options.env)) {
+    return;
+  }
+  settingsWindow.webContents
+    .executeJavaScript(buildYomitanSettingsCloseButtonScript())
+    .catch((error: Error) => {
+      logger.warn('Failed to install Yomitan settings close button:', error.message);
+    });
+}
+
+export function configureYomitanSettingsWindowChrome(
+  settingsWindow: Pick<BrowserWindow, 'close' | 'isDestroyed' | 'setAutoHideMenuBar' | 'setMenu'>,
+  buildMenu: (template: MenuItemConstructorOptions[]) => Menu = (template) =>
+    ElectronMenu.buildFromTemplate(template),
+): void {
+  settingsWindow.setAutoHideMenuBar(false);
+  settingsWindow.setMenu(buildMenu(buildYomitanSettingsWindowMenuTemplate(settingsWindow)));
 }
 
 export function buildYomitanSettingsUrl(extensionId: string): string {
-  return `chrome-extension://${extensionId}/settings.html?popup-preview=false&subminer-settings-safe=true`;
+  return `chrome-extension://${extensionId}/settings.html?popup-preview=false`;
 }
 
 export function showYomitanSettingsWindow(settingsWindow: BrowserWindow): void {
@@ -108,6 +220,7 @@ export function openYomitanSettingsWindow(options: OpenYomitanSettingsWindowOpti
 
   settingsWindow.webContents.on('did-finish-load', () => {
     logger.info('Settings page loaded successfully');
+    installYomitanSettingsCloseButton(settingsWindow);
   });
 
   setTimeout(() => {

src/main.ts

@@ -82,6 +82,7 @@ function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
   return {
     shouldUseMinimalStartup: Boolean(
       (initialArgs && isStandaloneTexthookerCommand(initialArgs)) ||
+      initialArgs?.update ||
       (initialArgs?.stats &&
         (initialArgs.statsCleanup || initialArgs.statsBackground || initialArgs.statsStop)),
     ),
@@ -90,6 +91,7 @@ function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
       (shouldRunSettingsOnlyStartup(initialArgs) ||
         initialArgs.stats ||
         initialArgs.dictionary ||
+        initialArgs.update ||
         initialArgs.setup),
     ),
   };
@@ -365,6 +367,7 @@ import { toggleStatsOverlay as toggleStatsOverlayWindow } from './core/services/
 import {
   createFirstRunSetupService,
   getFirstRunSetupCompletionMessage,
+  isStandaloneFirstRunSetupCommand,
   shouldAutoOpenFirstRunSetup,
 } from './main/runtime/first-run-setup-service';
 import { createYoutubeFlowRuntime } from './main/runtime/youtube-flow';
@@ -483,13 +486,13 @@ import { createOverlayModalInputState } from './main/runtime/overlay-modal-input
 import { openYoutubeTrackPicker } from './main/runtime/youtube-picker-open';
 import { openRuntimeOptionsModal as openRuntimeOptionsModalRuntime } from './main/runtime/runtime-options-open';
 import { openJimakuModal as openJimakuModalRuntime } from './main/runtime/jimaku-open';
+import { openSubsyncManualModal as openSubsyncManualModalRuntime } from './main/runtime/subsync-open';
 import { openSessionHelpModal as openSessionHelpModalRuntime } from './main/runtime/session-help-open';
 import { openCharacterDictionaryModal as openCharacterDictionaryModalRuntime } from './main/runtime/character-dictionary-open';
 import { openControllerSelectModal as openControllerSelectModalRuntime } from './main/runtime/controller-select-open';
 import { openControllerDebugModal as openControllerDebugModalRuntime } from './main/runtime/controller-debug-open';
 import { createPlaylistBrowserIpcRuntime } from './main/runtime/playlist-browser-ipc';
 import { writeSessionBindingsArtifact } from './main/runtime/session-bindings-artifact';
-import { openOverlayHostedModal } from './main/runtime/overlay-hosted-modal-open';
 import { createOverlayShortcutsRuntimeService } from './main/overlay-shortcuts-runtime';
 import {
   createFrequencyDictionaryRuntimeService,
@@ -508,22 +511,21 @@ import { handleCharacterDictionaryAutoSyncComplete } from './main/runtime/charac
 import { notifyCharacterDictionaryAutoSyncStatus } from './main/runtime/character-dictionary-auto-sync-notifications';
 import { createCurrentMediaTokenizationGate } from './main/runtime/current-media-tokenization-gate';
 import { createStartupOsdSequencer } from './main/runtime/startup-osd-sequencer';
-import { createElectronAppUpdater } from './main/runtime/update/app-updater';
+import {
+  createElectronAppUpdater,
+  isNativeUpdaterSupported,
+} from './main/runtime/update/app-updater';
 import {
   fetchLatestStableRelease,
   fetchReleaseAssetBuffer,
   fetchReleaseAssetText,
   findReleaseAsset,
   parseSha256Sums,
+  type GitHubRelease,
 } from './main/runtime/update/release-assets';
 import { updateLauncherFromRelease } from './main/runtime/update/launcher-updater';
 import { notifyUpdateAvailable } from './main/runtime/update/update-notifications';
-import {
-  showNoUpdateDialog,
-  showRestartDialog,
-  showUpdateAvailableDialog,
-  showUpdateFailedDialog,
-} from './main/runtime/update/update-dialogs';
+import { createUpdateDialogPresenter } from './main/runtime/update/update-dialogs';
 import {
   runUpdateCliCommand,
   writeUpdateCliCommandResponse,
@@ -847,6 +849,9 @@ const appLogger = {
   logInfo: (message: string) => {
     logger.info(message);
   },
+  logDebug: (message: string) => {
+    logger.debug(message);
+  },
   logWarning: (message: string) => {
     logger.warn(message);
   },
@@ -1479,9 +1484,11 @@ const buildMainSubsyncRuntimeMainDepsHandler = createBuildMainSubsyncRuntimeMain
   },
   showMpvOsd: (text) => showMpvOsd(text),
   openManualPicker: (payload) => {
-    sendToActiveOverlayWindow('subsync:open-manual', payload, {
-      restoreOnModalClose: 'subsync',
-    });
+    openOverlayHostedModalWithOsd(
+      (deps) => openSubsyncManualModalRuntime(deps, payload),
+      'Subsync overlay unavailable.',
+      'Failed to open subsync overlay.',
+    );
   },
 });
 const immersionMediaRuntime = createImmersionMediaRuntime(
@@ -2062,6 +2069,7 @@ const overlayVisibilityRuntime = createOverlayVisibilityRuntimeService(
     getModalActive: () => overlayModalInputState.getModalInputExclusive(),
     getVisibleOverlayVisible: () => overlayManager.getVisibleOverlayVisible(),
     getForceMousePassthrough: () => appState.statsOverlayVisible,
+    getOverlayInteractionActive: () => visibleOverlayInteractionActive,
     getWindowTracker: () => appState.windowTracker,
     getLastKnownWindowsForegroundProcessName: () => lastWindowsVisibleOverlayForegroundProcessName,
     getWindowsOverlayProcessName: () => path.parse(process.execPath).name.toLowerCase(),
@@ -2105,23 +2113,24 @@ const overlayVisibilityRuntime = createOverlayVisibilityRuntimeService(
   })(),
 );
 
-const WINDOWS_VISIBLE_OVERLAY_BLUR_REFRESH_DELAYS_MS = [0, 25, 100, 250] as const;
+const VISIBLE_OVERLAY_BLUR_REFRESH_DELAYS_MS = [0, 25, 100, 250] as const;
 const WINDOWS_VISIBLE_OVERLAY_Z_ORDER_RETRY_DELAYS_MS = [0, 48, 120, 240, 480] as const;
 const WINDOWS_VISIBLE_OVERLAY_FOREGROUND_POLL_INTERVAL_MS = 75;
 const WINDOWS_VISIBLE_OVERLAY_FOCUS_HANDOFF_GRACE_MS = 200;
-let windowsVisibleOverlayBlurRefreshTimeouts: Array<ReturnType<typeof setTimeout>> = [];
+let visibleOverlayBlurRefreshTimeouts: Array<ReturnType<typeof setTimeout>> = [];
 let windowsVisibleOverlayZOrderRetryTimeouts: Array<ReturnType<typeof setTimeout>> = [];
 let windowsVisibleOverlayZOrderSyncInFlight = false;
 let windowsVisibleOverlayZOrderSyncQueued = false;
 let windowsVisibleOverlayForegroundPollInterval: ReturnType<typeof setInterval> | null = null;
 let lastWindowsVisibleOverlayForegroundProcessName: string | null = null;
 let lastWindowsVisibleOverlayBlurredAtMs = 0;
+let visibleOverlayInteractionActive = false;
 
-function clearWindowsVisibleOverlayBlurRefreshTimeouts(): void {
-  for (const timeout of windowsVisibleOverlayBlurRefreshTimeouts) {
+function clearVisibleOverlayBlurRefreshTimeouts(): void {
+  for (const timeout of visibleOverlayBlurRefreshTimeouts) {
     clearTimeout(timeout);
   }
-  windowsVisibleOverlayBlurRefreshTimeouts = [];
+  visibleOverlayBlurRefreshTimeouts = [];
 }
 
 function clearWindowsVisibleOverlayZOrderRetryTimeouts(): void {
@@ -2322,20 +2331,22 @@ function clearWindowsVisibleOverlayForegroundPollLoop(): void {
 }
 
 function scheduleVisibleOverlayBlurRefresh(): void {
-  if (process.platform !== 'win32') {
+  if (process.platform !== 'win32' && process.platform !== 'darwin') {
     return;
   }
 
-  lastWindowsVisibleOverlayBlurredAtMs = Date.now();
-  clearWindowsVisibleOverlayBlurRefreshTimeouts();
-  for (const delayMs of WINDOWS_VISIBLE_OVERLAY_BLUR_REFRESH_DELAYS_MS) {
+  if (process.platform === 'win32') {
+    lastWindowsVisibleOverlayBlurredAtMs = Date.now();
+  }
+  clearVisibleOverlayBlurRefreshTimeouts();
+  for (const delayMs of VISIBLE_OVERLAY_BLUR_REFRESH_DELAYS_MS) {
     const refreshTimeout = setTimeout(() => {
-      windowsVisibleOverlayBlurRefreshTimeouts = windowsVisibleOverlayBlurRefreshTimeouts.filter(
+      visibleOverlayBlurRefreshTimeouts = visibleOverlayBlurRefreshTimeouts.filter(
         (timeout) => timeout !== refreshTimeout,
       );
       overlayVisibilityRuntime.updateVisibleOverlayVisibility();
     }, delayMs);
-    windowsVisibleOverlayBlurRefreshTimeouts.push(refreshTimeout);
+    visibleOverlayBlurRefreshTimeouts.push(refreshTimeout);
   }
 }
 
@@ -2900,6 +2911,8 @@ const openFirstRunSetupWindowHandler = createOpenFirstRunSetupWindowHandler({
   },
   isSetupCompleted: () => firstRunSetupService.isSetupCompleted(),
   shouldQuitWhenClosedIncomplete: () => !appState.backgroundMode,
+  shouldQuitWhenClosedCompleted: () =>
+    Boolean(appState.initialArgs && isStandaloneFirstRunSetupCommand(appState.initialArgs)),
   quitApp: () => requestAppQuit(),
   clearSetupWindow: () => {
     appState.firstRunSetupWindow = null;
@@ -3034,6 +3047,7 @@ const {
   resetAnilistMediaTracking,
   getAnilistMediaGuessRuntimeState,
   setAnilistMediaGuessRuntimeState,
+  recordAnilistMediaDuration,
   resetAnilistMediaGuessState,
   maybeProbeAnilistDuration,
   ensureAnilistMediaGuess,
@@ -3137,6 +3151,13 @@ const {
       );
     },
   },
+  recordMediaDurationMainDeps: {
+    getCurrentMediaKey: () => getCurrentAnilistMediaKey(),
+    getState: () => getAnilistMediaGuessRuntimeState(),
+    setState: (state) => {
+      setAnilistMediaGuessRuntimeState(state);
+    },
+  },
   resetMediaGuessStateMainDeps: {
     setMediaGuess: (value) => {
       anilistMediaGuessRuntimeState = transitionAnilistMediaGuessRuntimeState(
@@ -3188,9 +3209,10 @@ const {
       );
     },
     refreshAnilistClientSecretState: () => refreshAnilistClientSecretState(),
-    updateAnilistPostWatchProgress: (accessToken, title, episode) =>
+    updateAnilistPostWatchProgress: (accessToken, title, episode, season) =>
       updateAnilistPostWatchProgress(accessToken, title, episode, {
         rateLimiter: anilistRateLimiter,
+        season,
       }),
     markSuccess: (key) => {
       anilistUpdateQueue.markSuccess(key);
@@ -3221,13 +3243,13 @@ const {
       resetAnilistMediaTracking(mediaKey);
     },
     getWatchedSeconds: () => appState.mpvClient?.currentTimePos ?? Number.NaN,
-    maybeProbeAnilistDuration: (mediaKey) => maybeProbeAnilistDuration(mediaKey),
+    maybeProbeAnilistDuration: (mediaKey, options) => maybeProbeAnilistDuration(mediaKey, options),
     ensureAnilistMediaGuess: (mediaKey) => ensureAnilistMediaGuess(mediaKey),
     hasAttemptedUpdateKey: (key) => anilistAttemptedUpdateKeys.has(key),
     processNextAnilistRetryUpdate: () => processNextAnilistRetryUpdate(),
     refreshAnilistClientSecretState: () => refreshAnilistClientSecretState(),
-    enqueueRetry: (key, title, episode) => {
-      anilistUpdateQueue.enqueue(key, title, episode);
+    enqueueRetry: (key, title, episode, season) => {
+      anilistUpdateQueue.enqueue(key, title, episode, season);
     },
     markRetryFailure: (key, message) => {
       anilistUpdateQueue.markFailure(key, message);
@@ -3236,9 +3258,10 @@ const {
       anilistUpdateQueue.markSuccess(key);
     },
     refreshRetryQueueState: () => anilistStateRuntime.refreshRetryQueueState(),
-    updateAnilistPostWatchProgress: (accessToken, title, episode) =>
+    updateAnilistPostWatchProgress: (accessToken, title, episode, season) =>
       updateAnilistPostWatchProgress(accessToken, title, episode, {
         rateLimiter: anilistRateLimiter,
+        season,
       }),
     rememberAttemptedUpdateKey: (key) => {
       rememberAnilistAttemptedUpdate(key);
@@ -3731,6 +3754,7 @@ const { appReadyRuntimeRunner } = composeAppReadyRuntime({
   reloadConfigMainDeps: {
     reloadConfigStrict: () => configService.reloadConfigStrict(),
     logInfo: (message) => appLogger.logInfo(message),
+    logDebug: (message) => appLogger.logDebug(message),
     logWarning: (message) => appLogger.logWarning(message),
     showDesktopNotification: (title, options) => showDesktopNotification(title, options),
     startConfigHotReload: () => configHotReloadRuntime.start(),
@@ -3854,6 +3878,9 @@ const { appReadyRuntimeRunner } = composeAppReadyRuntime({
     loadYomitanExtension: async () => {
       await loadYomitanExtension();
     },
+    ensureYomitanExtensionLoaded: async () => {
+      await ensureYomitanExtensionLoaded();
+    },
     handleFirstRunSetup: async () => {
       const snapshot = await firstRunSetupService.ensureSetupStateInitialized();
       appState.firstRunSetupCompleted = snapshot.state.status === 'completed';
@@ -3971,7 +3998,10 @@ const {
     reportJellyfinRemoteStopped: () => {
       void reportJellyfinRemoteStopped();
     },
-    maybeRunAnilistPostWatchUpdate: () => maybeRunAnilistPostWatchUpdate(),
+    maybeRunAnilistPostWatchUpdate: (options) => maybeRunAnilistPostWatchUpdate(options),
+    recordAnilistMediaDuration: (durationSec) => {
+      recordAnilistMediaDuration(durationSec);
+    },
     logSubtitleTimingError: (message, error) => logger.error(message, error),
     broadcastToOverlayWindows: (channel, payload) => {
       broadcastToOverlayWindows(channel, payload);
@@ -4611,12 +4641,12 @@ function getFetchForUpdater() {
   return globalThis.fetch.bind(globalThis);
 }
 
-async function updateLauncherFromLatestRelease(
+async function updateLauncherFromSelectedRelease(
   launcherPath?: string,
   channel: UpdateChannel = getResolvedConfig().updates.channel,
+  release: GitHubRelease | null = null,
 ) {
   const fetchForUpdater = getFetchForUpdater();
-  const release = await fetchLatestStableRelease({ fetch: fetchForUpdater, channel });
   if (!release) {
     return { status: 'missing-asset', message: `No ${channel} GitHub release found.` };
   }
@@ -4640,9 +4670,9 @@ async function updateLauncherFromLatestRelease(
   });
   for (const result of supportResults) {
     if (result.status === 'protected' && result.command) {
-      logger.warn(`Support assets update requires manual command: ${result.command}`);
+      logger.warn(`Rofi theme update requires manual command: ${result.command}`);
     } else if (result.status === 'hash-mismatch' || result.status === 'missing-asset') {
-      logger.warn(`Support assets update skipped: ${result.message ?? result.status}`);
+      logger.warn(`Rofi theme update skipped: ${result.message ?? result.status}`);
     }
   }
   return launcherResult;
@@ -4655,6 +4685,19 @@ function getUpdateService() {
     isPackaged: app.isPackaged,
     log: (message) => logger.info(message),
     getChannel: () => getResolvedConfig().updates.channel,
+    isNativeUpdaterSupported: () =>
+      isNativeUpdaterSupported({
+        platform: process.platform,
+        isPackaged: app.isPackaged,
+        execPath: process.execPath,
+        env: process.env,
+        log: (message) => logger.warn(message),
+      }),
+  });
+  const updateDialogPresenter = createUpdateDialogPresenter({
+    platform: process.platform,
+    focusApp: () => app.focus({ steal: true }),
+    showMessageBox: (options) => dialog.showMessageBox(options),
   });
   updateService = createUpdateService({
     getConfig: () => getResolvedConfig().updates,
@@ -4665,16 +4708,16 @@ function getUpdateService() {
     checkAppUpdate: (channel) => appUpdater.checkForUpdates(channel),
     fetchLatestStableRelease: (channel) =>
       fetchLatestStableRelease({ fetch: getFetchForUpdater(), channel }),
-    updateLauncher: (launcherPath, channel) =>
-      updateLauncherFromLatestRelease(launcherPath, channel),
-    showNoUpdateDialog: (version) =>
-      showNoUpdateDialog((options) => dialog.showMessageBox(options), version),
+    updateLauncher: (launcherPath, channel, release) =>
+      updateLauncherFromSelectedRelease(launcherPath, channel, release),
+    showNoUpdateDialog: (version) => updateDialogPresenter.showNoUpdateDialog(version),
     showUpdateAvailableDialog: (version) =>
-      showUpdateAvailableDialog((options) => dialog.showMessageBox(options), version),
-    showUpdateFailedDialog: (message) =>
-      showUpdateFailedDialog((options) => dialog.showMessageBox(options), message),
+      updateDialogPresenter.showUpdateAvailableDialog(version),
+    showUpdateFailedDialog: (message) => updateDialogPresenter.showUpdateFailedDialog(message),
+    showManualUpdateRequiredDialog: (version) =>
+      updateDialogPresenter.showManualUpdateRequiredDialog(version),
     downloadAppUpdate: () => appUpdater.downloadUpdate(),
-    showRestartDialog: () => showRestartDialog((options) => dialog.showMessageBox(options)),
+    showRestartDialog: () => updateDialogPresenter.showRestartDialog(),
     quitAndInstall: () => appUpdater.quitAndInstall(),
     notifyUpdateAvailable: (version) =>
       notifyUpdateAvailable(
@@ -5100,6 +5143,20 @@ const { registerIpcRuntimeHandlers } = composeIpcRuntimeHandlers({
       onOverlayModalOpened: (modal) => {
         overlayModalRuntime.notifyOverlayModalOpened(modal);
       },
+      onOverlayMouseInteractionChanged: (active, senderWindow) => {
+        const mainWindow = overlayManager.getMainWindow();
+        if (!mainWindow || senderWindow !== mainWindow) {
+          return;
+        }
+        if (visibleOverlayInteractionActive === active) {
+          if (active && process.platform === 'darwin' && !mainWindow.isFocused()) {
+            overlayVisibilityRuntime.updateVisibleOverlayVisibility();
+          }
+          return;
+        }
+        visibleOverlayInteractionActive = active;
+        overlayVisibilityRuntime.updateVisibleOverlayVisibility();
+      },
       onYoutubePickerResolve: (request) => youtubeFlowRuntime.resolveActivePicker(request),
       openYomitanSettings: () => openYomitanSettings(),
       quitApp: () => requestAppQuit(),
@@ -5307,7 +5364,7 @@ const { handleCliCommand, handleInitialArgs } = composeCliStartupHandlers({
     initializeOverlayRuntime: () => initializeOverlayRuntime(),
     toggleVisibleOverlay: () => toggleVisibleOverlay(),
     togglePrimarySubtitleBar: () => togglePrimarySubtitleBar(),
-    openFirstRunSetupWindow: () => openFirstRunSetupWindow(),
+    openFirstRunSetupWindow: (force?: boolean) => openFirstRunSetupWindow(force),
     setVisibleOverlayVisible: (visible: boolean) => setVisibleOverlayVisible(visible),
     copyCurrentSubtitle: () => copyCurrentSubtitle(),
     startPendingMultiCopy: (timeoutMs: number) => startPendingMultiCopy(timeoutMs),
@@ -5365,6 +5422,7 @@ const { handleCliCommand, handleInitialArgs } = composeCliStartupHandlers({
     getMultiCopyTimeoutMs: () => getConfiguredShortcuts().multiCopyTimeoutMs,
     schedule: (fn: () => void, delayMs: number) => setTimeout(fn, delayMs),
     logInfo: (message: string) => logger.info(message),
+    logDebug: (message: string) => logger.debug(message),
     logWarn: (message: string) => logger.warn(message),
     logError: (message: string, err: unknown) => logger.error(message, err),
   },

src/main/app-lifecycle.ts

@@ -44,6 +44,7 @@ export interface AppReadyRuntimeDepsFactoryInput {
   createImmersionTracker?: AppReadyRuntimeDeps['createImmersionTracker'];
   startJellyfinRemoteSession?: AppReadyRuntimeDeps['startJellyfinRemoteSession'];
   loadYomitanExtension: AppReadyRuntimeDeps['loadYomitanExtension'];
+  ensureYomitanExtensionLoaded?: AppReadyRuntimeDeps['ensureYomitanExtensionLoaded'];
   handleFirstRunSetup: AppReadyRuntimeDeps['handleFirstRunSetup'];
   prewarmSubtitleDictionaries?: AppReadyRuntimeDeps['prewarmSubtitleDictionaries'];
   startBackgroundWarmups: AppReadyRuntimeDeps['startBackgroundWarmups'];
@@ -109,6 +110,7 @@ export function createAppReadyRuntimeDeps(
     createImmersionTracker: params.createImmersionTracker,
     startJellyfinRemoteSession: params.startJellyfinRemoteSession,
     loadYomitanExtension: params.loadYomitanExtension,
+    ensureYomitanExtensionLoaded: params.ensureYomitanExtensionLoaded,
     handleFirstRunSetup: params.handleFirstRunSetup,
     prewarmSubtitleDictionaries: params.prewarmSubtitleDictionaries,
     startBackgroundWarmups: params.startBackgroundWarmups,

src/main/character-dictionary-runtime.test.ts

@@ -1459,7 +1459,7 @@ test('generateForCurrentMedia preserves duplicate surface forms across different
   }
 });
 
-test('getOrCreateCurrentSnapshot persists and reuses normalized snapshot data', async () => {
+test('getOrCreateCurrentSnapshot reuses cached media resolution without AniList requests', async () => {
   const userDataPath = makeTempDir();
   const originalFetch = globalThis.fetch;
   let searchQueryCount = 0;
@@ -1567,11 +1567,18 @@ test('getOrCreateCurrentSnapshot persists and reuses normalized snapshot data',
     });
 
     const first = await runtime.getOrCreateCurrentSnapshot();
+    assert.equal(searchQueryCount, 1);
+    assert.equal(characterQueryCount, 1);
+
+    fs.rmSync(path.join(userDataPath, 'character-dictionaries', 'anilist-resolution-cache.json'), {
+      force: true,
+    });
+
     const second = await runtime.getOrCreateCurrentSnapshot();
 
     assert.equal(first.fromCache, false);
     assert.equal(second.fromCache, true);
-    assert.equal(searchQueryCount, 2);
+    assert.equal(searchQueryCount, 1);
     assert.equal(characterQueryCount, 1);
     assert.equal(
       fs.existsSync(path.join(userDataPath, 'character-dictionaries', 'cache.json')),

src/main/character-dictionary-runtime.ts

@@ -15,7 +15,10 @@ import {
   getMergedZipPath,
   getSnapshotPath,
   normalizeMergedMediaIds,
+  readCachedMediaResolution,
+  readCachedSnapshots,
   readSnapshot,
+  writeCachedMediaResolution,
   writeSnapshot,
 } from './character-dictionary-runtime/cache';
 import {
@@ -41,6 +44,7 @@ import type {
   CharacterDictionaryManualSelectionResult,
   CharacterDictionaryManualSelectionSnapshot,
   CharacterDictionaryRuntimeDeps,
+  CharacterDictionarySnapshot,
   CharacterDictionarySnapshotImage,
   CharacterDictionarySnapshotProgress,
   CharacterDictionarySnapshotProgressCallbacks,
@@ -204,6 +208,26 @@ export function createCharacterDictionaryRuntimeService(deps: CharacterDictionar
     };
   };
 
+  const findCachedSnapshotForSeriesKey = (
+    seriesKey: string,
+  ): CharacterDictionarySnapshot | null => {
+    return (
+      readCachedSnapshots(outputDir).find((snapshot) => {
+        const snapshotSeriesKey = buildCharacterDictionarySeriesKey({
+          mediaPath: null,
+          mediaTitle: snapshot.mediaTitle,
+          guess: {
+            title: snapshot.mediaTitle,
+            season: null,
+            episode: null,
+            source: 'fallback',
+          },
+        });
+        return snapshotSeriesKey === seriesKey;
+      }) ?? null
+    );
+  };
+
   const resolveCurrentMedia = async (
     targetPath?: string,
     beforeRequest?: () => Promise<void>,
@@ -228,7 +252,43 @@ export function createCharacterDictionaryRuntimeService(deps: CharacterDictionar
         staleMediaIds: override.staleMediaIds,
       };
     }
+
+    const cachedResolution = readCachedMediaResolution(outputDir, seriesKey);
+    if (cachedResolution) {
+      const cachedSnapshot = readSnapshot(getSnapshotPath(outputDir, cachedResolution.mediaId));
+      if (cachedSnapshot) {
+        deps.logInfo?.(
+          `[dictionary] cached AniList match: ${cachedSnapshot.mediaTitle} -> AniList ${cachedSnapshot.mediaId}`,
+        );
+        return {
+          id: cachedSnapshot.mediaId,
+          title: cachedSnapshot.mediaTitle,
+        };
+      }
+    }
+
+    const cachedSnapshot = findCachedSnapshotForSeriesKey(seriesKey);
+    if (cachedSnapshot) {
+      writeCachedMediaResolution(outputDir, {
+        seriesKey,
+        mediaId: cachedSnapshot.mediaId,
+        mediaTitle: cachedSnapshot.mediaTitle,
+      });
+      deps.logInfo?.(
+        `[dictionary] cached snapshot match: ${cachedSnapshot.mediaTitle} -> AniList ${cachedSnapshot.mediaId}`,
+      );
+      return {
+        id: cachedSnapshot.mediaId,
+        title: cachedSnapshot.mediaTitle,
+      };
+    }
+
     const resolved = await resolveAniListMediaIdFromGuess(guessed, beforeRequest);
+    writeCachedMediaResolution(outputDir, {
+      seriesKey,
+      mediaId: resolved.id,
+      mediaTitle: resolved.title,
+    });
     deps.logInfo?.(`[dictionary] AniList match: ${resolved.title} -> AniList ${resolved.id}`);
     return resolved;
   };

src/main/character-dictionary-runtime/cache.ts

@@ -21,6 +21,102 @@ export function getMergedZipPath(outputDir: string): string {
   return path.join(outputDir, 'merged.zip');
 }
 
+type MediaResolutionCacheEntry = {
+  seriesKey: string;
+  mediaId: number;
+  mediaTitle: string;
+};
+
+type MediaResolutionCacheFile = {
+  entries?: MediaResolutionCacheEntry[];
+};
+
+function getMediaResolutionCachePath(outputDir: string): string {
+  return path.join(outputDir, 'anilist-resolution-cache.json');
+}
+
+function normalizeMediaResolutionEntry(value: unknown): MediaResolutionCacheEntry | null {
+  if (!value || typeof value !== 'object') return null;
+  const raw = value as Partial<MediaResolutionCacheEntry>;
+  const seriesKey = typeof raw.seriesKey === 'string' ? raw.seriesKey.trim() : '';
+  const mediaTitle = typeof raw.mediaTitle === 'string' ? raw.mediaTitle.trim() : '';
+  if (typeof raw.mediaId !== 'number' || !Number.isFinite(raw.mediaId)) return null;
+  const mediaId = Math.floor(raw.mediaId);
+  if (!seriesKey || mediaId <= 0 || !mediaTitle) return null;
+  return {
+    seriesKey,
+    mediaId,
+    mediaTitle,
+  };
+}
+
+function readMediaResolutionEntries(outputDir: string): MediaResolutionCacheEntry[] {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(getMediaResolutionCachePath(outputDir), 'utf8'),
+    ) as MediaResolutionCacheFile;
+    if (!Array.isArray(parsed.entries)) return [];
+    const byKey = new Map<string, MediaResolutionCacheEntry>();
+    for (const value of parsed.entries) {
+      const normalized = normalizeMediaResolutionEntry(value);
+      if (normalized) byKey.set(normalized.seriesKey, normalized);
+    }
+    return [...byKey.values()];
+  } catch {
+    return [];
+  }
+}
+
+function writeMediaResolutionEntries(
+  outputDir: string,
+  entries: MediaResolutionCacheEntry[],
+): void {
+  ensureDir(outputDir);
+  fs.writeFileSync(
+    getMediaResolutionCachePath(outputDir),
+    JSON.stringify({ entries }, null, 2),
+    'utf8',
+  );
+}
+
+export function readCachedMediaResolution(
+  outputDir: string,
+  seriesKey: string,
+): MediaResolutionCacheEntry | null {
+  const normalizedKey = seriesKey.trim();
+  if (!normalizedKey) return null;
+  return (
+    readMediaResolutionEntries(outputDir).find((entry) => entry.seriesKey === normalizedKey) ?? null
+  );
+}
+
+export function writeCachedMediaResolution(
+  outputDir: string,
+  entry: MediaResolutionCacheEntry,
+): void {
+  const normalized = normalizeMediaResolutionEntry(entry);
+  if (!normalized) return;
+  const remaining = readMediaResolutionEntries(outputDir).filter(
+    (existing) => existing.seriesKey !== normalized.seriesKey,
+  );
+  writeMediaResolutionEntries(outputDir, [...remaining, normalized]);
+}
+
+export function readCachedSnapshots(outputDir: string): CharacterDictionarySnapshot[] {
+  let entries: fs.Dirent[] = [];
+  try {
+    entries = fs.readdirSync(getSnapshotsDir(outputDir), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isFile() && /^anilist-\d+\.json$/.test(entry.name))
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => readSnapshot(path.join(getSnapshotsDir(outputDir), entry.name)))
+    .filter((snapshot): snapshot is CharacterDictionarySnapshot => snapshot !== null);
+}
+
 export function readSnapshot(snapshotPath: string): CharacterDictionarySnapshot | null {
   try {
     const raw = fs.readFileSync(snapshotPath, 'utf8');

src/main/cli-runtime.ts

@@ -20,7 +20,7 @@ export interface CliCommandRuntimeServiceContext {
   initializeOverlay: () => void;
   toggleVisibleOverlay: () => void;
   togglePrimarySubtitleBar: () => void;
-  openFirstRunSetup: () => void;
+  openFirstRunSetup: (force?: boolean) => void;
   setVisibleOverlay: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
   startPendingMultiCopy: (timeoutMs: number) => void;
@@ -54,6 +54,7 @@ export interface CliCommandRuntimeServiceContext {
   getMultiCopyTimeoutMs: () => number;
   schedule: (fn: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
   log: (message: string) => void;
+  logDebug: (message: string) => void;
   warn: (message: string) => void;
   error: (message: string, err: unknown) => void;
 }
@@ -133,6 +134,7 @@ function createCliCommandDepsFromContext(
     getMultiCopyTimeoutMs: context.getMultiCopyTimeoutMs,
     schedule: context.schedule,
     log: context.log,
+    logDebug: context.logDebug,
     warn: context.warn,
     error: context.error,
   };

src/main/controller-config-update.test.ts

@@ -75,3 +75,67 @@ test('applyControllerConfigUpdate detaches updated binding values from the patch
 
   assert.deepEqual(next.bindings?.toggleLookup, { kind: 'button', buttonIndex: 7 });
 });
+
+test('applyControllerConfigUpdate merges per-controller profile binding leaves', () => {
+  const next = applyControllerConfigUpdate(
+    {
+      profiles: {
+        'pad-1': {
+          label: 'Pad 1',
+          bindings: {
+            toggleLookup: { kind: 'button', buttonIndex: 0 },
+            closeLookup: { kind: 'button', buttonIndex: 1 },
+          },
+        },
+      },
+    },
+    {
+      profiles: {
+        'pad-1': {
+          bindings: {
+            toggleLookup: { kind: 'button', buttonIndex: 11 },
+          },
+        },
+        'pad-2': {
+          label: 'Pad 2',
+          bindings: {
+            mineCard: { kind: 'button', buttonIndex: 8 },
+          },
+        },
+      },
+    },
+  );
+
+  assert.deepEqual(next.profiles?.['pad-1']?.bindings?.toggleLookup, {
+    kind: 'button',
+    buttonIndex: 11,
+  });
+  assert.deepEqual(next.profiles?.['pad-1']?.bindings?.closeLookup, {
+    kind: 'button',
+    buttonIndex: 1,
+  });
+  assert.deepEqual(next.profiles?.['pad-2']?.bindings?.mineCard, {
+    kind: 'button',
+    buttonIndex: 8,
+  });
+});
+
+test('applyControllerConfigUpdate ignores reserved profile ids', () => {
+  const reservedProfiles = Object.create(null) as NonNullable<
+    Parameters<typeof applyControllerConfigUpdate>[1]['profiles']
+  >;
+  reservedProfiles.__proto__ = { label: 'polluted' };
+  reservedProfiles['constructor'] = { label: 'ctor' };
+  reservedProfiles['prototype'] = { label: 'proto' };
+  reservedProfiles['pad-1'] = { label: 'Pad 1' };
+
+  const next = applyControllerConfigUpdate(undefined, {
+    profiles: reservedProfiles,
+  });
+
+  assert.equal(Object.getPrototypeOf(next.profiles), Object.prototype);
+  assert.equal(Object.hasOwn(next.profiles ?? {}, '__proto__'), false);
+  assert.equal(Object.hasOwn(next.profiles ?? {}, 'constructor'), false);
+  assert.equal(Object.hasOwn(next.profiles ?? {}, 'prototype'), false);
+  assert.equal(next.profiles?.['pad-1']?.label, 'Pad 1');
+});

src/main/controller-config-update.ts

@@ -2,6 +2,66 @@ import type { ControllerConfigUpdate, RawConfig } from '../types';
 
 type RawControllerConfig = NonNullable<RawConfig['controller']>;
 type RawControllerBindings = NonNullable<RawControllerConfig['bindings']>;
+type RawControllerButtonIndices = NonNullable<RawControllerConfig['buttonIndices']>;
+type RawControllerProfiles = NonNullable<RawControllerConfig['profiles']>;
+type RawControllerProfile = NonNullable<RawControllerProfiles[string]>;
+
+const RESERVED_CONTROLLER_PROFILE_IDS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function mergeBindingPatch(
+  currentBindings: RawControllerBindings | undefined,
+  updateBindings: RawControllerBindings | undefined,
+): RawControllerBindings | undefined {
+  if (!currentBindings && !updateBindings) return undefined;
+  const nextBindings: RawControllerBindings = {
+    ...(currentBindings ?? {}),
+  };
+
+  for (const [key, value] of Object.entries(updateBindings ?? {}) as Array<
+    [keyof RawControllerBindings, RawControllerBindings[keyof RawControllerBindings] | undefined]
+  >) {
+    if (value === undefined) continue;
+    (nextBindings as Record<string, unknown>)[key] = structuredClone(value);
+  }
+
+  return nextBindings;
+}
+
+function mergeButtonIndexPatch(
+  currentButtonIndices: RawControllerButtonIndices | undefined,
+  updateButtonIndices: RawControllerButtonIndices | undefined,
+): RawControllerButtonIndices | undefined {
+  if (!currentButtonIndices && !updateButtonIndices) return undefined;
+  return {
+    ...(currentButtonIndices ?? {}),
+    ...(updateButtonIndices ?? {}),
+  };
+}
+
+function mergeControllerProfile(
+  currentProfile: RawControllerProfile | undefined,
+  updateProfile: RawControllerProfile,
+): RawControllerProfile {
+  const nextProfile: RawControllerProfile = {
+    ...(currentProfile ?? {}),
+    ...updateProfile,
+  };
+
+  const buttonIndices = mergeButtonIndexPatch(
+    currentProfile?.buttonIndices,
+    updateProfile.buttonIndices,
+  );
+  if (buttonIndices) {
+    nextProfile.buttonIndices = buttonIndices;
+  }
+
+  const bindings = mergeBindingPatch(currentProfile?.bindings, updateProfile.bindings);
+  if (bindings) {
+    nextProfile.bindings = bindings;
+  }
+
+  return nextProfile;
+}
 
 export function applyControllerConfigUpdate(
   currentController: RawConfig['controller'] | undefined,
@@ -12,26 +72,38 @@ export function applyControllerConfigUpdate(
     ...update,
   };
 
-  if (currentController?.buttonIndices || update.buttonIndices) {
-    nextController.buttonIndices = {
-      ...(currentController?.buttonIndices ?? {}),
-      ...(update.buttonIndices ?? {}),
-    };
+  const buttonIndices = mergeButtonIndexPatch(
+    currentController?.buttonIndices,
+    update.buttonIndices,
+  );
+  if (buttonIndices) {
+    nextController.buttonIndices = buttonIndices;
   }
 
-  if (currentController?.bindings || update.bindings) {
-    const nextBindings: RawControllerBindings = {
-      ...(currentController?.bindings ?? {}),
-    };
+  const bindings = mergeBindingPatch(currentController?.bindings, update.bindings);
+  if (bindings) {
+    nextController.bindings = bindings;
+  }
 
-    for (const [key, value] of Object.entries(update.bindings ?? {}) as Array<
-      [keyof RawControllerBindings, RawControllerBindings[keyof RawControllerBindings] | undefined]
+  if (currentController?.profiles || update.profiles) {
+    const nextProfiles: RawControllerProfiles = {};
+    for (const [profileId, profile] of Object.entries(currentController?.profiles ?? {}) as Array<
+      [string, RawControllerProfile]
     >) {
-      if (value === undefined) continue;
-      (nextBindings as Record<string, unknown>)[key] = structuredClone(value);
+      if (RESERVED_CONTROLLER_PROFILE_IDS.has(profileId)) continue;
+      nextProfiles[profileId] = profile;
     }
-
-    nextController.bindings = nextBindings;
+    for (const [profileId, profileUpdate] of Object.entries(update.profiles ?? {}) as Array<
+      [string, RawControllerProfile | undefined]
+    >) {
+      if (RESERVED_CONTROLLER_PROFILE_IDS.has(profileId)) continue;
+      if (profileUpdate === undefined) continue;
+      nextProfiles[profileId] = mergeControllerProfile(
+        currentController?.profiles?.[profileId],
+        profileUpdate,
+      );
+    }
+    nextController.profiles = nextProfiles;
   }
 
   return nextController;

src/main/dependencies.ts

@@ -57,6 +57,7 @@ export interface MainIpcRuntimeServiceDepsParams {
   getVisibleOverlayVisibility: IpcDepsRuntimeOptions['getVisibleOverlayVisibility'];
   onOverlayModalClosed: IpcDepsRuntimeOptions['onOverlayModalClosed'];
   onOverlayModalOpened?: IpcDepsRuntimeOptions['onOverlayModalOpened'];
+  onOverlayMouseInteractionChanged?: IpcDepsRuntimeOptions['onOverlayMouseInteractionChanged'];
   onYoutubePickerResolve: IpcDepsRuntimeOptions['onYoutubePickerResolve'];
   openYomitanSettings: IpcDepsRuntimeOptions['openYomitanSettings'];
   quitApp: IpcDepsRuntimeOptions['quitApp'];
@@ -198,6 +199,7 @@ export interface CliCommandRuntimeServiceDepsParams {
   getMultiCopyTimeoutMs: CliCommandDepsRuntimeOptions['getMultiCopyTimeoutMs'];
   schedule: CliCommandDepsRuntimeOptions['schedule'];
   log: CliCommandDepsRuntimeOptions['log'];
+  logDebug: CliCommandDepsRuntimeOptions['logDebug'];
   warn: CliCommandDepsRuntimeOptions['warn'];
   error: CliCommandDepsRuntimeOptions['error'];
 }
@@ -228,6 +230,7 @@ export function createMainIpcRuntimeServiceDeps(
     getVisibleOverlayVisibility: params.getVisibleOverlayVisibility,
     onOverlayModalClosed: params.onOverlayModalClosed,
     onOverlayModalOpened: params.onOverlayModalOpened,
+    onOverlayMouseInteractionChanged: params.onOverlayMouseInteractionChanged,
     onYoutubePickerResolve: params.onYoutubePickerResolve,
     openYomitanSettings: params.openYomitanSettings,
     quitApp: params.quitApp,
@@ -377,6 +380,7 @@ export function createCliCommandRuntimeServiceDeps(
     getMultiCopyTimeoutMs: params.getMultiCopyTimeoutMs,
     schedule: params.schedule,
     log: params.log,
+    logDebug: params.logDebug,
     warn: params.warn,
     error: params.error,
   };

src/main/overlay-visibility-runtime.ts

@@ -11,6 +11,7 @@ export interface OverlayVisibilityRuntimeDeps {
   getModalActive: () => boolean;
   getVisibleOverlayVisible: () => boolean;
   getForceMousePassthrough: () => boolean;
+  getOverlayInteractionActive?: () => boolean;
   getWindowTracker: () => BaseWindowTracker | null;
   getLastKnownWindowsForegroundProcessName?: () => string | null;
   getWindowsOverlayProcessName?: () => string | null;
@@ -49,6 +50,7 @@ export function createOverlayVisibilityRuntimeService(
         visibleOverlayVisible,
         modalActive: deps.getModalActive(),
         forceMousePassthrough,
+        overlayInteractionActive: deps.getOverlayInteractionActive?.() ?? false,
         mainWindow,
         windowTracker,
         lastKnownWindowsForegroundProcessName: deps.getLastKnownWindowsForegroundProcessName?.(),

src/main/runtime/anilist-media-guess.test.ts

@@ -30,6 +30,36 @@ test('maybeProbeAnilistDuration updates state with probed duration', async () =>
   assert.equal(state.mediaDurationSec, 321);
 });
 
+test('maybeProbeAnilistDuration force option bypasses retry interval', async () => {
+  let state: AnilistMediaGuessRuntimeState = {
+    mediaKey: '/tmp/video.mkv',
+    mediaDurationSec: null,
+    mediaGuess: null,
+    mediaGuessPromise: null,
+    lastDurationProbeAtMs: 1900,
+  };
+  let requestCount = 0;
+  const probe = createMaybeProbeAnilistDurationHandler({
+    getState: () => state,
+    setState: (next) => {
+      state = next;
+    },
+    durationRetryIntervalMs: 1000,
+    now: () => 2000,
+    requestMpvDuration: async () => {
+      requestCount += 1;
+      return 321;
+    },
+    logWarn: () => {},
+  });
+
+  const duration = await probe('/tmp/video.mkv', { force: true });
+
+  assert.equal(duration, 321);
+  assert.equal(requestCount, 1);
+  assert.equal(state.mediaDurationSec, 321);
+});
+
 test('ensureAnilistMediaGuess memoizes in-flight guess promise', async () => {
   let state: AnilistMediaGuessRuntimeState = {
     mediaKey: '/tmp/video.mkv',

src/main/runtime/anilist-media-guess.ts

@@ -14,6 +14,10 @@ type GuessAnilistMediaInfo = (
   mediaTitle: string | null,
 ) => Promise<AnilistMediaGuess | null>;
 
+type AnilistDurationProbeOptions = {
+  force?: boolean;
+};
+
 export function createMaybeProbeAnilistDurationHandler(deps: {
   getState: () => AnilistMediaGuessRuntimeState;
   setState: (state: AnilistMediaGuessRuntimeState) => void;
@@ -22,7 +26,10 @@ export function createMaybeProbeAnilistDurationHandler(deps: {
   requestMpvDuration: () => Promise<unknown>;
   logWarn: (message: string, error: unknown) => void;
 }) {
-  return async (mediaKey: string): Promise<number | null> => {
+  return async (
+    mediaKey: string,
+    options: AnilistDurationProbeOptions = {},
+  ): Promise<number | null> => {
     const state = deps.getState();
     if (state.mediaKey !== mediaKey) {
       return null;
@@ -34,7 +41,7 @@ export function createMaybeProbeAnilistDurationHandler(deps: {
       return state.mediaDurationSec;
     }
     const now = deps.now();
-    if (now - state.lastDurationProbeAtMs < deps.durationRetryIntervalMs) {
+    if (!options.force && now - state.lastDurationProbeAtMs < deps.durationRetryIntervalMs) {
       return null;
     }
 

src/main/runtime/anilist-media-state-main-deps.test.ts

@@ -3,6 +3,7 @@ import test from 'node:test';
 import {
   createBuildGetAnilistMediaGuessRuntimeStateMainDepsHandler,
   createBuildGetCurrentAnilistMediaKeyMainDepsHandler,
+  createBuildRecordAnilistMediaDurationMainDepsHandler,
   createBuildResetAnilistMediaGuessStateMainDepsHandler,
   createBuildResetAnilistMediaTrackingMainDepsHandler,
   createBuildSetAnilistMediaGuessRuntimeStateMainDepsHandler,
@@ -70,3 +71,32 @@ test('reset anilist media guess state main deps builder maps callbacks', () => {
   deps.setMediaGuessPromise(null);
   assert.deepEqual(calls, ['guess', 'promise']);
 });
+
+test('record anilist media duration main deps builder maps callbacks', () => {
+  const calls: string[] = [];
+  const state = {
+    mediaKey: '/tmp/video.mkv',
+    mediaDurationSec: null,
+    mediaGuess: null,
+    mediaGuessPromise: null,
+    lastDurationProbeAtMs: 0,
+  };
+  const deps = createBuildRecordAnilistMediaDurationMainDepsHandler({
+    getCurrentMediaKey: () => {
+      calls.push('key');
+      return '/tmp/video.mkv';
+    },
+    getState: () => {
+      calls.push('get');
+      return state;
+    },
+    setState: () => {
+      calls.push('set');
+    },
+  })();
+
+  assert.equal(deps.getCurrentMediaKey(), '/tmp/video.mkv');
+  deps.getState();
+  deps.setState(state);
+  assert.deepEqual(calls, ['key', 'get', 'set']);
+});

src/main/runtime/anilist-media-state-main-deps.ts

@@ -1,6 +1,7 @@
 import type {
   createGetAnilistMediaGuessRuntimeStateHandler,
   createGetCurrentAnilistMediaKeyHandler,
+  createRecordAnilistMediaDurationHandler,
   createResetAnilistMediaGuessStateHandler,
   createResetAnilistMediaTrackingHandler,
   createSetAnilistMediaGuessRuntimeStateHandler,
@@ -18,6 +19,9 @@ type GetAnilistMediaGuessRuntimeStateMainDeps = Parameters<
 type SetAnilistMediaGuessRuntimeStateMainDeps = Parameters<
   typeof createSetAnilistMediaGuessRuntimeStateHandler
 >[0];
+type RecordAnilistMediaDurationMainDeps = Parameters<
+  typeof createRecordAnilistMediaDurationHandler
+>[0];
 type ResetAnilistMediaGuessStateMainDeps = Parameters<
   typeof createResetAnilistMediaGuessStateHandler
 >[0];
@@ -66,6 +70,16 @@ export function createBuildSetAnilistMediaGuessRuntimeStateMainDepsHandler(
   });
 }
 
+export function createBuildRecordAnilistMediaDurationMainDepsHandler(
+  deps: RecordAnilistMediaDurationMainDeps,
+) {
+  return (): RecordAnilistMediaDurationMainDeps => ({
+    getCurrentMediaKey: () => deps.getCurrentMediaKey(),
+    getState: () => deps.getState(),
+    setState: (state) => deps.setState(state),
+  });
+}
+
 export function createBuildResetAnilistMediaGuessStateMainDepsHandler(
   deps: ResetAnilistMediaGuessStateMainDeps,
 ) {

src/main/runtime/anilist-media-state.test.ts

@@ -3,6 +3,7 @@ import test from 'node:test';
 import {
   createGetAnilistMediaGuessRuntimeStateHandler,
   createGetCurrentAnilistMediaKeyHandler,
+  createRecordAnilistMediaDurationHandler,
   createResetAnilistMediaGuessStateHandler,
   createResetAnilistMediaTrackingHandler,
   createSetAnilistMediaGuessRuntimeStateHandler,
@@ -176,3 +177,57 @@ test('reset anilist media guess state clears guess and in-flight promise', () =>
   assert.equal(state.mediaDurationSec, 240);
   assert.equal(state.lastDurationProbeAtMs, 321);
 });
+
+test('record anilist media duration stores observed mpv duration for current media', () => {
+  const existingPromise = Promise.resolve(null);
+  let state = {
+    mediaKey: '/tmp/video.mkv' as string | null,
+    mediaDurationSec: null as number | null,
+    mediaGuess: { title: 'guess' } as { title: string } | null,
+    mediaGuessPromise: existingPromise as Promise<unknown> | null,
+    lastDurationProbeAtMs: 321,
+  };
+
+  const recordDuration = createRecordAnilistMediaDurationHandler({
+    getCurrentMediaKey: () => '/tmp/video.mkv',
+    getState: () => state as never,
+    setState: (nextState) => {
+      state = nextState as never;
+    },
+  });
+
+  recordDuration(1440);
+
+  assert.equal(state.mediaDurationSec, 1440);
+  assert.deepEqual(state.mediaGuess, { title: 'guess' });
+  assert.equal(state.mediaGuessPromise, existingPromise);
+  assert.equal(state.lastDurationProbeAtMs, 321);
+});
+
+test('record anilist media duration resets stale media state when media key changes', () => {
+  let state = {
+    mediaKey: '/tmp/old.mkv' as string | null,
+    mediaDurationSec: 120 as number | null,
+    mediaGuess: { title: 'old' } as { title: string } | null,
+    mediaGuessPromise: Promise.resolve(null) as Promise<unknown> | null,
+    lastDurationProbeAtMs: 321,
+  };
+
+  const recordDuration = createRecordAnilistMediaDurationHandler({
+    getCurrentMediaKey: () => '/tmp/new.mkv',
+    getState: () => state as never,
+    setState: (nextState) => {
+      state = nextState as never;
+    },
+  });
+
+  recordDuration(1440);
+
+  assert.deepEqual(state, {
+    mediaKey: '/tmp/new.mkv',
+    mediaDurationSec: 1440,
+    mediaGuess: null,
+    mediaGuessPromise: null,
+    lastDurationProbeAtMs: 0,
+  });
+});

src/main/runtime/anilist-media-state.ts

@@ -61,6 +61,37 @@ export function createSetAnilistMediaGuessRuntimeStateHandler(deps: {
   };
 }
 
+export function createRecordAnilistMediaDurationHandler(deps: {
+  getCurrentMediaKey: () => string | null;
+  getState: () => AnilistMediaGuessRuntimeState;
+  setState: (state: AnilistMediaGuessRuntimeState) => void;
+}) {
+  return (durationSec: number): void => {
+    if (!Number.isFinite(durationSec) || durationSec <= 0) {
+      return;
+    }
+    const mediaKey = deps.getCurrentMediaKey();
+    if (!mediaKey) {
+      return;
+    }
+    const state = deps.getState();
+    if (state.mediaKey === mediaKey) {
+      deps.setState({
+        ...state,
+        mediaDurationSec: durationSec,
+      });
+      return;
+    }
+    deps.setState({
+      mediaKey,
+      mediaDurationSec: durationSec,
+      mediaGuess: null,
+      mediaGuessPromise: null,
+      lastDurationProbeAtMs: 0,
+    });
+  };
+}
+
 export function createResetAnilistMediaGuessStateHandler(deps: {
   setMediaGuess: (value: AnilistMediaGuessRuntimeState['mediaGuess']) => void;
   setMediaGuessPromise: (value: AnilistMediaGuessRuntimeState['mediaGuessPromise']) => void;

src/main/runtime/anilist-post-watch-main-deps.test.ts

@@ -13,7 +13,10 @@ test('process next anilist retry update main deps builder maps callbacks', async
     setLastAttemptAt: () => calls.push('attempt'),
     setLastError: () => calls.push('error'),
     refreshAnilistClientSecretState: async () => 'token',
-    updateAnilistPostWatchProgress: async () => ({ status: 'updated', message: 'ok' }),
+    updateAnilistPostWatchProgress: async (_accessToken, _title, _episode, season) => ({
+      status: 'updated',
+      message: `ok:${season}`,
+    }),
     markSuccess: () => calls.push('success'),
     rememberAttemptedUpdateKey: () => calls.push('remember'),
     markFailure: () => calls.push('failure'),
@@ -26,9 +29,9 @@ test('process next anilist retry update main deps builder maps callbacks', async
   deps.setLastAttemptAt(1);
   deps.setLastError('x');
   assert.equal(await deps.refreshAnilistClientSecretState(), 'token');
-  assert.deepEqual(await deps.updateAnilistPostWatchProgress('token', 't', 1), {
+  assert.deepEqual(await deps.updateAnilistPostWatchProgress('token', 't', 1, 2), {
     status: 'updated',
-    message: 'ok',
+    message: 'ok:2',
   });
   deps.markSuccess('k');
   deps.rememberAttemptedUpdateKey('k');
@@ -58,16 +61,22 @@ test('maybe run anilist post watch update main deps builder maps callbacks', asy
     getTrackedMediaKey: () => 'media',
     resetTrackedMedia: () => calls.push('reset'),
     getWatchedSeconds: () => 100,
-    maybeProbeAnilistDuration: async () => 120,
+    maybeProbeAnilistDuration: async (_mediaKey, options) => {
+      calls.push(`probe:${options?.force === true}`);
+      return 120;
+    },
     ensureAnilistMediaGuess: async () => ({ title: 'x', season: null, episode: 1 }),
     hasAttemptedUpdateKey: () => false,
     processNextAnilistRetryUpdate: async () => ({ ok: true, message: 'ok' }),
     refreshAnilistClientSecretState: async () => 'token',
-    enqueueRetry: () => calls.push('enqueue'),
+    enqueueRetry: (_key, _title, _episode, season) => calls.push(`enqueue:${season}`),
     markRetryFailure: () => calls.push('retry-fail'),
     markRetrySuccess: () => calls.push('retry-ok'),
     refreshRetryQueueState: () => calls.push('refresh'),
-    updateAnilistPostWatchProgress: async () => ({ status: 'updated', message: 'done' }),
+    updateAnilistPostWatchProgress: async (_accessToken, _title, _episode, season) => ({
+      status: 'updated',
+      message: `done:${season}`,
+    }),
     rememberAttemptedUpdateKey: () => calls.push('remember'),
     showMpvOsd: () => calls.push('osd'),
     logInfo: (message) => calls.push(`info:${message}`),
@@ -84,7 +93,7 @@ test('maybe run anilist post watch update main deps builder maps callbacks', asy
   assert.equal(deps.getTrackedMediaKey(), 'media');
   deps.resetTrackedMedia('media');
   assert.equal(deps.getWatchedSeconds(), 100);
-  assert.equal(await deps.maybeProbeAnilistDuration('media'), 120);
+  assert.equal(await deps.maybeProbeAnilistDuration('media', { force: true }), 120);
   assert.deepEqual(await deps.ensureAnilistMediaGuess('media'), {
     title: 'x',
     season: null,
@@ -93,13 +102,13 @@ test('maybe run anilist post watch update main deps builder maps callbacks', asy
   assert.equal(deps.hasAttemptedUpdateKey('k'), false);
   assert.deepEqual(await deps.processNextAnilistRetryUpdate(), { ok: true, message: 'ok' });
   assert.equal(await deps.refreshAnilistClientSecretState(), 'token');
-  deps.enqueueRetry('k', 't', 1);
+  deps.enqueueRetry('k', 't', 1, 2);
   deps.markRetryFailure('k', 'bad');
   deps.markRetrySuccess('k');
   deps.refreshRetryQueueState();
-  assert.deepEqual(await deps.updateAnilistPostWatchProgress('token', 't', 1), {
+  assert.deepEqual(await deps.updateAnilistPostWatchProgress('token', 't', 1, 2), {
     status: 'updated',
-    message: 'done',
+    message: 'done:2',
   });
   deps.rememberAttemptedUpdateKey('k');
   deps.showMpvOsd('ok');
@@ -110,7 +119,8 @@ test('maybe run anilist post watch update main deps builder maps callbacks', asy
   assert.deepEqual(calls, [
     'in-flight',
     'reset',
-    'enqueue',
+    'probe:true',
+    'enqueue:2',
     'retry-fail',
     'retry-ok',
     'refresh',

src/main/runtime/anilist-post-watch-main-deps.ts

@@ -19,8 +19,12 @@ export function createBuildProcessNextAnilistRetryUpdateMainDepsHandler(
     setLastAttemptAt: (value: number) => deps.setLastAttemptAt(value),
     setLastError: (value: string | null) => deps.setLastError(value),
     refreshAnilistClientSecretState: () => deps.refreshAnilistClientSecretState(),
-    updateAnilistPostWatchProgress: (accessToken: string, title: string, episode: number) =>
-      deps.updateAnilistPostWatchProgress(accessToken, title, episode),
+    updateAnilistPostWatchProgress: (
+      accessToken: string,
+      title: string,
+      episode: number,
+      season?: number | null,
+    ) => deps.updateAnilistPostWatchProgress(accessToken, title, episode, season),
     markSuccess: (key: string) => deps.markSuccess(key),
     rememberAttemptedUpdateKey: (key: string) => deps.rememberAttemptedUpdateKey(key),
     markFailure: (key: string, message: string) => deps.markFailure(key, message),
@@ -42,18 +46,23 @@ export function createBuildMaybeRunAnilistPostWatchUpdateMainDepsHandler(
     getTrackedMediaKey: () => deps.getTrackedMediaKey(),
     resetTrackedMedia: (mediaKey) => deps.resetTrackedMedia(mediaKey),
     getWatchedSeconds: () => deps.getWatchedSeconds(),
-    maybeProbeAnilistDuration: (mediaKey: string) => deps.maybeProbeAnilistDuration(mediaKey),
+    maybeProbeAnilistDuration: (mediaKey: string, options) =>
+      deps.maybeProbeAnilistDuration(mediaKey, options),
     ensureAnilistMediaGuess: (mediaKey: string) => deps.ensureAnilistMediaGuess(mediaKey),
     hasAttemptedUpdateKey: (key: string) => deps.hasAttemptedUpdateKey(key),
     processNextAnilistRetryUpdate: () => deps.processNextAnilistRetryUpdate(),
     refreshAnilistClientSecretState: () => deps.refreshAnilistClientSecretState(),
-    enqueueRetry: (key: string, title: string, episode: number) =>
-      deps.enqueueRetry(key, title, episode),
+    enqueueRetry: (key: string, title: string, episode: number, season?: number | null) =>
+      deps.enqueueRetry(key, title, episode, season),
     markRetryFailure: (key: string, message: string) => deps.markRetryFailure(key, message),
     markRetrySuccess: (key: string) => deps.markRetrySuccess(key),
     refreshRetryQueueState: () => deps.refreshRetryQueueState(),
-    updateAnilistPostWatchProgress: (accessToken: string, title: string, episode: number) =>
-      deps.updateAnilistPostWatchProgress(accessToken, title, episode),
+    updateAnilistPostWatchProgress: (
+      accessToken: string,
+      title: string,
+      episode: number,
+      season?: number | null,
+    ) => deps.updateAnilistPostWatchProgress(accessToken, title, episode, season),
     rememberAttemptedUpdateKey: (key: string) => deps.rememberAttemptedUpdateKey(key),
     showMpvOsd: (message: string) => deps.showMpvOsd(message),
     logInfo: (message: string) => deps.logInfo(message),

src/main/runtime/anilist-post-watch.test.ts

@@ -20,12 +20,15 @@ test('rememberAnilistAttemptedUpdateKey evicts oldest beyond max size', () => {
 test('createProcessNextAnilistRetryUpdateHandler handles successful retry', async () => {
   const calls: string[] = [];
   const handler = createProcessNextAnilistRetryUpdateHandler({
-    nextReady: () => ({ key: 'k1', title: 'Show', season: null, episode: 1 }),
+    nextReady: () => ({ key: 'k1', title: 'Show', season: 2, episode: 1 }),
     refreshRetryQueueState: () => calls.push('refresh'),
     setLastAttemptAt: () => calls.push('attempt'),
     setLastError: (value) => calls.push(`error:${value ?? 'null'}`),
     refreshAnilistClientSecretState: async () => 'token',
-    updateAnilistPostWatchProgress: async () => ({ status: 'updated', message: 'updated ok' }),
+    updateAnilistPostWatchProgress: async (_accessToken, _title, _episode, season) => ({
+      status: 'updated',
+      message: `updated ok:${season}`,
+    }),
     markSuccess: () => calls.push('success'),
     rememberAttemptedUpdateKey: () => calls.push('remember'),
     markFailure: () => calls.push('failure'),
@@ -34,7 +37,7 @@ test('createProcessNextAnilistRetryUpdateHandler handles successful retry', asyn
   });
 
   const result = await handler();
-  assert.deepEqual(result, { ok: true, message: 'updated ok' });
+  assert.deepEqual(result, { ok: true, message: 'updated ok:2' });
   assert.ok(calls.includes('success'));
   assert.ok(calls.includes('remember'));
 });
@@ -93,7 +96,7 @@ test('createMaybeRunAnilistPostWatchUpdateHandler force-runs manual watched upda
       calls.push('probe');
       return 1000;
     },
-    ensureAnilistMediaGuess: async () => ({ title: 'Show', episode: 3 }),
+    ensureAnilistMediaGuess: async () => ({ title: 'Show', season: null, episode: 3 }),
     hasAttemptedUpdateKey: () => false,
     processNextAnilistRetryUpdate: async () => ({ ok: true, message: 'noop' }),
     refreshAnilistClientSecretState: async () => 'token',
@@ -121,6 +124,106 @@ test('createMaybeRunAnilistPostWatchUpdateHandler force-runs manual watched upda
   assert.ok(calls.includes('osd:updated ok'));
 });
 
+test('createMaybeRunAnilistPostWatchUpdateHandler shows permanent AniList update errors without queueing retry', async () => {
+  const calls: string[] = [];
+  const attemptedKeys = new Set<string>();
+  let updateCalls = 0;
+  const handler = createMaybeRunAnilistPostWatchUpdateHandler({
+    getInFlight: () => false,
+    setInFlight: (value) => calls.push(`inflight:${value}`),
+    getResolvedConfig: () => ({}),
+    isAnilistTrackingEnabled: () => true,
+    getCurrentMediaKey: () => '/tmp/video.mkv',
+    hasMpvClient: () => true,
+    getTrackedMediaKey: () => '/tmp/video.mkv',
+    resetTrackedMedia: () => {},
+    getWatchedSeconds: () => 1000,
+    maybeProbeAnilistDuration: async () => 1000,
+    ensureAnilistMediaGuess: async () => ({ title: 'Show', season: null, episode: 2 }),
+    hasAttemptedUpdateKey: (key) => attemptedKeys.has(key),
+    processNextAnilistRetryUpdate: async () => ({ ok: true, message: 'noop' }),
+    refreshAnilistClientSecretState: async () => 'token',
+    enqueueRetry: () => calls.push('enqueue'),
+    markRetryFailure: () => calls.push('mark-failure'),
+    markRetrySuccess: () => calls.push('mark-success'),
+    refreshRetryQueueState: () => calls.push('refresh'),
+    updateAnilistPostWatchProgress: async () => {
+      updateCalls += 1;
+      return {
+        status: 'error',
+        retryable: false,
+        message:
+          'AniList update not possible: Show is not in your AniList Planning or Watching list.',
+      };
+    },
+    rememberAttemptedUpdateKey: (key) => {
+      attemptedKeys.add(key);
+      calls.push(`remember:${key}`);
+    },
+    showMpvOsd: (message) => calls.push(`osd:${message}`),
+    logInfo: (message) => calls.push(`info:${message}`),
+    logWarn: (message) => calls.push(`warn:${message}`),
+    minWatchSeconds: 600,
+    minWatchRatio: 0.85,
+  });
+
+  await handler();
+  await handler();
+
+  assert.equal(updateCalls, 1);
+  assert.equal(calls.includes('enqueue'), false);
+  assert.equal(calls.includes('mark-failure'), false);
+  assert.ok(calls.some((call) => call.startsWith('remember:')));
+  assert.ok(calls.includes('refresh'));
+  assert.ok(calls.some((call) => call.startsWith('osd:AniList update not possible')));
+  assert.ok(calls.some((call) => call.startsWith('warn:AniList update not possible')));
+});
+
+test('createMaybeRunAnilistPostWatchUpdateHandler uses provided watched seconds from time-position events', async () => {
+  const calls: string[] = [];
+  let durationProbeOptions: unknown = null;
+  const handler = createMaybeRunAnilistPostWatchUpdateHandler({
+    getInFlight: () => false,
+    setInFlight: (value) => calls.push(`inflight:${value}`),
+    getResolvedConfig: () => ({}),
+    isAnilistTrackingEnabled: () => true,
+    getCurrentMediaKey: () => '/tmp/video.mkv',
+    hasMpvClient: () => true,
+    getTrackedMediaKey: () => '/tmp/video.mkv',
+    resetTrackedMedia: () => {},
+    getWatchedSeconds: () => 0,
+    maybeProbeAnilistDuration: async (_mediaKey, options) => {
+      durationProbeOptions = options;
+      return 1000;
+    },
+    ensureAnilistMediaGuess: async () => ({ title: 'Show', season: 2, episode: 8 }),
+    hasAttemptedUpdateKey: () => false,
+    processNextAnilistRetryUpdate: async () => ({ ok: true, message: 'noop' }),
+    refreshAnilistClientSecretState: async () => 'token',
+    enqueueRetry: () => calls.push('enqueue'),
+    markRetryFailure: () => calls.push('mark-failure'),
+    markRetrySuccess: () => calls.push('mark-success'),
+    refreshRetryQueueState: () => calls.push('refresh'),
+    updateAnilistPostWatchProgress: async (_accessToken, _title, _episode, season) => {
+      calls.push(`update:${season}`);
+      return { status: 'updated', message: 'updated ok' };
+    },
+    rememberAttemptedUpdateKey: () => calls.push('remember'),
+    showMpvOsd: (message) => calls.push(`osd:${message}`),
+    logInfo: (message) => calls.push(`info:${message}`),
+    logWarn: (message) => calls.push(`warn:${message}`),
+    minWatchSeconds: 600,
+    minWatchRatio: 0.85,
+  });
+
+  await handler({ watchedSeconds: 850 });
+
+  assert.deepEqual(durationProbeOptions, { force: true });
+  assert.ok(calls.includes('update:2'));
+  assert.ok(calls.includes('remember'));
+  assert.ok(calls.includes('osd:updated ok'));
+});
+
 test('createMaybeRunAnilistPostWatchUpdateHandler blocks concurrent runs before async gating', async () => {
   const calls: string[] = [];
   let inFlight = false;

src/main/runtime/anilist-post-watch.ts

@@ -2,22 +2,30 @@ import { isYoutubeMediaPath } from './youtube-playback';
 
 type AnilistGuess = {
   title: string;
+  season: number | null;
   episode: number | null;
 };
 
 type AnilistUpdateResult = {
   status: 'updated' | 'skipped' | 'error';
   message: string;
+  retryable?: boolean;
 };
 
 type RetryQueueItem = {
   key: string;
   title: string;
+  season?: number | null;
   episode: number;
 };
 
 type AnilistPostWatchRunOptions = {
   force?: boolean;
+  watchedSeconds?: number;
+};
+
+type AnilistDurationProbeOptions = {
+  force?: boolean;
 };
 
 export function buildAnilistAttemptKey(mediaKey: string, episode: number): string {
@@ -49,6 +57,7 @@ export function createProcessNextAnilistRetryUpdateHandler(deps: {
     accessToken: string,
     title: string,
     episode: number,
+    season?: number | null,
   ) => Promise<AnilistUpdateResult>;
   markSuccess: (key: string) => void;
   rememberAttemptedUpdateKey: (key: string) => void;
@@ -74,6 +83,7 @@ export function createProcessNextAnilistRetryUpdateHandler(deps: {
       accessToken,
       queued.title,
       queued.episode,
+      queued.season ?? null,
     );
     if (result.status === 'updated' || result.status === 'skipped') {
       deps.markSuccess(queued.key);
@@ -101,12 +111,15 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
   getTrackedMediaKey: () => string | null;
   resetTrackedMedia: (mediaKey: string | null) => void;
   getWatchedSeconds: () => number;
-  maybeProbeAnilistDuration: (mediaKey: string) => Promise<number | null>;
+  maybeProbeAnilistDuration: (
+    mediaKey: string,
+    options?: AnilistDurationProbeOptions,
+  ) => Promise<number | null>;
   ensureAnilistMediaGuess: (mediaKey: string) => Promise<AnilistGuess | null>;
   hasAttemptedUpdateKey: (key: string) => boolean;
   processNextAnilistRetryUpdate: () => Promise<{ ok: boolean; message: string }>;
   refreshAnilistClientSecretState: () => Promise<string | null>;
-  enqueueRetry: (key: string, title: string, episode: number) => void;
+  enqueueRetry: (key: string, title: string, episode: number, season?: number | null) => void;
   markRetryFailure: (key: string, message: string) => void;
   markRetrySuccess: (key: string) => void;
   refreshRetryQueueState: () => void;
@@ -114,6 +127,7 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
     accessToken: string,
     title: string,
     episode: number,
+    season?: number | null,
   ) => Promise<AnilistUpdateResult>;
   rememberAttemptedUpdateKey: (key: string) => void;
   showMpvOsd: (message: string) => void;
@@ -146,7 +160,10 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
 
     let watchedSeconds = 0;
     if (!force) {
-      watchedSeconds = deps.getWatchedSeconds();
+      watchedSeconds =
+        typeof options.watchedSeconds === 'number' && Number.isFinite(options.watchedSeconds)
+          ? options.watchedSeconds
+          : deps.getWatchedSeconds();
       if (!Number.isFinite(watchedSeconds) || watchedSeconds < deps.minWatchSeconds) {
         return;
       }
@@ -155,7 +172,10 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
     deps.setInFlight(true);
     try {
       if (!force) {
-        const duration = await deps.maybeProbeAnilistDuration(mediaKey);
+        const duration = await deps.maybeProbeAnilistDuration(mediaKey, {
+          force:
+            typeof options.watchedSeconds === 'number' && Number.isFinite(options.watchedSeconds),
+        });
         if (!duration || duration <= 0) {
           return;
         }
@@ -181,7 +201,7 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
 
       const accessToken = await deps.refreshAnilistClientSecretState();
       if (!accessToken) {
-        deps.enqueueRetry(attemptKey, guess.title, guess.episode);
+        deps.enqueueRetry(attemptKey, guess.title, guess.episode, guess.season);
         deps.markRetryFailure(attemptKey, 'cannot authenticate without anilist.accessToken');
         deps.refreshRetryQueueState();
         deps.showMpvOsd('AniList: access token not configured');
@@ -192,6 +212,7 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
         accessToken,
         guess.title,
         guess.episode,
+        guess.season,
       );
       if (result.status === 'updated') {
         deps.rememberAttemptedUpdateKey(attemptKey);
@@ -209,7 +230,15 @@ export function createMaybeRunAnilistPostWatchUpdateHandler(deps: {
         return;
       }
 
-      deps.enqueueRetry(attemptKey, guess.title, guess.episode);
+      if (result.retryable === false) {
+        deps.rememberAttemptedUpdateKey(attemptKey);
+        deps.refreshRetryQueueState();
+        deps.showMpvOsd(result.message);
+        deps.logWarn(result.message);
+        return;
+      }
+
+      deps.enqueueRetry(attemptKey, guess.title, guess.episode, guess.season);
       deps.markRetryFailure(attemptKey, result.message);
       deps.refreshRetryQueueState();
       deps.showMpvOsd(`AniList: ${result.message}`);

src/main/runtime/app-ready-main-deps.test.ts

@@ -36,6 +36,9 @@ test('app-ready main deps builder returns mapped app-ready runtime deps', async
     loadYomitanExtension: async () => {
       calls.push('load-yomitan');
     },
+    ensureYomitanExtensionLoaded: async () => {
+      calls.push('ensure-yomitan');
+    },
     handleFirstRunSetup: async () => {
       calls.push('handle-first-run-setup');
     },
@@ -67,6 +70,7 @@ test('app-ready main deps builder returns mapped app-ready runtime deps', async
   onReady.createMpvClient();
   await onReady.createMecabTokenizerAndCheck();
   await onReady.loadYomitanExtension();
+  await onReady.ensureYomitanExtensionLoaded?.();
   await onReady.handleFirstRunSetup();
   await onReady.prewarmSubtitleDictionaries?.();
   onReady.startBackgroundWarmups();
@@ -79,6 +83,7 @@ test('app-ready main deps builder returns mapped app-ready runtime deps', async
     'create-mpv-client',
     'create-mecab',
     'load-yomitan',
+    'ensure-yomitan',
     'handle-first-run-setup',
     'prewarm-dicts',
     'start-warmups',

src/main/runtime/app-ready-main-deps.ts

@@ -27,6 +27,7 @@ export function createBuildAppReadyRuntimeMainDepsHandler(deps: AppReadyRuntimeD
     createImmersionTracker: deps.createImmersionTracker,
     startJellyfinRemoteSession: deps.startJellyfinRemoteSession,
     loadYomitanExtension: deps.loadYomitanExtension,
+    ensureYomitanExtensionLoaded: deps.ensureYomitanExtensionLoaded,
     handleFirstRunSetup: deps.handleFirstRunSetup,
     prewarmSubtitleDictionaries: deps.prewarmSubtitleDictionaries,
     startBackgroundWarmups: deps.startBackgroundWarmups,

src/main/runtime/cli-command-context-deps.test.ts

@@ -81,6 +81,7 @@ test('build cli command context deps maps handlers and values', () => {
       return setTimeout(() => {}, 0);
     },
     logInfo: (message) => calls.push(`info:${message}`),
+    logDebug: (message) => calls.push(`debug:${message}`),
     logWarn: (message) => calls.push(`warn:${message}`),
     logError: (message) => calls.push(`error:${message}`),
   });

src/main/runtime/cli-command-context-deps.ts

@@ -18,7 +18,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
   initializeOverlay: () => void;
   toggleVisibleOverlay: () => void;
   togglePrimarySubtitleBar: () => void;
-  openFirstRunSetup: () => void;
+  openFirstRunSetup: (force?: boolean) => void;
   setVisibleOverlay: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
   startPendingMultiCopy: (timeoutMs: number) => void;
@@ -52,6 +52,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
   getMultiCopyTimeoutMs: () => number;
   schedule: (fn: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
   logInfo: (message: string) => void;
+  logDebug: (message: string) => void;
   logWarn: (message: string) => void;
   logError: (message: string, err: unknown) => void;
 }) {
@@ -106,6 +107,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
     getMultiCopyTimeoutMs: deps.getMultiCopyTimeoutMs,
     schedule: deps.schedule,
     logInfo: deps.logInfo,
+    logDebug: deps.logDebug,
     logWarn: deps.logWarn,
     logError: deps.logError,
   });

src/main/runtime/cli-command-context-factory.test.ts

@@ -82,6 +82,7 @@ test('cli command context factory composes main deps and context handlers', () =
     getMultiCopyTimeoutMs: () => 5000,
     schedule: (fn) => setTimeout(fn, 0),
     logInfo: () => {},
+    logDebug: () => {},
     logWarn: () => {},
     logError: () => {},
   });

src/main/runtime/cli-command-context-main-deps.test.ts

@@ -30,7 +30,8 @@ test('cli command context main deps builder maps state and callbacks', async ()
     initializeOverlayRuntime: () => calls.push('init-overlay'),
     toggleVisibleOverlay: () => calls.push('toggle-visible'),
     togglePrimarySubtitleBar: () => calls.push('toggle-primary-subtitle'),
-    openFirstRunSetupWindow: () => calls.push('open-setup'),
+    openFirstRunSetupWindow: (force?: boolean) =>
+      calls.push(`open-setup:${force === true ? 'force' : 'default'}`),
     setVisibleOverlayVisible: (visible) => calls.push(`set-visible:${visible}`),
 
     copyCurrentSubtitle: () => calls.push('copy-sub'),
@@ -110,6 +111,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
       return setTimeout(() => {}, 0);
     },
     logInfo: (message) => calls.push(`info:${message}`),
+    logDebug: (message) => calls.push(`debug:${message}`),
     logWarn: (message) => calls.push(`warn:${message}`),
     logError: (message) => calls.push(`error:${message}`),
   });
@@ -125,11 +127,19 @@ test('cli command context main deps builder maps state and callbacks', async ()
   assert.equal(deps.shouldOpenBrowser(), true);
   deps.showOsd('hello');
   deps.initializeOverlay();
-  deps.openFirstRunSetup();
+  deps.openFirstRunSetup(true);
   deps.setVisibleOverlay(true);
   deps.printHelp();
+  await deps.runUpdateCommand({ update: true } as never, 'initial');
 
-  assert.deepEqual(calls, ['osd:hello', 'init-overlay', 'open-setup', 'set-visible:true', 'help']);
+  assert.deepEqual(calls, [
+    'osd:hello',
+    'init-overlay',
+    'open-setup:force',
+    'set-visible:true',
+    'help',
+    'run-update',
+  ]);
 
   const retry = await deps.retryAnilistQueueNow();
   assert.deepEqual(retry, { ok: true, message: 'ok' });

src/main/runtime/cli-command-context-main-deps.ts

@@ -28,7 +28,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
   initializeOverlayRuntime: () => void;
   toggleVisibleOverlay: () => void;
   togglePrimarySubtitleBar: () => void;
-  openFirstRunSetupWindow: () => void;
+  openFirstRunSetupWindow: (force?: boolean) => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
 
   copyCurrentSubtitle: () => void;
@@ -65,6 +65,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
   getMultiCopyTimeoutMs: () => number;
   schedule: (fn: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
   logInfo: (message: string) => void;
+  logDebug: (message: string) => void;
   logWarn: (message: string) => void;
   logError: (message: string, err: unknown) => void;
 }) {
@@ -97,7 +98,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
     initializeOverlay: () => deps.initializeOverlayRuntime(),
     toggleVisibleOverlay: () => deps.toggleVisibleOverlay(),
     togglePrimarySubtitleBar: () => deps.togglePrimarySubtitleBar(),
-    openFirstRunSetup: () => deps.openFirstRunSetupWindow(),
+    openFirstRunSetup: (force?: boolean) => deps.openFirstRunSetupWindow(force),
     setVisibleOverlay: (visible: boolean) => deps.setVisibleOverlayVisible(visible),
     copyCurrentSubtitle: () => deps.copyCurrentSubtitle(),
     startPendingMultiCopy: (timeoutMs: number) => deps.startPendingMultiCopy(timeoutMs),
@@ -134,6 +135,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
     getMultiCopyTimeoutMs: () => deps.getMultiCopyTimeoutMs(),
     schedule: (fn: () => void, delayMs: number) => deps.schedule(fn, delayMs),
     logInfo: (message: string) => deps.logInfo(message),
+    logDebug: (message: string) => deps.logDebug(message),
     logWarn: (message: string) => deps.logWarn(message),
     logError: (message: string, err: unknown) => deps.logError(message, err),
   });