@video-lab/player-core 3.0.1 → 4.0.0

package/dist/index.mjs

@@ -172,18 +172,7 @@ function extractHttpStatus(err) {
 function isAutoplayBlocked(err) {
 	return typeof err === "object" && err !== null && "name" in err && err.name === "NotAllowedError";
 }
-/**
-* xgplayer 错误 → 契约的 PlayerError。
-*
-* 优先级:autoplay 拒绝 > HTTP 认证失败 > errorType > MediaError.code > 兜底 E_UNKNOWN。
-* 认证放在 errorType 之前,是因为 401/403 在 xgplayer 里也会报成 `network`,
-* 但对消费方来说"登录过期"和"网络断了"要给完全不同的提示。
-*
-* @example
-* mapXgplayerError({ errorType: 'timeout', message: '请求超时' })
-* // → { code: 'E_NETWORK_TIMEOUT', category: 'network', retryable: true, ... }
-*/
-function mapXgplayerError(err) {
+function mapXgplayerError(err, context = {}) {
 	if (isAutoplayBlocked(err)) return makePlayerError("E_AUTOPLAY_BLOCKED", "浏览器拒绝了自动播放", err);
 	if (typeof err !== "object" || err === null) return makePlayerError("E_UNKNOWN", typeof err === "string" ? err : "未知播放错误", err);
 	const xgErr = err;
@@ -191,9 +180,10 @@ function mapXgplayerError(err) {
 	const status = extractHttpStatus(xgErr);
 	if (status === 401) return makePlayerError("E_AUTH_EXPIRED", message, err);
 	if (status === 403) return makePlayerError("E_AUTH_EXPIRED", message, err);
+	const mediaCode = xgErr.mediaError?.code;
+	if (context.live === false && mediaCode === 4) return makePlayerError("E_MEDIA_NOT_SUPPORTED", message, err);
 	const byType = xgErr.errorType ? ERROR_TYPE_CODES[xgErr.errorType] : void 0;
 	if (byType) return makePlayerError(byType, message, err);
-	const mediaCode = xgErr.mediaError?.code;
 	if (typeof mediaCode === "number") {
 		const byMedia = MEDIA_ERROR_CODES[mediaCode];
 		if (byMedia) return makePlayerError(byMedia, message, err);
@@ -230,27 +220,43 @@ function refineByDetails(type, details) {
 	if (type === "otherError" && details.includes("Parsing")) return "E_MANIFEST_PARSE";
 }
 /**
-* hls.js 内核诊断 → 契约 `PlayerError`。
+* 点播专有的 details 细化（ADR-107，ADR-061「按 type 映射」的例外）。
 *
-* ─── 为什么需要它(#402)─────────────────────────────
+* hls.js 把子播放列表解析失败（`levelParsingError`）归在 `networkError` 下，按 type 会映射成
+* 可重连的 `E_NETWORK`。点播的列表是静态文件，解析失败重试也还是同一份（LiveLab HLS-15 实测），
+* 应为不可重试的 `E_MANIFEST_PARSE`。直播列表动态生成，偶发损坏可能下次就好，不细化。
+* 只作用于 fatal 的 error 通道；`kernelhealth` 分类不受影响。
 *
-* `xgplayer-hls.js` 的包装层把 **NETWORK / MEDIA 两类 fatal 错误私吞了**:
-* 前者 `startLoad()` 重试、后者 `recoverMediaError()`,**两条都不 `emit('error')`**。
-* 而 `status === 404` 时连重试都没有 —— 那个 `if` 直接落空,什么都不做。
+* ⚠️ **不含 `manifestParsingError`。** 主清单地址返回 HTML（地址错、CDN / WAF 拦截页、
+* 强制门户登录页）时 hls.js 报的就是它，其中一部分重试可能成功；错误覆盖层 e2e 正是这个形态
+* （开发服务器对不存在的路径回 200 HTML），要求保留重试按钮。
+*/
+function refineVodByDetails(type, details, context) {
+	if (context.live !== false || details === void 0) return void 0;
+	if (type === "networkError" && details === "levelParsingError") return "E_MANIFEST_PARSE";
+}
+/**
+* hls.js 内核诊断 → 契约 `PlayerError`。
 *
-* 实测(chromium):manifest 从头 404 → hls.js 报 `manifestLoadError` **fatal=true**,
-* 消费方拿到的契约 `error` **0 条**;分片全 abort 40s → 9 条 `hlsError` 含 1 条 fatal,
-* 契约 `error` 仍然 **0 条**。**连 fatal 都到不了消费方。**
+* `OwnedHlsPlugin` 统一把 hls.js 诊断送入本映射：fatal 进入契约 `error`，非 fatal 返回
+* `undefined` 并由调用方送入 `kernelhealth` 聚合。恢复动作由统一恢复调度决定，映射层不重试。
 *
 * @returns `undefined` 表示这条不该进 error 流(非 fatal)——见 spec § 非 fatal 不进 error 流
 */
-function mapHlsKernelError(payload) {
+function mapHlsKernelError(payload, context = {}) {
 	if (payload.errorFatal !== true) return void 0;
 	const type = payload.errorType;
 	if (typeof type !== "string") return void 0;
-	const code = refineByDetails(type, payload.errorDetails) ?? HLS_TYPE_CODES[type] ?? "E_UNKNOWN";
 	const details = payload.errorDetails ?? "未知";
-	return makePlayerError(code, `内核错误:${type} / ${details}`, {
+	const message = `内核错误:${type} / ${details}`;
+	if (payload.errorFatal === true && (payload.httpStatus === 401 || payload.httpStatus === 403)) return makePlayerError("E_AUTH_EXPIRED", message, {
+		message: `${type} / ${details}`,
+		errorType: type,
+		errorDetails: payload.errorDetails,
+		errorFatal: true,
+		status: payload.httpStatus
+	});
+	return makePlayerError(refineVodByDetails(type, payload.errorDetails, context) ?? refineByDetails(type, payload.errorDetails) ?? HLS_TYPE_CODES[type] ?? "E_UNKNOWN", message, {
 		message: `${type} / ${details}`,
 		errorType: type,
 		errorDetails: payload.errorDetails,
@@ -562,6 +568,27 @@ var HlsAdapter = class {
 };
 //#endregion
 //#region src/kernels/owned-hls-plugin.ts
+/**
+* hls.js 默认拒绝重试所有 4xx。运行中的 playlist / fragment 403 另有瞬时
+* CDN/鉴权抖动这一种已测歧义，最多额外尝试三次；401 与其他 4xx 仍按内核默认。
+*
+* `retry` 是内核已经批准的超时、5xx 等重试结果，必须原样保留，避免收窄既有策略。
+*/
+function shouldRetryTransientForbidden(_retryConfig, retryCount, isTimeout, response, retry) {
+	return retry || !isTimeout && response?.code === 403 && retryCount < 3;
+}
+/** 不修改 hls.js 全局默认值；每个播放器实例取得自己的浅拷贝。 */
+function withTransientForbiddenRetry(policy) {
+	const errorRetry = policy.default.errorRetry;
+	if (!errorRetry) return policy;
+	return { default: {
+		...policy.default,
+		errorRetry: {
+			...errorRetry,
+			shouldRetry: shouldRetryTransientForbidden
+		}
+	} };
+}
 /** 生产 HLS 内部装配层；恢复预算由统一调度器持有，不作为宿主扩展口导出。 */
 var OwnedHlsPlugin = class extends BasePlugin {
 	static get pluginName() {
@@ -606,14 +633,21 @@ var OwnedHlsPlugin = class extends BasePlugin {
 		if (!this.adapter) {
 			const media = this.player.video;
 			if (!(media instanceof HTMLMediaElement)) return;
-			const hlsOpts = { ...this.config.hlsOpts };
+			const config = this.config;
+			const hlsOpts = {
+				...config.hlsOpts,
+				playlistLoadPolicy: withTransientForbiddenRetry(config.hlsOpts?.playlistLoadPolicy ?? HlsLight.DefaultConfig.playlistLoadPolicy),
+				fragLoadPolicy: withTransientForbiddenRetry(config.hlsOpts?.fragLoadPolicy ?? HlsLight.DefaultConfig.fragLoadPolicy)
+			};
 			if (hlsOpts.startPosition === void 0 && typeof this.playerConfig.startTime === "number") hlsOpts.startPosition = this.playerConfig.startTime;
 			this.adapter = new HlsAdapter(media, (error) => {
 				if (this.disposed) return;
+				const status = error.response?.code;
 				this.player.emit("HLS_ERROR", {
 					errorType: error.type,
 					errorDetails: error.details,
-					errorFatal: error.fatal
+					errorFatal: error.fatal,
+					...typeof status === "number" && status >= 100 && status < 600 ? { httpStatus: status } : {}
 				});
 			}, hlsOpts);
 		}
@@ -682,6 +716,55 @@ var OwnedHlsPlugin = class extends BasePlugin {
 	}
 };
 //#endregion
+//#region src/last-frame-placeholder.ts
+function createLastFramePlaceholder(getMedia) {
+	let canvas = null;
+	const release = () => {
+		if (!canvas) return;
+		canvas.remove();
+		canvas.width = 0;
+		canvas.height = 0;
+		canvas = null;
+	};
+	const capture = () => {
+		if (canvas?.parentNode) return true;
+		release();
+		const media = getMedia();
+		if (!(media instanceof HTMLVideoElement) || !media.parentElement) return false;
+		const { videoWidth: width, videoHeight: height } = media;
+		if (media.readyState < 2 || width <= 0 || height <= 0) return false;
+		const next = media.ownerDocument.createElement("canvas");
+		next.width = width;
+		next.height = height;
+		try {
+			const context = next.getContext("2d");
+			if (!context) return false;
+			context.drawImage(media, 0, 0, width, height);
+		} catch {
+			return false;
+		}
+		next.dataset.sentinelLastFrame = "";
+		next.setAttribute("aria-hidden", "true");
+		const fit = media.ownerDocument.defaultView?.getComputedStyle(media).objectFit;
+		Object.assign(next.style, {
+			position: "absolute",
+			top: "0",
+			left: "0",
+			width: "100%",
+			height: "100%",
+			objectFit: fit && fit !== "fill" ? fit : "contain",
+			pointerEvents: "none"
+		});
+		media.insertAdjacentElement("afterend", next);
+		canvas = next;
+		return true;
+	};
+	return {
+		capture,
+		release
+	};
+}
+//#endregion
 //#region src/page-fullscreen.ts
 /**
 * 接管锁定的 xgplayer 3.0.26 网页全屏按钮与 Esc；宿主确认后才应用本地状态。
@@ -765,6 +848,11 @@ const BACKOFF = [
 	4e3
 ];
 /**
+* 复发观察期（ADR-105）：判恢复成功后这么久之内再次需要恢复，视为同一故障复发，
+* 新一轮沿用上一轮已用的动作次数与退避档位。持续故障因此在累计 3 次后收口为失败（#103）。
+*/
+const RELAPSE_WINDOW_MS = 15e3;
+/**
 * 实例级内部调度器。执行器须在 abort 时同步停止旧动作；Promise 完成仅代表命令结束。
 * 强播放证据由调用方判定后交 recovered；生产装配层负责映射公开事件。
 */
@@ -772,6 +860,11 @@ var RecoveryController = class {
 	execute;
 	onTransition;
 	active = null;
+	/**
+	* 最近一次判恢复成功的会话、时刻与已用次数。保留到下一次判成功（覆盖）、失败、
+	* 非自然恢复的取消、手动重试或换会话为止；被自然恢复取消的一轮不打断计数链。
+	*/
+	lastRecovered = null;
 	sequence = 0;
 	disposed = false;
 	suspended = false;
@@ -780,10 +873,13 @@ var RecoveryController = class {
 	events = [];
 	publishing = false;
 	actionDepth = 0;
-	constructor(execute, onTransition) {
+	constructor(execute, onTransition, options = {}) {
 		this.execute = execute;
 		this.onTransition = onTransition;
+		this.resolveStrategy = options.resolveStrategy ?? ((strategy) => strategy);
 	}
+	/** 见 {@link StrategyResolver}；未提供时按请求时的策略原样上报。 */
+	resolveStrategy;
 	/** 供装配层识别同步重入后的新 episode，不是公开播放器查询。 */
 	get activeEpisodeId() {
 		return this.active?.id ?? null;
@@ -798,15 +894,17 @@ var RecoveryController = class {
 			}
 			return this.active.id;
 		}
+		const trigger = input.trigger ?? "error";
 		const episode = {
 			id: ++this.sequence,
 			sessionId,
 			deadline: performance.now() + 6e4,
 			startedAt: performance.now(),
 			strategy: input.strategy ?? "reconnect",
-			trigger: input.trigger ?? "error",
+			trigger,
 			reason: input.reason,
-			attempt: 0,
+			attempt: this.inheritedAttempts(sessionId, trigger),
+			issued: 0,
 			token: null,
 			abort: null,
 			finishing: false
@@ -823,9 +921,18 @@ var RecoveryController = class {
 		if (!episode || episode.token !== token) return;
 		this.finish(episode, performance.now() >= episode.deadline ? "failed" : "recovered");
 	}
-	/** 第一动作尚未发出时原播放自行恢复，不制造一次成功动作。 */
+	/** 是否有已发出、尚未得到证据的动作；退避等待不算。 */
+	get attemptInFlight() {
+		return Boolean(this.active?.token && !this.active.finishing);
+	}
+	/** 在途动作已被确定性证据证伪时立即结束它；退避中没有动作可结束，不消耗预算。 */
+	failActiveAttempt() {
+		const episode = this.active;
+		if (episode?.token && !episode.finishing) this.failAttempt(episode, episode.token);
+	}
+	/** 本轮第一动作尚未发出时原播放自行恢复，不制造一次成功动作。 */
 	naturalRecovered() {
-		if (this.active?.attempt === 0) this.finish(this.active, "cancelled", "natural_recovery");
+		if (this.active?.issued === 0) this.finish(this.active, "cancelled", "natural_recovery");
 	}
 	/** 换源、用户暂停等取消原因由上层记录；取消不等同于预算耗尽。 */
 	cancel(outcome = "superseded") {
@@ -851,6 +958,19 @@ var RecoveryController = class {
 		this.disposed = true;
 		this.cancel("destroyed");
 	}
+	/**
+	* 复发继承的已用次数。手动重试总从头开始；换源（会话变化）不继承；
+	* 只有「判恢复成功」之后的观察期内才继承。
+	*/
+	inheritedAttempts(sessionId, trigger) {
+		const last = this.lastRecovered;
+		if (!last) return 0;
+		if (trigger === "manual" || last.sessionId !== sessionId) {
+			this.lastRecovered = null;
+			return 0;
+		}
+		return performance.now() - last.at < RELAPSE_WINDOW_MS ? last.attempt : 0;
+	}
 	schedule(episode) {
 		if (this.active !== episode) return;
 		const delay = BACKOFF[episode.attempt];
@@ -870,12 +990,14 @@ var RecoveryController = class {
 			this.finish(episode, "failed");
 			return;
 		}
+		const attempt = ++episode.attempt;
 		const token = Object.freeze({
 			episode: episode.id,
 			sessionId: episode.sessionId,
-			attempt: ++episode.attempt,
-			strategy: episode.strategy
+			attempt,
+			strategy: this.resolveStrategy(episode.strategy, attempt)
 		});
+		episode.issued += 1;
 		const abort = new AbortController();
 		episode.issuedStrategy = token.strategy;
 		episode.token = token;
@@ -914,6 +1036,12 @@ var RecoveryController = class {
 		episode.token = null;
 		if (phase !== "recovered") episode.abort?.abort();
 		this.active = null;
+		if (phase === "recovered") this.lastRecovered = {
+			sessionId: episode.sessionId,
+			at: performance.now(),
+			attempt: episode.attempt
+		};
+		else if (outcome !== "natural_recovery") this.lastRecovered = null;
 		this.publish(episode, phase, outcome ?? (phase === "failed" ? performance.now() >= episode.deadline ? "timeout" : "attempts_exhausted" : void 0));
 	}
 	publish(episode, phase, outcome) {
@@ -924,7 +1052,7 @@ var RecoveryController = class {
 			phase,
 			elapsedMs: Math.max(0, performance.now() - episode.startedAt),
 			maxAttempts: BACKOFF.length,
-			strategy: phase === "detected" || phase === "backoff" ? episode.strategy : episode.issuedStrategy ?? episode.strategy,
+			strategy: phase === "detected" || phase === "backoff" ? this.resolveStrategy(episode.strategy, episode.attempt + 1) : episode.issuedStrategy ?? episode.strategy,
 			trigger: episode.trigger,
 			...episode.reason ? { reason: episode.reason } : {},
 			...outcome ? { outcome } : {}
@@ -953,17 +1081,25 @@ var PlaybackRecovery = class {
 	sessionId;
 	emit;
 	display;
+	options;
 	controller;
 	error = null;
+	/** 最近一次非致命内核诊断的分类；只用于给无原因的失败补 `reason`（#105） */
+	diagnostic = null;
 	desiredPlayback = false;
 	exhausted = false;
 	disposed = false;
 	revision = 0;
-	constructor(sessionId, execute, emit, display) {
+	constructor(sessionId, execute, emit, display, options = {}) {
 		this.sessionId = sessionId;
 		this.emit = emit;
 		this.display = display;
-		this.controller = new RecoveryController(execute, (event) => this.transition(event));
+		this.options = options;
+		this.controller = new RecoveryController(execute, (event) => this.transition(event), { ...options.resolveStrategy ? { resolveStrategy: options.resolveStrategy } : {} });
+	}
+	/** 是否有已发出、尚未得到证据的恢复动作；退避等待不算。 */
+	get attemptInFlight() {
+		return !this.disposed && this.controller.attemptInFlight;
 	}
 	/** 执行器完成异步换源后复查最新意图，避免恢复用户已暂停的播放。 */
 	get playingIntent() {
@@ -982,8 +1118,10 @@ var PlaybackRecovery = class {
 				failed: true,
 				action: this.action
 			});
-		} else if (this.desiredPlayback && !this.exhausted) this.request("error");
-		else this.display({
+		} else if (this.desiredPlayback && !this.exhausted) {
+			this.request("error");
+			if (this.options.failsAttempt?.(error)) this.controller.failActiveAttempt();
+		} else this.display({
 			recovering: false,
 			failed: true,
 			action: this.action
@@ -999,20 +1137,30 @@ var PlaybackRecovery = class {
 			this.controller.cancel("user_paused");
 		} else if (this.error?.retryable && !this.exhausted) this.request("manual");
 	}
-	/** 正常播放结束后不再接受自动恢复意图；不伪报用户暂停或恢复成功。 */
+	/**
+	* 播放到达结尾。正常结束后不再接受自动恢复意图；不伪报用户暂停或恢复成功。
+	* 动作在途时到达结尾说明该动作没能恢复播放，按动作失败处理；预算耗尽后的结尾
+	* 也不抹掉失败终态（#97）。返回 false 表示这不是一次正常结束。
+	*/
 	endPlayback() {
-		if (this.disposed) return;
+		if (this.disposed) return false;
+		if (this.controller.attemptInFlight) {
+			this.controller.failActiveAttempt();
+			return false;
+		}
+		if (this.exhausted) return false;
 		const revision = ++this.revision;
 		this.desiredPlayback = false;
 		this.exhausted = false;
 		this.error = null;
 		this.controller.cancel("superseded");
-		if (this.disposed || revision !== this.revision) return;
+		if (this.disposed || revision !== this.revision) return true;
 		this.display({
 			recovering: false,
 			failed: false,
 			action: "none"
 		});
+		return true;
 	}
 	/** 接受/合并手动重试；播放成功仍以当前动作的强证据为准。 */
 	async retry() {
@@ -1048,6 +1196,19 @@ var PlaybackRecovery = class {
 			action: "none"
 		});
 	}
+	/**
+	* 记录非致命内核诊断（`kernelhealth` degraded）。不触发恢复，只在恢复失败而没有致命错误时
+	* 作为原因来源（#105）；`other` 分类无法对应错误码，不记录。
+	*
+	* `auth` 是内核诊断里带 401/403 时由装配层单独给出的更具体分类（#114）：密钥或分片被拒
+	* 之后内核会继续重试并报网络类诊断，所以它在本轮内粘住，不能被后到的网络/媒体诊断冲掉，
+	* 否则「要重新取签名 URL」又会退化成「网络不好，再试试」。换源与恢复成功照旧清空。
+	*/
+	noteKernelHealth(reason) {
+		if (this.disposed || reason === "other") return;
+		if (this.diagnostic === "auth" && reason !== "auth") return;
+		this.diagnostic = reason;
+	}
 	/** 页面隐藏只暂停动作，不暂停总预算。 */
 	setSuspended(hidden) {
 		this.controller.setSuspended(hidden);
@@ -1058,6 +1219,7 @@ var PlaybackRecovery = class {
 		this.revision += 1;
 		this.sessionId = sessionId;
 		this.error = null;
+		this.diagnostic = null;
 		this.exhausted = false;
 		this.controller.cancel("source_changed");
 	}
@@ -1067,6 +1229,16 @@ var PlaybackRecovery = class {
 		this.disposed = true;
 		this.controller.destroy();
 	}
+	/**
+	* 恢复失败而本轮没有携带原因时的补填（#105）。致命错误发起或并入恢复时已带上错误码，
+	* 走不到这里；这里只处理非致命诊断分类，都没有（纯起播超时 / 纯卡顿）时为 `E_NETWORK_TIMEOUT`。
+	*/
+	get failureReason() {
+		if (this.diagnostic === "auth") return "E_AUTH_EXPIRED";
+		if (this.diagnostic === "network") return "E_NETWORK";
+		if (this.diagnostic === "media") return "E_MEDIA_DECODE";
+		return "E_NETWORK_TIMEOUT";
+	}
 	get action() {
 		if (!this.error || this.error.retryable) return "retry";
 		if (this.error.category === "autoplay") return "play";
@@ -1085,6 +1257,7 @@ var PlaybackRecovery = class {
 		if (event.sessionId === this.sessionId && event.phase === "failed") this.exhausted = true;
 		if (event.sessionId === this.sessionId && (event.phase === "recovered" || event.outcome === "natural_recovery")) {
 			this.error = null;
+			this.diagnostic = null;
 			this.exhausted = false;
 		}
 		this.emit({
@@ -1092,7 +1265,8 @@ var PlaybackRecovery = class {
 			payload: RecoveryPayloadSchema.parse({
 				...fact,
 				recoveryId: episode,
-				...event.phase === "recovered" ? { validatedBy: "playing_position_advance" } : {}
+				...event.phase === "recovered" ? { validatedBy: "playing_position_advance" } : {},
+				...event.phase === "failed" && !fact.reason ? { reason: this.failureReason } : {}
 			})
 		});
 		if (this.disposed || event.sessionId !== this.sessionId || revision !== this.revision) return;
@@ -1229,7 +1403,8 @@ const DEFAULT_CONFIG$5 = {
 * FullscreenGuardPlugin(P2)· iOS 微信原生全屏崩溃防护
 *
 * 解决的 pitfall:**#7**(iOS 26 微信里触发 `<video>` 原生全屏 `webkitEnterFullscreen()`
-* 直接崩溃 / 白屏)。ARCHITECTURE § 10.1 的处置是「禁用原生全屏 + CSS 兜底」。
+* 直接崩溃 / 白屏)。处置是「禁用原生全屏 + CSS 兜底」；坑点事实源见
+* `.claude/context/xgplayer-pitfalls.md`。
 *
 * 做法:仅在 iOS 微信环境,把媒体元素上的 `webkitEnterFullscreen` 换成 no-op,**阻断**
 * 会崩的原生全屏路径。xgplayer / 团队层的 CSS 伪全屏(操作容器,不走 `webkitEnterFullscreen`)
@@ -1279,7 +1454,9 @@ var FullscreenGuardPlugin = class extends BasePlugin {
 const DEFAULT_CONFIG$4 = {
 	enabled: true,
 	stallThresholdMs: 2e3,
-	pollIntervalMs: 1e3
+	pollIntervalMs: 1e3,
+	waitingStallThresholdMs: 1e3,
+	sustainedStallMs: 3e3
 };
 /**
 * 连续几次采样余量下降就判定「在净流失」(ADR-071)。
@@ -1304,13 +1481,16 @@ const DRAIN_STREAK = 3;
 *
 * 解决的 pitfall:**#13**(卡顿检测无信号上报 / 冻帧型隐性卡死)。见 ADR-026。
 *
-* 这是 11 个插件里唯一的**观察者**——不修任何东西,只**测量**播放质量并通过契约事件
-* `stalled` 上报(Phase-1 灰度卡顿率 / 首帧 KPI 的数据源)。
+* 它负责**测量**播放质量并通过契约事件 `stalled` 上报(Phase-1 灰度卡顿率 / 首帧 KPI 的
+* 数据源)；持续卡顿达到阈值时只提交恢复意图，实际动作仍由统一恢复调度执行。
 *
 * 两条测量路径喂同一个状态机(`stalling`),避免重复计数:
 * - **显性卡顿**:`waiting` → 进入卡顿(记开始时刻 + 位置);`playing` → 结束(算 `durationMs`)。
 * - **隐性卡顿(冻帧)**:定时轮询 `currentTime`,播放中却连续 `stallThresholdMs` 不推进 →
 *   进入卡顿;之后推进了 → 结束。这类卡死 xgplayer 不发 `waiting`,只能主动抓。
+* - **视频帧冻结(#102 · ADR-104)**:`currentTime` 在走、已解码视频帧却连续 `stallThresholdMs`
+*   不涨 → 进入 playback 卡顿;帧恢复增长才结束。视频解码停了而音频照常解码时,
+*   `<video>` 按音频时钟推进 `currentTime`,浏览器不发 `waiting` —— 只看时钟的两条路径都看不见。
 *
 * **不计后台卡顿**:`document.hidden` 时不进入卡顿——切后台 `currentTime` 本就停,那不是
 * 质量问题(iOS 后台切回归 VisibilityPlugin)。
@@ -1343,6 +1523,14 @@ var HealthMonitorPlugin = class extends BasePlugin {
 	/** 轮询用:上次看到的 currentTime + 它上次推进的时刻 */
 	lastTime = 0;
 	lastAdvanceAt = 0;
+	/** 帧冻结判据用:上次读到的已解码帧数(`null` = 没有基准)+ 它上次增长的时刻 */
+	lastFrames = null;
+	lastFrameAdvanceAt = 0;
+	/**
+	* 本次加载里**亲眼见过**帧数增长吗。没见过就不启用帧判据 ——
+	* 纯音频流、不支持 `getVideoPlaybackQuality` 的浏览器,帧数恒为 0,那不是冻结。
+	*/
+	sawFrameAdvance = false;
 	/** 上一次采到的余量;`null` 表示还没有基准(起播 / 刚复位) */
 	lastMargin = null;
 	/** 已经连续下降了几次 */
@@ -1356,6 +1544,10 @@ var HealthMonitorPlugin = class extends BasePlugin {
 	*/
 	sawBufferAdvance = false;
 	pollTimer = null;
+	/** `waiting` 到达、尚未满显性阈值的在途计时器(ADR-103) */
+	waitingTimer = null;
+	/** 当前卡顿持续满 `sustainedStallMs` 的计时器;只为 playback 卡顿设置 */
+	sustainedTimer = null;
 	get monitorConfig() {
 		return {
 			...DEFAULT_CONFIG$4,
@@ -1371,14 +1563,40 @@ var HealthMonitorPlugin = class extends BasePlugin {
 		this.on(Events.PLAYING, this.handlePlaying);
 		this.on(Events.SEEKING, this.handleSeeking);
 		this.on(Events.SEEKED, this.handleSeeked);
+		this.on(Events.LOAD_START, this.handleLoadStart);
 		this.lastAdvanceAt = now();
 		this.pollTimer = setInterval(this.poll, this.monitorConfig.pollIntervalMs);
 	}
 	/** 用箭头函数保持 this,否则 off / clearInterval 匹配不上(见 CLAUDE.md 红线) */
 	handleWaiting = () => {
-		this.enterStall();
+		if (this.stalling || this.waitingTimer !== null || isHidden()) return;
+		const kind = this.classifyStall();
+		const onsetAt = now();
+		const onsetPosition = numberOr$2(this.surface.currentTime, 0);
+		this.waitingTimer = setTimeout(() => {
+			this.waitingTimer = null;
+			if (numberOr$2(this.surface.currentTime, onsetPosition) > onsetPosition) return;
+			this.enterStall(onsetAt, kind);
+		}, this.monitorConfig.waitingStallThresholdMs);
+	};
+	/** 媒体开始新的加载(换源 / 重拉):回到「未见首帧」,重拉后的起播等待不再记成 playback(ADR-103) */
+	handleLoadStart = () => {
+		this.sawFirstFrame = false;
+		this.lastTime = 0;
+		this.lastAdvanceAt = now();
+		this.resetFrameBase();
 	};
+	resetFrameBase() {
+		this.lastFrames = null;
+		this.sawFrameAdvance = false;
+		this.lastFrameAdvanceAt = now();
+	}
+	clearWaiting() {
+		if (this.waitingTimer !== null) clearTimeout(this.waitingTimer);
+		this.waitingTimer = null;
+	}
 	handlePlaying = () => {
+		this.clearWaiting();
 		this.exitStall();
 		this.sawFirstFrame = true;
 	};
@@ -1405,19 +1623,61 @@ var HealthMonitorPlugin = class extends BasePlugin {
 		if (this.surface.paused === true || isHidden()) {
 			this.lastTime = t;
 			this.lastAdvanceAt = now();
+			this.lastFrameAdvanceAt = now();
+			this.lastFrames = this.readFrames();
 			this.resetDrain();
 			return;
 		}
 		this.sampleBufferHealth();
+		const framesFrozen = this.sampleFrames();
 		if (t > this.lastTime) {
 			this.lastTime = t;
 			this.lastAdvanceAt = now();
+			if (framesFrozen) {
+				this.clearWaiting();
+				this.enterStall(this.lastFrameAdvanceAt, this.classifyStall());
+				return;
+			}
 			this.exitStall();
 			return;
 		}
-		if (!this.stalling && now() - this.lastAdvanceAt >= this.monitorConfig.stallThresholdMs) this.enterStall();
+		if (!this.stalling && now() - this.lastAdvanceAt >= this.monitorConfig.stallThresholdMs) {
+			this.clearWaiting();
+			this.enterStall(this.lastAdvanceAt, this.classifyStall());
+		}
 	};
 	/**
+	* 采一次已解码视频帧数,返回「帧是否已冻结满 `stallThresholdMs`」(#102)。
+	*
+	* 只在见过帧数增长之后才可能返回 true;计数回退(换源重建)时重置基准。
+	* seek 中解码会短暂停下,不按冻结算。
+	*/
+	sampleFrames() {
+		const frames = this.readFrames();
+		if (frames === null) return false;
+		const prev = this.lastFrames;
+		this.lastFrames = frames;
+		if (prev !== null && frames < prev) {
+			this.sawFrameAdvance = false;
+			this.lastFrameAdvanceAt = now();
+			return false;
+		}
+		if (prev !== null && frames > prev) {
+			this.sawFrameAdvance = true;
+			this.lastFrameAdvanceAt = now();
+			return false;
+		}
+		if (this.seeking) {
+			this.lastFrameAdvanceAt = now();
+			return false;
+		}
+		return this.sawFrameAdvance && now() - this.lastFrameAdvanceAt >= this.monitorConfig.stallThresholdMs;
+	}
+	readFrames() {
+		const total = numberOr$2(this.surface.videoFrameInfo?.total, NaN);
+		return Number.isFinite(total) ? total : null;
+	}
+	/**
 	* 采一次缓冲余量,判断是不是在净流失(ADR-071)。
 	*
 	* **判据是「连续下降」,不是「低于某个秒数」。** 实测健康播放的余量是
@@ -1499,20 +1759,44 @@ var HealthMonitorPlugin = class extends BasePlugin {
 		const end = buffered.end(buffered.length - 1);
 		return Number.isFinite(end) ? end : null;
 	}
-	enterStall() {
+	/**
+	* @param onsetAt 这次卡顿**开始**的时刻(开始等待 / 最后一次推进),`durationMs` 与持续阈值都从它算
+	* @param kind 开始时定下的分类
+	*/
+	enterStall(onsetAt, kind) {
 		if (this.stalling) return;
 		if (isHidden()) return;
 		this.stalling = true;
-		this.stallStartAt = now();
-		this.stallKind = this.classifyStall();
+		this.stallStartAt = onsetAt;
+		this.stallKind = kind;
 		const position = numberOr$2(this.surface.currentTime, 0);
 		this.monitorConfig.onStall?.({
 			phase: "start",
 			position,
-			kind: this.stallKind
+			kind
 		});
+		if (kind !== "playback") return;
+		const remaining = Math.max(0, this.monitorConfig.sustainedStallMs - (now() - onsetAt));
+		this.armSustained(kind, remaining);
+	}
+	/**
+	* 满阈值请求恢复，卡顿仍在则每隔 `sustainedStallMs` 重申。只请求一次会丢请求：
+	* 卡顿恰在上一轮恢复判成功前一刻开始时，请求被并入那一轮后随之结束，画面冻住却再无恢复（ADR-105 ④）。
+	*/
+	armSustained(kind, delay) {
+		this.sustainedTimer = setTimeout(() => {
+			this.sustainedTimer = null;
+			if (!this.stalling) return;
+			this.monitorConfig.onSustainedStall?.({
+				kind,
+				position: numberOr$2(this.surface.currentTime, 0)
+			});
+			this.armSustained(kind, this.monitorConfig.sustainedStallMs);
+		}, delay);
 	}
 	exitStall() {
+		if (this.sustainedTimer !== null) clearTimeout(this.sustainedTimer);
+		this.sustainedTimer = null;
 		if (!this.stalling) return;
 		this.stalling = false;
 		const position = numberOr$2(this.surface.currentTime, 0);
@@ -1528,6 +1812,10 @@ var HealthMonitorPlugin = class extends BasePlugin {
 			clearInterval(this.pollTimer);
 			this.pollTimer = null;
 		}
+		this.clearWaiting();
+		if (this.sustainedTimer !== null) clearTimeout(this.sustainedTimer);
+		this.sustainedTimer = null;
+		this.off(Events.LOAD_START, this.handleLoadStart);
 		this.off(Events.WAITING, this.handleWaiting);
 		this.off(Events.PLAYING, this.handlePlaying);
 		this.off(Events.SEEKING, this.handleSeeking);
@@ -1550,8 +1838,7 @@ function isHidden() {
 /**
 * MediaSessionPlugin · 把契约的 `source.metadata` 喂给 W3C Media Session API
 *
-* 它**不解决任何 pitfall**,所以不在 11 个稳定性插件那张表里 —— 归类上与
-* `PlayableStatePlugin` 同档(见 CLAUDE.md「第 12 / 13 个插件」)。
+* 它**不解决任何 pitfall**，而是与 `PlayableStatePlugin` 同属生产 preset 的平台接线层。
 *
 * ## 为什么设置点必须在这一层
 *
@@ -1655,7 +1942,7 @@ var MediaSessionPlugin = class extends BasePlugin {
 //#region src/plugins/playable-state.ts
 const DEFAULT_CONFIG$3 = {
 	enabled: true,
-	bufferingDebounceMs: 300,
+	bufferingDebounceMs: 1e3,
 	droppedRateThreshold: 15,
 	degradedSamples: 3,
 	pollIntervalMs: 1e3,
@@ -1695,6 +1982,10 @@ const REASON_TABLE = {
 		playable: false,
 		recoverable: true
 	},
+	source_switching: {
+		playable: false,
+		recoverable: true
+	},
 	autoplay_blocked: {
 		playable: false,
 		recoverable: false
@@ -1718,6 +2009,7 @@ const PRIORITY = [
 	"error",
 	"frame_disconnected",
 	"autoplay_blocked",
+	"source_switching",
 	"reconnecting",
 	"stalled",
 	"buffering",
@@ -1726,7 +2018,7 @@ const PRIORITY = [
 	"ok"
 ];
 /**
-* PlayableStatePlugin(第 12 个稳定性插件)· 聚合播放状态
+* PlayableStatePlugin · 聚合播放状态
 *
 * 见 ADR-043 / issue #121。**它不产生新信息,只产生唯一结论。**
 *
@@ -1739,7 +2031,7 @@ const PRIORITY = [
 * **信号从两处来,分工是固定的**:
 * - **原生信号**(本插件自己 `this.on`):`loadeddata` / `play` / `waiting` / `playing`
 * - **兄弟插件的信号**(create-player 调本插件的 `setXxx`):卡顿(HealthMonitor)、
-*   重连(Reconnect)、自动播放被拒(AutoplayGuard)、错误(create-player 的 error 映射)
+*   恢复调度、自动播放被拒(AutoplayGuard)、错误(create-player 的 error 映射)
 *
 * 之所以不让本插件直接监听那几个 —— 它们的判定逻辑在各自插件里(比如冻帧要轮询
 * `currentTime` 才测得出来),重听一遍就是重实现一遍,两份实现必然漂移。
@@ -1797,7 +2089,7 @@ var PlayableStatePlugin = class extends BasePlugin {
 		this.stalling = value;
 		this.publish();
 	}
-	/** ReconnectPlugin 的重连状态机。重连**失败**归 `setError`,不是这里 */
+	/** 统一恢复调度的重连状态。恢复**失败**归 `setRecovery`,不是这里 */
 	setReconnecting(value) {
 		if (this.reconnecting === value) return;
 		this.reconnecting = value;
@@ -1887,6 +2179,7 @@ var PlayableStatePlugin = class extends BasePlugin {
 			error: this.errored,
 			frame_disconnected: false,
 			autoplay_blocked: this.autoplayBlocked,
+			source_switching: false,
 			reconnecting: this.reconnecting,
 			stalled: this.stalling,
 			buffering: this.buffering,
@@ -1939,7 +2232,7 @@ const DEFAULT_CONFIG$2 = { restoreRootStyle: true };
 * 解决的 pitfall:**#3**(destroy 后事件监听器残留)、**#4**(destroy 后 timer / root 样式残留)、
 * **#23**(反复 destroy 崩溃)。
 *
-* **没有 `enabled` 开关**——ARCHITECTURE § 10.2 明确它"强制,不可关"。
+* **没有 `enabled` 开关**——内存泄漏与重复销毁防护是强制能力，不提供关闭入口。
 * 一个能被关掉的内存泄漏防护没有意义。
 *
 * 注意 xgplayer 的 `BasePlugin.__destroy()` 本身已经会做 `offAll()` + `clearAllTimers(this)`,
@@ -2019,13 +2312,13 @@ function pickKernel(type, env) {
 * 最早也只到 `beforeCreate`,拿不到这个时机。所以它是一个纯函数,
 * 由 create-player 在构造 player 前调用。纯函数也更好测:UA 直接传进来就行。
 *
-* 选择规则(ARCHITECTURE § 8.2):
+* 选择规则（见 ADR-056 与 MEDIA-SOURCE-GUIDE）：
 * 1. iOS / 微信 / QQ / UC / 夸克 → **强制 HLS**;没 HLS 退 MP4;只剩 FLV 抛 `E_MEDIA_NOT_SUPPORTED`
 * 2. 其他平台:直播 `flv → hls → mp4`(FLV 延迟低);点播 `hls → mp4 → flv`(HLS 功能全)
 *
 * **降级只发生在选源这一刻,没有运行时兜底。** 上面的「→」是**候选缺失**时往下取
 * (没有 FLV 就用 HLS),**不是播放失败后换一个再试** —— 选完之后 `candidates` 里
-* 剩下的项没有任何代码会再读:ReconnectPlugin 重连 reload 的是同一个 URL(#192),
+* 剩下的项没有任何代码会再读：统一恢复仍重拉同一个 URL(#192),
 * 而 `load()` 跨内核会直接抛 `E_METHOD_NOT_SUPPORTED`。想要真兜底就得销毁重建 player,
 * 那是一条要走 ADR 的独立能力(#217)。
 *
@@ -2059,7 +2352,7 @@ function routeSource(source, env) {
 			reason: "无 HLS 候选,回退到原生 MP4",
 			routeReason: "native_mp4_fallback"
 		};
-		throwPlayerError("E_MEDIA_NOT_SUPPORTED", "FLV 在 iOS / 微信 / UC / 夸克 下无法播放,且候选源里没有 HLS 兜底。FLV 请始终和 HLS 一起放进 sources 数组。");
+		throwPlayerError("E_MEDIA_NOT_SUPPORTED", "当前 SDK 不支持在 iOS / 微信 / UC / 夸克中播放 FLV,且候选源里没有 HLS 兜底。FLV 请始终和 HLS 一起放进 sources 数组。");
 	}
 	const order = source.live ? [
 		"flv",
@@ -2129,7 +2422,7 @@ const DEFAULT_CONFIG$1 = {
 * iOS 把播放页切到后台再切回时,系统可能已回收底层 MSE / 解码管线:画面冻结在最后一帧、
 * `currentTime` 不再推进、声音丢失。xgplayer 自己不会恢复,消费方看到的是"卡死"。
 *
-* 策略(ARCHITECTURE § 10.3「信号 + 外层重建」的插件内自愈版):
+* 策略（见 ADR-079、ADR-098/099 的统一恢复边界）：
 * - 切**后台**(`document.hidden`)时,若正在播放,记下 `wasPlaying` + 当时的 `currentTime`。
 * - 切**回前台**时,只处理**直播**(点播 iOS 原生能续播,reload 会丢进度 → 不动)。
 *   等 `probeDelayMs` 给系统一个自恢复窗口,再探测:`currentTime` 没推进、或 paused → 判定卡死
@@ -2137,8 +2430,9 @@ const DEFAULT_CONFIG$1 = {
 *
 * 自愈的触发、尝试、验证和结果由 create-player 统一出为 `recovery` 事件；健康时不产生事件。
 *
-* 插件不越界 `destroy` player(§ 10.3 红线),只重新拉流(`reloadStream`)——与 ReconnectPlugin
-* **共用同一个实现**;从前是「同一手段」但各写各的,结果 #192 的修复只落在一边(见 `reload-stream.ts`)。
+* 生产装配下插件只提交恢复意图；没有协调器的独立使用才回落到 `reloadStream`。
+* 旧 ReconnectPlugin 曾与它各写一套重拉，#192 的修复只落在一边，因此两条历史路径后来共用
+* `reload-stream.ts`。
 *
 * @example
 * new Player({ el, plugins: [VisibilityPlugin], visibility: { isIOS: env.isIOS } })
@@ -2340,7 +2634,7 @@ const DEFAULT_CONFIG = {
 *
 * 解决的 pitfall:**#28**(覆盖层 z-index 冲突)、**#29**(fullscreen 时兄弟元素遮挡)
 * —— 部分 Android 浏览器 / WebView 把视频层的 z-index 抬得过高,
-* 盖住宿主的弹窗 / 抽屉 / toast(ARCHITECTURE § 10.1「视频层级过高盖弹窗」)。
+* 盖住宿主的弹窗 / 抽屉 / toast；完整坑点说明见 `.claude/context/xgplayer-pitfalls.md`。
 *
 * ⚠️ 这两个编号**此前不在这里**:JSDoc 只写着「层级冲突」四个字,而
 * `.claude/context/xgplayer-pitfalls.md`(35 个编号的唯一事实源)的快速索引表
@@ -2392,9 +2686,13 @@ var ZIndexGuardPlugin = class extends BasePlugin {
 /**
 * 观察一次恢复动作的强播放证据。仅 playing 后正常位置推进算成功；
 * seek、暂停和等待会重置基准。调用方负责把成功关联到当前动作凭据。
+* 点播传入 `beyond`（故障位置）时，推进还必须越过它：从头重播出的前缀不是恢复（#96）。
+* 有视频画面（`videoWidth > 0`）且拿得到解码帧计数时，还要求帧数自基准后增长：
+* 视频解码停而音频照走时位置也会推进，那不是画面恢复（#103 · ADR-105）。
 */
-function observeRecoveryPlayback(media, signal, recovered) {
+function observeRecoveryPlayback(media, signal, recovered, options = {}) {
 	let baseline = null;
+	let frameBaseline = null;
 	let playingSeen = false;
 	let disposed = false;
 	const reset = () => {
@@ -2404,12 +2702,16 @@ function observeRecoveryPlayback(media, signal, recovered) {
 	const playing = () => {
 		playingSeen = true;
 		baseline = Number.isFinite(media.currentTime) ? media.currentTime : null;
+		frameBaseline = decodedVideoFrames(media);
 	};
 	const seeking = () => {
 		baseline = null;
 	};
 	const seeked = () => {
-		if (playingSeen && !media.paused && !media.seeking && media.readyState >= 2) baseline = Number.isFinite(media.currentTime) ? media.currentTime : null;
+		if (playingSeen && !media.paused && !media.seeking && media.readyState >= 2) {
+			baseline = Number.isFinite(media.currentTime) ? media.currentTime : null;
+			frameBaseline = decodedVideoFrames(media);
+		}
 	};
 	const resets = [
 		"pause",
@@ -2430,6 +2732,8 @@ function observeRecoveryPlayback(media, signal, recovered) {
 	const progress = () => {
 		if (disposed || baseline === null || media.paused || media.seeking || media.readyState < 2) return;
 		if (!Number.isFinite(media.currentTime) || media.currentTime <= baseline) return;
+		if (options.beyond !== void 0 && media.currentTime <= options.beyond) return;
+		if (frameBaseline !== null && (decodedVideoFrames(media) ?? 0) <= frameBaseline) return;
 		dispose();
 		recovered();
 	};
@@ -2442,6 +2746,12 @@ function observeRecoveryPlayback(media, signal, recovered) {
 	signal.addEventListener("abort", dispose, { once: true });
 	return dispose;
 }
+/** 有视频画面时的已解码帧累计数；纯音频或浏览器不提供计数时为 `null`（不以帧为证据） */
+function decodedVideoFrames(media) {
+	if (!(media instanceof HTMLVideoElement) || media.videoWidth <= 0) return null;
+	const quality = media.getVideoPlaybackQuality?.();
+	return quality && Number.isFinite(quality.totalVideoFrames) ? quality.totalVideoFrames : null;
+}
 /** 媒体修复会重新挂载 MSE；先订阅 canplay，避免对尚未挂载的元素提前 play。 */
 function waitForMediaRepair(media, signal, repair) {
 	if (signal.aborted) return Promise.resolve(false);
@@ -2486,6 +2796,19 @@ function describePlaybackRuntime(env) {
 //#endregion
 //#region src/source-normalize.ts
 /**
+* 把 URL 回显进错误消息前只保留 origin+pathname —— 这两处抛出在 createPlayer 里同步
+* 发生,不经 `makePlayerError`,原样回显会把签名 URL 的完整 query(含 token)暴露给宿主。
+* 解析失败(如相对路径拼接错误)时回显占位符,而不是原样吐出未知格式的字符串。
+*/
+function redactUrlForMessage(url) {
+	try {
+		const parsed = new URL(url);
+		return `${parsed.origin}${parsed.pathname}`;
+	} catch {
+		return "(无法解析的 URL)";
+	}
+}
+/**
 * 从 URL 推断媒体类型。
 *
 * 先剥掉 query 和 hash 再看扩展名 —— 鉴权只能走签名 URL(坑 #26),而签名 URL 长这样
@@ -2519,7 +2842,7 @@ function isMultiSource(source) {
 function normalizeSource(source) {
 	if (typeof source === "string") {
 		const type = inferTypeFromUrl(source);
-		if (!type) throw new Error(`无法从 URL 推断媒体类型:${source}。请改用对象形式并显式传 type,如 { url, type: 'hls' }`);
+		if (!type) throw new Error(`无法从 URL 推断媒体类型:${redactUrlForMessage(source)}。请改用对象形式并显式传 type,如 { url, type: 'hls' }`);
 		return {
 			candidates: [{
 				url: source,
@@ -2540,7 +2863,7 @@ function normalizeSource(source) {
 	};
 	const explicit = source.type;
 	const type = explicit && explicit !== "auto" ? explicit : inferTypeFromUrl(source.url);
-	if (!type) throw new Error(`无法从 URL 推断媒体类型:${source.url}。请显式传 type,如 { url, type: 'hls' }`);
+	if (!type) throw new Error(`无法从 URL 推断媒体类型:${redactUrlForMessage(source.url)}。请显式传 type,如 { url, type: 'hls' }`);
 	return {
 		candidates: [{
 			url: source.url,
@@ -2580,9 +2903,8 @@ const CONTROL_MESSAGE_KEYS = {
 /**
 * 把契约的 `locale.messages` 里那一族 `controls.*` 翻成 xgplayer 的实例级 i18n 条目。
 *
-* **返回 `null` 表示「一条都没有」,调用方应当整个省略 `i18n` 键** ——
-* 不是传空数组:省略时 xgplayer 走 `this.config.i18n || []`,行为与接线前逐字节相同,
-* 而传 `[]` 虽然等价却让 config 的形状变了,e2e / 快照会无谓地漂。
+* 每次返回当前实例语言的完整控件快照。第三语言复用内部英文槽位；只注入部分 key
+* 会在切回另一种语言时留下上一种语言的文案。
 *
 * `lang` 由调用方传入(`toXgLang` 收敛后的 `zh-cn` / `en`)——
 * **注入的语义是「覆盖当前那一档的文案」,不是「注册一个新语种」**:
@@ -2593,7 +2915,7 @@ const CONTROL_MESSAGE_KEYS = {
 *
 * @example
 * toXgI18nEntries({ locale: 'vi-VN', messages: { 'vi-VN': { 'controls.play': 'Phát' } } }, 'en')
-* // → [{ LANG: 'en', TEXT: { PLAY_TIPS: 'Phát' } }]
+* // → [{ LANG: 'en', TEXT: { PLAY_TIPS: 'Phát', ...其余键逐项回退中文 } }]
 */
 function toXgI18nEntries(locale, lang) {
 	const { messages } = resolveLocaleMessages(locale);
@@ -2602,10 +2924,10 @@ function toXgI18nEntries(locale, lang) {
 		const value = messages[contractKey];
 		if (typeof value === "string" && value !== "") text[xgKey] = value;
 	}
-	return Object.keys(text).length > 0 ? [{
+	return [{
 		LANG: lang,
 		TEXT: text
-	}] : null;
+	}];
 }
 //#endregion
 //#region src/create-player.ts
@@ -2774,29 +3096,28 @@ function createPlayer(options) {
 	const normalized = normalizeSource(config.source);
 	let sessionId = newSessionId();
 	let deliverySequence = 0;
-	const makeDelivered = (event) => {
+	const attachDelivery = (event) => {
 		deliverySequence += 1;
 		return {
-			event,
-			producerSessionId: sessionId,
-			deliveryId: `${sessionId}:${deliverySequence}`,
-			occurredAtMs: Date.now(),
-			sequence: deliverySequence
+			...event,
+			delivery: {
+				producerSessionId: sessionId,
+				deliveryId: `${sessionId}:${deliverySequence}`,
+				occurredAtMs: Date.now(),
+				sequence: deliverySequence
+			}
 		};
 	};
-	const notify = (delivered) => {
-		try {
-			options.onEvent?.(delivered.event);
-		} catch {}
+	const notify = (event) => {
 		try {
-			options.onDeliveredEvent?.(delivered);
+			options.onEvent?.(event);
 		} catch {}
 	};
 	let routed;
 	try {
 		routed = routeSource(normalized, env);
 	} catch (error) {
-		if (error instanceof SentinelError && error.playerError.code === "E_MEDIA_NOT_SUPPORTED") notify(makeDelivered({
+		if (error instanceof SentinelError && error.playerError.code === "E_MEDIA_NOT_SUPPORTED") notify(attachDelivery({
 			event: "sourceroute",
 			payload: unsupportedRoutePayload(sessionId, normalized, env)
 		}));
@@ -2812,7 +3133,7 @@ function createPlayer(options) {
 	};
 	const emit = (event) => {
 		if (destroyed) return;
-		const delivered = makeDelivered(event);
+		const delivered = attachDelivery(event);
 		if (!eventStreamReady) {
 			deferredEvents.push(delivered);
 			return;
@@ -2890,6 +3211,7 @@ function createPlayer(options) {
 		options.el.ownerDocument.addEventListener("keydown", onPageEscape);
 	}
 	playerRef = player;
+	const lastFrame = createLastFramePlaceholder(() => player.video instanceof HTMLMediaElement ? player.video : null);
 	let desiredPlayback = config.autoplay ?? false;
 	let recoveryCleanup = null;
 	const stopRecoveryLoad = () => {
@@ -2903,10 +3225,29 @@ function createPlayer(options) {
 			}
 		}
 	};
+	/**
+	* 当前是否真的做得了媒体修复：只有 hls.js 内核挂载了插件时才有 recoverMediaError。
+	* 返回可调用的修复函数，`null` 表示这一步只能整条重拉（#111）。
+	*/
+	const hlsMediaRepair = () => {
+		if (routed.kernel !== "hls.js") return null;
+		const plugin = player.getPlugin("HlsJsPlugin");
+		return plugin?.recoverMediaError ? () => plugin.recoverMediaError() : null;
+	};
+	let recoveryResume = null;
 	recovery = new PlaybackRecovery(sessionId, async (token, signal) => {
 		recoveryCleanup?.();
 		const media = player.video;
 		if (!(media instanceof HTMLMediaElement)) throw new Error("Recovery requires a media element");
+		lastFrame.capture();
+		if (recoveryResume?.episode !== token.episode) {
+			const position = media.currentTime;
+			recoveryResume = {
+				episode: token.episode,
+				position: !normalized.live && Number.isFinite(position) && position > 0 ? position : 0
+			};
+		}
+		const resumeAt = recoveryResume.position;
 		const cleanup = () => {
 			unobserve();
 			signal.removeEventListener("abort", abort);
@@ -2920,14 +3261,21 @@ function createPlayer(options) {
 		const unobserve = observeRecoveryPlayback(media, signal, () => {
 			cleanup();
 			recovery?.recovered(token);
-		});
+		}, resumeAt > 0 ? { beyond: resumeAt } : {});
 		recoveryCleanup = cleanup;
 		signal.addEventListener("abort", abort, { once: true });
-		const repaired = token.strategy === "media_recovery" && token.attempt === 1 && routed.kernel === "hls.js" && await waitForMediaRepair(media, signal, () => player.getPlugin("HlsJsPlugin")?.recoverMediaError() ?? false);
+		const repaired = token.strategy === "media_recovery" && await waitForMediaRepair(media, signal, () => hlsMediaRepair()?.() ?? false);
 		if (signal.aborted || destroyed) return;
 		if (!repaired) await player.switchURL(currentSrcUrl);
+		if (!signal.aborted && !destroyed && media.currentTime < resumeAt) media.currentTime = resumeAt;
 		if (!signal.aborted && !destroyed && recovery?.playingIntent) await player.play();
-	}, emit, (state) => playableState()?.setRecovery(state));
+	}, emit, (state) => {
+		if (!state.recovering) lastFrame.release();
+		playableState()?.setRecovery(state);
+	}, {
+		failsAttempt: (error) => !normalized.live && error.category === "media",
+		resolveStrategy: (strategy, attempt) => strategy === "media_recovery" && !(attempt === 1 && hlsMediaRepair()) ? "reconnect" : strategy
+	});
 	recovery.setPlayingIntent(desiredPlayback);
 	const listeners = [];
 	const listen = (name, handler) => {
@@ -2936,6 +3284,7 @@ function createPlayer(options) {
 	};
 	const hlsCleanups = [];
 	const disposers = [];
+	disposers.push(() => lastFrame.release());
 	disposers.push(observeMediaPlayRejection(player));
 	let flvAudioHealth = null;
 	let flvPlaybackActive = false;
@@ -2962,18 +3311,18 @@ function createPlayer(options) {
 	*
 	* ```
 	* player.switchURL(url)
-	*   → xgplayer/es/player.js        this.src = _src
-	*   → xgplayer/es/mediaProxy.js    emit(URL_CHANGE, url)
-	*   → xgplayer-hls.js/es/index.js  on(URL_CHANGE) → register(url)
-	*   → xgplayer-hls.js/es/index.js  this.hls.destroy(); this.hls = new Hls(...)
+	*   → xgplayer/es/player.js             this.src = _src
+	*   → xgplayer/es/mediaProxy.js         emit(URL_CHANGE, url)
+	*   → OwnedHlsPlugin.on(URL_CHANGE)     register(url)
+	*   → HlsAdapter.stop() + start(url)    换成新的 hls.js 实例
 	* ```
 	*
 	* 布尔标志一旦置起就再也不复位,于是新实例上一条监听都没有 —— `qualitychange`
 	* 不再发、`currentQualityLevel` 永远停在 `null`(而契约说 `null` 的含义是
 	* 「单码率源或档位未知」,这里会把多码率源持续误报)。
 	*
-	* **触发入口不只是 `load()`**:`ReconnectPlugin` 的每一次重试和 `VisibilityPlugin`
-	* 的 iOS 后台切回自愈都走 `reloadStream()` → `switchURL`。所以复位点**不能只放在
+	* **触发入口不只是 `load()`**:统一恢复的重拉动作和 `VisibilityPlugin`
+	* 的 iOS 后台切回意图都可能走 `reloadStream()` → `switchURL`。所以复位点**不能只放在
 	* `load()` 里** —— 判据必须是「实例还是不是同一个」,而不是「有没有换过源」。
 	*
 	* `reload-stream.ts` 的注释早就写着 `switchURL` 会「重新建 hls 实例并 attach」,
@@ -3020,7 +3369,7 @@ function createPlayer(options) {
 	emitContextChange();
 	for (const delivered of deferredEvents) {
 		notify(delivered);
-		reportRecoveryFault(delivered.event, delivered.producerSessionId);
+		reportRecoveryFault(delivered, delivered.delivery?.producerSessionId ?? sessionId);
 	}
 	deferredEvents.length = 0;
 	const attachQualityListener = () => {
@@ -3067,6 +3416,8 @@ function createPlayer(options) {
 	};
 	disposers.push(() => naturalProof?.abort());
 	let sawFirstFrame = false;
+	let firstFrameDataReady = false;
+	let firstFrameStartedAt = performance.now();
 	let sawPlaybackStart = false;
 	let sawPlaying = false;
 	let sawStartupWaiting = false;
@@ -3097,6 +3448,8 @@ function createPlayer(options) {
 	armStartupDeadline();
 	const resetPrematureVodEndState = () => {
 		sawFirstFrame = false;
+		firstFrameDataReady = false;
+		firstFrameStartedAt = performance.now();
 		sawPlaybackStart = false;
 		sawPlaying = false;
 		sawStartupWaiting = false;
@@ -3105,6 +3458,15 @@ function createPlayer(options) {
 		seeking = false;
 		prematureVodEnd = null;
 	};
+	const markFirstFrame = (fvt) => {
+		if (sawFirstFrame) return;
+		sawFirstFrame = true;
+		clearStartupDeadline();
+		emit({
+			event: "firstframe",
+			payload: { fvt }
+		});
+	};
 	const observePlaybackPosition = () => {
 		const position = safeNumber(player.currentTime);
 		const duration = safeNumber(player.duration);
@@ -3171,13 +3533,15 @@ function createPlayer(options) {
 			desiredPlayback = false;
 			clearStartupDeadline();
 			recovery?.endPlayback();
-		}
+		} else if (!normalized.live && recovery?.attemptInFlight) recovery.endPlayback();
+		else if (normalized.live) recovery?.requestRecovery("ended");
 		emit({
 			event: "ended",
 			payload: {}
 		});
 	});
 	listen("loadeddata", () => {
+		firstFrameDataReady = true;
 		attachQualityListener();
 		emit({
 			event: "ready",
@@ -3191,6 +3555,8 @@ function createPlayer(options) {
 	});
 	listen("timeupdate", () => {
 		observePlaybackPosition();
+		const media = player.video;
+		if (!sawFirstFrame && firstFrameDataReady && desiredPlayback && media instanceof HTMLMediaElement && !media.paused && media.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) markFirstFrame(Math.max(0, performance.now() - firstFrameStartedAt));
 		emit({
 			event: "timeupdate",
 			payload: {
@@ -3233,12 +3599,7 @@ function createPlayer(options) {
 		if (log.eventType !== "firstFrame") return;
 		const fvt = log.fvt;
 		if (typeof fvt !== "number" || !Number.isFinite(fvt)) return;
-		sawFirstFrame = true;
-		clearStartupDeadline();
-		emit({
-			event: "firstframe",
-			payload: { fvt }
-		});
+		markFirstFrame(fvt);
 	});
 	listen("fps_stuck", (raw) => {
 		const payload = normalizeFrameFreeze(raw);
@@ -3251,14 +3612,17 @@ function createPlayer(options) {
 	listen("user_action", (raw) => {
 		const payload = normalizeUserAction(raw);
 		if (payload === null) return;
-		if (payload.action === "switch_play_pause" && typeof payload.to === "boolean") setPlayingIntent(!payload.to);
+		if (payload.action === "switch_play_pause") {
+			const video = player.video;
+			setPlayingIntent(typeof payload.to === "boolean" ? !payload.to : video instanceof HTMLMediaElement && video.paused);
+		}
 		emit({
 			event: "useraction",
 			payload
 		});
 	});
 	listen("error", (err) => {
-		const mapped = mapXgplayerError(err);
+		const mapped = mapXgplayerError(err, { live: normalized.live });
 		if ((flvJustReported || hlsJustReported) && mapped.code === "E_UNKNOWN") return;
 		sawNativeError = true;
 		emit({
@@ -3306,10 +3670,8 @@ function createPlayer(options) {
 	/**
 	* HLS 侧的同一道闸(#724 · A-8)。理由与 `flvJustReported` **同构**,只是上游形状不同。
 	*
-	* `xgplayer-hls.js` 对每条 hls 错误先 `emit('HLS_ERROR', …)`,随后
-	* `if (data.fatal) switch (data.type)` —— NETWORK / MEDIA 两支私吞,
-	* **`default:` 支再 `emit('error', data)`**(即 `muxError` / `keySystemError` /
-	* `otherError` 这三类 fatal)。
+	* SDK 自有 `OwnedHlsPlugin` 对每条 hls.js 诊断先发结构化 `HLS_ERROR`；xgplayer 的
+	* 通用错误路径在部分 fatal 形态下仍可能同步补一条信息更少的 `error`。
 	*
 	* 于是同一次故障走两条路:`HLS_ERROR` 那条经 `mapHlsKernelError` 精确映射(好的),
 	* `error` 那条经 `mapXgplayerError` —— 而它读 `errorType`、查的是 xgplayer 自己的词表
@@ -3486,10 +3848,9 @@ function createPlayer(options) {
 	/**
 	* 内核诊断 → 契约 error 流(#402)。
 	*
-	* `xgplayer-hls.js` 的包装层把 **NETWORK / MEDIA 两类 fatal 错误私吞了**
-	*(`startLoad()` 重试 / `recoverMediaError()`,都不 `emit('error')`),
-	* 而 `status === 404` 时连重试都没有。实测:manifest 404 → hls.js 报
-	* `manifestLoadError` **fatal=true**,消费方拿到的契约 `error` **0 条**。
+	* SDK 自有 `OwnedHlsPlugin` 会把 hls.js 的诊断清洗为 `HLS_ERROR`；这里负责尽早接住、
+	* 映射为契约错误或送入非 fatal 聚合。不能等 `loadeddata` 后再挂监听，因为 manifest
+	* 加载失败时该事件永远不会发生。
 	*
 	* ⚠️ **必须挂在 player 上,不能去够 hls 实例。** 三条都是实测出来的:
 	* ① `attachQualityListener` 那个挂载点用不了 —— 它在 `loadeddata` 里挂,
@@ -3499,9 +3860,8 @@ function createPlayer(options) {
 	*    `manifestLoadError fatal=true`,差别只是 50ms 轮询与 `loadSource` 的先后。
 	*    **一个会随机漏报的接线比没有更坏**,因为它看起来在工作。
 	*
-	* `HLS_ERROR` 是 player 级事件、包装层对每条 hls 错误都发,三条一次绕开。
-	*
-	* **只做可见性,不改恢复行为**:不触发重连、不干预 `startLoad` / `recoverMediaError`。
+	* `HLS_ERROR` 是 player 级事件，OwnedHlsPlugin 对每条 hls.js 错误都发；映射层本身只
+	* 提供可见性，恢复动作由 PlaybackRecovery / RecoveryController 决定。
 	*/
 	/**
 	* 非致命诊断的**聚合**出口(#391 · ADR-062)。
@@ -3515,17 +3875,21 @@ function createPlayer(options) {
 	* 非 fatal 走这里,同一条诊断只进一边。改动时别让 fatal 也 `record` 进来 ——
 	* 那会让 `count` 把已经报过 `error` 的东西再数一遍。
 	*/
-	const kernelHealth = createKernelHealthAggregator({ onReport: (payload) => emit({
-		event: "kernelhealth",
-		payload
-	}) });
+	const kernelHealth = createKernelHealthAggregator({ onReport: (payload) => {
+		if (payload.degraded) recovery?.noteKernelHealth(payload.reason);
+		emit({
+			event: "kernelhealth",
+			payload
+		});
+	} });
 	disposers.push(() => kernelHealth.dispose());
 	listen("HLS_ERROR", (...args) => {
 		const payload = args.at(-1);
 		if (typeof payload !== "object" || payload === null) return;
 		const hls = payload;
-		const mapped = mapHlsKernelError(hls);
+		const mapped = mapHlsKernelError(hls, { live: normalized.live });
 		if (mapped === void 0) {
+			if (hls.httpStatus === 401 || hls.httpStatus === 403) recovery?.noteKernelHealth("auth");
 			kernelHealth.record(hlsHealthReason(hls), `${hls.errorType ?? "未知"} / ${hls.errorDetails ?? "未知"}`);
 			return;
 		}
@@ -3614,9 +3978,9 @@ function createPlayer(options) {
 		setLocale(locale) {
 			if (destroyed) return;
 			const lang = toXgLang(locale);
-			if (!lang) return;
 			extendInstanceI18n(player, locale, lang);
 			player.lang = lang;
+			syncXgplayerTimeLocale(player);
 		},
 		pushDanmaku(item) {
 			if (destroyed) return;
@@ -3744,24 +4108,14 @@ function createPlayer(options) {
 * 覆盖层是越南语、控件是英文,两半对不上。接了这条线,`locale` 才真正统辖两者。
 *
 * 注意作用范围:这里只管 **xgplayer 自带控件**的文案;player-ui 的 4 个覆盖层文案
-* 走 `locale.messages` 注入(SDK 不内置翻译),两者互不干扰。
+* 由消费面解析官方资源及 `locale.messages` 后注入，两者使用同一有效语言。
 *
-* **未传 locale 时返回 undefined,调用方须整个省略 `lang` 键** —— 不能兜底成 `'en'`。
-* 省略时 xgplayer 走自己的 `getLang()`:
-* `document.documentElement.getAttribute('lang') || navigator.language || 'zh-cn'`
-* (`utils/util.js:815`)。**注意 `<html lang>` 排在浏览器语言前面** —— 宿主页声明了 lang
-* 就以它为准,没声明才跟浏览器走。兜底成 `'en'` 会把这整套既有行为一刀切掉。
-* 这条线只该在消费方明确表态时才接管。
-*
-* ⚠️ 由此带来的一个实测结论(#190 step 3):`apps/embed-app/index.html` 写死 `<html lang="en">`,
-* 所以**静态 iframe 那条路不传 locale 时控件恒为英文**,读者的浏览器语言完全不参与。
-* 那条路现在有 `?locale=` 了(`config-from-url.ts`),它是那一页上唯一能改控件语言的东西;
-* e2e 在 `locale-static-iframe.spec.ts` 里把这两半都钉住了。
+* 未传 locale 时固定选 `zh-cn`，不再跟随宿主页面或浏览器语言(ADR-120)。
 */
 function toXgLang(locale) {
 	const tag = typeof locale === "string" ? locale : locale?.locale;
-	if (!tag) return void 0;
-	return tag.toLowerCase().startsWith("zh") ? "zh-cn" : "en";
+	if (!tag) return "zh-cn";
+	return /^(zh|zh-cn)$/i.test(tag.replaceAll("_", "-")) ? "zh-cn" : "en";
 }
 /**
 * 把 `controls.*` extend 进**这个播放器实例**的 i18n 表(运行时切语言用,ADR-035)。
@@ -3773,11 +4127,28 @@ function toXgLang(locale) {
 */
 function extendInstanceI18n(player, locale, lang) {
 	const entries = toXgI18nEntries(locale, lang);
-	if (!entries) return;
 	const instanceI18n = player.__i18n;
 	if (!instanceI18n) return;
 	I18N.extend(entries, instanceI18n);
 }
+/**
+* 补齐 xgplayer 3.0.26 Time 控件的运行时语言切换。
+*
+* 该控件首次渲染 `.time-live-tag` 时直接写入 `i18n.LIVE_TIP`，却没有像其他
+* 官方控件一样附上 `lang-key`。因此 `player.lang = ...` 会更新播放、全屏等提示，
+* 却把直播标签留在旧语言。这里只在当前播放器的 Time 插件根节点内补齐文案和语言键；
+* 无该插件、DOM 形状变化或翻译缺失时都安全降级，不写 xgplayer 全局 i18n。
+*/
+function syncXgplayerTimeLocale(player) {
+	const playerWithI18n = player;
+	const liveTag = playerWithI18n.getPlugin?.("time")?.root?.querySelector?.(".time-live-tag");
+	if (!liveTag) return;
+	const liveText = playerWithI18n.i18n?.LIVE_TIP;
+	if (typeof liveText !== "string" || liveText === "") return;
+	liveTag.textContent = liveText;
+	const langKey = playerWithI18n.i18nKeys?.LIVE_TIP;
+	if (typeof langKey === "string" && langKey !== "") liveTag.setAttribute("lang-key", langKey);
+}
 function buildXgplayerConfig(options, routed, normalized, emit, env, playableState, recovery) {
 	const { config } = options;
 	const live = normalized.live;
@@ -3810,12 +4181,10 @@ function buildXgplayerConfig(options, routed, normalized, emit, env, playableSta
 			...config.controlVisibility?.volume === false ? ["volume"] : [],
 			...config.controlVisibility?.time === false ? ["time"] : []
 		],
-		...toXgLang(config.locale) ? { lang: toXgLang(config.locale) } : {},
+		lang: toXgLang(config.locale),
 		...(() => {
 			const lang = toXgLang(config.locale);
-			if (!lang) return {};
-			const entries = toXgI18nEntries(config.locale, lang);
-			return entries ? { i18n: entries } : {};
+			return { i18n: toXgI18nEntries(config.locale, lang) };
 		})(),
 		plugins,
 		...subtitleList.length > 0 ? { texttrack: {
@@ -3859,7 +4228,9 @@ function buildXgplayerConfig(options, routed, normalized, emit, env, playableSta
 					payload
 				});
 				playableState()?.setStalled(payload.phase === "start");
-				if (payload.phase === "start" && payload.kind === "playback") recovery()?.requestRecovery("stall");
+			},
+			onSustainedStall: () => {
+				recovery()?.requestRecovery("stall");
 			},
 			onBufferHealth: (payload) => {
 				emit({
@@ -3892,7 +4263,7 @@ function buildXgplayerConfig(options, routed, normalized, emit, env, playableSta
 	};
 }
 /**
-* 取 xgplayer-hls.js 插件持有的 hls.js 实例。非 HLS 源(MP4 走原生、FLV 走 flv.js)
+* 取 SDK 自有 OwnedHlsPlugin 持有的 hls.js 实例。非 HLS 源(MP4 走原生、FLV 走 flv.js)
 * 拿不到,返回 undefined —— 上层据此把多码率相关能力降级成 no-op / 空档位。
 */
 function getHlsInstance(player) {