dsh-plugin-wallpaper-engine-media-bridge 0.0.0-stage → 1.4.0

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# cordis.patch.yml — 「系统媒体桥」子包自己的行（ADR-0014 S4.1 / S4.2 / S4.4）。
+#
+# ⚠️ 一次安装形态（主包 patch 用 name 引用子包，ADR-0014 S4.1）下，这一行由**主包**的
+# cordis.patch.yml 插入；只有把这个子包自己当成独立 bundle 时
+# （各自 dsh.bundle.patch + 各自进 dsh.profile.bundles，**不采纳**）本文件才生效。
+# 两处同时插同一个 id 会撞车 ⇒ 接线时以主包那份为准，本文件保持与它逐字一致（ADR-0014 S4.2）。
+#
+# 行名 = 真实包名（裸真名）：本版 DSH 不传 bareModuleBaseUrl ⇒ 行名一律从 <profile>/cordis.yml
+# 旁起算，裸名 → <profile>/node_modules/<name>；开发期靠 scripts/dev-link-subpackages.mjs 建的
+# junction 让这个名字出现在 profile/node_modules 里（ADR-0014 S4.4），发布期靠传递依赖 hoist。
+# id 一旦定下不再改（ADR-0014 S4.3）。
+- insert:
+    - id: wallpaper-engine-media-bridge
+      name: 'dsh-plugin-wallpaper-engine-media-bridge'

package/lib/audio-tap.swift

