dsh-mpkg-wallpaper 3.12.0 → 3.13.0

package/lib/audio-bus.js

@@ -0,0 +1,457 @@
+// audio-bus.js —— 「跨出口的总线级静音」内核（宿主侧，纯逻辑，可在桩环境单测）
+//
+// 为什么要它（事故链）：用户反复报「设置里静音了，但还是会偶发卡顿地响一声」。根因不是"静音按钮没生效"，
+// 而是**声音出口不止一个**：我们自己的音乐控件走 `<audio>`（muted 够用），但壁纸/角色语音/可视化可能走
+// Web Audio——`new AudioContext()` 是**别人**建的、`source.connect(ctx.destination)` 也是**别人**连的，
+// 我们连"谁在响"都看不见。上几轮我们只做到了**记录**（`mpwInstallAudioAudit` 的钩子），
+// 记录不等于接管：只要有一个节点直连 `destination`，它就绕过了我们的静音。
+//
+// 本模块做**接管**，而且是**总线级**的（逐条对应审阅意见里点出的坑）：
+//   ① `AudioNode.prototype.connect` 原型级拦截：任何节点连 `ctx.destination` ⇒ 改接到该 ctx 的
+//      **懒创建 masterGain**。原型级 ⇒ "比我们更早创建的 AudioContext"也能被收进来（只要它**还没**连）；
+//   ② masterGain 的创建与它到 destination 的连接**走原始引用**（否则懒创建那一下会自己拦自己 ⇒ 递归）；
+//   ③ `connect` 的**返回值原样透传**（`a.connect(b).connect(c)` 链式依赖它）；
+//   ④ 判定用 `dest === ctx.destination`（**引用比较**；`instanceof` 跨 realm 会失败）；
+//   ⑤ `OfflineAudioContext` **放行**（它也有 destination；误挂 master 会改掉离线渲染结果）；
+//   ⑥ 静音 = `master.gain.cancelScheduledValues(now) + setValueAtTime(0, now)`（**不用 `ctx.suspend()`**：
+//      冻结 `currentTime` 会破坏第三方的调度与可视化）；analyser 若接在 master **之前**，频谱仍有数据
+//      ⇒ 这同时修掉我们"元素被 muted ⇒ 音条恒 0"的老限制；
+//   ⑦ 归因补齐：`new Audio()`、`createMediaElementSource`（元素 muted 只影响输入源，输出在 Web Audio）、
+//      `createMediaStreamSource`（不吃 `track.enabled`）、`src`/`srcObject` setter（autoplay 绕过 `play()`）、
+//      `start(when)` 的迟到分布（**负很多** = bfcache/节流恢复；**负一点点** = 正常抖动，不误杀）、
+//      Shadow DOM 里的媒体元素、`speechSynthesis`、`RTCPeerConnection` 的 `track.enabled`；
+//   ⑧ **跨 realm 各装一遍**（同源 iframe 的 `AudioNode.prototype` 与父页不是同一个）。
+//
+// 档位（`?mpwhardmute=` 或 `bus.setMode()`）—— 二分定位用，不是"总开关"：
+//   off       只归因，不动声音（缺省）
+//   redirect  **只重定向不静音**：还能听见 ⇒ 有出口绕过 connect（历史遗留直连 / 跨 realm）；
+//             声音变闷变小 ⇒ 有节点被**重复挂** master（多次 connect destination）
+//   1         重定向 + master 归零 + 媒体压制 + speechSynthesis.cancel + WebRTC track.enabled=false
+//   all       1 + 对跨域帧 postMessage 请求静音 + 连未归因的 ctx 也压
+//   report    只汇报不压（产出"不可控清单"）
+//
+// 诚实边界：hook 之前**已经**连上 destination 的节点无法追溯（没有任何 API 能枚举已有连接）⇒
+//   report() 会把"能观测到出声但不在我们 bus 上"的 ctx 单列为 `bypassSuspected`，不假装收全了。
+
+export const BUS_MODES = ['off', 'redirect', '1', 'all', 'report'];
+export const BUS_DEFAULT_MODE = 'off';
+export const BUS_ATTR = 'data-mpw-audio-bus';
+export const BUS_MSG = 'mpw:audio-bus';
+/** 迟到补播的判定阈值：负得比这个多 ⇒ 当"恢复后补播"（bfcache/节流），否则算正常抖动，不误杀。 */
+export const LATE_START_SEC = 1.0;
+export const JITTER_START_SEC = 0.05;
+
+const now = (win) => { try { return win.performance && win.performance.now ? win.performance.now() : Date.now() } catch (e) { return Date.now() } };
+
+/** 规范化档位（未知值 ⇒ 缺省；不抛）。 */
+export function normalizeMode(m) {
+  const s = String(m === undefined || m === null ? '' : m).trim().toLowerCase();
+  return BUS_MODES.indexOf(s) >= 0 ? s : BUS_DEFAULT_MODE;
+}
+
+/** 该档是否真的**压**声音（report/off/redirect 都不压）。 */
+export function modeMutes(m) {
+  const s = normalizeMode(m);
+  return s === '1' || s === 'all';
+}
+/** 该档是否要连"未归因的 ctx"一起压。 */
+export function modeMutesAll(m) { return normalizeMode(m) === 'all'; }
+/** 该档是否只重定向（诊断档：验证 bus 收没收全）。 */
+export function modeRedirectOnly(m) { return normalizeMode(m) === 'redirect'; }
+
+/**
+ * 在一个 window 上装总线。**幂等**（同一 win 多次调用只装一遍）。
+ * @param {object} win 目标 window（可传 iframe 的 contentWindow ⇒ 跨 realm 各装一遍）
+ * @param {object} opts { mode, onEvent(name, detail), mediaRoots: ()=>Element[] }
+ * @returns {object|null} api
+ */
+export function installAudioBus(win, opts = {}) {
+  if (!win || typeof win !== 'object') return null;
+  if (win.__mpwAudioBus && win.__mpwAudioBus.__installed) {           // 幂等：同一 realm 只装一遍
+    if (opts.mode !== undefined) win.__mpwAudioBus.setMode(opts.mode);
+    return win.__mpwAudioBus;
+  }
+  const log = [];
+  const emit = (name, detail) => {
+    const rec = { t: now(win), name, detail: detail || null };
+    log.push(rec);
+    if (log.length > 300) log.shift();
+    try { if (typeof opts.onEvent === 'function') opts.onEvent(name, rec.detail) } catch (e) { /* 上报失败不许影响音频 */ }
+  };
+
+  const state = {
+    mode: normalizeMode(opts.mode),
+    muted: false,
+    wasMuted: false,          // 上一次是否处于"真的压着"的状态（决定恢复时要不要写回 1）
+    contexts: [],                 // { id, ctx, adopted, offline, createAt, createStack, frames }
+    masters: new WeakMap(),       // ctx -> masterGain
+    adopted: new Set(),           // 被我们接管过的 ctx（**含**安装前就存在的老 ctx）——静音要遍历这一份
+    media: new Set(),             // 媒体元素（含 new Audio() 与 shadow DOM 里的）
+    tappedMedia: new WeakSet(),   // 被 createMediaElementSource 接管的元素（不能 pause：analyser 要数据）
+    redirects: 0,
+    bypassSuspected: [],          // 能观测到出声但不在 bus 上的 ctx
+    uncontrollable: [],           // 跨域帧（拿不到 contentDocument）
+    frames: [],
+  };
+  let ctxSeq = 0;
+  let timer = 0;
+  /* 本 realm 的**原始 connect**。必须是 `AudioNode.prototype.connect` —— 真实浏览器里
+     `AudioContext.prototype` 上**没有** connect（我第一版写错过，那样一条都拦不到）。 */
+  let realmOrigConnect = null;
+  let realmNodeProto = null;
+
+  const protoOf = (Ctor) => { try { return Ctor && Ctor.prototype ? Ctor.prototype : null } catch (e) { return null } };
+  const stackOf = () => { try { return String(new win.Error().stack || '').split('\n').slice(2, 5).join(' | ').slice(0, 400) } catch (e) { return '' } };
+
+  /* ── ① 原型级 connect 拦截（含"懒创建 masterGain"） ───────────────────────────── */
+  const patched = [];               // [{ proto, origConnect }]，卸载时还原
+  const patchConnect = (proto) => {
+    if (!proto || typeof proto.connect !== 'function' || proto.__mpwBusPatched) return false;
+    const origConnect = proto.connect;
+    proto.connect = function mpwBusConnect(dest) {
+      const rest = Array.prototype.slice.call(arguments, 1);
+      let ctx = null;
+      try { ctx = this && this.context } catch (e) { /* 某些桩没有 context */ }
+      // 只拦"直连 destination"；用**引用比较**（instanceof 跨 realm 会失败）
+      if (ctx && dest && dest === ctx.destination && !isOfflineCtx(ctx)) {
+        let master = state.masters.get(ctx);
+        if (!master) {
+          master = createMaster(ctx);        // 内部全走原始引用
+          state.masters.set(ctx, master);
+          if (master) {
+            state.adopted.add(ctx);
+            /* 比我们更早创建、我们没登记过的 ctx（历史遗留）：**采用时补登记**，
+               否则 applyMute 遍历的名单里没有它 ⇒ 它照样出声（这正是"假绿"的来源）。 */
+            if (ctxId(ctx) < 0) state.contexts.push({ id: 'ctx' + (++ctxSeq), ctx, adopted: true, legacy: true, createAt: now(win), createStack: stackOf(), frames: 0 });
+          }
+        }
+        if (this !== master) state.redirects++;
+        emit('reroute', { ctxId: ctxId(ctx), kind: nodeKind(this), stack: stackOf() });
+        origConnect.call(this, master, ...rest);
+        /* ③ 真 API 语义：`connect(dest)` 返回**调用方传进来的那个目标节点**（链式 `a.connect(b).connect(c)` 依赖它）。
+           若把 master 返回出去，第三方的 `a.connect(ctx.destination).connect(y)` 会变成 `master→y`（语义被改）。 */
+        return dest;
+      }
+      return origConnect.call(this, dest, ...rest);
+    };
+    proto.__mpwBusPatched = true;
+    patched.push({ proto, origConnect });
+    if (!realmOrigConnect) { realmOrigConnect = origConnect; realmNodeProto = proto }
+    return true;
+  };
+  /** ② masterGain 的创建与连接**必须走原始引用**（否则懒创建那一下会自己拦自己 ⇒ 递归）。 */
+  const createMaster = (ctx) => {
+    const origCreate = ctx.__origCreateGain || (ctx.createGain && ctx.createGain.bind(ctx));
+    const master = origCreate ? origCreate() : null;
+    if (!master) return null;
+    try {
+      if (master.gain) { master.gain.value = state.muted ? 0 : 1 }
+      const origConnect = realmOrigConnect;
+      if (origConnect) origConnect.call(master, ctx.destination);       // 原始引用，绕开 hook
+      else if (master.connect) master.connect(ctx.destination);
+    } catch (e) { emit('master-connect-fail', { err: String(e && e.message || e) }) }
+    return master;
+  };
+  const isOfflineCtx = (ctx) => {
+    try {
+      const OAC = win.OfflineAudioContext || win.webkitOfflineAudioContext;
+      return !!(OAC && ctx instanceof OAC);        // ⑤ 离线渲染放行
+    } catch (e) { return false }
+  };
+  const ctxId = (ctx) => { const f = state.contexts.find((c) => c.ctx === ctx); return f ? f.id : -1 };
+  const nodeKind = (n) => { try { return String((n && n.constructor && n.constructor.name) || 'AudioNode') } catch (e) { return 'AudioNode' } };
+
+  /* ── ② AudioContext 构造拦截：登记 + 归因（接管本身靠 connect，构造只登记） ───── */
+  const patchCtor = (winObj, key) => {
+    try {
+      const Orig = winObj[key];
+      if (typeof Orig !== 'function' || Orig.__mpwBusWrapped) return;
+      const Wrapped = function (...args) {
+        const ctx = new Orig(...args);
+        try {
+          state.contexts.push({ id: 'ctx' + (++ctxSeq), ctx, adopted: false, offline: false, createAt: now(win), createStack: stackOf(), frames: 0 });
+          emit('ctx-created', { ctor: key, state: ctx && ctx.state });
+        } catch (e) {}
+        return ctx;
+      };
+      try { Wrapped.prototype = Orig.prototype } catch (e) {}
+      Wrapped.__mpwBusWrapped = true;
+      winObj[key] = Wrapped;                        // 构造只负责**登记/归因**；接管靠下面的 AudioNode.prototype
+    } catch (e) {}
+  };
+
+  /* ── ③ 归因钩子：MediaElement / MediaStream / src / srcObject / start(when) / speech / WebRTC ── */
+  const patchAttribution = () => {
+    const ACproto = protoOf(win.AudioContext || win.webkitAudioContext);
+    if (ACproto && !ACproto.__mpwBusAttr) {
+      ACproto.__mpwBusAttr = true;
+      for (const [fn, kind] of [['createMediaElementSource', 'media-element'], ['createMediaStreamSource', 'media-stream'], ['createMediaStreamDestination', 'media-stream-dest']]) {
+        try {
+          const orig = ACproto[fn];
+          if (typeof orig !== 'function') continue;
+          ACproto[fn] = function (...a) {
+            const node = orig.apply(this, a);
+            try {
+              if (kind === 'media-element' && a[0]) { state.tappedMedia.add(a[0]); registerMedia(a[0]); }
+              emit('source-node', { kind, ctxId: -1, stack: stackOf() });
+            } catch (e) {}
+            return node;
+          };
+        } catch (e) {}
+      }
+    }
+    // start(when)：迟到分布（负很多 = bfcache/节流恢复；负一点点 = 抖动）
+    for (const [key, kind] of [['AudioBufferSourceNode', 'buffer'], ['OscillatorNode', 'oscillator'], ['ConstantSourceNode', 'constant'], ['AudioWorkletNode', 'worklet']]) {
+      try {
+        const Ctor = win[key]; const np = protoOf(Ctor);
+        if (!np || typeof np.start !== 'function' || np.__mpwBusStart) continue;
+        const origStart = np.start;
+        np.start = function (when) {
+          const rest = Array.prototype.slice.call(arguments, 1);
+          try {
+            const ctx = this.context;
+            const cur = ctx && ctx.currentTime;
+            const delta = (typeof when === 'number' && typeof cur === 'number') ? (when - cur) : null;
+            /* 只**记录**、绝不阻止/丢弃 start（"误杀会掉音符"）：负得多 ⇒ burst（bfcache/节流恢复后的补播）；
+               负一点点 ⇒ jitter（正常调度抖动，进分布供人判读）。未来时刻不记。 */
+            if (delta !== null && delta < 0) {
+              emit(delta < -LATE_START_SEC ? 'start-late-burst' : 'start-late-jitter', { kind, delta: Number(delta.toFixed(3)), mode: state.mode, muted: state.muted, stack: stackOf() });
+            }
+          } catch (e) {}
+          return origStart.apply(this, arguments);
+        };
+        np.__mpwBusStart = true;
+      } catch (e) {}
+    }
+    // new Audio() / src / srcObject（autoplay + src 赋值绕过 play()）
+    try {
+      const OrigAudio = win.Audio;
+      if (typeof OrigAudio === 'function' && !OrigAudio.__mpwBusAudio) {
+        const Wrapped = function (...a) { const el = new OrigAudio(...a); try { registerMedia(el); emit('new-audio', { src: shortSrc(el && el.src) }) } catch (e) {} return el };
+        try { Wrapped.prototype = OrigAudio.prototype } catch (e) {}
+        Wrapped.__mpwBusAudio = true;
+        win.Audio = Wrapped;
+      }
+    } catch (e) {}
+    const HME = win.HTMLMediaElement && win.HTMLMediaElement.prototype;
+    if (HME && !HME.__mpwBusMedia) {
+      HME.__mpwBusMedia = true;
+      for (const prop of ['src', 'srcObject']) {
+        try {
+          const d = Object.getOwnPropertyDescriptor(HME, prop);
+          if (!d || !d.set) continue;
+          const origSet = d.set, origGet = d.get;
+          Object.defineProperty(HME, prop, {
+            configurable: true, enumerable: d.enumerable,
+            get: origGet,
+            set(v) {
+              try { if (state.muted && modeMutes(state.mode)) suppress(this) } catch (e) {}
+              emit(prop === 'src' ? 'src-set' : 'srcobject-set', { src: prop === 'src' ? shortSrc(v) : '[stream]', muted: !!(this && this.muted) });
+              return origSet.call(this, v);
+            },
+          });
+        } catch (e) {}
+      }
+      // play()：静音期间**压制**且返回 resolved Promise（不排队——排队会在取消静音瞬间多声齐发）
+      try {
+        const origPlay = HME.play;
+        if (typeof origPlay === 'function' && !HME.__mpwBusPlay) {
+          HME.__mpwBusPlay = true;
+          HME.play = function () {
+            try {
+              if (state.muted && modeMutes(state.mode)) {
+                suppress(this);
+                emit('play-suppressed', { src: shortSrc(this && this.src), stack: stackOf() });
+                return win.Promise ? win.Promise.resolve() : undefined;   // 必须 resolved，否则调用方 await 卡住
+              }
+            } catch (e) {}
+            return origPlay.apply(this, arguments);
+          };
+        }
+      } catch (e) {}
+      // volumechange：静音下有人抬 volume/muted ⇒ 立刻归零 + 记栈
+      try {
+        if (!HME.__mpwBusVol) {
+          HME.__mpwBusVol = true;
+          const origAdd = HME.addEventListener;
+          if (typeof origAdd === 'function') {
+            const self = win;
+            origAdd.call(self.document || self, 'volumechange', (e) => {
+              const el = e && e.target;
+              if (!el || !state.muted || !modeMutes(state.mode)) return;
+              if (!el.muted || Number(el.volume) > 0) {
+                emit('volume-raised-while-muted', { muted: !!el.muted, volume: Number(el.volume), stack: stackOf() });
+                suppress(el);
+              }
+            }, true);
+          }
+        }
+      } catch (e) {}
+    }
+    // speechSynthesis（角色语音可能走它，完全不受 <audio>/Web Audio 控制）
+    try {
+      const ss = win.speechSynthesis;
+      if (ss && typeof ss.speak === 'function' && !ss.__mpwBusSpeech) {
+        const origSpeak = ss.speak.bind(ss);
+        ss.__mpwBusSpeech = true;
+        ss.speak = function (u) {
+          if (state.muted && modeMutes(state.mode)) { try { ss.cancel() } catch (e) {} ; emit('speech-suppressed', { text: String(u && u.text || '').slice(0, 60) }); return }
+          emit('speech', { text: String(u && u.text || '').slice(0, 60) });
+          return origSpeak(u);
+        };
+      }
+    } catch (e) {}
+    // WebRTC：outbound 的 track.enabled 是唯一能压它的开关
+    try {
+      const RTC = win.RTCPeerConnection;
+      if (typeof RTC === 'function' && !RTC.__mpwBusRtc) {
+        const Wrapped = function (...a) {
+          const pc = new RTC(...a);
+          try {
+            pc.addEventListener('track', (ev) => {
+              const tracks = (ev && ev.streams && ev.streams[0] && ev.streams[0].getTracks) ? ev.streams[0].getTracks() : [];
+              for (const t of tracks) { try { if (t.kind === 'audio' && state.muted && modeMutes(state.mode)) t.enabled = false } catch (e) {} }
+              emit('rtc-track', { n: tracks.length });
+            });
+          } catch (e) {}
+          return pc;
+        };
+        try { Wrapped.prototype = RTC.prototype } catch (e) {}
+        Wrapped.__mpwBusRtc = true;
+        win.RTCPeerConnection = Wrapped;
+      }
+    } catch (e) {}
+  };
+
+  const shortSrc = (s) => String(s || '').replace(/token=[^&]*/, 'token=…').slice(0, 120);
+
+  const registerMedia = (el) => {
+    if (!el || typeof el !== 'object') return false;
+    if (state.media.has(el)) return false;
+    state.media.add(el);
+    return true;
+  };
+  /** 收集媒体元素：document + **Shadow DOM**（querySelectorAll 抓不到 shadow root 里的）+ 同源 iframe。 */
+  const collectMedia = (doc, out) => {
+    try {
+      for (const el of doc.querySelectorAll('audio,video')) out.push(el);
+      for (const host of doc.querySelectorAll('*')) { if (host.shadowRoot) collectMedia(host.shadowRoot, out) }
+    } catch (e) {}
+    return out;
+  };
+  const allMedia = () => {
+    const out = [];
+    try { collectMedia(win.document, out) } catch (e) {}
+    for (const el of state.media) out.push(el);
+    if (typeof opts.mediaRoots === 'function') { try { for (const el of opts.mediaRoots() || []) out.push(el) } catch (e) {} }
+    return out;
+  };
+  /** 压一个媒体元素：**被 createMediaElementSource 接管的不要 pause**（analyser 要数据，暂停 = 频谱恒 0）。 */
+  const suppress = (el) => {
+    try { el.muted = true } catch (e) {}
+    try {
+      if (state.tappedMedia.has(el)) { /* 只总线归零，保留元素输出给 analyser */ }
+      else { el.volume = 0; if (typeof el.pause === 'function' && !el.paused) el.pause() }
+    } catch (e) {}
+  };
+
+  /* ── ④ 总线静音：只动我们自己的 masterGain（不 suspend：冻结 currentTime 会破坏调度/可视化） ── */
+  const applyMute = () => {
+    const mute = state.muted && modeMutes(state.mode);
+    /* 非静音档（off/report/redirect）**不碰 gain**：我们的 master 初值就是 1，没人会去改它；
+       反过来"每次都写 1"会盖掉第三方自己对 master 的调整，也会让 redirect 诊断档失去意义
+       （它要能回答"bus 到底收没收全"，而不是顺手改了音量）。只有**从静音恢复**那一次必须写回 1。 */
+    if (!mute && !state.wasMuted) return;
+    state.wasMuted = mute;
+    for (const ctx of state.adopted) {
+      const master = state.masters.get(ctx);
+      if (!master || !master.gain) continue;
+      try {
+        const t = ctx.currentTime;
+        if (master.gain.cancelScheduledValues) master.gain.cancelScheduledValues(t);
+        if (master.gain.setValueAtTime) master.gain.setValueAtTime(mute ? 0 : 1, t);
+        else master.gain.value = mute ? 0 : 1;
+      } catch (e) { try { master.gain.value = mute ? 0 : 1 } catch (e2) {} }
+    }
+    for (const el of allMedia()) { try { if (mute) suppress(el); else { el.muted = false } } catch (e) {} }
+    if (mute) { try { win.speechSynthesis && win.speechSynthesis.cancel && win.speechSynthesis.cancel() } catch (e) {} }
+    emit('apply-mute', { muted: state.muted, mode: state.mode, contexts: state.contexts.length, media: state.media.size });
+  };
+
+  /* ── ⑤ 跨域帧：压不动就**如实报不可控**；同源帧各装一遍（跨 realm） ── */
+  const syncFrames = () => {
+    state.uncontrollable = [];
+    let frames = [];
+    try { frames = Array.prototype.slice.call(win.document.querySelectorAll('iframe')) } catch (e) {}
+    state.frames = frames.map((f, i) => {
+      let sameOrigin = false, cw = null;
+      try { cw = f.contentWindow; sameOrigin = !!(cw && cw.document) } catch (e) { sameOrigin = false }
+      if (sameOrigin && cw) { try { installAudioBus(cw, { mode: state.mode, onEvent: opts.onEvent, mediaRoots: opts.mediaRoots }) } catch (e) {} }
+      else state.uncontrollable.push({ i, src: shortSrc(f.src || f.getAttribute && f.getAttribute('src')) });
+      return { i, sameOrigin, src: shortSrc(f.src || '') };
+    });
+    if (modeMutesAll(state.mode)) {
+      for (const f of frames) { try { f.contentWindow && f.contentWindow.postMessage({ type: BUS_MSG, muted: state.muted, mode: state.mode }, '*') } catch (e) {} }
+    }
+    return state.frames;
+  };
+
+  const api = {
+    __installed: true,
+    get mode() { return state.mode },
+    get muted() { return state.muted },
+    setMode(m) { state.mode = normalizeMode(m); applyMute(); emit('mode', { mode: state.mode }); return state.mode },
+    setMuted(v) {
+      state.muted = !!v;
+      syncFrames();
+      applyMute();
+      if (state.muted && modeMutes(state.mode)) {                 // "偶发" ⇒ 周期性重压（新节点/自动化都要压住）
+        if (!timer) timer = win.setInterval(() => { try { applyMute(); syncFrames() } catch (e) {} }, 750);
+      } else if (timer) { try { win.clearInterval(timer) } catch (e) {} ; timer = 0 }
+      return state.muted;
+    },
+    installFrame(cw, o) { return installAudioBus(cw, Object.assign({ mode: state.mode, onEvent: opts.onEvent }, o || {})) },
+    syncFrames,
+    /** 自上报快照（探针/diag 直接读它，**不需要用户操作**）。 */
+    report() {
+      return {
+        mode: state.mode, muted: state.muted, redirects: state.redirects,
+        contexts: state.contexts.map((c) => Object.assign({}, c, { ctx: undefined, adopted: state.masters.has(c.ctx), state: safeState(c.ctx) })),
+        masters: state.contexts.filter((c) => state.masters.has(c.ctx)).length,
+        media: allMedia().length, registered: state.media.size, tapped: countTapped(),
+        bypassSuspected: state.bypassSuspected.slice(0, 12),
+        uncontrollableFrames: state.uncontrollable.slice(0, 12),
+        frames: state.frames.slice(0, 12),
+        log: log.slice(-40),
+      };
+    },
+    log: () => log.slice(-100),
+    dispose() {
+      if (timer) { try { win.clearInterval(timer) } catch (e) {} ; timer = 0 }
+      for (const p of patched) { try { p.proto.connect = p.origConnect; p.proto.__mpwBusPatched = false } catch (e) {} }
+      try { delete win.__mpwAudioBus } catch (e) { win.__mpwAudioBus = null }
+    },
+  };
+  const safeState = (ctx) => { try { return ctx.state } catch (e) { return null } };
+  const countTapped = () => { let n = 0; for (const el of state.media) if (state.tappedMedia.has(el)) n++; return n };
+
+  patchCtor(win, 'AudioContext'); patchCtor(win, 'webkitAudioContext');
+  /* ④ `AudioNode.prototype` 每 realm 各装一遍（同源 iframe 的 prototype 与父页不是同一个）；
+     用 `AudioNode` 而不是 `AudioContext` —— 后者身上没有 connect。 */
+  if (!patchConnect(protoOf(win.AudioNode))) patchConnect(protoOf(win.AudioContext));
+  patchAttribution();
+  try { win.__mpwAudioBus = api } catch (e) {}
+  try {
+    const doc = win.document;
+    if (doc && doc.addEventListener) {
+      const onVis = () => { emit('visibility', { state: doc.visibilityState }); if (state.muted && modeMutes(state.mode)) applyMute() };
+      doc.addEventListener('visibilitychange', onVis, true);
+      win.addEventListener && win.addEventListener('pageshow', (e) => { emit('pageshow', { persisted: !!(e && e.persisted) }); if (state.muted && modeMutes(state.mode)) applyMute() }, true);
+      win.addEventListener && win.addEventListener('message', (e) => {          // 跨域帧配合时的入口
+        try { if (e && e.data && e.data.type === BUS_MSG) api.setMuted(!!e.data.muted) } catch (err) {}
+      }, false);
+    }
+  } catch (e) {}
+  emit('installed', { mode: state.mode });
+  return api;
+}

