update at 2026-03-18 13:35:19

dash/docs/pagepress-theme-menu-plan.zh.md

@@ -4,6 +4,9 @@
 
 本文是评审方案，不是实机结论。
 
+补充说明：当前仓库默认已经不启用这套运行态菜单，主题切换入口只保留在 KUAL。
+本文保留为备选方案与历史设计记录，不代表当前默认交互。
+
 当前 Kindle 已掉出 Wi-Fi，SSH 中断，因此这份文档的目标是：
 
 - 先把“左右同时按下翻页键，呼出主题选择页面”的方案固定下来
@@ -14,7 +17,15 @@
 
 - Kindle Voyage
 - 固件 5.13.6
-- dashboard 运行时会停掉 framework / webreader
+- 当前默认实现为“保留 framework / webreader 的 overlay 模式”
+
+补充：
+
+- 本文很多菜单设计最初建立在“dashboard 会停掉原生 UI 栈”的旧架构上
+- 截至 `2026-03-17`，默认实现已经切到“保留原生 UI 栈”
+- 因此文中提到的 `Return Home`，应以 `stop.sh` 的当前行为为准：
+  - overlay 模式下：停掉 dashboard，并在底层是 KUAL 时把它正常退回首页
+  - 旧架构兼容模式下：保守恢复 `framework / cvm / webreader`
 
 ## 1. 已确认事实
 
@@ -85,6 +96,7 @@ echo "mem" >/sys/power/state
 3. 用户通过翻页键在主题列表中移动选中项
 4. 用户再次同时按下左右翻页键，确认并切换主题
 5. 切换完成后，立即刷新背景和时钟
+6. 菜单列表末尾可附带一个“返回首页”动作项，安全退出 dashboard 并恢复 Kindle 首页
 
 本阶段非目标：
 
@@ -113,7 +125,16 @@ echo "mem" >/sys/power/state
 
 - `PageUp`：向上移动
 - `PageDown`：向下移动
-- 再次双键同时按下：确认当前主题
+- 再次双键同时按下：确认当前项
+
+同时保留一个触摸兜底入口：
+
+- 右下角长按：直接呼出同一份运行态主题菜单
+
+其中当前项可以是：
+
+- 某个主题：执行主题切换
+- `Return Home`：退出 dashboard，恢复 framework / webreader，回到 Kindle 首页
 
 这样做的原因：
 
@@ -221,12 +242,19 @@ Press both keys: apply
 3. 识别到组合键后，本机绘制菜单
 4. 用户确认后，调用现有：
    - `/mnt/us/dashboard/switch-theme.sh <theme-id> [orientation]`
+   - 或 `/mnt/us/dashboard/stop.sh`
 5. `switch-theme.sh` 继续负责：
    - 同步主题配置
    - 拉最新背景
    - 刷新屏幕
    - 重绘时钟
 
+如果选中的是 `Return Home`，则不走主题切换，而是调用 `stop.sh`：
+
+- 停掉 dashboard 和菜单监听器
+- 恢复 `framework / cvm / webreader`
+- 回到 Kindle 首页
+
 也就是说，菜单服务只负责：
 
 - 触发
@@ -309,6 +337,7 @@ Press both keys: apply
 export THEME_MENU_ENABLED=true
 export THEME_MENU_EVENT_DEVICE="/dev/input/event2"
 export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
+export THEME_MENU_RUNTIME_DIR="/tmp/kindle-dash-theme-menu"
 ```
 
 说明：
@@ -320,6 +349,9 @@ export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
   - 后续换机型时可以只改这个
 - `THEME_MENU_COMBO_WINDOW_SECONDS`
   - 组合键判定窗口
+- `THEME_MENU_RUNTIME_DIR`
+  - 菜单服务的临时运行目录
+  - 需要放在支持 FIFO 的文件系统上，Voyage 上应使用 `/tmp`
 
 ## 9. 风险与限制
 
@@ -408,8 +440,12 @@ export THEME_MENU_COMBO_WINDOW_SECONDS=0.35
 - 监听 `/dev/input/event2`
 - 用短时间窗口识别 `PageUp + PageDown` 组合键
 - 在运行态下绘制一个 KUAL 风格的文本主题菜单
+- 右下角长按也复用同一份菜单，而不是另起一套触摸 UI
 - 用 `PageUp / PageDown` 导航
 - 再次双键确认
 - 最终复用现有 `switch-theme.sh` 完成主题切换
 
 这是当前成本最低、最容易恢复、也最适合在 SSH 不稳定阶段先落地评审的方案。
+
+如果菜单需要提供稳定退出入口，也可以在列表末尾追加一个 `Return Home` 动作项。
+实现上应复用 `stop.sh` 的保守恢复链路，而不要直接强拉 `booklet.home`。