@@ -0,0 +1,146 @@
+// dsh-wallpaper-engine — 系统音频频谱采集器（macOS 14.2+ CoreAudio Process Tap）
+//
+// 用途：把「系统正在播放的声音」（loopback，不经过麦克风）转成 64 段频谱，
+// 20fps 写到 stdout（每帧固定 64 字节，0-255 整数）—— 供插件宿主喂给
+// WebWallGL 渲染页，让壁纸的音频可视化 / registerAudioBuffers 跟随真实音乐。
+//
+// 权限：首次运行会请求「音频录制」（TCC）。未授权时 AudioHardwareCreateProcessTap
+// 返回错误码，本程序以 stderr 一行 `tap-create-failed <code>` 退出 —— 宿主据此
+// 在设置界面给出授权指引，并回落到模拟频谱。
+//
+// 设计取舍：
+//  - tap 的 IOProc 在实时线程：回调里只做「写环形缓冲」（无分配、无锁；单写单读
+//    的环形缓冲最坏读到半帧数据，频谱略微跳动，音频可视化完全可接受）。
+//  - FFT / 分箱 / 输出放在主线程 20fps 定时器里做（2048 点 vDSP real FFT，微秒级）。
+//  - 立体声 → 单声道（多声道取平均）：壁纸音条不强调声道差（上游对自带 BGM 也是
+//    同值喂左右）。
+import AudioToolbox
+import CoreAudio
+import Accelerate
+import Foundation
+
+let FFT_N = 2048
+let LOG2N = vDSP_Length(11) // 2^11 = 2048
+let BANDS = 64
+let FPS = 20
+let RING = 1 << 15 // 32768 样本（约 0.68s @48k），远大于 FFT 窗口
+
+private var ring = [Float](repeating: 0, count: RING)
+private var ringWrite = 0
+
+private func fail(_ msg: String, _ code: Int32) -> Never {
+  FileHandle.standardError.write((msg + "\n").data(using: .utf8)!)
+  exit(code)
+}
+
+// ── 1. Process Tap（系统全局音频；排除自身进程避免自采反馈）──────────────────
+let tapDesc = CATapDescription(stereoGlobalTapButExcludeProcesses: [])
+tapDesc.name = "dsh-we-audio-tap"
+tapDesc.isPrivate = true
+tapDesc.muteBehavior = .unmuted // 只监听，不影响系统输出
+
+var tapID = AudioObjectID(kAudioObjectUnknown)
+var err = AudioHardwareCreateProcessTap(tapDesc, &tapID)
+if err != noErr { fail("tap-create-failed \(err)", 2) }
+
+// ── 2. 聚合设备承载 tap ──────────────────────────────────────────────────────
+let aggDesc: [String: Any] = [
+  kAudioAggregateDeviceNameKey: "dsh-we-audio-tap-agg",
+  kAudioAggregateDeviceUIDKey: UUID().uuidString,
+  kAudioAggregateDeviceIsPrivateKey: true,
+  kAudioAggregateDeviceTapListKey: [[
+    kAudioSubTapUIDKey: tapDesc.uuid.uuidString,
+    kAudioSubTapDriftCompensationKey: true,
+  ]],
+]
+var aggID = AudioObjectID(kAudioObjectUnknown)
+err = AudioHardwareCreateAggregateDevice(aggDesc as CFDictionary, &aggID)
+if err != noErr { fail("agg-create-failed \(err)", 3) }
+
+// ── 3. IOProc：只写环形缓冲 ─────────────────────────────────────────────────
+var procID: AudioDeviceIOProcID?
+err = AudioDeviceCreateIOProcIDWithBlock(&procID, aggID, nil) { _, inData, _, _, _ in
+  let abl = UnsafeMutableAudioBufferListPointer(UnsafeMutablePointer(mutating: inData))
+  guard abl.count > 0 else { return }
+  let buf = abl[0]
+  guard let mData = buf.mData else { return }
+  let ch = max(1, Int(buf.mNumberChannels))
+  let total = Int(buf.mDataByteSize) / MemoryLayout<Float>.size
+  let ptr = mData.bindMemory(to: Float.self, capacity: total)
+  if ch == 1 {
+    for i in 0..<total {
+      ring[ringWrite] = ptr[i]
+      ringWrite = (ringWrite + 1) % RING
+    }
+  } else {
+    var i = 0
+    while i + ch <= total {
+      var s: Float = 0
+      for c in 0..<ch { s += ptr[i + c] }
+      ring[ringWrite] = s / Float(ch)
+      ringWrite = (ringWrite + 1) % RING
+      i += ch
+    }
+  }
+}
+if err != noErr { fail("ioproc-create-failed \(err)", 4) }
+err = AudioDeviceStart(aggID, procID)
+if err != noErr { fail("device-start-failed \(err)", 5) }
+FileHandle.standardError.write("ready\n".data(using: .utf8)!)
+
+// ── 4. 主线程 20fps：FFT → 64 段 → stdout ──────────────────────────────────
+let setup = vDSP_create_fftsetup(LOG2N, FFTRadix(kFFTRadix2))!
+var hann = [Float](repeating: 0, count: FFT_N)
+vDSP_hann_window(&hann, vDSP_Length(FFT_N), Int32(vDSP_HANN_NORM))
+var input = [Float](repeating: 0, count: FFT_N)
+var real = [Float](repeating: 0, count: FFT_N / 2)
+var imag = [Float](repeating: 0, count: FFT_N / 2)
+var mags = [Float](repeating: 0, count: FFT_N / 2)
+var out = [UInt8](repeating: 0, count: BANDS)
+let usable = Float(FFT_N / 2) * 0.72 // 截到 ~16kHz@48k：更高频段能量极微
+let lo = 2
+
+func emitFrame() {
+  let w = ringWrite
+  let start = (w - FFT_N + RING) % RING
+  for i in 0..<FFT_N { input[i] = ring[(start + i) % RING] }
+  vDSP_vmul(input, 1, hann, 1, &input, 1, vDSP_Length(FFT_N))
+  real.withUnsafeMutableBufferPointer { rp in
+    imag.withUnsafeMutableBufferPointer { ip in
+      var split = DSPSplitComplex(realp: rp.baseAddress!, imagp: ip.baseAddress!)
+      input.withUnsafeBufferPointer { inp in
+        inp.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: FFT_N / 2) { cp in
+          vDSP_ctoz(cp, 2, &split, 1, vDSP_Length(FFT_N / 2))
+        }
+      }
+      vDSP_fft_zrip(setup, &split, 1, LOG2N, FFTDirection(FFT_FORWARD))
+      vDSP_zvabs(&split, 1, &mags, 1, vDSP_Length(FFT_N / 2))
+    }
+  }
+  let norm = 1.0 / Float(FFT_N) // real FFT 的幅度归一（相对值，标定足够）
+  for b in 0..<BANDS {
+    let f0 = lo + Int(Float(usable) * pow(Float(b) / Float(BANDS), 2))
+    let f1 = max(f0 + 1, lo + Int(Float(usable) * pow(Float(b + 1) / Float(BANDS), 2)))
+    var peak: Float = 0
+    var f = f0
+    while f < f1 && f < mags.count {
+      let v = mags[f] * norm
+      if v > peak { peak = v }
+      f += 1
+    }
+    // -70dB..0dB → 0..255（对数观感，安静段落接近 0 而不是恒亮）
+    let db = 20 * log10(max(peak, 1e-7))
+    let n = max(0, min(1, (db + 70) / 70))
+    out[b] = UInt8(n * 255)
+  }
+  FileHandle.standardOutput.write(Data(out))
+}
+
+let timer = Timer(timeInterval: 1.0 / Double(FPS), repeats: true) { _ in emitFrame() }
+RunLoop.main.add(timer, forMode: .common)
+
+// 信号兜底：宿主 kill 时安静退出（private 聚合设备随进程回收）
+signal(SIGTERM) { _ in exit(0) }
+signal(SIGINT) { _ in exit(0) }
+
+RunLoop.main.run()