package/lib/client.js

@@ -1044,6 +1044,33 @@ function sectionSigNow() {
 		let mpwThumbDirSeen = null;     // 上一次算缓存键时的目录身份
 		let mpwThumbEpoch = 0;          // 缓存纪元（毫秒时间戳；换目录/显式失效即前进）
 		let mpwThumbInvalidations = 0;  // 纪元前进次数（诊断/门禁读数）
+		let mpwThumbContentSig = "";    // 当前目录的**内容身份**（扫描响应算出来的稳定串；同一个目录同一份清单恒等）
+		/** 目录内容签名（纯函数）：目录身份 + 文件清单（名字/类型/子路径/预览名/大小/时间戳，排序后拼接）。
+ *  为什么要有它：缓存纪元过去**每次扫描都前进**，而纪元进了 React 的 key ⇒ 11 个缩略图全部
+ *  重挂载、全部重发请求（真机读数：宿主串行解析容器，`/custom-mpkg-preview` 逐个 5.6s→11.8s
+ *  递增 ⇒ 预览框白十几秒、偶发落到类型占位）。判据"扫描 N 次结果一致"要求：同一份内容 ⇒ 同一个键。 */
+function mpwThumbContentSignature(dirId, files) {
+	try {
+		const rows = (Array.isArray(files) ? files : []).map((f) => [
+			String(f && f.name || ""), String(f && f.type || ""), String(f && f.media || ""),
+			String(f && f.preview || ""), String(f && f.size || ""), String(f && f.mtime || ""),
+		].join(":"));
+		rows.sort();   // 宿主给的文件顺序不参与身份（顺序变了不算内容变了）
+		return String(dirId || "") + "|" + rows.join(",");
+	} catch (e) { return String(dirId || "") + "|err" }
+}
+/** 扫描响应到达：内容**变了**才推进缓存纪元（换了 URL 键 ⇒ React 换新节点 + 浏览器重发请求）。
+ *  返回 {changed, epoch} 供诊断/探针读。诚实边界：宿主清单里没有内容指纹（同名文件被替换）
+ *  时这里判不出来 —— 那种情况用面板的「刷新壁纸」显式重来一次。 */
+function mpwThumbNoteContent(dirId, files, why) {
+	try {
+		const sig = mpwThumbContentSignature(dirId, files);
+		if (sig === mpwThumbContentSig) return { changed: false, epoch: mpwThumbEpoch, sig: sig };
+		mpwThumbContentSig = sig;
+		const ep = mpwThumbInvalidate(why || "content-changed");
+		return { changed: true, epoch: ep, sig: sig };
+	} catch (e) { return { changed: false, epoch: mpwThumbEpoch, err: String(e && e.message || e) } }
+}
 		/** 缩略图所属的**目录身份**：盘上目录（customDirPath）> 来源目录名 > mpkgKey 里的目录 > ltoken。 */
 		function mpwThumbDirIdentity(s) {
 			try {
@@ -1105,62 +1132,146 @@ function sectionSigNow() {
 			try { ph = box.querySelector ? box.querySelector("[data-mpw-thumb-ph]") : null } catch (e) { ph = null }
 			return { box: box, media: media, ph: ph };
 		}
-		/** 媒体可用（onLoad/新候选）：显示它、撤下**同框的其它媒体**与占位 —— 只碰 `hidden` 属性
-		 *  （React 也用它，两边语义一致）与 `display`（试用期隐藏的候选由我们自己管）。 */
-		function mpwThumbOk(el) {
-			try {
-				const p = mpwThumbParts(el);
-				if (!p) return false;
-				for (const m of p.media) {
-					const mine = m === el;
-					try { m.style.display = mine ? "" : "none" } catch (e) {}
-					try { m.setAttribute("data-mpw-thumb-state", mine ? "media" : "standby") } catch (e) {}
-					/* 只给**自己**记"试过了"：备胎（video）被顺手记成试过的话，
-					   图候选随后失败时它就不会被启用 —— 首帧兜底整条失效。 */
-					if (mine) {
-						try { m.setAttribute("data-mpw-thumb-tried", "1") } catch (e) {}
-						try { m.removeAttribute("data-mpw-thumb-failed") } catch (e) {}
-					}
-				}
-				if (p.ph) { try { p.ph.removeAttribute("data-mpw-thumb-shown") } catch (e) {}; try { p.ph.style.display = "" } catch (e) {} }
-				try { p.box.setAttribute("data-mpw-thumb-state", "media") } catch (e) {}
-				try { p.box.removeAttribute("data-mpw-thumb-why") } catch (e) {}
-				return true;
-			} catch (e) { return false }
+		/** 媒体"真的画出来了"没有（唯一判据；`onError` 之后 naturalWidth 会归零，天然自洽）。
+ *  video 要求 `readyState>=2`（HAVE_CURRENT_DATA）：只有元数据、还没解出帧的元素是**空白**的，
+ *  让它可见就会得到用户说的"白白一片"。 */
+function mpwThumbPainted(el) {
+	try {
+		if (!el) return false;
+		const tag = String(el.tagName || "").toUpperCase();
+		if (tag === "IMG") return !!(el.complete && (el.naturalWidth || 0) > 0);
+		if (tag === "VIDEO") return !!((el.readyState || 0) >= 2 && (el.videoWidth || 0) > 0);
+		return false;
+	} catch (e) { return false }
+}
+/** 候选优先级 = DOM 顺序（`<img>` 在前、视频首帧在后）。**前面的还没判死 ⇒ 后面的不许抢镜头**。
+ *  真机 bug：`<video>` 的 onLoadedMetadata 里无条件调 mpwThumbOk ⇒ 与 `<img>` 的 onLoad 抢，
+ *  同一档"多数时候是图、偶而是视频帧"，点一次「扫描该目录」就翻一次面（用户第 1 条）。 */
+function mpwThumbEarlierFailed(p, el) {
+	try {
+		for (const m of p.media) { if (m === el) return true; if (m.getAttribute("data-mpw-thumb-failed") !== "1") return false }
+		return true;
+	} catch (e) { return false }
+}
+/** 把"框底色"补上：媒体以 `contain` 呈现（**不裁切**，既有契约），留白过去露的是框底色
+ *  —— 浅色主题下就是白条（真机读数：容器自带的 192×192 预览放进 74×42 的框 ⇒ 左右各留
+ *  21.6% ≈ 用户说的"左右两边各约 1/5 是白块，只剩中间能预览"）。这里用**同一个媒体**做一层
+ *  模糊铺满的底（CSS `--mpw-thumb-cover` + `::before`），于是"不裁切"与"没有白边"同时成立，
+ *  而且底色与画面的来源是**同一个元素**（唯一事实源，不会出现两者不一致）。 */
+function mpwThumbCover(el, box) {
+	try {
+		if (!box || !box.style || !box.style.setProperty || !el) return false;
+		const tag = String(el.tagName || "").toUpperCase();
+		if (tag === "VIDEO") return mpwThumbCoverFromVideo(el, box);
+		const u = String(el.currentSrc || el.getAttribute("src") || "");
+		if (!u) return false;
+		box.style.setProperty("--mpw-thumb-cover", 'url("' + u.replace(/"/g, "%22") + '")');
+		return true;
+	} catch (e) { return false }
+}
+/** 视频的底色：`background-image: url(mp4)` 画不出画面 ⇒ 只在**画幅与框不一致**（contain 会留边）
+ *  时把当前帧画进一张 32×18 的小画布当底色。画不出来（跨源/未解码/被拒）就什么都不做 ——
+ *  诚实退化成"有留边"，绝不伪造一张假底色。同一张只画一次（`data-mpw-thumb-cover`）。 */
+function mpwThumbCoverFromVideo(video, box) {
+	try {
+		const vw = video.videoWidth || 0, vh = video.videoHeight || 0;
+		const bw = box.clientWidth || 0, bh = box.clientHeight || 0;
+		if (!(vw > 0) || !(vh > 0) || !(bw > 0) || !(bh > 0)) return false;
+		if (Math.abs((vw / vh) - (bw / bh)) <= 0.06) {   // 画幅与框基本一致 ⇒ contain 已经铺满，不必画
+			try { box.style.removeProperty("--mpw-thumb-cover") } catch (e) {}
+			return true;
 		}
-		/** 某个媒体元素**这一条用不了**（候选耗尽/加载失败）：撤下它，然后按候选链的**优先级顺序**
-		 *  启用下一个还没试过的媒体（典型：先试目录内 `preview.*` 的 `<img>`，全失败后启用
-		 *  `<video>` 首帧），一个都没有了才露出占位。唯一落点 —— 任何分支都不许自己 `display=""`。 */
-		function mpwThumbFail(el, why) {
-			try {
-				const p = mpwThumbParts(el);
-				if (!p) return false;
-				try { el.style.display = "none" } catch (e) {}
-				try { el.setAttribute("data-mpw-thumb-state", "failed") } catch (e) {}
-				try { el.setAttribute("data-mpw-thumb-failed", "1") } catch (e) {}
-				try { el.setAttribute("data-mpw-thumb-tried", "1") } catch (e) {}
-				// 还有没试过的候选元素（video）⇒ 启用它，占位**继续藏着**（不露出中间态）
-				for (const m of p.media) {
-					if (m === el || !m) continue;
-					if (m.getAttribute && m.getAttribute("data-mpw-thumb-tried") === "1") continue;
-					const src = (m.getAttribute && (m.getAttribute("src") || "")) || "";
-					if (!src) continue;
-					try { m.style.display = "" } catch (e) {}
-					try { m.setAttribute("data-mpw-thumb-state", "trying") } catch (e) {}
-					try { p.box.setAttribute("data-mpw-thumb-state", "trying") } catch (e) {}
-					try { p.box.setAttribute("data-mpw-thumb-why", String(why || "").slice(0, 80)) } catch (e) {}
-					return true;
-				}
-				if (p.ph) {
-					try { p.ph.setAttribute("data-mpw-thumb-shown", "") } catch (e) {}
-					try { p.ph.style.display = "" } catch (e) {}
-					try { p.ph.setAttribute("data-mpw-thumb-state", "placeholder") } catch (e) {}
-				}
-				try { p.box.setAttribute("data-mpw-thumb-state", "placeholder") } catch (e) {}
-				try { p.box.setAttribute("data-mpw-thumb-why", String(why || "").slice(0, 80)) } catch (e) {}
-				return true;
-			} catch (e) { return false }
+		if (box.getAttribute("data-mpw-thumb-cover") === "1") return true;
+		const c = document.createElement("canvas"); c.width = 32; c.height = 18;
+		const ctx = c.getContext && c.getContext("2d");
+		if (!ctx) return false;
+		ctx.drawImage(video, 0, 0, 32, 18);
+		const url = c.toDataURL("image/jpeg", 0.5);
+		if (!url || url.length < 32) return false;
+		box.style.setProperty("--mpw-thumb-cover", 'url("' + url + '")');
+		box.setAttribute("data-mpw-thumb-cover", "1");
+		return true;
+	} catch (e) { return false }
+}
+/** **唯一落点**：把整个框的显隐按"候选优先级 + 真的画出来了"重新推导一遍。
+ *  三个不变量（判据见 tools/thumb-chain-test.mjs B 组与 tools/scan-switch-live-probe.mjs T1/T2）：
+ *   ① 同框**至多一个可见**：主人 = 第一个"已画出来 + 前面的候选都判死"的媒体；其余一律 display:none；
+ *   ② **可见即有画面**：显示只由这里写，而这里只挑"画出来了"的元素 ⇒ 不存在"可见但空白"的中间态
+ *      （旧写法在换候选时先把还没加载完的 `<img>` 显示出来 ⇒ 真机"一块白底"）；
+ *   ③ 占位只在**一个都没画出来、且没有还没试过的候选**时整块露出（状态机之外的任何地方都不许写它）。
+ *  事件（onLoad/onError/onLoadedMetadata/onLoadedData）只负责**触发**它，自己不写显隐。 */
+function mpwThumbSync(p, why) {
+	try {
+		if (!p) return false;
+		let owner = null;
+		for (const m of p.media) {
+			if (m.getAttribute("data-mpw-thumb-failed") === "1") continue;
+			if (!mpwThumbEarlierFailed(p, m)) continue;
+			if (!mpwThumbPainted(m)) continue;
+			owner = m; break;
+		}
+		for (const m of p.media) {
+			const mine = m === owner;
+			try { m.style.display = mine ? "" : "none" } catch (e) {}
+			const st = mine ? "media" : (m.getAttribute("data-mpw-thumb-failed") === "1" ? "failed" : "trying");
+			try { m.setAttribute("data-mpw-thumb-state", st) } catch (e) {}
+			if (mine) { try { m.setAttribute("data-mpw-thumb-tried", "1") } catch (e) {} }
+		}
+		if (owner) {
+			if (p.ph) { try { p.ph.removeAttribute("data-mpw-thumb-shown") } catch (e) {}; try { p.ph.style.display = "" } catch (e) {} }
+			try { p.box.setAttribute("data-mpw-thumb-state", "media") } catch (e) {}
+			try { p.box.removeAttribute("data-mpw-thumb-why") } catch (e) {}
+			mpwThumbCover(owner, p.box);
+			return true;
+		}
+		/* 没有画面：还有"没试过且带 src"的候选就继续等（框交给 CSS 的加载态，不露类型文字）；
+		   一个都不剩才露占位 —— 占位的两个属性仍然只在这一个函数里写。 */
+		const untried = p.media.some((m) => m.getAttribute("data-mpw-thumb-tried") !== "1" && String(m.getAttribute("src") || ""));
+		if (untried) {
+			if (p.ph) { try { p.ph.removeAttribute("data-mpw-thumb-shown") } catch (e) {}; try { p.ph.style.display = "" } catch (e) {} }
+			try { p.box.setAttribute("data-mpw-thumb-state", "trying") } catch (e) {}
+			if (why) { try { p.box.setAttribute("data-mpw-thumb-why", String(why).slice(0, 80)) } catch (e) {} }
+			return false;
+		}
+		if (p.ph) {
+			try { p.ph.setAttribute("data-mpw-thumb-shown", "") } catch (e) {}
+			try { p.ph.style.display = "" } catch (e) {}
+			try { p.ph.setAttribute("data-mpw-thumb-state", "placeholder") } catch (e) {}
 		}
+		try { p.box.setAttribute("data-mpw-thumb-state", "placeholder") } catch (e) {}
+		if (why) { try { p.box.setAttribute("data-mpw-thumb-why", String(why).slice(0, 80)) } catch (e) {} }
+		return false;
+	} catch (e) { return false }
+}
+/** 媒体可用（`onLoad` / `onLoadedMetadata` / `onLoadedData` / `onSeeked`）：只是**触发一次重推导** ——
+ *  真正的裁决在 mpwThumbSync 里（"画出来了没有 + 优先级"）。事件本身不再写显隐，这就是
+ *  "谁最后跑谁说了算"那个竞态的根除点。
+ *  ①(2026-09-21 真机) **入参既认元素也认事件**：挂成 `onLoad: mpwThumbOk` 时 React 交下来的是
+ *  **事件对象**，旧实现直接拿它当元素用 ⇒ `parentElement` 为 undefined ⇒ 永远返回 false ——
+ *  也就是说 `<img>` 的 onLoad **从来没有生效过**（真机读数：图的 naturalWidth 早已是 192，
+ *  框里却是视频首帧/空白，只能靠视频那条 `onLoadedMetadata: ev => mpwThumbOk(ev.target)` 救场）。
+ *  这个坑正是"多数时候正常、点一下扫描就白一块"的另一半根因：唯一能画的是慢半拍的视频。 */
+function mpwThumbOk(el) {
+	try {
+		const target = (el && el.target) ? el.target : el;
+		const p = mpwThumbParts(target);
+		if (!p) return false;
+		return mpwThumbSync(p, "");
+	} catch (e) { return false }
+}
+/** 某个媒体元素**这一条用不了**（候选耗尽 / 加载失败 / 请求被取消）：判死它，然后重推导 ——
+ *  下一个候选（视频首帧）只有在"前面的候选都判死"之后才可能被选中，占位则要等到一个都不剩。 */
+function mpwThumbFail(el, why) {
+	try {
+		const p = mpwThumbParts(el);
+		if (!p) return false;
+		try { el.style.display = "none" } catch (e) {}
+		try { el.setAttribute("data-mpw-thumb-failed", "1") } catch (e) {}
+		try { el.setAttribute("data-mpw-thumb-tried", "1") } catch (e) {}
+		try { el.setAttribute("data-mpw-thumb-state", "failed") } catch (e) {}
+		return mpwThumbSync(p, why || "chain-exhausted");
+	} catch (e) { return false }
+}
 		/** 候选链载荷：一次 JSON 写清 `{urls,i}`（**一个属性**，换目录时 URL 与下标一起重置，
 		    不会出现"URL 换了、下标还停在上一次的 3"这种跳过候选的中间态）。
 		    兼容旧的 `data-mpw-thumb-list` 数组 + `data-mpw-thumb-idx` 两属性写法（旧产物/夹具）。 */
@@ -1178,6 +1289,14 @@ function sectionSigNow() {
 		function mpwThumbPayloadSet(el, urls, i) {
 			try { el.setAttribute("data-mpw-thumb-list", JSON.stringify({ urls: urls, i: i })) } catch (e) {}
 		}
+		/** 这个候选源是不是**容器文件**（`.mpkg`/`.pkg`）：URL 或文件名里出现容器扩展名即为真。
+		 *  纯函数，门禁可直接断言（tools/thumb-chain-test.mjs B7）。 */
+		function mpwThumbIsContainerUrl(u, name) {
+			try {
+				const all = String(u || "") + " " + String(name || "");
+				return /\.(mpkg|pkg)([?#"'\s]|$)/i.test(all);
+			} catch (e) { return false }
+		}
 		/** 预览候选链（**顺序即优先级**，2026-09-21 定案）：
 		     ① 扫描器**明确**找到的目录内预览图（`section.preview`，如 video 档旁边的 `preview.gif`）；
 		     ② 容器内 preview.*（mpkg 容器档，服务端解容器；既有行为，容器档第一位）；
@@ -1230,34 +1349,47 @@ function sectionSigNow() {
 						push("img", "dir-preview-convention", host + dirRef.base + encodeURIComponent(dirRef.id) + "/" + name);
 					}
 				}
-				// ④ 视频首帧（浏览器原生抽帧，零依赖）/ ⑤ 图片
-				if (img) {
+							// ④ 视频首帧（浏览器原生抽帧，零依赖）/ ⑤ 图片
+				/* ①(2026-09-21 真机)"候选的 kind 跟着**源文件类型**走"：`.mpkg/.pkg` 是**容器**，
+				   不是媒体流。把它交给 `<video>` 只会让浏览器去拉几百 MB 字节然后报
+				   "Content-Type not supported"（真机读数：`/custom-media` 206 ×20，文件 130MB~830MB；
+				   这些无谓请求还会**占满宿主的连接与解析**，把真正要用的容器预览挤到 5.6s→11.8s）。
+				   容器档的"首帧"本来就有正道：② 的容器内预览图。 */
+				const containerSrc = mpwThumbIsContainerUrl(img, srcName);
+				if (img && !containerSrc) {
 					if (converted === "mp4" || /\.(mp4|webm|mkv|mov|m4v)$/i.test(srcName)) push("video", "video-first-frame", resolveHostUrl(img));
 					else push("img", "image", resolveHostUrl(img));
 				}
 			} catch (e) {}
 			return out;
 		}
-		/** 预览候选链的推进器（挂在 <img>/<video> 的 onError 上）：下一个候选 / 耗尽则显示占位。
-		 *  状态存在**元素自己身上**（`data-mpw-thumb-list` 的 `{urls,i}`），与 React 重渲染无冲突。 */
+		/** 预览候选链的推进器（挂在 <img>/<video> 的 onError 上）：下一个候选 / 耗尽则落占位。
+		 *  状态存在**元素自己身上**（`data-mpw-thumb-list` 的 `{urls,i}`），与 React 重渲染无冲突。
+		 *  ①(2026-09-21 真机) 换源那一瞬间元素**必然空掉**（浏览器换了 src 就不再有画面）⇒ 先把它收起来
+		 *  再继续试下一个候选；框的显隐一律交给 mpwThumbSync 推导（旧写法在这里调 mpwThumbOk 把
+		 *  还没加载完的元素显示出来 ⇒ 真机"一块白底"就是这么来的）。 */
 		function mpwThumbNext(ev) {
 			try {
-				const el = ev && ev.target;
+				const el = (ev && ev.target) ? ev.target : ev;   // 事件或元素都认（与 mpwThumbOk 同一口径）
 				if (!el || !el.getAttribute) return;
-				const p = mpwThumbPayloadGet(el);
-				const list = p.urls;
-				let i = p.i + 1;
+				const p = mpwThumbParts(el);
+				const payload = mpwThumbPayloadGet(el);
+				const list = payload.urls;
+				let i = payload.i + 1;
+				try { el.style.display = "none" } catch (e) {}
+				try { el.removeAttribute("data-mpw-thumb-failed") } catch (e) {}
+				try { el.setAttribute("data-mpw-thumb-state", "trying") } catch (e) {}
 				while (i < list.length) {
 					if (list[i]) {
 						mpwThumbPayloadSet(el, list, i);
 						try { el.setAttribute("src", list[i]) } catch (e) {}
-						mpwThumbOk(el);            // 换候选期间不出占位
+						mpwThumbSync(p, "trying:next-candidate");
 						return;
 					}
 					i++;
 				}
 				try { el.setAttribute("data-mpw-thumb-failed", "1") } catch (e) {}
-				mpwThumbFail(el, "chain-exhausted");   // 隐藏媒体 + 露出占位（整块，不并排）
+				mpwThumbFail(el, "chain-exhausted");
 			} catch (e) {}
 		}
 		/** 预览框的子元素**唯一构造点**（设置里"当前壁纸"、自定义目录列表、本地库列表共用一套）：
@@ -1275,20 +1407,32 @@ function sectionSigNow() {
 			const imgs = cands.filter((c) => c.kind !== "video").map((c) => c.src);
 			const vids = cands.filter((c) => c.kind === "video").map((c) => c.src);
 			const out = [];
+			/* ①(2026-09-21 真机) **媒体一律"先藏着"**：显示只由 mpwThumbSync 在"真的画出来了"那一刻写。
+			   旧写法把 `<img>` 的 display 留空 ⇒ 元素一挂上就可见、而画面还没到 ⇒ 用户看到"一块白底"。
+			   `data-mpw-thumb-standby` 保留为**可读标记**（"这是还没轮到它的备胎"），裁决仍看优先级。 */
 			if (imgs.length) {
-				out.push(h("img", { key: keyBase + "|img", className: "mpw_thumbImg", src: imgs[0], alt: "", loading: "lazy", decoding: "async",
+				/* ①(2026-09-21 真机)**不许用 `loading="lazy"`**：真机读数 —— 元素被我们"先藏着"
+				   （display:none）时，Firefox 的惰性加载**永远不发出请求**（`/custom-mpkg-preview`
+				   在整轮里 0 次），于是图既不出画也不报错，而候选优先级又挡着视频首帧
+				   ⇒ 框永远停在加载态。改为即时加载（预览图都很小；真正的大请求是容器字节那条，
+				   已被"容器不给 video 候选"堵掉）。 */
+				out.push(h("img", { key: keyBase + "|img", className: "mpw_thumbImg", src: imgs[0], alt: "", decoding: "async",
+					style: { display: "none" },
 					"data-mpw-thumb-list": JSON.stringify({ urls: imgs, i: 0 }),
 					onLoad: mpwThumbOk, onError: mpwThumbNext }));
 			}
 			if (vids.length) {
 				out.push(h("video", { key: keyBase + "|video", className: "mpw_thumbImg", src: vids[0], muted: true, playsInline: true, preload: "metadata",
-					style: imgs.length ? { display: "none" } : void 0,
+					style: { display: "none" },
 					"data-mpw-thumb-list": JSON.stringify({ urls: vids, i: 0 }),
 					"data-mpw-thumb-standby": imgs.length ? "1" : void 0,
+					/* 元数据到 ⇒ 定到 0.05s 抽首帧；**帧真的到了**（loadeddata/seeked，readyState≥2）才可能被
+					   选中 —— 只有元数据时元素是空白的，让它可见就又是一块白底（判据 T2）。 */
 					onLoadedMetadata: (ev) => {
 						try { const v = ev.target; if (v.duration && v.duration > 0.1) v.currentTime = 0.05 } catch (e) {}
 						mpwThumbOk(ev.target);
 					},
+					onLoadedData: mpwThumbOk, onSeeked: mpwThumbOk,
 					onError: mpwThumbNext }));
 			}
 			out.push(h("span", { key: keyBase + "|ph", className: "mpw_hint", style: { margin: 0 }, "data-mpw-thumb-ph": "",
@@ -5292,9 +5436,10 @@ function sectionSigNow() {
 		   这里再加一道有界兜底：apply 后 1.2s 复核一次，若"有源但没挂上"→ 补挂一次 + 一行 console.warn
 		   + 计数 `window.__mpwBgSrcHeal`（同一内容签名只补一次，绝不循环）。
 		   `?bgwrapfix=legacy` 时整段跳过（回退到改动前：不校验、只靠调用方）。 */
-		let __mpwBgHeal = { sig: "", tries: 0 };
+		let __mpwBgHeal = { sig: "", tries: 0, slowTries: 0 };
 		let __mpwBgHealTimer = 0;
-		/** 当前壁纸源对应的媒体是否真的挂上了（按 converted/webUrl 分派，与 show*El 的落点一致）。 */
+		let __mpwBgHealSlowTimer = 0;
+		/** 当前壁纸源对应的媒体**有没有挂上 src**（按 converted/webUrl 分派，与 show*El 的落点一致）。 */
 		function mpwBgArmedNow(section) {
 			try {
 				const { img, video, frame, canvas, wrap } = bgElements();
@@ -5307,37 +5452,95 @@ function sectionSigNow() {
 				return !!(img && (img.getAttribute("src") || img.currentSrc));
 			} catch { return true } // 判定本身出错时**不补挂**（宁可不动，也不制造抖动）
 		}
+		/* ①(2026-09-21 真机)"有 src" ≠ "画出来了"（用户原话"壁纸是白色的，什么都没有"）：
+		   宿主被容器解析占满时（真机读数：10 个缩略图的 `/custom-mpkg-preview` 串行放大到
+		   5.6s→11.8s），壁纸自己的 `<video>` 会长时间停在 readyState 0 / videoWidth 0 —— 层是可见的、
+		   里面却没有画面；而之后**任何**一次 re-apply（设置同步 / 卡片交互 / 重新选一次）都会把它
+		   重新武装 ⇒ 用户以为"点一下 Now Playing 就好了"。所以补挂校验分两档：
+		     · 快判（1.2s）：有源但**没有 src** ⇒ 立刻补挂（既有行为）；
+		     · 慢判（12s）：有 src 但**一直没有画面** ⇒ 强制重挂一次（同签名只做一次）。
+		   诚实边界：转码档（host 正在转）不判死 —— 它有自己的超时回退（见 showVideoEl 后面的
+		   `__mpwTransLoadingTimeout`），在后面推它只会把转码重来一遍。 */
+		function mpwBgPaintedNow(section) {
+			try {
+				const { img, video, canvas, wrap } = bgElements();
+				if (!wrap) return true;
+				if (section.webUrl) return true;                       // 帧内画面看不见，不越权判死
+				if (section.converted === "scene" && section.sceneKey) return !!(canvas && (canvas.width || 0) > 0);
+				if (section.converted === "mp4") {
+					if (!video) return true;
+					let st = "";
+					try { st = String(video.getAttribute("data-mpw-wp-state") || (window.__mpwWallpaperState && window.__mpwWallpaperState.state) || "") } catch {}
+					if (st === "transcode") return true;               // 转码中：交给它自己的超时回退
+					/* 用户自己按了暂停 / 省电暂停 / 页面在后台 ⇒ 元素**本来就不该出画面**，
+					   这时"没画面"是正常的：不许补（补了会打断用户的暂停，也会白丢已缓冲的数据）。 */
+					try { if (wallUserPaused || powPaused) return true } catch (e) {}
+					try { if (typeof document !== "undefined" && document && document.hidden) return true } catch (e) {}
+					const rs = Number(video.readyState || 0);
+					const vw = Number(video.videoWidth || 0);
+					if (!(video.getAttribute("src") || video.currentSrc)) return true;  // 没 src 属于"快判"那一档
+					return rs >= 2 && vw > 0;
+				}
+				if (!img) return true;
+				if (!(img.getAttribute("src") || img.currentSrc)) return true;
+				return !!(img.complete && (img.naturalWidth || 0) > 0);
+			} catch { return true }
+		}
 		function mpwBgSrcHealSchedule() {
 			if (!mpwBgWrapFixOn()) return;
-			if (__mpwBgHealTimer) return; // 已有待复核（apply 很频繁，只留一个）
+			// 已有待复核（apply 很频繁，只留一个）—— 两档各留一个
 			try {
-				__mpwBgHealTimer = setTimeout(() => {
-					__mpwBgHealTimer = 0;
-					try { mpwBgSrcHealCheck(); } catch (e) { mpwErr("壁纸源补挂校验", e) }
-				}, 1200);
+				if (!__mpwBgHealTimer) {
+					__mpwBgHealTimer = setTimeout(() => {
+						__mpwBgHealTimer = 0;
+						try { mpwBgSrcHealCheck("fast") } catch (e) { mpwErr("壁纸源补挂校验", e) }
+					}, 1200);
+				}
+			} catch {}
+			try {
+				if (!__mpwBgHealSlowTimer) {
+					__mpwBgHealSlowTimer = setTimeout(() => {
+						__mpwBgHealSlowTimer = 0;
+						try { mpwBgSrcHealCheck("slow") } catch (e) { mpwErr("壁纸源补画校验", e) }
+					}, 12000);
+				}
 			} catch {}
 		}
-		function mpwBgSrcHealCheck() {
+		function mpwBgSrcHealCheck(phase) {
+			const fast = phase !== "slow";
 			const s = normalizeSection(readSection());
 			if (!(s.enabled !== void 0 ? !!s.enabled : DEFAULT_ENABLED)) return; // 总开关关：不挂是对的
 			if (!(s.image || s.webUrl)) return;                                   // 无源：不挂是对的（正常语义）
 			const sig = sectionSigNow();
-			if (__mpwBgHeal.sig !== sig) __mpwBgHeal = { sig, tries: 0 };
-			if (mpwBgArmedNow(s)) return;
-			if (__mpwBgHeal.tries >= 1) {
-				// 补挂过一次仍没挂上 → 只报一次，不再重试（避免抖动/循环）
+			if (__mpwBgHeal.sig !== sig) __mpwBgHeal = { sig, tries: 0, slowTries: 0 };
+			const bad = fast ? !mpwBgArmedNow(s) : !mpwBgPaintedNow(s);
+			if (!bad) return;
+			const used = fast ? __mpwBgHeal.tries : __mpwBgHeal.slowTries;
+			if (used >= 1) {
+				// 补过一次仍没到位 → 只报一次，不再重试（避免抖动/循环）
 				if (__mpwBgHeal.warned !== true) {
 					__mpwBgHeal.warned = true;
-					console.warn("[dsh-mpkg-wallpaper] 有壁纸源但补挂仍未生效（媒体元素没有 src）:", sig.slice(0, 80));
+					console.warn("[dsh-mpkg-wallpaper] 有壁纸源但补" + (fast ? "挂" : "画") + "仍未生效:",
+						fast ? "（媒体元素没有 src）" : "（有 src 但一直没有画面）", sig.slice(0, 80));
 				}
 				return;
 			}
-			__mpwBgHeal.tries++;
+			if (fast) __mpwBgHeal.tries++; else __mpwBgHeal.slowTries++;
 			try { window.__mpwBgSrcHeal = ((window.__mpwBgSrcHeal || 0) + 1) } catch {}
-			console.warn("[dsh-mpkg-wallpaper] 检测到有壁纸源但媒体未挂上 → 补挂一次:", sig.slice(0, 80));
+			console.warn("[dsh-mpkg-wallpaper] 检测到有壁纸源但" + (fast ? "媒体未挂上" : "一直没有画面") + " → 补一次:", sig.slice(0, 80));
+			if (!fast) {
+				/* 慢判要**强制重挂**：showVideoEl 有"src 相同就不重设"的守卫（那是有意的，防止
+				   无关设置把播放打断），所以只调 applyFromStorageInner 对"卡住的那一次加载"没用 ——
+				   必须显式把同一个 URL 重新 load 一遍。有界：同签名只做一次。 */
+				try {
+					const v = bgElements().video;
+					const cur = v ? String(v.getAttribute("src") || v.currentSrc || "") : "";
+					if (v && cur) { try { v.pause() } catch (e) {}; v.removeAttribute("src"); v.src = cur; if (v.load) v.load(); }
+				} catch (e) {}
+			}
 			try { applyFromStorageInner() } catch (e) { mpwErr("壁纸源补挂", e) }
 		}
-		try { window.__mpwBgWrapState = () => ({ fixOn: mpwBgWrapFixOn(), heal: (() => { try { return window.__mpwBgSrcHeal || 0 } catch { return -1 } })(), last: __mpwBgHeal }) } catch {}
+		try { window.__mpwBgWrapState = () => ({ fixOn: mpwBgWrapFixOn(), heal: (() => { try { return window.__mpwBgSrcHeal || 0 } catch { return -1 } })(), last: __mpwBgHeal, paintedNow: (() => { try { return mpwBgPaintedNow(normalizeSection(readSection())) } catch { return null } })() }) } catch {}
 		/* ═══ ①(2026-09-16 根治) 设置归一化：**必须是模块级函数** ═══
 		   历史 bug（"标题栏磨砂一直没有效果"的真根因，真机 diag 实锤）：
 		     `__asStr` / `normalizeSection` 原本定义在 `applyFromStorageInner()` **函数体内**
@@ -9615,7 +9818,15 @@ function sectionSigNow() {
 				thumbParts: (el) => { try { const p = mpwThumbParts(el); return p ? { box: p.box, media: p.media, ph: p.ph } : null } catch (e) { return null } },
 				thumbIdentity: (s) => { try { return mpwThumbDirIdentity(s || readSection()) } catch (e) { return "" } },
 				thumbBust: (url, s) => { try { return mpwThumbBust(url, s || readSection()) } catch (e) { return String(e && e.message || e) } },
-				thumbEpoch: () => { try { return { epoch: mpwThumbEpoch, dir: mpwThumbDirSeen, n: mpwThumbInvalidations } } catch (e) { return null } },
+				thumbEpoch: () => { try { return { epoch: mpwThumbEpoch, dir: mpwThumbDirSeen, n: mpwThumbInvalidations, sig: mpwThumbContentSig } } catch (e) { return null } },
+				thumbNoteContent: (dirId, files, why) => { try { return mpwThumbNoteContent(dirId, files, why) } catch (e) { return { err: String(e && e.message || e) } } },
+				thumbContentSig: (dirId, files) => { try { return mpwThumbContentSignature(dirId, files) } catch (e) { return "" } },
+				thumbSync: (el, why) => { try { const p = mpwThumbParts(el); return p ? mpwThumbSync(p, why || "test") : false } catch (e) { return String(e && e.message || e) } },
+				thumbPainted: (el) => { try { return mpwThumbPainted(el) } catch (e) { return null } },
+				thumbContainerUrl: (u, name) => { try { return mpwThumbIsContainerUrl(u, name) } catch (e) { return null } },
+				bgPaintedNow: (sec) => { try { return mpwBgPaintedNow(normalizeSection(sec || readSection())) } catch (e) { return null } },
+				bgArmedNow: (sec) => { try { return mpwBgArmedNow(normalizeSection(sec || readSection())) } catch (e) { return null } },
+				bgHealCheck: (phase) => { try { mpwBgSrcHealCheck(phase || "slow"); return true } catch (e) { return String(e && e.message || e) } },
 				thumbInvalidate: (why) => { try { return mpwThumbInvalidate(why || "test") } catch (e) { return -1 } },
 				// ⑥ 弹层类污染
 				syncLayerHosts: () => { try { return mpwSyncLayerHosts() } catch (e) { return { error: String(e && e.message || e) } } },
@@ -10512,10 +10723,19 @@ const barTop = (p) => mix(SHUT - PAD - RAIL_H, RAIL_Y, p);
 /** 轨道的左右端点（一个 margin，所以两端永不移动）。 */
 const barLeft = () => PAD;
 const barWidth = () => W - PAD * 2;
-/** 播放进度百分比（0..TOTAL 的时钟 → 0..100）。 */
-const runPct = (at) => (clamp(at, 0, TOTAL) / TOTAL) * 100;
-/** 剩余时间（负号由组件加，保证两段数字等宽）。 */
-const remain = (at) => TOTAL - clamp(at, 0, TOTAL);
+/** 时间轴（**唯一事实源**）：当前媒体的时长。缺省/非法值才退回上游演示常量 `TOTAL`。
+ *
+ *  为什么必须带参（2026-09-21 真机）：卡片的"−剩余"与进度条填充过去无条件用 `TOTAL`（214 = 上游
+ *  演示里那首曲子的秒数）。真实媒体 100.05s（1:40）时：卡片写 `−3:29`、条子播到结尾也只画到
+ *  47%（100/214）⇒ 用户看到的正是「1 分 40 秒读成 3 分 30 多秒」+「点一下只跳到整条的一半」。
+ *  3.11.0 修的是**数据目标**（npMediaTarget：位置/时长/seek 落到同一个元素），
+ *  但**显示轴**还是这个常量 —— 于是"数据对、显示错"能长期共存。这条口径与数据面同源：
+ *  显示用的时长 == `npResolveMedia()` 送进控制器的 `media.total` == 媒体元素自己的 duration。 */
+const axisOf = (total) => (typeof total === "number" && isFinite(total) && total > 0 ? total : TOTAL);
+/** 播放进度百分比（0..`total` 的时钟 → 0..100）。`total` 省略 = 上游演示常量（演示/纯几何测试用）。 */
+const runPct = (at, total) => (clamp(at, 0, axisOf(total)) / axisOf(total)) * 100;
+/** 剩余时间（负号由组件加，保证两段数字等宽）。同样以 `total` 为准（唯一事实源）。 */
+const remain = (at, total) => axisOf(total) - clamp(at, 0, axisOf(total));
 
 /* ── the one thing you press to change shape ───────
    Invisible, and it is the WHOLE bar when shut — the
@@ -10561,7 +10781,7 @@ module.exports = {
   /* 两个八点四边形 */
   PAUSE_L, PLAY_L, PAUSE_R, PLAY_R, quad,
   /* 时间 */
-  clock, tickClock,
+  clock, tickClock, axisOf,
   /* 端点/派生形状 */
   durationOf, artRadius, cornerOffset, boxRadius,
   swellOf, zoomOf, gooOf, gooPull, gooTip, gooScale,
@@ -11324,7 +11544,12 @@ function createNowPlaying(deps) {
     const going = !!q.playing;
     const media = q.media || {};
     const known = typeof media.total === "number" && media.total > 0;
-    const at = Math.max(0, Math.min(known ? media.total : M.TOTAL, Number(q.at) || 0));
+    /* 时间轴 = **当前媒体的时长**（唯一事实源；`known` 为假才退回上游演示常量）。
+       夹取、进度条填充、"−剩余"三处**共用这一个值** —— 任何一处各自用常量，就会出现
+       "数据对、显示错"（真机：100.05s 的媒体被画成 214s 的轴）。判据见
+       tools/np-axis-live-probe.mjs（真机）与 tools/np-control-test.mjs 的 X 组（无浏览器）。 */
+    const axis = M.axisOf(known ? media.total : null);
+    const at = Math.max(0, Math.min(axis, Number(q.at) || 0));
 
     const art = M.artSize(p);
     const artR = M.artRadius(M.CORNER);
@@ -11372,7 +11597,7 @@ function createNowPlaying(deps) {
           h("span", { className: "mpw_np_rail" },
             h("span", {
               className: "mpw_np_run",
-              style: { width: (known ? M.runPct(at) : 0) + "%" },
+              style: { width: (known ? M.runPct(at, axis) : 0) + "%" },
             })),
           /* ①(NP-4)③ 进度条可拖动：命中带绝对定位在 bar 上（**不进**那一列的 flex 流），
              所以时钟与轨道的布局一个像素都不动。轨道只有 3px，命中带上下各补 NP_SCRUB_PAD。
@@ -11429,7 +11654,7 @@ function createNowPlaying(deps) {
                 h("span", { className: "mpw_np_volRun", style: { width: (vol * 100) + "%" } }),
                 h("span", { className: "mpw_np_volKnob", style: { left: (vol * 100) + "%" } }))) : null,
             /* 数据源没有时长时**不假装**：显示 --:--（见 docs/NOW-PLAYING-DSH.md §4 情形②） */
-            h("span", null, known ? ("−" + M.clock(M.remain(at))) : "--:--"))),
+            h("span", null, known ? ("−" + M.clock(M.remain(at, axis))) : "--:--"))),
         h("button", {
           className: "mpw_np_tap", type: "button",
           onClick: () => { if (q.onToggle) q.onToggle(); },
@@ -12256,6 +12481,9 @@ function createNowPlaying(deps) {
   }
 
   return {
+    /* ①(2026-09-21) 纯渲染函数也对外：**显示面**（进度条填充宽度、"−剩余"文本）要能在
+       无浏览器门禁里对着产出的元素树断言 —— 只测控制器状态测不到"数据对、显示错"
+       （真机 bug：媒体 100.05s，卡片按上游常量 214 画）。判据：tools/np-control-test.mjs 的 X 组。 */
     NowPlaying, PlayMark, createController, createSlotAction, shouldHide, resolveAnchor, sidebarRoot, sidebarCol, occupantOf,
   };
 }
@@ -14244,8 +14472,28 @@ body[data-ds-dark-theme] .mpw_tabBar {
    媒体脱离文档流铺满整框 + object-fit:contain（宁可留边，绝不切图）；占位同层居中。
    旧写法是 flex 行 + object-fit:cover：占位一露出来就把 100% 宽的图压到 3/4，
    右侧 1/4 变成白块（真机读数）——现在两者重叠而非并排，且由状态机保证只露一个。 */
-.mpw_wallThumb .mpw_thumbImg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; display: block; }
-.mpw_thumbImg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; display: block; }
+.mpw_wallThumb .mpw_thumbImg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; display: block; z-index: 1; }
+.mpw_thumbImg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; display: block; z-index: 1; }
+/* ①(2026-09-21 真机)"留白露框底色"的修法：媒体以 contain 呈现（**不裁切**，既有契约），
+   留白由**同一张图**的模糊铺满层兜底 —— --mpw-thumb-cover 由状态机在"媒体真的画出来"那一刻
+   写成（唯一事实源，与画面同一个元素）。真机读数：容器自带 192×192 预览放进 74×42 的框，
+   contain 左右各留 21.6% ≈ 用户说的"左右两边各约 1/5 是白块，只剩中间能预览"。 */
+.mpw_thumb::before, .mpw_wallThumb::before {
+  content: ""; position: absolute; inset: 0; z-index: 0; pointer-events: none;
+  background-image: var(--mpw-thumb-cover, none); background-size: cover; background-position: center;
+  filter: blur(6px); transform: scale(1.08);
+}
+.mpw_thumb [data-mpw-thumb-ph], .mpw_wallThumb [data-mpw-thumb-ph] { z-index: 2; }
+/* ①(2026-09-21 真机)"框里还没有画面"的加载态：给一层会走的骨架，而不是纯底色
+   （用户原话"变成一块白色、中间写着 mp4"—— 分不清在加载还是坏了）。
+   只在 trying 出现；一旦有媒体画出来 box 状态就变 media，这一层随之消失。 */
+.mpw_thumb[data-mpw-thumb-state="trying"], .mpw_wallThumb[data-mpw-thumb-state="trying"] {
+  background-image: linear-gradient(100deg, transparent 25%, rgba(255,255,255,.30) 50%, transparent 75%);
+  background-size: 200% 100%; background-repeat: no-repeat;
+  animation: mpwThumbSkeleton 1.4s linear infinite;
+}
+@keyframes mpwThumbSkeleton { from { background-position: 120% 0; } to { background-position: -120% 0; } }
+@media (prefers-reduced-motion: reduce) { .mpw_thumb[data-mpw-thumb-state="trying"], .mpw_wallThumb[data-mpw-thumb-state="trying"] { animation: none; } }
 /* 占位：整块（铺满 + 居中），不是一条被挤出来的白边。
    显隐由**我们自己的**属性 data-mpw-thumb-shown 控制（不用标准 [hidden]：样式作用域护栏要求
    选择器里的原子都在登记表里，而我们自己的 data-mpw-* 天生在册；状态机也只有这一个开关）。 */
@@ -15835,10 +16083,16 @@ body[data-mpw-modal] [role="dialog"] {
 						setCustomFiles([]); setWallList([]);
 					}
 					else {
-						/* ①(2026-09-21 第13条) 扫描成功 ⇒ 缩略图缓存纪元前进：**同一个目录**重新扫描
-						   （用户换了目录再换回来、或目录内容变了）也强制换 URL 键、重走候选链，
-						   不沿用浏览器里那份旧结果（失败结果同样不缓存）。 */
-						try { mpwThumbInvalidate("scan-custom-dir"); } catch (e) {}
+						/* ①(2026-09-21 真机) 扫描成功 ⇒ **只有内容真的变了**才推进缩略图缓存纪元。
+						   旧写法无条件 invalidate ⇒ 每次扫描都把全部缩略图重挂载 + 重发请求（真机读数：
+						   宿主串行解析容器，`/custom-mpkg-preview` 逐个 5.6s→11.8s 递增 ⇒ 预览框白十几秒、
+						   偶发落到类型占位）—— 而用户看到的只是"同一批壁纸"。
+						   现在：同一个目录、同一份清单 ⇒ 纪元不动、URL 不动、React 节点不动 ⇒
+						   "扫描 N 次结果一致"是**构造出来的**，不是碰巧。判据 T3（真机探针）。 */
+						try {
+							const dirId = mpwThumbDirIdentity(readSection());
+							mpwThumbNoteContent(dirId, d.files || [], "scan-custom-dir");
+						} catch (e) {}
 						setCustomFiles(d.files || []);
 						// ①(新) 合并进统一列表：自定义目录文件（图片+视频）+ workshop 原始子文件夹
 						// （video → mp4 播放；web → iframe；scene → 预览图/后续静态帧）

package/lib/now-playing-math.js

@@ -605,10 +605,19 @@ const barTop = (p) => mix(SHUT - PAD - RAIL_H, RAIL_Y, p);
 /** 轨道的左右端点（一个 margin，所以两端永不移动）。 */
 const barLeft = () => PAD;
 const barWidth = () => W - PAD * 2;
-/** 播放进度百分比（0..TOTAL 的时钟 → 0..100）。 */
-const runPct = (at) => (clamp(at, 0, TOTAL) / TOTAL) * 100;
-/** 剩余时间（负号由组件加，保证两段数字等宽）。 */
-const remain = (at) => TOTAL - clamp(at, 0, TOTAL);
+/** 时间轴（**唯一事实源**）：当前媒体的时长。缺省/非法值才退回上游演示常量 `TOTAL`。
+ *
+ *  为什么必须带参（2026-09-21 真机）：卡片的"−剩余"与进度条填充过去无条件用 `TOTAL`（214 = 上游
+ *  演示里那首曲子的秒数）。真实媒体 100.05s（1:40）时：卡片写 `−3:29`、条子播到结尾也只画到
+ *  47%（100/214）⇒ 用户看到的正是「1 分 40 秒读成 3 分 30 多秒」+「点一下只跳到整条的一半」。
+ *  3.11.0 修的是**数据目标**（npMediaTarget：位置/时长/seek 落到同一个元素），
+ *  但**显示轴**还是这个常量 —— 于是"数据对、显示错"能长期共存。这条口径与数据面同源：
+ *  显示用的时长 == `npResolveMedia()` 送进控制器的 `media.total` == 媒体元素自己的 duration。 */
+const axisOf = (total) => (typeof total === "number" && isFinite(total) && total > 0 ? total : TOTAL);
+/** 播放进度百分比（0..`total` 的时钟 → 0..100）。`total` 省略 = 上游演示常量（演示/纯几何测试用）。 */
+const runPct = (at, total) => (clamp(at, 0, axisOf(total)) / axisOf(total)) * 100;
+/** 剩余时间（负号由组件加，保证两段数字等宽）。同样以 `total` 为准（唯一事实源）。 */
+const remain = (at, total) => axisOf(total) - clamp(at, 0, axisOf(total));
 
 /* ── the one thing you press to change shape ───────
    Invisible, and it is the WHOLE bar when shut — the
@@ -654,7 +663,7 @@ module.exports = {
   /* 两个八点四边形 */
   PAUSE_L, PLAY_L, PAUSE_R, PLAY_R, quad,
   /* 时间 */
-  clock, tickClock,
+  clock, tickClock, axisOf,
   /* 端点/派生形状 */
   durationOf, artRadius, cornerOffset, boxRadius,
   swellOf, zoomOf, gooOf, gooPull, gooTip, gooScale,

package/lib/now-playing.js

@@ -745,7 +745,12 @@ function createNowPlaying(deps) {
     const going = !!q.playing;
     const media = q.media || {};
     const known = typeof media.total === "number" && media.total > 0;
-    const at = Math.max(0, Math.min(known ? media.total : M.TOTAL, Number(q.at) || 0));
+    /* 时间轴 = **当前媒体的时长**（唯一事实源；`known` 为假才退回上游演示常量）。
+       夹取、进度条填充、"−剩余"三处**共用这一个值** —— 任何一处各自用常量，就会出现
+       "数据对、显示错"（真机：100.05s 的媒体被画成 214s 的轴）。判据见
+       tools/np-axis-live-probe.mjs（真机）与 tools/np-control-test.mjs 的 X 组（无浏览器）。 */
+    const axis = M.axisOf(known ? media.total : null);
+    const at = Math.max(0, Math.min(axis, Number(q.at) || 0));
 
     const art = M.artSize(p);
     const artR = M.artRadius(M.CORNER);
@@ -793,7 +798,7 @@ function createNowPlaying(deps) {
           h("span", { className: "mpw_np_rail" },
             h("span", {
               className: "mpw_np_run",
-              style: { width: (known ? M.runPct(at) : 0) + "%" },
+              style: { width: (known ? M.runPct(at, axis) : 0) + "%" },
             })),
           /* ①(NP-4)③ 进度条可拖动：命中带绝对定位在 bar 上（**不进**那一列的 flex 流），
              所以时钟与轨道的布局一个像素都不动。轨道只有 3px，命中带上下各补 NP_SCRUB_PAD。
@@ -850,7 +855,7 @@ function createNowPlaying(deps) {
                 h("span", { className: "mpw_np_volRun", style: { width: (vol * 100) + "%" } }),
                 h("span", { className: "mpw_np_volKnob", style: { left: (vol * 100) + "%" } }))) : null,
             /* 数据源没有时长时**不假装**：显示 --:--（见 docs/NOW-PLAYING-DSH.md §4 情形②） */
-            h("span", null, known ? ("−" + M.clock(M.remain(at))) : "--:--"))),
+            h("span", null, known ? ("−" + M.clock(M.remain(at, axis))) : "--:--"))),
         h("button", {
           className: "mpw_np_tap", type: "button",
           onClick: () => { if (q.onToggle) q.onToggle(); },
@@ -1677,6 +1682,9 @@ function createNowPlaying(deps) {
   }
 
   return {
+    /* ①(2026-09-21) 纯渲染函数也对外：**显示面**（进度条填充宽度、"−剩余"文本）要能在
+       无浏览器门禁里对着产出的元素树断言 —— 只测控制器状态测不到"数据对、显示错"
+       （真机 bug：媒体 100.05s，卡片按上游常量 214 画）。判据：tools/np-control-test.mjs 的 X 组。 */
     NowPlaying, PlayMark, createController, createSlotAction, shouldHide, resolveAnchor, sidebarRoot, sidebarCol, occupantOf,
   };
 }

package/package.json

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