docs: add device debugging and UI iteration log

docs/devlog-2026-08-16.md

@@ -71,3 +71,52 @@
 ## 7. 分支与提交
 
 开发走 `dev` 分支（`main` 为发布分支）。设计文档 `docs/superpowers/specs/`、实现计划 `docs/superpowers/plans/`、本日志 `docs/`。
+
+## 8. 真机调试与 UI 迭代（宿主机 OnePlus PLK110）
+
+### 8.1 真机环境
+
+- 通过 SSH 连宿主机 Termux（`aska@127.0.0.1:2022`），KernelSU root，`logcat` 抓日志排查。
+- APK 用容器内 Python `http.server` 分发（`http://localhost:8080/Hearth-debug.apk`）。
+- 真机是 Android 16（API 36）手机，非目标板（RK3566/Android 11），但能验证 H5 逻辑与大部分原生行为。
+
+### 8.2 关键崩溃修复
+
+1. **黑屏（实为崩溃）**：`enterImmersive()` 在 `setContentView()` 之前调 `window.insetsController`，此时 DecorView 未创建（null）→ NPE。日志堆栈 `Attempt to invoke WindowInsetsController on a null object reference`。修复：把 `enterImmersive()` 移到 `setupWebView()`（内含 setContentView）之后。
+2. **闪退**：`MediaSessionSource` 未授权「通知使用权」时 `addOnActiveSessionsChangedListener` 抛 `SecurityException: Missing permission to control media`。修复：`start()` 内 try-catch 降级 + 设置页加授权引导项（跳 `ACTION_NOTIFICATION_LISTENER_SETTINGS`）。
+
+### 8.3 媒体卡完善
+
+- **封面**：`METADATA_KEY_ART` → 128px JPEG base64；加**封面缓存**（切歌瞬间 ART 短暂为 null，缓存兜底避免横划后封面消失）。
+- **控制按钮**：上一首/暂停/下一首（`transportControls`），**按索引**作用于当前横划到的会话。
+- **实时歌词**：网易云歌词实时更新在**通知标题**（不在 MediaSession metadata），`NotificationListenerService` 监听 `CATEGORY_TRANSPORT` 通知的 `EXTRA_TITLE`，标题优先用通知实时歌词。
+- **进度条 + 时长 + 拖动 seek**：轮询兜底（registerCallback 在歌词场景不触发）；进度条 `box-sizing:border-box` 下 `padding` 吃掉 `height` 导致 bar 高度 0 的坑；拖动 seek 调 `transportControls.seekTo`。
+- **多会话滑动**：左右横划切换（方向过渡动画），多个媒体通知（音乐/听书/视频）并存。
+
+### 8.4 玻璃效果与壁纸
+
+- **壁纸进 H5**：`backdrop-filter` 只能模糊 WebView 内部内容，而壁纸原来在 WebView 之外（透明透出），故无模糊。原生 `getWallpaper()` 把壁纸转 base64 作 body 背景，卡片才能真正模糊壁纸。
+- **动态壁纸降级**：检测 `wallpaperInfo != null` 返回空，H5 保持透明透出动态壁纸，玻璃模糊降级为普通半透明。
+- **玻璃开关**：设置页开关，默认关（普通半透明），开 = 液态玻璃（磨砂模糊 + 边缘高光）。
+
+### 8.5 设置页交互
+
+主题三态（跟随/浅色/深色，`data-theme` 覆盖 `prefers-color-scheme`）、背景遮罩（夜间，开关+明暗度）、系统亮度（`WRITE_SETTINGS` 授权）、webAPP 服务器地址（SharedPreferences）、检查更新（重拉清单）；滑块统一 touch 拖动。
+
+### 8.6 webapp 多标签
+
+- **原生标签面板**：H5 面板是桌面 WebView 底层元素，被上层内容 WebView 遮住（Android View 层级无法用 z-index 跨越）。改 **PopupWindow 原生面板**覆盖显示，内容 WebView 只预留顶栏高度（不压 webapp）。
+- **切页隐藏 webapp**：`hideWebApps()`（内容 WebView GONE，标签保留）+ `body.webapp-active` 隐藏列表内容，切回自动恢复。
+- **内容 WebView** 透明背景（未声明背景色的 webapp 透出壁纸）。
+
+### 8.7 性能
+
+- **页面预加载**：启动后后台并行拉取 APP 列表/webAPP 清单/卡片目录缓存，切页直接渲染。
+- **媒体卡增量更新**：歌词实时变化时只更新媒体卡文字，不重建整个首页（之前每次歌词变化都重建导致卡顿）。
+
+## 9. 仍在遗留
+
+- 真机为手机（Android 16），目标板 RK3566/Android 11 尚未验证（壁纸/玻璃/沉浸式/媒体卡的板子适配）。
+- 沉浸模式未在 onResume 重设；内容 WebView 无 onPause/onResume 同步。
+- 二期：沉浸首页 freeform 小窗（需固件 `enable_freeform_support`）。
+- webAPP/卡片目录默认占位地址，真机部署时配置真实服务器。