同上

mengsan/docs/ui-hand-subextension.md

@@ -0,0 +1,98 @@
+# 梦三手牌 UI 子扩展
+
+## 模块边界
+
+这是术樱包内部的必需子模块，由梦三战斗加载，不是另一个可安装扩展。
+没有单独关闭开关。JS 或样式加载失败时进入既有战斗异常处理流程，
+保留存档并提供返回模式选择入口；不会静默略过必需模块。
+
+| 位置 | 职责 |
+| --- | --- |
+| `ui/hand/index.js` | 挂载、同步、局部输入适配、回退和幂等卸载 |
+| `ui/hand/adapter.js` | 校验引擎容器并读取真实卡牌，识别第二容器离线结构 |
+| `ui/hand/overlays.js` | 费用与强化覆盖层，仅维护当前手牌的显示节点 |
+| `ui/hand/style.css` | 独立排列、尺寸、间距、选中标记及隔离样式 |
+| `ui/hand/diagnostics.js` | 生命周期、回退和加载失败诊断日志 |
+| `tools/test-hand-ui.cjs` | 浏览器隔离验证，非发布资源 |
+| `verification/hand-ui/` | 本地验证报告、截图和清单，非发布资源 |
+| `logs/log.txt` | 游戏内生成的最近 100 条诊断，非发布资源 |
+
+`cards/personal-piles.js` 只负责个人牌堆业务，原先的手牌 DOM 显示逻辑
+已移入本模块。旧的 `ui/hand-upgrade.js` 和通用样式文件中的对应规则
+已移除，避免两套覆盖层并行维护。发布入口仍为 `register.js`。
+
+## 交互方案与证据
+
+本体 `noname/ui/click/index.js` 的 `card()` 使用真实 `this` 操作
+`ui.selected.cards` 并调用 `game.check()`。本体 `card.updateTransform()`
+检查卡牌祖先是否为 `ui.me`。十周年 `core/layout.js`、`cardDragSort.js`
+也依赖真实节点的父容器和变换。因此首期选用真实节点原位复用，
+不复制卡面，不移动手牌容器，不替换全局原型或布局函数。
+
+排列使用独立命名空间的 flex 样式；默认卡牌 90×110、间距 8，
+小屏卡牌 80×100，牌多时横向滚动。具体尺寸集中在本模块 CSS。
+卡面继续采用当前引擎/主题生成的内容。选择、取消、出牌、响应和
+选目标继续交给引擎，模块不另行计算卡牌可用性或提交出牌事件。
+
+引擎仍维护节点上的 `selected`、`selectable` 等状态。本模块通过这些
+原有类显示选择状态，保留 DOM 顺序作为引擎排序的依据。
+检测到移动手势时临时退回既有排列，释放或取消后恢复独立排列；
+触屏水平滚动保留独立排列。首期没有另做手动拖动排序系统。
+
+费用调用既有 `cardCost`，强化读取既有 `cardUpgradeLevel`。
+覆盖层只在自己的子节点 dataset 上保存显示值，使用伪元素显示文字，
+避免十周年对出牌子节点 innerText 的扫描误识别费用数字。
+覆盖层不接收指针事件；离开手牌区即回收，返回手牌区重新生成。
+若业务直接修改卡牌 storage，修改者应调用返回控制器的 `refresh()`。
+
+十周年 `uiCreateMe()` 的第二手牌容器默认离线。
+适配器允许“主容器连接、第二容器离线且为空”的结构。
+未知或被替换的容器退回原排列，保留覆盖层，并通过游戏日志和
+诊断文件报告，不依赖 `decadeUI` 的内部坐标接口。
+
+## 生命周期与日志
+
+`mode.js` 在玩家初始化后、开局摸牌前等待 `mountHandUI()`。
+模块资源登记到 battle-session，逆序释放早于个人牌堆和玩家资源。
+正常战斗结束和流程异常另有显式卸载入口；DOM 根节点被移除时
+观察器会触发卸载。加载中取消会结束等待并取消计时器。
+卸载移除覆盖层、观察器、局部监听、样式链接、自己的类名，并恢复
+自己改过的属性；多次调用安全。它不销毁真实卡牌或重置选择状态。
+
+支持引擎文件接口时，日志写入安装目录下
+`extension/术樱包/mengsan/logs/log.txt`，包含时间、战斗 session ID、
+挂载、回退、卸载与加载错误。最近 100 条覆盖写入，串行提交。
+没有文件接口时保留控制台日志；布局回退也写入游戏日志。
+
+## 验证结果及边界
+
+本次参考安装源码：本体 `game/update.js` 为 1.11.5.2；
+十周年 `info.json` 为 1.3.1。
+十周年 `STYLE_TO_SKIN` 将 off/on/othersOff 映射到
+shousha/shizhounian/xinsha，配置菜单显示名与规划文档略有不同。
+
+浏览器验证加载安装目录中的本体 CSS、十周年实际基础样式组合及
+手杀/十周年/新杀的按钮和技能样式，以匹配 `uiCreateMe()` 的 DOM 结构
+构造测试场景；点击测试使用安装源码中的真实 `ui.click.card` 函数体，
+其 `game.check` 等引擎服务为测试替身，不代表完整游戏事件链验证。
+
+| 场景 | 桌面 1280×720 | 小屏 540×360 | 完整游戏实测 |
+| --- | --- | --- | --- |
+| 原生 UI | 隔离验证通过 | 隔离验证通过 | 待验证 |
+| 手杀 off/shousha | 隔离验证通过 | 隔离验证通过 | 待验证 |
+| 十周年 on/shizhounian | 隔离验证通过 | 隔离验证通过 | 待验证 |
+| 新杀 othersOff/xinsha | 隔离验证通过 | 隔离验证通过 | 待验证 |
+
+已验证真实节点父级及点击身份、选择/取消、费用与强化移除、
+手牌离开/返回、横向滚动处理、手势布局退让、会话结束、重复卸载、
+根节点移除、加载中取消、CSS 加载失败、回退覆盖层及属性恢复。
+已有梦三逻辑回归 44 项通过。发布清单包含本模块全部 JS/CSS，
+不包含 tools、verification、.planning 和 log.txt。
+
+尚需真实游戏验证出牌/响应、技能虚拟牌、选目标/取消、引擎自动排序、
+十周年拖拽排序插件及真实手机触屏。本次没有改动已安装的游戏文件，
+也没有把隔离场景结果标记为游戏内实测通过。
+
+运行浏览器测试：`node mengsan/tools/test-hand-ui.cjs`。
+可用 NONAME_APP 指向本体目录、CODEX_NODE_MODULES 指向提供 Playwright
+的依赖目录；脚本使用本机 Chrome 的无界面独立实例。

mengsan/docs/ui-subsystem-outline.md

@@ -1,5 +1,10 @@
 # 梦三手牌 UI 子系统规划大纲
 
+首期实现已归入 `ui/hand/`，是梦三必须依赖的包内子模块，
+没有单独关闭开关。实现及验证状态见
+[手牌 UI 子扩展说明](ui-hand-subextension.md)。
+下文保留规划与完整游戏验收项；隔离测试不等同于游戏内实测。
+
 ## 1. 背景与目标
 
 - 当前手牌 UI 与无名杀真实卡牌节点的关系