mirror of
https://github.com/motajs/template.git
synced 2026-10-30 04:40:18 +08:00
docs(09-31): add TextContent loc/key cleanup plan and execution summary (code uncommitted)
This commit is contained in:
parent
310a5894d1
commit
95f0116d16
@ -0,0 +1,48 @@
|
||||
{
|
||||
"head": "ff0f729cfc7065c00a57d2bf5fd8eb4ff8b74071",
|
||||
"hashes": {
|
||||
"packages-user/client-base/src/components/scroll.tsx": "74fb21f5c9d9c7329e99b8345ba6d7ee7b1eae48",
|
||||
"src/client/ui/settings.tsx": "c5cca14cde8ba813ac4ef5e624e8b359470c472d",
|
||||
"src/client/ui/index.ts": "4e3950598b1beee23753a5556d8e8c82eb21bc57",
|
||||
"src/client/misc/hotkey.ts": "6e884ab4f36cdff958a3490697406a00f67d2e7f",
|
||||
"src/client/ui/inputBox.tsx": "3eb246200ae3300f9f221a8e0e9142e5a612a696",
|
||||
"src/client/ui/waitBox.tsx": "3d5ad7f304e1db0e1b1e75fe76801ec37b917c9f"
|
||||
},
|
||||
"textbox": "b17e988d77c3a81fe3ce3250940e31a9774f8dfb",
|
||||
"dirty": [
|
||||
"AGENTS.md",
|
||||
"dev.md",
|
||||
"docs/advanced/iii/anon-tokyo.md",
|
||||
"docs/advanced/iii/core-state.md",
|
||||
"docs/advanced/iii/event-system.md",
|
||||
"docs/advanced/iii/index.md",
|
||||
"docs/advanced/iii/loading-system.md",
|
||||
"docs/advanced/iii/passability-and-pathfinding.md",
|
||||
"docs/advanced/iii/plugin-internals.md",
|
||||
"docs/advanced/iii/replay-internals.md",
|
||||
"packages-user/client-base/src/index.ts",
|
||||
"packages-user/client-base/src/map/__test__/rendererGate.test.ts",
|
||||
"packages-user/client-base/src/map/renderer.ts",
|
||||
"packages-user/client-base/src/map/shader/map.frag",
|
||||
"packages-user/client-base/src/map/status.ts",
|
||||
"packages-user/client-base/src/map/types.ts",
|
||||
"packages-user/client-base/src/map/vertex.ts",
|
||||
"packages-user/client-base/src/setting/index.ts",
|
||||
"packages-user/client-base/src/setting/types.ts",
|
||||
"src/client/ui/__test__/uiContainerGate.test.ts",
|
||||
"src/client/ui/book.tsx",
|
||||
"src/client/ui/bookDetail.tsx",
|
||||
"src/client/ui/equipbox.tsx",
|
||||
"src/client/ui/hotkey.tsx",
|
||||
"src/client/ui/toolbox.tsx"
|
||||
],
|
||||
"eslint": [],
|
||||
"typecheck": [
|
||||
"src/client/ui/book.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'.",
|
||||
"src/client/ui/equipbox.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'.",
|
||||
"src/client/ui/equipbox.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'.",
|
||||
"src/client/ui/equipbox.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'.",
|
||||
"src/client/ui/toolbox.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'.",
|
||||
"src/client/ui/toolbox.tsx error TS2322: Type 'number' is not assignable to type 'AllNumbers | keyof IdToNumber'."
|
||||
]
|
||||
}
|
||||
483
.planning/phases/09-minimum-browser-runnable/09-31-PLAN.md
Normal file
483
.planning/phases/09-minimum-browser-runnable/09-31-PLAN.md
Normal file
@ -0,0 +1,483 @@
|
||||
---
|
||||
phase: 09-minimum-browser-runnable
|
||||
plan: 31
|
||||
type: execute
|
||||
# 26：沿用本阶段既有计划的波次编号，使本计划排在 09-01..09-30 之后（D-01 增量派发，计划累积）
|
||||
# depends_on 为空：本计划触碰的 6 个代码 / 测试文件没有任何并发计划在本波次触碰，故结构上独立；
|
||||
# 运行在最后的波次只是「排期在后」，不是「依赖前序计划」
|
||||
wave: 26
|
||||
depends_on: []
|
||||
# 09-31-BASELINE.json 由 Task 1 在收到「可以执行」之后、编辑任何代码之前写出（Task 0 只汇报、不写文件）
|
||||
files_modified:
|
||||
- packages-user/client-base/src/components/textbox.tsx
|
||||
- src/client/ui/book.tsx
|
||||
- src/client/ui/bookDetail.tsx
|
||||
- src/client/ui/equipbox.tsx
|
||||
- src/client/ui/toolbox.tsx
|
||||
- src/client/ui/hotkey.tsx
|
||||
- src/client/ui/__test__/uiContainerGate.test.ts
|
||||
- .planning/phases/09-minimum-browser-runnable/09-31-PLAN.md
|
||||
- .planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json
|
||||
- .planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md
|
||||
autonomous: false
|
||||
requirements: []
|
||||
estimate:
|
||||
# 未校准估算（confidence: low），SUMMARY 须声明这一点。
|
||||
# 本计划改三件互不新增行为的事：①`TextContent` 让 `props.loc` 响应式、宽度恒取 `props.width`；
|
||||
# ②`bookDetail` 用 `cumsum` 取代手写累加；③五个 UI 文件删除全部 37 个 `key`（13+2+9+8+5）。
|
||||
# 不新增入口、不改数据逻辑、不改按键注册、不改 `Scroll`。
|
||||
# 主要成本在理解 `TextContent` 既有的打字机 / 高度回调时序、5 个文件逐处删 key、重写闸门断言、跑两轮 eslint 与一次整仓 vue-tsc。
|
||||
# tokens 取 raw 的 2 倍，与 09-19..09-30 的换算口径一致；仍属未校准。
|
||||
# tasks 只计 4 个 auto 执行任务（Task 1–4）；Task 0 是 blocking-human 汇报关卡，不写文件、不编辑代码，不计入估算。
|
||||
tokens: 70000
|
||||
raw_tokens: 35000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
must_haves:
|
||||
truths:
|
||||
- "**本计划第一个 block 点是 Task 0 的 `blocking-human` 汇报关卡（AGENTS.md 硬要求 / D-03）**：先汇报「让 `TextContent` 的 `loc` 响应式、`bookDetail` 改用 `cumsum`、五个 UI 文件删除全部 `key`」的要做什么 / 为什么 / 大致怎么做 / 影响范围，逐条说明 `TextContent` 的新语义（只同步 x/y/ax/ay、宽度恒取 `props.width`、高度按 `autoHeight` 分流）、`cumsum` 替换手写累加的等价性、37 个 `key` 的删除清单与不放回的理由、渲染器 `removeChild` 被实现为 `destroy` 的问题按 `dev.md` 视为「假定已修复」而不做 workaround、验证方式，以及「不做浏览器 UAT / 执行器不提交任何代码」两条铁律，然后停下等待用户恰好回复「可以执行」"
|
||||
- "**只动 `files_modified` 的 10 个路径**：`textbox.tsx`、5 个 UI 文件、1 个既有闸门测试、3 个 `.planning` 产物；不改 `packages-user/client-base/src/components/scroll.tsx`、不改 `src/client/ui/settings.tsx` / `src/client/ui/index.ts` / `src/client/misc/hotkey.ts`、**不改 `src/client/ui/inputBox.tsx` / `waitBox.tsx`**、不改任何其它 UI / 依赖 / 配置"
|
||||
- "**`TextContent` 的 `props.loc` 变为响应式，且语义按下述四条固定**：①新增一个专用 watcher（`watch(() => props.loc, () => { updateLoc(); })`）或把它折进既有 `watch(props, …)`，位置同步不得依赖挂载时的一次性拷贝；②`updateLoc` 产出的 `loc.value` 为六元组，x / y / ax / ay 只来自传入的 `props.loc`（缺省时退回既有 `loc.value` 的同位），宽度恒为 `props.width`（不再用传入 `loc[2]`），高度在 `props.autoHeight` 为真时用 `getHeight()` 的实测值、否则用传入 `loc[3]`；③既有的 `typer` / `retype` / `showAll` / `getHeight` / `renderContent` / `emit('updateHeight', height)` / `expose` 行为一字不改；④`bookDetail` 之外没有任何组件被改（`Textbox` 仍原样使用 `TextContent`）"
|
||||
- "**`bookDetail` 用 `cumsum` 取代手写累加**：从 `@motajs/common` 与 `ITileLocator` 一起导入 `cumsum`；在 `specialRows` 内先由 `specials.value.map(…)` 得到每行行高（含标题高度与行间隔），再用 `cumsum(hs)` 一次得到累计结束位置，行顶由「结束位置 − 行高」得出；文件内不再出现 `top +=`、不再用 `for` 累加 `top`；行高数组与结束位置数组用短名（`hs` / `ends`），索引用 `i`"
|
||||
- "**`bookDetail` 渲染不再用 `key` 触发重挂载**：`Scroll` 内为 `specialRows.value.map(row => [<text … />, <TextContent … />])`，两个元素都没有 `key`；`TextContent` 的 `loc` 用一个每次求值都新建的数组（`[0, row.textTop, SPECIAL_WIDTH, row.textHeight]`），靠 `props.loc` 的新引用触发响应式位置同步；`autoHeight` / `onUpdateHeight` / `textHeights` / `updateTextHeight` / `SPECIAL_MIN_HEIGHT` 回退全部保留；描述 `TextContent` 的旧两行「复制一次 props.loc / 用 key 重挂载」注释按用户本次明确要求**替换**为一行说明「已按 `props.loc` 响应式同步，无需重挂载」"
|
||||
- "**五个 UI 文件的全部 `key` 都被删除，且不再放回**：`book` 13 个（`hit-` / `icon-` / `name-` / `special-` / `hp-` / `atk-` / `def-` / `money-` / `exp-` / `dmg-` / `crit-` / `reduce-` / `def1-`）、`bookDetail` 2 个（`label-` / `<code>-<textTop>-<textHeight>`）、`equipbox` 9 个（`name-` / `value-` / `delta-` / `slot-` / `icon-` / `name-` / `row-` / `icon-` / `name-`）、`toolbox` 8 个（两列各 `row-` / `icon-` / `name-` / `count-`）、`hotkey` 5 个（`hit-` / `name-` / `name-` / `box-` / `text-`）；删完后五个文件在去注释源码里 `key={` 出现次数为 0，且没有任何元素因为「可能的状态复用」把 `key` 重新加回来（本计划不存在真正需要身份的静态列表）"
|
||||
- "**`key` 删除不改变列表结构与顺序**：五个文件仍用内联 `.map()` 返回同级元素数组（`book` 13 元组、`bookDetail` 2 元组、`equipbox` 三处 3 元组、`toolbox` 两处 4 元组、`hotkey` 左 2 元组 / 右 1 + 内层 2 元组），`Scroll` 的直接子元素仍是平铺元素，`Scroll` 内仍无 `container`、无 `hidden=`、无包裹层，每个列表段落仍保留既有的 `{/* … */}` 职责注释"
|
||||
- "**行为零变化**：`book` / `bookDetail` 的 0 值回退、`bookDetail` 的高度测量与 `SPECIAL_MIN_HEIGHT` 回退、`equipbox` 的拖拽 / 悬停 / 再点穿戴、`toolbox` 的点击与「再点使用」、`hotkey` 的捕获 / 写回 / 分组切换 / 无入口 / 无持久化 / 无冲突检测 / 无恢复默认，全部保持 09-30 的日志口径；`startPress` / `movePress` / `endPress` / `clickItem` / `selectGroup` / `selectKey` / `onKeyDown` / `onKeyUp` 逻辑体零改动"
|
||||
- "**不做 key 的替代 workaround**：不得为了「避免列表元素复用」而新增 `key`、Fragment、包裹 `container`、条件渲染或 `hidden` 开关；渲染系统当前 `removeChild` 被实现为 `destroy` 导致无法重新挂载的问题，按 `dev.md` 第 123 行**记录为已知问题、假定修复**，不得在本计划里规避"
|
||||
- "**验证是源码形状 + 静态检查，且如实声明未做浏览器验证**：更新 `src/client/ui/__test__/uiContainerGate.test.ts`——删除 13 个 `key` 前缀与「key 重挂载」断言，新增「五个文件无 `key={`」「`bookDetail` 用 `cumsum` 且无 `top +=`」「`textbox` 的 `props.loc` 响应式同步」三组，保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` 逐元素断言；每个 `it` 上方紧邻一行 `//` 注释；跑 eslint（只判 NEW，基线采集与比较用**同一组 7 个路径**）、`pnpm check:type`（整仓，只判改动文件内 NEW，过滤范围同样是**同一组 7 个路径**）、`hotkeySettingsGate.test.ts` 仍为绿、**6 个**受保护文件哈希 + `textbox.tsx` 改动前哈希与全仓脏文件快照范围闸门；**不做浏览器 UAT，不宣称任何视觉 / 滚动 / 点击 / 拖拽行为已验证**"
|
||||
- "**范围与纪律**：除用户本次明确授权的两处（`TextContent` 语义、删除描述 key 重挂载的注释）外，不修改任何既有注释或 jsDoc（只允许新增）；不改按键注册表；不改设置入口；不新增依赖；不执行构建；不顺手修复任何无关诊断；发现疑似问题只记录、不擅自登记为缺陷"
|
||||
artifacts:
|
||||
- path: packages-user/client-base/src/components/textbox.tsx
|
||||
provides: "`TextContent` 的 `props.loc` 响应式：新增 `watch(() => props.loc, () => { updateLoc(); })`；`updateLoc` 改为 `const [x = 0, y = 0, , h = 0, ax = 0, ay = 0] = props.loc ?? loc.value;` 与 `loc.value = [x, y, props.width, props.autoHeight ? height : h, ax, ay];`；保留 `typer` / `retype` / `showAll` / `getHeight` / `renderContent` / `emit('updateHeight', height)` / `expose` / 既有 `watch(props, …)`；不动 `Textbox` 组件与 `TextboxStore`"
|
||||
- path: src/client/ui/bookDetail.tsx
|
||||
provides: "从 `@motajs/common` 导入 `cumsum`；`specialRows` 改为「行高 `hs` → `ends = cumsum(hs)` → `specials.value.map((special, i) => …)`」并用 `ends[i] - hs[i]` 得行顶，无 `top +=`；渲染为 `specialRows.value.map(row => [<text …/>, <TextContent …/>])`，两者均无 `key`，`TextContent` 的 `loc` 为每次新建数组；旧的「复制一次 / key 重挂载」两行注释替换为一行「已按 `props.loc` 响应式同步，无需重挂载」；`textHeights` / `updateTextHeight` / `watch` / `SPECIAL_MIN_HEIGHT` / `autoHeight` / `onUpdateHeight` / 0 回退保留"
|
||||
- path: src/client/ui/book.tsx
|
||||
provides: "删除 13 个 `key`；其余 13 个同级元素、`loc`、`noevent`、`onClick={() => openDetail(view)}`、0 值回退、`specialText(base)`、五条基础数值文案、三条既有 `//` 与 `{/* … */}` 注释全部不动；仍为 `enemies.value.map((view, i) => [...])`"
|
||||
- path: src/client/ui/equipbox.tsx
|
||||
provides: "删除 9 个 `key`；三处内联 `.map()` 的三元组结构、`hidden` 分流、空文本 / 0 回退、`startPress` / `movePress` / `endPress`、悬停判定、4 个 `*_SCROLL_LOC` 与 `ElementLocator` 导入全部不动"
|
||||
- path: src/client/ui/toolbox.tsx
|
||||
provides: "删除 8 个 `key`；两处内联 `.map()` 的四元组结构、`hidden={!!current}` 提示位置、`TextContent` 空文本回退、`clickItem` 的再点使用全部不动"
|
||||
- path: src/client/ui/hotkey.tsx
|
||||
provides: "删除 5 个 `key`；两栏内联 `.map()`（外层 `i`、内层 `j`）、`commandRows` / `combinationLists` / `ICommandRow`、`selectKey(row.command, j)`、选中边框、根 `nocache`、捕获 / 写回 / 分组切换全部不动"
|
||||
- path: src/client/ui/__test__/uiContainerGate.test.ts
|
||||
provides: "删除 13 个 `key` 前缀与两个 key 重挂载注释 / `key` 模板断言；新增「五文件去注释后无 `key={`」「`bookDetail` 含 `cumsum(` / `ends[i] - hs[i]` 且无 `top +=`」「`textbox` 含 `watch(() => props.loc`、`props.autoHeight ? height : h`、`props.width`、`emit('updateHeight', height)`」三组；`book` 每行改为按标签计数（11 `text` + 1 `icon` + 1 `g-rect` = 13）；保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` / `nocache` / `*_SCROLL_LOC` 断言；每个 `it` 上方紧邻一行 `//`"
|
||||
- path: .planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json
|
||||
provides: "Task 1 在收到「可以执行」之后、编辑任何代码之前写出的机器可读基线：`{ head, hashes, textbox, dirty, eslint, typecheck }`；`hashes` 保护 **6 个**文件（`scroll.tsx` / `settings.tsx` / `ui/index.ts` / `misc/hotkey.ts` / `inputBox.tsx` / `waitBox.tsx`）；`textbox` 单独记录 `textbox.tsx` 改动前的 `git hash-object`（用于证明它**确实被改**，不作为「不得变化」的闸门）；`dirty` 是当时 `git status --porcelain -uall` 的全仓脏文件快照（去掉 `.planning/`）；只写一次"
|
||||
- path: .planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md
|
||||
provides: "执行摘要：逐处改动（`TextContent` 新语义、`cumsum` 等价性、37 个 key 的删除清单）、未保留任何 key 的说明、「`removeChild`/`destroy` 已知问题按 `dev.md` 假定修复、未做 workaround」声明、门禁结果、未做浏览器 UAT 声明、估算未校准声明、执行器 0 次代码提交声明；**先跑完所有门禁再写本文件，写完后再跑摘要闸门**"
|
||||
- path: .planning/phases/09-minimum-browser-runnable/09-31-PLAN.md
|
||||
provides: "本计划文件本身"
|
||||
key_links:
|
||||
- "`TextContent` 的 `updateLoc` ← `props.loc` 新引用 — 这是本计划唯一的跨组件契约：只要 `bookDetail` 每次求值都传新数组、`TextContent` 只按传入的 x/y/ax/ay 覆盖自己的 `loc`，行位置就能在高度回调后自行收敛；任何一方退回「挂载时拷贝一次」都会让描述重新重叠"
|
||||
- "`textHeights` → `specialRows` → `TextContent.loc` → `props.loc` watcher → `updateLoc` → `emit('updateHeight')` → `updateTextHeight`（同值早退）— 这条闭环必须稳定：`updateTextHeight` 的「同值不写」是本计划唯一的防循环保险，不得删除"
|
||||
- "`cumsum(hs)` 的返回值是**累计结束位置**（不是偏移），因此行顶必须是 `ends[i] - hs[i]`；写成 `ends[i]` 会把每行往下推一个行距，且不会报错"
|
||||
- "37 个 `key` 删除 ← `dev.md` 第 122–123 行新规 — 列表无状态、顺序固定时不得加 `key`；渲染器 `removeChild`/`destroy` 问题假定修复，不得用 `key` 规避"
|
||||
- "`Scroll` 的直接子元素 → 内联 `.map()` 返回的数组 — 删除 `key` 不得伴随任何容器 / Fragment 包裹；一旦重包容器，「Scroll 内无 container」闸门失败"
|
||||
- "受保护文件哈希（`scroll.tsx` / `settings.tsx` / `ui/index.ts` / `misc/hotkey.ts` / `inputBox.tsx` / `waitBox.tsx`）+ `textbox.tsx` 的前后哈希差异 — 证明本计划只改 `TextContent`、没有改 `Scroll`、设置入口、按键注册与指定不动的两个 UI"
|
||||
assumptions:
|
||||
- "**`dev.md` 新行长这样（本计划的直接依据）**：第 122 行「`key` 仅在列表会重排、插入、删除且需要保留元素身份（尤其是有状态组件）时使用；无状态、顺序固定的列表不要添加 `key`」；第 123 行「渲染系统当前存在 `removeChild` 被实现为 `destroy` 导致无法重新挂载的问题；在该问题修复前，一律按「元素可以正常重新挂载」假设编写代码，不得为规避该问题添加 `key` 或改用其他 workaround」"
|
||||
- "**`TextContent` 当前实现（`packages-user/client-base/src/components/textbox.tsx:122-170`）**：`loc = shallowRef(props.loc?.slice() ?? [])` 只在 setup 拷一次；`updateLoc` 仅在 `props.autoHeight` 时把它改成 `[x, y, width, height, ax, ay]`，其中 `width` 取自 `loc.value[2]`（即传入的 `loc[2]`），非 `props.width`；`retype()` 末尾调用 `updateLoc()`；不存在监听 `props.loc` 的 watcher。因此「改 props.loc 不移动元素」正是 `bookDetail` 当初用 `key` 重挂载的原因"
|
||||
- "**`cumsum` 的语义**：`packages/common/src/utils/func.ts` 的 `cumsum(seq)` 返回 `[a0, a0+a1, …]`，即**累计结束位置**而不是偏移量；`@motajs/common` 已从 `packages/common/src/index.ts` 对外导出（`09-30` 的 `bookDetail` 已从该包导入 `ITileLocator`）"
|
||||
- "**37 个 `key` 的分布（规划日实测）**：`book.tsx` 13、`bookDetail.tsx` 2、`equipbox.tsx` 9、`toolbox.tsx` 8、`hotkey.tsx` 5，合计 37；其中没有一个是「真正需要保留身份」的列表（全部是固定顺序的数据映射，`TextContent` 的身份需求由响应式 loc 解决）"
|
||||
- "**`watch(props, …)` 仍会因 `loc` 变化触发一次 `retype()`**：这是既有行为（此前 loc 变化时是 `key` 重挂载，同样会重建 `TextContent`），本计划不改这条 watcher；新增的专用 watcher 只做位置同步，不重复触发打字机；若执行期发现两条 watcher 造成重复渲染，只允许在专用 watcher 内去重，不得改动既有 watcher 的 retype 语义"
|
||||
- "**`bookDetail` 的渲染 map 只取一个参数**：行顶已由 `specialRows` 的 `cumsum` 结果给出，取第二个参数 `i` 会因未使用而违反 `dev.md`（未使用参数应直接不填）并触发 eslint；因此渲染写成 `specialRows.value.map(row => […])`，`i` 只出现在 `specialRows` 计算内部（`specials.value.map((special, i) => …)`）"
|
||||
- "**范围闸门会看到 09-29 / 09-30 的未提交改动**：`e2415a7a48d9a9e9d2f886e00c10ca51e91340d1` 是「09-30 结束时的 HEAD」，只作历史记录、可能已经过期；所有闸门一律使用 `09-31-BASELINE.json` 中 Task 1 现场采集的 `head`，**不使用这个字面量**。09-29 / 09-30 的 5 个 UI 文件与 `uiContainerGate.test.ts` 可能已在脏树中；`textbox.tsx` 在基线采集时仍是干净的，Task 1 编辑之后才变脏。因此范围闸门只能证明「没有新增范围外路径」；内容是否改到位由源码形状闸门负责，SUMMARY 必须如实说明"
|
||||
- "**`hotkeySettingsGate.test.ts` 必须仍为绿**：它断言 `hotkey.tsx` 去注释后不匹配 `/<g-rect[\\s>]/`、不含持久化调用、监听在捕获阶段、含 `setKeyCombination(` / `iterateKeyCombinations(` / `iterateGroups(` / `@common/exit` / `返回`。删 `key` 不触碰这些语义，也不改该测试文件"
|
||||
- "**`keyAdaptationGate.test.ts` 是既存失败**（09-30 SUMMARY 记录：15 个用例 5 个失败，改动前即如此），不在本计划范围；不修、不以它为绿、不声称全部既有闸门为绿"
|
||||
- "**测试读取跨包源码的方式**：`uiContainerGate.test.ts` 用 Vite 的 `?raw` 导入 `../../../../packages-user/client-base/src/components/textbox.tsx?raw`（仓库根即 Vite root，`packages-user/` 在 root 内）。若该导入在运行时报错，**停下上报**；允许的兜底是用 `node:fs` 的 `readFileSync` 读同一路径，并在 SUMMARY 记录为偏离，不得改读别的文件"
|
||||
- "**dev.md 约束**：不得出现 `import type`；尽量避免 `?.`；对象类型必须先声明 `interface`；`//` 后留空格；既有注释只增不改（本次两处 key 重挂载注释是用户明确授权的例外）；导入之间不得夹注释与空行；换行 CRLF；Prettier 配置 `printWidth: 80` / `tabWidth: 4` / 单引号 / 无尾逗号"
|
||||
- "**无 RESEARCH / 无 VALIDATION**：本 run 不存在 `09-31-RESEARCH.md` 与 `09-31-VALIDATION.md`；本阶段无 requirement ID，Nyquist 验证不适用，不创建这两类文件"
|
||||
- "**波次与独立性（`wave: 26` / `depends_on: []`）**：本计划按 D-01 追加在 09-01..09-30 之后；它改动的文件没有任何**并发**计划在本波次触碰，`depends_on: []` 表示结构独立；`wave` 只是排期编号"
|
||||
prohibitions:
|
||||
- "不得在用户恰好回复「可以执行」之前执行任何任务或派发执行子代理（AGENTS.md / D-03）"
|
||||
- "**不得运行任何 git 写命令**：`git add` / `commit` / `stash` / `checkout` / `restore` / `worktree` / `reset` 一律禁止；代码改动留在工作树，是否提交由用户另行决定；三个 `.planning` 产物可能被编排器按 `commit_docs: true` 聚合提交，不属于本计划的代码提交"
|
||||
- "不得修改 `packages-user/client-base/src/components/scroll.tsx`（不允许通过改 `Scroll` 来「适配」缺 key 的列表）"
|
||||
- "不得修改 `src/client/ui/settings.tsx`、`src/client/ui/index.ts`、`src/client/misc/hotkey.ts`（设置入口、UI 导出清单、按键注册）"
|
||||
- "**不得修改 `src/client/ui/inputBox.tsx` 与 `waitBox.tsx`**（用户明确要求不动）"
|
||||
- "不得修改 `Textbox` 组件、`TextboxStore`、`ITextContentConfig` / `TextContentTyper` 的接口与实现；`textbox.tsx` 只允许改 `TextContent` 的 `updateLoc` 与其 watcher"
|
||||
- "不得在 `Scroll` 内新增任何 `container` / `template` / 包裹层 / Fragment；不得为「让列表稳定」而重新引入 `key`"
|
||||
- "不得把 `key` 换成 `index` 形式的 key、`v-for` 或其它等价身份标记；删除就是删除"
|
||||
- "不得删除 `updateTextHeight` 的「同值不写」早退，也不得让 `updateLoc` 在每次调用时都无条件 `emit('updateHeight')` 之外再额外触发重排"
|
||||
- "不得修改除下述两处以外的任何既有注释或 jsDoc：①`bookDetail` 中描述「复制一次 props.loc / key 重挂载」的两行；②若执行期为对齐 cumsum 必须改动的紧邻注释，须先在 SUMMARY 记录并在 Task 4 汇报。其余既有注释只增不改"
|
||||
- "不得新增依赖、不得执行安装命令；不得跑 `build:game` / `build:packages` / `build:lib`"
|
||||
- "不得改变行为口径：0 值回退、`SPECIAL_MIN_HEIGHT` 回退、`equipbox` 拖拽 / 悬停、`toolbox` 再点使用、`hotkey` 捕获 / 写回 / 无入口 / 无持久化 / 无冲突 / 无恢复默认、透明命中层 + `noevent` 全部保持"
|
||||
- "不得越界处理发现的其它疑似问题；只记录、不擅自修复、不擅自登记为缺陷"
|
||||
open_items:
|
||||
- "**OI-1（命名报备，按 AGENTS.md 在 Task 0 一并报备）**：新增/改名的**局部标识符**为 `textbox.tsx` 的 `h`（传入的 `loc[3]`）与解构出的 `x` / `y` / `ax` / `ay`；`bookDetail.tsx` 的 `hs`（每行行高）与 `ends`（`cumsum` 结果）；`specialRows` 内部索引用 `i`。**不新增**任何文件作用域常量、`interface`、导出函数；**删除** 37 个 `key` 表达式但保留 `base` / `row` / `item` / `attr` / `id` / `group` / `keys` / `j` 等既有局部名。公共 / 受保护 / 导出命名、`GameUI` id、`selectKey` 签名一律不改。**你若要求其它命名，执行前按你的命名整体替换，方案形态不变**"
|
||||
- "**OI-2（执行期硬停条件）**：若 `TextContent` 的响应式 loc 在浏览器 / 单测环境下出现「位置更新后高度被重置」或「`updateHeight` 无限回调」，**必须停下上报**，不得删除 `updateTextHeight` 的同值早退，也不得改回 `key` 或改 `Scroll`"
|
||||
- "**OI-3（已知遗留，只记录、不修复）**：①渲染系统 `removeChild` 被实现为 `destroy` 导致无法重新挂载的问题仍存在，本计划按 `dev.md` **假定已修复**、不做任何 workaround；②浏览器 UAT 全程跳过，滚动、内存、点击命中、拖拽手感、位置收敛由用户自行验证；③`book.tsx` 的过期 TODO（写着「留空」，与 0 值回退矛盾）按 AGENTS.md 原样保留；④`bookDetail` 中「一次遍历累加出每行位置」的既有注释保留不改（虽已改为 `cumsum`，语义仍是一次累加，且 AGENTS.md 禁止擅改既有注释）；⑤`keyAdaptationGate.test.ts` 为既存失败，不在本计划范围；⑥`src/client/ui/bookDetail.tsx:58` 的 `/** 描述文本的实测高度，同时用于 TextContent 的 key */` 与 `:108` 的 `// 同值不写，避免高度回调与 key 重挂载互相触发` 在删 key 后已成为**过期注释**，按 AGENTS.md 原样保留、不改一字，仅在 SUMMARY / 汇报中登记；⑦`TextContent` 另有 8 个只读使用方（`inputBox` / `waitBox` / `statusBar` / `statistics` / `choices` / `src/client/plugin/shop/shop` / `components/input` / `components/misc`），本计划不改；其尺寸口径不变，`choices` 等 computed `loc` 调用点的 x / y 会随 `loc` 变化响应式跟随（预期效果）"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: key={ -->
|
||||
<!-- planner-discipline-allow: key= -->
|
||||
<!-- planner-discipline-allow: container -->
|
||||
<!-- planner-discipline-allow: top += -->
|
||||
<!-- planner-discipline-allow: width = props.width -->
|
||||
<!-- planner-discipline-allow: loc.value[2] -->
|
||||
<!-- planner-discipline-allow: VNode -->
|
||||
|
||||
<objective>
|
||||
Phase 9 · 第 31 个计划（新增的独立增量）——**让 `TextContent` 的位置真正响应式、把 `bookDetail` 的累加交给 `cumsum`、按新的 `dev.md` 规则删掉五个 UI 文件里的全部 `key`**。
|
||||
|
||||
**要解决的问题：**
|
||||
|
||||
1. `TextContent` 只在 setup 时复制一次 `props.loc`，之后改 `loc` 不会移动元素；`bookDetail` 因此被迫用 `key` 重挂载来「推动」每一行描述。同时 `updateLoc` 的宽度取自传入的 `loc[2]` 而不是 `props.width`，`Textbox` 内嵌的 `TextContent` 会拿到整框宽度。
|
||||
2. `bookDetail` 的 `specialRows` 用手写 `let top = 0; … top += …` 累加每行位置，项目已有 `cumsum` 可以直接表达。
|
||||
3. `dev.md` 新增规则：无状态、顺序固定的列表不要加 `key`；渲染器的 `removeChild`/`destroy` 问题假定修复、不得用 `key` 规避。五个 UI 文件里仍有 37 个 `key`。
|
||||
|
||||
**做法（用户决定，不得扩大）：**
|
||||
|
||||
1. **`TextContent`（`packages-user/client-base/src/components/textbox.tsx`）**：保持 `typer` / 打字机 / 高度回调 / `expose` 全部不动；新增专用 watcher 监听 `() => props.loc` 并调用 `updateLoc`；`updateLoc` 改为只从传入 `loc` 取 x / y / ax / ay，宽度恒取 `props.width`，高度在 `autoHeight` 时取 `getHeight()`、否则取传入 `loc[3]`；继续 `emit('updateHeight', height)`。
|
||||
2. **`bookDetail`**：从 `@motajs/common` 导入 `cumsum`；行高数组 `hs` → `ends = cumsum(hs)` → `specials.value.map((special, i) => …)` 用 `ends[i] - hs[i]` 得行顶，删除 `top +=`；渲染 `specialRows.value.map(row => [<text …/>, <TextContent …/>])`，两者无 `key`，`TextContent` 的 `loc` 每次新建数组；旧的「复制一次 / key 重挂载」两行注释替换为一行「已按 `props.loc` 响应式同步，无需重挂载」。
|
||||
3. **五个 UI 文件删除全部 `key`（37 个）**：`book` 13、`bookDetail` 2、`equipbox` 9、`toolbox` 8、`hotkey` 5；列表结构、元素顺序、属性、`noevent`、`loc`、事件回调一律不变；不新增 Fragment / 容器 / 条件渲染 / `hidden` 开关。
|
||||
4. **验证**：更新 `uiContainerGate.test.ts`——删除 13 个 `key` 前缀与 key 重挂载断言，新增「无 `key={`」「`cumsum` 且无 `top +=`」「`textbox` 响应式 loc」三组，保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent`；eslint 只判 NEW（同一组 7 个路径）、`pnpm check:type` 只判改动文件内 NEW（同一组 7 个路径）、`hotkeySettingsGate` 仍为绿、6 个受保护文件哈希 + `textbox.tsx` 前后哈希差异、全仓脏文件范围闸门；**不做浏览器 UAT，不提交代码**。
|
||||
|
||||
**明确不做：** 不接入口、不做持久化、不做冲突检测 / 恢复默认、不改按键注册、不改设置入口、不改 `Scroll`、不改 `inputBox.tsx` / `waitBox.tsx`、不改任何行为口径、不用 `key` 规避渲染器的 `destroy` 问题。
|
||||
|
||||
**约束：** 只动 `files_modified` 的 10 个路径；除用户明确授权的两处（`TextContent` 语义、删除描述 key 重挂载的注释）外不改既有注释与 jsDoc；不新增依赖；不新增文件作用域标识符；不顺手修复任何无关诊断。
|
||||
|
||||
**修改方式声明（AGENTS.md）：** 本计划的全部文件写入（写基线、改 `textbox.tsx`、改 5 个 UI 文件、更新 1 个闸门测试、写摘要）由**派发子代理（`gsd-executor`）执行**，非内联执行；除 `files_modified` 外无任何写入。**Task 0 只汇报、不写任何文件**；`09-31-BASELINE.json` 是 **Task 1 在收到「可以执行」之后、编辑任何代码之前的第一步**写出（只写一次）。「开始执行」的界限仍是「可以执行」四个字。
|
||||
|
||||
**可见跳过：** spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip)。本阶段无 requirement ID，不创建 RESEARCH.md / VALIDATION.md，Nyquist 验证不适用。
|
||||
</objective>
|
||||
|
||||
## 本计划产出物（Artifacts this plan produces）
|
||||
|
||||
| 类型 | 名称 / 路径 | 说明 |
|
||||
|------|-------------|------|
|
||||
| 修改 | `packages-user/client-base/src/components/textbox.tsx` | `TextContent`：`props.loc` watcher + `updateLoc` 新语义（x/y/ax/ay 取传入 loc、宽度恒 `props.width`、高度按 `autoHeight` 分流）；其余不动 |
|
||||
| 修改 | `src/client/ui/bookDetail.tsx` | `cumsum` 取代手写累加；渲染无 `key`；`TextContent` 的 `loc` 每次新建；旧重挂载注释替换为一行 |
|
||||
| 修改 | `src/client/ui/book.tsx` | 删除 13 个 `key`；其余一律不动 |
|
||||
| 修改 | `src/client/ui/equipbox.tsx` | 删除 9 个 `key`；拖拽 / 悬停 / 显示分流不动 |
|
||||
| 修改 | `src/client/ui/toolbox.tsx` | 删除 8 个 `key`；再点使用 / 空文本回退不动 |
|
||||
| 修改 | `src/client/ui/hotkey.tsx` | 删除 5 个 `key`；捕获 / 写回 / 分组切换不动 |
|
||||
| 修改 | `src/client/ui/__test__/uiContainerGate.test.ts` | 删 key / 重挂载断言，新增无 key、cumsum、textbox 响应式 loc 三组；其余保留 |
|
||||
| 基线 | `.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json` | `head` + **6 个**受保护文件哈希 + `textbox.tsx` 改动前哈希 + 全仓脏文件快照 + eslint / typecheck 基线 |
|
||||
| 交付 | `.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md` | 执行摘要、门禁结果、未 UAT / 0 次代码提交声明 |
|
||||
| 计划 | `.planning/phases/09-minimum-browser-runnable/09-31-PLAN.md` | 本文件 |
|
||||
|
||||
## 覆盖审计（Multi-Source Coverage Audit）
|
||||
|
||||
| 源 | 条目 | 覆盖位置 |
|
||||
|----|------|----------|
|
||||
| GOAL（ROADMAP §Phase 9） | 「可在浏览器中运行并验证的最小版本」伞目标 | 本增量不新增入口、不做浏览器验证；修正 `TextContent` 位置语义与列表 `key` 规则，SUMMARY 如实记录 |
|
||||
| REQ | 本阶段无 requirement ID（`requirements: []`） | Nyquist 不适用 |
|
||||
| RESEARCH | 本 run 无 RESEARCH.md / 本计划无 DISCOVERY.md | 不适用 |
|
||||
| CONTEXT D-01 | 增量派发，一个任务一个计划 | 本计划即该次派发的唯一计划，不拆分 |
|
||||
| CONTEXT D-02 | 计划可累积追加 | plan 31，排在 09-01..09-30 之后（`wave: 26` 只是排期编号） |
|
||||
| CONTEXT D-03 | 执行前必须先汇报并等待「可以执行」 | Task 0（`blocking-human`），`autonomous: false` |
|
||||
| CONTEXT D-04 | 新命名必须先反馈获批 | OI-1（只改局部标识符，不新增文件作用域命名） |
|
||||
| CONTEXT D-06 | 范围由用户界定，不擅自扩大 | `files_modified` 10 项 + 范围闸门 + **6 个**受保护文件哈希 |
|
||||
| 用户要求 1 | `TextContent` 的 `props.loc` 响应式；只更新 x/y/ax/ay；宽度恒 `props.width`；高度按 `autoHeight` 分流 | Task 1 / Task 4 闸门 |
|
||||
| 用户要求 2 | `bookDetail` 用 `@motajs/common` 的 `cumsum` 取代手写累加 | Task 2 / Task 4 闸门 |
|
||||
| 用户要求 3 | 五个 UI 文件删除全部 `key`（13 / 2 / 9 / 8 / 5），不保留、不 workaround | Task 2 / Task 3 / Task 4 闸门 |
|
||||
| 用户要求 4 | `bookDetail` 传响应式 `loc`、`TextContent` 无 key | Task 2 / Task 4 闸门 |
|
||||
| 用户要求 5 | 行为保持（0 回退、hidden 分流、hotkey 全口径、equipbox 拖拽 / 悬停、toolbox use） | Task 2 / Task 3 约束 + Task 4 保留断言 |
|
||||
| 用户要求 6 | 不改 `inputBox.tsx` / `waitBox.tsx`、不改按键注册 | 受保护哈希 6 个（含这两个文件与 `misc/hotkey.ts`） |
|
||||
| 验证要求 | 更新 `uiContainerGate.test.ts`：删 key / 重挂载断言，新增无 key / cumsum / textbox 响应式 loc；保留 flat-Scroll / 无容器 / hidden 分流 / 0 回退 / noevent；eslint、类型 NEW-only（同一组 7 个路径）、`hotkeySettingsGate` 绿、哈希 / 范围、无提交、无浏览器 UAT | Task 4 |
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md
|
||||
@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/09-minimum-browser-runnable/09-CONTEXT.md
|
||||
@.planning/phases/09-minimum-browser-runnable/09-30-PLAN.md
|
||||
@.planning/phases/09-minimum-browser-runnable/09-30-SUMMARY.md
|
||||
@.planning/phases/09-minimum-browser-runnable/09-30-BASELINE.json
|
||||
@AGENTS.md
|
||||
@dev.md
|
||||
@packages/common/src/utils/func.ts
|
||||
@packages-user/client-base/src/components/scroll.tsx
|
||||
@packages-user/client-base/src/components/textbox.tsx
|
||||
@src/client/ui/book.tsx
|
||||
@src/client/ui/bookDetail.tsx
|
||||
@src/client/ui/equipbox.tsx
|
||||
@src/client/ui/toolbox.tsx
|
||||
@src/client/ui/hotkey.tsx
|
||||
@src/client/ui/__test__/uiContainerGate.test.ts
|
||||
@src/client/ui/__test__/hotkeySettingsGate.test.ts
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 0: 预执行汇报关卡 —— 汇报「`TextContent` 响应式 loc + `bookDetail` 用 `cumsum` + 五个 UI 文件删除 37 个 key」的要做什么 / 为什么 / 怎么做 / 影响范围、逐文件清单、新语义与验证方式，等待「可以执行」</name>
|
||||
<precondition>工作树仍是 09-30 结束时的状态，可用以下事实自检：`packages-user/client-base/src/components/textbox.tsx` 第 122-124 行为 `const loc = shallowRef<ElementLocator>((props.loc?.slice() as ElementLocator) ?? []);`，第 153-156 行为 `watch(props, () => { typer.setConfig(props); retype(); });`，第 162-170 行 `updateLoc` 内为 `const [x = 0, y = 0, width = props.width, , ax = 0, ay = 0] = loc.value;` 与 `loc.value = [x, y, width, height, ax, ay];`（宽度取自 `loc.value[2]`，且仅 `autoHeight` 时改写）；`src/client/ui/bookDetail.tsx` 第 125-140 行 `specialRows` 用 `let top = 0; … top += SPECIAL_LABEL_HEIGHT + textHeight + SPECIAL_GAP;`，第 186-187 行为两行「复制一次 `props.loc` / key 重挂载」注释，第 245-271 行渲染为 `specialRows.value.map(row => [<text … key={…} />, <TextContent … key={`${row.special.code}-${row.textTop}-${row.textHeight}`} />])`；五个 UI 文件的 `key={` 数量实测为 `book 13` / `bookDetail 2` / `equipbox 9` / `toolbox 8` / `hotkey 5`；`src/client/ui/__test__/uiContainerGate.test.ts` 已存在且 13 组断言全绿，其中 `book` 每行断言 13 个 `key` 前缀、`bookDetail` 断言 `key` 模板与两行重挂载注释。</precondition>
|
||||
<files>无（本任务不写任何文件，只做只读汇报；`09-31-BASELINE.json` 改由 Task 1 在获批后、改代码前写出）</files>
|
||||
<read_first>
|
||||
- .planning/phases/09-minimum-browser-runnable/09-30-SUMMARY.md（09-30 完成后的源码形状与门禁口径）
|
||||
- .planning/phases/09-minimum-browser-runnable/09-CONTEXT.md（D-01 增量派发、D-03 汇报关卡、D-04 命名批准、D-06 不扩大范围）
|
||||
- dev.md（第 122–123 行新增的 `key` 规则与 `removeChild`/`destroy` 假定修复条款；注释 / 类型 / 无 `?.` / CRLF 规范）
|
||||
- packages-user/client-base/src/components/textbox.tsx（`TextContent` 的 `loc` / `updateLoc` / `watch` / `typer` 时序）
|
||||
- packages/common/src/utils/func.ts（`cumsum` 返回累计结束位置）
|
||||
- src/client/ui/{book,bookDetail,equipbox,toolbox,hotkey}.tsx（37 个 `key` 的当前位置与列表结构）
|
||||
- src/client/ui/__test__/uiContainerGate.test.ts（本次要更新的既有闸门）
|
||||
- AGENTS.md（执行前须获批、命名先反馈、既有注释不得擅改、修改方式须预先声明）
|
||||
</read_first>
|
||||
<what-built>
|
||||
一份待批准的执行计划（`09-31-PLAN.md`）：让 `TextContent` 的 `props.loc` 真正响应式并修正宽度来源；让 `bookDetail` 用 `@motajs/common` 的 `cumsum` 计算行位置；按 `dev.md` 新规删除五个 UI 文件里的全部 37 个 `key`，且不做任何 workaround；用源码形状闸门 + eslint / 类型前后基线验收。
|
||||
</what-built>
|
||||
<action>
|
||||
**停下并向用户汇报，等待恰好回复「可以执行」后才继续；本任务不写任何文件（含 `09-31-BASELINE.json`——它由 Task 1 的第一步写出），不派发执行子代理。**
|
||||
|
||||
① **要做什么（三件事，互不新增行为）：**
|
||||
- **`TextContent` 的位置语义修正**（`packages-user/client-base/src/components/textbox.tsx`）：新增专用 watcher 监听 `() => props.loc`；`updateLoc` 改为只从传入 loc 取 x / y / ax / ay，宽度恒取 `props.width`，高度在 `autoHeight` 时取 `getHeight()`、否则取传入 `loc[3]`。
|
||||
- **`bookDetail` 的累加改为 `cumsum`**（`src/client/ui/bookDetail.tsx`）：导入 `cumsum`；先算每行行高 `hs`，再 `ends = cumsum(hs)`，行顶用 `ends[i] - hs[i]`；删除 `let top = 0` 与 `top +=`。
|
||||
- **删除五个 UI 文件的全部 `key`**（`book` 13、`bookDetail` 2、`equipbox` 9、`toolbox` 8、`hotkey` 5，共 37 个），并让 `bookDetail` 的 `TextContent` 靠响应式 `loc` 自行收敛位置，不再靠 key 重挂载。
|
||||
|
||||
② **为什么：**
|
||||
- `TextContent` 现在只在 setup 时把 `props.loc` 拷贝一次（`loc = shallowRef(props.loc?.slice() ?? [])`），之后改 `props.loc` 不会移动元素；`bookDetail` 正是因此才用「`code` + `textTop` + `textHeight`」当 key 强制重挂载。位置同步本该由组件自己响应，而不是由调用方靠重挂载推动。
|
||||
- 同一段 `updateLoc` 把宽度取自传入的 `loc[2]`，而 `Textbox` 内嵌的 `TextContent` 传入的 `loc` 是整框矩形、另有独立的 `width` 属性（内容宽度）。改为恒取 `props.width` 后，宽度来源唯一。
|
||||
- `bookDetail` 的手写 `top +=` 与项目已有的 `cumsum` 完全等价，且 `cumsum` 已在 `@motajs/common` 导出，不必自己维护累加变量。
|
||||
- `dev.md` 新增第 122 行：`key` 只在列表会重排 / 插入 / 删除且需要保留元素身份时使用，无状态、顺序固定的列表不要加；第 123 行：渲染器当前 `removeChild` 被实现为 `destroy` 导致无法重新挂载，但**在该问题修复前一律按「元素可以正常重新挂载」假设编写代码，不得为规避它添加 `key` 或改用其他 workaround**。这 37 个 key 全部是固定顺序的数据映射，属于该删除的范围。
|
||||
|
||||
③ **怎么写（严格按此范围）：**
|
||||
- **`textbox.tsx`（只改 `TextContent`）**：
|
||||
- 在 `updateLoc` 定义之后、紧随其后新增：`watch(() => props.loc, () => { updateLoc(); });`（不传 `deep`，靠新数组引用触发）。
|
||||
- `updateLoc` 改为：先 `const height = getHeight();`，再 `const [x = 0, y = 0, , h = 0, ax = 0, ay = 0] = props.loc ?? loc.value;`，再 `loc.value = [x, y, props.width, props.autoHeight ? height : h, ax, ay];`，最后保留 `emit('updateHeight', height);`。
|
||||
- **不改** `typer` / `retype` / `showAll` / `getHeight` / `renderContent` / `renderFunc` / 事件转发 / `expose` / 既有 `watch(props, …)`；**不改** `Textbox` 组件、`TextboxStore`、`TextContentProps` 与 `textContentOptions`。
|
||||
- 说明：`watch(props, …)` 仍会因 `loc` 变化触发一次 `retype()`，这与之前 key 重挂载的效果一致（重建并重新打字），属于保持既有行为；专用 watcher 只做位置同步。
|
||||
- **`bookDetail.tsx`**：
|
||||
- 导入改为 `import { cumsum, ITileLocator } from '@motajs/common';`（导入之间不得夹注释 / 空行）。
|
||||
- `specialRows` 改为：`const hs = specials.value.map(special => { return (textHeights.value[special.code] ?? SPECIAL_MIN_HEIGHT) + SPECIAL_LABEL_HEIGHT + SPECIAL_GAP; });` → `const ends = cumsum(hs);` → `return specials.value.map((special, i) => ({ special, labelTop: ends[i] - hs[i], textTop: ends[i] - hs[i] + SPECIAL_LABEL_HEIGHT, textHeight: hs[i] - SPECIAL_LABEL_HEIGHT - SPECIAL_GAP }));`。**不得出现 `top +=`，不得用 `for` 累加。**
|
||||
- 渲染改为 `{specialRows.value.map(row => [<text … />, <TextContent … />])}`：标题与描述都**删除 `key`**；`TextContent` 的 `loc` 用 `[0, row.textTop, SPECIAL_WIDTH, row.textHeight]`（每次求值新建数组）；`text` / `width={SPECIAL_WIDTH}` / `font` / `fillStyle` / `autoHeight` / `onUpdateHeight={height => updateTextHeight(row.special.code, height)}` 逐字保留。
|
||||
- 第 186-187 行两行注释（「TextContent 只在 setup 时复制一次 props.loc，之后改 loc 不会移动元素」与「因此 key 同时包含行位置与实测高度，位置变化时重挂载一次即可收敛」）**替换为一行新注释**：`// TextContent 已按 props.loc 响应式同步位置，行位置变化时无需重挂载`。这是用户本次明确授权的唯一注释替换。
|
||||
- `textHeights` / `updateTextHeight`（含「同值不写」早退）/ `watch(specials, …)` / `SPECIAL_MIN_HEIGHT` / 0 值回退 / 其余元素全部不动；`// 一次遍历累加出每行位置…` 这条既有注释**保留不改**（只记录）。
|
||||
- **`book.tsx` / `equipbox.tsx` / `toolbox.tsx` / `hotkey.tsx`**：逐个删除 `key={…}` 属性（含同一行 / 独占一行的写法），**不删除、不重排、不改写**任何其它属性、元素、数组结构或回调；列表仍是内联 `.map()` 返回同级数组，`Scroll` 内仍无容器、无 `hidden`；每个列表段落既有的 `{/* … */}` 与 `//` 注释原样保留（`hotkey` 内层注释也保留）。
|
||||
- **`uiContainerGate.test.ts`（Task 4 执行，此处只汇报口径）**：删除 13 个 `key` 前缀断言与 `${row.special.code}-${row.textTop}-${row.textHeight}` / 两行重挂载注释断言；新增「五文件去注释后无 `key={`」「`bookDetail` 含 `cumsum(` 与 `ends[i] - hs[i]`、且无 `top +=`」「`textbox` 含 `watch(() => props.loc` / `props.autoHeight ? height : h` / `props.width` / `emit('updateHeight', height)`」；`book` 每行改为按标签计数（11 个 `text` + 1 个 `icon` + 1 个 `g-rect`）；保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` / `nocache` / `*_SCROLL_LOC` 断言；每个 `it` 上方紧邻一行 `//` 注释。
|
||||
|
||||
④ **需要你重点核对的行为变化：**
|
||||
- **`TextContent` 的宽度来源变化（唯一有意为之的语义修正）**：宽度不再取自传入 `loc[2]`，恒取 `props.width`。对 `bookDetail` / `equipbox` / `toolbox` 三处调用，`loc[2]` 与 `width` 本来就相等，**无可见变化**；对 `Textbox` 内嵌的 `TextContent`，宽度会从「整框宽度」变为「内容宽度」（`contentWidth`），这是修正而不是回归。
|
||||
- **`TextContent` 的高度**：`autoHeight` 时仍用实测高度（`bookDetail` 依赖它）；非 `autoHeight` 时用传入 `loc[3]`（`equipbox` / `toolbox` / `Textbox` 的既有矩形）。
|
||||
- **其余行为完全不变**：0 值回退、`SPECIAL_MIN_HEIGHT` 回退、`hidden` 分流、`equipbox` 拖拽 / 悬停、`toolbox` 再点使用、`hotkey` 捕获 / 写回 / 分组切换 / 无入口 / 无持久化 / 无冲突 / 无恢复默认。
|
||||
- **`bookDetail` 的行位置**：`cumsum` 与手写累加等价（`ends[i] - hs[i]` 就是原来的 `top`），第一次测量前仍用 `SPECIAL_MIN_HEIGHT`；测量回调更新 `textHeights` → `specialRows` 重算 → 新的 `loc` 数组 → `TextContent` 的 watcher 同步位置，闭环收敛。
|
||||
- **已知问题按 `dev.md` 假定修复**：渲染器 `removeChild` 被实现为 `destroy` 导致无法重新挂载的问题**仍然存在**，但按第 123 行我们**假定元素可以正常重新挂载**，因此删 `key` 后如果浏览器里出现复用错位，被视为渲染器问题、不是本计划的 workaround 目标；本计划**不**为此加回 key 或改 `Scroll`。
|
||||
- **两条会变「过期」但本次不改的既有注释（请你确认是否保留）**：删掉 `key` 后，`src/client/ui/bookDetail.tsx:58` 的 `/** 描述文本的实测高度，同时用于 TextContent 的 key */` 与 `src/client/ui/bookDetail.tsx:108` 的 `// 同值不写，避免高度回调与 key 重挂载互相触发` 仍然提到「`TextContent` 的 key / key 重挂载」，与改后代码不再一致。按 AGENTS.md「不得擅自修改任何已有注释」，本计划**默认原样保留、不改一个字**，只在 SUMMARY 与 OI-3 中如实登记为已知过期注释。**若你要求把这两条也一并改写，请在回复中直接说明**（届时会作为第三处授权注释改动加进 Task 2，并同步 Task 4 的注释断言；默认不变）。
|
||||
|
||||
⑤ **影响范围：**
|
||||
- 修改 6 个代码文件：`packages-user/client-base/src/components/textbox.tsx`、`src/client/ui/{book,bookDetail,equipbox,toolbox,hotkey}.tsx`。
|
||||
- 修改 1 个既有测试：`src/client/ui/__test__/uiContainerGate.test.ts`。
|
||||
- 另有 3 个 `.planning` 产物：本计划、`09-31-BASELINE.json`、`09-31-SUMMARY.md`。合计 10 个路径。
|
||||
- **显式不改**：`packages-user/client-base/src/components/scroll.tsx`、`src/client/ui/settings.tsx`、`src/client/ui/index.ts`、`src/client/misc/hotkey.ts`、**`src/client/ui/inputBox.tsx` / `waitBox.tsx`**、`Textbox` 组件 / `TextboxStore`、其它任何 UI、依赖与配置。
|
||||
- **`TextContent` 的其它使用方（均为只读，本计划一字不改，不是「只有 4 处调用」）**：除 `bookDetail.tsx` / `equipbox.tsx` / `toolbox.tsx` 与 `textbox.tsx` 内嵌的 `Textbox` 外，`TextContent` 还被 `src/client/ui/inputBox.tsx`、`src/client/ui/waitBox.tsx`、`src/client/ui/statusBar.tsx`、`src/client/ui/statistics.tsx`、`src/client/ui/choices.tsx`（两处）、`src/client/plugin/shop/shop.tsx`、`packages-user/client-base/src/components/input.tsx`、`packages-user/client-base/src/components/misc.tsx` 使用。按规划日抽样核对：凡传入 4 元组 `loc` 的调用点，`width` 与 `loc[2]` 相等（`statusBar` / `misc` 传的是 2 元组 `loc`，旧代码的 `width = props.width` 默认本来就生效），`autoHeight` 处高度仍取实测 —— 因此**尺寸口径不变**。唯一的行为差异是 `choices.tsx` 的 `loc={contentLoc.value}`（以及同为 computed 的 `input.tsx` / `waitBox.tsx` 调用点）：`contentLoc` 变化时 x / y 现在会响应式跟随，**这正是本次修正的预期效果，不是回归**。这 8 个文件都不在 `files_modified` 里，本计划不改；若执行期发现某处 `width` 与 `loc[2]` 不等，SUMMARY 须逐点记录（宽度来源统一属于预期修正）。
|
||||
|
||||
⑥ **验证方式：**
|
||||
1. `pnpm exec eslint` 跑 **同一组 7 个代码 / 测试文件**（`textbox.tsx` + 5 个 UI + `uiContainerGate.test.ts`），基线采集与最终比较的 scope 完全相同，只判 **NEW**；路径归一化口径固定为「反斜杠转正斜杠后，从 `packages-user/` 或 `src/` 开始截取」，Task 1 采集与 Task 4 比较逐字一致。
|
||||
2. `pnpm check:type`（整仓 `vue-tsc --noEmit`）前后基线比较：过滤范围同样是**同一组 7 个路径**，只对改动文件内的 **NEW** 诊断判失败；既有基线诊断允许消失；不修无关错误。
|
||||
3. `uiContainerGate.test.ts`：删除 key / 重挂载断言；新增「五文件无 `key={`」「`bookDetail` 的 `cumsum` 与 `ends[i] - hs[i]`、无 `top +=`」「`textbox` 的响应式 loc」三组；`book` 每行改为 11 `text` + 1 `icon` + 1 `g-rect` 计数；保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` 断言；每个 `it` 上方一行 `//`。
|
||||
4. `hotkeySettingsGate.test.ts` 仍为绿。
|
||||
5. 受保护文件哈希闸门（**6 个**：`scroll.tsx`、`settings.tsx`、`ui/index.ts`、`misc/hotkey.ts`、`inputBox.tsx`、`waitBox.tsx`）；另外记录 `textbox.tsx` 改动前的哈希并要求结束时**不同**（证明它确实被改，而不是「受保护不变」）。
|
||||
6. 改动范围闸门：只有 7 个代码 / 测试路径，且用整仓 `git status --porcelain -uall` 与基线 `dirty` 快照比较，任何「不在快照、不属于这 7 个路径、也不在 `.planning/`」的新路径都判范围外写入。**注意**：09-29 / 09-30 的改动尚未提交，这些路径在基线里本来就是脏的，因此该闸门只能证明「没有新增范围外路径」。
|
||||
7. `keyAdaptationGate.test.ts` 是既存失败，不在本计划范围，不修、不声称全绿。
|
||||
8. **不做浏览器 UAT**：位置收敛、滚动、点击命中、拖拽手感、复用正确性留给你人工确认。
|
||||
|
||||
⑦ **命名清单（OI-1）：** 只改局部标识符——`textbox.tsx` 新增 `h`（传入的 `loc[3]`），沿用 `x` / `y` / `ax` / `ay`；`bookDetail.tsx` 新增 `hs`（每行行高）与 `ends`（`cumsum` 结果），`specialRows` 内部索引用 `i`；删除 37 个 `key` 表达式与 `bookDetail` 的 `top` 变量。不新增文件作用域常量 / `interface` / 导出函数；既有公共 / 受保护 / 导出命名、`GameUI` id、`selectKey` 签名一律不改。**你若要求其它命名，请在回复中说明，我会整体替换后再执行。**
|
||||
|
||||
⑧ **两条铁律：** **不做浏览器 UAT、不宣称任何视觉 / 滚动 / 点击 / 拖拽 / 位置收敛行为已验证**；**执行器不提交任何代码**（禁止 `git add` / `commit` / `stash` / `checkout` / `worktree` / `reset`），代码改动留在工作树供你审查。三个 `.planning` 产物可能由 GSD 编排器按 `commit_docs: true` 聚合提交，不算本计划的代码提交。
|
||||
</action>
|
||||
<how-to-verify>
|
||||
逐条核对 ①–⑧ 是否与你的意图一致，特别是：①`TextContent` 的四条新语义（x/y/ax/ay 取传入 loc、宽度恒 `props.width`、高度按 `autoHeight` 分流、其余时序不动）是否就是你要的；②「宽度从整框宽度变为内容宽度」这一处唯一有意为之的可见变化是否接受；③`cumsum` 用 `ends[i] - hs[i]` 求行顶、且不删除 `updateTextHeight` 同值早退是否认可；④37 个 key 的分布（13 / 2 / 9 / 8 / 5）与「一个都不保留」是否符合 `dev.md` 新规；⑤把两行 key 重挂载注释替换为一行新注释是否是你可以接受的注释改动；⑥`uiContainerGate.test.ts` 删除 key 断言 + 新增三组 + `book` 改按标签计数是否就是你要的覆盖面；⑦「不做浏览器 UAT / 执行器不提交代码」与 `textbox.tsx` 改为「允许修改但需记录前后哈希」的闸门口径；⑧09-29 / 09-30 改动未提交导致范围闸门只能证明「无新增范围外路径」这一点是否接受；⑨`bookDetail.tsx:58` / `:108` 两条仍提到 `TextContent` key 重挂载的过期注释**默认原样保留**（AGENTS.md 禁止擅改）是否可接受，以及 `TextContent` 的另外 8 个使用方（`inputBox` / `waitBox` / `statusBar` / `statistics` / `choices` / `plugin/shop/shop` / `components/input` / `components/misc`）只读不改、尺寸口径不变、`choices` 的 x / y 会随 `contentLoc` 响应式跟随（预期效果）这一说明是否符合你的理解。
|
||||
</how-to-verify>
|
||||
<resume-signal>仅当完全同意时回复恰好四个字「可以执行」；任何修改意见（**尤其是 OI-1 的局部变量命名、以及宽度语义修正是否接受**）请直接说明，本计划会据此改写后再来一次汇报。</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: 写出改动前基线，然后把 `TextContent` 的 `props.loc` 改为响应式并修正宽度 / 高度来源</name>
|
||||
<files>.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json（新增，第一步写出）, packages-user/client-base/src/components/textbox.tsx</files>
|
||||
<action>
|
||||
**依赖 Task 0 已收到「可以执行」。** **第一步（必须在任何代码编辑之前）：** 写出 `.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json`，schema 为 `{ head, hashes, textbox, dirty, eslint, typecheck }`：
|
||||
- `head`：当前 `git rev-parse HEAD`。
|
||||
- `hashes`：**6 个**受保护文件的 `git hash-object`——`packages-user/client-base/src/components/scroll.tsx`、`src/client/ui/settings.tsx`、`src/client/ui/index.ts`、`src/client/misc/hotkey.ts`、`src/client/ui/inputBox.tsx`、`src/client/ui/waitBox.tsx`；键用完整仓库相对路径（POSIX 正斜杠），值小写 sha。**`textbox.tsx` 不在这 6 个里**。
|
||||
- `textbox`：`packages-user/client-base/src/components/textbox.tsx` 改动前的 `git hash-object`（字符串）。Task 4 要求它与结束时的哈希**不同**，证明该文件确实被改过。
|
||||
- `dirty`：`git status --porcelain -uall`（**不加 pathspec**），取状态列之后的路径、去掉 `.planning/` 开头的条目，按字典序写入。**注意：本快照在 Task 1 编辑任何代码之前采集**——09-29 / 09-30 的 5 个 UI 文件与 `uiContainerGate.test.ts` 尚未提交，会出现在这份快照里；`textbox.tsx` 此刻仍是干净的，它是在 Task 1 编辑该文件之后才变脏，因此不出现在 `dirty` 里；这是基线，不是异常。
|
||||
- `eslint`：对**同一组 7 个路径**（`packages-user/client-base/src/components/textbox.tsx`、`src/client/ui/book.tsx`、`bookDetail.tsx`、`equipbox.tsx`、`toolbox.tsx`、`hotkey.tsx`、`src/client/ui/__test__/uiContainerGate.test.ts`）跑 `pnpm exec eslint -f json`，每条归一化为 `仓库相对路径|规则ID|严重度|消息`，归一化代码必须与 Task 4 逐字相同：`const norm = p => { const s = String(p).replace(/\\/g, '/'); const i = s.search(/(packages-user|src)\//); return i >= 0 ? s.slice(i) : s; };`，条目为 `norm(f.filePath) + '|' + String(m.ruleId || 'null') + '|' + String(m.severity) + '|' + String(m.message).trim()`。**基线采集与 Task 4 比较的 scope 必须完全相同（都是这 7 个路径，测试文件不排除）**。`eslint` 以 `status === 1` 退出属于正常（有告警），必须照常解析 stdout；只有未运行 / stdout 为空 / JSON 不可解析才停下上报。
|
||||
- `typecheck`：整仓跑 `pnpm check:type`，再**原样复制 Task 4 的 `norm`**——`const norm = l => l.replace(/\\/g, '/').replace(/\(\d+,\d+\):/, '').replace(/^.*?(?=(src|packages-user)\/)/, '').trim();`——并用与 Task 4 **逐字相同的 7 路径 `scope`** 过滤出这些文件内的诊断，保留重复项与 `src/` / `packages-user/` 前缀。只写一次，此后不得重写。
|
||||
|
||||
**第二步：`packages-user/client-base/src/components/textbox.tsx`（只改 `TextContent`）。**
|
||||
1. 在 `updateLoc` 定义之后、紧随其后新增专用 watcher：`watch(() => props.loc, () => { updateLoc(); });`。**不要**给现有 `watch(props, …)` 增加或删除任何行为；**不要**传 `deep: true`（`bookDetail` 每次求值都传新数组，引用变化即足够）。
|
||||
2. 把 `updateLoc` 的实现改为（保持 `emit` 在最后）：
|
||||
- `const height = getHeight();`
|
||||
- `const [x = 0, y = 0, , h = 0, ax = 0, ay = 0] = props.loc ?? loc.value;`
|
||||
- `loc.value = [x, y, props.width, props.autoHeight ? height : h, ax, ay];`
|
||||
- `emit('updateHeight', height);`
|
||||
**要点**：第三个位置（宽度）恒为 `props.width`，**不再**从传入 `loc[2]` 取值；第四个位置（高度）在 `autoHeight` 时为实测 `height`、否则为传入 `loc[3]`；第二位置的空位（原 `width` 解构）必须删掉，否则会与「宽度恒取 `props.width`」冲突。
|
||||
3. **不得改动**该文件其它任何内容：`TextContentProps` / `TextContentEmits` / `TextContentExpose` / `textContentOptions` / `loc` 的初始化（仍为 `props.loc?.slice()` 拷贝，作为 `props.loc` 缺省时的回退）/ `typer` / `retype` / `showAll` / `getHeight` / `renderContent` / `renderFunc` / `onMounted(retype)` / `expose` / 渲染函数 / `Textbox` 组件 / `TextboxStore` / 既有 jsDoc 与注释。
|
||||
4. `loc.value` 仍须是 `ElementLocator` 六元组；不得新增文件作用域标识符；不得新增依赖。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>node -e "const fs=require('fs');const b='.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json';const bad=[];if(!fs.existsSync(b))bad.push('baseline missing');else{let j={};try{j=JSON.parse(fs.readFileSync(b,'utf8'))}catch(e){bad.push('baseline unparsable')}for(const k of ['head','hashes','textbox','dirty','eslint','typecheck'])if(!(k in j))bad.push('missing '+k);if(Object.keys(j.hashes||{}).length!==6)bad.push('hashes must have 6 entries');for(const f of ['packages-user/client-base/src/components/scroll.tsx','src/client/ui/settings.tsx','src/client/ui/index.ts','src/client/misc/hotkey.ts','src/client/ui/inputBox.tsx','src/client/ui/waitBox.tsx'])if(!Object.prototype.hasOwnProperty.call(j.hashes||{},f))bad.push('hashes missing '+f);if(Object.prototype.hasOwnProperty.call(j.hashes||{},'packages-user/client-base/src/components/textbox.tsx'))bad.push('textbox must NOT be hash-protected');if(typeof j.textbox!=='string'||j.textbox.length<8)bad.push('textbox pre-change hash missing');if(!Array.isArray(j.dirty))bad.push('dirty must be an array')}if(bad.length){console.error('TASK1 BASELINE GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK task1: baseline')"</automated>
|
||||
<automated>node -e "const fs=require('fs');const c=fs.readFileSync('packages-user/client-base/src/components/textbox.tsx','utf8');const s=c.replace(/\s+/g,' ');const bad=[];for(const n of ['watch(() => props.loc','props.autoHeight ? height : h','props.width','emit(\'updateHeight\', height)','typer.setConfig(props)','typer.type()','expose<TextContentExpose>'])if(s.indexOf(n)<0)bad.push('missing :: '+n);if(!/loc\.value = \[\s*x,\s*y,\s*props\.width,\s*props\.autoHeight \? height : h,\s*ax,\s*ay\s*\]/.test(s))bad.push('loc.value assignment is not the expected six-tuple');const i0=c.indexOf('const updateLoc = () => {');const i1=c.indexOf('expose<TextContentExpose>');const ub=(i0>=0&&i1>i0)?c.slice(i0,i1).replace(/\s+/g,' '):'';if(!ub)bad.push('updateLoc body not found');if(ub.indexOf('width = props.width')>=0)bad.push('old width destructuring default still in updateLoc');if(ub.indexOf('loc.value[2]')>=0)bad.push('updateLoc still reads width from loc.value[2]');if(s.indexOf('deep: true')>=0)bad.push('unexpected deep watcher');if(bad.length){console.error('TASK1 TEXTBOX GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK task1: TextContent reactive loc')"</automated>
|
||||
<automated>cmd /c "pnpm exec eslint packages-user/client-base/src/components/textbox.tsx"</automated>
|
||||
<fails_when>基线缺失或字段残缺、`hashes` 不是 6 条、`textbox.tsx` 被误列为受保护文件、`textbox` 改动前哈希缺失、`dirty` 不是数组；`textbox.tsx` 缺 `watch(() => props.loc`、缺 `props.autoHeight ? height : h`、缺 `emit('updateHeight', height)`、`loc.value` 不是 `[x, y, props.width, props.autoHeight ? height : h, ax, ay]`、在 `updateLoc` 体内仍保留 `width = props.width` 或 `loc.value[2]`（闸门取 `const updateLoc = () => {` 到 `expose<TextContentExpose>` 之间的切片，**不扫描 `Textbox` 里既有的 `data.width = props.width`**）、出现 `deep: true`、或改动了 `typer` / `retype` / `expose` / 渲染函数（缺失任一既有标识）；eslint 报错；或任一 node 闸门非零退出。</fails_when>
|
||||
</verify>
|
||||
<done>`09-31-BASELINE.json` 已在改代码前写出且只写一次（6 个受保护哈希 + `textbox.tsx` 改动前哈希 + 7 路径 eslint / typecheck 基线 + 脏文件快照）；`TextContent` 新增 `watch(() => props.loc, () => { updateLoc(); })`，`updateLoc` 产出 `[x, y, props.width, props.autoHeight ? height : h, ax, ay]` 并继续 `emit('updateHeight', height)`；宽度不再取自传入 `loc[2]`，非 `autoHeight` 时高度取传入 `loc[3]`；`typer` / 打字机 / `expose` / `Textbox` / `TextboxStore` 与所有既有注释零改动；eslint 无报错。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: `bookDetail` 改用 `cumsum` 并去掉渲染 key，删除 `book` 的 13 个 key</name>
|
||||
<files>src/client/ui/bookDetail.tsx, src/client/ui/book.tsx</files>
|
||||
<action>
|
||||
**依赖 Task 1 已完成。**
|
||||
|
||||
**A. `src/client/ui/bookDetail.tsx`**
|
||||
1. 导入：`import { cumsum, ITileLocator } from '@motajs/common';`（与本文件其它导入之间不夹注释 / 空行）。
|
||||
2. `specialRows` 的 `computed<ISpecialRow[]>` 计算体改为「行高 → 累计结束位置 → 行」三段，**不得出现 `let top` 或 `top +=`**：
|
||||
- `const hs = specials.value.map(special => { return (textHeights.value[special.code] ?? SPECIAL_MIN_HEIGHT) + SPECIAL_LABEL_HEIGHT + SPECIAL_GAP; });`
|
||||
- `const ends = cumsum(hs);`
|
||||
- `return specials.value.map((special, i) => ({ special, labelTop: ends[i] - hs[i], textTop: ends[i] - hs[i] + SPECIAL_LABEL_HEIGHT, textHeight: hs[i] - SPECIAL_LABEL_HEIGHT - SPECIAL_GAP }));`
|
||||
**等价性**：原 `top` 从 0 开始、每行结束于 `top + SPECIAL_LABEL_HEIGHT + textHeight + SPECIAL_GAP`，而 `hs[i]` 正是这一增量，`ends[i] - hs[i]` 就是原来的 `top`；`textTop` / `textHeight` 与原来逐字一致。
|
||||
3. `Scroll` 的 children 改为：`{specialRows.value.map(row => [<text … />, <TextContent … />])}`，**两个元素都不带 `key`**。保留的属性逐字对应：标题 `text={`${row.special.getSpecialName()}：`}` / `loc={[0, row.labelTop]}` / `anc={[0, 0]}` / `font={specialFont}` / `fillStyle={row.special.getNameColor()}`；描述 `text={row.special.getDescription()}` / `width={SPECIAL_WIDTH}` / `loc={[0, row.textTop, SPECIAL_WIDTH, row.textHeight]}` / `font={specialFont}` / `fillStyle="#dddddd"` / `autoHeight` / `onUpdateHeight={height => updateTextHeight(row.special.code, height)}`。**`loc` 必须是每次求值新建的数组字面量**（不要提取成常量、不要复用上次的数组）。
|
||||
4. 第 186-187 行两行注释替换为**一行**：`// TextContent 已按 props.loc 响应式同步位置，行位置变化时无需重挂载`。除这两行外，**不得修改任何既有注释 / jsDoc**（`// 一次遍历累加出每行位置；行高只在循环内使用，不写入接口`、`// 按特殊属性 code 记录实测描述高度…`、`// 同值不写，避免高度回调与 key 重挂载互相触发`、`// 只保留仍存在的条目…` 全部原样保留）。
|
||||
5. 不动：`textHeights` / `updateTextHeight`（含「同值不写」早退）/ `watch(specials, …)` / `SPECIAL_MIN_HEIGHT` / 0 值回退 / `critical` / `format` / `statX` / `toggleMode` / `close` / 其它所有元素与注释。`Scroll` 内仍只有一条 `{/* … */}`，仍无 `container`、无 `hidden=`。
|
||||
|
||||
**B. `src/client/ui/book.tsx`**
|
||||
1. 删除 13 个 `key` 属性：`hit-` / `icon-` / `name-` / `special-` / `hp-` / `atk-` / `def-` / `money-` / `exp-` / `dmg-` / `crit-` / `reduce-` / `def1-`（每处形态为 `key={`前缀-${base.code}`}`）。只删 `key` 这一行 / 这一段属性，不动元素本身。
|
||||
2. 其余一律不动：13 个元素的顺序与全部属性（含 `loc` / `anc` / `font` / `fillStyle` / `noevent` / `cursor` / `fill` / `onClick={() => openDetail(view)}`）、`enemies.value.map((view, i) => …)` 的内联数组返回、`const base` / `locator` / `critical` / `def1` / `y` / `damage` / `nextDiff` / `damageDiff` / `def1Damage`、三条既有 `//`（含单独成行的 `// 临界信息缺失时回退为 0…`）、`{/* … */}`、根 `container`。
|
||||
3. 不得新增 Fragment / 容器 / 条件渲染 / `hidden` 开关；不得把 `key` 换成索引 key。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>node -e "const fs=require('fs');const strip=s=>s.replace(/\/\*[^]*?\*\//g,'').replace(/^[ \t]*\/\/[^\n]*/gm,'');const d=strip(fs.readFileSync('src/client/ui/bookDetail.tsx','utf8'));const df=d.replace(/\s+/g,' ');const bad=[];for(const n of ['cumsum(hs)','ends[i] - hs[i]','specialRows.value.map(','autoHeight','onUpdateHeight','textHeights','SPECIAL_MIN_HEIGHT','getDescription()','textTop','textHeight','ISpecialRow','ISpecial<unknown>','format(critical.value ? critical.value.nextDiff : 0)','format(critical.value ? -critical.value.damageDiff : 0)'])if(df.indexOf(n)<0)bad.push('bookDetail missing :: '+n);if(df.indexOf('top +=')>=0)bad.push('bookDetail still has top +=');if(df.indexOf('key={')>=0)bad.push('bookDetail still has key={');if(!/from '@motajs\/common'/.test(df)||df.indexOf('cumsum')<0)bad.push('cumsum not imported from @motajs/common');const n=(d.match(/<container(?=[\s>])/g)||[]).length;if(n!==1)bad.push('bookDetail expected exactly 1 container, got '+n);let i=0;while(true){const a=d.indexOf('<Scroll',i);if(a<0)break;const e=d.indexOf('</Scroll>',a);if(e<0){bad.push('unclosed Scroll');break}const blk=d.slice(a,e);if(/<container(?=[\s>])/.test(blk))bad.push('container inside Scroll');if(/hidden\s*=/.test(blk))bad.push('hidden inside Scroll');i=e+1}const src=fs.readFileSync('src/client/ui/bookDetail.tsx','utf8');if(src.indexOf('// TextContent 已按 props.loc 响应式同步位置，行位置变化时无需重挂载')<0)bad.push('new loc comment missing');for(const old of ['// TextContent 只在 setup 时复制一次 props.loc，之后改 loc 不会移动元素','// 因此 key 同时包含行位置与实测高度，位置变化时重挂载一次即可收敛'])if(src.indexOf(old)>=0)bad.push('old remount comment still present :: '+old);const bsrc=fs.readFileSync('src/client/ui/book.tsx','utf8');const b=strip(bsrc);const bf=b.replace(/\s+/g,' ');if(bf.indexOf('key={')>=0)bad.push('book still has key={');for(const n2 of ['enemies.value.map(','specialText(base)','format(damage)','format(nextDiff)','format(damageDiff)','format(def1Damage)'])if(bf.indexOf(n2)<0)bad.push('book missing :: '+n2);const nb=(b.match(/<container(?=[\s>])/g)||[]).length;if(nb!==1)bad.push('book expected exactly 1 container, got '+nb);const blocks=[];let k=0;while(true){const a=b.indexOf('<Scroll',k);if(a<0)break;const e=b.indexOf('</Scroll>',a);if(e<0)break;blocks.push(b.slice(a,e));k=e+1}if(blocks.length!==1)bad.push('book expected 1 Scroll, got '+blocks.length);else{const blk=blocks[0];const texts=(blk.match(/<text(?=[\s>])/g)||[]).length;const icons=(blk.match(/<icon(?=[\s>])/g)||[]).length;const rects=(blk.match(/<g-rect(?=[\s>])/g)||[]).length;if(texts!==11||icons!==1||rects!==1)bad.push('book row element counts text/icon/g-rect = '+texts+'/'+icons+'/'+rects+' (want 11/1/1)')}for(const lbl of ['\u751f\u547d','\u653b\u51fb','\u9632\u5fa1','\u91d1\u5e01','\u7ecf\u9a8c'])if(bsrc.indexOf(lbl)<0)bad.push('book missing label :: '+lbl);if(bad.length){console.error('TASK2 BOOKDETAIL/BOOK GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK task2: bookDetail cumsum + no key, book no key with 13 elements')"</automated>
|
||||
<automated>cmd /c "pnpm exec eslint src/client/ui/bookDetail.tsx src/client/ui/book.tsx"</automated>
|
||||
<fails_when>`bookDetail` 缺 `cumsum(hs)` / `ends[i] - hs[i]` / `specialRows.value.map(`，仍含 `top +=` 或 `key={`，未从 `@motajs/common` 导入 `cumsum`，缺 `autoHeight` / `onUpdateHeight` / `textHeights` / `SPECIAL_MIN_HEIGHT` / `getDescription()` / `textTop` / `textHeight` / `ISpecialRow` / `ISpecial<unknown>` / 两条 0 回退文案，`<container>` 计数不为 1，`Scroll` 内出现 `container` 或 `hidden=`，新注释缺失或旧两行重挂载注释仍在；`book` 仍含 `key={`、缺任一内联映射 / 0 回退标识、`<container>` 计数不为 1、`Scroll` 块内 `text` / `icon` / `g-rect` 计数不是 11 / 1 / 1，或缺五条基础数值文案；eslint 报错；或 node 闸门非零退出。</fails_when>
|
||||
</verify>
|
||||
<done>`bookDetail.tsx` 用 `hs` + `cumsum(hs)` 得出 `ends`，行顶为 `ends[i] - hs[i]`，无 `top +=`、无 `for` 累加；渲染为 `specialRows.value.map(row => [<text/>, <TextContent/>])` 且两者无 `key`，描述 `loc` 每次新建；旧两行重挂载注释替换为一行新注释，其余注释与高度逻辑原样保留；`book.tsx` 的 13 个 `key` 全部删除，`Scroll` 块内仍是 11 个 `text` + 1 个 `icon` + 1 个 `g-rect`，0 回退与 `noevent` 不变；两文件 eslint 无报错。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: 删除 `equipbox` / `toolbox` / `hotkey` 的 22 个 key（9 + 8 + 5），其余一律不动</name>
|
||||
<files>src/client/ui/equipbox.tsx, src/client/ui/toolbox.tsx, src/client/ui/hotkey.tsx</files>
|
||||
<action>
|
||||
**依赖 Task 2 已完成。只删 `key` 属性，不改任何逻辑体、不改列表结构、不改注释。**
|
||||
|
||||
**A. `src/client/ui/equipbox.tsx`（9 个）**
|
||||
1. 状态区三元组删除 `key={`name-${attr.id}`}` / `key={`value-${attr.id}`}` / `key={`delta-${attr.id}`}`。
|
||||
2. 槽位三元组删除 `key={`slot-${i}`}` / `key={`icon-${i}`}` / `key={`name-${i}`}`。
|
||||
3. 拥有装备三元组删除 `key={`row-${item.uid}`}` / `key={`icon-${item.uid}`}` / `key={`name-${item.uid}`}`。
|
||||
4. 不动：三处内联 `.map()` 与返回的三元组、`hidden={!!equip}` / `hidden={!equip}` / `hidden={!dragging.value}`、`delta === 0 ? ''` / `equip ? equip.item.text : ''` / `slotEquip ? slotEquip.item.num : 0` 三处回退、`onEnter` / `onLeave` / `onDown` / `onMove` / `onUp`、`startPress` / `movePress` / `endPress`、`getTargetSlot` / `selectedSlot` 的既有单行 `for`、4 个 `*_SCROLL_LOC`（含 `: ElementLocator`）与 `ElementLocator` 导入、两条既有 `//` 与三条 `{/* … */}`、根 `container`。
|
||||
5. 不得新增 Fragment / 容器 / 条件渲染 / `hidden` 开关；不得把 `key` 换成索引 key。
|
||||
|
||||
**B. `src/client/ui/toolbox.tsx`（8 个）**
|
||||
1. 永久道具列四元组删除 `key={`row-${item.num}`}` / `key={`icon-${item.num}`}` / `key={`name-${item.num}`}` / `key={`count-${item.num}`}`；可消耗道具列同样删除四个。
|
||||
2. 不动：两处内联 `.map()` 与四元组、`hidden={!!current}` 提示位置、`TextContent` 的 `current ? current.raw.text : ''` 空文本回退、`clickItem(item)` 的再点使用、`collect` / `selectedItem` / `permItems` / `consItems`、两条 `{/* … */}`、根 `container`。
|
||||
|
||||
**C. `src/client/ui/hotkey.tsx`（5 个）**
|
||||
1. 左栏删除 `key={`hit-${id}`}` / `key={`name-${id}`}`；右栏删除 `key={`name-${row.command.command}`}`；内层组合删除 `key={`box-${i}-${j}`}` / `key={`text-${i}-${j}`}`。
|
||||
2. 不动：`groups.map(([id, group], i) => …)` / `commandRows.value.map((row, i) => …)` / 内层 `.map((keys, j) => …)`、`commandRows` / `combinationLists` / `ICommandRow` / `refreshCombinations` / `formatCombination`、`selectGroup(id)` / `selectKey(row.command, j)`、两处 `strokeStyle` / `lineWidth` 的 `isSelected` 三元、两条既有 `//` 与新增内层 `//`、两条 `{/* … */}`、根 `container` 的 `nocache`、捕获 / 写回 / 分组切换 / 关闭逻辑。
|
||||
3. 不得新增 Fragment / 容器 / 条件渲染 / `hidden` 开关；不得把 `key` 换成索引 key。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>node -e "const fs=require('fs');const strip=s=>s.replace(/\/\*[^]*?\*\//g,'').replace(/^[ \t]*\/\/[^\n]*/gm,'');const bad=[];const spec=[['src/client/ui/equipbox.tsx',['hidden={!!equip}','hidden={!equip}','hidden={!dragging.value}',\"delta === 0 ? ''\",\"equip ? equip.item.text : ''\",'slotEquip ? slotEquip.item.num : 0','STATUS_SCROLL_LOC','DESC_SCROLL_LOC','SLOT_SCROLL_LOC','OWNED_SCROLL_LOC','props.attributes.map(','hero.equip.slots.map(','owned.value.map(','startPress(','onUp={endPress}']],['src/client/ui/toolbox.tsx',['hidden={!!current}',\"current ? current.raw.text : ''\",'permItems.value.map(','consItems.value.map(','clickItem(item)']],['src/client/ui/hotkey.tsx',['groups.map(','commandRows.value.map(','combinationLists.value[i]','.map((keys, j)','selectKey(row.command, j)','selectGroup(id)','setKeyCombination(','nocache','formatCombination(showing)']]];for(const [p,need] of spec){const raw=fs.readFileSync(p,'utf8');const c=strip(raw);const f=c.replace(/\s+/g,' ');for(const n of need)if(f.indexOf(n)<0)bad.push(p+' missing :: '+n);if(c.indexOf('key={')>=0)bad.push(p+' still has key={');const cnt=(c.match(/<container(?=[\s>])/g)||[]).length;if(cnt!==1)bad.push(p+' expected exactly 1 container, got '+cnt);let i=0;while(true){const a=c.indexOf('<Scroll',i);if(a<0)break;const e=c.indexOf('</Scroll>',a);if(e<0){bad.push(p+' unclosed Scroll');break}const blk=c.slice(a,e);if(/<container(?=[\s>])/.test(blk))bad.push(p+' container inside Scroll');if(/hidden\s*=/.test(blk))bad.push(p+' hidden inside Scroll');i=e+1}if(/for\s*\(\s*\r?\n/.test(c))bad.push(p+' has a wrapped for (')}if(bad.length){console.error('TASK3 KEY-REMOVAL GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK task3: equipbox/toolbox/hotkey key-free')"</automated>
|
||||
<automated>node -e "const fs=require('fs');const strip=s=>s.replace(/\/\*[^]*?\*\//g,'').replace(/^[ \t]*\/\/[^\n]*/gm,'');const bad=[];const spec=[['src/client/ui/equipbox.tsx',[1,0,1,1],2],['src/client/ui/toolbox.tsx',[1,1,0],0],['src/client/ui/hotkey.tsx',[1,1],3]];for(const [p,exp,expLc] of spec){const c=fs.readFileSync(p,'utf8');const blocks=[];let i=0;while(true){const a=c.indexOf('<Scroll',i);if(a<0)break;const e=c.indexOf('</Scroll>',a);if(e<0){bad.push(p+' unclosed Scroll');break}blocks.push(c.slice(a,e));i=e+9}if(blocks.length!==exp.length)bad.push(p+' Scroll count '+blocks.length+' != '+exp.length);let lc=0;blocks.forEach((b,ix)=>{const jsx=(b.match(/\{\s*\/\*/g)||[]).length;if(jsx!==(exp[ix]||0))bad.push(p+' Scroll#'+ix+' JSX comments '+jsx+' != '+exp[ix]);lc+=(b.match(/(^|\r?\n)[ \t]*\/\//g)||[]).length;const g=b.indexOf('>')+1;const f=(b.slice(g).trimStart()[0]||'');if(f!=='{'&&f!=='<')bad.push(p+' Scroll#'+ix+' child position starts with '+f)});if(lc!==expLc)bad.push(p+' line comments inside Scrolls '+lc+' != '+expLc)}if(bad.length){console.error('TASK3 COMMENT GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK task3: comments untouched')"</automated>
|
||||
<automated>cmd /c "pnpm exec eslint src/client/ui/equipbox.tsx src/client/ui/toolbox.tsx src/client/ui/hotkey.tsx"</automated>
|
||||
<fails_when>三个文件任一仍含 `key={`、缺任一既有标识（`hidden` 分流 / 空文本 / 0 回退 / 4 个 `*_SCROLL_LOC` / 三处内联 `.map(` / `clickItem(item)` / `selectKey(row.command, j)` / `.map((keys, j)` / `nocache` 等）、`<container>` 计数不为 1、`Scroll` 内出现 `container` 或 `hidden=`、出现换行的 `for (`；`Scroll` 块数与每块 `{/* … */}` 数量不等于 `equipbox [1,0,1,1]` / `toolbox [1,1,0]` / `hotkey [1,1]`、`Scroll` 内 `//` 行数不是 `equipbox 2` / `toolbox 0` / `hotkey 3`、或某块子元素位置不以 `{` / `<` 开头；eslint 报错；或 node 闸门非零退出。</fails_when>
|
||||
</verify>
|
||||
<done>`equipbox.tsx`（9 个）/ `toolbox.tsx`（8 个）/ `hotkey.tsx`（5 个）的 `key` 全部删除，去注释源码里 `key={` 为 0；三处 / 两处 / 两栏的列表结构、元素顺序、属性、`noevent`、事件、显示分流与格式回退全部不变；`Scroll` 块内 `{/* … */}` 与 `//` 数量、子元素起始字符与 Task 2 完成时一致；eslint 无报错。</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: 更新 `uiContainerGate.test.ts`（删 key / 重挂载断言 + 新增三组），先跑全部门禁、再写执行摘要、最后跑摘要闸门</name>
|
||||
<files>src/client/ui/__test__/uiContainerGate.test.ts, .planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md</files>
|
||||
<action>
|
||||
**依赖 Task 1、2、3 已完成。**
|
||||
|
||||
**A. 更新 `src/client/ui/__test__/uiContainerGate.test.ts`（保留原有辅助函数与保留项断言）：**
|
||||
1. 顶部新增 `import textBoxSource from '../../../../packages-user/client-base/src/components/textbox.tsx?raw';`；`stripComments` / `flatten` / `getScrollBlocks` / `firstContainerTag` / `tagAround` 五个辅助函数与既有说明注释原样保留。
|
||||
2. **删除 / 改写**下列断言（因为它们描述的是已被删除的 `key` 行为）：
|
||||
- 「`keeps all thirteen elements in every book row`」这一组（`book` 每行 13 个 `key` 前缀）：**删除 13 个 `` `前缀-${base.code}` `` 模板断言**，改为按标签计数的等价断言——`getScrollBlocks(stripComments(bookSource))` 只有一个块，块内 `/<text(?=[\s>])/g` 恰 11 个、`/<icon(?=[\s>])/g` 恰 1 个、`/<g-rect(?=[\s>])/g` 恰 1 个（合计 13），并保留 `生命` / `攻击` / `防御` / `金币` / `经验` 与 `specialText(base)` 的存在断言。
|
||||
- 「`measures special rows through the height callback and remount keys`」这一组中 `bookDetail` 的 `expect(flat).toContain('${row.special.code}-${row.textTop}-${row.textHeight}')`：**删除**（组名同步改为 `measures special rows through the height callback without remount keys`）；同组其余高度断言（`autoHeight` / `onUpdateHeight` / `textHeights` / `specialRows` / `SPECIAL_MIN_HEIGHT` / `getDescription()` / `textTop` / `textHeight` / `ISpecialRow` / `ISpecial<unknown>`）保留，并新增 `expect(flat).toContain('cumsum(hs)')`、`expect(flat).toContain('ends[i] - hs[i]')`、`expect(flat).not.toContain('top +=')`。
|
||||
- 「`keeps line comments out of Scroll children`」这一组中两行 `bookDetail` 重挂载注释的 `toContain` 与「索引小于 `<Scroll` / 大于 `return () =>`」断言：**删除**；改为断言原文含新注释 `// TextContent 已按 props.loc 响应式同步位置，行位置变化时无需重挂载` 恰好 1 次，且**不含**那两行旧注释；同组其余注释位置 / 数量断言（`book` 三条、`equipbox` 两条、`hotkey` 两条、每块 `{/* … */}` 计数、子元素起始字符、剩余文本不含 `//`）全部保留。
|
||||
3. **新增三组**（每组 `it` 上方紧邻一行 `//` 注释）：
|
||||
- `// 五个列表文件都不再用 key 强制重挂载`：对五个 `stripComments(source)` 逐个 `expect(source).not.toContain('key={')`；并额外取 `tagAround(stripComments(bookDetailSource), 'TextContent', 'getDescription()')`，断言该标签非空、`not.toContain('key=')`、`toContain('loc={[')`。
|
||||
- `// bookDetail 用 cumsum 计算行位置且不再手写累加`：`flatten(stripComments(bookDetailSource))` 含 `from '@motajs/common'`、`cumsum`、`cumsum(hs)`、`ends[i] - hs[i]`，且不含 `top +=`。
|
||||
- `// TextContent 会随 props.loc 更新位置并恒用 props.width 作为宽度`：对 `stripComments(textBoxSource).replace(/\s+/g, ' ')` 断言含 `watch(() => props.loc`、`props.autoHeight ? height : h`、`props.width`、`emit('updateHeight', height)`、`typer.setConfig(props)`；并用正则 `/loc\.value = \[\s*x,\s*y,\s*props\.width,\s*props\.autoHeight \? height : h,\s*ax,\s*ay\s*\]/` 断言六元组赋值形态。
|
||||
4. **保留**全部原有保留项断言：`Scroll` 块内无 `container` / 无 `hidden=`、每文件仅 1 个根 `container`、`hotkey` 两栏与两处选中边框、`book` 四项 / `bookDetail` 两项 0 回退、显示开关分流与 `noevent` 逐元素配对、`hotkey` 根 `nocache`、4 个 `*_SCROLL_LOC` 带 `: ElementLocator`、无预建 `VNode` 数组、内联 `.map()` 与短循环变量。
|
||||
5. 每个 `it` 上方紧邻一行 `//` 注释；不修改既有 `it` 名称以外的说明注释（删除上述 key 断言时，同步更新与之直接对应的注释文本，其余不动）；测试不读取 `.planning/`、不导入组件本体。
|
||||
6. **跨包 `?raw` 兜底**：若该导入在运行时报错，停下上报；允许改用 `node:fs` 的 `readFileSync` 读同一路径并在 SUMMARY 记录为偏离，不得改读别的文件。
|
||||
|
||||
**B. 先跑完所有门禁（此时还没有 SUMMARY）：** 逐条执行下方 automated 命令并记录**实际**输出。
|
||||
- vitest：`uiContainerGate.test.ts` 与 `hotkeySettingsGate.test.ts`。
|
||||
- eslint：跑**与 Task 1 基线完全相同的 7 个路径**，与 `09-31-BASELINE.json` 的 `eslint` 比较，只判 NEW。
|
||||
- `pnpm check:type`：整仓运行，按**与 Task 1 基线完全相同的 7 路径 `scope`** 过滤，只判 NEW；基线中存在、执行后消失的诊断允许。
|
||||
- 受保护文件哈希（**6 个**）与基线逐字相等；`textbox.tsx` 当前哈希与基线的 `textbox` 字段**不同**；HEAD 与基线相同，或 `git diff --name-only <baseline>..HEAD` 只含 `.planning/` 路径。
|
||||
- 范围（两条都要）：①`git status --porcelain -uall -- <7 个代码 / 测试路径>` 只出现这 7 个路径（因 09-29 / 09-30 未提交，它们本来就在脏树里，仍应全部出现）；②整仓 `git status --porcelain -uall` 的每条路径必须属于这 7 个路径、或出现在基线 `dirty` 快照、或以 `.planning/` 开头，否则判范围外写入。
|
||||
- **顺序铁律**：先跑门禁，**再**写 SUMMARY；不得在门禁实际运行之前把结果写进 SUMMARY。
|
||||
|
||||
**C. 写 `.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md`（用 B 步的真实结果）：**
|
||||
- `TextContent` 新语义逐条：`watch(() => props.loc, …)`、`[x, y, props.width, props.autoHeight ? height : h, ax, ay]`、宽度不再取 `loc[2]`、非 `autoHeight` 用传入 `loc[3]`、`emit('updateHeight', height)` 与打字机时序不变；说明 `Textbox` 内嵌 `TextContent` 的宽度由整框宽度变为内容宽度是**有意修正**。
|
||||
- `bookDetail` 的 `cumsum` 等价性：`hs` / `ends = cumsum(hs)` / `ends[i] - hs[i]` 与原 `top` 的逐行对照，明确 `cumsum` 返回累计结束位置。
|
||||
- `key` 删除清单：`book` 13 / `bookDetail` 2 / `equipbox` 9 / `toolbox` 8 / `hotkey` 5，合计 37；说明**没有保留任何一个**，并写明「渲染器 `removeChild` 被实现为 `destroy` 的问题按 `dev.md` 第 123 行视为已知、假定修复，本计划未做任何 workaround」。
|
||||
- 注释改动清单：仅 `bookDetail` 两行旧重挂载注释替换为一行新注释；其余既有注释（含 `bookDetail` 的「一次遍历累加…」）未改。
|
||||
- 过期注释登记：`src/client/ui/bookDetail.tsx:58` 的 `/** 描述文本的实测高度，同时用于 TextContent 的 key */` 与 `:108` 的 `// 同值不写，避免高度回调与 key 重挂载互相触发`，在删 key 后已过期，**按 AGENTS.md 原样保留、未改一字**，此处如实记录（OI-3 ⑥）。
|
||||
- `TextContent` 的其它使用方声明：`inputBox.tsx` / `waitBox.tsx` / `statusBar.tsx` / `statistics.tsx` / `choices.tsx` / `src/client/plugin/shop/shop.tsx` / `packages-user/client-base/src/components/input.tsx` / `components/misc.tsx` 均**未改**；尺寸口径不变（这些调用点 `width` 与 `loc[2]` 相等，`autoHeight` 处仍取实测高度）；`choices` 等 computed `loc` 调用点的 x / y 现在会随 `loc` 变化响应式跟随，属本次修正的预期效果（OI-3 ⑦）。
|
||||
- 记录 B 步的真实门禁结果（`uiContainerGate` 用例数、`hotkeySettingsGate` 用例数、eslint NEW-only、`pnpm check:type` NEW-only、6 个受保护哈希、`textbox.tsx` 前后哈希、HEAD 政策、全仓脏文件快照范围闸门）。
|
||||
- 声明：`estimate` 未校准（`confidence: low`）；**不做浏览器 UAT，不宣称位置收敛 / 滚动 / 内存 / 点击命中 / 拖拽行为已验证**；09-29 / 09-30 改动未提交、这些路径在基线里本来就是脏的，范围闸门只证明「无新增范围外路径」；`book.tsx` 的过期 TODO 未改；`keyAdaptationGate.test.ts` 是既存失败、不在本计划范围；**执行器 0 次代码提交**（`.planning` 产物可能由编排器按 `commit_docs: true` 聚合提交），代码工作树留给用户审查。
|
||||
|
||||
**D. 最后跑摘要闸门：** 确认 SUMMARY 存在且包含上述必需声明（见下方最后一条 automated）；该闸门必须在 C 步之后运行，失败则补齐 SUMMARY 后重跑，不得只改闸门。
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cmd /c "pnpm exec vitest run src/client/ui/__test__/uiContainerGate.test.ts"</automated>
|
||||
<automated>cmd /c "pnpm exec vitest run src/client/ui/__test__/hotkeySettingsGate.test.ts"</automated>
|
||||
<automated>node -e "const cp=require('child_process'),fs=require('fs');const b=JSON.parse(fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json','utf8'));const files=['packages-user/client-base/src/components/textbox.tsx','src/client/ui/book.tsx','src/client/ui/bookDetail.tsx','src/client/ui/equipbox.tsx','src/client/ui/toolbox.tsx','src/client/ui/hotkey.tsx','src/client/ui/__test__/uiContainerGate.test.ts'];const r=cp.spawnSync('cmd',['/c','pnpm exec eslint -f json '+files.join(' ')],{encoding:'utf8',timeout:300000});const text=(r.stdout||'').trim();const bad=[];if(r.status===null||r.status>=2||!text)bad.push('eslint failed to run (status '+r.status+')');let arr=[];try{arr=JSON.parse(text||'[]')}catch(e){bad.push('eslint json unparsable')}const norm=p=>{const s=String(p).replace(/\\/g,'/');const i=s.search(/(packages-user|src)\//);return i>=0?s.slice(i):s};const cur=[];for(const f of arr){for(const m of (f.messages||[]))cur.push(norm(f.filePath)+'|'+String(m.ruleId||'null')+'|'+String(m.severity)+'|'+String(m.message).trim())}const before=b.eslint||[];const count=(a,v)=>{let n=0;for(const x of a)if(x===v)n++;return n};for(const v of new Set(cur)){if(count(cur,v)>count(before,v))bad.push('NEW eslint :: '+v)}if(bad.length){console.error('ESLINT GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK eslint: no new entries (baseline '+before.length+' -> current '+cur.length+')')"</automated>
|
||||
<automated>node -e "const cp=require('child_process'),fs=require('fs');const b=JSON.parse(fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json','utf8'));const scope=['packages-user/client-base/src/components/textbox.tsx','src/client/ui/book.tsx','src/client/ui/bookDetail.tsx','src/client/ui/equipbox.tsx','src/client/ui/toolbox.tsx','src/client/ui/hotkey.tsx','src/client/ui/__test__/uiContainerGate.test.ts'];const r=cp.spawnSync('cmd',['/c','pnpm check:type'],{encoding:'utf8',timeout:900000});const text=(r.stdout||'')+(r.stderr||'');const diag=text.split(/\r?\n/).filter(l=>/error TS\d+/.test(l));const bad=[];if(r.status===null)bad.push('vue-tsc did not run');else if(r.status!==0&&diag.length===0)bad.push('vue-tsc crashed with no parseable diagnostics');const norm=l=>l.replace(/\\/g,'/').replace(/\(\d+,\d+\):/,'').replace(/^.*?(?=(src|packages-user)\/)/,'').trim();const cur=diag.map(norm).filter(x=>scope.some(p=>x.indexOf(p)===0));const before=(b.typecheck||[]).filter(x=>scope.some(p=>x.indexOf(p)===0));const count=(a,v)=>{let n=0;for(const x of a)if(x===v)n++;return n};for(const v of new Set(cur)){if(count(cur,v)>count(before,v))bad.push('NEW diagnostic :: '+v)}if(bad.length){console.error('TYPECHECK GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK typecheck: no new diagnostics in changed files (baseline '+before.length+' -> current '+cur.length+')')"</automated>
|
||||
<automated>node -e "const cp=require('child_process'),fs=require('fs');const b=JSON.parse(fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json','utf8'));const bad=[];const keys=Object.keys(b.hashes||{});if(keys.length!==6)bad.push('baseline must protect 6 files, got '+keys.length);for(const file of keys){const r=cp.spawnSync('git',['hash-object',file],{encoding:'utf8'});if(r.status!==0)bad.push('cannot hash '+file);else if((r.stdout||'').trim()!==b.hashes[file])bad.push(file+' changed')}const tb='packages-user/client-base/src/components/textbox.tsx';const now=cp.spawnSync('git',['hash-object',tb],{encoding:'utf8'}).stdout.trim();if(now===b.textbox)bad.push('textbox.tsx was not modified');const head=(cp.spawnSync('git',['rev-parse','HEAD'],{encoding:'utf8'}).stdout||'').trim();if(head!==b.head){const d=cp.spawnSync('git',['diff','--name-only',b.head+'..'+head],{encoding:'utf8'});if(d.status!==0)bad.push('HEAD changed and diff failed');else{const nonPlan=(d.stdout||'').split(/\r?\n/).filter(Boolean).filter(p=>!p.startsWith('.planning/'));if(nonPlan.length)bad.push('HEAD changed with non-planning commits :: '+nonPlan.join(','))}}if(bad.length){console.error('PROTECTED GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK protected files unchanged; textbox.tsx modified; HEAD policy satisfied')"</automated>
|
||||
<automated>node -e "const cp=require('child_process'),fs=require('fs');const b=JSON.parse(fs.readFileSync('.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json','utf8'));const allowed=['packages-user/client-base/src/components/textbox.tsx','src/client/ui/book.tsx','src/client/ui/bookDetail.tsx','src/client/ui/equipbox.tsx','src/client/ui/toolbox.tsx','src/client/ui/hotkey.tsx','src/client/ui/__test__/uiContainerGate.test.ts'];const bad=[];if(!Array.isArray(b.dirty))bad.push('baseline dirty snapshot missing');const out=cp.spawnSync('git',['status','--porcelain','-uall'],{encoding:'utf8'}).stdout||'';const paths=out.split(/\r?\n/).filter(Boolean).map(l=>l.slice(3).replace(/^\"|\"$/g,'')).filter(p=>p.indexOf('.planning/')!==0);const before=new Set((b.dirty||[]).map(p=>String(p).replace(/\\/g,'/')));for(const p of paths)if(!allowed.includes(p)&&!before.has(p))bad.push('out-of-scope write :: '+p);for(const p of allowed)if(!paths.includes(p))bad.push('expected change missing :: '+p);if(bad.length){console.error('SCOPE GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK scope: no out-of-scope writes ('+paths.length+' dirty paths total, '+before.size+' pre-existing)')"</automated>
|
||||
<automated>node -e "const fs=require('fs');const p='.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md';const bad=[];if(!fs.existsSync(p))bad.push('summary missing');else{const s=fs.readFileSync(p,'utf8');for(const n of ['textbox.tsx','cumsum','37','removeChild','destroy','uiContainerGate','hotkeySettingsGate','eslint','check:type','confidence: low','UAT','0 次代码提交','ends[i] - hs[i]','props.autoHeight ? height : h','过期注释','choices'])if(s.indexOf(n)<0)bad.push('summary missing :: '+n)}if(bad.length){console.error('SUMMARY GATE FAILED :: '+bad.join(' ; '));process.exit(1)}console.log('OK summary content')"</automated>
|
||||
<fails_when>任一 vitest 用例失败；eslint 出现 NEW 条目（归一化口径与 scope 必须与 Task 1 相同，含 `textbox.tsx` 与测试文件）；`pnpm check:type` 在改动文件集合内出现 NEW 诊断（`norm` 与 scope 必须与 Task 1 逐字相同、保留 `src/` / `packages-user/` 前缀）；6 个受保护文件哈希变化（含 `inputBox.tsx` / `waitBox.tsx`）；`textbox.tsx` 哈希与基线相同（说明没改成）；HEAD 变化且 `baseline..HEAD` 含非 `.planning` 路径；7 个允许路径缺失；整仓脏文件里出现既不在基线 `dirty` 快照也不在 7 个允许路径中的新路径；`09-31-SUMMARY.md` 缺失或缺少必需声明；或任一 node 闸门非零退出。**不要把 `keyAdaptationGate.test.ts` 的既存失败计入本闸门**。**顺序错误（先写 SUMMARY 再跑门禁、或未运行就记录结果）同样判失败。**</fails_when>
|
||||
</verify>
|
||||
<done>`uiContainerGate.test.ts` 通过：无 `key={`（五文件 + `bookDetail` 的 `TextContent` 标签）、`bookDetail` 含 `cumsum(hs)` / `ends[i] - hs[i]` 且无 `top +=`、`textbox` 含 `watch(() => props.loc` 与六元组赋值、`book` 每行 11 `text` + 1 `icon` + 1 `g-rect`，且 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` / `nocache` / `*_SCROLL_LOC` 断言全部保留；每个 `it` 上方有一行注释；`hotkeySettingsGate` 仍全绿；eslint 无 NEW（7 路径同 scope）；`pnpm check:type` 改动文件内无 NEW（7 路径同 scope）；6 个受保护文件哈希与基线一致且 `textbox.tsx` 哈希已变；HEAD 与基线相同或仅含 `.planning` 聚合提交；7 个代码 / 测试路径全部出现且无新增范围外路径；**先跑完门禁、再写 `09-31-SUMMARY.md`、最后通过摘要闸门**，摘要如实声明未做浏览器 UAT、37 个 key 全删、渲染器问题假定修复且未做 workaround、执行器 0 次代码提交、估算未校准、范围闸门局限。</done>
|
||||
</task>
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| `TextContent` 的 props ↔ 内部渲染矩形 | `props.loc` 是调用方（`bookDetail` / `equipbox` / `toolbox` / `Textbox`）传入的几何契约；一旦组件不响应新引用，或宽度仍取 `loc[2]`，元素就会停在旧位置 / 用错宽度 |
|
||||
| 高度回调 ↔ 行位置计算 | `onUpdateHeight` 是异步上报；`textHeights → specialRows → loc` 形成闭环，同值早退是唯一的防循环保险 |
|
||||
| `Scroll` ↔ 列表子元素 | 删除 `key` 不改变子元素数量 / 顺序；一旦为此加包裹容器或条件渲染，`Scroll` 的平铺契约被破坏 |
|
||||
| 渲染系统 ↔ 本计划的范围 | 渲染器 `removeChild`/`destroy` 问题是已知缺陷；按 `dev.md` 假定修复，不得用 `key` / `Scroll` 改动规避 |
|
||||
| 用户可见行为 ↔ 未验证声明 | 本计划不做浏览器 UAT，任何「位置收敛已验证」的表述都属于不实声明 |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-09-31-01 | Tampering | `TextContent.updateLoc` 的宽度 / 高度来源 | high | mitigate | 源码闸门断言六元组形态 `[x, y, props.width, props.autoHeight ? height : h, ax, ay]`，并在 `updateLoc` 切片内禁止 `width = props.width` 与 `loc.value[2]`（切片外的 `Textbox` 既有 `data.width = props.width` 不在探针范围）；Task 4 断言 `textbox` 的唯一赋值形态 |
|
||||
| T-09-31-02 | Denial of Service | 高度回调闭环（`emit` → `updateTextHeight` → `specialRows` → `loc` → `updateLoc`） | high | mitigate | 保留 `updateTextHeight` 的同值早退（prohibition）；Task 4 断言 `textHeights` / `specialRows` / `SPECIAL_MIN_HEIGHT` 仍在；OI-2 规定出现无限回调必须停下上报 |
|
||||
| T-09-31-03 | Tampering | `bookDetail` 的 `cumsum` 误用（把累计结束位置当行顶） | medium | mitigate | 规定并断言 `ends[i] - hs[i]`；同时断言无 `top +=`，防止退回手写累加 |
|
||||
| T-09-31-04 | Tampering | 五个 UI 文件「删 key 顺手改结构」 | high | mitigate | Task 2 / 3 断言元素属性、`noevent`、`hidden` 分流、0 回退、`loc` 常量与 `Scroll` 块计数；Task 4 保留 flat-Scroll / 无容器 / `noevent` 配对断言 |
|
||||
| T-09-31-05 | Elevation of Privilege | 用改 `scroll.tsx` 或 `Textbox` 来「适配」缺 key 列表 | high | mitigate | `scroll.tsx` 等 6 个文件进入哈希闸门；`textbox.tsx` 改为「改动前哈希必须不同」的显式可改项；prohibition 明确禁止改 `Textbox` / `TextboxStore` |
|
||||
| T-09-31-06 | Repudiation | 声称「位置收敛 / 重挂载已验证」但未做浏览器 UAT | medium | mitigate | Task 0 汇报与 SUMMARY 均必须写明「未做浏览器 UAT」与「`removeChild`/`destroy` 问题假定修复、未做 workaround」；执行器不提交代码 |
|
||||
| T-09-31-07 | Tampering | 借删 key 之名重新引入索引 key / Fragment / 条件渲染 | high | mitigate | Task 2 / 3 / 4 对五文件断言 `key={` 为 0；prohibition 明确禁止索引 key 与容器 / `hidden` 开关；`Scroll` 内无 `container` 断言保留 |
|
||||
| T-09-31-SC | Tampering | npm / pnpm 安装 | high | mitigate | 本计划**不新增任何依赖、不执行安装命令**；若执行期出现安装需求，必须停下上报 |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- **源码形状**：`src/client/ui/__test__/uiContainerGate.test.ts` 全部断言通过（`?raw`，不导入组件）：保留 flat-Scroll / 无容器 / 显示开关分流 / 0 回退 / `noevent` / `nocache` / `*_SCROLL_LOC` / 无预建 `VNode` / 内联 `.map()`；新增「五文件无 `key={`」「`bookDetail` 的 `cumsum(hs)` + `ends[i] - hs[i]` 且无 `top +=`」「`textbox` 的 `watch(() => props.loc` + 六元组赋值 + `props.width` + `emit('updateHeight', height)`」；`book` 每行按标签计数为 11 `text` + 1 `icon` + 1 `g-rect`。
|
||||
- **静态检查**：`pnpm exec eslint` 对**同一组 7 个改动文件**无 NEW（Task 1 基线与 Task 4 比较的 scope 完全相同）；`pnpm check:type` 整仓运行后在**同一组 7 个路径**内无 NEW 诊断（既有基线诊断允许消失）。
|
||||
- **既有闸门**：`src/client/ui/__test__/hotkeySettingsGate.test.ts` 仍为绿（`hotkey.tsx` 只用 `g-rectr`、捕获阶段监听、`setKeyCombination(`、无持久化）。`keyAdaptationGate.test.ts` 是既存失败（15 个用例 5 个失败），不在本计划范围；不修、不声称全部既有闸门为绿。
|
||||
- **执行顺序**：全部门禁（vitest / eslint / check:type / 哈希 / HEAD / 范围）先跑完 → 再写 `09-31-SUMMARY.md` → 最后跑摘要闸门；不得在门禁运行前记录结果。
|
||||
- **范围**：`git status --porcelain -uall -- <7 个代码 / 测试路径>` 恰好只有这 7 个路径；整仓 `git status --porcelain -uall` 里没有「不在基线 `dirty` 快照、也不在这 7 个路径、也不在 `.planning/`」的新路径；**6 个**受保护文件（`scroll.tsx` / `settings.tsx` / `ui/index.ts` / `misc/hotkey.ts` / `inputBox.tsx` / `waitBox.tsx`）哈希与基线一致；`textbox.tsx` 哈希与基线**不同**。
|
||||
- **无代码提交**：HEAD 与 `09-31-BASELINE.json` 的 `head` 相同，或 `git diff --name-only <baseline>..HEAD` 只含 `.planning/` 路径；任何非 `.planning` 路径的提交都判失败。
|
||||
- **无浏览器验证声明**：SUMMARY 明确写入「未做浏览器 UAT，未宣称位置收敛 / 滚动 / 内存 / 点击命中 / 拖拽行为已验证」；并写明 `removeChild`/`destroy` 问题按 `dev.md` 假定修复、未做 workaround。
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- [ ] `packages-user/client-base/src/components/textbox.tsx`：`TextContent` 有 `watch(() => props.loc, () => { updateLoc(); })`；`updateLoc` 为 `const height = getHeight(); const [x = 0, y = 0, , h = 0, ax = 0, ay = 0] = props.loc ?? loc.value; loc.value = [x, y, props.width, props.autoHeight ? height : h, ax, ay]; emit('updateHeight', height);`；`typer` / 打字机 / `expose` / `Textbox` / `TextboxStore` / 既有注释零改动。
|
||||
- [ ] `bookDetail.tsx`：从 `@motajs/common` 导入 `cumsum`；`hs` → `ends = cumsum(hs)` → `specials.value.map((special, i) => …)` 用 `ends[i] - hs[i]` 得行顶，无 `top +=`；渲染无 `key`，`TextContent` 的 `loc` 每次新建；两行重挂载注释替换为一行新注释；高度逻辑与 0 回退不变。
|
||||
- [ ] `book.tsx`：13 个 `key` 删除；13 个元素（11 `text` + 1 `icon` + 1 `g-rect`）与全部属性、0 回退、`noevent`、三条既有 `//` 不变。
|
||||
- [ ] `equipbox.tsx` / `toolbox.tsx` / `hotkey.tsx`：9 / 8 / 5 个 `key` 删除；拖拽 / 悬停 / 再点使用 / 捕获 / 写回 / 分组切换等逻辑体零改动。
|
||||
- [ ] 五个 UI 文件在去注释源码里 `key={` 出现次数均为 0，且没有 Fragment / 容器 / 条件渲染 / `hidden` 开关作为替代。
|
||||
- [ ] `uiContainerGate.test.ts` 通过（含新增三组、`book` 按标签计数、每个 `it` 上方一行注释）；`hotkeySettingsGate` 全绿；eslint 无 NEW（7 路径同 scope）；`pnpm check:type` 改动文件内无 NEW（7 路径同 scope）；6 个受保护哈希一致且 `textbox.tsx` 已变；HEAD 政策 / 范围闸门通过。
|
||||
- [ ] **顺序正确**：先跑完所有门禁 → 再写 `09-31-SUMMARY.md` → 最后通过摘要闸门；摘要含 `TextContent` 新语义、`cumsum` 等价性、37 个 key 的删除清单、未做 workaround 声明、真实门禁结果、未 UAT 声明、估算未校准声明、执行器 0 次代码提交声明、范围闸门局限说明。
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md` **after all gates have actually run**, recording: the `TextContent` semantics change (`watch(() => props.loc, …)`, `[x, y, props.width, props.autoHeight ? height : h, ax, ay]`, width no longer taken from the incoming `loc[2]`, height from `getHeight()` when `autoHeight` else the incoming `loc[3]`, `emit('updateHeight', height)` and the typer pipeline untouched), the intentional visible effect that `Textbox`'s inner `TextContent` now uses the content width instead of the box width; the `cumsum` equivalence in `bookDetail` (`hs` / `ends = cumsum(hs)` / `ends[i] - hs[i]` equals the old `top`, with `cumsum` returning cumulative ends, not offsets); the complete key-removal inventory (`book` 13, `bookDetail` 2, `equipbox` 9, `toolbox` 8, `hotkey` 5 — 37 total, none retained, no index-key / Fragment / container / conditional-render / hidden workaround); the note that the renderer's `removeChild`-implemented-as-`destroy` remount problem is known and assumed fixed per `dev.md` line 123, with no workaround applied; the only comment replacement (the two `bookDetail` remount lines became one line stating the loc is now reactive) and that all other existing comments — including `bookDetail`'s "一次遍历累加…" and `book.tsx`'s stale TODO — were left untouched; gate results (all `uiContainerGate` groups including the three new ones, `hotkeySettingsGate`, eslint NEW-only and `pnpm check:type` NEW-only over the same seven-path scope, the six protected hashes, the changed `textbox.tsx` hash, HEAD policy, and the full-repo dirty-snapshot scope gate); the uncalibrated estimate (`confidence: low`, `tasks: 4` excluding the Task 0 checkpoint); skipped browser UAT; that 09-29 / 09-30's changes are still uncommitted (so the scope gate can only prove no new out-of-scope paths); the pre-existing `keyAdaptationGate.test.ts` failures that are out of scope; zero executor code commits; and that the code working tree is left for user review. Then re-run the summary gate.
|
||||
</output>
|
||||
|
||||
205
.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md
Normal file
205
.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md
Normal file
@ -0,0 +1,205 @@
|
||||
---
|
||||
phase: 09-minimum-browser-runnable
|
||||
plan: 31
|
||||
subsystem: ui
|
||||
tags: [vue, jsx, textcontent, reactive-loc, cumsum, key-removal, source-gate]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 09-minimum-browser-runnable
|
||||
provides: "09-30 的内联 JSX .map() 列表渲染、平铺 Scroll、0 值回退与 TextContent 高度测量"
|
||||
provides:
|
||||
- "TextContent 的 props.loc 响应式同步（宽度恒取 props.width，高度按 autoHeight 分流）"
|
||||
- "bookDetail 用 @motajs/common 的 cumsum 计算行位置"
|
||||
- "5 个列表型 UI 的 37 个 key 全部删除（不保留、不做 workaround）"
|
||||
- "16 组源码形状闸门（原 13 组，删 key / 重挂载断言，新增 3 组）"
|
||||
|
||||
# 未校准估算：09-29 / 09-30 的改动在基线时仍未提交，无法从工作树分离 09-31 自身的真实 diff。
|
||||
# 为避免把前序计划的工作计入 09-31，tokens 不虚报，记 null。
|
||||
actuals:
|
||||
tokens: null
|
||||
tasks: 4
|
||||
commits: 0
|
||||
note: "工作树自带 09-29 / 09-30 的未提交改动，无法分离 09-31 自身的 diff，tokens 记 null；tasks 只计 Task 1-4（Task 0 汇报关卡不计入）；commits 为 0，执行器未做任何代码提交。"
|
||||
|
||||
estimate:
|
||||
tokens: 70000
|
||||
raw_tokens: 35000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "TextContent 只从 props.loc 取 x / y / ax / ay，宽度恒取 props.width；调用方每次求值传新数组即可推动位置"
|
||||
- "行位置用 cumsum(hs) 的累计结束位置减去本行行高得到，不再手写累加变量"
|
||||
- "无状态、顺序固定的列表一律不加 key（dev.md 第 122-123 行）"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- .planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json
|
||||
- .planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md
|
||||
modified:
|
||||
- packages-user/client-base/src/components/textbox.tsx
|
||||
- src/client/ui/bookDetail.tsx
|
||||
- src/client/ui/book.tsx
|
||||
- src/client/ui/equipbox.tsx
|
||||
- src/client/ui/toolbox.tsx
|
||||
- src/client/ui/hotkey.tsx
|
||||
- src/client/ui/__test__/uiContainerGate.test.ts
|
||||
|
||||
key-decisions:
|
||||
- "TextContent 新增 watch(() => props.loc, updateLoc)，updateLoc 恒写六元组 [x, y, props.width, props.autoHeight ? height : h, ax, ay]，宽度不再取传入 loc[2]"
|
||||
- "bookDetail 的 specialRows 改为「行高 hs → ends = cumsum(hs) → ends[i] - hs[i] 为行顶」，删除 let top 与 top +="
|
||||
- "5 个 UI 文件的 37 个 key 全删（book 13 / bookDetail 2 / equipbox 9 / toolbox 8 / hotkey 5），一个都不保留，不加索引 key、不加 Fragment / 容器 / 条件渲染 / hidden 开关"
|
||||
- "渲染器 removeChild 被实现为 destroy 的既有问题按 dev.md 第 123 行视为已知并假定修复，本计划不做任何 workaround"
|
||||
- "按用户本轮授权，删除 bookDetail 中两处仍提到 key 的过期注释（原计划默认保留）"
|
||||
|
||||
patterns-established:
|
||||
- "响应式几何契约：调用方每次求值构造新 loc 数组，组件只按新引用同步自己的矩形，不靠 key 重挂载"
|
||||
- "累计位置：cumsum(hs) 返回累计结束位置，行顶必须写 ends[i] - hs[i]"
|
||||
|
||||
requirements-completed: []
|
||||
|
||||
duration: "未精确计时（约 30 分钟）"
|
||||
completed: 2026-10-28
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Phase 09 Plan 31: `TextContent` 响应式 loc + `bookDetail` 改用 `cumsum` + 5 个 UI 文件删除 37 个 `key` Summary
|
||||
|
||||
**让 `TextContent` 的 `props.loc` 真正响应式（宽度恒取 `props.width`、高度按 `autoHeight` 分流）、把 `bookDetail` 的行位置交给 `cumsum`、并按 `dev.md` 新规删掉 5 个列表型 UI 的全部 37 个 `key`；不新增入口、不改变行为口径、不做浏览器 UAT**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 未精确计时（约 30 分钟）
|
||||
- **Completed:** 2026-10-28
|
||||
- **Tasks:** 4（Task 1-4；Task 0 的 `blocking-human` 汇报关卡不计入）
|
||||
- **Files modified:** 6 个代码 / 测试文件 + 1 个 `.planning` 基线；另加本摘要与计划文件
|
||||
- **Commits:** 0（执行器严格未运行任何 git 写命令）
|
||||
|
||||
## Accomplishments
|
||||
|
||||
### 1. `TextContent` 的位置语义（`packages-user/client-base/src/components/textbox.tsx`）
|
||||
|
||||
- 新增专用 watcher，紧随 `updateLoc` 之后：`watch(() => props.loc, updateLoc);`（不传 `deep`，靠调用方每次求值产生的新数组引用触发）。
|
||||
- `updateLoc` 改为：
|
||||
|
||||
```ts
|
||||
const height = getHeight();
|
||||
const [x = 0, y = 0, , h = 0, ax = 0, ay = 0] = props.loc ?? loc.value;
|
||||
loc.value = [x, y, props.width, props.autoHeight ? height : h, ax, ay];
|
||||
emit('updateHeight', height);
|
||||
```
|
||||
|
||||
- 四条固定语义：①`x` / `y` / `ax` / `ay` 只来自传入的 `props.loc`（缺省退回 `loc.value` 同位）；②宽度恒为 `props.width`，**不再**取传入 `loc[2]`；③高度在 `props.autoHeight` 为真时取 `getHeight()` 的实测值，否则取传入 `loc[3]`；④`typer` / `retype` / `showAll` / `getHeight` / `renderContent` / `renderFunc` / `emit('updateHeight', height)` / `expose` / 既有 `watch(props, …)` / `Textbox` / `TextboxStore` / 既有注释全部一字未改。
|
||||
- 唯一有意为之的可见变化：`Textbox` 内嵌的 `TextContent` 宽度由「整框宽度」变为「内容宽度 `contentWidth`」。这是修正，不是回归。
|
||||
- `TextContent` 的其它 8 个使用方（`inputBox.tsx` / `waitBox.tsx` / `statusBar.tsx` / `statistics.tsx` / `choices.tsx` 两处 / `src/client/plugin/shop/shop.tsx` / `packages-user/client-base/src/components/input.tsx` / `components/misc.tsx`）**未改**；这些调用点 `width` 与 `loc[2]` 相等，`autoHeight` 处仍取实测高度，尺寸口径不变。`choices` 等 computed `loc` 调用点的 x / y 现在会随 `loc` 变化响应式跟随，属本次修正的预期效果。
|
||||
|
||||
### 2. `bookDetail` 的 `cumsum` 等价性（`src/client/ui/bookDetail.tsx`）
|
||||
|
||||
- 导入改为 `import { cumsum, ITileLocator } from '@motajs/common';`。
|
||||
- `specialRows` 改为三段式：行高 `hs` → `const ends = cumsum(hs);` → `specials.value.map((special, i) => …)`，行顶 `labelTop = ends[i] - hs[i]`、`textTop = ends[i] - hs[i] + SPECIAL_LABEL_HEIGHT`、`textHeight = hs[i] - SPECIAL_LABEL_HEIGHT - SPECIAL_GAP`。
|
||||
- 等价性逐行对照：原 `top` 从 0 开始，每行结束于 `top + SPECIAL_LABEL_HEIGHT + textHeight + SPECIAL_GAP`；`hs[i]` 正是这一增量，`ends[i] - hs[i]` 就是原来的 `top`，`textTop` / `textHeight` 与原来逐字一致。`cumsum` 返回的是**累计结束位置**（不是偏移），所以必须减去 `hs[i]`。
|
||||
- 文件内不再出现 `top +=`，也没有任何 `for` 累加。`textHeights` / `updateTextHeight`（含同值早退）/ `watch(specials, …)` / `SPECIAL_MIN_HEIGHT` 回退 / 0 值回退全部保留。
|
||||
- 渲染改为 `specialRows.value.map(row => [<text …/>, <TextContent …/>])`，两个元素**都没有 `key`**；`TextContent` 的 `loc` 为每次求值新建的 `[0, row.textTop, SPECIAL_WIDTH, row.textHeight]`，靠新引用触发位置同步；`autoHeight` / `onUpdateHeight` / `width` / `font` / `fillStyle` 逐字保留。
|
||||
|
||||
### 3. 37 个 `key` 的完整删除清单
|
||||
|
||||
| 文件 | 删除的 key | 数量 |
|
||||
|------|-----------|------|
|
||||
| `src/client/ui/book.tsx` | `hit-` / `icon-` / `name-` / `special-` / `hp-` / `atk-` / `def-` / `money-` / `exp-` / `dmg-` / `crit-` / `reduce-` / `def1-` | 13 |
|
||||
| `src/client/ui/bookDetail.tsx` | `label-` / `${code}-${textTop}-${textHeight}` | 2 |
|
||||
| `src/client/ui/equipbox.tsx` | 状态区 3、槽位 3、拥有装备 3 | 9 |
|
||||
| `src/client/ui/toolbox.tsx` | 永久道具列 4、可消耗道具列 4 | 8 |
|
||||
| `src/client/ui/hotkey.tsx` | 左栏 2、右栏 1、内层组合 2 | 5 |
|
||||
| **合计** | | **37** |
|
||||
|
||||
- **没有保留任何一个**；没有把 `key` 换成索引 key，也没有新增 Fragment / 容器 / 条件渲染 / `hidden` 开关作为替代。列表仍是内联 `.map()` 返回同级数组，`Scroll` 内仍无 `container`、无 `hidden=`。
|
||||
- 渲染系统当前 `removeChild` 被实现为 `destroy` 导致无法重新挂载的问题**仍然存在**，按 `dev.md` 第 123 行视为已知并**假定修复**，本计划**未做任何 workaround**（没有加回 `key`，也没有改 `Scroll`）。
|
||||
- 行为口径零变化：`book` / `bookDetail` 的 0 值回退、`bookDetail` 的 `SPECIAL_MIN_HEIGHT` 回退、`equipbox` 拖拽 / 悬停 / 再点穿戴、`toolbox` 再点使用、`hotkey` 捕获 / 写回 / 分组切换全部保持 09-30 口径。
|
||||
|
||||
### 4. 注释改动清单
|
||||
|
||||
- `bookDetail` 中描述「复制一次 `props.loc` / `key` 重挂载」的两行旧注释，替换为一行：`// TextContent 已按 props.loc 响应式同步位置，行位置变化时无需重挂载`（计划授权范围内）。
|
||||
- 按用户本轮明确授权，**删除**两处删掉 key 后已过期的注释：`ISpecialRow.textHeight` 上方的 `/** 描述文本的实测高度，同时用于 TextContent 的 key */` 与 `updateTextHeight` 上方的 `// 同值不写，避免高度回调与 key 重挂载互相触发`。这两处属于本计划对「既有注释只增不改」的**授权例外**（原计划默认保留，见下方「偏离说明」）。
|
||||
- 其余既有注释**一律未改**，包括 `bookDetail` 的 `// 一次遍历累加出每行位置；行高只在循环内使用，不写入接口`、`// 按特殊属性 code 记录实测描述高度…`、`// 只保留仍存在的条目…`，以及 `book.tsx` 里那条写着「留空」的过期 TODO。
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `packages-user/client-base/src/components/textbox.tsx` - `TextContent` 新增 `props.loc` 的 watcher，`updateLoc` 改为六元组形态（宽度恒 `props.width`、高度按 `autoHeight` 分流）；其余零改动。
|
||||
- `src/client/ui/bookDetail.tsx` - 导入 `cumsum`；`specialRows` 用 `hs` + `cumsum(hs)` + `ends[i] - hs[i]`；渲染去掉 2 个 `key`，`TextContent` 的 `loc` 每次新建；替换 1 处旧注释、删除 2 处授权删除的过期注释。
|
||||
- `src/client/ui/book.tsx` - 删除 13 个 `key`，元素、属性、0 回退、`noevent`、三条 `//` 与 `{/* … */}` 全部不变。
|
||||
- `src/client/ui/equipbox.tsx` - 删除 9 个 `key`，三处三元组结构、`hidden` 分流、拖拽 / 悬停逻辑与 4 个 `*_SCROLL_LOC` 全部不变。
|
||||
- `src/client/ui/toolbox.tsx` - 删除 8 个 `key`，两处四元组结构、`hidden={!!current}`、空文本回退、`clickItem` 再点使用全部不变。
|
||||
- `src/client/ui/hotkey.tsx` - 删除 5 个 `key`，两栏结构、`selectGroup` / `selectKey`、选中边框、根 `nocache` 全部不变。
|
||||
- `src/client/ui/__test__/uiContainerGate.test.ts` - 新增跨包 `?raw` 导入 `textbox.tsx`；删除 13 个 key 前缀断言与 2 处重挂载注释断言；`book` 每行改为按标签计数（11 `text` + 1 `icon` + 1 `g-rect`）；新增「五文件无 `key={`」「`cumsum` 且无 `top +=`」「`textbox` 响应式 loc」三组；其余保留项断言与辅助函数不变；每个 `it` 上方紧邻一行 `//`。
|
||||
- `.planning/phases/09-minimum-browser-runnable/09-31-BASELINE.json` - Task 1 在编辑任何代码之前写出的机器可读基线：`head` / 6 个受保护文件哈希 / `textbox.tsx` 改动前哈希 / 全仓脏文件快照 / 7 路径 eslint 基线 / 7 路径 typecheck 基线。
|
||||
- `.planning/phases/09-minimum-browser-runnable/09-31-SUMMARY.md` - 本文件。
|
||||
|
||||
## Gate Results（全部为实际运行结果）
|
||||
|
||||
| 闸门 | 结果 |
|
||||
|------|------|
|
||||
| `09-31-BASELINE.json` 结构 | 通过：`head` / `hashes`（6 条）/ `textbox` / `dirty`（25 条，已去 `.planning/`）/ `eslint` / `typecheck` 齐全；`textbox.tsx` 未被列入受保护哈希 |
|
||||
| `uiContainerGate.test.ts` | 通过：**16 passed / 16**（原 13 组，删 3 处 key 断言、新增 3 组） |
|
||||
| `hotkeySettingsGate.test.ts` | 通过：**12 passed / 12**（未修改该文件） |
|
||||
| `eslint`（同一组 7 个路径，只判 NEW） | 通过：基线 0 条 → 当前 0 条，**无 NEW** |
|
||||
| `pnpm check:type`（整仓，仅 7 路径 scope 内判 NEW） | 通过：7 路径内基线 6 条 → 当前 6 条，**无 NEW**（均为既有的 `AllNumbers | keyof IdToNumber` 诊断） |
|
||||
| 受保护文件哈希（6 个） | 通过：`scroll.tsx` / `settings.tsx` / `ui/index.ts` / `misc/hotkey.ts` / `inputBox.tsx` / `waitBox.tsx` 与基线逐字相等 |
|
||||
| `textbox.tsx` 前后哈希 | 通过：`b17e988d77c3a81fe3ce3250940e31a9774f8dfb` → `5b58de65007189314553be0aca48209bd9e25981`（**已变化**，证明确实改到位） |
|
||||
| HEAD 政策 | 通过：HEAD 仍为 `ff0f729cfc7065c00a57d2bf5fd8eb4ff8b74071`，与基线 `head` 相同，无任何提交 |
|
||||
| 改动范围 | 通过：`git status --porcelain -uall` 共 26 条脏路径，其中 25 条是基线快照里的既有脏文件，新增的只有 `textbox.tsx`；无任何范围外新路径 |
|
||||
| 摘要内容闸门 | 通过（本文件写完后再跑一次） |
|
||||
| `keyAdaptationGate.test.ts` | **既存失败，不在本计划范围**（09-30 记录：15 个用例 5 个失败，改动前即如此）；未修、未以它为绿、不声称全部既有闸门为绿 |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### 授权偏离（用户本轮 addendum）
|
||||
|
||||
**1. [用户授权] 删除 `bookDetail.tsx` 两处过期注释**
|
||||
- **原计划口径：** 这两处注释按 AGENTS.md「不得擅改既有注释」原样保留，只在 SUMMARY / OI-3 中登记为已知过期注释。
|
||||
- **实际执行：** 用户明确要求删除 `ISpecialRow.textHeight` 上方的 `/** 描述文本的实测高度，同时用于 TextContent 的 key */` 与 `updateTextHeight` 上方的 `// 同值不写，避免高度回调与 key 重挂载互相触发`。
|
||||
- **影响：** 仅注释；接口字段与 `updateTextHeight` 的同值早退逻辑一字未动。测试中新增两条否定断言，锁定这两段文字不再出现。
|
||||
|
||||
### 执行期自动修正
|
||||
|
||||
**2. [Rule 3 - 阻塞] watcher 写成 `watch(() => props.loc, updateLoc)`**
|
||||
- **发现于：** Task 1
|
||||
- **问题：** 计划给出的 `watch(() => props.loc, () => { updateLoc(); });` 会被 Prettier（`printWidth: 80` + `eslint-plugin-prettier/recommended`）展开成多行，`watch(` 与 `() => props.loc` 之间会插入换行，导致计划自带的形状闸门（要求字面量 `watch(() => props.loc`）失败。两者不可能同时满足。
|
||||
- **修正：** 改为等价的 `watch(() => props.loc, updateLoc);`（同一 source、同一回调，行为完全一致），既通过 prettier 也满足闸门字面量。
|
||||
- **文件：** `packages-user/client-base/src/components/textbox.tsx`
|
||||
|
||||
**3. [Rule 3 - 阻塞] 测试对 `TextContent` 的 `loc` 断言改用空白容忍正则**
|
||||
- **发现于：** Task 4
|
||||
- **问题：** 计划要求断言 `toContain('loc={[')`。经复核，Prettier 换行后仍保留 `loc={[` 字面量，因此原断言实际可以通过；此处的改动不是修复失败，而是把断言收紧为对字段顺序与取值的匹配。
|
||||
- **修正：** 改为对 `flatten(tagAround(...))` 断言 `/loc=\{\[\s*0,\s*row\.textTop,\s*SPECIAL_WIDTH,\s*row\.textHeight\s*\]\}/`，语义相同、比原来的字面量断言更严格，且与格式化无关。
|
||||
|
||||
### 未执行 / 保留项
|
||||
|
||||
- **`bookDetail` 的 `// 一次遍历累加出每行位置；行高只在循环内使用，不写入接口`** 在改成 `cumsum` 后已略显过时（已无循环），但按 AGENTS.md「不得擅改既有注释」**原样保留**，在此登记。
|
||||
- **`book.tsx` 的过期 TODO（写着「留空」）** 原样保留。
|
||||
- 未修改 `Scroll`、设置入口、UI 导出清单、按键注册表、`inputBox.tsx` / `waitBox.tsx`、`map/*`、`10-*` 及相关文档。
|
||||
|
||||
## Known Stubs
|
||||
|
||||
无。本计划不新增任何入口、不新增占位数据、不新增未接线的组件；5 个 UI 文件与 `TextContent` 的行为口径与 09-30 一致。
|
||||
|
||||
## Threat Flags
|
||||
|
||||
无新增信任边界：本计划只改组件内部的位置计算与列表属性，不新增网络 / 文件 / 认证 / 权限相关面。
|
||||
|
||||
## 未验证事项（必须如实声明）
|
||||
|
||||
- **未做浏览器 UAT**：位置收敛、滚动、内存、点击命中、拖拽手感、复用正确性**均未验证**，本摘要不宣称任何视觉 / 滚动 / 点击 / 拖拽行为已验证。
|
||||
- **估算未校准**：`estimate` 为 `confidence: low` 的未校准估算（`tokens: 70000` / `raw_tokens: 35000` / `tasks: 4`，Task 0 不计入）；`actuals.tokens` 因工作树自带 09-29 / 09-30 的未提交改动而无法分离，记 `null`。
|
||||
- **范围闸门的局限**：09-29 / 09-30 的 5 个 UI 文件与 `uiContainerGate.test.ts` 在本计划开始前就已经是脏的，因此范围闸门只能证明「没有新增范围外路径」，不能证明这些文件的全部内容都出自本计划；内容是否改到位由源码形状闸门负责。
|
||||
- **执行器 0 次代码提交**：本计划未运行任何 git 写命令（`add` / `commit` / `stash` / `checkout` / `restore` / `reset` / `worktree` 一律未执行），全部代码改动留在工作树，交由用户审查。两个 `.planning` 产物（`09-31-BASELINE.json` / 本 SUMMARY）可能由编排器按 `commit_docs: true` 聚合提交，不属于本计划的代码提交。
|
||||
- **`keyAdaptationGate.test.ts` 的既存失败**不在本计划范围，未修。
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- 5 个 UI 文件去注释源码中 `key={` 出现次数均为 0（实测 `book` 0 / `bookDetail` 0 / `equipbox` 0 / `toolbox` 0 / `hotkey` 0）。
|
||||
- `textbox.tsx` 的 `updateLoc` 仅保留一处 `loc.value` 赋值，形态为 `[x, y, props.width, props.autoHeight ? height : h, ax, ay]`。
|
||||
- `bookDetail.tsx` 含 `cumsum(hs)` 与 `ends[i] - hs[i]`，无 `top +=`。
|
||||
- 全部自动闸门以退出码 0 通过（摘要内容闸门在本文件写完后运行）。
|
||||
Loading…
Reference in New Issue
Block a user