package/lib/backend.js

@@ -0,0 +1,144 @@
+/**
+ * backend.js — 媒体桥的**媒体后端门面**：**首选 media-bridge 子进程，失败自动回落内置实现**。
+ *
+ * 对宿主只暴露一小组方法（start/stop/spectrum/nowPlaying/artworkFile/artworkMime/status
+ * 与内置实现同名，另有中间件专供的 usingBridge/bridgeInfo/control），所以同目录的路由族
+ * （`now-playing.js`）不需要知道底下是谁在供数 —— 这是刻意留的接缝：换后端不动路由形状，
+ * 回滚也不需要改路由。
+ *
+ * 选择逻辑（每次会话只决定一次，之后靠 bridge.ready() 判断中间件是否还活着）：
+ *   1. `DSH_WE_MEDIA_LEGACY=1`            → 直接用内置实现（排查/对比用）
+ *   2. 产物解析成功 + spawn + 握手通过     → 中间件（三平台同一套能力）
+ *   3. 任一步失败（取不到产物/起不来/协议不符/连续崩溃）→ 内置实现 + 原因进 status
+ *
+ * 日志注入契约：本目录只调用注入的 `log(msg, level?)`，**不自己写终端**（终端与落档的唯一
+ * 入口是 `lib/log.js`，见其文件头）。级别缺省 `info`；判据是"影响显示效果的非正常表现
+ * ⇒ `warn`"：回落、启动失败、中间件报错与重启都是 `warn`，成功事实与运行信息是 `info`。
+ */
+import { join } from 'node:path';
+import { createMediaBridge as createLegacy } from './legacy.js';
+import { createBridgeSupervisor } from './supervisor.js';
+import { provisionMediaBridge } from './provision.js';
+
+/**
+ * @param {object} o
+ * @param {string} o.dataDir 插件数据目录（**不是**缓存根）：中间件产物 `<dataDir>/bin/media-bridge/`
+ *   与 macOS 音频 tap 的编译产物 `<dataDir>/bin/we-audio-tap` 都落这里 —— 它们属**工具链**，
+ *   和 ffmpeg 一样不随「缓存位置」走（挪了要重下 / 重编译，那是另一件事）。
+ * @param {string|(() => string)} [o.cacheBaseDir] 缓存根（见 `lib/kernel/data-dir.js` 的 `cacheBaseDir()`）：中间件的
+ *   运行时缓存（`--cache-dir`）与内置实现的封面缓存都在它下面。缺省 `<dataDir>/cache` ——
+ *   与默认布局逐字一致，所以只传 `dataDir` 的老调用点行为不变。**可以传访问器**（推荐，
+ *   路由就这么传）：那样「缓存位置」改完，中间件下一次起动 / 下一张封面就走新根，不必重启宿主。
+ * @param {(text: any, level?: string) => void} [o.log] 日志被调用面（`log(msg, level?)`）；缺省空实现。
+ * @param {(name:string, data?:any) => void} [o.diag] 诊断上报（宿主注入 `appendDiagLine` 包装）。
+ */
+export function createMediaBackend({ dataDir, cacheBaseDir = join(dataDir, 'cache'), log = () => {}, diag = () => {} }) {
+  // 缓存根**每次现问**（同 `cacheBaseDir()` 的理由）：传进来是访问器就现算，是字符串就照用。
+  // 在这里存值快照会让"改完缓存位置、新缓存又写回旧盘"悄悄发生 —— 正是本轮要修的那类 bug。
+  const cacheRoot = () => (typeof cacheBaseDir === 'function' ? cacheBaseDir() : cacheBaseDir);
+
+  let started = false;
+  let useBridge = false;         // 中间件可用（握手通过且没被判死）
+  let fallback = '';             // 回落原因（空 = 没回落）
+  let note = '';                 // 准备中的说明（设置界面可见）
+  let booting = null;
+  let sup = null;
+  let legacy = null;
+  const optsRef = { audio: true, online: false };
+  const forceLegacy = String(process.env.DSH_WE_MEDIA_LEGACY || '').trim() === '1';
+
+  /** 内置实现按需构造（音频开关要跟着用户设置走，不能构造时就定死）。 */
+  function legacyBackend() {
+    if (!legacy) legacy = createLegacy({ dataDir, cacheBaseDir: cacheRoot, log, audio: optsRef.audio });
+    return legacy;
+  }
+
+  /** 当前真正在供数的后端（中间件没就绪/已判死时都落到内置实现）。 */
+  function active() {
+    if (useBridge && sup && sup.ready()) return sup;
+    return legacyBackend();
+  }
+
+  function fallBackTo(reason) {
+    if (fallback) return;
+    fallback = reason || '中间件不可用';
+    useBridge = false;
+    note = '';
+    log('回落到内置媒体实现：' + fallback, 'warn');
+    diag('media-fallback', { reason: String(fallback).slice(0, 200) });
+    try { legacyBackend().start(); } catch (err) { log('内置媒体实现启动失败：' + err, 'warn'); }
+  }
+
+  function bootBridge() {
+    if (booting) return booting;
+    booting = (async () => {
+      note = '正在准备系统媒体中间件…';
+      const prov = await provisionMediaBridge({ dataDir, log });
+      if (!prov.path) { fallBackTo(prov.error || '中间件产物不可用'); return; }
+      sup = createBridgeSupervisor({
+        binPath: prov.path,
+        cacheDir: join(cacheRoot(), 'media-bridge'),
+        log,
+        diag,
+        onFatal: (why) => fallBackTo(why),
+      });
+      const ok = await sup.start({ audio: optsRef.audio, online: optsRef.online });
+      if (!ok) { fallBackTo(sup.lastError() || '中间件启动失败'); return; }
+      useBridge = true;
+      note = '';
+      log(`媒体数据源：系统媒体中间件（${prov.source}${prov.tag ? ', ' + prov.tag : ''}）`, 'info');
+    })().catch((err) => {
+      fallBackTo('中间件准备出错：' + String(err && err.message ? err.message : err));
+    }).finally(() => { booting = null; });
+    return booting;
+  }
+
+  return {
+    /** 懒启动（由路由第一次被访问时触发；重复调用无副作用）。 */
+    start(opts = {}) {
+      if (started) return;
+      started = true;
+      Object.assign(optsRef, { audio: opts.audio !== false, online: opts.online === true });
+      if (forceLegacy) {
+        fallback = '按 DSH_WE_MEDIA_LEGACY=1 使用内置实现';
+        log('媒体数据源：内置实现（DSH_WE_MEDIA_LEGACY=1）', 'info');
+        legacyBackend().start();
+        return;
+      }
+      bootBridge();
+    },
+    stop() {
+      try { if (sup) sup.stop(); } catch { /* ignore */ }
+      try { if (legacy) legacy.stop(); } catch { /* ignore */ }
+    },
+    spectrum: () => active().spectrum(),
+    nowPlaying: () => active().nowPlaying(),
+    artworkFile: () => active().artworkFile(),
+    artworkMime: () => active().artworkMime(),
+    /**
+     * 反向控制（壁纸里的播放按钮 / 宿主面板 → 真实播放器）：**只有中间件能做**
+     * —— 内置实现是纯读取。中间件没就绪（还没启动 / 已判死回落）时统一回不可用，
+     * 不在此处触发启动：控制是用户点一下的交互，不该顺带把产物下载与子进程
+     * 拉起来（启动仍由取数那四条路由的懒启动决定）。
+     *
+     * 返回值一律是 `{ ok, … }`（不抛），路由按它决定状态码。
+     */
+    async control(action) {
+      if (useBridge && sup && sup.ready()) return sup.control(action);
+      return { ok: false, error: fallback ? 'control-unsupported' : 'media-backend-not-ready' };
+    },
+    status() {
+      const live = useBridge && sup && sup.ready();
+      const st = active().status();
+      return {
+        ...st,
+        backend: live ? 'bridge' : st.backend,
+        fallback,
+        note,
+      };
+    },
+    /** 当前是否中间件在供数（自检与设置界面用）。 */
+    usingBridge: () => Boolean(useBridge && sup && sup.ready()),
+    bridgeInfo: () => (sup ? sup.info() : null),
+  };
+}

