dsh-mpkg-wallpaper 3.9.0 → 3.10.0

package/README.en.md

@@ -6,7 +6,7 @@
 
 Adds background wallpapers to the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web UI (`dsh web`): **Wallpaper Engine `.mpkg` parsing, Steam Workshop folders, video/web/image wallpapers, time-of-day switching for Time Variation wallpapers, a full-screen blur system, theme colours and glass surfaces, a local wallpaper library, scheduled rotation, a Now playing widget and one-click update**. Almost every appearance detail is adjustable.
 
-> Version scope: this document describes the implementation shipped as **`3.9.0`** in `package.json`. The publish surface is **15 files** (`lib/` runtime files + `package.json`, `icon.svg`, `cordis.patch.yml`, `README.md`, `README.en.md`, `THIRD-PARTY.md`, `LICENSE`; measured with `npm pack --dry-run`: 15 files / 2,088,240 B unpacked); `lib/liquid-glass/**`, `lib/liquid-glass-bundle.js`, `dist/`, `tools/` and `docs/` never enter the npm package (`package.json:8-21`). Defaults that changed: **`npNowPlaying` off → on** (since 3.8.0) and **`powPauseHidden` off → on** (since 3.9.0, migrating only profiles that never set it; see [What changed in this version](#what-changed-in-this-version)).
+> Version scope: this document describes the implementation shipped as **`3.10.0`** in `package.json`. The publish surface is **15 files** (`lib/` runtime files + `package.json`, `icon.svg`, `cordis.patch.yml`, `README.md`, `README.en.md`, `THIRD-PARTY.md`, `LICENSE`; measured with `npm pack --dry-run`: 15 files / 2,088,240 B unpacked); `lib/liquid-glass/**`, `lib/liquid-glass-bundle.js`, `dist/`, `tools/` and `docs/` never enter the npm package (`package.json:8-21`). Defaults that changed: **`npNowPlaying` off → on** (since 3.8.0) and **`powPauseHidden` off → on** (since 3.9.0, migrating only profiles that never set it; see [What changed in this version](#what-changed-in-this-version)).
 
 ---
 
@@ -560,7 +560,7 @@ This section is a file-by-file map of the repository: what enters the npm packag
 
 ```text
 dsh-mpkg-wallpaper/
-├── package.json      # version 3.9.0; dsh.bundle + dsh.client declarations; files allow-list = publish surface (15 files)
+├── package.json      # version 3.10.0; dsh.bundle + dsh.client declarations; files allow-list = publish surface (15 files)
 ├── cordis.patch.yml  # install declaration used by dsh plugin add
 ├── LICENSE           # MIT
 ├── THIRD-PARTY.md    # third-party provenance / clean-room records / licence attribution (shipped)
@@ -610,7 +610,7 @@ The 12 steps of `tools/check.sh`: ① syntax ② panel smoke + P-66 + folder pic
 
 ## What changed in this version
 
-Current version = **3.9.0** in `package.json` (this release line: 3.8.0 → 3.8.1 → 3.8.2 → **3.9.0**). Release prerequisites, commands and rollback live in [`docs/RELEASE.md`](docs/RELEASE.md); this round's change list is in [`docs/RELEASE-READY-3.8.0.md`](docs/RELEASE-READY-3.8.0.md); the root causes and on-device readings for Now playing / wallpaper sound are in [`docs/NOW-PLAYING-DSH.md`](docs/NOW-PLAYING-DSH.md) §7.7.
+Current version = **3.10.0** in `package.json` (this release line: 3.8.0 → 3.8.1 → 3.8.2 → 3.9.0 → 3.9.1 → **3.10.0**). Release prerequisites, commands and rollback live in [`docs/RELEASE.md`](docs/RELEASE.md); this round's change list is in [`docs/RELEASE-READY-3.8.0.md`](docs/RELEASE-READY-3.8.0.md); the root causes and on-device readings for Now playing / wallpaper sound are in [`docs/NOW-PLAYING-DSH.md`](docs/NOW-PLAYING-DSH.md) §7.7.
 
 - **Now playing is on by default and yields its slot**: the `npNowPlaying` setting is **on by default** (`DEFAULT_NP_NOW_PLAYING` in `lib/client.js`), still in the *Wallpaper* tab directly under the existing `mute` toggle (`toggleRow(t("npNowPlaying"), …)` in `lib/client.js`). Turning it off returns to zero injection (mechanism and criteria in [Now playing and wallpaper sound](#now-playing-and-wallpaper-sound)). Being on by default requires **yielding**: when another plugin has already injected an element into the same host slot we do not mount (or we retract) and leave a queryable state `data-mpw-np-yield` (`occupantOf()` in `lib/now-playing.js`; judged both before and after mounting, and it comes back once the occupant leaves). The component itself is a **line-by-line port of Bencho's "Now playing" (MIT)** with the upstream comments kept verbatim (attribution in `THIRD-PARTY.md` §6); pure math and component are split into `lib/now-playing-math.js` / `lib/now-playing.js` and **inlined byte-for-byte** into the `MPW-NP-GEN-START/END` region of `lib/client.js` by `tools/build-now-playing.mjs`, guarded by two independent drift gates. Mounting and collapse criteria: see [Now playing and wallpaper sound](#now-playing-and-wallpaper-sound).
 - **Wallpaper sound is actually wired up**: the data source only accepts the media element that is **really playing right now** (the hidden shell `#mpw-bgVideo` exists in the DOM under **every** wallpaper type, and the old implementation treated the first selector match as "the current media") ⇒ a video wallpaper's play/pause/mute land on the real element (the **`mute` switch now really reaches the element — unmuting really produces sound**; the old code hard-coded `video.muted = true` and never assigned it from the setting again); audio files that **really exist** in the wallpaper folder play through our own `<audio>` (the scope accepts `mpkgKey="custom|<folder>"`; the old code only accepted `folderName`, so a web wallpaper in a custom folder always built a library route and got a 404) ⇒ **previous/next follow the track-list order and wrap around**, instead of "restart"; for a web wallpaper's in-frame sound only **mute** is a real channel (`canPlay=false` is reported honestly — we do not pretend we can pause in-frame WebAudio); while our player is playing, the frame is force-muted so the same track cannot play twice.

package/README.md

@@ -6,7 +6,7 @@
 
 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web 界面（`dsh web`）添加背景壁纸的插件：**Wallpaper Engine `.mpkg` 解析、Steam 创意工坊目录、视频/网页/图片壁纸、时间变化壁纸的多时段切换、整屏虚化体系、主题色与玻璃外观、本地壁纸库、定时轮换、Now playing 控件、一键更新**。外观细节几乎全部可调。
 
-> 版本口径：本文件描述的是 `package.json` 里 **`3.9.0`** 这一版实现。发布面共 **15 个文件**（`lib/` 8 个运行时文件 + `package.json`、`icon.svg`、`cordis.patch.yml`、`README.md`、`README.en.md`、`THIRD-PARTY.md`、`LICENSE`；`npm pack --dry-run` 实测 15 文件 / unpacked 2 088 240 B）；`lib/liquid-glass/**`、`lib/liquid-glass-bundle.js`、`dist/`、`tools/`、`docs/` 都不进 npm 包（`package.json:8-21`）。本轮的默认档变化：**`npNowPlaying` 关 → 开**（3.8.0 起）与 **`powPauseHidden` 关 → 开**（3.9.0 起，只迁移"从没设过"的存量档；详见[这一版新增/变更](#这一版新增变更)）。
+> 版本口径：本文件描述的是 `package.json` 里 **`3.10.0`** 这一版实现。发布面共 **15 个文件**（`lib/` 8 个运行时文件 + `package.json`、`icon.svg`、`cordis.patch.yml`、`README.md`、`README.en.md`、`THIRD-PARTY.md`、`LICENSE`；`npm pack --dry-run` 实测 15 文件 / unpacked 2 088 240 B）；`lib/liquid-glass/**`、`lib/liquid-glass-bundle.js`、`dist/`、`tools/`、`docs/` 都不进 npm 包（`package.json:8-21`）。本轮的默认档变化：**`npNowPlaying` 关 → 开**（3.8.0 起）与 **`powPauseHidden` 关 → 开**（3.9.0 起，只迁移"从没设过"的存量档；详见[这一版新增/变更](#这一版新增变更)）。
 
 ---
 
@@ -560,7 +560,7 @@ node tools/build-bundle.mjs
 
 ```text
 dsh-mpkg-wallpaper/
-├── package.json      # 版本 3.9.0；dsh.bundle + dsh.client 声明；files 白名单 = 发布面（15 文件）
+├── package.json      # 版本 3.10.0；dsh.bundle + dsh.client 声明；files 白名单 = 发布面（15 文件）
 ├── cordis.patch.yml  # 插件安装声明（dsh plugin add 使用）
 ├── LICENSE           # MIT
 ├── THIRD-PARTY.md    # 第三方来历/洁净室记录与许可归属（随包发布）
@@ -610,7 +610,7 @@ node tools/style-scope-guard.mjs   # 判据是末行「… OK / … ALLOWLISTED
 
 ## 这一版新增/变更
 
-当前版本 = `package.json` 的 **3.9.0**（本轮发布线 3.8.0 → 3.8.1 → 3.8.2 → **3.9.0**）。发布前置/命令/回滚见 [`docs/RELEASE.md`](docs/RELEASE.md)，本轮改动清单见 [`docs/RELEASE-READY-3.8.0.md`](docs/RELEASE-READY-3.8.0.md)，Now playing / 壁纸声音的根因与真机读数见 [`docs/NOW-PLAYING-DSH.md`](docs/NOW-PLAYING-DSH.md) §7.7。
+当前版本 = `package.json` 的 **3.10.0**（本轮发布线 3.8.0 → 3.8.1 → 3.8.2 → 3.9.0 → 3.9.1 → **3.10.0**）。发布前置/命令/回滚见 [`docs/RELEASE.md`](docs/RELEASE.md)，本轮改动清单见 [`docs/RELEASE-READY-3.8.0.md`](docs/RELEASE-READY-3.8.0.md)，Now playing / 壁纸声音的根因与真机读数见 [`docs/NOW-PLAYING-DSH.md`](docs/NOW-PLAYING-DSH.md) §7.7。
 
 - **Now playing 默认挂载 + 会让位**：设置项 `npNowPlaying` **默认开**（`lib/client.js` 的 `DEFAULT_NP_NOW_PLAYING`），仍在「壁纸设置」tab、紧挨既有 `mute` 下方（`lib/client.js` 的 `toggleRow(t("npNowPlaying"), …)`）。关掉即回到零注入（机制与判据见 [Now playing 与壁纸声音](#now-playing-与壁纸声音)）。默认开的前提是**礼让**：宿主同一位置已经有别的插件注入的元素时不挂/撤下，并留一个可查询状态 `data-mpw-np-yield`（`lib/now-playing.js` 的 `occupantOf()`；挂载前与挂载后都判，占用者走了再回来）。组件本体是 **Bencho 的 "Now playing"（MIT）逐行移植**（注释原文保留，归属见 `THIRD-PARTY.md` §6）；纯数学与组件拆成 `lib/now-playing-math.js` / `lib/now-playing.js`，由 `tools/build-now-playing.mjs` **逐字节内联**进 `lib/client.js` 的 `MPW-NP-GEN-START/END` 生成区，配两道漂移门禁（生成器自比 + 产物反抠比对）。挂载与收起判据见 [Now playing 与壁纸声音](#now-playing-与壁纸声音)。
 - **壁纸声音真的接线**：数据源只认**当前真的在放**的那个媒体元素（页面里那个隐藏空壳 `#mpw-bgVideo` 在**任何壁纸类型下都在 DOM 里**，旧实现按选择器命中它就当"当前媒体"）⇒ 视频壁纸的播放/暂停/静音落在真实元素上（**`mute` 开关真的落到元素上：关掉静音就真的出声**，旧写法把 `video.muted` 写死 `true`，之后再没有代码按设置赋值）；壁纸目录里**真实存在**的音频文件由我们自己的 `<audio>` 播（作用域认 `mpkgKey="custom|<folder>"`，旧写法只认 `folderName` ⇒ 自定义目录里的 web 壁纸永远拼成 library 路由 404）⇒ **上一首/下一首按清单顺序环形切换**，不再是"回到开头"；web 壁纸帧内那份声音只有**静音**这一条真通道（`canPlay=false`，如实显示，不假装能暂停帧内 WebAudio）；我们放音时帧内被强制静音（防同一首放两遍）。
@@ -633,7 +633,7 @@ node tools/style-scope-guard.mjs   # 判据是末行「… OK / … ALLOWLISTED
   **宿主超限语义**：两个 POST 接收端超限从"先掐连接"改成 **413 + JSON 说明**（旧行为客户端只看到 ECONNRESET）。
   真机读数、根因链与 10 条诚实清单见 [`docs/WALLPAPER-LIFECYCLE.md`](docs/WALLPAPER-LIFECYCLE.md)；发布记录见 [`docs/RELEASE.md`](docs/RELEASE.md)。
 - **3.8.1 / 3.8.2：Now playing 第二次真机批次（NP-4）** —— 起播顺序（旧写法先取消静音再 `play()`，等于一次有声自动播放 ⇒ 被浏览器拒绝且被吞掉）、被浏览器策略停住（muted 起播 resolve 后取消静音，元素被直接停住）、**新增音量电平**（0..100，落到真实元素）与**可拖动进度（seek）**、**新增「播放/暂停同时控制壁纸」开关（`npLinkWallpaper`，默认开 = 与改动前逐字节同行为）**、悬浮态卡片放大、音轨清单的"能不能播"如实分类。可交付口径：**首次用户手势后必定出声**（被策略停住时退回 muted 保画面并记 `window.__mpwNpSoundBlocked`）。详见 [`docs/RELEASE.md`](docs/RELEASE.md) 的 3.8.1/3.8.2 发布记录与 [`docs/NOW-PLAYING-DSH.md`](docs/NOW-PLAYING-DSH.md) §7.8。
-- **仍在同一发布面上的前一轮能力**：网页壁纸渲染 / API 覆盖（帧内存储 facade + 宿主 `/web-store`、主音量、源级 `file:///` 改写、CSP 跳过注入、`/media-audio`）与网页壁纸触控（`op:'touch'` 真 `TouchEvent`）；系统媒体会话的**宿主端适配器** `lib/media-session.js`（MPRIS / SMTC，**已实现、尚未接线**，见下文）。
+- **仍在同一发布面上的前一轮能力**：网页壁纸渲染 / API 覆盖（帧内存储 facade + 宿主 `/web-store`、主音量、源级 `file:///` 改写、CSP 跳过注入、`/media-audio`）与网页壁纸触控（`op:'touch'` 真 `TouchEvent`）；系统媒体会话的**宿主端适配器** `lib/media-session.js`（MPRIS / SMTC）**已接线**：宿主 `GET /media-session`（21 键快照）/`POST /media-control`（六个 op，能力位先判）/`GET /media-art`（`file://` 封面代理），客户端 `npSystemMedia*` 自适应轮询（有系统媒体 2s、本机无会话总线 30s）⇒ 卡片显示**真实系统曲目/封面/进度**，本机如实 `available:false / no-session-bus`（接线判据 `tools/media-session-wiring-test.mjs` 24 断言 + 3 变异）。
 - **门禁与护栏**：CSS 组合矩阵、样式作用域护栏、表面 token 命名空间等价性、开关接线审计、秒级 pre-commit（见[历史台账](#历史台账)与「[判据](#判据与门禁)」）。
 
 ## 历史台账

package/lib/client.js

@@ -7621,6 +7621,21 @@ function sectionSigNow() {
 			let did = "";
 			const trace = () => npOpTrace(op, value, did || "no-target");
 			try {
+				/* ①(MEDIA-1 接线) **系统媒体优先**：卡片现在显示的是系统曲目时，按钮必须控系统播放器
+				   （否则用户按"下一首"，动的是壁纸而不是他耳机里那首歌）。能力位先判：够不着就不发命令。 */
+				if (npSystemMediaActive() && ["play", "pause", "restart", "next", "prev"].includes(op)) {
+					const last = npSysLast || {};
+					const capOk = (op === "next" ? last.canNext !== false : (op === "prev" ? last.canPrev !== false : true));
+					if (capOk) {
+						did = "system:" + op;
+						trace();
+						npSystemControl(op);
+						return true;
+					}
+					did = "system:no-cap:" + op;
+					trace();
+					return false;
+				}
 				if (op === "play" || op === "pause") {
 					const vid = npActiveVideo(s);
 					/* ①(NP-4)② 联动开 ⇒ 壁纸媒体一起动；关 ⇒ **一个字节都不碰壁纸**（画面不受控件影响）。 */
@@ -7706,6 +7721,127 @@ function sectionSigNow() {
 			setTimeout(() => { try { applyNowPlaying(readSection()); } catch {} }, 60);
 		}
 
+		/* ══════════════════════════════════════════════════════════════════════════════════
+		   ①(MEDIA-1 接线 2026-09-20)「系统媒体」补充路径：把宿主读到的**系统正在播放**喂给卡片
+		   ──────────────────────────────────────────────────────────────────────────────────
+		   为什么是**另一条**路径（而不是塞进 `npResolveMedia`）：那个函数是**同步**的、解的是"**壁纸自己的**
+		   媒体/音频轨"（封面来自 preview、标题来自 project.json）。系统媒体（MPRIS/SMTC）是**异步**的外部世界，
+		   两者可以同时存在（壁纸在放自己的 BGM 时，Spotify 也在放）。口径：
+		     · 宿主 `GET /media-session` 回 `available:false`（如本机无会话总线）⇒ **不接管**，卡片继续显示壁纸自己的媒体
+		       —— 这是本机的**正常**结局，不是失败（诚实降级）；
+		     · `available:true` ⇒ 用系统曲目覆盖标题/副标题/封面/时长，进度按 position 走；
+		       `canNext/canPrev/canPlay` 决定卡片按钮的可用性；封面 `file://` 走宿主代理 `/media-art?player=`。
+		   轮询纪律（本机是手机，这条不是可选项）：**≥2000ms**、只在开关打开且页面可见时跑、开关关掉立刻停。 */
+		const NP_SYS_POLL_MS = 2000;          // 有系统媒体时：2s 一次（进度条要跟得上）
+		const NP_SYS_IDLE_MS = 30000;         // **本机常态**（没有会话总线）：30s 一次
+		/* 为什么不是死板的 `setInterval(2000)`：一次 `snapshot()` = 宿主机上**起一个进程**。本机（手机）
+		   没有会话总线 ⇒ 每 2s 起一个必然查不到东西的进程是纯浪费（用户点名过资源纪律）。
+		   所以用**自适应延时**：拿到系统媒体 ⇒ 2s；不可用/失败 ⇒ 30s 慢慢探。 */
+		let npSysTimer = 0, npSysLast = null, npSysFails = 0, npSysProxyWarned = false, npSysDelay = NP_SYS_POLL_MS;
+		function npSystemMediaStop() {
+			try { if (npSysTimer) { clearTimeout(npSysTimer); npSysTimer = 0 } } catch (e) {}
+		}
+		/** 定时器工厂：**有 `unref` 就 unref**（Node/门禁环境）。
+		 *  为什么必须这样：门禁把 client.js 跑在桩 DOM 里，断言跑完后**进程要能自己退出**——
+		 *  一个挂着的 30s 定时器会让事件循环一直有活干 ⇒ 整条门禁"跑完了却不结束"（实测踩到：
+		 *  `now-playing-test` 卡到 600s 超时）。浏览器里没有 `unref`，这一行等于不存在。 */
+		function npSysTimerSet(fn, ms) {
+			let t = null;
+			try { t = setTimeout(fn, ms) } catch (e) { return null }
+			try { if (t && typeof t.unref === "function") t.unref() } catch (e) {}
+			return t;
+		}
+		/** 排下一次探测（单链，不叠定时器；`npSysTimer` 同时是"在跑"的哨兵）。 */
+		function npSystemMediaSchedule(ms) {
+			try {
+				npSystemMediaStop();
+				npSysDelay = Math.max(NP_SYS_POLL_MS, Math.min(NP_SYS_IDLE_MS, Number(ms) || NP_SYS_POLL_MS));
+				npSysTimer = npSysTimerSet(() => { npSysTimer = 0; try { npSystemMediaTick() } catch (e) {} }, npSysDelay);
+			} catch (e) {}
+		}
+		/** 把宿主快照映射到卡片（`kind:'system'` 只是个信息字段：组件侧对 `media.kind` 零分支）。 */
+		function npApplySystemMedia(d) {
+			try {
+				const ctl = npEnsureCtl();
+				if (!ctl || !d || d.available !== true) return false;
+				const cover = d.artUrlKind === 'file'
+					? (HOST_BASE + '/media-art?player=' + encodeURIComponent(String(d.player || '')))
+					: (d.artUrl || '');
+				if (d.artUrlKind === 'file' && !npSysProxyWarned) { npSysProxyWarned = true; try { mpwTrace("media-session:art-proxy", { player: d.player }) } catch (e) {} }
+				ctl.setMedia({
+					kind: 'system',
+					title: String(d.title || ''),
+					byline: [d.artist, d.album].filter(Boolean).join(' · ') || String(d.player || ''),
+					cover: cover, total: d.duration ? Math.round(Number(d.duration) / 1000) : null,
+					playing: !!d.playing, canPlay: !!d.canPlay, canNext: !!d.canNext, canPrev: !!d.canPrev,
+					canVolume: true, system: true, player: String(d.player || ''), adapter: String(d.adapter || ''),
+				});
+				if (d.position !== null && d.position !== undefined) ctl.setProgress(Math.round(Number(d.position) / 1000));
+				npSysLast = { at: Date.now(), player: String(d.player || ''), title: String(d.title || ''), playing: !!d.playing, canNext: !!d.canNext, canPrev: !!d.canPrev, canPlay: !!d.canPlay };
+				return true;
+			} catch (e) { mpwErr("npApplySystemMedia", e); return false }
+		}
+		/** 一次拉取 + 落卡（轮询的每一步都走它；`?describe=1` 不带 —— 那是诊断用的）。 */
+		async function npRefreshSystemMedia() {
+			try {
+				const ctl = npEnsureCtl();
+				if (!ctl || !ctl.isEnabled()) { npSystemMediaStop(); return null }
+				const r = await fetch(HOST_BASE + '/media-session', { cache: 'no-store' });
+				if (!r.ok) throw new Error('HTTP ' + r.status);
+				const d = await r.json();
+				npSysFails = 0;
+				if (d && d.available === true) { npApplySystemMedia(d); return d }
+				/* 不可用：**不接管**（卡片继续显示壁纸自己的媒体），但把原因留痕 —— 排障时一眼看到"为什么没接上"。 */
+				try { window.__mpwSystemMedia = { available: false, reason: d && d.reason, at: Date.now() } } catch (e) {}
+				return d || null;
+			} catch (e) {
+				npSysFails++;
+				try { window.__mpwSystemMedia = { available: false, reason: 'fetch:' + String(e && e.message || e).slice(0, 80), fails: npSysFails, at: Date.now() } } catch (e2) {}
+				return null;
+			}
+		}
+		/** 一拍：不可见就**不发请求**（只把下一次排后一点）；可见才拉一次，并按结果决定节奏。 */
+		async function npSystemMediaTick() {
+			try {
+				const ctl = npEnsureCtl();
+				if (!ctl || !ctl.isEnabled()) { npSystemMediaStop(); return null }
+				if (document.visibilityState !== 'visible') { npSystemMediaSchedule(NP_SYS_IDLE_MS); return null }
+				const d = await npRefreshSystemMedia();
+				if (npSysFails >= 3) { npSystemMediaSchedule(NP_SYS_IDLE_MS); return d }   // 连续失败：降到慢探（不再骚扰宿主，也不彻底停 ⇒ 后端起来了还能自己接上）
+				npSystemMediaSchedule(d && d.available === true ? NP_SYS_POLL_MS : NP_SYS_IDLE_MS);
+				return d;
+			} catch (e) { npSystemMediaSchedule(NP_SYS_IDLE_MS); return null }
+		}
+		/** 起轮询（幂等）：第一次立刻探一拍，之后由 `npSystemMediaTick` 自适应续期。 */
+		function npSystemMediaStart() {
+			try {
+				const ctl = npEnsureCtl();
+				if (!ctl || !ctl.isEnabled()) return false;
+				npSysFails = 0;
+				npSysTimerSet(() => { try { npSystemMediaTick() } catch (e) {} }, 0);
+				npSysTimer = npSysTimerSet(() => { npSysTimer = 0; try { npSystemMediaTick() } catch (e) {} }, NP_SYS_POLL_MS);
+				return true;
+			} catch (e) { return false }
+		}
+		/** 系统媒体是否是当前数据源（供传输动作改道；`npSysLast` 只记"真的接上过"）。 */
+		function npSystemMediaActive() { try { return !!(npSysLast && Date.now() - npSysLast.at < 5 * NP_SYS_POLL_MS) } catch (e) { return false } }
+		/** 传输动作改道：系统媒体在场时，卡片按钮控制**系统播放器**（能力位先判，够不着就不发）。 */
+		async function npSystemControl(op) {
+			try {
+				const map = { play: 'playpause', pause: 'playpause', restart: 'playpause', next: 'next', prev: 'prev' };
+				const sysOp = map[op];
+				if (!sysOp) return { ok: false, reason: 'unsupported-op' };
+				const last = npSysLast || {};
+				const r = await fetch(HOST_BASE + '/media-control', {
+					method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ op: sysOp }),
+				});
+				const d = await r.json().catch(() => null);
+				try { npOpTrace('system-control', sysOp, (d && d.ok ? 'ok' : 'fail:' + String(d && d.reason || r.status)) + ' player=' + last.player) } catch (e) {}
+				setTimeout(() => { try { npRefreshSystemMedia() } catch (e) {} }, 250);   // 控制完立刻回读一次状态
+				return d || { ok: false, reason: 'bad-reply' };
+			} catch (e) { return { ok: false, reason: 'fetch:' + String(e && e.message || e).slice(0, 60) } }
+		}
+
 		let npSlotAction = null;        // 宿主 slot `sidebar.footer.action` 的占用组件
 
 		/** 控制器**单例**（幂等）：slot 组件与 apply 路径共用同一个。 */
@@ -7765,6 +7901,7 @@ function sectionSigNow() {
 				npDropAudio();
 				npMediaCache = { key: "", at: 0, data: null };
 				npMediaToken++;
+				npSystemMediaStop();   // ①(MEDIA-1 接线) 开关关掉 ⇒ 系统媒体轮询也要停（不留后台定时器）
 				return;
 			}
 			ctl.setEnabled(true);
@@ -7839,6 +7976,9 @@ function sectionSigNow() {
 			/* ①(NP-4)① 电平：刷新/切壁纸后把 `npVolume` 补落到真实元素上。 */
 			try { npApplyVolume(); } catch (e) {}
 			ctl.setMedia(npResolveMedia(s));
+			/* ①(MEDIA-1 接线 2026-09-20) 壁纸自己的媒体先落卡（同步、不变），**再**异步补系统媒体：
+			   宿主回 `available:false`（本机无会话总线）⇒ 什么都不覆盖，卡片还是壁纸自己的标题/预览。 */
+			try { npSystemMediaStart(); } catch (e) {}
 			/* ①(NP-3) 清单/播放器：有目录作用域才拉清单；清单到了之后把当前曲目装进播放器
 			   （**只装源、不自动播放** —— 浏览器自动播放策略 + "不替用户按播放"两条都要求这样）。 */
 			try {
@@ -8712,6 +8852,18 @@ function sectionSigNow() {
 				return st.join(" <- ");
 			} catch (e) { return "" }
 		}
+		/** ①(2026-09-20 彻查「静音下仍出声」) 这一条记录**来自哪个窗口**：
+		 *  主页面 / 同源 iframe（壁纸帧、别的插件帧…）。跨源帧我们的钩子装不进去 ⇒ 如实标 `foreign:true`，
+		 *  绝不把"看不到"说成"没有"（用户能据此知道"声音来自某个跨源帧，本插件管不到它的 WebAudio"）。 */
+		function mpwAuditWin(win) {
+			try {
+				const w = win || window;
+				const isTop = (() => { try { return w === w.top } catch (e) { return false } })();
+				let url = "";
+				try { url = String((w.location && w.location.href) || "") } catch (e) { url = "cross-origin" }
+				return { top: isTop, url: url.replace(/token=[^&]*/, "token=…").slice(0, 120), foreign: url === "cross-origin" };
+			} catch (e) { return { top: true, url: "", foreign: false } }
+		}
 		function mpwAuditEl(el) {
 			try {
 				if (!el) return null;
@@ -8721,6 +8873,17 @@ function sectionSigNow() {
 					connected: el.isConnected !== false,
 					src: src.replace(/token=[^&]*/, "token=…").slice(0, 90),
 					hasSrcAttr: !!(el.getAttribute && el.getAttribute("src")),
+					/* 声音素材的**归属指纹**（用户问"这声音是谁放的"时，一眼能分类）：
+					   ours = 我们自己的元素/接口；whale = 那个第三方鲸鱼插件；frame = 壁纸帧内；other = 未知 */
+					owner: (() => {
+						try {
+							const own = (String(el.id || "") === "mpw-bgVideo") || /(^|\s)mpw[-_]/.test(String(el.className || "")) || /\/api\/mpkg-wallpaper\//.test(src);
+							if (own) return "ours";
+							if (/\/dsh-whale\//.test(src)) return "whale-widget";
+							if (el.ownerDocument && el.ownerDocument !== document) return "frame";
+							return "other";
+						} catch (e) { return "unknown" }
+					})(),
 				};
 			} catch (e) { return null }
 		}
@@ -8730,11 +8893,11 @@ function sectionSigNow() {
 				return { on: s.npNowPlaying !== void 0 ? !!s.npNowPlaying : DEFAULT_NP_NOW_PLAYING, link: npLinkOn(s), mute: s.mute !== void 0 ? !!s.mute : true };
 			} catch (e) { return null }
 		}
-		function mpwAuditPush(kind, el, extra) {
+		function mpwAuditPush(kind, el, extra, win) {
 			try {
 				if (!mpwAuditOn()) return null;
 				const rec = Object.assign({
-					t: Date.now(), kind: String(kind || ""), who: mpwAuditWho(), el: mpwAuditEl(el),
+					t: Date.now(), kind: String(kind || ""), who: mpwAuditWho(), el: mpwAuditEl(el), win: mpwAuditWin(win),
 					muted: el ? !!el.muted : null, volume: el && typeof el.volume === "number" ? Number(el.volume.toFixed(2)) : null,
 					paused: el ? !!el.paused : null, currentTime: el && typeof el.currentTime === "number" ? Number(el.currentTime.toFixed(2)) : null,
 					hidden: (() => { try { return document.hidden === true } catch (e) { return null } })(),
@@ -8751,7 +8914,14 @@ function sectionSigNow() {
 				   ③ hidden 期间的 play / 取消静音。
 				   命中 ⇒ 立刻把**审计窗口**（最近 12 条）POST 到 /diag（脱敏、截断、5s 节流）。 */
 				const audible = !!(rec.el && rec.paused === false && rec.muted === false && Number(rec.volume) > 0);
+				/* ①(2026-09-20 用户点名「静音状态下还是突然冒出来的声音」) **这一条**才是那次投诉的直接判据：
+				   设置项 `mute === true`（面板写着静音），元素却处在**可听**状态（`!paused && !muted && volume>0`）
+				   —— 不管是谁把它改成这样的（我们的哪条路径 / 壁纸帧内 / 别的插件），都必须立刻上报并带上**是谁改的**。
+				   旧判据只有"可听播放"这一条泛判据（设置是开是关都报），既漏了"静音下可听"这个组合的强调，
+				   也没把 `np.mute` 与可听状态**放在一起**判断。 */
+				const muteOnAudible = !!(rec.np && rec.np.mute === true && audible);
 				const suspicious = audible
+					|| muteOnAudible
 					|| !!(rec.el && rec.el.connected === false && rec.paused === false)
 					|| (kind === "play" && rec.hidden === true)
 					|| ((kind === "unmute" || kind === "volume") && rec.hidden === true && rec.muted === false);
@@ -8761,7 +8931,8 @@ function sectionSigNow() {
 						mpwAuditLastBeacon = Date.now();
 						try {
 							mpwWebDiag("audio-audit", {
-								trigger: audible ? "audible-playback" : (rec.el && rec.el.connected === false ? "detached-playing" : "hidden-transition"),
+								trigger: muteOnAudible ? "mute-on-but-audible"
+									: (audible ? "audible-playback" : (rec.el && rec.el.connected === false ? "detached-playing" : "hidden-transition")),
 								record: rec, window: list.slice(-12), count: list.length,
 								visibility: (() => { try { return document.visibilityState } catch (e) { return null } })(),
 							});
@@ -8772,19 +8943,24 @@ function sectionSigNow() {
 				return rec;
 			} catch (e) { return null }
 		}
-		function mpwInstallAudioAudit() {
-			if (mpwAuditInstalled || !mpwAuditOn()) return false;
-			mpwAuditInstalled = true;
-			try {
-				window.__mpwAudioAudit = window.__mpwAudioAudit || { list: [], suspicious: 0 };
-				window.__mpwAudioAudit.push = mpwAuditPush;
-				window.__mpwAudioAudit.clear = () => { try { window.__mpwAudioAudit.list.length = 0 } catch (e) {} };
-			} catch (e) {}
+		/** ①(2026-09-20 彻查「静音下仍出声」) 对**任意窗口**装审计钩子。
+		 *  为什么必须能装进子窗口：真机上"突然响一声"的声源有两类是我们看不到的 ——
+		 *    ① **壁纸帧内**的 `<audio>/<video>`（同源模式帧有**自己独立的 `HTMLMediaElement.prototype`**，
+		 *       在主窗口上打补丁对它完全无效 ⇒ 旧审计对帧内声音是"瞎的"）；
+		 *    ② 别的插件帧里的声音（同一原因）。
+		 *  跨源帧装不进去（浏览器安全模型）⇒ 由 `mpwAuditWin()` 如实标 `foreign:true`，不谎报"没有声音"。
+		 *  `who` 的栈里会带上帧 URL，用户/我们都能据此指认"这条声音是谁放的"。 */
+		function mpwAuditPatchWin(win) {
+			if (!win) return false;
+			try { if (win.__mpwAuditedWin) return false } catch (e) { return false }
+			try { win.__mpwAuditedWin = true } catch (e) { /* 只读窗口也继续装 */ }
+			const push = (kind, el, extra) => { try { return mpwAuditPush(kind, el, extra, win) } catch (e) { return null } };
+			/* ① `<audio>/<video>`：play / muted / volume */
 			try {
-				const P = globalThis.HTMLMediaElement && HTMLMediaElement.prototype;
+				const P = win.HTMLMediaElement && win.HTMLMediaElement.prototype;
 				if (P && typeof P.play === "function" && !P.__mpwAudited) {
 					const origPlay = P.play;
-					P.play = function () { try { mpwAuditPush("play", this) } catch (e) {} return origPlay.apply(this, arguments) };
+					P.play = function () { push("play", this); return origPlay.apply(this, arguments) };
 					for (const prop of ["muted", "volume"]) {
 						try {
 							const d = Object.getOwnPropertyDescriptor(P, prop);
@@ -8794,7 +8970,7 @@ function sectionSigNow() {
 								const bMuted = !!this.muted, bVol = this.volume;
 								set.call(this, v);
 								const kind = prop === "muted" ? (this.muted ? "mute" : "unmute") : "volume";
-								if (prop === "muted" ? bMuted !== !!this.muted : bVol !== this.volume) { try { mpwAuditPush(kind, this, { before: { muted: bMuted, volume: bVol } }) } catch (e) {} }
+								if (prop === "muted" ? bMuted !== !!this.muted : bVol !== this.volume) push(kind, this, { before: { muted: bMuted, volume: bVol } });
 								return v;
 							};
 							wrapped.__mpwAudited = true;
@@ -8804,34 +8980,88 @@ function sectionSigNow() {
 					P.__mpwAudited = true;
 				}
 			} catch (e) {}
+			/* ② `new Audio(...)`（绕过 DOM 标签的声源，最常见的"响一声"） */
 			try {
-				if (typeof window.Audio === "function" && !window.Audio.__mpwAudited) {
-					const OrigAudio = window.Audio;
-					const Wrapped = function () { const a = new OrigAudio(...arguments); try { mpwAuditPush("new-Audio", a, { args: Array.prototype.slice.call(arguments).join(",").slice(0, 80) }) } catch (e) {} return a };
+				if (typeof win.Audio === "function" && !win.Audio.__mpwAudited) {
+					const OrigAudio = win.Audio;
+					const Wrapped = function () { const a = new OrigAudio(...arguments); try { push("new-Audio", a, { args: Array.prototype.slice.call(arguments).join(",").slice(0, 80) }) } catch (e) {} return a };
 					Wrapped.__mpwAudited = true;
 					try { Wrapped.prototype = OrigAudio.prototype } catch (e) {}
-					window.Audio = Wrapped;
+					win.Audio = Wrapped;
 				}
 			} catch (e) {}
+			/* ③ WebAudio：构造 / decodeAudioData / **真的出声那一刻**（AudioBufferSourceNode.start）
+			   ④(2026-09-20 补) 只记"建了 AudioContext"是没用的：Live2D 角色语音那类声源
+			   走 `AudioBufferSourceNode.start()` 出声，**不碰任何 `<audio>` 标签** ——
+			   这正是"设置静音却仍然响一声"最可能的声源，必须记到"谁在什么时候 start 了它"。 */
 			for (const key of ["AudioContext", "webkitAudioContext"]) {
 				try {
-					const Orig = window[key];
+					const Orig = win[key];
 					if (typeof Orig !== "function" || Orig.__mpwAudited) continue;
-					const Wrapped = function () { const c = new Orig(...arguments); try { mpwAuditPush("AudioContext", null, { ctor: key, state: c && c.state }) } catch (e) {} return c };
+					const Wrapped = function () { const c = new Orig(...arguments); try { push("AudioContext", null, { ctor: key, state: c && c.state }) } catch (e) {} return c };
 					Wrapped.__mpwAudited = true;
 					try { Wrapped.prototype = Orig.prototype } catch (e) {}
-					window[key] = Wrapped;
+					win[key] = Wrapped;
 				} catch (e) {}
 			}
 			try {
-				const AC = window.AudioContext || window.webkitAudioContext;
+				const AC = win.AudioContext || win.webkitAudioContext;
 				const proto = AC && AC.prototype;
 				if (proto && typeof proto.decodeAudioData === "function" && !proto.__mpwAudited) {
 					const orig = proto.decodeAudioData;
-					proto.decodeAudioData = function () { try { mpwAuditPush("decodeAudioData", null, { ctxState: this && this.state }) } catch (e) {} return orig.apply(this, arguments) };
+					proto.decodeAudioData = function () { push("decodeAudioData", null, { ctxState: this && this.state }); return orig.apply(this, arguments) };
 					proto.__mpwAudited = true;
 				}
+				if (proto && typeof proto.resume === "function" && !proto.__mpwResumed) {
+					const origResume = proto.resume;
+					proto.resume = function () { push("audioctx-resume", null, { ctxState: this && this.state }); return origResume.apply(this, arguments) };
+					proto.__mpwResumed = true;
+				}
+			} catch (e) {}
+			for (const [nodeKey, nodeName] of [["AudioBufferSourceNode", "buffer-source"], ["OscillatorNode", "oscillator"], ["ConstantSourceNode", "constant"]]) {
+				try {
+					const Ctor = win[nodeKey];
+					const np = Ctor && Ctor.prototype;
+					if (np && typeof np.start === "function" && !np.__mpwAudited) {
+						const origStart = np.start;
+						np.start = function () {
+							let ctxState = null, dur = null;
+							try { ctxState = this.context && this.context.state } catch (e) {}
+							try { dur = this.buffer && this.buffer.duration } catch (e) {}
+							push("webaudio-start", null, { node: nodeName, ctxState: ctxState, bufferSec: dur == null ? null : Number(Number(dur).toFixed(3)), ourCtx: !!this.context });
+							return origStart.apply(this, arguments)
+						};
+						np.__mpwAudited = true;
+					}
+				} catch (e) {}
+			}
+			/* ④ 递归同源子帧（帧内元素有自己的原型对象；跨源会抛 ⇒ 记一条"装不上"的痕） */
+			try {
+				for (let i = 0; i < win.frames.length; i++) {
+					try { mpwAuditPatchWin(win.frames[i]) } catch (e) { try { mpwAuditPush("frame-cross-origin", null, { idx: i, reason: String(e && e.name || e).slice(0, 40) }, win) } catch (e2) {} }
+				}
+			} catch (e) {}
+			return true;
+		}
+		/** 新出现的 iframe（壁纸帧常是晚一步插进来的）⇒ 重新扫一遍；每秒一次、上限 60 次，零长尾开销。 */
+		let mpwAuditFrameScans = 0;
+		function mpwAuditScanFrames() {
+			try {
+				if (mpwAuditFrameScans++ > 60) return;
+				mpwAuditPatchWin(window);
+			} catch (e) {}
+		}
+		function mpwInstallAudioAudit() {
+			if (mpwAuditInstalled || !mpwAuditOn()) return false;
+			mpwAuditInstalled = true;
+			try {
+				window.__mpwAudioAudit = window.__mpwAudioAudit || { list: [], suspicious: 0 };
+				window.__mpwAudioAudit.push = mpwAuditPush;
+				window.__mpwAudioAudit.clear = () => { try { window.__mpwAudioAudit.list.length = 0 } catch (e) {} };
+				window.__mpwAudioAudit.scanFrames = () => { try { mpwAuditFrameScans = 0; mpwAuditScanFrames(); return true } catch (e) { return false } };
 			} catch (e) {}
+			try { mpwAuditPatchWin(window); } catch (e) {}
+			try { setInterval(mpwAuditScanFrames, 1000); } catch (e) {}
 			try { mpwTrace("audio-audit:installed", {}); } catch (e) {}
 			return true;
 		}

package/lib/index.js

@@ -26,6 +26,12 @@ import {
   MEDIA_AUDIO_ROUTE, MEDIA_AUDIO_DEFAULTS, normalizeMediaAudio, mediaAudioReport, mediaAudioPatchForEntry,
 } from './web-wallpaper.js';
 
+/* ①(MEDIA-1 接线 2026-09-20) 系统媒体会话（MPRIS / SMTC）：模块早就在（`media-session-test` 95/0），
+   但一直**没接线** ⇒ NP 卡片拿不到系统曲目/封面/进度（喂它的是测试台自己的播放器状态）。
+   接线口径见 docs/MEDIA-SESSION.md §6：宿主三条只读/控制路由 + 客户端异步补充路径，
+   **不改** `npResolveMedia` 那条同步语义（它解的是"壁纸自己的媒体"）。 */
+import { createMediaSession, CONTROL_OPS, SEEK_MAX_MS, MAX_ART_CHARS } from './media-session.js';
+
 const BASE = '/api/mpkg-wallpaper';
 /** ①(修正) 更新检测：版本号主导（semver），哈希仅作内容差异提示。
  *  之前纯哈希对比——本地有未推送改动就误报"新版本 3.1.2 → 3.1.2"（用户实测）。 */
@@ -1916,6 +1922,74 @@ function apply(ctx) {
     });
 
     // ①(新) 自定义本地壁纸目录：POST 设置并扫描目录内的媒体文件
+    /* ═══ ①(MEDIA-1 接线 2026-09-20) 系统媒体会话三条路由（契约：docs/MEDIA-SESSION.md §6） ═══════════
+       · GET  /media-session            ⇒ `snapshot()` 21 键**原样透传**（路由里不"顺手"改形状）
+       · POST /media-control {op,arg}   ⇒ op 只允许 CONTROL_OPS 六项（坏 op 在模块里就被拒，这里再挡一道）
+       · GET  /media-art?player=<名>    ⇒ MPRIS 的 `file://` 封面代理（浏览器读不到宿主磁盘；
+                                            只允许**快照里出现过的** player + 那个 artUrl 路径）
+       为什么是三条而不是一条：封面是二进制（不能塞进 JSON）、控制是副作用（不能混进只读快照）、
+       快照要能被 2s 轮询（越简单越好）。 */
+    const mediaSession = createMediaSession({ env: process.env });
+    webServer.register({
+      kind: 'exact', path: BASE + '/media-session',
+      handler: async (req, res) => {
+        try {
+          const snap = await mediaSession.snapshot();
+          /* 默认档**只回 21 键快照**（契约：路由里不改形状）。`?describe=1` 才附带模块自述
+             （平台/适配器/超时/上限；纯函数、不触发任何命令），给诊断面板与探针用。 */
+          let extra = {};
+          try { if (new URL(req.url, 'http://localhost').searchParams.get('describe') === '1') extra.describe = mediaSession.describe(); } catch (e) {}
+          json(res, 200, Object.assign({ ok: true }, snap, extra));
+        } catch (e) { json(res, 500, { ok: false, error: String(e && e.message || e) }); }
+      },
+    });
+    webServer.register({
+      kind: 'exact', path: BASE + '/media-control',
+      handler: async (req, res) => {
+        try {
+          if (req.method !== 'POST') { json(res, 405, { ok: false, error: '只接受 POST（body = {op,arg}）', allow: 'POST' }); return; }
+          let body = '';
+          for await (const c of req) { body += String(c); if (body.length > 64 * 1024) { json(res, 413, { ok: false, error: 'body 过大' }); return; } }
+          let d = {};
+          try { d = JSON.parse(body || '{}'); } catch { json(res, 400, { ok: false, error: 'bad json' }); return; }
+          const op = String(d && d.op || '');
+          if (!CONTROL_OPS.includes(op)) { json(res, 400, { ok: false, error: 'bad op', ops: CONTROL_OPS.slice() }); return; }
+          let arg = d && d.arg;
+          if (op === 'seek') {
+            const n = Number(arg);
+            if (!Number.isFinite(n) || n < 0) { json(res, 400, { ok: false, error: 'bad seek arg', maxMs: SEEK_MAX_MS }); return; }
+            arg = Math.min(Math.floor(n), SEEK_MAX_MS);
+          } else arg = null;
+          const out = await mediaSession.control(op, arg);
+          json(res, out && out.ok ? 200 : 200, Object.assign({ ok: !!(out && out.ok) }, out || {}));
+        } catch (e) { json(res, 500, { ok: false, error: String(e && e.message || e) }); }
+      },
+    });
+    webServer.register({
+      kind: 'exact', path: BASE + '/media-art',
+      handler: async (req, res) => {
+        try {
+          const u = new URL(req.url, 'http://localhost');
+          const player = String(u.searchParams.get('player') || '');
+          const snap = await mediaSession.snapshot();
+          // 只服务**当前快照里**那个玩家的封面：调用方不能拿任意路径来读宿主文件。
+          if (!snap || !snap.available || !player || player !== snap.player) { json(res, 404, { ok: false, error: 'no such player in current snapshot' }); return; }
+          if (snap.artUrlKind !== 'file') { json(res, 409, { ok: false, error: 'artUrl 不是本地文件（直接用 artUrl 即可）', kind: snap.artUrlKind }); return; }
+          const p = decodeURIComponent(String(snap.artUrl).replace(/^file:\/\//, ''));
+          let st = null;
+          try { st = statSync(p); } catch { json(res, 404, { ok: false, error: '封面文件不存在' }); return; }
+          if (!st.isFile()) { json(res, 400, { ok: false, error: '不是文件' }); return; }
+          if (st.size > MAX_ART_CHARS) { json(res, 413, { ok: false, error: '封面过大', bytes: st.size, maxBytes: MAX_ART_CHARS }); return; }
+          const buf = readFileSync(p);
+          const mime = /^\x89PNG/.test(buf.slice(0, 4).toString('latin1')) ? 'image/png'
+            : (buf.slice(0, 3).toString('latin1') === 'GIF' ? 'image/gif'
+              : (buf.slice(0, 2).toString('latin1') === '\xff\xd8' ? 'image/jpeg' : 'application/octet-stream'));
+          res.writeHead(200, { 'content-type': mime, 'content-length': String(buf.length), 'cache-control': 'no-store' });
+          res.end(buf);
+        } catch (e) { json(res, 500, { ok: false, error: String(e && e.message || e) }); }
+      },
+    });
+
     webServer.register({
       kind: 'exact', path: BASE + '/custom-dir',
       handler: async (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mpkg-wallpaper",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "DSH Web 壁纸引擎 Wallpaper Engine mpkg 背景插件：浏览器内直接解析 .mpkg（preview.gif 动态背景/内嵌 mp4 视频/多时段切换），整屏统一虚化/对话框/弹层/遮罩独立虚化、镜头缩放平移、时钟、冲突检测。",
   "private": false,
   "type": "module",