fix(jellyfin): show overlay, inject plugin, and fix stats title on playback (#77)

* fix(jellyfin): show overlay, inject plugin, and fix stats title on playb

- Show visible overlay automatically during Jellyfin playback so subtitleStyle applies
- Inject bundled mpv plugin on auto-launch so keybindings work without overlay focus
- Group Jellyfin playback stats under item metadata (jellyfin://host/item/id) instead of stream URLs so episodes merge with matching local titles
- Mark ffsubsync unavailable in subsync modal for remote media paths
- Drain queued second-instance commands even when onReady throws

* fix(overlay): stabilize macOS focus handoff and sidebar Yomitan pause

- Keep overlay visible during macOS foreground probe after overlay blur
- Hold sidebar hover-pause while a Yomitan lookup popup remains open

* fix(jellyfin): fix discovery loop, device identity, tray state, and Disc

- Derive device identity from OS hostname; remove legacy configurable client/device fields
- Prevent discovery playback from reloading active item, misreporting pause state, and duplicate overlay restores
- Restart stale tray discovery sessions without re-login when server drops SubMiner cast target
- Sync tray discovery checkbox state on Linux after CLI/startup/remote-session changes
- Stop Discord presence falling back to stream URLs; prime title before tokenized stream loads
- Fix picker library discovery when log level is above info
- Fix config.example.jsonc trailing commas and array formatting

* docs(release): trim and consolidate prerelease notes for 0.15.0

- Remove breaking changes section and several redundant bullet points
- Consolidate per-platform updater notes into a single entry
- Normalize em-dash separators to hyphens in section headers

* fix(config): remove trailing commas from config.example.jsonc

- Strip trailing commas throughout both config.example.jsonc copies
- Reformat inline arrays to multi-line for JSON strictness
- Update Jellyfin subtitle preload and playback launch tests and impl

* fix(tokenizer): preserve known-word highlight when POS filters suppress

- Known-word cache matches now set isKnown=true even for tokens excluded by POS filters
- POS exclusion gate suppresses N+1, frequency, and JLPT only; known status is computed before the gate
- Jellyfin subtitle preload continues after cleanup failures instead of aborting
- Update config docs and option description to document the known-word bypass behavior

* fix(jellyfin): send explicit hide/show overlay instead of toggle

- Track overlay visibility in plugin state; y-t uses explicit hide/show commands when state is known
- Prevent paused Jellyfin playback from resuming on overlay hide
- Fix subtitle cache cleanup to only remove dirs after successful cleanup

* fix(jellyfin): fix remote progress sync, seek reporting, and startup sto

- arm active playback before loadfile with loadedMediaPath: null to suppress premature stop events
- force immediate progress report on seek-like position jumps at the mpv time-pos level
- send positionTicks and failed=false in reportStopped payload
- remove EventName from HTTP timeline payloads (websocket-only field)
- add startup grace window to drop stop events before media finishes loading

* fix(jellyfin): fix overlay toggle sync, redirect reload, and AppImage bi

- Sync visible-overlay state back to plugin via script messages to avoid toggle/hide drift
- Collapse duplicate toggle events within 250ms to prevent hide-then-show on single keypress
- Preserve manual hide across Jellyfin path-changing redirects even when media-title drops
- Rearm managed subtitle defaults on path-changing redirects
- Route toggleVisibleOverlay session binding through plugin toggle instead of app-side IPC
- Show Linux/Hyprland overlay passively (showInactive) to avoid stealing mpv keyboard focus
- Fix AppImage binary resolution to prefer $APPIMAGE env over mounted inner binary
- Add stats window layer management so delete/update dialogs appear above stats window
- Fix Jellyfin remote progress sync during Linux websocket reconnect windows

* Fix CodeRabbit review feedback

* fix(jellyfin): subtitle timing, resume progress, and overlay sync

- Add per-stream subtitle delay persistence and auto timeline-offset correction
- Strip server-selected subtitle stream from mpv load URL; suppress plugin subtitle rearm and auto-start during app-managed preload
- Fix resume position lost when mpv resets on stop; use last known position for final progress/stopped reports
- Keep Play vs Resume distinct to avoid early seek race on normal play
- Fix discovery resume when remote play sends StartPositionTicks=0 despite saved progress
- Deduplicate show/hide overlay commands using recorded visibility state
- Rewrite docs-site Jellyfin page around cast-to-device UX

* test: update lifecycle cleanup assertion

* fix: clear aborted playback state, fix overlay passthrough, and guard du

- Reset app_managed_playback_pending on lifecycle cleanup to prevent state leak into next item
- Record visible overlay action only after command succeeds, not before
- Non-native passive overlay now always click-through on re-show (fix isNonNativePassiveOverlay ordering)
- Defer activeParsedSubtitleMediaPath assignment until after prefetch completes
- Move autoplay gate release into the hide branch of toggleVisibleOverlay
- Clear active Jellyfin playback when stopping media that never loaded
- Reset managed subtitle delay and delay key when no external tracks are available
- Await async removeDir in subtitle cache cleanup
- Guard duplicate delete clicks in MediaDetailView and SessionsTab with refs
- Escape key in DeleteConfirmDialog now calls stopPropagation and stopImmediatePropagation

plugin/subminer/binary.lua

@@ -114,6 +114,13 @@ function M.create(ctx)
 			end
 		end
 
+		if not environment.is_windows() then
+			local appimage_path = resolve_binary_candidate(os.getenv("APPIMAGE"))
+			if appimage_path and appimage_path ~= "" then
+				return appimage_path
+			end
+		end
+
 		return nil
 	end
 

plugin/subminer/lifecycle.lua

@@ -33,6 +33,20 @@ function M.create(ctx)
 		return nil
 	end
 
+	local function resolve_media_title()
+		local media_title = mp.get_property("media-title")
+		if type(media_title) == "string" and media_title ~= "" then
+			return media_title
+		end
+
+		local filename = mp.get_property("filename")
+		if type(filename) == "string" and filename ~= "" then
+			return filename
+		end
+
+		return nil
+	end
+
 	local function is_reload_end_file(reason)
 		return reason == "reload" or reason == "redirect"
 	end
@@ -71,6 +85,10 @@ function M.create(ctx)
 		if not has_matching_subminer_socket() then
 			return false
 		end
+		if state.skip_managed_subtitle_rearm_once then
+			state.skip_managed_subtitle_rearm_once = false
+			return true
+		end
 		mp.set_property_native("sub-auto", "fuzzy")
 		mp.set_property_native("sid", "auto")
 		mp.set_property_native("secondary-sid", "auto")
@@ -125,6 +143,10 @@ function M.create(ctx)
 
 	local function on_start_file()
 		if state.pending_reload_media_identity ~= nil then
+			local media_identity = resolve_media_identity()
+			if media_identity ~= nil and media_identity ~= state.pending_reload_media_identity then
+				rearm_managed_subtitle_load_defaults()
+			end
 			return
 		end
 		rearm_managed_subtitle_load_defaults()
@@ -132,24 +154,56 @@ function M.create(ctx)
 
 	local function on_file_loaded()
 		local media_identity = resolve_media_identity()
+		local media_title = resolve_media_title()
 		local retry_generation = next_auto_start_retry_generation()
 		local previous_media_identity = state.current_media_identity
+		local pending_reload_title = state.pending_reload_media_title
+		local pending_reload_reason = state.pending_reload_reason
 		local same_media_reload = (
 			media_identity ~= nil
 			and state.pending_reload_media_identity ~= nil
 			and media_identity == state.pending_reload_media_identity
+		) or (
+			state.pending_reload_media_identity ~= nil
+			and media_title ~= nil
+			and pending_reload_title ~= nil
+			and media_title == pending_reload_title
+		) or (
+			pending_reload_reason == "redirect"
+			and state.pending_reload_media_identity ~= nil
 		)
 		local same_media_loaded = (
 			media_identity ~= nil
 			and previous_media_identity ~= nil
 			and media_identity == previous_media_identity
 		)
+		local new_media_loaded = media_identity ~= nil and not same_media_reload and not same_media_loaded
 		state.pending_reload_media_identity = nil
+		state.pending_reload_media_title = nil
+		state.pending_reload_reason = nil
 		state.current_media_identity = media_identity
+		state.current_media_title = media_title
+		if state.app_managed_playback_pending then
+			state.app_managed_playback_pending = false
+			state.app_managed_playback_active = true
+		elseif new_media_loaded then
+			state.app_managed_playback_active = false
+		end
+		if new_media_loaded then
+			state.suppress_ready_overlay_restore = false
+		end
 
 		if same_media_reload then
 			subminer_log("debug", "lifecycle", "Skipping startup lifecycle for same-media mpv reload")
-			if state.overlay_running and resolve_auto_start_enabled() and process.has_matching_mpv_ipc_socket(opts.socket_path) then
+			if state.app_managed_playback_active then
+				return
+			end
+			if
+				state.overlay_running
+				and not state.suppress_ready_overlay_restore
+				and resolve_auto_start_enabled()
+				and process.has_matching_mpv_ipc_socket(opts.socket_path)
+			then
 				process.run_control_command_async("show-visible-overlay", {
 					socket_path = opts.socket_path,
 				})
@@ -167,6 +221,11 @@ function M.create(ctx)
 			process.disarm_auto_play_ready_gate()
 		end
 
+		if state.app_managed_playback_active then
+			subminer_log("debug", "lifecycle", "Skipping plugin auto-start for app-managed subtitle preload")
+			return
+		end
+
 		if should_auto_start then
 			start_overlay_when_socket_ready(retry_generation, media_identity, same_media_loaded, 1)
 			return
@@ -182,7 +241,12 @@ function M.create(ctx)
 		hover.clear_hover_overlay()
 		process.disarm_auto_play_ready_gate()
 		state.current_media_identity = nil
+		state.current_media_title = nil
 		state.pending_reload_media_identity = nil
+		state.pending_reload_media_title = nil
+		state.pending_reload_reason = nil
+		state.app_managed_playback_pending = false
+		state.app_managed_playback_active = false
 	end
 
 	local function register_lifecycle_hooks()
@@ -198,11 +262,18 @@ function M.create(ctx)
 			local reason = type(event) == "table" and event.reason or nil
 			if is_reload_end_file(reason) then
 				state.pending_reload_media_identity = state.current_media_identity or resolve_media_identity()
+				state.pending_reload_media_title = state.current_media_title or resolve_media_title()
+				state.pending_reload_reason = reason
 				return
 			end
 			next_auto_start_retry_generation()
 			state.current_media_identity = nil
+			state.current_media_title = nil
 			state.pending_reload_media_identity = nil
+			state.pending_reload_media_title = nil
+			state.pending_reload_reason = nil
+			state.app_managed_playback_pending = false
+			state.app_managed_playback_active = false
 			if state.overlay_running and reason ~= "quit" then
 				process.hide_visible_overlay()
 			end

plugin/subminer/messages.lua

@@ -6,6 +6,7 @@ function M.create(ctx)
 	local aniskip = ctx.aniskip
 	local hover = ctx.hover
 	local ui = ctx.ui
+	local state = ctx.state
 
 	local function register_script_messages()
 		mp.register_script_message("subminer-start", function(...)
@@ -17,6 +18,16 @@ function M.create(ctx)
 		mp.register_script_message("subminer-toggle", function()
 			process.toggle_overlay()
 		end)
+		mp.register_script_message("subminer-visible-overlay-hidden", function()
+			process.record_visible_overlay_visibility(false)
+		end)
+		mp.register_script_message("subminer-visible-overlay-shown", function()
+			process.record_visible_overlay_visibility(true)
+		end)
+		mp.register_script_message("subminer-managed-subtitles-loading", function()
+			state.skip_managed_subtitle_rearm_once = true
+			state.app_managed_playback_pending = true
+		end)
 		mp.register_script_message("subminer-menu", function()
 			ui.show_menu()
 		end)

plugin/subminer/process.lua

@@ -7,6 +7,7 @@ local OVERLAY_RESTART_PING_MAX_ATTEMPTS = 20
 local AUTO_PLAY_READY_LOADING_OSD = "Loading subtitle tokenization..."
 local AUTO_PLAY_READY_READY_OSD = "Subtitle tokenization ready"
 local DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS = 15
+local DUPLICATE_VISIBLE_OVERLAY_TOGGLE_SECONDS = 0.25
 
 function M.create(ctx)
 	local mp = ctx.mp
@@ -31,6 +32,16 @@ function M.create(ctx)
 		return options_helper.coerce_bool(raw_visible_overlay, false)
 	end
 
+	local function resolve_auto_start_visibility_action()
+		if resolve_visible_overlay_startup() then
+			if state.suppress_ready_overlay_restore then
+				return nil
+			end
+			return "show-visible-overlay"
+		end
+		return "hide-visible-overlay"
+	end
+
 	local function resolve_pause_until_ready()
 		local raw_pause_until_ready = opts.auto_start_pause_until_ready
 		if raw_pause_until_ready == nil then
@@ -67,6 +78,89 @@ function M.create(ctx)
 		return DEFAULT_AUTO_PLAY_READY_TIMEOUT_SECONDS
 	end
 
+	local function record_visible_overlay_action(action)
+		if action == "show-visible-overlay" then
+			state.visible_overlay_requested = true
+			state.suppress_ready_overlay_restore = false
+		elseif action == "hide-visible-overlay" then
+			state.visible_overlay_requested = false
+		elseif action == "toggle-visible-overlay" and state.visible_overlay_requested ~= nil then
+			state.visible_overlay_requested = not state.visible_overlay_requested
+			if state.visible_overlay_requested then
+				state.suppress_ready_overlay_restore = false
+			end
+		end
+	end
+
+	local function record_visible_overlay_visibility(visible)
+		if visible then
+			state.visible_overlay_requested = true
+			state.suppress_ready_overlay_restore = false
+			return
+		end
+		state.visible_overlay_requested = false
+		state.suppress_ready_overlay_restore = true
+	end
+
+	local function record_start_visibility_args(args)
+		for _, arg in ipairs(args) do
+			if arg == "--show-visible-overlay" then
+				record_visible_overlay_action("show-visible-overlay")
+				return
+			end
+			if arg == "--hide-visible-overlay" then
+				record_visible_overlay_action("hide-visible-overlay")
+				return
+			end
+		end
+	end
+
+	local function should_run_visibility_action(action)
+		if action == "show-visible-overlay" and state.visible_overlay_requested == true then
+			return false
+		end
+		if action == "hide-visible-overlay" and state.visible_overlay_requested == false then
+			return false
+		end
+		return true
+	end
+
+	local function run_visibility_action_if_needed(action, overrides, callback)
+		if action == nil then
+			if callback then
+				callback(true)
+			end
+			return
+		end
+		if not should_run_visibility_action(action) then
+			subminer_log("debug", "process", "Skipping duplicate visible overlay action: " .. tostring(action))
+			if callback then
+				callback(true)
+			end
+			return
+		end
+		run_control_command_async(action, overrides, callback)
+	end
+
+	local function should_ignore_duplicate_visible_overlay_toggle()
+		if type(mp.get_time) ~= "function" then
+			return false
+		end
+		local now = mp.get_time()
+		if type(now) ~= "number" then
+			return false
+		end
+
+		local previous = state.last_visible_overlay_toggle_time
+		state.last_visible_overlay_toggle_time = now
+		if type(previous) ~= "number" then
+			return false
+		end
+
+		local elapsed = now - previous
+		return elapsed >= 0 and elapsed < DUPLICATE_VISIBLE_OVERLAY_TOGGLE_SECONDS
+	end
+
 	local function normalize_socket_path(path)
 		if type(path) ~= "string" then
 			return nil
@@ -129,7 +223,7 @@ function M.create(ctx)
 
 	local function release_auto_play_ready_gate(reason)
 		if not state.auto_play_ready_gate_armed then
-			return
+			return false
 		end
 		local should_resume_playback = state.auto_play_ready_should_resume_playback == true
 		disarm_auto_play_ready_gate({ resume_playback = false })
@@ -140,6 +234,7 @@ function M.create(ctx)
 		else
 			subminer_log("info", "process", "Startup gate ready; leaving playback paused: " .. tostring(reason or "ready"))
 		end
+		return true
 	end
 
 	local function arm_auto_play_ready_gate()
@@ -179,9 +274,12 @@ function M.create(ctx)
 	end
 
 	local function notify_auto_play_ready()
-		release_auto_play_ready_gate("tokenization-ready")
+		local released_ready_gate = release_auto_play_ready_gate("tokenization-ready")
 		local force_ready_overlay_restore = state.force_ready_overlay_restore == true
 		state.force_ready_overlay_restore = false
+		if not released_ready_gate and not force_ready_overlay_restore then
+			return
+		end
 		if state.suppress_ready_overlay_restore and not force_ready_overlay_restore then
 			return
 		end
@@ -189,7 +287,7 @@ function M.create(ctx)
 			state.suppress_ready_overlay_restore = false
 		end
 		if state.overlay_running and (force_ready_overlay_restore or resolve_visible_overlay_startup()) then
-			run_control_command_async("show-visible-overlay", {
+			run_visibility_action_if_needed("show-visible-overlay", {
 				socket_path = opts.socket_path,
 			})
 		end
@@ -224,7 +322,7 @@ function M.create(ctx)
 
 			local should_show_visible = overrides.show_visible_overlay
 			if should_show_visible == nil then
-				should_show_visible = resolve_visible_overlay_startup()
+				should_show_visible = resolve_visible_overlay_startup() and not state.suppress_ready_overlay_restore
 			end
 			if should_show_visible then
 				table.insert(args, "--show-visible-overlay")
@@ -315,6 +413,9 @@ function M.create(ctx)
 			capture_stderr = true,
 		}, function(success, result, error)
 			local ok = success and (result == nil or result.status == 0)
+			if ok then
+				record_visible_overlay_action(action)
+			end
 			if callback then
 				callback(ok, result, error)
 			end
@@ -399,9 +500,6 @@ function M.create(ctx)
 
 	local function start_overlay(overrides)
 		overrides = overrides or {}
-		if overrides.auto_start_trigger == true then
-			state.suppress_ready_overlay_restore = false
-		end
 
 		if not binary.ensure_binary_available() then
 			subminer_log("error", "binary", "SubMiner binary not found")
@@ -424,10 +522,8 @@ function M.create(ctx)
 				elseif not state.auto_play_ready_gate_armed then
 					disarm_auto_play_ready_gate()
 				end
-				local visibility_action = resolve_visible_overlay_startup()
-						and "show-visible-overlay"
-					or "hide-visible-overlay"
-				run_control_command_async(visibility_action, {
+				local visibility_action = resolve_auto_start_visibility_action()
+				run_visibility_action_if_needed(visibility_action, {
 					socket_path = socket_path,
 					log_level = overrides.log_level,
 				})
@@ -470,6 +566,7 @@ function M.create(ctx)
 			state.overlay_running = true
 
 			local command = build_subprocess_command(args)
+			record_start_visibility_args(args)
 			mp.command_native_async({
 				name = "subprocess",
 				args = command.args,
@@ -495,13 +592,11 @@ function M.create(ctx)
 				end
 
 				if overrides.auto_start_trigger == true then
-					local visibility_action = resolve_visible_overlay_startup()
-							and "show-visible-overlay"
-						or "hide-visible-overlay"
-						run_control_command_async(visibility_action, {
-							socket_path = socket_path,
-							log_level = overrides.log_level,
-						})
+					local visibility_action = resolve_auto_start_visibility_action()
+					run_visibility_action_if_needed(visibility_action, {
+						socket_path = socket_path,
+						log_level = overrides.log_level,
+					})
 				end
 
 			end)
@@ -546,7 +641,8 @@ function M.create(ctx)
 		show_osd("Stopped")
 	end
 
-	local function hide_visible_overlay()
+	local function hide_visible_overlay(options)
+		options = options or {}
 		if not binary.ensure_binary_available() then
 			subminer_log("error", "binary", "SubMiner binary not found")
 			return
@@ -566,7 +662,9 @@ function M.create(ctx)
 			end
 		end)
 
-		disarm_auto_play_ready_gate()
+		disarm_auto_play_ready_gate({
+			resume_playback = options.resume_playback ~= false,
+		})
 	end
 
 	local function toggle_overlay()
@@ -575,7 +673,28 @@ function M.create(ctx)
 			show_osd("Error: binary not found")
 			return
 		end
+		if should_ignore_duplicate_visible_overlay_toggle() then
+			subminer_log("debug", "process", "Ignoring duplicate visible overlay toggle")
+			return
+		end
+		if state.visible_overlay_requested == true then
+			state.suppress_ready_overlay_restore = true
+			hide_visible_overlay({ resume_playback = false })
+			return
+		end
+		if state.visible_overlay_requested == false then
+			state.suppress_ready_overlay_restore = false
+			disarm_auto_play_ready_gate({ resume_playback = false })
+			run_control_command_async("show-visible-overlay", nil, function(ok)
+				if not ok then
+					subminer_log("warn", "process", "Show-visible-overlay command failed")
+					show_osd("Toggle failed")
+				end
+			end)
+			return
+		end
 		state.suppress_ready_overlay_restore = true
+		disarm_auto_play_ready_gate({ resume_playback = false })
 
 		run_control_command_async("toggle-visible-overlay", nil, function(ok)
 			if not ok then
@@ -705,6 +824,7 @@ function M.create(ctx)
 		build_command_args = build_command_args,
 		has_matching_mpv_ipc_socket = has_matching_mpv_ipc_socket,
 		run_control_command_async = run_control_command_async,
+		record_visible_overlay_visibility = record_visible_overlay_visibility,
 		run_binary_command_async = run_binary_command_async,
 		parse_start_script_message_overrides = parse_start_script_message_overrides,
 		ensure_texthooker_running = ensure_texthooker_running,

plugin/subminer/session_bindings.lua

@@ -251,6 +251,11 @@ function M.create(ctx)
 			return
 		end
 
+		if binding.actionId == "toggleVisibleOverlay" and type(process.toggle_overlay) == "function" then
+			process.toggle_overlay()
+			return
+		end
+
 		invoke_cli_action(binding.actionId, binding.payload)
 	end
 

plugin/subminer/state.lua

@@ -35,8 +35,15 @@ function M.new()
 		auto_play_ready_osd_timer = nil,
 		suppress_ready_overlay_restore = false,
 		force_ready_overlay_restore = false,
+		visible_overlay_requested = nil,
+		last_visible_overlay_toggle_time = nil,
 		current_media_identity = nil,
+		current_media_title = nil,
 		pending_reload_media_identity = nil,
+		pending_reload_media_title = nil,
+		pending_reload_reason = nil,
+		app_managed_playback_pending = false,
+		app_managed_playback_active = false,
 		auto_start_retry_generation = 0,
 		session_binding_generation = 0,
 		session_binding_names = {},