package/lib/index.js

@@ -0,0 +1,129 @@
+/**
+ * `media-bridge` 子包宿主入口（P-F 第三格：`lib/components/media-bridge/` → `packages/media-bridge/`）。
+ *
+ * 为什么这一格独立成行：这五条路由（`/media-status`、`/audio-spectrum`、`/now-playing`、
+ * `/now-playing/artwork`、`/media-control`）与它们的后端实现（media-bridge 子进程 + 内置回落）
+ * 自成一条边：桥的状态 = 一个**子进程**与它自己的磁盘载体，与 `lib/media/` 那六个"内核媒体"
+ * 文件（帧缓存 / 媒体目录 / MP4 探测 / 场景探测 / 视频预览 / 转码）零交叉 —— 后者仍由内核
+ * （`lib/kernel/host-kernel.js`）持有，因为 `lib/index.js` 的 `/inventory`、`/media`、`/scene-*`
+ * 都消费它们。出户后"这个组件由哪些文件构成"由**位置**回答（M6/M10）。
+ *
+ * 两处加载路径共用同一份实现（照抄 dsh-ops 的组件真形）：
+ *   ① 宿主把 patch 行的 `name` 当**独立 plugin** 加载 ⇒ `apply(ctx, config)` 是入口；
+ *   ② 门面的 `applyComponent(root, rawConfig, 'media-bridge')` 是"按组件加载"入口。
+ * P-F 之后两条路径的 deps **不再是两份各写各的字面量**：门面与入口都从
+ * `lib/subpackage-boot.js` 的 `subpackageKeys('media-bridge', ctx)` 取**同一份冻结键视图**
+ * ⇒ 两条路径不可能漂移（对账面 = `test/verify-inject-contracts.mjs` ② 的叶子冻结表逐键对账）。
+ *
+ * `export const name` 与 patch 行的 `name` 逐字相等（`dsh-plugin-wallpaper-engine-media-bridge`）。
+ *
+ * ⚠️ **跨包纪律（ADR-0014 S5.1 / S5.2，判据 `test/verify-subpackage-purity.mjs`）**：本模块
+ * **零主包说明符、零相对路径逃出本包** —— 只 import 本包内的路由族。宿主能力一律经
+ * `ctx.wallpaperEngineHost` 的键视图（`host.keys('media-bridge', ctx)`）取。这不是风格问题：
+ * 相对 import 主包文件、或 import 主包名，都是该判据的硬红。
+ *
+ * ⚠️ **取服务姿势**：先声明 `export const inject = ['webServer', 'wallpaperEngineHost']`，再直接读
+ * `ctx.<服务>`。缺服务且不声明 inject 会被 cordis 的 reflect `get` 当场抛
+ * `cannot get property "webServer" without inject at applyImpl`（真机原文），函数体里那些早退
+ * 分支永远执行不到（死代码）。声明 inject 后由 Loader 保证「服务就绪才激活」，下面的早退分支只兜
+ * 「服务在、但 register 面还没挂上」这一种情况。
+ *
+ * ⚠️ **teardown 得交两份**：本模块导出的 `apply` 是**函数声明**（有 `prototype`）⇒ cordis 的 loader
+ * 走 `new apply(ctx, config)` 分支、**返回值被丢弃** ⇒ 只 `return keys.runComponent(…)` 的话 fiber
+ * 卸载时没人撤路由。所以返回值一律走 `keys.handOffTeardown(ctx, …)`（同一份 disposer 也交给
+ * `ctx.effect` 并做幂等包装，见 `lib/host-boot.js`）。判据 `test/verify-bundle-rows.mjs` ⑧c。
+ *
+ * ⚠️ **模块作用域纪律**：本模块被门面**静态** import（`test/verify-reachability.mjs` 的 import 图
+ * 承重），宿主真实装载顺序又是**裸行在前** ⇒ 本模块可能**先于**门面求值。模块作用域（顶层、
+ * 任何函数体之外）只许放声明/常量 —— 不得在求值期读别的模块的绑定并调用它（会踩 TDZ）。
+ * 对应判据：`test/verify-bundle-rows.mjs` ⑥（结构判据 + 模块作用域文本兜底，双向）。
+ *
+ * ⚠️ **原先的两个叶子 import 已改为服务面取键（P-F）**：`configPath` 与 `CONTROL_JSON_MAX_BYTES`
+ * 曾由本入口直接 import 主包叶子模块（`lib/kernel/data-dir.js` / `lib/http-body.js`）——出户后
+ * 那两条相对路径既不可解析、也违反跨包纪律。现在它们分别走键表的 `data:<名>` 与 `http:<名>` 源型
+ * （`lib/subpackage-boot.js` 的 `DATA_VIEW` / `HTTP_VIEW`），**仍然是同一份模块级绑定**（不是副本）。
+ * 键集见 `lib/kernel/component-session.js` 的 `COMPONENT_VIEW_KEYS['media-bridge']` 注释。
+ */
+import { registerNowPlayingRoutes } from './routes/now-playing.js';
+
+/** patch 行 slug（`cordis.patch.yml` 里该行 `name` 的完整值，两处逐字相等）。 */
+export const name = 'dsh-plugin-wallpaper-engine-media-bridge';
+
+/**
+ * 硬依赖 web 服务 + 主包宿主服务：与主行 `lib/index.js` 的 `inject` 同一套语义。
+ * 子包行走 patch 行加载时，Loader 靠这两句保证「服务就绪才激活」，`ctx.webServer` /
+ * `ctx.wallpaperEngineHost` 才读得到。
+ */
+export const inject = ['webServer', 'wallpaperEngineHost'];
+
+/** 独立 plugin 入口：宿主按 patch 行加载本子包时走这里，转调本模块的实现（不经门面）。 */
+export function apply(ctx, config) {
+  // ⚠️ 这个字面形态是**承重**的：`test/verify-inject-contracts.mjs` 的 `tableBindingNames()` 按
+  // `const <host> = ctx.<服务名>` 认「本文件里的冻结表绑定」（`recvRe`），再据此把下面调用点的
+  // `...keys` 展开成叶子冻结表。写成 `ctx && ctx.<服务名>` 守卫就认不出表 ⇒ 整包调用点判 dynamic
+  // 而红（nc-sub7 钉的就是这条：接收者必须源自 `ctx.<服务名>`）。
+  const host = ctx.wallpaperEngineHost;
+  // 拿不到服务名就大声失败：静默 `undefined` 会让下面每一步都在 undefined 上取属性（半死态）。
+  if (!host) {
+    throw new Error('[wallpaper-engine] media-bridge 没拿到 wallpaperEngineHost 服务'
+      + '（inject 声明与宿主装载顺序不匹配）');
+  }
+  // 键视图 = `lib/subpackage-boot.js` 的 SUBPACKAGE_KEY_TABLE 里本包那一行（值全部来自主包模块级绑定）。
+  // 记账 / 错误留证 / 「失败仍原样抛」三件事都在 `keys.runComponent()`（门面 `applyComponent`
+  // 走的是同一个函数）⇒ 两条装载路径共用一份语义，不可能一条记了、另一条忘了。
+  const keys = host.keys('media-bridge', ctx);
+  // `http` 面（`sendJson` / `bodyReader`）不在冻结键表里，与 `packages/fonts` 同款：按需显式带上。
+  const deps = Object.freeze({ ...keys, http: host.http });
+  return keys.handOffTeardown(ctx, keys.runComponent('media-bridge', ctx, config, deps, applyImpl));
+}
+
+/**
+ * 组件实现。第三个形参名取 `c`（与 `lib/kernel/host-session.js` 同一约定）：
+ * `test/tools/host-route-index.mjs --deps` 按 `const { … } = c;` 现抽契约；路由族调用点的
+ * `...keys` 展开则由 `test/verify-inject-contracts.mjs` 按冻结表认（`keys` 与 `apply()` 里那个
+ * 绑定同名 ⇒ 两边指的是同一份键视图）。
+ */
+export function applyImpl(root, _rawConfig, c) {
+  const keys = c;
+  const { base, pluginName, configPath, CONTROL_JSON_MAX_BYTES, componentViewFrom, createComponentSession } = c;
+  // 两条装载路径都能这么读：① 子包行自己声明了 `inject = ['webServer', 'wallpaperEngineHost']`；
+  // ② 门面路径的 `root` 就是门面的 ctx，而门面同样声明了 `inject = ['webServer']`（主行
+  // `lib/index.js` 的 `inject` 声明）。
+  const webServer = root && root.webServer;
+  // 与门面 `apply()` 同款早退：服务在、但 register 面还没挂上（或换成了别的 webServer 实现）。
+  if (!webServer || typeof webServer.register !== 'function') return () => {};
+
+  // P2-7B 注入面收窄：从内核取**本组件声明的视图**（`COMPONENT_VIEW_KEYS['media-bridge']`），
+  // 不再 `const { … } = hostKernel` 现解构；视图缺键即抛，不静默 `undefined`。
+  const view = componentViewFrom('media-bridge');
+  // 迷你会话（disposers / log / serveFile / 同序 teardown）收在内核侧；`appendDiagLine` 由会话
+  // 一并交出（它在 SESSION_SERVE_KEYS 里，入口若自己再从视图解构一次，`verify-component-face` ③
+  // 的「入口 ∩ 会话 = ∅」会红）。
+  const { log, disposers, serveFile, teardown, appendDiagLine } = createComponentSession(root, { base, pluginName }, view);
+  // 本组件自己要的两个键：后端启动决策每次现读设置（`readConfig`），缓存根传**访问器**。
+  const { readConfig, cacheBaseDir } = view;
+
+  // ⚠️ **注册期必须包 try**（P2-4）：这一族一次性注册**五条**路由，中途抛错时已经推进
+  // `disposers` 的那几条会留下（`mediaBackend.stop()` 也在同一个 disposer 列表里，一并丢）
+  // ⇒ 下一次启用撞 `webserver: duplicate … route`，且桥的子进程无人收。`teardown()` 自己吞异常，
+  // 原错照抛（装载失败必须仍然是红的）。
+  try {
+    // 3c-5. 媒体状态族路由（媒体后端懒启动 + /media-status、/audio-spectrum、/now-playing、
+    //       /now-playing/artwork、/media-control）→ 本包 `lib/routes/now-playing.js`。
+    //       后端实例、启动决策与五条注册都在那个文件里；这里只声明它的依赖（与门面调用点逐键相同）。
+    registerNowPlayingRoutes(webServer, {
+      ...keys, disposers, base, appendDiagLine, configPath, cacheBaseDir, readConfig, serveFile,
+      CONTROL_JSON_MAX_BYTES, http: keys.http,
+      // 媒体子系统的行统一带 `[media]` 标签（与终端既有形状逐字一致）；级别由调用点标注。
+      log: log.tag('media'),
+    });
+  } catch (error) {
+    teardown();
+    throw error;
+  }
+
+  // 本组件自己的收尾（会话的 teardown）：与 host-session 的 teardown 同序（逐个 disposer →
+  // destroy 在途流 → 清两个容器），但**没有** releaseKernelLease —— 见 `component-session.js`
+  // 文件头那条有意不对称（桥的子进程由它自己的 disposer `mediaBackend.stop()` 收掉）。
+  return teardown;
+}