diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 551b9aa..e4b3262 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -590,6 +590,7 @@ Plans: - [x] 10-31-PLAN.md — 两篇补写内容的独立读者审阅(沿用高级 I 人格)→ 问题清单 → 迭代修正(≤3 轮)→ 复审清零 - [x] 10-32-PLAN.md — 两篇补写内容的用户主导修订循环 → 用户确认 → 最终格式 / 构建 / SUMMARY 收尾 - [x] 10-42-PLAN.md — VitePress 内嵌自定义渲染器 demo 最小 POC(config alias / dedupe / isCustomElement / vue-jsx + 包装组件 + 渲染基础与 UISystem 两个 demo + 不进导航的 POC 页) +- [x] 10-54-PLAN.md — 用户审阅与收尾(19 篇非示例文档已审阅;示例 1-6 标记待审阅;文档审阅计划完成,带待审阅项) **说明:** 每篇中级教程遵循 `10-CONTEXT.md` D-21..D-44 的逐篇要点与阅读顺序(4/8/9/3)。**旧内容删除已并入本批(D-04,Wave 0 / 10-01)**:删除 `docs/guide/*`、`docs/dev/*`、`docs/logger/*`、`docs/api/*` 与首页 `docs/index.md`,并清理 `docs/.vitepress/config.ts` 的旧 `nav`/`sidebar` 键。文档改动为 `docs/intermediate/*.md`(新增)、`docs/.vitepress/config.ts` 与 `docs/.vitepress/api.ts`(缺失目录守卫,保留按包生成机制)。构建命令 `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`;`init.ts` 在 `docs/api/` 缺失时安全跳过。本机 PowerShell 禁止 `pnpm.ps1`,命令经 `cmd /c "..."` 执行。 diff --git a/.planning/STATE.md b/.planning/STATE.md index d1c507c..2a3974a 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,10 +4,10 @@ milestone: v1.0 current_phase: 10 current_phase_name: 文档重构 status: executing -stopped_at: Phase 10 进行中:中级 24 篇 + 高级 I 9 篇 + 高级 II 10 篇已收尾;10-06/10-11/10-12 待补 -last_updated: "2026-10-29T00:00:00.000Z" -last_activity: 2026-10-29 -last_activity_desc: 10-42 文档内嵌渲染 demo POC 完成并经用户人工验证 +stopped_at: Phase 10 进行中:10-54 文档审阅计划已收尾(非示例文档完成,示例 1-6 待审阅);10-06/10-11/10-12 待补 +last_updated: "2026-11-15T00:00:00.000Z" +last_activity: 2026-11-15 +last_activity_desc: 10-54 用户审阅计划收尾;非示例文档完成,示例 1-6 标记待审阅 state_head: dbbcf533dce2f22078a82d26817f36b85865da62 progress: total_phases: 10 @@ -29,11 +29,11 @@ See: .planning/PROJECT.md (updated 2026-09-17) ## Current Position Phase: 10 (文档重构) — IN PROGRESS -Plan: 第一批(中级 24 篇)、第二批(高级 I 7 篇)、第三批(高级 II 10 篇)、第四批(高级 I 补写 Mover/FaceHandler 2 篇)已收尾;10-42 文档内嵌渲染 demo POC 已完成并经用户验证;10-06 / 10-11 / 10-12 待补 +Plan: 第一批(中级 24 篇)、第二批(高级 I 7 篇)、第三批(高级 II 10 篇)、第四批(高级 I 补写 Mover/FaceHandler 2 篇)已收尾;10-42 文档内嵌渲染 demo POC 已完成并经用户验证;10-54 文档审阅计划已收尾(非示例文档完成,示例 1-6 待审阅);10-06 / 10-11 / 10-12 待补 Status: In Progress -Last activity: 2026-10-29 — 10-42 文档内嵌渲染 demo POC 完成并经用户确认(人工验证通过) +Last activity: 2026-11-15 — 10-54 用户审阅计划收尾;非示例文档完成,示例 1-6 标记待审阅 -Progress: Phase 10 · 29/32 plans(中级 + 高级 I 9 篇 + 高级 II 已收尾;总览 / 初级 / 高级 III / API / Agent 参考仍待推进)(另:10-42 文档内嵌渲染 demo POC 已完成并经用户验证,Phase 10 的计数收口仍归 10-41) +Progress: Phase 10 · 29/32 plans(中级 + 高级 I 9 篇 + 高级 II 已收尾;总览 / 初级 / 高级 III / API / Agent 参考仍待推进)(另:10-42 文档内嵌渲染 demo POC 已完成并经用户验证,10-54 文档审阅计划已收尾但示例 1-6 待审阅,Phase 10 的计数收口仍归 10-41) ## Performance Metrics @@ -268,6 +268,7 @@ Recent decisions affecting current work: - Phase 10 added (2026-10-14): 文档重构(重构过老、结构不佳、新人难懂的项目文档,面向新人/不懂代码的作者/有基础作者等多背景读者提供分层指南,并专门为 AI Agent 编写参考文档);Depends on Phase 9 - Phase 10 第一批(中级教程 24 篇 + 旧内容清空 + 站点注册 + D-09 修订 + 读者/用户修订循环)已完成并收尾(2026-10-20);第二批(高级 I 7 篇 + 站点注册 + 独立读者审阅 + 用户 6 轮修订)已完成并经用户确认收尾(2026-10-20);第三批(高级 II 10 篇 + 站点注册 + 独立读者审阅 + 用户 3 轮修订)已完成并经用户确认收尾(2026-10-23);第四批(高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订)已完成并经用户确认收尾(2026-10-24)。遗留 `10-06` / `10-11` / `10-12` 缺独立 SUMMARY,其范围已被后续修订覆盖 - Phase 10 增量 10-42(2026-10-29):VitePress 内嵌自定义渲染器 demo 最小 POC(DOM 包装组件动态 import 引擎 + 渲染基础 / UISystem 两个 demo + 不进导航 POC 页 + docs 局部 tsconfig + ESLint docs override);用户人工验证通过(原话 `pass`),页面 `docs/poc/render-demo.md` 与命名暂时保留;未做 fence 插件 / 正式渲染端文档批次 / client-base 组件 / nav·sidebar 注册;无源码改动、无 commit +- Phase 10 增量 10-54(2026-11-15):用户审阅计划收尾;19 篇非示例文档已审阅,6 篇示例保留现状并标记待审阅;文档审阅计划标记为完成(带待审阅项);未改源码/demo,未 commit;详见 `10-54-SUMMARY.md` ### Pending Todos diff --git a/.planning/phases/10-docs-restructure/10-43-PLAN.md b/.planning/phases/10-docs-restructure/10-43-PLAN.md new file mode 100644 index 0000000..5bbab97 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-43-PLAN.md @@ -0,0 +1,372 @@ +--- +phase: 10-docs-restructure +plan: 43 +type: execute +wave: 1 +depends_on: [] +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/tsconfig.json + - docs/.vitepress/config.ts + - docs/advanced/ii/index.md + - docs/advanced/index.md + - docs/advanced/ii/ui/ui-template.md + - docs/advanced/ii/ui/ui-template-ts.md + - docs/advanced/ii/ui/container-and-coordinates.md + - docs/advanced/ii/ui/basic-shapes.md + - docs/advanced/ii/ui/curves-and-paths.md + - docs/advanced/ii/ui/text.md + - docs/.vitepress/components/demos/ui/template-demo.tsx + - docs/.vitepress/components/demos/ui/container-demo.tsx + - docs/.vitepress/components/demos/ui/shapes-demo.tsx + - docs/.vitepress/components/demos/ui/curves-demo.tsx + - docs/.vitepress/components/demos/ui/text-demo.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 78000 + raw_tokens: 48000 + tasks: 7 + confidence: low +must_haves: + truths: + - "新增子分组下先落地 6 篇正文(Part 0 两篇 + Part 1 前四篇),每篇单 `#` H1、按 D-84 的理解顺序组织、末尾有 `## 边界与注意`;篇幅由内容决定,不套模板、不留 `[待补]` 占位" + - "所有 UI 示例是完整、结构正确的 TSX 组件/文件级片段(`defineComponent` + `SetupComponentOptions` + 返回 render 函数),Props 一律 `extends IGameUIPropsBase, DefaultProps`,`props` 数组含 `controller` / `instance` / `state`;属性名全程 camelCase;条件写 `hidden` 或三元、循环写 `.map()`;`key` 只在会重排/增删且需要保留身份时出现" + - "示例里的容器自定义标签只出现 `container-custom` 这一种写法(`docs/.vitepress/config.ts` 的 `custom` 数组同时放行 `container-custom` 与 `custom-container`,后者是运行时当前注册名);正文不出现渲染器类名、渲染器初始化、标签注册、以及以 core 开头的命名空间;不出现 Thumbnail / Tip;`icon` / `winskin` / `map-render` 只作占位" + - "5 个 live demo(template / container / shapes / curves / text)都是 `.tsx` 默认导出组件,无 DOM 属性;其中 4 个只 import vue 与元素标签(不得出现任何 `@motajs/*` / `@user/*`),唯一例外是 `text-demo.tsx` 可以 `import { Font } from '@motajs/render'`(元素层类,不是渲染器)且必须用**位置参数**构造 `new Font('Verdana', 32, 'px', 700)`(签名 `(family, size, sizeUnit, weight, italic)`),不得调用 `Font.defaults`;页面用 `<ClientOnly>` 包裹 `RenderDemo` 且 loader 为 `() => import('...')`,文档正文不展示 demo 源码" + - "`docs/tsconfig.json` 的 `include` 增加 `.vitepress/**/*.tsx`(其余字段原样),`cmd /c \"pnpm exec vue-tsc --noEmit -p docs/tsconfig.json\"` 中路径以 `docs/` 开头且含 `error TS` 的行为 0" + - "侧边栏在高级 II 分组内新增嵌套子分组,只登记已存在的 6 篇;`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`(前者是文档写法,后者是运行时当前注册名);`cmd /c \"pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build\"` 通过、输出含 `build complete`、无 dead link" + - "`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 不再声称本层只写数据端 / 渲染端未完工,并给出指向新子分组的一句入口;两页**都**写出同一条性能边界(「高级 II 的性能篇讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III」);`docs/advanced/ii/index.md` 的「本层一共十篇」改写为「十篇数据端 + 27 篇 UI 子分组」,并列明「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端」" + - "`cmd /c \"pnpm exec prettier --check docs/advanced/ii/ui docs/.vitepress/components/demos/ui\"` 通过;`cmd /c \"pnpm exec eslint docs/.vitepress/components/demos/ui\"` 为 0 error / 0 warning" + - "未改 `packages/` / `packages-user/` / `src/`、未改 `10-01`..`10-42` 的计划与 POC 记录、未改既有 JSDoc/注释;本计划不产生任何 git commit" + artifacts: + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表 + 用户确认标记 + 参考清单哈希基线 + 写作硬规则 + 门禁记录区)" + - "docs/advanced/ii/ui/ui-template.md、ui-template-ts.md、container-and-coordinates.md、basic-shapes.md、curves-and-paths.md、text.md" + - "docs/.vitepress/components/demos/ui/template-demo.tsx、container-demo.tsx、shapes-demo.tsx、curves-demo.tsx、text-demo.tsx" + - "docs/tsconfig.json(include 增加 `.vitepress/**/*.tsx`)" + - "docs/.vitepress/config.ts(`custom` 数组追加 `container-custom`;高级 II 分组内新增嵌套子分组与两个 Part 分组)" + - "docs/advanced/ii/index.md、docs/advanced/index.md(措辞修正 + 子分组入口)" + key_links: + - "页面 → live:`.md` 里 `import RenderDemo from '../../../.vitepress/components/renderDemo.vue'` + `() => import('../../../.vitepress/components/demos/ui/xxx-demo.tsx')`;demo 由包装组件在 `onMounted` 动态 import,因此 SSR 预渲染不触碰 `document`" + - "demo → 渲染树:demo 只写 vue 的 `ref` / `computed` 与元素标签,标签由 docs 的 `isCustomElement` 放行、由 `vuejsx` 编译;属性名 camelCase 才能命中元素的属性处理。`text-demo` 是唯一允许从 `@motajs/render` 取元素层类 `Font` 的 demo——那是元素,不是渲染器,仍不创建渲染器、不初始化画布;其余 4 个 demo 必须零引擎 import" + - "侧边栏 → 页面:每条 `link` 必须是 `docs/advanced/ii/ui/` 下已存在的文件名,否则构建报 dead link;因此登记与建页在同一任务内完成" + - "`docs/tsconfig.json` → vue-tsc:`.tsx` 进入 include 后 demo 才参与类型检查;根 `tsconfig.json` 已为 `jsx: preserve` + `jsxImportSource: vue`,docs 配置沿用即可" + - "跨页引用时序:目标页已存在时才写 `./xxx.md` 链接;目标页要到后续批次才创建时只写纯文本(如「第 8 篇『层级、变换与性能』」「第 17 篇『内置组件:文本与输入』」),由创建该页的批次回填链接。本计划第 3 / 4 / 6 篇因此都含纯文本前瞻引用,不含前向 markdown 链接" +--- + +> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。 + + +本计划 7 个任务、16 个 `files_modified`,超出「2–3 任务 / ≤ 8 文件」的默认上限,仍保持单计划: + +- 任务拆分的依据是「每个任务能独立验证」:Task 0 是用户关卡,Task 1 是基础设施(改完即可构建),Task 2/Task 3/Task 4 各写 2 篇正文 + 对应 demo + 侧边栏登记,Task 5 是六类门禁收口,Task 6 是用户 live 目视。再合并会让「4 篇正文 + 4 个 demo + 侧边栏 + 全量门禁」压成一个不可独立验证的巨块。 +- 16 个文件里 6 个是正文、5 个是 demo、2 个是导览修正、1 个是 docs 配置、1 个是侧边栏、1 个是本批记录文件。它们共享同一套写作规则、同一份参考清单哈希与同一次构建,切片只会让记录与门禁跨计划重复。 +- 用户原始建议把 Part 0 + Part 1 八篇放在 10-43;实测这会让单计划吃下 8 篇正文 + 7 个 demo + 4 个基础设施文件,单次执行超出智能区。本计划把 Part 1 后两篇(图片与最小纹理、层级变换与性能)移到 10-44,与 Part 2 合并为 6 篇,保持「每计划 ≤ 8 篇」的约束;批次边界与依赖关系已在 10-44 的 `` 中说明。 +- 成本约占单计划预算的 78%(`estimate.tokens` 78,000 / 单计划预算 100,000;`raw_tokens` 48,000 × 校准系数),无跨计划依赖(`depends_on: []`、`wave: 1`)。 + +不因篇幅删内容:6 篇正文、5 个 live、导览修正、参考清单哈希校验、六类门禁、用户 live 目视全部保留。 + + + +在高级 II 下开出子分组「自定义 UI 与渲染」,落地其中第一组正文(Part 0 起步两篇 + Part 1 元素与布局前四篇),并把这一批的写作基础设施一次建好:docs 的 `.tsx` 类型入口、侧边栏嵌套子分组、live demo 目录约定、参考清单哈希基线、以及高级 II / 高级总导览的措辞修正。 + +Purpose: 读者第一次写 UI 需要一条从「复制模板 → 打开面板」开始的直线路径,并且作者的例子必须全部是可运行的 TSX;文档站的侧边栏、类型检查与 live 机制必须先支撑得住这批页面,后续四个批次才能只做加法。 +Output: 6 篇正文、5 个 `.tsx` live demo、`10-CUSTOM-UI-NOTES.md` 记录文件、`docs/tsconfig.json` 与侧边栏(含 `custom` 数组放行 `container-custom`)的加法式改动、两处导览措辞修正。**不改源码、不改已有正文、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/STATE.md +@.planning/ROADMAP.md +@.planning/phases/10-docs-restructure/10-CONTEXT.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-42-PLAN.md +@.planning/phases/10-docs-restructure/10-42-POC-NOTES.md +@docs/.vitepress/config.ts +@docs/tsconfig.json +@docs/.vitepress/components/renderDemo.vue +@docs/poc/render-demo.md +@docs/advanced/ii/index.md +@docs/advanced/index.md + +**本批定位(D-10 / D-11 / D-13 / D-14):** +- 这是 Phase 10 的又一次增量派发:**只新增 10-43..10-49 七个计划**(其中 10-48 只做独立读者审阅、10-49 做用户主导修订与收尾),不改 `10-01`..`10-42`,不重规划其它批次,不补 `10-06` / `10-11` / `10-12`。 +- 27 篇按 6 个内容计划推进:10-43(基础设施 + 6 篇)、10-44(Part 1 后两篇 + Part 2 四篇)、10-45(Part 3 四篇)、10-46(Part 4 五篇)、10-47(Part 5 六篇);写作完成后 10-48(独立读者审阅)、10-49(用户主导修订 + 最终门禁 + 落位评估 + 收尾)。 +- **Task 0 是硬关卡**:先汇报本计划要写什么、页面文件名 / 侧边栏显示名 / demo 文件与组件名 / 落点 / 参考文件清单与哈希策略,等用户明确回复「可以执行」;未收到前不得改任何文件、不得派发修改子代理。 +- 页面文件名、侧边栏显示名、子分组名、demo 文件名与组件名都属 D-13,**必须先经用户同意**;本计划里出现的名字一律标注为「建议值,待 Task 0 确认」。 +- 越界内容(源码修改、既有正文改写、nav 新增顶层入口、fence 插件)只记录、不实施(D-14)。 + +**本批写作硬规则(全批一致,逐条来自锁定决策与 `10-CUSTOM-UI-RESEARCH.md`):** +- 目标读者:完全没写过 UI、不知道 canvas 是什么的作者。只讲写 UI 必需的 Vue 概念(响应式、props、条件、循环、组件、slots、attrs);不讲作者不需要调用的初始化。 +- 示例一律 TSX,不用单文件组件示例;条件写 `hidden` 或三元,循环写 `.map()`;`key` 只在列表会重排 / 插入 / 删除且需要保留元素身份时加(`dev.md:122`),不为规避重挂载问题加 `key`(`dev.md:123`)。 +- `hidden` = 不显示、不交互:保留元素与状态,跳过绘制与命中;三元会创建 / 销毁并重置状态,只在「必须真正不存在」「需要重置状态或生命周期」「子树很重且长期不用」时用。 +- 属性名一律 camelCase(`fillStyle` / `strokeStyle` / `lineWidth` / `anchorX` / `zIndex`)。容器自定义标签全批只用 `container-custom` 这一种写法。 +- UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`,`props` 数组至少含 `controller` / `instance` / `state`。 +- `update:xxx` 只作为 `v-model:xxx` 的使用说明出现,不教读者手动监听对应的事件属性。 +- 组件内按键用 `useKey(props.state.hotkey.system)!` 非空断言,不加多余类型守卫。 +- 正文不出现渲染器类名、渲染器初始化、标签注册;不出现以 core 开头的命名空间(当它不存在,live 跑不起来也保留内容)。 +- 不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位,不展开内部。 +- 正文不写「源码里怎么实现」的叙述、不写仓库行号引用;跨页引用:**目标页已存在时**写 `./xxx.md#标题`,**目标页要到后续批次才创建时**先写纯文本(如「第 8 篇『层级、变换与性能』」),由创建该页的批次回填链接——绝不在目标页存在前写 markdown 链接,否则构建报 dead link。 +- 代码块是完整、结构正确的文件 / 类 / 函数级片段(D-62 / D-70 / D-87),注释按 D-65 尽量写;编辑器产出的内容(配置、生成物)不手写(D-73)。 +- 篇幅由内容决定(D-88);一节只回答一个问题,认知跳跃处补 1–2 句过渡(D-86);按「问题 / 场景 → 系统模型 → 机制与理由 → 接口 / 用法 → 完整示例 → 边界」组织(D-84)。单 `#` H1,`## 边界与注意` 收尾(D-61)。 +- live 一律 `RenderDemo` + `.tsx` demo:页面 `` 包裹、loader 写 `() => import('...')`、正文不展示 demo 源码;跑不起来不阻塞、不删内容。 +- 文件 CRLF;每篇写完后跑 prettier(D-45)。 + +**参考文件与哈希(写作前必查,变化即停):** `10-CUSTOM-UI-RESEARCH.md` 的 `## Reference Manifest` 已给出 A–F 各表在基线 `b94b4c3` 的 `git rev-parse HEAD:` 哈希。本计划只用其中与元素属性、TSX 属性、UI 栈、live 基础设施相关的条目;Task 1 用 `git hash-object -- ` 逐条核对并把结果写进 NOTES。**任何一条哈希与 Manifest 不一致,或 `git status --porcelain -- ` 显示工作树已改,立即停下向用户报告,不得按旧内容继续写作。** `src/client/ui/choices.tsx` 只允许接口参考,且工作树版本与 HEAD 不同(Manifest I 节已记录),本计划不读它。 + + + + + + Task 0: 汇报本批拆分、命名清单与落点,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(User Constraints、Page Plan、Docs Placement / Conventions、Per-page Notes 第 1–6 篇、Reference Manifest)、.planning/phases/10-docs-restructure/10-CONTEXT.md(D-09、D-10、D-11、D-13、D-14、D-45、D-46、D-84..D-90)、.planning/phases/10-docs-restructure/10-42-PLAN.md(Task 0 汇报与关卡体例)、docs/.vitepress/config.ts:215-257(高级 II 现有分组)、docs/.vitepress/components/renderDemo.vue、docs/poc/render-demo.md + 向用户做四段汇报并停下等待(D-12)。 + +**要做什么**——在高级 II 下新开子分组「自定义 UI 与渲染」(建议名,待确认),本计划先落地 6 篇正文(UI 通用模板、同一 UI 的 TS 元素层写法、容器与坐标、基础图形、曲线与路径、文字),配套 5 个 `.tsx` live demo,并把这一批的基础设施一次建好。**不做**任何源码修改、不改已有正文语义、不动 nav 顶层入口。 + +**为什么**——读者的第一个 UI 需要一条能照着抄的直线路径;先把模板、坐标、图形、文字讲通,后面的响应式、组件化、内置组件与完整示例才有落点。基础设施(`.tsx` 类型入口、侧边栏骨架、demo 目录、参考清单哈希)必须先立,否则后面每个批次都要重复一遍。 + +**大致怎么做**——Task 1 建记录文件并核对参考清单哈希、给 `docs/tsconfig.json` 加 `.tsx`、修正两处导览措辞,然后跑首次全量构建;Task 2 写 Part 0 两篇 + 模板 demo 并登记侧边栏;Task 3 写容器与坐标、基础图形两篇 + 两个 demo;Task 4 写曲线与路径、文字两篇 + 两个 demo;Task 5 收口六类门禁(prettier / ESLint / docs 类型 / 构建 / 静态断言 / 记录);Task 6 由用户在浏览器目视 live 与抽查正文。 + +**影响范围**——只新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `docs/.vitepress/components/demos/ui/` 下 5 个 `.tsx`,加法式修改 `docs/.vitepress/config.ts`(高级 II 分组内新增嵌套子分组;`custom` 数组追加 `container-custom`,保留 `custom-container`)与 `docs/tsconfig.json`(include 增加 `.tsx`),修正 `docs/advanced/ii/index.md` 与 `docs/advanced/index.md` 两处措辞,新增 `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md`。不动 `packages/`、`packages-user/`、`src/`、已有正文、nav 顶层入口、POC 页与 `10-01`..`10-42`。 + +**必须整份交给用户确认的清单(建议值,未确认不得落盘):** + +| 项 | 建议值 | +|----|--------| +| 子分组名 | 自定义 UI 与渲染 | +| 子分组内分组 | Part 0 起步 / Part 1 元素与布局 / Part 2 交互与数据 / Part 3 组件化 / Part 4 内置组件与 UI 系统 / Part 5 完整示例 | +| 目录 | `docs/advanced/ii/ui/` | +| 第 1 篇 | `ui-template.md` ·「UI 通用模板(TSX)」 | +| 第 2 篇 | `ui-template-ts.md` ·「同一 UI 的 TS 元素层写法」 | +| 第 3 篇 | `container-and-coordinates.md` ·「容器与坐标」 | +| 第 4 篇 | `basic-shapes.md` ·「基础图形」 | +| 第 5 篇 | `curves-and-paths.md` ·「曲线与路径」 | +| 第 6 篇 | `text.md` ·「文字」 | +| 后续 21 篇文件名 | 见 `10-CUSTOM-UI-RESEARCH.md` 的「建议目录与文件名」表(本次一并确认,后续批次不再重开命名) | +| demo 目录 | `docs/.vitepress/components/demos/ui/` | +| 本计划 demo | `template-demo.tsx`(`TemplateDemo`)/ `container-demo.tsx`(`ContainerDemo`)/ `shapes-demo.tsx`(`ShapesDemo`)/ `curves-demo.tsx`(`CurvesDemo`)/ `text-demo.tsx`(`TextDemo`) | +| 侧边栏层级 | 高级 II → 子分组 → 6 个 Part → 篇目(两层嵌套);若渲染不理想,退化为子分组下 27 条平铺 | +| 落点 | 先全部写进高级 II 的新子分组;合并 / 拆分的评估留到 10-49 | +| 导览更新时机 | 本计划只做措辞修正 + 一句入口;完整目录表留到 10-49 收尾 | + +同时说明:①本计划的 6 篇与 5 个 demo 在本计划内完成,Part 1 后两篇(图片与最小纹理、层级变换与性能)与 Part 2 合并到 10-44,原因是单计划不超过 8 篇正文;②参考清单以 `10-CUSTOM-UI-RESEARCH.md` 的 Manifest 为准,写作前逐条核对哈希,变化即停;③改名即改本计划中对应路径与断言,其余结构不变;④**容器标签的已知重构点**:运行时代码当前注册的自定义标签名是 `custom-container`,而用户已锁定文档统一写 `container-custom`;本计划会在 `docs/.vitepress/config.ts` 的 `custom` 数组里同时放行两者(docs-only,不改 `packages/`),因此构建不会报未知标签,但 live 里的 `container-custom` 可能暂时不渲染——这是已知重构点,不阻塞写作与构建,也**不得**把文档改写回 `custom-container`、**不得**要求修改 `packages/`。**未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;执行期间不得调用 `opencode` 命令;不得修改任何既有 JSDoc / 注释;本计划不做 git commit。然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。 + 尚无产物;本任务只汇报拆分、命名清单、落点与参考清单策略,供用户裁决。 + 确认:①是否同意本批 27 篇拆成 10-43..10-49 七个计划(六个内容计划 + 10-48 审阅 + 10-49 修订收尾)、且 10-43 只做 6 篇 + 基础设施;②子分组名、6 个 Part 名、目录、27 个文件名与侧边栏名、demo 目录与 5 个 demo 名是否采用建议值(逐项可改);③侧边栏两层嵌套是否可接受;④是否同意本计划只做导览措辞修正、完整目录表留到 10-49;⑤是否接受「不改源码、不改已有正文、不 commit」;⑥是否接受「文档统一写 `container-custom`,并在 docs 的 `custom` 数组里同时放行 `custom-container`,live 可能暂时不渲染」。⑥确认后不得再要求改回 `custom-container` 或改 `packages/`。 + 回复「可以执行」以继续(可同时给出命名选择);其它回复视为未批准,本计划停在此处。 + 用户已回复「可以执行」;子分组名、目录、6 个 Part 名、27 个文件名与侧边栏名、demo 目录与 5 个 demo 名、侧边栏层级、导览更新时机逐项确定。用户未回复「可以执行」前不得创建或修改任何文件。汇报中已完整给出上表与拆分理由。 + + 用户已回复「可以执行」,且命名与落点已逐项确认(含最终子分组名、6 个 Part 名、6 篇文件名、5 个 demo 名、侧边栏层级、导览更新时机)。 + + 用户回复「可以执行」且命名清单已确定。 + + + + Task 1: 记录命名与参考清单哈希 + docs 的 .tsx 入口 + 导览措辞修正 + 首次构建 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/tsconfig.json, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md + 用户已在 Task 0 明确回复「可以执行」,且命名清单已逐项确认;命令在仓库根目录执行。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(Reference Manifest A–G、Docs Placement / Conventions、写作规范表)、docs/tsconfig.json(全文)、docs/advanced/ii/index.md(全文,重点 15 与 77-81 两处措辞)、docs/advanced/index.md(重点 13 与 36-41)、.planning/config.json(security_enforcement / ASVS 级别) + 本任务做四件事。 + +**(a)新建 `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md`**(CRLF、UTF-8)。这是本批七个计划共用的**追加式**记录文件,后续只允许在末尾追加小节,不得改写前面已写内容。内容顺序: +1. 标题与一行说明「本文件记录 10-43..10-49 的命名、参考清单哈希、门禁与人工验证,只追加不改写」。 +2. **命名总表**:按 Task 0 确认结果逐项写最终值,覆盖子分组名、6 个 Part 名、目录、27 个文件名与侧边栏显示名、demo 目录、27 篇各自是否配 live 与 demo 文件名。 +3. 独占一行 `用户确认(10-43):可以执行`,**下一行**以 `用户原文:` 开头写用户原话;紧接着独占一行写 `基线 HEAD:` + `git rev-parse HEAD` 的完整 sha(**本批七个计划的起点**;10-48 的 Task 1 会记录 `基线 HEAD(10-48 记录)` 用于证明审阅期间未改正文,10-49 的 Task 1 会另行记录 `基线 HEAD(10-49 记录)` 用于收尾断言,此处只作整批起点的补充证据)。 +4. **参考清单哈希基线**:一张表,列为「路径 / Manifest 哈希(HEAD)/ 写作前 `git hash-object -- ` 实测 / 是否一致」,覆盖 `10-CUSTOM-UI-RESEARCH.md` 中本批会引用的条目(Manifest A:`core/item.ts`、`core/types.ts`、`core/graphics.ts`、`core/misc.ts`、`core/transform.ts`、`core/canvas2d.ts`、`style/font.ts`、`assets/texture.ts`;B:`render-vue/src/props.ts`、`elements.ts`、`tag.ts`、`types.ts`、`use.ts`;C:`system/src/ui/*`;F:`client-base/src/types.ts`、`client-modules/src/client.ts`、`ui/func.ts`、`src/bootstrap.ts`、`src/client/ui/main.tsx`、`inputBox.tsx`、`title.tsx`、`load.tsx`;G:`docs/.vitepress/components/renderDemo.vue`、`demos/basicRender.vue`、`demos/uiSystem.vue`、`docs/.vitepress/config.ts`)。另单列一行记录 `src/client/ui/choices.tsx` 的**工作树** `git hash-object` 值与其 HEAD 值(Manifest I 已注明两者不同,只允许接口参考)。 +5. 一句规则:**任一文件实测哈希与 Manifest 不一致、或 `git status --porcelain -- ` 非空(`docs/.vitepress/config.ts` 与 `docs/tsconfig.json` 本计划自己要改,除外),立即停下向用户报告,不得按旧内容继续写作。** +6. **写作硬规则摘要**(把本计划 `` 里的十二条规则压缩成可执行清单)。 +7. **门禁记录区**:预留 `## 门禁记录` 与 `## 人工验证记录` 两个二级标题,本任务只建标题,内容由 Task 5 / Task 6 追加。 + +**(b)`docs/tsconfig.json`**:`include` 数组增加一项 `"./.vitepress/**/*.tsx"`(放在现有 `.vue` 项之后)。**不得**改 `extends`、`baseUrl`、`paths`、`ignoreDeprecations`,不得把它并入 `pnpm check:type`,不得改根 `tsconfig.json` / `tsconfig.node.json`。 + +**(b-2)`docs/.vitepress/config.ts` 的 `custom` 数组**:在 `'custom-container'` 之后追加一项 `'container-custom'`(用户锁定的文档写法)。**只做加法**:保留 `'custom-container'`(运行时代码当前注册的名字)、不动 `map-render` / `animate` / `damage` / `graphics` / `icon` / `winskin` 这些既有项、不改 `isCustomElement` 函数体、不改 `vuejsx({ isCustomElement })` 调用点、不引入新依赖。这是 docs-only 改动,**不得**改 `packages/` / `packages-user/` / `src/`,也**不得**把文档改写回 `custom-container`。 + +**(c)导览措辞修正(两处,只改矛盾句,不改篇目表)**: +- **前置约束**:本任务**不得**在 `docs/advanced/ii/index.md` / `docs/advanced/index.md` 里写入任何指向 `./ui/...` 的 markdown 链接,也不得写入 `/advanced/ii/ui/...` 形式的站内链接——这些页面要到 Task 2 才创建,提前写会让 `pnpm docs:build` 报 dead link。本任务只写纯文本入口,链接由 Task 2 在页面落盘后回填。 +- `docs/advanced/ii/index.md`:把「这里仍然只写数据端;引擎编写者的内容属于高级 III。」改写成「这一层的主体是数据端;另有自定义 UI 与渲染子分组(见侧边栏),面向要在画布上写界面的作者。」;把「本层不覆盖什么」里的「**渲染端与编辑器**:渲染端表现、编辑器属性项、状态栏展示、怪物图鉴都不在本层范围内」改写为只排除「编辑器属性项、状态栏展示、怪物图鉴」,并补一句「界面绘制与 UI 系统见子分组『自定义 UI 与渲染』」——**改写后该页不得残留 `渲染端与编辑器` 这一小标题**。**同时改三处计数/受众/边界措辞**:①把「本层一共十篇:这一页导览,加上九篇正文。」改成「本层一共十篇(这一页导览 + 九篇数据端正文),另有『自定义 UI 与渲染』子分组 27 篇(见侧边栏)。」;②在 UI 子分组入口处补一句「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端;上文的数据端前置只对数据端篇目成立。」;③补一句性能边界「高级 II 的性能篇(第 21 篇)讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III。」。其余表格、篇目表、插件边界不动。 +- `docs/advanced/index.md`:把「渲染端尚未完工,本层当前只收录数据端内容;渲染端专属篇目只以占位符出现,等渲染端完工后补齐。」改写成说明高级 II 已收录自定义 UI 与渲染子分组、但本层其它篇目仍以数据端为主;并在提到「性能」的位置补**与上一页同一句**「高级 II 的性能篇(第 21 篇)讲 UI 系统的缓存与显示策略,引擎级性能仍属高级 III」,避免与高级 III 重叠。**只改这些语义,不新增顶层导航、不改 phase 表其它行、不动「三条路径」计数**(第四条路径在两处导览的收尾批次 10-49 Task 3 才写入)。 + +**(d)首次全量构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`。把结论写进 NOTES 门禁区:`首次构建:green` 并附命令与关键输出(`build complete` / dead link 行数)。若 red:先只回退本任务 (b)(b-2)(c) 的改动再跑一次,判断是否由本次改动引起;回退后仍 red 则**停止后续所有任务**,把完整报错贴回对话等用户指令,不得自行修复既有问题。另跑一次 `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,确认 `docs/` 路径 0 报错,把条数与摘要(含既有引擎报错条数)记进 NOTES 门禁区。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; if(-not(Test-Path -LiteralPath $n)){ Write-Error "MISSING $n" }; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'CONFIRM-10-43' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'CONFIRM-QUOTE' }; foreach($k in @('命名总表','参考清单哈希基线','写作硬规则','## 门禁记录','## 人工验证记录','choices.tsx')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD:[0-9a-f]{7,40}'){ Write-Error 'NOTES-NO-BASE-HEAD' }; if($np -match "(?=0})){console.error("TSCONFIG-NO-TSX");process.exit(1)}const keep=[".vitepress/**/*.ts",".vitepress/**/*.vue","../src/types/vite-env.d.ts"];keep.forEach(function(k){if(!inc.some(function(v){return v.indexOf(k)>=0})){console.error("TSCONFIG-LOST:"+k);process.exit(1)}});if(t.extends!=="../tsconfig.json"){console.error("TSCONFIG-EXTENDS");process.exit(1)}if(!t.compilerOptions||t.compilerOptions.baseUrl!==".."||t.compilerOptions.ignoreDeprecations!=="6.0"){console.error("TSCONFIG-OPTS");process.exit(1)}const p=t.compilerOptions.paths||{};if(!p["@motajs/*"]||!p["@user/*"]){console.error("TSCONFIG-PATHS");process.exit(1)}console.log("TSCONFIG-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'TSCONFIG-FAIL' }; $cfg1=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); if($cfg1.IndexOf('container-custom') -lt 0){ Write-Error 'CFG-NO-CONTAINER-CUSTOM' }; if($cfg1.IndexOf('custom-container') -lt 0){ Write-Error 'CFG-LOST-CUSTOM-CONTAINER' }; if($cfg1.IndexOf('isCustomElement') -lt 0){ Write-Error 'CFG-LOST-ISCUSTOM' }; if($cfg1.IndexOf("'map-render'") -lt 0 -and $cfg1.IndexOf('"map-render"') -lt 0){ Write-Error 'CFG-LOST-MAPRENDER' }; $ii=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($ii -match '仍然只写数据端'){ Write-Error 'INDEX2-STILL-DATA-ONLY' }; if($ii.IndexOf('自定义 UI 与渲染') -lt 0){ Write-Error 'INDEX2-NO-ENTRY' }; if($ii.IndexOf('custom-range.md') -lt 0){ Write-Error 'INDEX2-LOST-TABLE' }; if($ii -match '\]\(\./ui/'){ Write-Error 'INDEX2-FORWARD-LINK' }; if($ii.IndexOf('/advanced/ii/ui/') -ge 0){ Write-Error 'INDEX2-FORWARD-LINK-ABS' }; if($ii.IndexOf('27 篇') -lt 0){ Write-Error 'INDEX2-NO-UI-COUNT' }; if($ii.IndexOf('渲染端与编辑器') -ge 0){ Write-Error 'INDEX2-OLD-RENDERER-TERM' }; if($ii.IndexOf('一共十篇:') -ge 0){ Write-Error 'INDEX2-OLD-COUNT' }; if($ii.IndexOf('基础 TS') -lt 0){ Write-Error 'INDEX2-NO-AUDIENCE' }; if($ii.IndexOf('引擎级性能仍属高级 III') -lt 0){ Write-Error 'INDEX2-NO-PERF-BOUNDARY' }; $ad=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($ad -match '\]\(\./ui/'){ Write-Error 'INDEX1-FORWARD-LINK' }; if($ad.IndexOf('引擎级性能仍属高级 III') -lt 0){ Write-Error 'INDEX1-NO-PERF-BOUNDARY' }; if($ad -match '渲染端尚未完工'){ Write-Error 'INDEX1-STILL-UNFINISHED' }; if($ad.IndexOf('自定义 UI 与渲染') -lt 0){ Write-Error 'INDEX1-NO-ENTRY' }; if($ad.IndexOf('高级 III') -lt 0){ Write-Error 'INDEX1-LOST-III' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK' + non-zero exit, or output contains "MISSING", "CONFIRM-10-43", "CONFIRM-QUOTE", "NOTES-MISSING", "NOTES-NO-BASE-HEAD", "NOTES-LF-ONLY", "TSCONFIG-", "TSCONFIG-FAIL", "CFG-NO-CONTAINER-CUSTOM", "CFG-LOST-", "INDEX2-", "INDEX1-", "INDEX1-FORWARD-LINK", "INDEX1-NO-PERF-BOUNDARY", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK" + + NOTES 存在且含命名总表、独占一行 `用户确认(10-43):可以执行` + 下一行 `用户原文:`、独占一行 `基线 HEAD:`、参考清单哈希基线表(含 choices.tsx 的 HEAD 与工作树两值)、写作硬规则、`## 门禁记录` 与 `## 人工验证记录` 两个预留标题;`docs/tsconfig.json` 的 include 含 `*.tsx` 且既有三项 / extends / baseUrl / paths / ignoreDeprecations 未变;`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`,其余既有项(含 `map-render`)与 `isCustomElement` 未变;两处导览不再出现矛盾句并给出子分组入口,原篇目表与高级 III 引用仍在,且**不含**任何指向 `./ui/...` 的前向链接(入口只有纯文本,链接由 Task 2 回填);`docs/advanced/ii/index.md` 的「一共十篇」已改写为「十篇数据端 + 27 篇 UI 子分组」,并写明「Part 0 起步只要求基础 TS / JS,不要求先读高级 I 或数据端」;`docs/advanced/ii/index.md` 与 `docs/advanced/index.md` **两页都**含同一句性能边界;首次全量构建 green、无 dead link;`vue-tsc -p docs/tsconfig.json` 下 `docs/` 路径 0 报错并把结论记入 NOTES。 + 命名与哈希基线落盘,docs 接受 `.tsx`,导览矛盾句已修,首次构建 green。 + + + + Task 2: Part 0 两篇(UI 通用模板 / TS 元素层写法)+ 模板 demo + 侧边栏子分组骨架 + docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/ui-template-ts.md, docs/.vitepress/components/demos/ui/template-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/index.md + NOTES 含 `用户确认(10-43):可以执行`;Task 1 的首次构建 green;子分组名、两篇文件名与 demo 名已确认。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 1、2 篇;Author Entry 全节;Render Elements 的「所有元素共有的属性」)、.planning/phases/10-docs-restructure/10-42-POC-NOTES.md(命名与落点体例)、packages-user/client-base/src/types.ts:16-55(IGameUIPropsBase 与 ClientCore 的两个控制器)、src/bootstrap.ts:12-16、src/client/ui/title.tsx:1-3、docs/.vitepress/components/renderDemo.vue、docs/.vitepress/config.ts:215-257 + 写两篇正文与一个 demo,并在侧边栏建立子分组骨架。 + +**(1)`ui-template.md`(第 1 篇)**:按 D-84 顺序写。开头用两三句话回答「UI 是什么、canvas 是什么」——画面由本框架的元素绘制,作者用 TSX 描述结构,不用 DOM。然后给**完整最小模板**:`import { defineComponent } from 'vue'`、`import { GameUI, SetupComponentOptions } from '@motajs/system'`、`import { DefaultProps } from '@motajs/render-vue'`、`import { IGameUIPropsBase } from '@user/client-base'`;`interface MyPanelProps extends IGameUIPropsBase, DefaultProps {}`;`const myPanelProps = { props: ['controller', 'instance', 'state'] } satisfies SetupComponentOptions<MyPanelProps>`;组件用 `defineComponent<MyPanelProps>` 返回 render 函数,内部是 `container` + `g-rect` + `text`;最后 `export const MyPanelUI = new GameUI('my-panel', MyPanel)`。随后给「只改哪几行」表格(文件名 / 组件名 / `GameUI` 名、`container` 的 `loc`、里面的元素、Props 基类、`props` 列表、打开处)。再讲打开与关闭三个位置:`client.sceneController.open(MyPanelUI, {})`(作者入口)、`props.controller.open(MyPanelUI, {})`(在另一个 UI 内)、`props.controller.close(props.instance)`(关闭自己),并各配一小段说明;主 UI 栈只用一句话交代 `props.state.mainUIController.open(...)` 的存在,不展开。最后放 live(`template-demo`)。`## 边界与注意` 写:少声明 `controller` / `instance` / `state` 中任何一个就拿不到对应 props;Props 基类只能用 `IGameUIPropsBase` 配 `DefaultProps`;属性名必须 camelCase,写错不报错也不生效;不要用单文件组件写法。 + +**(2)`template-demo.tsx`**:默认导出一个 `defineComponent`,只 import `vue` 的所需符号(若不需要响应式就不要 import 多余符号),根节点 `container` 逻辑尺寸 480×320,内含 `g-rect` 背景与 `text`;不 import 任何引擎包,不创建渲染器或 canvas,不写 `style` / `class`;组件名 `TemplateDemo`。 + +**(3)`ui-template-ts.md`(第 2 篇)**:讲同一画面用元素层接口怎么写:先用 `ref<Container>()` 拿到 TSX 里的 `container`,在 `onMounted` 里 `new Rect()` / `new Text(...)`,用 `size` / `pos` 设几何、用**各自类上的 setter** 设样式(图形:`rect.setFillStyle(...)` / `rect.setStrokeStyle(...)`;文字:`label.setText(...)` / `label.setStyle(fill, stroke)` / `label.setFont(...)`——`setFillStyle` 只在 `GraphicItemBase` 上,`Text` 没有它),再 `host.value!.appendChild(rect, label)`;给完整组件片段(含 import 与 render 函数)。然后给**两张**对照表而不是一张:`TSX 属性 ↔ 图形元素 setter`(`loc` ↔ `pos` + `size`、`fillStyle` ↔ `setFillStyle`、`strokeStyle` ↔ `setStrokeStyle`)与 `TSX 属性 ↔ 文字元素 setter`(`loc` ↔ `pos`、`text` ↔ `setText`、`fillStyle` / `strokeStyle` ↔ `setStyle`、`font` ↔ `setFont`),并明确「两套映射不能混用:把 `setFillStyle` 用在文字元素上不成立」。再讲清楚三件事:元素层不参与 Vue 响应式、改属性必须调 setter、`ref` 要等挂载后才拿得到实例所以放在 `onMounted`;`host.value!` 是组件内必定存在的非空断言。live 复用 `template-demo`(说明「同一画面,两种写法」)。`## 边界与注意` 写:元素层是画布元素,不能直接当 UI 打开(UI 必须是 Vue 组件);不要为了拿到容器去查询 DOM;不要在这里引入渲染器。 + +**(4)侧边栏**:在 `docs/.vitepress/config.ts` 的高级 II 分组 `items` 末尾新增一个嵌套子分组对象:`text` 为确认后的子分组名、`collapsed: false`,其 `items` 里先放一个 `{ text: '起步', collapsed: false, items: [...] }`,`items` 两条分别指向 `'/advanced/ii/ui/ui-template'` 与 `'/advanced/ii/ui/ui-template-ts'`,显示名按确认结果。**只做加法**:不动高级 II 既有 10 条、不动高级 I / III 分组、不改任何既有注释与缩进风格(4 空格)。**每条 link 必须对应本任务已创建的文件**,否则构建会报 dead link。 + +**(5)回填导览链接**:两篇页面已在本任务落盘,把 Task 1 写下的纯文本入口改成带链接的版本——在 `docs/advanced/ii/index.md` 的那句入口里,用 `[UI 通用模板](./ui/ui-template.md)` 与 `[同一 UI 的 TS 元素层写法](./ui/ui-template-ts.md)` 两个链接指向本任务创建的两篇。**只加这两个链接**:不得加其它 `./ui/...` 链接(其余 25 篇要到后续批次才创建),不得改导览其它段落。 + +写完后先跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`(D-45),再交给自动门禁。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const p1="docs/advanced/ii/ui/ui-template.md";const p2="docs/advanced/ii/ui/ui-template-ts.md";[p1,p2].forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const s1=fs.existsSync(p1)?rd(p1):"";["defineComponent","SetupComponentOptions","GameUI","IGameUIPropsBase","DefaultProps","controller","instance","state","sceneController.open","props.controller.open","props.controller.close(props.instance)","g-rect","container","text"].forEach(function(k){if(s1.indexOf(k)<0)bad.push("P1:"+k)});if(!/\x3cClientOnly\x3e/.test(s1))bad.push("P1:NO-CLIENTONLY");if(!/\(\)\s*=>\s*import\(/.test(s1))bad.push("P1:NO-LOADER");const s2=fs.existsSync(p2)?rd(p2):"";["appendChild","ref\x3cContainer\x3e","onMounted","Rect","Text","setFillStyle","setText","setStyle","setFont"].forEach(function(k){if(s2.indexOf(k)<0)bad.push("P2:"+k)});const d="docs/.vitepress/components/demos/ui/template-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT");if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE-IMPORT");["container","g-rect","text"].forEach(function(k){if(s.indexOf(k)<0)bad.push("DEMO:"+k)});if(/style=|class=/.test(s))bad.push("DEMO-DOM-ATTR")}const idx2=rd("docs/advanced/ii/index.md");if(idx2.indexOf("./ui/ui-template.md")<0||idx2.indexOf("./ui/ui-template-ts.md")<0)bad.push("INDEX-BACKFILL");if((idx2.match(/\]\(\.\/ui\//g)||[]).length!==2)bad.push("INDEX-FORWARD-LINK");const cfg=rd("docs/.vitepress/config.ts");if(cfg.indexOf("/advanced/ii/ui/ui-template")<0||cfg.indexOf("/advanced/ii/ui/ui-template-ts")<0)bad.push("SIDEBAR-LINKS");if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("SIDEBAR-LOST");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "CRLF:", "P1:", "P2:", "NO-DEMO", "DEMO-", "SIDEBAR-", "INDEX-BACKFILL", "INDEX-FORWARD-LINK", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK" + + 两篇正文各单 H1、含 `## 边界与注意`、CRLF;第 1 篇含完整模板所需的全部标识符(`defineComponent` / `SetupComponentOptions` / `GameUI` / `IGameUIPropsBase` / `DefaultProps` / 三个 props 名 / 三个打开关闭入口),并用 `<ClientOnly>` + `() => import(...)` 接 live;第 2 篇含 `appendChild` 与**两张**元素层 setter 对照表(图形:`setFillStyle` / `setStrokeStyle`;文字:`setText` / `setStyle` / `setFont`),并明确两套映射不能混用、元素层不当 UI 打开;两篇都不出现被禁写法;`template-demo.tsx` 默认导出、只 import vue、无 DOM 属性、含 container / g-rect / text;侧边栏新增嵌套子分组、两条链接指向已建页面、高级 II 既有条目与高级 III 分组未丢;`docs/advanced/ii/index.md` 的纯文本入口已回填这两个页面的链接,且全文只有这两处 `./ui/` 链接(其余 25 篇此时尚未创建);全量构建 green 且无 dead link。 + Part 0 两篇与模板 demo 完成,侧边栏子分组骨架可用且构建 green。 + + + + Task 3: 容器与坐标 / 基础图形两篇 + 两个 demo + 侧边栏登记 + docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/.vitepress/components/demos/ui/container-demo.tsx, docs/.vitepress/components/demos/ui/shapes-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-43):可以执行`;Task 2 的页面与侧边栏骨架已存在且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 3、4 篇;Render Elements 的属性默认值 / 各元素专属属性 / loc 顺序;Common Pitfalls)、packages/render/src/core/types.ts:37-44(ElementLocator)、packages/render-vue/src/props.ts:24-160、packages/render/src/core/graphics.ts:37-49(图形默认值)、docs/.vitepress/config.ts(Task 2 新增的子分组结构) + 写两篇正文与两个 demo,并把它们登记进侧边栏。 + +**(1)`container-and-coordinates.md`(第 3 篇)**:先回答「坐标从哪来」——根容器的左上角就是原点,子元素坐标相对父容器左上角;容器同时是布局单位与事件捕获单位。再讲 `loc` 的六元组顺序 `[x, y, width, height, anchorX, anchorY]` 与等价的分开属性,讲锚点 0 / 0.5 的差别(默认 `anchorX` / `anchorY` 为 0,圆形与椭圆默认 0.5)。给出默认值表(`width` / `height` 默认 200),提醒按需显式给尺寸。示例写一个 480×320 根容器,内部两个不同 `loc` / `anc` 的嵌套容器,各放一个 `g-rect` 标出边界并用 `text` 标注坐标。`zIndex` 只讲「越大越靠上」一句,细节留给第 8 篇——**此处只写纯文本「第 8 篇『层级、变换与性能』」,不要写 `./layer-transform-performance.md` 链接**(该页在 10-44 创建,届时由 10-44 回填)。元素层的 `appendChild` / `removeChild` 只用一两句话带过(完整写法见第 2 篇)。live 用 `container-demo`。`## 边界与注意`:默认尺寸 200 容易被忽略;锚点改变了元素「自己的哪一点」落在 `x` / `y` 上;不要用 DOM 的定位思路去理解嵌套。 + +**(2)`basic-shapes.md`(第 4 篇)**:四个基础图形 `g-rect` / `g-circle` / `g-ellipse` / `g-line` 各给一个最小示例;讲清 `fill` / `stroke` / `strokeAndFill` 是**模式开关**,`fillStyle` / `strokeStyle` 才是样式;讲线宽、虚线、端点与连接样式(`lineWidth` / `lineDash` / `lineCap` / `lineJoin`);讲 `g-line` 用两点(`x1` / `y1` / `x2` / `y2` 或 `line`)自动算位置与大小;讲 `radius` / `radiusX` / `radiusY`;讲 `actionStroke` 让命中区域只算描边。同一页里给一张「默认填充 / 默认描边」对照表。live 用 `shapes-demo`,点击让某个图形换色(这为第 10 篇埋伏笔,正文用一句话点明「事件在第 10 篇展开」——**只写纯文本,不加链接**;该页在 10-44 创建,届时由 10-44 回填)。`## 边界与注意`:默认色是浅灰,示例要显式给色;`fill` 不是颜色属性;圆的默认锚点与矩形不同。 + +**(3)两个 demo**:`container-demo.tsx`(`ContainerDemo`)展示嵌套容器 + 半透明矩形 + 坐标标注文字;`shapes-demo.tsx`(`ShapesDemo`)展示四个图形 + 点击换色(用 `ref<string>` 存颜色,`onClick` 改值)。都只 import vue 与元素标签,默认导出组件,不 import 引擎包,不写 `style` / `class`。 + +**(4)侧边栏**:在 Task 2 建的子分组 `items` 里追加 `{ text: '元素与布局', collapsed: false, items: [...] }`,两条链接分别指向 `/advanced/ii/ui/container-and-coordinates` 与 `/advanced/ii/ui/basic-shapes`。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const pages={"docs/advanced/ii/ui/container-and-coordinates.md":["loc","anc","anchorX","anchorY","width","height","zIndex","container","g-rect","text"],"docs/advanced/ii/ui/basic-shapes.md":["g-rect","g-circle","g-ellipse","g-line","fillStyle","strokeStyle","lineWidth","lineDash","actionStroke","radius"]};Object.keys(pages).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});pages[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("NO-CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("NO-LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["container-demo.tsx","shapes-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/container-and-coordinates","/advanced/ii/ui/basic-shapes","/advanced/ii/ui/ui-template","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK' + non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "NO-CLIENTONLY", "NO-LOADER", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK" + + 两篇正文单 H1、含 `## 边界与注意`、CRLF、含各自必需标识符(容器篇:`loc` / `anc` / `anchorX` / `anchorY` / 默认尺寸 / `zIndex` 一句;图形篇:四个图形与填充描边 / 线宽虚线 / `actionStroke` / `radius`),都接 live 且不出现被禁写法;两个 demo 默认导出、只 import vue、无 DOM 属性;侧边栏新增「元素与布局」两条且既有条目未丢;构建 green、无 dead link。 + 容器与坐标、基础图形两篇与两个 demo 完成并已登记。 + + + + Task 4: 曲线与路径 / 文字两篇 + 两个 demo + 侧边栏登记 + docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/.vitepress/components/demos/ui/curves-demo.tsx, docs/.vitepress/components/demos/ui/text-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-43):可以执行`;Task 3 的两篇与「元素与布局」分组已存在且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 5、6 篇;各元素专属属性表的曲线 / 路径 / 文字行)、packages/render/src/core/graphics.ts:564-1014(曲线、路径、圆角矩形的属性语义)、packages/render/src/style/font.ts:35-60(`constructor(family, size, sizeUnit, weight, italic)` 位置参数与静态默认值)、:160-192(`Font.defaults` / `Font.clone` 的 `Partial` 形式)、packages/render/src/core/misc.ts:10-147(文字默认填充色 / 描边宽度 / 自动尺寸)、docs/.vitepress/config.ts(Task 3 后的子分组结构) + 写两篇正文与两个 demo,并把它们登记进侧边栏。 + +**(1)`curves-and-paths.md`(第 5 篇)**:先一句话说明「曲线用控制点画,路径用浏览器自带的 `Path2D` 存一组子路径」。`g-bezier` 讲三点式控制点(起点、两个控制点、终点)与 `curve` 八元数组;`g-quad` 讲单控制点与六元数组;`g-path` 讲 `path` 必须是 `Path2D` 实例(给出在组件外用 `new Path2D()` 组好再传入的完整片段);`g-rectr` 讲圆角数组:`circle` 1–4 项、`ellipse` 2 / 4 / 6 / 8 项,并说明为什么四个角可以不同。给一张「默认描边 / 默认填充」对照表,指出曲线默认描边、路径与圆角矩形默认填充。live 用 `curves-demo`:一条三次贝塞尔、一条二次贝塞尔、一个 `Path2D` 折线、一个圆角矩形。`## 边界与注意`:`path` 传字符串不行;`curve` 数组长度写错不会报错只是画不对;圆角矩形与矩形的命中区域不同。 + +**(2)`text.md`(第 6 篇)**:先讲文字元素是最简单也最容易误用的一种:`text` 属性 + `fillStyle` 填充 + 可选描边(`stroke` / `strokeStyle` / `strokeWidth`);字体用 `font`(`Font` 类型),给出**位置参数**构造 `new Font('Verdana', 32, 'px', 700)`(签名 `(family, size, sizeUnit, weight, italic)`,默认值取自 `Font.defaultFamily` / `Font.defaultSize` 等静态字段)与命名式的 `Font.clone(Font.defaults(), { size: 32, weight: 700 })`;**构造函数只接受位置参数——不要传对象字面量(对象形式的配置只属于 `Font.defaults` / `Font.clone` 的 `Partial`)**;讲文字尺寸由测量决定,不要给 `width` / `height` 期待裁剪;讲用锚点把文字居中(`anchorX` / `anchorY` 0.5)。明确说明文字元素**不会自动换行**,需要换行、打字机效果时用第 17 篇的文本组件——**此处只写纯文本「第 17 篇『内置组件:文本与输入』」,不要写 `./builtin-text-and-input.md` 链接**(该页在 10-46 创建,届时由 10-46 回填)。live 用 `text-demo`:三种字号 / 颜色的对照,加一个 `new Font('Verdana', 32, 'px', 700)` 的标题(**位置参数构造**;live 里不调用 `Font.defaults`、不改 `Font.defaultFamily` 等静态默认值,避免影响后续 demo 的默认字体;正文可以讲 `Font.defaults` / `Font.clone` 的语义)。`## 边界与注意`:`fillStyle` 默认白色;`strokeWidth` 默认 1;给文字设宽高不会截断;长文本不要用文字元素硬排。 + +**(3)两个 demo**:`curves-demo.tsx`(`CurvesDemo`)与 `text-demo.tsx`(`TextDemo`),都默认导出组件、无 DOM 属性。`curves-demo` **只** import vue 与元素标签;`text-demo` 额外允许 `import { Font } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`,且必须用 `new Font('Verdana', 32, 'px', 700)` 构造、不得调用 `Font.defaults`。`CurvesDemo` 的 `Path2D` 在组件内构造一次即可(不要每次渲染都 new,必要时用 `ref` 或模块内常量并在注释里说明原因)。 + +**(4)侧边栏**:在「元素与布局」分组的 `items` 末尾追加两条链接,分别指向 `/advanced/ii/ui/curves-and-paths` 与 `/advanced/ii/ui/text`。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/new\s+Font\s*\(\s*\{/];const pages={"docs/advanced/ii/ui/curves-and-paths.md":["g-bezier","g-quad","g-path","g-rectr","Path2D","curve","circle","ellipse"],"docs/advanced/ii/ui/text.md":["text=","fillStyle","strokeStyle","strokeWidth","Font","Font.defaults","anchorX","anchorY"]};Object.keys(pages).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});pages[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("NO-CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("NO-LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const t=fs.existsSync("docs/advanced/ii/ui/text.md")?rd("docs/advanced/ii/ui/text.md"):"";if(t.indexOf("不会自动换行")<0){bad.push("TEXT-NO-WRAP-NOTE")}if(t.indexOf("](./builtin-text-and-input.md)")>=0){bad.push("TEXT-FORWARD-LINK")}if(t.indexOf("第 17 篇")<0){bad.push("TEXT-NO-PLAINREF")}["curves-demo.tsx","text-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-NO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(f==="text-demo.tsx"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+f);if(!/new\s+Font\(\s*[\x22\x27]/.test(s))bad.push("DEMO-NO-FONT-CTOR:"+f);if(/new\s+Font\(\s*\{/.test(s))bad.push("DEMO-FONT-OBJ-CTOR:"+f);if(/Font\.defaults/.test(s))bad.push("DEMO-FONT-DEFAULTS:"+f)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f)}});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/curves-and-paths","/advanced/ii/ui/text","/advanced/ii/ui/container-and-coordinates","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK' + non-zero exit, or output contains "NO-CONFIRM-10-43", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "TEXT-NO-WRAP-NOTE", "TEXT-FORWARD-LINK", "TEXT-NO-PLAINREF", "NO-CLIENTONLY", "NO-LOADER", "CRLF:", "NO-DEMO", "DEMO-", "DEMO-NO-FONT-CTOR", "DEMO-FONT-OBJ-CTOR", "DEMO-FONT-DEFAULTS", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T4-OK" + + 曲线篇含四种路径元素与 `Path2D` / `curve` / 圆角项数说明,文字篇含填充 / 描边 / **位置参数**构造 `new Font('Verdana', 32, 'px', 700)` 与 `Font.clone(Font.defaults(), ...)` 的命名式写法(并说明对象参数构造不存在)/ 锚点居中,并明确「不会自动换行」且以**纯文本**指向第 17 篇(不含 `./builtin-text-and-input.md` 链接,由 10-46 回填);两篇单 H1、有 `## 边界与注意`、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性,`text-demo` 只额外 import `@motajs/render` 的 `Font` 且用位置参数 `new Font('Verdana', 32, 'px', 700)`(不出现对象参数构造、不调用 `Font.defaults`),`curves-demo` 不 import 任何引擎包;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。 + 曲线与路径、文字两篇与两个 demo 完成并已登记。 + + + + Task 5: 六类门禁收口(prettier / ESLint / docs 类型 / 构建 / 静态断言)+ NOTES 记录 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 2..4 的 6 篇与 5 个 demo 已落盘、侧边栏 6 条齐全、构建 green。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/*.md、docs/.vitepress/components/demos/ui/*.tsx、docs/.vitepress/config.ts、docs/tsconfig.json + 按固定顺序跑门禁并记录结论,**顺序不可颠倒**: + +1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md"`,随后 `--check` 同路径(D-45)。不要格式化 `.prettierignore` 内文件或其它既有页面。 +2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 0 error / 0 warning。若出现 `react/jsx-boolean-value` 之类的 JSX 规则告警,按规则改写法(布尔 prop 用简写),**不得**为消告警把渲染属性改成连字符形式。 +3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:只要求路径以 `docs/` 开头且含 `error TS` 的行为 0;`packages/` / `packages-user/` / `src/` 的既有报错只记条数与摘要,标注「既有、非本轮引入、不得修」。 +4. 静态断言:用一条 Node 脚本复核本批 6 篇与 5 个 demo 的硬约束(单 H1、`## 边界与注意`、被禁写法为 0、每篇 `` + 动态 loader、demo 默认导出且无 DOM 属性(4 个 demo 必须零引擎 import;`text-demo` 允许且仅允许 `@motajs/render` 的 `Font`,且必须是位置参数 `new Font('Verdana', 32, 'px', 700)`,不得出现对象参数构造或 `Font.defaults`)、CRLF),并复核侧边栏 6 条链接、`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom` 与 `custom-container`、高级 II 既有条目、高级 III 分组仍在。 +5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、无 dead link。 +6. 向 NOTES 的 `## 门禁记录` 追加本次结论:六类门禁逐条命令与结果、`docs/` 路径类型报错 0、既有引擎报错条数与摘要、构建耗时与 dead link 行数、本批 6 篇与 5 个 demo 的清单(路径 + 是否配 live)。 + +本任务不改任何正文语义,只做格式化、断言与记录。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-43):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-43' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/ii/index.md docs/advanced/index.md'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/new\s+Font\s*\(\s*\{/];const md=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["template-demo","container-demo","shapes-demo","curves-demo","text-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(m==="text-demo"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+m);if(!/new\s+Font\(\s*[\x22\x27]/.test(s))bad.push("DEMO-NO-FONT-CTOR:"+m);if(/new\s+Font\(\s*\{/.test(s))bad.push("DEMO-FONT-OBJ-CTOR:"+m);if(/Font\.defaults/.test(s))bad.push("DEMO-FONT-DEFAULTS:"+m)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m)}if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("DEMO-CRLF:"+m)});const cfg=rd("docs/.vitepress/config.ts");if(cfg.indexOf("container-custom")<0)bad.push("CFG-NO-CONTAINER-CUSTOM");if(cfg.indexOf("custom-container")<0)bad.push("CFG-LOST-CUSTOM-CONTAINER");md.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-43 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T5-OK' + non-zero exit, or output contains "NO-CONFIRM-10-43", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "DEMO-NO-FONT-CTOR", "DEMO-FONT-OBJ-CTOR", "DEMO-FONT-DEFAULTS", "CFG-NO-CONTAINER-CUSTOM", "CFG-LOST-", "NOTES-NO-", or "NOTES-NO-ENGINE-NOTE"; or output lacks "T5-OK" + + prettier `--write` 与 `--check` 均通过;ESLint 为 0 error / 0 warning 且渲染属性仍为 camelCase;`vue-tsc -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / ClientOnly + 动态 loader / CRLF;5 个 demo 默认导出、无 DOM 属性、CRLF,4 个零引擎 import,`text-demo` 仅允许 `@motajs/render` 的 `Font` 且为位置参数构造、无 `Font.defaults`;侧边栏 6 条 + `custom` 数组双名放行 + 既有条目 + 高级 III 未丢);全量构建 green、无 dead link;NOTES 的 `## 门禁记录` 下有 `### 10-43 门禁` 小节并含 `docs/ 路径类型报错 0` 与「既有引擎报错」条数摘要。 + 六类门禁全绿并已记录,本批 6 篇 5 demo 达到可交付状态。 + + + + Task 6: 用户目视 5 个 live 并抽查正文 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 5 通过(六类门禁全绿、构建产物已生成、NOTES 已记录门禁结论)。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录与命名表)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(5 个 demo) + 请用户用 `cmd /c "pnpm docs:dev"`(或对构建产物用 `cmd /c "pnpm docs:preview"`)打开这 6 篇页面,逐条确认:①侧边栏出现子分组与「起步 / 元素与布局」两个分组,6 条链接都能点开且不 404;②第 1 篇的 live 显示深色背景矩形与标题文字;③第 3 篇的 live 能看到嵌套容器边界与坐标文字;④第 4 篇的 live 能看到四个图形,点击其中某个图形颜色变化;⑤第 5 篇的 live 能看到两条曲线、一条折线和圆角矩形;⑥第 6 篇的 live 能看到不同字号 / 颜色的文字与带描边的标题;⑦抽查第 1、2 篇正文:模板能直接照抄(含 `client.sceneController.open`)、TS 对照表与代码一致、没有渲染器类名与 core 命名空间。用户确认通过时,在 NOTES 的 `## 人工验证记录` 追加**独占一行**的 `用户人工验证(10-43):通过`,下一行以 `用户原文:` 开头写原话;若发现问题,逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复后重跑 Task 5 门禁再请用户复验(循环不限轮次)。**只有用户明确通过才可进入 10-44**;沉默或只回复「可以」不算通过。 + 6 篇正文与 5 个 live demo,站点构建产物已生成并可在本地预览。 + 按上面①–⑦逐条在浏览器与正文中检查;重点看侧边栏层级、每个 live 是否真实绘制、第 4 篇点击是否变色、模板是否可直接照抄。 + 若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。 + 用户明确回复 live 与正文均通过,且 NOTES 的 `## 人工验证记录` 下有 `用户人工验证(10-43):通过` 与用户原文;否则问题清单已记录并进入修复循环。 + + 用户已明确确认 6 篇页面可读、5 个 live 正常、侧边栏层级可用,并已把结论记入 NOTES。 + + 用户人工验证结论已记录(通过,或问题清单进入修复循环)。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 文档站构建期(SSR 预渲染)→ live demo | 预渲染在 Node 中执行;demo 必须由 `RenderDemo` 在浏览器端动态 import,页面不得静态 import demo | +| demo → 渲染树 | demo 只声明本地静态结构与 props,不接收外部输入、不解析字符串、不发请求 | +| 侧边栏 → 页面文件 | 每条 link 必须指向已存在文件,否则构建 dead link 失败 | +| 文档正文 → 读者 | 读者照抄示例;写错属性名不会报错但也不生效,属于正确性风险而非安全风险 | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-129 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页在同一任务内完成;构建门禁要求 0 dead link,静态断言复核 6 条链接与既有条目未丢 | +| T-10-130 | Denial of Service(构建不可用) | `.tsx` demo 进入 SSR | high | mitigate | demo 只由 `RenderDemo` 的 loader 动态 import;页面只静态 import 包装组件;`` 包裹;每次构建门禁必须 `build complete` | +| T-10-131 | Information Disclosure | 正文泄露引擎内部实现 | low | mitigate | 静态断言禁渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;正文只写应用层用法 | +| T-10-132 | Repudiation | 命名与验证结论无据可查 | medium | mitigate | 命名总表、哈希基线、门禁与人工验证全部落在追加式 NOTES;每个 auto 任务复检 `用户确认(10-43):可以执行` | +| T-10-133 | Tampering | 参考文件在写作期间被改动 | high | mitigate | Task 1 记录 `git hash-object` 基线;写作前逐条核对,任一不一致或工作树被改即停下问用户 | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 本计划不安装任何新包(`vue` / `@vitejs/plugin-vue-jsx` / `vitepress` / `prettier` 均已在依赖中);若发现缺失,停止并报告,不得临时安装 | + + + +- 确认门禁:NOTES 含 `用户确认(10-43):可以执行` + 下一行 `用户原文:`;Task 6 后含 `用户人工验证(10-43):通过` + `用户原文:`,且无 `状态:待处理`。 +- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性;跨批次前瞻引用(第 8 / 10 / 17 篇)只写纯文本,不含指向尚未创建页面的 markdown 链接。 +- 示例门禁:Props 基类与三个 props 名齐全;属性 camelCase;live 全部 `` + 动态 loader;demo 默认导出、无 DOM 属性;4 个 demo 零引擎 import,`text-demo` 是唯一例外(仅 `@motajs/render` 的 `Font`,位置参数 `new Font('Verdana', 32, 'px', 700)`,不出现对象参数构造、不碰 `Font.defaults`)。 +- 容器标签门禁:`docs/.vitepress/config.ts` 的 `custom` 数组同时含 `container-custom`(文档写法)与 `custom-container`(运行时当前注册名),其余既有项与 `isCustomElement` 未变。 +- 类型门禁:`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;引擎既有报错只记录。 +- 构建门禁:`pnpm docs:build` green、`build complete`、0 dead link。 +- 格式门禁:prettier `--check` 通过;ESLint 0 error / 0 warning。 +- 越界门禁:`git status --porcelain packages/ packages-user/ src/` 不含本计划引入的改动;未改 `10-01`..`10-42` 与 POC 文件;未 commit;ROADMAP / STATE 本计划不改。 + + + +- 高级 II 下出现新子分组,第一批 6 篇正文可按顺序阅读并直接照抄模板;tsx 示例与 live 一致。 +- 基础设施一次建好:`.tsx` 进入 docs 类型检查、侧边栏两层嵌套可用、demo 目录约定确立、参考清单哈希基线在案、docs 的 `custom` 数组放行 `container-custom`。 +- 两处导览不再自相矛盾,并给出本子分组的入口与性能边界说明。 +- 六类门禁全绿并有记录;用户目视 live 通过;未改源码、未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-43-SUMMARY.md` when done + + +## 编号变更(2026-11-01) + +本文件写作期的计划编号已因后续重排而改变,原文保持不变,读到时按下列映射理解: + +- 本文件提到的「10-49 用户主导修订 + 收尾」→ 现为 `10-54-PLAN.md`(用户审阅 + 最终门禁 + 落位评估 + 收尾)。 +- 本文件提到的旧「10-49 七个计划」中的读者审阅 / 用户修订两段 → 读者循环现为 `10-53-PLAN.md`(Round 2/3,Round 1 记录保留在 `10-49-READER-REVIEW.md`);用户审阅现为 `10-54-PLAN.md`。 +- 新增的 `10-49`..`10-52` 是 Part 0–1 / 2–3 / 4 / 5 的深度扩写(D-93),`10-48` 仍是 pre-review 修复。 +- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。 diff --git a/.planning/phases/10-docs-restructure/10-44-PLAN.md b/.planning/phases/10-docs-restructure/10-44-PLAN.md new file mode 100644 index 0000000..63f9793 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-44-PLAN.md @@ -0,0 +1,327 @@ +--- +phase: 10-docs-restructure +plan: 44 +type: execute +wave: 2 +depends_on: + - 10-43 +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/basic-shapes.md + - docs/advanced/ii/ui/container-and-coordinates.md + - docs/advanced/ii/ui/image-and-texture.md + - docs/advanced/ii/ui/layer-transform-performance.md + - docs/advanced/ii/ui/reactivity.md + - docs/advanced/ii/ui/events.md + - docs/advanced/ii/ui/hotkey-in-ui.md + - docs/advanced/ii/ui/conditional-and-list-rendering.md + - docs/.vitepress/components/demos/ui/texture-demo.tsx + - docs/.vitepress/components/demos/ui/layer-demo.tsx + - docs/.vitepress/components/demos/ui/events-demo.tsx + - docs/.vitepress/components/demos/ui/reactivity-demo.tsx + - docs/.vitepress/components/demos/ui/conditional-demo.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 76000 + raw_tokens: 47000 + tasks: 6 + confidence: low +must_haves: + truths: + - "Part 1 收尾两篇(图片与最小纹理、层级/变换/性能)与 Part 2 四篇(响应式、事件与交互、按键与快捷键、条件与循环渲染)全部落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF" + - "性能篇明确「优先 `hidden`」:`hidden` 不显示、不交互、保留元素与状态、跳过绘制与命中;三元只在必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用时使用;`scale` 写成 `[x, y]` 数组、`rotate` 用弧度" + - "响应式篇从零讲 `ref` / `reactive` / `computed` / `watch`,讲清 TSX 里为什么写 `.value`、`reactive` 不能整体替换与解构会丢响应式、props 不要解构;不假设读者会 Vue" + - "事件篇覆盖 `onClick` / `onDown` / `onUp` / `onMove` / `onEnter` / `onLeave` / `onWheel` 与捕获变体,讲 `IActionEvent` 的坐标字段、`stopPropagation`、`noevent`、`cursor`、`actionStroke`,并说明 `enter` / `leave` 不走普通冒泡" + - "按键篇只写 UI 作者会用到的部分:`props.state.hotkey.system`、`useKey(...)!`、`implement`、注册新指令与分组、`HotkeyEmitMode`、优先级与阻断、UI 相关默认按键表;不展开按键系统的存档、监听与内部匹配" + - "条件与循环篇按 `dev.md:122` 写 `key` 规则:`.map()` 用于循环,`key` 只在列表会重排 / 插入 / 删除且需要保留身份时加,不为规避重挂载问题加 `key`" + - "5 个 live demo(texture / layer / events / reactivity / conditional)默认导出、无 DOM 属性;其中 layer / events / reactivity / conditional 只 import vue 与元素标签,唯一例外是 `texture-demo.tsx` 可以 `import { Texture } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`;页面用 `<ClientOnly>` + `() => import('...')`;按键篇不配伪装成引擎按键的 live" + - "侧边栏新增「交互与数据」分组 4 条、「元素与布局」补 2 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link" + - "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning" + - "未改 `packages/` / `packages-user/` / `src/`、未改 10-43 已验收的 6 篇正文与 5 个 demo 的语义(第 3 / 4 篇各只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-43` 计划、未改既有 JSDoc/注释;不 commit" + artifacts: + - "docs/advanced/ii/ui/image-and-texture.md、layer-transform-performance.md、reactivity.md、events.md、hotkey-in-ui.md、conditional-and-list-rendering.md" + - "docs/.vitepress/components/demos/ui/texture-demo.tsx、layer-demo.tsx、events-demo.tsx、reactivity-demo.tsx、conditional-demo.tsx" + - "docs/.vitepress/config.ts(高级 II 子分组内新增「交互与数据」、补「元素与布局」两条)" + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-44 命名确认、门禁与人工验证记录)" + key_links: + - "第 8 篇的 `hidden` 口径与第 12 篇的条件渲染口径必须一致:两处都写「不显示、不交互、保留状态、跳过绘制与命中」,否则读者会在两篇之间得到相反结论" + - "第 9 篇的响应式是第 10、12、13 篇的前置:事件回调用 `ref` 改状态、条件用 `hidden` 读状态、组件用 props 收状态;这三处的示例都要能回到第 9 篇的同一套写法。第 9 篇对第 13 篇只写纯文本前瞻引用,链接由 10-45 创建第 13 篇时回填;本批创建第 8、10 篇后要回填 10-43 第 3、4 篇的纯文本前瞻引用(只加链接,不改文字语义)" + - "第 11 篇的 `useKey` 作用域跟随组件挂载 / 卸载;示例只写 `useKey(props.state.hotkey.system)!` 与 `implement`,不引导读者自己监听键盘" + - "第 7 篇的最小纹理与第 17 篇的 `image` 相关组件共用 `ITexture` 概念;本篇只讲最小可运行纹理,不展开素材管线" +--- + + +本计划 6 个任务、15 个 `files_modified`,超出默认上限,保持单计划: + +- 6 篇正文分三个写作任务(2 + 2 + 2),每个任务都能独立验证「两篇 + 对应 demo + 侧边栏」;门禁与人工验证各自独立成任务,无法再合并。 +- 15 个文件里 6 篇正文、5 个 demo、2 篇**只回填链接**的 10-43 已验收页面(第 3 篇 `container-and-coordinates.md`、第 4 篇 `basic-shapes.md`——10-43 约定目标页不存在时只写纯文本,由本批创建第 8 / 10 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件;它们共享同一份参考清单哈希、同一套写作规则与同一次构建。 +- 承接 10-43 的拆分:Part 1 后两篇随 Part 2 一起做,是因为这两篇(纹理与性能)都需要「响应式 / 事件」已建立的概念做对照;放在同一计划可避免跨计划重复解释。 + +不删内容:6 篇正文、5 个 live、按键默认表、性能口径、`key` 规则、六类门禁、用户目视全部保留。 + + + +落地子分组的第二批 6 篇:Part 1 收尾的「图片与最小纹理」「层级、变换与性能」,以及 Part 2 的「响应式」「事件与交互」「按键与快捷键」「条件与循环渲染」。这一批把读者从「会画静态图形」推到「会接交互、会读数据、会按条件与列表组织画面」。 + +Purpose: 元素与布局讲完之后,读者必须能用状态驱动画面、用事件接住点击、用按键收口操作,并且知道什么时候用 `hidden`、什么时候必须让元素真正消失。这一批也是后面组件化与内置组件的前置。 +Output: 6 篇正文、5 个 `.tsx` live demo、侧边栏两处登记、NOTES 追加记录。**不改源码、不改 10-43 已验收内容、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-43-PLAN.md +@docs/.vitepress/config.ts +@docs/advanced/ii/ui/text.md +@docs/.vitepress/components/demos/ui/template-demo.tsx +@docs/.vitepress/components/demos/ui/shapes-demo.tsx + +**流程约定:** +- 本计划是 Phase 10 的增量派发:只新增/修改本计划 `files_modified` 内文件;不改 `10-01`..`10-43` 计划文件;不重规划其它批次。 +- **Task 0 是硬关卡**:向用户汇报本计划 6 篇写什么、demo 名、live 取舍、以及第 7 篇的纹理造法选项,等用户明确回复「可以执行」。 +- 6 篇文件名与侧边栏名已在 10-43 的命名总表里确认;本计划 Task 0 只需复述确认值并等「可以执行」,**若用户在本轮改动命名**,先更新 NOTES 命名总表再落盘。 +- 每次改文件前必须声明是「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理(AGENTS.md)。 +- 不得调用 `opencode` 命令;不得修改任何既有 JSDoc / 注释(新增文件除外);不做 git commit / push。 + +**本批写作硬规则(与 10-43 完全一致,不再重复展开):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。 + +**参考文件与哈希:** 以 `10-CUSTOM-UI-RESEARCH.md` 的 `## Reference Manifest` 与 NOTES 的「参考清单哈希基线」为准。写作前对本计划涉及的文件(`core/misc.ts`、`core/item.ts`、`core/canvas2d.ts`、`core/transform.ts`、`assets/texture.ts`、`core/event.ts`、`core/container.ts`、`system/src/hotkey/*`、`client-base/src/use/hotkey.ts`、`client-base/src/hotkey/hotkey.ts`)重跑 `git hash-object -- ` 比对;任一不一致或 `git status --porcelain` 非空即停下问用户。 + + + + + + Task 0: 汇报本计划 6 篇与 live 取舍得,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、参考清单哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 7–12 篇、Performance、Hotkey、Common Pitfalls)、docs/advanced/ii/ui/text.md(Page 6 已落地体例)、docs/.vitepress/config.ts(10-43 建好的子分组结构) + 向用户做四段汇报并停下等待: + +**要做什么**——落地 6 篇:图片与最小纹理、层级/变换与性能、响应式、事件与交互、按键与快捷键、条件与循环渲染;配 5 个 `.tsx` live,按键篇不配 live。 + +**为什么**——读者在会画静态图形之后,必须先学会「状态驱动画面」,才能接交互、接按键、接列表;性能篇把 `hidden` 的口径一次讲定,后面组件化与完整示例都直接引用它。Part 1 的两篇在此收尾,是因为它们与响应式 / 事件互为对照。 + +**大致怎么做**——Task 1 写纹理篇与性能篇 + `texture-demo` / `layer-demo`;Task 2 写响应式篇与事件篇 + `reactivity-demo` / `events-demo`;Task 3 写按键篇与条件循环篇 + `conditional-demo`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 5 个 live 并抽查正文。 + +**影响范围**——新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `demos/ui/` 下 5 个 `.tsx`;加法式追加侧边栏 6 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、10-43 已验收的 6 篇与 5 个 demo、POC 页、ROADMAP / STATE。 + +**必须请用户确认的两点:** + +1. **第 7 篇的最小纹理造法**(研究文件 Q2,尚未定):推荐用 `document.createElement('canvas')` 画一个色块再包成纹理,因为最直观、不依赖素材;备选是用 `ImageBitmap` 或一张现成图片占位。请用户选一个。 +2. **live 取舍**:纹理 / 层级变换 / 事件 / 响应式 / 条件循环五篇配 live;按键篇**不配** live(文档站没有游戏的按键系统,配一个假的会误导读者),只放代码块并在正文标明这一点。若用户要求按键篇也要 live,必须先说明「只能演示浏览器键盘事件,不是引擎按键」。 + +同时复述 6 篇文件名与侧边栏显示名(沿用 10-43 的命名总表)与 5 个 demo 名,确认无改动。**参考文件:`packages/render/src/core/misc.ts`、`core/item.ts`、`core/canvas2d.ts`、`core/transform.ts`、`core/event.ts`、`core/container.ts`、`assets/texture.ts`、`packages/system/src/hotkey/*`、`packages-user/client-base/src/use/hotkey.ts`、`client-base/src/hotkey/hotkey.ts`;策略:写作前逐条 `git hash-object -- ` 与 Manifest / NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。 + 尚无产物;本任务只汇报本计划范围、live 取舍与第 7 篇纹理方案。 + 确认:①是否同意本计划 6 篇与 5 个 live 的范围;②第 7 篇最小纹理用 canvas 自造 / `ImageBitmap` / 现成图片占位(三选一);③是否接受按键篇不配 live;④6 篇文件名与侧边栏名是否沿用 10-43 确认值。 + 回复「可以执行」以继续(请同时给出纹理方案选择);其它回复视为未批准。 + 用户已回复「可以执行」,且纹理造法方案、按键篇 live 取舍、6 篇命名三项均已确定;NOTES 命名总表如被改动已同步。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,并已选定纹理方案与按键篇 live 取舍;命名沿用或在 NOTES 中同步。 + + 用户回复「可以执行」且三项待定项已定。 + + + + Task 1: 图片与最小纹理 / 层级、变换与性能 两篇 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/.vitepress/components/demos/ui/texture-demo.tsx, docs/.vitepress/components/demos/ui/layer-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/container-and-coordinates.md + 本计划的 Task 0 已回复「可以执行」并选定纹理方案;10-43 的 6 篇与侧边栏骨架存在且构建 green。本任务负责把 `用户确认(10-44):可以执行` 与用户原文追加进 NOTES。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 7、8 篇;Render Elements 的属性默认值 / 缓存默认值;Performance 全节;`docs/guide/ui/perf.md` 的可用结论)、packages/render/src/core/misc.ts:150-192(image 元素语义)、packages/render/src/assets/texture.ts、packages/render-vue/src/props.ts:24-81(`hd` / `anti` / `noanti` / `cache` / `nocache` / `scale` / `rotate`)、dev.md:116-123(换行与 `key` 规则)、docs/.vitepress/config.ts + 先向 NOTES 末尾追加本节(`## 10-44 命名确认`),写独占一行 `用户确认(10-44):可以执行`、下一行 `用户原文:`、纹理方案最终选择、按键篇 live 取舍、6 篇与 5 个 demo 的最终名;并重跑本任务涉及参考文件的 `git hash-object` 比对,把结果追加到哈希表。然后写两篇正文与两个 demo。 + +**(1)`image-and-texture.md`(第 7 篇)**:先回答「图片元素需要什么」——一个纹理对象 + 元素的宽高(按元素框拉伸)。讲 `image` 元素:`image` 属性接收纹理,`loc` 决定绘制区域。讲最小纹理怎么造:按 Task 0 选定方案给完整片段——若选 canvas,就在组件外或 `onMounted` 里画一个色块 / 棋盘,再包成纹理;若选 `ImageBitmap` 或现成图片,就给对应写法与加载时机的说明。讲像素图设置:`noanti` 关抗锯齿、`hd={false}` 关高清缓存,并说明为什么要一起关(放大时边缘不被插值模糊)。`icon` / `winskin` / `map-render` 只用一两句话说明是应用层素材标签、本篇不展开,**不写内部实现**。`## 边界与注意`:纹理创建有成本,不要在每次渲染里重复造;图片按元素宽高拉伸,比例不对会变形;纹理对象不要在组件卸载后继续被引用(一句话点到,不展开生命周期细节)。 + +**(2)`layer-transform-performance.md`(第 8 篇)**:按「遮挡 → 变换 → 显示开关 → 缓存」的顺序讲: +- `zIndex` 决定遮挡,同级越大越靠上;给出两个重叠矩形换序的示例。 +- `scale` 必须是 `[x, y]` 数组;`rotate` 用弧度;`alpha` 改不透明度;三者都在元素自己的坐标系里生效。 +- **`hidden` 优先**:明确写「`hidden` 不显示、不交互,但保留元素与状态,并跳过绘制与命中」,给出用按钮切换 `hidden` 的示例;再说明三元表达式会创建 / 销毁并重置状态,只在「必须真正不存在」「需要重置状态或生命周期」「子树很重且长期不用」,以及「必须彻底摘掉事件监听、或不能接受隐藏元素继续占内存」时使用。这一段的口径必须与第 12 篇一致。 +- 缓存:讲 `cache` / `nocache` 的默认取向(容器类默认缓存、图形 / 文字 / 图片默认不缓存),以及什么情况值得打开缓存;`hd` / `anti` / `noanti` 一句带过并指向第 7 篇。 +- `noevent`:元素可见但不接收交互,且会让 `cursor` 失效;给出一个遮罩示例。 +- `filter` / `composite` 各一句话,说明存在即可,不展开取值表。 +- 末尾给一张「什么时候用 `hidden`、什么时候用三元」的判定表。 +`## 边界与注意`:`scale` 写数字无效;`rotate` 单位是弧度;改锚点会连同变换一起改变视觉位置;缓存打开后内容变化需要让元素知道自己脏了,简单场景优先不缓存。 + +**(3)两个 demo**:`texture-demo.tsx`(`TextureDemo`)显示动态生成的最小纹理 + 一个 `noanti hd={false}` 对照;`layer-demo.tsx`(`LayerDemo`)用按钮切换 `hidden` / `alpha` / `scale` 并展示 `zIndex` 遮挡。都默认导出、无 DOM 属性。`layer-demo` **只** import vue 与元素标签;`texture-demo` 额外允许 `import { Texture } from '@motajs/render'`(元素层类,不是渲染器),除此之外不得 import 任何 `@motajs/*` / `@user/*`。`texture-demo` 里造纹理的代码只跑一次(`onMounted` 或模块内常量),并在注释里写明原因。 + +**(5)回填第 3 篇的跨页链接**:`docs/advanced/ii/ui/container-and-coordinates.md` 里讲 `zIndex` 的那句现在写的是纯文本「第 8 篇『层级、变换与性能』」(10-43 的约定:目标页不存在时只写纯文本)。本任务已创建第 8 篇,把该纯文本改成 `[第 8 篇「层级、变换与性能」](./layer-transform-performance.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。** + +**(4)侧边栏**:在「元素与布局」分组末尾追加 `/advanced/ii/ui/image-and-texture` 与 `/advanced/ii/ui/layer-transform-performance` 两条。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/image-and-texture.md":["image","noanti","hd","icon","winskin","map-render"],"docs/advanced/ii/ui/layer-transform-performance.md":["zIndex","scale","rotate","alpha","hidden","cache","nocache","noevent","三元","filter","composite"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const L=fs.existsSync("docs/advanced/ii/ui/layer-transform-performance.md")?rd("docs/advanced/ii/ui/layer-transform-performance.md"):"";if(L.indexOf("不显示、不交互")<0){bad.push("HIDDEN-SEMANTICS")}if(!/三元/.test(L)){bad.push("NO-TERNARY")}if(!/重置/.test(L)){bad.push("NO-RESET")}["texture-demo.tsx","layer-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(f==="texture-demo.tsx"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+f);if(s.indexOf("Texture")<0)bad.push("DEMO-NO-TEXTURE:"+f)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f)}});const p3=rd("docs/advanced/ii/ui/container-and-coordinates.md");if(p3.indexOf("](./layer-transform-performance.md)")<0)bad.push("BACKFILL-P3");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/image-and-texture","/advanced/ii/ui/layer-transform-performance","/advanced/ii/ui/text","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK' + non-zero exit, or output contains "NO-CONFIRM-10-44", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "HIDDEN-SEMANTICS", "NO-TERNARY", "NO-RESET", "NO-DEMO", "DEMO-", "DEMO-NO-TEXTURE", "BACKFILL-P3", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK" + + NOTES 追加了 10-44 命名确认(含独占一行确认标记 + 用户原文 + 纹理方案 + 按键 live 取舍)与哈希比对结果;纹理篇覆盖 image / noanti / hd / 三个占位标签;性能篇覆盖 zIndex / scale 数组 / rotate 弧度 / alpha / hidden 语义 / cache / noevent / filter / composite,并用判定表区分 `hidden` 与三元;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;`layer-demo` 只 import vue 与元素标签,`texture-demo` 只额外 import `@motajs/render` 的 `Texture`,两者都默认导出且无 DOM 属性;第 3 篇(`container-and-coordinates.md`)里对第 8 篇的纯文本引用已回填为 `./layer-transform-performance.md` 链接且该页其它内容未变;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。 + 纹理篇与性能篇完成,`hidden` 口径与后续篇章统一。 + + + + Task 2: 响应式 / 事件与交互 两篇 + 两个 demo + 侧边栏「交互与数据」 + docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/.vitepress/components/demos/ui/reactivity-demo.tsx, docs/.vitepress/components/demos/ui/events-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/basic-shapes.md + NOTES 含 `用户确认(10-44):可以执行`;Task 1 两篇已落盘且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 9、10 篇;Vue / TSX Integration 全节;事件类型与字段)、packages/render/src/core/event.ts:52-134(事件名与字段)、packages/render/src/core/item.ts:757、1106-1109(noevent 与 cursor)、packages/render/src/core/container.ts:93-116(捕获与冒泡顺序)、Vue 官方文档 reactivity-fundamentals(2026-10-30 读取) + 写两篇正文与两个 demo,并建立「交互与数据」分组。 + +**(1)`reactivity.md`(第 9 篇)**:从零讲,不假设读者会 Vue。顺序: +- 问题:画面要跟着数据变,手写「改数据再重画」迟早漏。 +- `ref`:`const count = ref(0)`;在 TSX 里读要写 `count.value`,模板渲染函数里也一样——这一点必须讲透,并解释为什么(`ref` 是一个带 `value` 的盒子,Vue 靠读它来追踪依赖)。 +- `reactive`:适合一整块对象;讲两条限制——不能整体替换、解构会丢响应式,并给出替代写法。 +- `computed`:派生值,示例 `const doubled = computed(() => count.value * 2)`,说明它惰性求值且会缓存。 +- `watch`:副作用,示例监听 `count` 打印一行;说明什么时候用 `watch`、什么时候其实用 `computed` 更合适。 +- 一小节「什么时候用 `shallowRef` / `markRaw`」:只讲判断依据(大对象、不需要深层响应、外部实例),不展开内部机制。 +- 最后一小节「props 不要解构」,**只写纯文本「第 13 篇『组件与 props』」**——第 13 篇在 10-45 创建,此处不写 markdown 链接,由 10-45 回填。 +`## 边界与注意`:`reactive` 不能整体替换;解构会丢响应式;`ref` 忘记 `.value` 是最常见错误;不要在渲染函数里做副作用。 + +**(2)`events.md`(第 10 篇)**:先讲命中测试:事件先找到最上层被点到的元素,再沿容器向外传递。然后: +- 事件名用 `on` + 事件名(`onClick` / `onDown` / `onUp` / `onMove` / `onEnter` / `onLeave` / `onWheel`),捕获阶段在名字后加 `Capture`;**不要**写成模板指令语法(这一点用文字说明,不给反例代码)。 +- 事件对象字段:相对元素的坐标、相对画布的坐标、`identifier`、`type`、`buttons` 与修饰键;给一个把坐标显示到文字元素上的示例。 +- 捕获与冒泡:子元素先捕获、父元素后冒泡;`stopPropagation()` 在捕获阶段阻止继续捕获、在冒泡阶段阻止继续冒泡,但不阻止同一元素上的其它监听器。 +- `enter` / `leave`:由根节点的悬停集合统一触发,不走普通冒泡,给一句提醒。 +- `noevent`:元素可见但不接收交互,事件下穿,`cursor` 也不再生效;给一个遮罩示例。 +- `cursor`:悬停时的鼠标样式,写在元素上。 +- `actionStroke`:只把描边算作命中区域(链接回第 4 篇的说明)。 +示例用「点击矩形换色 + 悬停改光标 + 滚轮改文字」一组,全部用 `ref` 驱动。`## 边界与注意`:属性名写错不报错也不触发;`hidden` 的元素既不绘制也不参与命中;`noevent` 与 `hidden` 是两件事,不要混用。 + +**(3)两个 demo**:`reactivity-demo.tsx`(`ReactivityDemo`)做计数器 + 计算属性 + 监听结果文字;`events-demo.tsx`(`EventsDemo`)做点击换色 + 悬停改光标 + 滚轮改文字,并把事件坐标写到文字元素上。都默认导出、只 import vue 与元素标签、无 DOM 属性。 + +**(4)侧边栏**:在子分组 `items` 里追加 `{ text: '交互与数据', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/reactivity` 与 `/advanced/ii/ui/events` 两条。只做加法。 + +**(5)回填第 4 篇的跨页链接**:`docs/advanced/ii/ui/basic-shapes.md` 的 live 说明里现在写的是纯文本「事件在第 10 篇展开」。本任务已创建第 10 篇,把该纯文本改成 `[第 10 篇「事件与交互」](./events.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。** + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/reactivity.md":["ref(","reactive(","computed(","watch(","value","shallowRef","markRaw","解构"],"docs/advanced/ii/ui/events.md":["onClick","onDown","onUp","onMove","onEnter","onLeave","onWheel","Capture","stopPropagation","noevent","cursor","actionStroke"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["reactivity-demo.tsx","events-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const p4=rd("docs/advanced/ii/ui/basic-shapes.md");if(p4.indexOf("](./events.md)")<0)bad.push("BACKFILL-P4");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/reactivity","/advanced/ii/ui/events","/advanced/ii/ui/image-and-texture","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(cfg.indexOf("交互与数据")<0)bad.push("CFG-NO-PART2");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "NO-CONFIRM-10-44", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P4", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK" + + 响应式篇含 `ref` / `reactive` / `computed` / `watch` / `.value` 解释 / `shallowRef` / `markRaw` / 解构警告,且从零讲、不假设读者会 Vue;事件篇含 7 个冒泡事件名 + 捕获变体 + `stopPropagation` / `noevent` / `cursor` / `actionStroke`,并说明 `enter` / `leave` 不普通冒泡;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;第 9 篇对第 13 篇只含纯文本前瞻引用(无 markdown 链接);两个 demo 默认导出、无 DOM 属性、不 import 任何引擎包;第 4 篇(`basic-shapes.md`)里对第 10 篇的纯文本引用已回填为 `./events.md` 链接且该页其它内容未变;侧边栏新增「交互与数据」两条且既有条目未丢;构建 green、无 dead link。 + 响应式篇与事件篇完成,交互与数据分组已建立。 + + + + Task 3: 按键与快捷键 / 条件与循环渲染 两篇 + 条件循环 demo + 侧边栏 + docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/.vitepress/components/demos/ui/conditional-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-44):可以执行`;Task 2 已落盘并建好「交互与数据」分组;Task 0 已确认按键篇不配 live。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 11、12 篇;Hotkey 全节)、packages-user/client-base/src/use/hotkey.ts:6-71、packages/system/src/hotkey/types.ts:9-77、src/client/misc/hotkey.ts(默认按键与分组,只取 UI 相关行)、dev.md:116-123、docs/.vitepress/components/demos/ui/layer-demo.tsx(`hidden` 示例体例) + 写两篇正文与一个 demo。 + +**(1)`hotkey-in-ui.md`(第 11 篇)**:只写 UI 作者会用到的部分。顺序: +- 问题:UI 里要让 Esc 关闭、Enter 确认,不要自己监听键盘。 +- 按键系统的最小模型:指令(有名字、有默认按键)+ 作用域(跟着组件挂载 / 卸载)+ 实现(把指令接到当前作用域的回调)。 +- `useKey`:在 `setup` 里 `const key = useKey(props.state.hotkey.system)!;`,说明组件内必定有实例所以用非空断言;讲作用域随卸载自动离开。 +- `key.implement('@common/exit', () => props.controller.close(props.instance))`,并给一个再绑一条的示例。 +- 注册新指令:`system.addCommand(...)`;分组:`hotkey.setGroup(...)`;说明为什么分组(设置界面按组显示)。 +- 触发方式:`HotkeyEmitMode` 的三种(抬起、只触发一次、持续触发)各一句话;优先级与阻断各一句话,并说明「同优先级不互相阻断」。 +- UI 相关默认按键表(`@common/confirm` / `@common/exit` / `@ui/menu` / `@ui/toolbox` / `@ui/command` / `@ui/save` / `@ui/load` / `@ui/book` / `@ui/input-confirm` 等),标明「默认值,玩家可在设置里改」。 +- 明确一句:本篇不涉及按键系统的存档、监听与内部匹配。 +**不配 live**,并在正文用一句话说明「文档站没有游戏的按键系统,因此本篇不提供可运行示例」。`## 边界与注意`:`useKey` 必须在 `setup` 中调用;作用域随组件卸载离开,不要在已卸载组件里继续用;同一次挂载里重复 `implement` 同一指令会覆盖;别把按键回调写成异步长任务。 + +**(2)`conditional-and-list-rendering.md`(第 12 篇)**:先讲 TSX 里没有模板指令,条件与循环都是普通表达式。 +- 条件:**优先 `hidden`**——写清「不显示、不交互、保留元素与状态、跳过绘制与命中」,给一个开关面板的示例;再讲三元表达式会真正移除节点(组件卸载、状态重置),列出三类该用三元的场景(必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用),并补一句「需要彻底摘掉事件监听、或不能接受隐藏元素继续占内存时,也只能用三元」。 +- 循环:用 `.map()` 生成一组元素;给一个固定顺序、无状态列表的例子并**不加** `key`,说明为什么不加。 +- `key`:只在列表会重排 / 插入 / 删除且需要保留元素身份时加(引用 `dev.md:122` 的规则,用文字复述),给一个带 `key` 的可增删列表例子;明确不要为规避重挂载问题加 `key`。 +- 一小节对比表:`hidden` vs 三元 vs `.map()` + `key`。 +`## 边界与注意`:`hidden` 的元素仍在树里,数量和层级照旧;三元反复切换会反复重建,成本在组件初始化;`map` 返回的每一项都要有稳定结构;`key` 不是性能开关。 + +**(3)`conditional-demo.tsx`**:一个开关切换面板 `hidden`,一个可增删列表用 `.map()`(初始固定顺序的简单列表不加 `key`,可增删的那组加 `key`),并用文字显示「切换后状态是否保留」。默认导出、只 import vue 与元素标签、无 DOM 属性。 + +**(4)侧边栏**:在「交互与数据」分组追加 `/advanced/ii/ui/hotkey-in-ui` 与 `/advanced/ii/ui/conditional-and-list-rendering` 两条。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const hk="docs/advanced/ii/ui/hotkey-in-ui.md";const cd="docs/advanced/ii/ui/conditional-and-list-rendering.md";if(!fs.existsSync(hk))bad.push("MISSING:"+hk);else{const s=rd(hk);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+hk);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+hk);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+hk+":"+r)});["useKey(","implement(","addCommand","setGroup","HotkeyEmitMode","@common/exit","@common/confirm","priority"].forEach(function(k){if(s.indexOf(k)<0)bad.push("HK:"+k)});if(/saveState|loadState|preventDefault/.test(s))bad.push("HK-INTERNAL");if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+hk);if(/\x3cClientOnly\x3e/.test(s))bad.push("HK-UNEXPECTED-LIVE")}if(!fs.existsSync(cd))bad.push("MISSING:"+cd);else{const s=rd(cd);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+cd);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+cd);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+cd+":"+r)});["hidden",".map(","key","三元","重置"].forEach(function(k){if(s.indexOf(k)<0)bad.push("CD:"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+cd);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+cd);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+cd)}const d="docs/.vitepress/components/demos/ui/conditional-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT");if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE");if(/style=|class=/.test(s))bad.push("DEMO-DOM");if(!/\.map\(/.test(s))bad.push("DEMO-NO-MAP");if(s.indexOf("hidden")<0)bad.push("DEMO-NO-HIDDEN")}const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/hotkey-in-ui","/advanced/ii/ui/conditional-and-list-rendering","/advanced/ii/ui/reactivity","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK' + non-zero exit, or output contains "NO-CONFIRM-10-44", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "HK:", "HK-INTERNAL", "HK-UNEXPECTED-LIVE", "CD:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK" + + 按键篇含 `useKey(...)!` / `implement` / `addCommand` / `setGroup` / `HotkeyEmitMode` / 优先级 / UI 相关默认按键表,且不出现按键系统的存档与监听接口、不配 live;条件循环篇含 `hidden` 优先、三元场景、`.map()`、`key` 规则与对比表,且与第 8 篇口径一致;两篇单 H1、有边界节、CRLF、无被禁写法;条件循环篇接 live、按键篇不接;demo 含 `.map(` 与 `hidden`;侧边栏新增两条且既有条目未丢;构建 green、无 dead link。 + 按键篇与条件循环篇完成,Part 2 四篇齐备。 + + + + Task 4: 六类门禁收口 + NOTES 记录 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1..3 的 6 篇与 5 个 demo 已落盘、侧边栏 6 条齐全、构建 green。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts + 按固定顺序跑门禁并记录,顺序不可颠倒: + +1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。 +2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning;布尔 JSX 属性用简写,不得为消告警改渲染属性名。 +3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:只要求 `docs/` 路径 0 报错;引擎既有报错记条数与摘要。 +4. 静态断言:6 篇单 H1 / `## 边界与注意` / 无被禁写法 / 该配 live 的五篇有 `` + 动态 loader / 按键篇不接 live / 5 个 demo 默认导出且无 DOM 属性(`texture-demo` 允许且仅允许 `@motajs/render` 的 `Texture`)/ 侧边栏 12 条(本批 6 条 + 10-43 的 6 条)都在 / 第 3 与第 4 篇的跨页链接已回填。 +5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。 +6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-44 门禁` 小节:六类命令与结果、`docs/` 路径类型报错 0、既有引擎报错条数、构建耗时、本批 6 篇与 5 个 demo 清单。 +7. 交叉一致性检查并写进该小节:第 8 篇与第 12 篇的 `hidden` 表述逐字同义(「不显示、不交互」+「保留元素与状态」);第 6 篇对第 17 篇仍是纯文本前瞻引用(链接由 10-46 回填),本批未引入任何指向未创建页面的链接;第 3 / 4 篇的跨页链接已回填且构建 0 dead link。 + +本任务不改正文语义,只做格式化、断言与记录。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-44):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-44' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const live=["image-and-texture","layer-transform-performance","reactivity","events","conditional-and-list-rendering"];const md=live.concat(["hotkey-in-ui"]);md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m);if(live.indexOf(m)>=0){if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m)}});const hk=rd("docs/advanced/ii/ui/hotkey-in-ui.md");if(hk.indexOf("\x3cClientOnly\x3e")>=0)bad.push("HK-LIVE");const L=rd("docs/advanced/ii/ui/layer-transform-performance.md");const C=rd("docs/advanced/ii/ui/conditional-and-list-rendering.md");[L,C].forEach(function(s,i){if(s.indexOf("不显示、不交互")<0)bad.push("HIDDEN-SEMANTICS:"+i);if(s.indexOf("保留")<0)bad.push("HIDDEN-KEEP:"+i)});["texture-demo","layer-demo","events-demo","reactivity-demo","conditional-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(m==="texture-demo"){if(/from\s+[\x22\x27]@(?:motajs\/(?!render[\x22\x27])|user\/)/.test(s))bad.push("DEMO-ENGINE:"+m)}else{if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m)}if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m)});const p3=rd("docs/advanced/ii/ui/container-and-coordinates.md");const p4=rd("docs/advanced/ii/ui/basic-shapes.md");if(p3.indexOf("](./layer-transform-performance.md)")<0)bad.push("BACKFILL-P3");if(p4.indexOf("](./events.md)")<0)bad.push("BACKFILL-P4");const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-44 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T4-OK' + non-zero exit, or output contains "NO-CONFIRM-10-44", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "HIDDEN-", "HK-LIVE", "BACKFILL-", "NOTES-NO-"; or output lacks "T4-OK" + + prettier `--write` / `--check` 通过;ESLint 0 error / 0 warning;`docs/` 路径类型报错 0;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / 五篇接 live 且按键篇不接 / 5 个 demo 默认导出、无 DOM 属性,`texture-demo` 仅额外允许 `@motajs/render` 的 `Texture` / 侧边栏 12 条齐全 / 既有条目与高级 III 未丢 / 第 8 与第 12 篇 `hidden` 口径一致 / 第 3、4 篇跨页链接已回填);构建 green、无 dead link;NOTES 有 `### 10-44 门禁` 且含 `docs/ 路径类型报错 0` 与既有引擎报错摘要。 + 第二批 6 篇 5 demo 通过六类门禁并已记录。 + + + + Task 5: 用户目视 5 个 live 并抽查 6 篇正文 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(本批 5 个 demo) + 请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 6 篇,逐条确认:①侧边栏「元素与布局」补齐 6 条、「交互与数据」4 条,全部可点开;②纹理篇 live 能看到最小纹理与关抗锯齿后的像素边缘;③性能篇 live 能切换 `hidden` / `alpha` / `scale`,遮挡顺序正确;④响应式篇 live 的计数、计算值与监听输出一致变化;⑤事件篇 live 点击换色、悬停光标、滚轮改文字都生效;⑥条件循环篇 live 切换时状态保留、增删列表正常;⑦按键篇没有 live,正文明确说明原因;⑧抽查第 8 与第 12 篇:两处对 `hidden` 的说法一致。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-44):通过` + 下一行 `用户原文:`;发现问题则逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后再复验。只有用户明确通过才可进入 10-45。 + 6 篇正文与 5 个 live demo,构建产物可在本地预览。 + 按上面①–⑧逐条检查;重点看 `hidden` 切换是否真的不绘制不命中、事件三件套是否都生效、两篇的 `hidden` 口径是否一致。 + 若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。 + 用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。 + + 用户已明确确认 6 篇可读、5 个 live 正常、按键篇不配 live 的说明清楚,并已把结论记入 NOTES。 + + 用户人工验证结论已记录。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 构建期(SSR)→ live demo | demo 必须由 `RenderDemo` 在浏览器端动态 import;页面不得静态 import demo | +| demo → 纹理创建 | 纹理只在本地用浏览器 API 造,不加载远程图片、不发请求 | +| 按键文档 → 读者 | 文档站没有游戏的按键系统,按键篇不提供可能被误认为引擎行为的 live | +| 侧边栏 → 页面 | 每条 link 必须对应已存在页面,否则构建 dead link 失败 | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-134 | Denial of Service(构建不可用) | `.tsx` demo 与纹理创建 | high | mitigate | demo 只由 loader 动态 import、`` 包裹;纹理在 `onMounted` 或模块常量里造一次;构建门禁必须 `build complete` | +| T-10-135 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务完成;静态断言复核 12 条链接与既有条目未丢;构建 0 dead link | +| T-10-136 | Information Disclosure | 按键篇误写成内部实现 | low | mitigate | 静态断言禁 `saveState` / `loadState` / `preventDefault`;正文只写 `useKey` / `implement` / 注册与分组 | +| T-10-137 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录命名确认、哈希比对、门禁与人工验证;每个 auto 任务复检 `用户确认(10-44):可以执行` | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告,不得临时安装 | + + + +- 确认门禁:NOTES 含 `用户确认(10-44):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-44):通过` + `用户原文:`,无 `状态:待处理`。 +- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性。 +- 一致性门禁:第 8 与第 12 篇都含「不显示、不交互」与「保留」;第 6 篇对第 17 篇仍是纯文本前瞻引用(链接由 10-46 回填),第 9 篇对第 13 篇同样是纯文本;本批未引入任何指向未创建页面的链接;第 3 / 4 篇的跨页链接已回填。 +- 示例门禁:五篇接 live(`` + 动态 loader),按键篇不接;5 个 demo 默认导出、无 DOM 属性;`layer` / `events` / `reactivity` / `conditional` 不 import 引擎包,`texture-demo` 仅额外 import `@motajs/render` 的 `Texture`。 +- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。 +- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改 10-43 已验收的 6 篇与 5 个 demo 的语义;未改 `10-01`..`10-43` 计划;未 commit;ROADMAP / STATE 本计划不改。 + + + +- 读者读完这一批,能用状态驱动画面、接住点击与滚轮、用按键收口操作,并知道 `hidden` 与三元的取舍。 +- 6 篇正文与 5 个 live 全部可用;按键篇明确交代不配 live 的原因,不误导读者。 +- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-44-SUMMARY.md` when done + diff --git a/.planning/phases/10-docs-restructure/10-44-SUMMARY.md b/.planning/phases/10-docs-restructure/10-44-SUMMARY.md new file mode 100644 index 0000000..2cd1515 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-44-SUMMARY.md @@ -0,0 +1,179 @@ +--- +phase: 10-docs-restructure +plan: 44 +subsystem: docs +tags: [vitepress, tsx, ui, texture, reactivity, events, hotkey, conditional-rendering] + +requires: + - phase: 10-docs-restructure + provides: 10-43 的 6 篇元素与布局正文、5 个 live demo、侧边栏子分组骨架 +provides: + - Part 1 收尾两篇(图片与最小纹理、层级/变换与性能) + - Part 2 四篇(响应式、事件与交互、按键与快捷键、条件与循环渲染) + - 5 个 live demo 与侧边栏「交互与数据」分组 + - 第 3 / 4 篇跨页链接回填 +affects: [10-45, 10-46, 10-47] + +actuals: + tokens: 9666 + tasks: 5 + commits: 0 + +tech-stack: + added: [] + patterns: + - hidden 优先、三元只用于必须卸载/重置/释放的场景 + - ref / reactive / computed / watch 的 UI 写作口径 + - 事件 onXxx + 捕获变体,enter/leave 不按普通冒泡 + - useKey 作用域跟随组件生命周期 + +key-files: + created: + - docs/advanced/ii/ui/image-and-texture.md + - docs/advanced/ii/ui/layer-transform-performance.md + - docs/advanced/ii/ui/reactivity.md + - docs/advanced/ii/ui/events.md + - docs/advanced/ii/ui/hotkey-in-ui.md + - docs/advanced/ii/ui/conditional-and-list-rendering.md + - docs/.vitepress/components/demos/ui/texture-demo.tsx + - docs/.vitepress/components/demos/ui/layer-demo.tsx + - docs/.vitepress/components/demos/ui/events-demo.tsx + - docs/.vitepress/components/demos/ui/reactivity-demo.tsx + - docs/.vitepress/components/demos/ui/conditional-demo.tsx + modified: + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/container-and-coordinates.md + - docs/advanced/ii/ui/basic-shapes.md + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + +key-decisions: + - "第 7 篇最小纹理用 document.createElement('canvas') 画棋盘再包成 Texture" + - "按键篇不配 live:文档站没有游戏按键系统,避免误导读者" + - "hidden 与三元的口径在第 8、12 篇保持逐字同义" + - "第 9 篇对第 13 篇、第 6 篇对第 17 篇仍为纯文本前瞻引用,链接留给后续批次回填" + +requirements-completed: [] + +coverage: + - id: D1 + description: "图片与最小纹理篇 + texture live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "live 的纹理放大效果需要人眼确认像素边缘是否清晰" + - id: D2 + description: "层级、变换与性能篇 + layer live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "hidden / alpha / scale 切换与遮挡顺序需要人工目视" + - id: D3 + description: "响应式篇 + reactivity live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "计数、计算值与监听输出的一致性需要人工目视" + - id: D4 + description: "事件与交互篇 + events live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "点击、悬停光标、滚轮与坐标显示需要人工操作确认" + - id: D5 + description: "按键与快捷键篇(无 live)" + verification: + - kind: automated_ui + ref: "静态断言禁止 与内部接口" + status: pass + human_judgment: true + rationale: "正文是否清楚交代「不配 live 的原因」需要人工审阅" + - id: D6 + description: "条件与循环渲染篇 + conditional live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "hidden 切换后的状态保留与列表增删需要人工目视" + +duration: 15min +completed: 2026-10-31 +status: complete +--- + +# Phase 10 Plan 44: 交互与数据批次 Summary + +**六篇正文与五个 TSX live 落地,第 8/12 篇统一 hidden 口径,侧边栏补齐 12 条并回填两条跨页链接** + +## Performance + +- **Duration:** 15 min +- **Started:** 2026-10-31 17:57(本地时间) +- **Completed:** 2026-10-31 18:12(本地时间) +- **Tasks:** 5(Task 0 记录 + Task 1..4;Task 5 live 人工验证待最终审阅) +- **Files modified:** 15 + +## Accomplishments + +- 新增 `image-and-texture.md` 与 `layer-transform-performance.md`,并配 `texture-demo` / `layer-demo`。 +- 新增 `reactivity.md` 与 `events.md`,建立侧边栏「交互与数据」分组,并配 `reactivity-demo` / `events-demo`。 +- 新增 `hotkey-in-ui.md`(不配 live)与 `conditional-and-list-rendering.md`,并配 `conditional-demo`。 +- 回填第 3 篇指向第 8 篇、第 4 篇指向第 10 篇的跨页链接;只改链接,不改文字语义。 +- 六类门禁全绿:prettier、ESLint、docs 类型、静态断言、全量构建。 + +## Files Created/Modified + +- `docs/advanced/ii/ui/image-and-texture.md` - 图片元素、canvas 最小纹理、像素图设置 +- `docs/advanced/ii/ui/layer-transform-performance.md` - zIndex、变换、hidden、缓存、noevent +- `docs/advanced/ii/ui/reactivity.md` - ref / reactive / computed / watch / shallowRef / markRaw +- `docs/advanced/ii/ui/events.md` - 命中、事件名、捕获冒泡、noevent、cursor、actionStroke +- `docs/advanced/ii/ui/hotkey-in-ui.md` - useKey / implement / addCommand / setGroup / 默认按键 +- `docs/advanced/ii/ui/conditional-and-list-rendering.md` - hidden vs 三元、map 与 key +- `docs/.vitepress/components/demos/ui/*.tsx` - 5 个 live demo(texture / layer / events / reactivity / conditional) +- `docs/.vitepress/config.ts` - 元素与布局补 2 条、「交互与数据」新增 4 条 +- `docs/advanced/ii/ui/container-and-coordinates.md` - 第 8 篇链接回填 +- `docs/advanced/ii/ui/basic-shapes.md` - 第 10 篇链接回填 +- `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md` - 10-44 命名确认、哈希复核、门禁与待审记录 + +## Decisions Made + +- 纹理方案采用 canvas 自造棋盘,符合 Task 0 推荐方案。 +- 按键篇不配 live,正文用一小节说明「文档站没有游戏按键系统」。 +- `hidden` 与三元的选择写成判定表,第 8、12 篇共用同一口径。 +- 第 9 篇对第 13 篇保持纯文本前瞻引用,等 10-45 建页后回填。 + +## Deviations from Plan + +None - 计划内容按原样落地(仅执行机制上适配了 PowerShell 5.1 的引号/标准错误行为,未改任何断言)。 + +## Issues Encountered + +- PowerShell 5.1 把 `node -e` 的内嵌引号剥离,导致计划里的 `` 片段不能原样执行;改为把同一段 JS 写入临时 `.cjs` 后运行,断言内容未变。 +- PowerShell 把构建的标准错误输出当作终止错误;执行时将该段 `$ErrorActionPreference` 临时设为 `Continue`,构建结果仍按退出码、`build complete` 与 dead link 判定。 + +## Gates + +| 门禁 | 结果 | +|------|------| +| prettier `--write` / `--check` | 通过,`All matched files use Prettier code style!` | +| ESLint | 0 error / 0 warning | +| `vue-tsc -p docs/tsconfig.json` | `docs/` 路径 0 报错;既有引擎报错 11 条(非本轮引入) | +| 静态断言 | `STATIC-OK` | +| 全量构建 | green,`build complete in 15.35s.`,无 dead link | + +## Pending + +- Task 5 live 目视与正文抽查:`live 人工验证(10-44):待最终人工审阅`。本轮未写「用户人工验证:通过」。 + +## Next Phase Readiness + +- 10-45 可以直接使用本批建立的响应式、事件与 hidden 口径。 +- 第 13 篇建页后需回填第 9 篇的纯文本前瞻引用。 diff --git a/.planning/phases/10-docs-restructure/10-45-PLAN.md b/.planning/phases/10-docs-restructure/10-45-PLAN.md new file mode 100644 index 0000000..e83a562 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-45-PLAN.md @@ -0,0 +1,277 @@ +--- +phase: 10-docs-restructure +plan: 45 +type: execute +wave: 3 +depends_on: + - 10-44 +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/reactivity.md + - docs/advanced/ii/ui/props.md + - docs/advanced/ii/ui/component-tsx.md + - docs/advanced/ii/ui/component-ts.md + - docs/advanced/ii/ui/slots-and-attrs.md + - docs/.vitepress/components/demos/ui/props-demo.tsx + - docs/.vitepress/components/demos/ui/component-demo.tsx + - docs/.vitepress/components/demos/ui/ts-component-demo.tsx + - docs/.vitepress/components/demos/ui/slots-demo.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 62000 + raw_tokens: 38000 + tasks: 5 + confidence: low +must_haves: + truths: + - "Part 3 四篇(props、组件 TSX、组件 TS 元素层、slots 与 attrs)落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF" + - "props 篇讲清 `defineComponent` + `SetupComponentOptions` 的 `props` 数组、属性名 camelCase、默认值用 `props.x ?? 默认`、props 是响应式且不要解构、`emits` 与 `v-model:xxx` 的关系" + - "组件(TSX)篇给出完整组件结构、`setup` 返回 render 函数、`onMounted` / `onUnmounted`、`emit` / `expose`,并明确区分「组件」与「UI」:只有声明 `controller` / `instance` / `state` 且 Props 继承 `IGameUIPropsBase, DefaultProps` 的组件才能被 `GameUI` 打开" + - "组件(TS 元素层)篇只讲元素层类:继承容器或渲染元素、实现渲染方法、`appendChild`、`update`、离屏画布复用;明确元素层类不是 UI、不能直接交给 `GameUI`;不出现标签注册、`createElement` 与渲染器类名" + - "slots 与 attrs 篇讲清 TSX 里 slot 是函数、默认 / 具名 / 作用域 slot 的写法、`attrs` 透传与 `inheritAttrs`,并给出「什么时候用 slot、什么时候用 props」的判定" + - "4 个 live demo(props / component / ts-component / slots)默认导出、只 import vue 与元素标签、无 DOM 属性;页面用 `<ClientOnly>` + `() => import('...')`" + - "侧边栏新增「组件化」分组 4 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link" + - "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning" + - "未改 `packages/` / `packages-user/` / `src/`、未改 10-43 / 10-44 已验收的 12 篇正文与 10 个 demo 的语义(第 9 篇 `reactivity.md` 只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-44` 计划、未改既有 JSDoc/注释;不 commit" + artifacts: + - "docs/advanced/ii/ui/props.md、component-tsx.md、component-ts.md、slots-and-attrs.md" + - "docs/.vitepress/components/demos/ui/props-demo.tsx、component-demo.tsx、ts-component-demo.tsx、slots-demo.tsx" + - "docs/.vitepress/config.ts(高级 II 子分组内新增「组件化」分组 4 条)" + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-45 命名确认、门禁与人工验证记录)" + key_links: + - "第 13 篇的 props 写法是第 14 / 16 篇的前置:组件示例收 props、slot 组件接收 attrs,都回到同一套 `SetupComponentOptions` 声明" + - "第 14 篇的「组件 vs UI」判定必须与第 1 篇的模板一致:`IGameUIPropsBase` + `DefaultProps` + 三个 props 名,缺一不可;两篇口径不一致会让读者在 §1 与 §14 之间摇摆" + - "第 15 篇的元素层类与第 2 篇的元素层写法是同一层:`appendChild` 挂载、setter 改属性;区别只在于「类」封装了创建逻辑,不能把类当 UI 打开" + - "第 16 篇的 `attrs` 透传与第 17 篇内置组件(`Input` / `Textbox` 都用属性透传)呼应;本篇只讲机制,不提前展开内置组件" +--- + + +本计划 5 个任务、11 个 `files_modified`,略超「2–3 任务 / ≤ 8 文件」默认上限: + +- 四篇正文分两个写作任务(2 + 2),各带 2 个 demo 与侧边栏登记;门禁与人工验证各自独立。合并会得到「4 篇 + 4 demo + 侧边栏 + 全量门禁」的不可验证大块。 +- 11 个文件里 4 篇正文、4 个 demo、1 篇**只回填链接**的 10-44 已验收页面(第 9 篇 `reactivity.md`——10-43 约定目标页不存在时只写纯文本,由本批创建第 13 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件,共享同一份哈希基线与同一套规则。 +- 本批内容量小于前两批(无按键表、无性能表),但两篇「组件」是概念分水岭(Vue 组件 vs 元素层类),必须留出足够篇幅,不能压缩成接口清单(D-88)。 + +不删内容:四篇正文、4 个 live、组件 vs UI 判定、slots / attrs 判定、六类门禁、用户目视全部保留。 + + + +落地 Part 3 组件化四篇:props、组件(TSX)、组件(TS 元素层)、slots 与 attrs。这一批把读者从「一个文件写完一个面板」推到「会拆组件、会传参、会开槽、会透传属性」,并明确划出「Vue 组件」与「元素层类」的界线。 + +Purpose: 后面的内置组件与完整示例都要复用组件化能力;如果读者在这里分不清组件与 UI、组件与元素层类,后面每一篇都会重新解释一次。 +Output: 4 篇正文、4 个 `.tsx` live demo、侧边栏「组件化」分组、NOTES 追加记录。**不改源码、不改前两批已验收内容、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-44-PLAN.md +@docs/.vitepress/config.ts +@docs/advanced/ii/ui/ui-template.md +@docs/advanced/ii/ui/ui-template-ts.md +@docs/advanced/ii/ui/conditional-and-list-rendering.md +@docs/.vitepress/components/demos/ui/template-demo.tsx + +**流程约定:** +- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-44` 计划;不重规划其它批次。 +- **Task 0 是硬关卡**:汇报本计划 4 篇写什么、4 个 demo 名、组件 vs UI 与组件 vs 元素层类两条界线怎么讲,等用户明确回复「可以执行」。 +- 4 篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名则先更新 NOTES 再落盘。 +- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。 +- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。 + +**本批写作硬规则(与 10-43 / 10-44 一致):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。 + +**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `packages/render-vue/src/types.ts`(`DefaultProps` / `SetupComponentOptions`)、`render-vue/src/props.ts`、`render/src/core/item.ts`、`render/src/core/container.ts`、`render/src/core/custom.ts`、`render/src/core/canvas2d.ts`、`client-base/src/types.ts`、`client-base/src/components/input.tsx` 与 `textbox.tsx`(只看 `attrs` 透传形态)。写作前逐条 `git hash-object` 比对;不一致或工作树被改即停下问用户。 + + + + + + Task 0: 汇报组件化四篇的边界讲法,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 13–16 篇;Vue / TSX Integration 全节)、docs/advanced/ii/ui/ui-template.md 与 ui-template-ts.md(已落地口径)、docs/.vitepress/config.ts + 向用户做四段汇报并停下等待: + +**要做什么**——落地四篇:props、组件(TSX)、组件(TS 元素层)、slots 与 attrs;配 4 个 `.tsx` live。 + +**为什么**——读者到这一批必须会拆组件。这里有两个最容易混淆的界线:①「组件」不等于「UI」(UI 必须能拿到 `controller` / `instance` / `state` 且 Props 继承 `IGameUIPropsBase, DefaultProps`);②「Vue 组件」不等于「元素层类」(后者不是 UI,不能直接交给 `GameUI`)。这两条界线如果讲不清,后面的内置组件与完整示例就要反复解释。 + +**大致怎么做**——Task 1 写 props 篇与组件(TSX)篇 + `props-demo` / `component-demo`;Task 2 写组件(TS 元素层)篇与 slots / attrs 篇 + `ts-component-demo` / `slots-demo`;Task 3 跑六类门禁并写 NOTES;Task 4 由用户目视 4 个 live 并抽查正文。 + +**影响范围**——新增 `docs/advanced/ii/ui/` 下 4 个 `.md` 与 `demos/ui/` 下 4 个 `.tsx`;追加侧边栏「组件化」4 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前两批已验收的 12 篇与 10 个 demo、ROADMAP / STATE。 + +**请用户确认:** +1. 四篇文件名与侧边栏名沿用 10-43 命名总表(`props.md` / `component-tsx.md` / `component-ts.md` / `slots-and-attrs.md`)。 +2. 第 14 篇的示例组件用「带选中态的道具格子」还是「进度条」;推荐前者,因为第 23 篇的完整示例会复用同一个组件概念。 +3. 「组件 vs UI」与「组件 vs 元素层类」两条界线是否都单独设小节(推荐都设,各控制在半页内)。 + +**参考文件:`packages/render-vue/src/types.ts`(`DefaultProps` / `SetupComponentOptions`)、`render-vue/src/props.ts`、`render/src/core/item.ts`、`render/src/core/container.ts`、`render/src/core/custom.ts`、`render/src/core/canvas2d.ts`、`client-base/src/types.ts`、`client-base/src/components/input.tsx` 与 `textbox.tsx`(只看 `attrs` 透传形态);策略:写作前逐条 `git hash-object -- ` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。 + 尚无产物;本任务只汇报四篇范围、示例选型与两条界线的讲法。 + 确认:①是否同意四篇范围与 4 个 live;②第 14 篇示例组件选道具格子还是进度条;③两条界线是否各设一小节;④四篇命名是否沿用确认值。 + 回复「可以执行」以继续(请同时给示例选型);其它回复视为未批准。 + 用户已回复「可以执行」,且示例选型、两条界线是否分节、四篇命名三项已确定。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,示例组件选型与两条界线的分节方式已确定。 + + 用户回复「可以执行」且待定项已定。 + + + + Task 1: props / 组件(TSX)两篇 + 两个 demo + 侧边栏「组件化」 + docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/.vitepress/components/demos/ui/props-demo.tsx, docs/.vitepress/components/demos/ui/component-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/reactivity.md + 本计划的 Task 0 已记录 `用户确认(10-45):可以执行`;10-44 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 13、14 篇;Vue / TSX Integration 全节)、packages/render-vue/src/types.ts(`DefaultProps` / `SetupComponentOptions`)、packages/render-vue/src/props.ts:24-81、packages-user/client-base/src/types.ts:16-55、docs/advanced/ii/ui/ui-template.md(模板与 Props 基类口径)、dev.md:54、97-98 + 先向 NOTES 末尾追加 `## 10-45 命名确认`:独占一行 `用户确认(10-45):可以执行`、下一行 `用户原文:`、四篇与四个 demo 最终名、第 14 篇示例选型;再重跑本任务参考文件的哈希比对并追加结果。然后写两篇正文与两个 demo。 + +**(1)`props.md`(第 13 篇)**:先回答「组件怎么拿参数」。讲 `interface ItemCellProps extends DefaultProps`(普通组件不必继承 UI 基类),`const itemCellProps = { props: ['item', 'selected'] } satisfies SetupComponentOptions`,以及为什么 `props` 数组必须把用到的键写全(没写就收不到)。讲: +- 属性名 camelCase(写错不报错也拿不到)。 +- 默认值写法:`const size = props.size ?? 16`,并说明不使用其它默认值语法。 +- props 是响应式对象:在 render 函数里读 `props.x` 会跟随更新;**不要解构**(解构会丢响应式),需要局部变量就在 render 函数里取。 +- `emits`:声明后 `emit('select', item.id)`;`update:xxx` 只作为 `v-model:xxx` 的实现出现,演示父组件用 `v-model:selected` 绑定,**不教手动监听对应事件属性**。 +- 一小节「props 与 `hidden` / 三元」:控制显示用 prop 传 `hidden`,不要用 prop 传「渲染什么组件」。 +示例用 `ItemCell` + 父组件传三份不同 props。`## 边界与注意`:漏写 prop 名等于没传;解构丢响应式;默认值不要写成改写 props;子组件不要直接改 props。 + +**(2)`component-tsx.md`(第 14 篇)**:先讲一个 TSX 组件的完整结构(import → Props 接口 → `SetupComponentOptions` → `defineComponent` → render 函数 → 导出),用第 0 步选定的组件写完整实现(props + `computed` + `return () => (...)`)。然后讲生命周期:`onMounted` 做什么(需要实例的操作)、`onUnmounted` 做什么(清理)。讲 `emit` 与 `expose`:父组件怎么拿子组件方法(`ref` + `expose`),并给一小段示例。最后单设小节**「组件与 UI 的区别」**:UI 是「能被 `GameUI` 打开、由 UI 栈管理的组件」,因此它必须声明 `controller` / `instance` / `state`,且 Props `extends IGameUIPropsBase, DefaultProps`;普通组件没有这些,只负责画面的一部分。给一张两列对照表。`## 边界与注意`:组件不声明三个 props 就不是 UI,不能直接 `new GameUI` 打开;`defineComponent` 的第二个参数是 `SetupComponentOptions`;生命周期钩子必须在 `setup` 同步调用;`expose` 只暴露必要方法。 + +**(3)两个 demo**:`props-demo.tsx`(`PropsDemo`)父组件传不同 props 给 `ItemCell`,点击回调改选中态;`component-demo.tsx`(`ComponentDemo`)展示第 14 篇的完整组件 + 一个通过 `ref` 调用 `expose` 方法的按钮。都默认导出、只 import vue 与元素标签、无 DOM 属性;一个文件内可定义多个局部组件(ESLint 的 `vue/one-component-per-file` 只针对 `.vue`,`.tsx` 不受该规则约束)。 + +**(4)侧边栏**:在子分组 `items` 追加 `{ text: '组件化', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/props` 与 `/advanced/ii/ui/component-tsx` 两条。只做加法。 + +**(5)回填第 9 篇的跨页链接**:`docs/advanced/ii/ui/reactivity.md` 最后一小节现在写的是纯文本「第 13 篇『组件与 props』」(10-44 的约定:目标页不存在时只写纯文本)。本任务已创建第 13 篇,把该纯文本改成 `[第 13 篇「组件与 props」](./props.md)`。**只改这一处链接,不改任何文字语义、不动该页其它内容。** + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/props.md":["SetupComponentOptions","props:","camelCase","??","emits","v-model:","解构"],"docs/advanced/ii/ui/component-tsx.md":["defineComponent","SetupComponentOptions","onMounted","onUnmounted","emit","expose","IGameUIPropsBase","DefaultProps","controller","instance","state"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["props-demo.tsx","component-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/props","/advanced/ii/ui/component-tsx","/advanced/ii/ui/conditional-and-list-rendering","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});const p9=rd("docs/advanced/ii/ui/reactivity.md");if(p9.indexOf("](./props.md)")<0)bad.push("BACKFILL-P9");if(cfg.indexOf("组件化")<0)bad.push("CFG-NO-PART3");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK' + non-zero exit, or output contains "NO-CONFIRM-10-45", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P9", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK" + + NOTES 追加 10-45 命名确认(确认标记 + 用户原文 + 示例选型)与哈希比对;props 篇含 `SetupComponentOptions` / `props` 数组 / camelCase / `??` 默认值 / `emits` / `v-model:` / 解构警告;组件 TSX 篇含 `defineComponent` / 生命周期 / `emit` / `expose` 与「组件 vs UI」对照表(`IGameUIPropsBase` / `DefaultProps` / 三个 props 名);两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性、不 import 任何引擎包;第 9 篇(`reactivity.md`)里对第 13 篇的纯文本引用已回填为 `./props.md` 链接且该页其它内容未变;侧边栏新增「组件化」两条且既有条目未丢;构建 green、无 dead link。 + props 篇与组件 TSX 篇完成,「组件 vs UI」界线立起。 + + + + Task 2: 组件(TS 元素层)/ slots 与 attrs 两篇 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/component-ts.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/.vitepress/components/demos/ui/ts-component-demo.tsx, docs/.vitepress/components/demos/ui/slots-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-45):可以执行`;Task 1 两篇与「组件化」分组已存在且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 15、16 篇;Render Elements;Vue / TSX Integration)、packages/render/src/core/container.ts(容器与绘制流程)、packages/render/src/core/item.ts:196-244(渲染入口与 `update`)、packages/render/src/core/custom.ts:6-59(`CustomRenderItem` / `bindings`)、packages/render/src/core/canvas2d.ts:25-30(离屏画布复用建议)、packages-user/client-base/src/components/input.tsx:261-270(`attrs` 透传形态)、packages-user/client-base/src/components/textbox.tsx:539-548 + 写两篇正文与两个 demo。 + +**(1)`component-ts.md`(第 15 篇)**:先讲清这一篇讲的是**元素层**,不是 UI:用类把「怎么画」封装起来,再用 `appendChild` 挂到画布容器上。内容: +- 最小自定义容器类:先 `interface IBadge { /* 本类对外暴露的成员,带 jsDoc */ }`,再 `class Badge extends Container implements IBadge`(`dev.md` 要求所有类先声明 `interface` 再由类 `implements`,不得出现没有 `implements` 的类);在类里组织子元素或在渲染入口里绘制;给完整片段(含 `interface`、`class`、import 与导出)。 +- 元素层类的常用扩展点:绘制入口、`update()`(告诉父级自己脏了)、`appendChild`(组合子元素)、离屏画布复用(需要缓存时用 `requireCanvas` 申请、用 `deleteCanvas` 归还,而不是每次渲染都新建画布)。 +- 在 UI 组件里使用:`ref` 拿容器 → `onMounted` 里 `host.value!.appendChild(new Badge())`(与第 2 篇同一套写法)。 +- 什么时候值得写元素层类:同一套绘制要被多处以命令式方式复用、或者需要精细控制绘制与命中;普通界面结构用 TSX 组件即可。 +- 单设小节**「组件 vs 元素层类」**:Vue 组件参与响应式与 UI 栈,元素层类不参与;元素层类不能被 `GameUI` 打开;两者可以组合(Vue 组件里挂元素层类)。 +`## 边界与注意`:元素层类不是 UI;不要在这里注册自定义标签(那属于渲染器内部);忘了 `update()` 会导致画面不刷新;离屏画布不要每次渲染都新建。 + +**(2)`slots-and-attrs.md`(第 16 篇)**:先讲 slot 解决什么问题(父组件决定子组件里面放什么)。内容: +- 默认 slot:子组件里调用 `slots.default?.()`;父组件在标签之间写内容。 +- 具名 slot:`slots.title?.(...)`,父组件用具名写法传入;说明 TSX 里 slot 是函数,不是标签。 +- 作用域 slot:子组件把数据传给 slot 函数,父组件拿到参数再渲染。 +- `attrs`:没被 `props` 声明、也没被 `emits` 消费的属性会进 `attrs`;用 `{...attrs}` 透传到底层元素或内置组件;讲 `inheritAttrs: false` 什么时候需要。提「第 17 篇的内置组件也用属性透传」时**只写纯文本**,不要写 `./builtin-text-and-input.md` 链接——该页在 10-46 创建,届时由 10-46 回填。 +- 判定表:什么时候用 slot(结构由调用方决定)、什么时候用 props(数据与开关由调用方决定)、什么时候用 attrs(纯透传)。 +示例写一个带标题 slot 与默认 slot 的面板,再加一个把 `fillStyle` / `font` 透传给文字元素的包装组件(证明属性名仍要 camelCase)。正文代码块可以同时给 `fillStyle` 与 `font`,其中 `font` 写成 `new Font('Verdana', 16, 'px', 400)`(**位置参数**;`Font` 构造签名是 `(family, size, sizeUnit, weight, italic)`,不存在对象参数形式);**live 里只透传 `fillStyle`**——`font` 需要 `Font` 实例,live 不为此引入引擎 import(见下条 demo 约束)。`## 边界与注意`:TSX 里 slot 是函数,忘记 `?.()` 什么都不显示;`attrs` 透传不会做 camelCase 转换,属性名照原样;`inheritAttrs: false` 只影响自动落到根元素,不阻止手动透传;slot 内容变化不会重置子组件状态。 + +**(3)两个 demo**:`ts-component-demo.tsx`(`TsComponentDemo`)用 TSX 等价展示第 15 篇的元素层类画面(类本身只出现在正文代码块);`slots-demo.tsx`(`SlotsDemo`)展示带标题 slot 与默认 slot 的面板 + 一个 attrs 透传包装组件(**只透传 `fillStyle`**)。都默认导出、无 DOM 属性,且**只** import vue 与元素标签——`slots-demo` 不 import 任何 `@motajs/*` / `@user/*`(`font` 的透传只留在正文代码块)。 + +**(4)侧边栏**:在「组件化」分组追加 `/advanced/ii/ui/component-ts` 与 `/advanced/ii/ui/slots-and-attrs` 两条。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/component-ts.md":["interface IBadge","implements IBadge","extends Container","appendChild","update(","onMounted","GameUI","requireCanvas","deleteCanvas"],"docs/advanced/ii/ui/slots-and-attrs.md":["slots.default","slots.title","attrs","inheritAttrs","camelCase"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const ts=fs.existsSync("docs/advanced/ii/ui/component-ts.md")?rd("docs/advanced/ii/ui/component-ts.md"):"";if(ts.indexOf("元素层")<0)bad.push("TS-NO-LAYER-WORD");if(ts.indexOf("不是 UI")<0&&ts.indexOf("不能直接")<0)bad.push("TS-NO-UI-BOUNDARY");const sa=rd("docs/advanced/ii/ui/slots-and-attrs.md");if(sa.indexOf("](./builtin-text-and-input.md)")>=0)bad.push("SA-FORWARD-LINK");["ts-component-demo.tsx","slots-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/component-ts","/advanced/ii/ui/slots-and-attrs","/advanced/ii/ui/props","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "NO-CONFIRM-10-45", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "TS-NO-", "SA-FORWARD-LINK", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK" + + 元素层篇含 `interface IBadge` + `implements IBadge` + `extends Container` / `appendChild` / `update(` / 离屏画布复用 / 「元素层不是 UI、不能直接被 `GameUI` 打开」的界线,且不出现标签注册与渲染器类名;slots 篇含 `slots.default` / `slots.title` / `attrs` / `inheritAttrs` / camelCase 提醒与判定表;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出、无 DOM 属性且不 import 任何引擎包(`slots-demo` 只透传 `fillStyle`,`font` 只在正文代码块);第 16 篇对第 17 篇只写纯文本前瞻引用(不含 `./builtin-text-and-input.md` 链接,由 10-46 回填);侧边栏补两条且既有条目未丢;构建 green、无 dead link。 + 元素层组件篇与 slots / attrs 篇完成,Part 3 四篇齐备。 + + + + Task 3: 六类门禁收口 + NOTES 记录 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1..2 的 4 篇与 4 个 demo 已落盘、侧边栏 4 条齐全、构建 green。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 4 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts + 按固定顺序跑门禁并记录: + +1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。 +2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning;布尔 JSX 属性用简写。 +3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。 +4. 静态断言:4 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live 且 `` + 动态 loader / 4 个 demo 默认导出且只 import vue / 侧边栏 16 条(本批 4 + 前三批 12)都在 / 既有条目与高级 III 未丢。 +5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。 +6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-45 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 4 篇与 4 个 demo 清单。 +7. 交叉一致性:第 13 篇的 props 声明与第 14 篇的组件实现使用同一套写法;第 1 篇与第 14 篇的「UI 判定」三要素(`IGameUIPropsBase` / `DefaultProps` / 三个 props 名)表述一致。把核对结论写进该小节。 + +本任务不改正文语义。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-45):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-45' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const md=["props","component-tsx","component-ts","slots-and-attrs"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["props-demo","component-demo","ts-component-demo","slots-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/from\s+[\x22\x27]@(?:motajs|user)\//.test(s))bad.push("DEMO-ENGINE:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m)});const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");const u1=rd("docs/advanced/ii/ui/ui-template.md");const c14=rd("docs/advanced/ii/ui/component-tsx.md");["IGameUIPropsBase","DefaultProps"].forEach(function(k){if(u1.indexOf(k)<0||c14.indexOf(k)<0)bad.push("CONSIST:"+k)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-45 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T3-OK' + non-zero exit, or output contains "NO-CONFIRM-10-45", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "CONSIST:", "NOTES-NO-"; or output lacks "T3-OK" + + prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(4 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 4 个 demo 合规 / 侧边栏 16 条齐全 / 第 1 与第 14 篇 UI 判定口径一致);构建 green、无 dead link;NOTES 有 `### 10-45 门禁` 且含类型检查与引擎报错摘要。 + Part 3 四篇 4 demo 通过六类门禁并已记录。 + + + + Task 4: 用户目视 4 个 live 并抽查四篇正文 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 3 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 4 篇)、docs/.vitepress/components/demos/ui/(本批 4 个 demo) + 请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 4 篇,逐条确认:①侧边栏「组件化」4 条可点开;②props 篇 live 的三个格子显示不同 props,点击回调生效;③组件 TSX 篇 live 的组件正常显示,`expose` 按钮能触发子组件方法;④元素层篇 live 与正文的类片段画面一致;⑤slots 篇 live 的标题 slot 与默认 slot 都渲染出来,attrs 透传的文字样式生效;⑥抽查第 13 / 14 篇:props 声明与组件实现是同一套写法,UI 判定三要素与第 1 篇一致;⑦抽查第 15 篇:明确写了「元素层不是 UI」,且没有出现标签注册与渲染器类名。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-45):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 3 后复验。只有用户明确通过才可进入 10-46。 + 4 篇正文与 4 个 live demo,构建产物可在本地预览。 + 按上面①–⑦逐条检查;重点看 props 与组件两篇的写法是否一致、两条界线是否讲清、slot 是否真的渲染。 + 若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。 + 用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。 + + 用户已明确确认 4 篇可读、4 个 live 正常、两条界线清楚,并已把结论记入 NOTES。 + + 用户人工验证结论已记录。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 构建期(SSR)→ live demo | demo 由 `RenderDemo` 在浏览器端动态 import;页面只静态 import 包装组件 | +| demo → 元素层类 | 文档正文展示类,demo 用 TSX 等价画面;不在 live 里动态注册标签 | +| 侧边栏 → 页面 | 每条 link 必须对应已存在页面,否则构建 dead link 失败 | +| 文档 → 读者 | 组件 / UI / 元素层类三条概念边界若写混,读者会写出无法打开的 UI | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-138 | Denial of Service(构建不可用) | `.tsx` demo | high | mitigate | demo 由 loader 动态 import、`` 包裹;构建门禁必须 `build complete` | +| T-10-139 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务;静态断言复核 16 条链接与既有条目、高级 III 未丢 | +| T-10-140 | Information Disclosure | 元素层篇误写渲染器内部 | low | mitigate | 静态断言禁渲染器类名 / 标签注册 / core 命名空间;正文只写类 + `appendChild` | +| T-10-141 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录;每个 auto 任务复检 `用户确认(10-45):可以执行` | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 | + + + +- 确认门禁:NOTES 含 `用户确认(10-45):可以执行` + `用户原文:`;Task 4 后含 `用户人工验证(10-45):通过` + `用户原文:`,无 `状态:待处理`。 +- 内容门禁:4 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性。 +- 概念门禁:第 1 与第 14 篇的 UI 判定三要素一致;第 15 篇明确「元素层不是 UI」。 +- 示例门禁:4 篇全部接 live(`` + 动态 loader);4 个 demo 默认导出、只 import vue、无 DOM 属性。 +- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。 +- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前两批已验收内容;未改 `10-01`..`10-44` 计划;未 commit;ROADMAP / STATE 本计划不改。 + + + +- 读者能把面板拆成组件,会传 props、开 slot、透传属性,并分得清组件 / UI / 元素层类。 +- 4 篇正文与 4 个 live 可用;第 1 与第 14 篇的 UI 判定口径一致。 +- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-45-SUMMARY.md` when done + diff --git a/.planning/phases/10-docs-restructure/10-46-PLAN.md b/.planning/phases/10-docs-restructure/10-46-PLAN.md new file mode 100644 index 0000000..ed7d54f --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-46-PLAN.md @@ -0,0 +1,327 @@ +--- +phase: 10-docs-restructure +plan: 46 +type: execute +wave: 4 +depends_on: + - 10-45 +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/slots-and-attrs.md + - docs/advanced/ii/ui/text.md + - docs/advanced/ii/ui/builtin-text-and-input.md + - docs/advanced/ii/ui/builtin-list-and-containers.md + - docs/advanced/ii/ui/ui-controller-and-stack.md + - docs/advanced/ii/ui/replace-builtin-ui.md + - docs/advanced/ii/ui/ui-performance.md + - docs/.vitepress/components/demos/ui/builtin-text-demo.tsx + - docs/.vitepress/components/demos/ui/builtin-list-demo.tsx + - docs/.vitepress/components/demos/ui/controller-demo.tsx + - docs/.vitepress/components/demos/ui/strategy-demo.tsx + - docs/.vitepress/components/demos/ui/perf-demo.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 72000 + raw_tokens: 45000 + tasks: 6 + confidence: low +must_haves: + truths: + - "Part 4 五篇(内置组件文本与输入、内置组件列表与容器、UIController 与 UI 栈、修改/替换内置 UI、UI 系统性能与注意事项)落地,每篇单 `#` H1、按 D-84 组织、末尾 `## 边界与注意`、CRLF" + - "内置组件篇只写公开契约(props / emits / expose):`TextContent` 的 `width` 必填与 `autoHeight`、`Textbox` 的标题与内边距、`Input` 用 `v-model:value`、`List` 用 `v-model:selected`、`Page` / `Scroll` / `Selection` 的对外用法;`Choices` 必须写,只按接口讲" + - "特殊组件 `InputBox` / `ConfirmBox` / `Choices` 按「单次调用型」讲:通过 UI 栈打开或调用封装函数、结果用 Promise 或事件拿到;不引用实现细节;`Choices` 正文标题保留 `Choices`,并说明「用户习惯叫 `ChoicesBox`,**源码导出名是 `Choices` / `ChoicesUI`**」——不得写成按 `ChoicesBox` 就能 import" + - "UIController 篇讲清四层模型(声明 / 控制 / 实例 / 显示)、栈与背景、`active` / `showBack`、`open` / `close` / `closeAll` / `hide` / `show`、`lastOnly` / `showAll` / `showCustom`、`keep` 防闪烁、场景 UI 与主 UI 的区别;并明确当前没有全局 UI 注册 / 覆盖入口" + - "替换内置 UI 篇先把「内置 UI」定义为 `src/client/ui` 里的 UI,再讲三种改法(打开处替换 / 包装组件 / 显示策略与背景),不教读者改 `packages`,也不引用不存在的全局注册接口" + - "UI 性能篇覆盖缓存与脏更新、HD / 抗锯齿、`hidden` 优先与三元取舍、列表 `key`、组件粒度、`Scroll` / `Page`、`keep` / `setBackground`、`createPropsBase` 每次渲染都会调用;明确本篇是 UI 系统性能,引擎级性能属于高级 III" + - "5 个 live demo(builtin-text / builtin-list / controller / strategy / perf)默认导出、无 DOM 属性;可以 import vue、元素标签、内置组件(内置组件只在 demo 内静态 import),或用 `@motajs/system` 构造最小控制器(`controller-demo` / `strategy-demo` / `perf-demo`),除此之外不得 import 其它 `@motajs/*` / `@user/*`;页面用 `<ClientOnly>` + `() => import('...')`" + - "侧边栏新增「内置组件与 UI 系统」分组 5 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link" + - "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning" + - "未改 `packages/` / `packages-user/` / `src/`、未改前三批已验收的 16 篇正文与 14 个 demo 的语义(第 6 / 16 篇各只回填一处跨页链接,不改文字语义)、未改 `10-01`..`10-45` 计划、未改既有 JSDoc/注释;不 commit;不引用 `src/client/ui/choices.tsx` 的实现细节(只按接口)" + artifacts: + - "docs/advanced/ii/ui/builtin-text-and-input.md、builtin-list-and-containers.md、ui-controller-and-stack.md、replace-builtin-ui.md、ui-performance.md" + - "docs/.vitepress/components/demos/ui/builtin-text-demo.tsx、builtin-list-demo.tsx、controller-demo.tsx、strategy-demo.tsx、perf-demo.tsx" + - "docs/.vitepress/config.ts(高级 II 子分组内新增「内置组件与 UI 系统」分组 5 条)" + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-46 命名确认、门禁与人工验证记录)" + key_links: + - "第 17 / 18 篇的内置组件契约必须与第 16 篇的 `attrs` 透传呼应:内置组件用属性透传接收样式,属性名仍 camelCase" + - "第 19 篇的 UI 栈是第 1 篇「打开 / 关闭」的系统化:第 1 篇给最小入口,本篇给栈、背景、显示策略与 `keep`;两处对 `controller` / `instance` 的用法必须一致" + - "第 20 篇的三种改法都落在「打开处」与「包装组件」,不依赖全局注册表;这与第 19 篇「没有全局覆盖入口」的结论一致,两篇不能互相矛盾" + - "第 21 篇的 `hidden` 口径必须与第 8、12 篇逐字同义;性能建议只做汇总与指向,不重新定义概念" +--- + + +本计划 6 个任务、14 个 `files_modified`,超出默认上限,保持单计划: + +- 五篇正文分三个写作任务(2 + 2 + 1),每篇都带 live;门禁与人工验证独立。第 21 篇单独成任务,是因为它要汇总前四批的所有性能结论并做交叉核对,不适合与其它篇混在一起写。 +- 14 个文件里 5 篇正文、5 个 demo、2 篇**只回填链接**的更早已验收页面(第 6 篇 `text.md`、第 16 篇 `slots-and-attrs.md`——它们对第 17 篇只写了纯文本前瞻引用,由本批创建第 17 篇后回填 markdown 链接)、1 个侧边栏、1 个记录文件,共享同一份哈希基线与同一套规则。 +- 内置组件篇的契约信息量大(`TextContent` / `Textbox` / `Input` / `List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices`),压缩会让读者拿不到可用参数,违反 D-88。 + +不删内容:五篇正文、5 个 live、`Choices` 必写、特殊组件三种、UI 栈全接口、三种替换法、性能汇总、六类门禁、用户目视全部保留。 + + + +落地 Part 4:内置组件(文本与输入、列表与容器)、UIController 与 UI 栈、修改 / 替换内置 UI、UI 系统性能与注意事项。这一批把读者从「自己写组件」带到「用现成组件 + 接 UI 栈 + 改内置 UI」,并给出一份可执行的性能清单。 + +Purpose: 背包面板不可能全部手写;`TextContent` / `Input` / `List` / `Page` / `Scroll` 覆盖了绝大多数界面需求,`UIController` 决定面板怎么叠、怎么关、背景怎么留。性能篇则是整批的唯一汇总口径,第 8 / 12 篇的 `hidden` 结论在这里收口。 +Output: 5 篇正文、5 个 `.tsx` live demo、侧边栏「内置组件与 UI 系统」分组、NOTES 追加记录。**不改源码、不改前三批已验收内容、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-45-PLAN.md +@docs/.vitepress/config.ts +@docs/advanced/ii/ui/ui-template.md +@docs/advanced/ii/ui/layer-transform-performance.md +@docs/advanced/ii/ui/slots-and-attrs.md +@docs/.vitepress/components/demos/uiSystem.vue +@docs/.vitepress/components/demos/ui/component-demo.tsx + +**流程约定:** +- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-45` 计划;不重规划其它批次。 +- **Task 0 是硬关卡**:汇报五篇范围、5 个 demo 名、内置组件篇的契约取舍(哪些展开、哪些只给一行)、第 20 篇的示例力度,等用户明确回复「可以执行」。 +- 五篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名先更新 NOTES 再落盘。 +- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。 +- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。 + +**本批写作硬规则(延续前三批):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。 + +**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `client-base/src/components/textbox.tsx`、`list.tsx`、`page.tsx`、`scroll.tsx`、`input.tsx`、`misc.tsx`、`system/src/ui/controller.ts`、`ui.ts`、`instance.ts`、`container.tsx`、`types.ts`、`client-modules/src/ui/func.ts`、`client-modules/src/client.ts`、`src/client/ui/inputBox.tsx`。`src/client/ui/choices.tsx` **只读 props / emits / 函数签名**,不引用实现;其工作树哈希与 HEAD 不同(Manifest I 已记录),若工作树哈希再变即停下问用户。其余 dirty 的 `src/client/ui/*` 一律不读。 + + + + + + Task 0: 汇报内置组件与 UI 系统的契约取舍,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 17–21 篇;Built-in Components;UI System;Performance;Open Questions Q5 / Q6)、docs/advanced/ii/ui/layer-transform-performance.md 与 slots-and-attrs.md(已落地口径) + 向用户做四段汇报并停下等待: + +**要做什么**——落地五篇:内置组件(文本 / 输入)、内置组件(列表 / 容器)、UIController 与 UI 栈、修改 / 替换内置 UI、UI 系统性能与注意事项;配 5 个 `.tsx` live。 + +**为什么**——读者到这一步要开始「用现成的」:文本换行、输入框、列表、分页、滚动都不该手写。同时 `UIController` 决定面板怎么叠、怎么关、背景怎么留;性能篇则是整批的唯一汇总口径,第 8 / 12 篇的 `hidden` 结论在这里收口。 + +**大致怎么做**——Task 1 写文本 / 输入篇与列表 / 容器篇 + `builtin-text-demo` / `builtin-list-demo`;Task 2 写 UIController 篇与替换内置 UI 篇 + `controller-demo` / `strategy-demo`;Task 3 写性能篇 + `perf-demo`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 5 个 live 并抽查正文。 + +**影响范围**——新增 `docs/advanced/ii/ui/` 下 5 个 `.md` 与 `demos/ui/` 下 5 个 `.tsx`;追加侧边栏「内置组件与 UI 系统」5 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前三批已验收的 16 篇与 14 个 demo、ROADMAP / STATE。 + +**请用户确认:** +1. 五篇文件名与侧边栏名沿用 10-43 命名总表。 +2. **契约取舍**:内置组件篇给「属性表 + 完整示例」还是「示例为主、只在表里列常用项」;推荐后者(D-88 要求原理讲透、不堆接口表),但 `TextContent` 的 `width` 必填、`autoHeight`、`Input` 的 `v-model:value`、`List` 的 `v-model:selected`、`Scroll` 只对直接子元素生效这几条必须写全。 +3. **第 20 篇力度**(研究 Q5):只讲「打开处替换 / 包装组件 / 显示策略与背景」三种改法,还是再加「复制内置 UI 源码再改」的完整示例;推荐只讲三种改法(当前没有全局注册表,复制源码不是推荐路径)。 +4. **`Choices` 命名**(研究 Q6):正文标题用 `Choices(选项框)`,并说明「用户习惯叫 `ChoicesBox`,源码导出名是 `Choices` / `ChoicesUI`」;是否接受。 + +**参考文件:`client-base/src/components/textbox.tsx`、`list.tsx`、`page.tsx`、`scroll.tsx`、`input.tsx`、`misc.tsx`、`system/src/ui/controller.ts`、`ui.ts`、`instance.ts`、`container.tsx`、`types.ts`、`client-modules/src/ui/func.ts`、`client-modules/src/client.ts`、`src/client/ui/inputBox.tsx`(`choices.tsx` 只读 props / emits / 函数签名);策略:写作前逐条 `git hash-object -- ` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。 + 尚无产物;本任务只汇报五篇范围、契约取舍与第 20 / 18 篇的示例力度。 + 确认:①是否同意五篇范围与 5 个 live;②内置组件篇用「示例为主 + 常用项表」是否可接受;③第 20 篇只讲三种改法是否可接受;④`Choices` 标题与 `ChoicesBox` 别名的处理是否可接受。 + 回复「可以执行」以继续(请同时给出契约取舍与第 20 篇力度的选择);其它回复视为未批准。 + 用户已回复「可以执行」,且契约取舍、第 20 篇力度、`Choices` 命名、五篇命名四项已确定。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,并已确定契约写法、第 20 篇力度与 `Choices` 命名。 + + 用户回复「可以执行」且待定项已定。 + + + + Task 1: 内置组件(文本/输入)/ 内置组件(列表/容器)两篇 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/.vitepress/components/demos/ui/builtin-text-demo.tsx, docs/.vitepress/components/demos/ui/builtin-list-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/slots-and-attrs.md + 本计划的 Task 0 已记录 `用户确认(10-46):可以执行`;10-45 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 17、18 篇;Built-in Components 全节;Open Questions Q6)、packages-user/client-base/src/components/textbox.tsx(`TextContentProps` / 事件 / expose / `TextboxProps`)、input.tsx(`InputProps` / `InputEmits`)、list.tsx(`ListProps` / `ListEmits` / `ListPageProps` / `ListPageSlots`)、page.tsx(`PageProps` / `PageEmits` / `PageExpose`)、scroll.tsx(`ScrollProps` / `ScrollExpose` 与平铺建议)、misc.tsx:280-320(`SelectionProps`)、src/client/ui/inputBox.tsx(`InputBox` 的对外用法与 `getInput` / `getInputNumber` 签名)、src/client/ui/choices.tsx(**只读** `ConfirmBoxProps` / `ChoicesProps` / emits / `getConfirm` / `getChoice` 签名) + 先向 NOTES 末尾追加 `## 10-46 命名确认`(`用户确认(10-46):可以执行` + 下一行 `用户原文:` + 契约取舍、第 20 篇力度、`Choices` 命名结论),并重跑本任务参考文件的哈希比对追加结果。然后写两篇正文与两个 demo。 + +**(1)`builtin-text-and-input.md`(第 17 篇)**:按「用现成的」组织。 +- `TextContent`:解决长文本换行与打字机。讲 `width` 必填、`autoHeight` 让高度自适应、`fill` / `stroke` 与文字样式配置;事件 `typeEnd` / `typeStart` / `updateHeight`;暴露的 `retype` / `showAll` / `getHeight` 怎么在父组件里用(`ref` + `expose`)。给一个完整示例:一段会逐字显示的说明文字 + 一个「立即显示全部」按钮。 +- `Textbox`:在 `TextContent` 上加背景、标题、内边距、图标与皮肤;`icon` / `winskin` 只写成「可填名字」的占位,说明本篇不展开素材来源;讲 `show` / `hide` / `retype` / `showAll` 与「在组件外更新文本」的 `TextboxStore` 用法(一段话 + 一小段代码,不展开内部)。 +- `Input`:模板外创建真实输入框对齐画布。讲 `value` 用 `v-model:value`、`multiline`、`placeholder`、边框与圆角、内边距;明确不要手动监听 `update:value` 对应的事件属性。 +- 特殊组件 `InputBox`:单次调用型弹窗;讲 `getInput(controller, text, loc, width, props?)` 返回 `Promise`、`getInputNumber` 返回 `Promise`,以及需要自己打开时用 `InputBoxUI` 配 `controller.open`;给一段 `await getInput(...)` 的完整示例。 +`## 边界与注意`:`TextContent` 不传 `width` 不能用;`autoHeight` 与固定高度二选一;`Input` 的 `v-model` 要带 `:value`;`InputBox` 依赖 UI 栈,关掉面板前要处理未完成的 Promise。 + +**(2)`builtin-list-and-containers.md`(第 18 篇)**: +- `List`:`list` 是 `[id, 文本]` 数组;选中用 `v-model:selected`;讲 `lineHeight` / `font` / 颜色与皮肤占位;说明初始选中以列表第一项为准,不要承诺用 `selected` 控制初始值。 +- `ListPage`:在 `List` 上加左右分栏、`basis`、`right`、`close` 与关闭按钮位置;用动态 slot 按选中 key 渲染右侧内容,给完整示例骨架。 +- `Page`:`pages` / `page` / `hideIfSingle`;事件 `pageChange` 与 `v-model:page`;暴露 `changePage` / `movePage` / `now`;默认 slot 拿到页码索引(从 0 开始)。 +- `Scroll`:`hor` / `noscroll` / `padEnd`;暴露 `scrollTo` / `getScrollLength`;**明确只对视口的直接子元素做虚拟滚动**,给出推荐写法(子元素平铺)与不推荐写法(用一个容器包住全部内容),并用一句话说明容器自定义标签只写 `container-custom`。 +- `Selection`:不接收事件的视觉光标;`color` / `border` / `alphaRange`;`winskin` 只作占位。 +- 特殊组件 `ConfirmBox` 与 `Choices`:`getConfirm` 返回 `Promise`;`getChoice` 返回 `Promise`;`Choices` 的 `choices` 是 `[key, text]` 数组、`maxHeight` 超过时分页、`selected` 默认项;正文标题用 `Choices(选项框)`,并写明「用户习惯叫 `ChoicesBox`,**源码导出名是 `Choices` / `ChoicesUI`**」(避免读者按 `ChoicesBox` 去找 import);**只按接口讲,不描述实现**。 +`## 边界与注意`:`Scroll` 里包一层容器会让虚拟滚动失效;`List` 的选中不要手动去改列表数据;`Page` 的索引从 0 开始;`Choices` / `ConfirmBox` 是一次性 UI,不要在它们上面再叠自己的面板而不处理返回值。 + +**(3)两个 demo**:`builtin-text-demo.tsx`(`BuiltinTextDemo`)展示 `TextContent` 打字机 + 「立即显示全部」按钮 + 一个 `Input`(`v-model:value`);`builtin-list-demo.tsx`(`BuiltinListDemo`)展示 `List` 选中 + `Page` 分页 + `Scroll` 平铺列表 + `Selection` 光标。两个 demo 可以静态 import 内置组件(demo 由 loader 动态 import,SSR 安全),但不得写 DOM 属性;若某个内置组件在文档站跑不起来,保留代码块与页面,不删内容,并在正文用一句话说明该示例依赖完整客户端环境。 + +**(4)侧边栏**:追加 `{ text: '内置组件与 UI 系统', collapsed: false, items: [...] }`,先放 `/advanced/ii/ui/builtin-text-and-input` 与 `/advanced/ii/ui/builtin-list-and-containers`。只做加法。 + +**(5)回填第 6 篇与第 16 篇的跨页链接**:本任务创建了第 17 篇 `builtin-text-and-input.md`,把两处纯文本前瞻引用改成链接—— +- `docs/advanced/ii/ui/text.md`:把纯文本「第 17 篇『内置组件:文本与输入』」改成 `[第 17 篇「内置组件:文本与输入」](./builtin-text-and-input.md)`; +- `docs/advanced/ii/ui/slots-and-attrs.md`:把纯文本「第 17 篇的内置组件」改成 `[第 17 篇「内置组件:文本与输入」](./builtin-text-and-input.md)`。 + +**只改这两处链接,不改任何文字语义、不动这两页其它内容。** + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/builtin-text-and-input.md":["TextContent","Textbox","Input","InputBox","getInput","getInputNumber","autoHeight","v-model:value","width"],"docs/advanced/ii/ui/builtin-list-and-containers.md":["List","ListPage","Page","Scroll","Selection","Choices","ChoicesBox","ChoicesUI","ConfirmBox","getChoice","getConfirm","v-model:selected","scrollTo"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const l=rd("docs/advanced/ii/ui/builtin-list-and-containers.md");if(l.indexOf("直接子元素")<0)bad.push("LIST-NO-SCROLL-NOTE");if(l.indexOf("container-custom")<0)bad.push("LIST-NO-CONTAINER-NAME");["builtin-text-demo.tsx","builtin-list-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+f);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/builtin-text-and-input","/advanced/ii/ui/builtin-list-and-containers","/advanced/ii/ui/slots-and-attrs","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});const b6=rd("docs/advanced/ii/ui/text.md");const b16=rd("docs/advanced/ii/ui/slots-and-attrs.md");if(b6.indexOf("](./builtin-text-and-input.md)")<0)bad.push("BACKFILL-P6");if(b16.indexOf("](./builtin-text-and-input.md)")<0)bad.push("BACKFILL-P16");if(cfg.indexOf("内置组件与 UI 系统")<0)bad.push("CFG-NO-PART4");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK' + non-zero exit, or output contains "NO-CONFIRM-10-46", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "LIST-NO-", "CRLF:", "NO-DEMO", "DEMO-", "BACKFILL-P", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK" + + NOTES 追加 10-46 命名确认与哈希比对;文本 / 输入篇含 `TextContent` / `Textbox` / `Input` / `InputBox` 与 `getInput` / `getInputNumber` / `autoHeight` / `v-model:value`;列表 / 容器篇含 `List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices`(并注明 `ChoicesBox` 是俗称、源码导出名是 `Choices` / `ChoicesUI`)/ `ConfirmBox` / `getChoice` / `getConfirm` / `v-model:selected` / `scrollTo`,并写明 `Scroll` 只对直接子元素生效与 `container-custom` 写法;两篇单 H1、有边界节、CRLF、无被禁写法;两个 demo 默认导出且无 DOM 属性;第 6 篇(`text.md`)与第 16 篇(`slots-and-attrs.md`)里对第 17 篇的纯文本前瞻引用已回填为 `./builtin-text-and-input.md` 链接且这两页其它内容未变;侧边栏新增「内置组件与 UI 系统」两条且既有条目未丢;构建 green、无 dead link。 + 内置组件两篇与两个 demo 完成,`Choices` 已按接口写入。 + + + + Task 2: UIController 与 UI 栈 / 修改与替换内置 UI 两篇 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/.vitepress/components/demos/ui/controller-demo.tsx, docs/.vitepress/components/demos/ui/strategy-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-46):可以执行`;Task 1 两篇与「内置组件与 UI 系统」分组已存在且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 19、20 篇;UI System 全节;Open Questions Q5)、packages/system/src/ui/controller.ts(`open` / `close` / `closeAll` / `hide` / `show` / `keep` / `setBackground` / `lastOnly` / `showAll` / `showCustom` / `render`)、ui.ts(`GameUI` 与全局表现状)、instance.ts、container.tsx、types.ts、packages-user/client-modules/src/ui/func.ts、packages-user/client-modules/src/client.ts:101-105、src/client/ui/title.tsx:214、233(场景 UI 打开主场景)、docs/.vitepress/components/demos/uiSystem.vue(POC 的控制器用法) + 写两篇正文与两个 demo。 + +**(1)`ui-controller-and-stack.md`(第 19 篇)**:先给系统模型(D-82):四层——声明(把名字和组件绑在一起)、控制(管栈、背景、显示策略)、实例(一次打开产生的 key / 绑定参数 / 隐藏状态)、显示(把背景与栈映射成组件树)。然后: +- 栈:`stack` 是打开顺序;`controller.open(ui, vBind)` 入栈并激活;`controller.close(instance)` 按策略出栈;`controller.closeAll()` 清空或按 UI 清理;`controller.hide(instance)` / `controller.show(instance)` 只改实例可见性、不动栈。 +- 显示策略:默认「只显示最后一个」;`lastOnly` / `showAll` / `showCustom` 的差别;**明确在栈模式下关闭某个 UI 会连带关闭它之后打开的 UI**,而 `showAll` 默认不连带。给一张对照表。 +- 背景:`setBackground` 放一个始终存在的背景实例;`hideBackground` / `showBackground` / `showingBack`。 +- `keep`:关闭当前、打开下一个的间隙保持背景,避免闪烁;给 `const keep = controller.keep(); controller.close(a); controller.open(b, {}); keep.safelyUnload()` 的完整片段,并说明 `safelyUnload` 与 `unload` 的区别。 +- 场景 UI 与主 UI:`sceneController`(加载、标题、主场景)与 `mainUIController`(游戏内主 UI 栈)的区别与打开位置;主 UI 栈由主场景的容器负责显示,作者不需要关心渲染位置。 +- 基础 props 注入:`setPropsBaseCreator` 决定每个实例能拿到哪些基础参数(`instance` / `controller` / `state`);作者 UI 的 Props 必须 `extends IGameUIPropsBase, DefaultProps`。 +- 明确一句:当前没有全局 UI 注册 / 覆盖入口,`GameUI` 的全局表不会被自动填充,因此不要指望按名字取到内置 UI。 +`## 边界与注意`:`close` 在栈模式下会连带关闭上层;`alwaysShow` 的背景不会被 `hide` 关掉;`active` / `showBack` 是引用值,在 TSX 里要 `.value`;频繁 `open` / `close` 会重建组件。 + +**(2)`replace-builtin-ui.md`(第 20 篇)**:先把「内置 UI」定义清楚——指 `src/client/ui` 里的设置、存档、工具栏等**应用层 UI**,不是泛指内置组件。然后按用户 Task 0 的选择讲三种改法(默认只讲三种,不复制源码): +1. 打开处替换:找到调用 `open` 的那一行,换成自己的 UI;给前后对照片段。 +2. 包装组件:写一个组件包住原 UI,转发 props / slots / emits,只改需要改的部分;重点讲「保持对外契约不变」,这样调用方不用改。 +3. 改显示策略或背景:用 `showAll` / `lastOnly` / `showCustom` 与 `setBackground` 改变叠放与背景,而不是改原组件。 +再给一张「改法 / 适用场景 / 代价」表,并明确:不要去改 `packages` / `packages-user` 里的内置实现;当前没有全局替换接口。 +`## 边界与注意`:包装组件要转发全部 props,漏一个就会出现「某些设置不生效」;emit 名称必须原样转发;换打开处要同时检查 `keep` 的配对;改显示策略会影响同栈的其它 UI。 + +**(3)两个 demo**:`controller-demo.tsx`(`ControllerDemo`)自建一个最小 UI 栈:`new UIController()` + `setPropsBaseCreator` + 一个最小 `GameUI` + 打开 / 关闭按钮,并把栈长度与激活状态显示出来;`strategy-demo.tsx`(`StrategyDemo`)并排对比「只显示最后一个」与「显示全部」两种策略的叠放效果。都默认导出;可以在 demo 内静态 import `@motajs/system`(loader 动态 import,SSR 安全);不写 DOM 属性。 + +**(4)侧边栏**:在「内置组件与 UI 系统」分组追加 `/advanced/ii/ui/ui-controller-and-stack` 与 `/advanced/ii/ui/replace-builtin-ui`。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const need={"docs/advanced/ii/ui/ui-controller-and-stack.md":["open(","close(","closeAll","hide(","show(","lastOnly","showAll","showCustom","setBackground","keep(","safelyUnload","active","showBack","sceneController","mainUIController","setPropsBaseCreator","IGameUIPropsBase"],"docs/advanced/ii/ui/replace-builtin-ui.md":["src/client/ui","open(","showAll","setBackground","包装","props","emits","packages"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const r20=rd("docs/advanced/ii/ui/replace-builtin-ui.md");if(r20.indexOf("没有全局")<0&&r20.indexOf("没有全局替换")<0)bad.push("R20-NO-GLOBAL-NOTE");["controller-demo.tsx","strategy-demo.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+f);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/ui-controller-and-stack","/advanced/ii/ui/replace-builtin-ui","/advanced/ii/ui/builtin-list-and-containers","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "NO-CONFIRM-10-46", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "R20-", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK" + + UIController 篇含四层模型、栈与背景、`active` / `showBack`、全部 `open` / `close` / 策略 / `keep` 接口、场景 UI 与主 UI 的区别、`setPropsBaseCreator` 与 Props 基类,并明确没有全局注册 / 覆盖入口;替换篇把「内置 UI」定义为 `src/client/ui` 的应用层 UI,讲三种改法且不教改 `packages`;两篇单 H1、有边界节、CRLF、接 live、无被禁写法(含 `GameUI.get`);两个 demo 默认导出且无 DOM 属性;侧边栏补两条且既有条目未丢;构建 green、无 dead link。 + UIController 篇与替换内置 UI 篇完成。 + + + + Task 3: UI 系统性能与注意事项 + perf demo + 侧边栏 + docs/advanced/ii/ui/ui-performance.md, docs/.vitepress/components/demos/ui/perf-demo.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-46):可以执行`;Task 2 两篇已落盘且构建 green;第 8 / 12 篇的 `hidden` 口径已验收。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 21 篇;Performance 全节;旧性能文档可用结论)、packages/render/src/core/render.ts:182-186(脏更新)、packages/render/src/core/item.ts:229-244(脏标记冒泡)、packages/render-vue/src/tag.ts:103-115(缓存默认值)、packages/system/src/ui/container.tsx:14-47(每次渲染都会调用 creator)、packages/system/src/ui/controller.ts(`keep` / `active` / `showBack`)、docs/advanced/ii/ui/layer-transform-performance.md 与 conditional-and-list-rendering.md(本批要收口的 `hidden` 口径) + 写性能篇与 demo,并登记侧边栏。 + +**`ui-performance.md`(第 21 篇)**:开头先划边界——本篇讲 **UI 系统**的性能(缓存、显示开关、组件粒度、栈与背景),引擎级性能(渲染管线、批处理)属于高级 III,给跨页链接。然后按「先省掉不该做的事 → 再减少重绘 → 再减少重建」的顺序组织: +1. **显示开关**:重申 `hidden` 优先——不显示、不交互、保留元素与状态、跳过绘制与命中;三元只在必须真正不存在 / 需要重置状态或生命周期 / 子树很重且长期不用 / 必须彻底摘掉事件监听或不能接受隐藏元素继续占内存时用(与第 8、12 篇逐字同义)。给一张判定表。 +2. **缓存**:哪些标签默认缓存、哪些默认不缓存;`nocache` 优先于 `cache`;简单文字不要开缓存,复杂且不常变的图形可以试;说明元素的脏标记会向上冒泡,父级已脏时提前返回。 +3. **画面质量**:`hd` / `anti` / `noanti`;像素图建议关高清与抗锯齿(与第 7 篇一致,不重复展开)。 +4. **列表与分页**:大量列表优先 `Scroll`(只对直接子元素生效),分页优先 `Page`;`.map()` 与 `key` 按 `dev.md:122`,不把 `key` 当性能开关。 +5. **组件粒度**:把高频更新与低频更新拆到不同容器里,但不要嵌套过深;一次状态变化影响的组件越少越好。 +6. **UI 栈**:能用 `hide` / `show` 就不重建;`setBackground` 把稳定背景移出栈;`keep` 只在「关一个开一个」的间隙用;栈越深,每次渲染的映射与隐藏切换越多。 +7. **基础 props**:每个实例渲染时都会走一次基础参数创建,自定义 creator 里不要做重活。 +8. 末尾给一张「症状 → 先查什么 → 怎么改」的排查表(卡顿、切页闪烁、频繁重建、列表滚动掉帧)。 +`## 边界与注意`:缓存不是越多越好;`hidden` 的子树仍在内存里;`keep` 用完必须卸载;性能建议先测再改,不要凭感觉堆 `nocache`。 + +**`perf-demo.tsx`**(`PerfDemo`):一个切换 `hidden` / `cache` 的小面板,并把 `active` / `showBack` 的状态显示出来(用最小控制器或直接传静态值,二者择一,不引入引擎初始化)。默认导出、无 DOM 属性。 + +**侧边栏**:在「内置组件与 UI 系统」分组追加 `/advanced/ii/ui/ui-performance`。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const f="docs/advanced/ii/ui/ui-performance.md";if(!fs.existsSync(f))bad.push("MISSING:"+f);else{const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1");if(s.indexOf("## 边界与注意")<0)bad.push("EDGE");forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+r)});["hidden","不显示、不交互","cache","nocache","hd","noanti","Scroll","Page","key","keep","setBackground","createPropsBase","高级 III"].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY");if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER");if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF");const L=rd("docs/advanced/ii/ui/layer-transform-performance.md");const C=rd("docs/advanced/ii/ui/conditional-and-list-rendering.md");[L,C].forEach(function(t,i){if(t.indexOf("不显示、不交互")<0)bad.push("HIDDEN-DRIFT:"+i)})}const d="docs/.vitepress/components/demos/ui/perf-demo.tsx";if(!fs.existsSync(d))bad.push("NO-DEMO");else{const s=rd(d);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT");if(/style=|class=/.test(s))bad.push("DEMO-DOM");if(s.indexOf("hidden")<0)bad.push("DEMO-NO-HIDDEN")}const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/ui-performance","/advanced/ii/ui/ui-controller-and-stack","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK' + non-zero exit, or output contains "NO-CONFIRM-10-46", "PAGE-ASSERT", "MISSING:", "H1", "EDGE", "FORBID:", "KEY:", "HIDDEN-DRIFT", "CLIENTONLY", "LOADER", "CRLF", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK" + + 性能篇覆盖 `hidden` 优先、缓存与 `nocache`、`hd` / `anti`、`Scroll` / `Page`、`key` 规则、组件粒度、`keep` / `setBackground`、`createPropsBase`,并与高级 III 划清边界;`hidden` 表述与第 8 / 12 篇一致;单 H1、有边界节、CRLF、接 live、无被禁写法;demo 合规;侧边栏补一条且既有条目未丢;构建 green、无 dead link。 + 性能篇与 perf demo 完成,Part 4 五篇齐备。 + + + + Task 4: 六类门禁收口 + NOTES 记录 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1..3 的 5 篇与 5 个 demo 已落盘、侧边栏 5 条齐全、构建 green。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区)、docs/advanced/ii/ui/(本批 5 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts + 按固定顺序跑门禁并记录: + +1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。 +2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning。 +3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。 +4. 静态断言:5 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live / 5 个 demo 默认导出且无 DOM 属性 / 侧边栏 21 条(本批 5 + 前三批 16)齐全 / 既有条目与高级 III 未丢 / 三篇(第 8、12、21)的 `hidden` 表述都含「不显示、不交互」。 +5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。 +6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-46 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 5 篇与 5 个 demo 清单。 +7. 交叉一致性:第 19 篇「没有全局注册 / 覆盖入口」与第 20 篇「没有全局替换接口」表述一致;第 17 篇 `v-model:value`、第 18 篇 `v-model:selected` 与第 13 篇的 `v-model:xxx` 口径一致。写进该小节。 + +本任务不改正文语义。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-46):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-46' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const md=["builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+m);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["builtin-text-demo","builtin-list-demo","controller-demo","strategy-demo","perf-demo"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+m);if(/from\s+[\x22\x27]@user\/(?!client-base[\x22\x27])/.test(s))bad.push("DEMO-USER:"+m)});const cfg=rd("docs/.vitepress/config.ts");const links=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs","builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance"];links.forEach(function(m){if(cfg.indexOf("/advanced/ii/ui/"+m)<0)bad.push("CFG:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");["layer-transform-performance","conditional-and-list-rendering","ui-performance"].forEach(function(m){const s=rd("docs/advanced/ii/ui/"+m+".md");if(s.indexOf("不显示、不交互")<0)bad.push("HIDDEN-DRIFT:"+m)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-46 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; 'T4-OK' + non-zero exit, or output contains "NO-CONFIRM-10-46", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "HIDDEN-DRIFT", "NOTES-NO-"; or output lacks "T4-OK" + + prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(5 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 5 个 demo 合规 / 侧边栏 21 条齐全 / 第 8、12、21 篇 `hidden` 表述一致);构建 green、无 dead link;NOTES 有 `### 10-46 门禁` 且含类型检查与引擎报错摘要。 + Part 4 五篇 5 demo 通过六类门禁并已记录。 + + + + Task 5: 用户目视 5 个 live 并抽查五篇正文 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录)。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录)、docs/advanced/ii/ui/(本批 5 篇)、docs/.vitepress/components/demos/ui/(本批 5 个 demo) + 请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 5 篇,逐条确认:①侧边栏「内置组件与 UI 系统」5 条可点开;②文本 / 输入篇 live 的打字机能逐字显示、「立即显示全部」生效、输入框能输入;③列表 / 容器篇 live 的选中、分页、滚动、光标正常;④UI 栈篇 live 能打开 / 关闭最小 UI,栈长度与激活状态随之变化;⑤策略篇 live 能看出「只显示最后一个」与「显示全部」的叠放差别;⑥性能篇 live 能切换 `hidden` / `cache` 并显示状态;⑦抽查第 19 / 20 篇:都写明「没有全局注册 / 覆盖入口」,替换只发生在打开处或包装层;⑧抽查第 18 篇:`Choices` 已按接口写入并注明 `ChoicesBox` 别名。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-46):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后复验。只有用户明确通过才可进入 10-47。 + 5 篇正文与 5 个 live demo,构建产物可在本地预览。 + 按上面①–⑧逐条检查;重点看内置组件 live 是否真实可用、栈与策略的差别是否看得出来、`Choices` 是否按接口写。 + 若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。 + 用户明确回复 live 与正文均通过,且 NOTES 有人工验证标记与用户原文;否则问题清单已记录并进入修复循环。 + + 用户已明确确认 5 篇可读、5 个 live 正常、第 19 / 20 篇口径一致,并已把结论记入 NOTES。 + + 用户人工验证结论已记录。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 构建期(SSR)→ live demo(含内置组件) | 内置组件可能间接依赖浏览器 API,因此 demo 必须由 loader 动态 import | +| demo → 输入框 | `Input` 会在 `document.body` 创建真实输入元素;demo 只做本地输入,不持久化、不发请求 | +| 文档 → 读者(替换内置 UI) | 建议路径只有「打开处替换 / 包装 / 显示策略」,避免读者去改内置包 | +| 侧边栏 → 页面 | 每条 link 必须对应已存在页面 | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-142 | Denial of Service(构建不可用) | 内置组件 demo 进入 SSR | high | mitigate | demo 由 loader 动态 import、`` 包裹;构建门禁必须 `build complete` | +| T-10-143 | Tampering | 侧边栏登记 | medium | mitigate | 登记与建页同任务;静态断言复核 21 条链接与既有条目、高级 III 未丢 | +| T-10-144 | Information Disclosure | `choices.tsx` 实现细节被写入正文 | medium | mitigate | 只读 props / emits / 函数签名;正文不描述实现;工作树哈希变化即停下问用户 | +| T-10-145 | Elevation of Privilege | 教读者改 `packages` 内置实现 | medium | mitigate | 替换篇只讲三种应用层改法,并明确当前没有全局替换接口 | +| T-10-146 | Repudiation | 命名与门禁无据可查 | medium | mitigate | NOTES 追加式记录;每个 auto 任务复检 `用户确认(10-46):可以执行` | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 | + + + +- 确认门禁:NOTES 含 `用户确认(10-46):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-46):通过` + `用户原文:`,无 `状态:待处理`。 +- 内容门禁:5 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性、`GameUI.get`。 +- 契约门禁:`TextContent` 的 `width` 必填与 `autoHeight`、`Input` 的 `v-model:value`、`List` 的 `v-model:selected`、`Scroll` 只对直接子元素生效、`Choices` 按接口写且有「`ChoicesBox` 是俗称、源码导出名 `Choices` / `ChoicesUI`」的说明。 +- 一致性门禁:第 8 / 12 / 21 篇的 `hidden` 表述一致;第 19 / 20 篇「没有全局注册 / 覆盖入口」一致。 +- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。 +- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前三批已验收内容;未改 `10-01`..`10-45` 计划;未 commit;ROADMAP / STATE 本计划不改。 + + + +- 读者能用现成组件拼出文本、输入、列表、分页、滚动与一次性选择框,并知道 `Choices` 怎么用。 +- 读者能接 UI 栈、用背景与 `keep` 控制叠放与闪烁,并知道替换内置 UI 只有三种应用层做法。 +- 性能篇成为整批的唯一汇总口径,且与第 8 / 12 篇不冲突。 +- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-46-SUMMARY.md` when done + diff --git a/.planning/phases/10-docs-restructure/10-46-SUMMARY.md b/.planning/phases/10-docs-restructure/10-46-SUMMARY.md new file mode 100644 index 0000000..113c21d --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-46-SUMMARY.md @@ -0,0 +1,202 @@ +--- +phase: 10-docs-restructure +plan: 46 +subsystem: docs +tags: [vitepress, tsx, ui, builtin-components, ui-stack, performance] + +requires: + - phase: 10-docs-restructure + provides: 10-45 的 props / 组件 / slots 四篇正文、4 个 live demo、侧边栏「组件化」分组 +provides: + - Part 4 五篇(内置组件文本/输入、内置组件列表/容器、UIController 与 UI 栈、修改/替换内置 UI、UI 系统性能) + - 5 个 live demo 与侧边栏「内置组件与 UI 系统」分组 + - 第 6 / 16 篇对第 17 篇的跨页链接回填 +affects: [10-47, 10-48] + +actuals: + tokens: 29000 + tasks: 5 + commits: 0 + +tech-stack: + added: [] + patterns: + - 内置组件按公开契约使用,属性名保持 camelCase + - v-model:value / v-model:selected 双向绑定口径与第 13 篇一致 + - 四层 UI 模型、栈与背景、lastOnly / showAll / showCustom + - keep 防闪烁,safelyUnload 只在栈空时关背景 + - hidden 优先、缓存只给稳定子树、createPropsBase 不做重活 + +key-files: + created: + - docs/advanced/ii/ui/builtin-text-and-input.md + - docs/advanced/ii/ui/builtin-list-and-containers.md + - docs/advanced/ii/ui/ui-controller-and-stack.md + - docs/advanced/ii/ui/replace-builtin-ui.md + - docs/advanced/ii/ui/ui-performance.md + - docs/.vitepress/components/demos/ui/builtin-text-demo.tsx + - docs/.vitepress/components/demos/ui/builtin-list-demo.tsx + - docs/.vitepress/components/demos/ui/controller-demo.tsx + - docs/.vitepress/components/demos/ui/strategy-demo.tsx + - docs/.vitepress/components/demos/ui/perf-demo.tsx + modified: + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/text.md + - docs/advanced/ii/ui/slots-and-attrs.md + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + +key-decisions: + - "内置组件篇用「示例为主 + 常用项表」,但 TextContent 的 width 必填、autoHeight、Input 的 v-model:value、List 的 v-model:selected、Scroll 只对直接子元素生效写全" + - "第 20 篇只讲打开处替换 / 包装组件 / 显示策略与背景三种改法,不复制源码" + - "Choices 正文标题用 Choices(选项框),并注明 ChoicesBox 是俗称、源码导出名是 Choices / ChoicesUI" + - "文档站无法 import client-base 内置组件时,正文保留真实代码块,live 用等价元素演示并明确说明" + +requirements-completed: [] + +coverage: + - id: D1 + description: "内置组件:文本与输入篇 + builtin-text live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "打字机、立即显示全部与输入框交互需要人工目视" + - id: D2 + description: "内置组件:列表与容器篇 + builtin-list live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "List / Page / Scroll / Selection 的交互与平铺要求需要人工确认" + - id: D3 + description: "UIController 与 UI 栈篇 + controller live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "打开 / 关闭、栈长度与 active 状态需要人工操作确认" + - id: D4 + description: "修改 / 替换内置 UI 篇 + strategy live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "lastOnly 与 showAll 的叠放差别需要人工目视" + - id: D5 + description: "UI 系统性能与注意事项篇 + perf live" + verification: + - kind: automated_ui + ref: "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" + status: pass + human_judgment: true + rationale: "hidden / cache 切换与 active / showBack 状态显示需要人工确认" + - id: D6 + description: "第 6 / 16 篇跨页链接回填与侧边栏 5 条" + verification: + - kind: automated_ui + ref: "静态断言:5 篇单 H1 / 边界节 / 无被禁写法 / 21 条链接 / 回填链接" + status: pass + human_judgment: true + rationale: "链接位置与侧边栏显示名需要人工抽查" + +duration: 24min +completed: 2026-10-31 +status: complete +--- + +# Phase 10 Plan 46: 内置组件与 UI 系统 Summary + +**Part 4 五篇与五个 live 落地:内置组件按公开契约讲、UI 栈讲清四层模型与 keep、替换只走三种应用层改法、性能篇收口 hidden 口径** + +## Performance + +- **Duration:** 24 min +- **Started:** 2026-10-31 18:28(本地时间) +- **Completed:** 2026-10-31 18:52(本地时间) +- **Tasks:** 5(Task 0 记录 + Task 1..4;Task 5 live 人工验证按用户要求留待最终审阅) +- **Files modified:** 14 + +## Accomplishments + +- 新增 `builtin-text-and-input.md`:`TextContent` / `Textbox` / `Input` / `InputBox`,含打字机、`v-model:value`、`getInput` / `getInputNumber`。 +- 新增 `builtin-list-and-containers.md`:`List` / `ListPage` / `Page` / `Scroll` / `Selection` / `Choices` / `ConfirmBox`,讲明 `Scroll` 只对直接子元素生效与 `ChoicesBox` 别名。 +- 新增 `ui-controller-and-stack.md`:四层模型、栈与背景、`lastOnly` / `showAll` / `showCustom`、`keep`、场景 UI 与主 UI、基础 props 注入。 +- 新增 `replace-builtin-ui.md`:内置 UI 定义、打开处替换 / 包装组件 / 显示策略与背景三种改法,明确没有全局替换接口。 +- 新增 `ui-performance.md`:`hidden` 优先、缓存、HD / 抗锯齿、列表、组件粒度、UI 栈、`createPropsBase` 与排查表。 +- 侧边栏新增「内置组件与 UI 系统」5 条;第 6 / 16 篇对第 17 篇的纯文本前瞻引用回填为链接。 +- 六类门禁全绿:prettier、ESLint、docs 类型、静态断言、全量构建。 + +## Files Created/Modified + +- `docs/advanced/ii/ui/builtin-text-and-input.md` - 文本、输入、Textbox、InputBox +- `docs/advanced/ii/ui/builtin-list-and-containers.md` - 列表、分页、滚动、选中框、一次性选择框 +- `docs/advanced/ii/ui/ui-controller-and-stack.md` - UIController 四层模型与 UI 栈 +- `docs/advanced/ii/ui/replace-builtin-ui.md` - 修改 / 替换内置 UI 的三种做法 +- `docs/advanced/ii/ui/ui-performance.md` - UI 系统性能与注意事项 +- `docs/.vitepress/components/demos/ui/*.tsx` - 5 个 live demo(builtin-text / builtin-list / controller / strategy / perf) +- `docs/.vitepress/config.ts` - 「内置组件与 UI 系统」新增 5 条 +- `docs/advanced/ii/ui/text.md` - 第 17 篇链接回填 +- `docs/advanced/ii/ui/slots-and-attrs.md` - 第 17 篇链接回填 +- `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md` - 10-46 命名确认、哈希复核、门禁与待审记录 + +## Decisions Made + +- 契约写法采用「示例为主 + 常用项表」,关键约束(`width`、`autoHeight`、`v-model:value`、`v-model:selected`、`Scroll` 直接子元素)全部写全。 +- 第 20 篇不复制内置源码,只讲打开处替换 / 包装 / 显示策略与背景。 +- `Choices` 按接口讲,正文标题用 `Choices(选项框)`,并注明 `ChoicesBox` 只是俗称。 +- 文档站无法 import `client-base` 内置组件时,正文保留真实代码块,live 用等价元素演示并在「运行效果」说明。 + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] 内置组件无法在文档站静态 import,live 改为等价元素演示** +- **Found during:** Task 1 +- **Issue:** 导入 `@user/client-base` 触发 `Could not resolve "../renderer" from "packages-user/client-base/src/elements/index.ts"`;`packages-user/client-base/src/renderer` 在当前工作树不存在(`elements/index.ts` 与 `components/misc.tsx` 的 `../renderer` 引用未解析,属既有中间态,非本轮引入)。 +- **Fix:** 正文保留真实内置组件代码块;`builtin-text-demo.tsx` / `builtin-list-demo.tsx` 用等价渲染元素演示交互,并在正文「运行效果」写明「文档站缺少完整客户端环境,示例用等价元素演示」。 +- **Files modified:** `docs/.vitepress/components/demos/ui/builtin-text-demo.tsx`、`docs/.vitepress/components/demos/ui/builtin-list-demo.tsx`、两篇正文的「运行效果」段。 +- **Commit:** 无(按用户要求不 commit)。 + +### Execution Environment Adaptation + +- PowerShell 5.1 会把 `node -e` 的内嵌引号剥离,计划里的 `` 片段不能原样执行;改为把同一段 JS 提取到临时文件后运行,断言内容未变。 +- PowerShell 把构建的标准错误输出当作终止错误;按退出码、`build complete` 与 dead link 判定,构建结果为 green。 + +## Issues Encountered + +- `packages-user/client-base/src/renderer` 缺失导致内置组件无法进入文档站点构建;未修改任何源码,按计划允许的 fallback 处理。 +- 既有引擎类型报错 11 条(`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条),非本轮引入,保持不动。 + +## Gates + +| 门禁 | 结果 | +|------|------| +| prettier `--write` / `--check` | 通过,`All matched files use Prettier code style!` | +| ESLint | 0 error / 0 warning | +| `vue-tsc -p docs/tsconfig.json` | `docs/` 路径 0 报错;既有引擎报错 11 条(非本轮引入) | +| 静态断言 | `STATIC-OK`(5 篇 + 5 demo + 21 条侧边栏 + 回填链接 + hidden 一致) | +| 全量构建 | green,`build complete in 22.06s.`,无 dead link | + +## Known Stubs + +- `builtin-text-demo.tsx` / `builtin-list-demo.tsx` 用等价元素而不是真实内置组件(原因见上)。正文已说明;真实组件需在完整客户端环境验证,留待 10-48 读者/用户审阅。 + +## Pending + +- Task 5 live 目视与正文抽查:`live 人工验证(10-46):待最终人工审阅`。本轮未写「用户人工验证:通过」。 + +## Next Phase Readiness + +- 10-47 可以直接复用本批的内置组件契约、UI 栈口径与性能结论。 +- 10-48 审阅时需重点确认:内置组件 live 的等价演示是否可接受、`Choices` 别名说明是否清楚、第 19 / 20 篇「没有全局入口」是否一致。 + +## Self-Check: PASSED + +- 5 篇正文存在,单 H1、`## 边界与注意`、CRLF。 +- 5 个 demo 存在,默认导出、无 DOM 属性。 +- 侧边栏 5 条与前三批 16 条齐全。 +- 门禁全绿;本轮未 commit。 diff --git a/.planning/phases/10-docs-restructure/10-47-PLAN.md b/.planning/phases/10-docs-restructure/10-47-PLAN.md new file mode 100644 index 0000000..eaed1cb --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-47-PLAN.md @@ -0,0 +1,332 @@ +--- +phase: 10-docs-restructure +plan: 47 +type: execute +wave: 5 +depends_on: + - 10-46 +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/.vitepress/config.ts + - docs/advanced/ii/ui/inventory-example-1-skeleton.md + - docs/advanced/ii/ui/inventory-example-2-grid.md + - docs/advanced/ii/ui/inventory-example-3-detail.md + - docs/advanced/ii/ui/inventory-example-4-scroll.md + - docs/advanced/ii/ui/inventory-example-5-state.md + - docs/advanced/ii/ui/inventory-example-6-animation-and-register.md + - docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx + - docs/.vitepress/components/demos/ui/inventory-2-grid.tsx + - docs/.vitepress/components/demos/ui/inventory-3-detail.tsx + - docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx + - docs/.vitepress/components/demos/ui/inventory-5-state.tsx + - docs/.vitepress/components/demos/ui/inventory-6-full.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 84000 + raw_tokens: 52000 + tasks: 6 + confidence: low +must_haves: + truths: + - "完整示例六篇(目标与骨架 / 道具网格 / 详情区 / 滚动与列表 / 交互与状态 / 动画、拆分与注册)按顺序递增,每篇只在上一步基础上加一小段代码,不重复贴整份实现" + - "每篇配一个 live 检查点(6 个 `.tsx` demo),页面用 `<ClientOnly>` + `() => import('...')`;6 个 demo 默认导出、无 DOM 属性,只 import vue 与元素标签,**允许但不要求** `@motajs/system` 的 `GameUI` / `UIController`,除此之外不得 import 其它 `@motajs/*` / `@user/*`;文档正文不展示 demo 源码,只给正文代码块" + - "六篇的组件拆分从第一天定好并在后续只填内容:`InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar`;最终篇给出文件结构与 `GameUI` 注册、打开处替换" + - "面板 Props 一律 `extends IGameUIPropsBase, DefaultProps`、`props` 数组含 `controller` / `instance` / `state`;示例数据只用 `g-rect` / `g-rectr` / `text` 造假数据,不引入真实素材、不出现 Thumbnail / Tip、不出现 core 命名空间" + - "显示与列表口径与前面一致:频繁切换用 `hidden`,必须卸载 / 重置时才用三元;循环用 `.map()`,`key` 只在会重排 / 增删且需要保留身份时加" + - "交互篇只用手写按钮与 `useKey(...)!`(不配按键 live 可用按钮替代),状态用 `ref` / `computed` / `watch` 驱动;动画篇的 live 用 `requestAnimationFrame` 驱动并在 `onUnmounted` 取消(不在 live 里用返回 `ITransitionedController | null` 的渐变工具;正文若提及必须写明可空并做 null 判断)" + - "最终篇的 live 是完整背包面板:网格、详情、滚动、装备 / 使用、关闭、动画都能用;跑不起来不删内容,但要保留代码与说明" + - "侧边栏新增「完整示例」分组 6 条,只链接已存在页面;`pnpm docs:build` green、含 `build complete`、0 dead link" + - "`vue-tsc --noEmit -p docs/tsconfig.json` 中 `docs/` 路径 0 报错;prettier `--check` 通过;ESLint 0 error / 0 warning" + - "未改 `packages/` / `packages-user/` / `src/`、未改前四批已验收的 21 篇正文与 19 个 demo 的语义、未改 `10-01`..`10-46` 计划、未改既有 JSDoc/注释;不 commit" + artifacts: + - "docs/advanced/ii/ui/inventory-example-1-skeleton.md、inventory-example-2-grid.md、inventory-example-3-detail.md、inventory-example-4-scroll.md、inventory-example-5-state.md、inventory-example-6-animation-and-register.md" + - "docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx、inventory-2-grid.tsx、inventory-3-detail.tsx、inventory-4-scroll.tsx、inventory-5-state.tsx、inventory-6-full.tsx" + - "docs/.vitepress/config.ts(高级 II 子分组内新增「完整示例」分组 6 条)" + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-47 命名确认、门禁与人工验证记录)" + key_links: + - "六篇是同一个面板的六步:每一步的 live 必须是「上一步 + 本步新增」,读者按顺序看能对上;任何一步另起一套实现都会让读者无法对照" + - "第 22 篇的组件拆分决定第 23–27 篇的落点;第 27 篇的「拆分与注册」必须与第 22 篇的拆分一致,不能到结尾才换结构" + - "第 23 篇的 `ItemCell` props 写法必须复用第 13 篇;第 26 篇的 `useKey` 必须复用第 11 篇;第 27 篇的动画必须复用第 8 篇的 `alpha` / `scale` 与第 21 篇的性能口径" + - "第 27 篇的最终 live 是本批唯一的「完整面板」,也是 10-48 读者审阅的终点页;它必须能独立看懂,不依赖前五篇的 live" +--- + +> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。 + + +本计划 6 个任务、14 个 `files_modified`,超出默认上限,保持单计划: + +- 六篇分三个写作任务(2 + 2 + 2),每篇都带 live;门禁与人工验证独立。合并会让「6 篇 + 6 demo + 侧边栏 + 全量门禁」成为不可验证的大块。 +- 14 个文件里 6 篇正文、6 个 demo(每步一个,便于读者对照)、1 个侧边栏、1 个记录文件。demo 逐级递增是本批的核心价值(锁定决策 16「每步只加一小段代码 + 一个 live 检查点」),合并成 1 个 demo 会破坏检查点。 +- 六篇正文天然短于前几批(每篇只讲一个增量),但单个 demo 是完整可运行组件,代码量集中;拆成两个计划会让同一份面板在两次执行里重复读上下文。 + +不删内容:六篇正文、6 个 live、组件拆分、交互与按键、动画与注册、六类门禁、用户目视全部保留。 + + + +用六篇把一个完整可用的背包 / 装备面板写出来:目标与骨架 → 道具网格 → 详情区 → 滚动与列表 → 交互与状态 → 动画、拆分与注册。每一步只加一小段代码,并配一个 live 检查点。 + +Purpose: 这是整批的收束:读者在前面学到的模板、元素、响应式、事件、组件、内置组件、UI 栈,全部在同一个面板里汇合。它也是 10-48 独立读者审阅的终点页——如果读者能照着这六篇把面板跑起来,这批文档就成立了。 +Output: 6 篇正文、6 个逐级递增的 `.tsx` live demo、侧边栏「完整示例」分组、NOTES 追加记录。**不改源码、不改前四批已验收内容、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-46-PLAN.md +@docs/.vitepress/config.ts +@docs/advanced/ii/ui/ui-template.md +@docs/advanced/ii/ui/props.md +@docs/advanced/ii/ui/conditional-and-list-rendering.md +@docs/advanced/ii/ui/builtin-list-and-containers.md +@docs/advanced/ii/ui/ui-performance.md +@docs/.vitepress/components/demos/ui/conditional-demo.tsx + +**流程约定:** +- 只新增 / 修改本计划 `files_modified` 内文件;不改 `10-01`..`10-46` 计划;不重规划其它批次。 +- **Task 0 是硬关卡**:汇报六篇的增量划分、6 个 demo 的命名与目录、示例组件拆分与最终文件结构、示例技术选型(网格用容器还是 `Scroll`、滚动用 `Scroll` 还是 `ListPage`),等用户明确回复「可以执行」。 +- 六篇文件名与侧边栏名已在 10-43 命名总表确认;Task 0 复述确认值,若用户本轮改名先更新 NOTES 再落盘。 +- 改文件前声明「内联执行」还是「派发子代理执行」;正文 / demo / 文档一律派发子代理。 +- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit。 + +**本批写作硬规则(延续前四批):** 目标读者完全没写过 UI;示例一律 TSX;条件 `hidden` 或三元、循环 `.map()`、`key` 按 `dev.md:122`;属性 camelCase、容器自定义标签只用 `container-custom`;UI 的 Props 只能 `extends IGameUIPropsBase, DefaultProps`;`update:xxx` 只随 `v-model:xxx` 出现;组件内 `useKey(...)!`;不出现渲染器类名 / 渲染器初始化 / 标签注册 / core 命名空间;不含 Thumbnail 与 Tip;`icon` / `winskin` / `map-render` 只作占位;正文不写源码叙述与行号;代码块完整并带注释;单 H1 + `## 边界与注意`;CRLF;写完跑 prettier。 + +**参考文件与哈希:** 以 NOTES 的「参考清单哈希基线」为准;本计划涉及 `render/src/core/item.ts`、`render/src/core/container.ts`、`render-vue/src/props.ts`、`system/src/ui/controller.ts`、`system/src/ui/ui.ts`、`client-base/src/components/list.tsx`、`scroll.tsx`、`textbox.tsx`、`use/hotkey.ts`、`client-modules/src/render/use.ts`(渐变工具)。写作前逐条 `git hash-object` 比对;不一致或工作树被改即停下问用户。 + + + + + + Task 0: 汇报六步增量划分与最终文件结构,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、哈希基线)、10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 22–27 篇;Open Questions Q3)、docs/advanced/ii/ui/(前四批已落地篇目体例)、docs/.vitepress/config.ts + 向用户做四段汇报并停下等待: + +**要做什么**——用六篇写一个完整背包 / 装备面板,每篇只加一小段代码并配一个 live:①目标与骨架;②道具网格;③详情区;④滚动与列表;⑤交互与状态;⑥动画、拆分与注册。 + +**为什么**——前四批讲的是零件,这一批必须证明零件能拼成能用的面板;它同时是最后独立读者审阅的终点页,读者能不能照着跑起来,就是这批文档是否成立的判据。 + +**大致怎么做**——Task 1 写第 22、23 篇 + `inventory-1-skeleton` / `inventory-2-grid`;Task 2 写第 24、25 篇 + `inventory-3-detail` / `inventory-4-scroll`;Task 3 写第 26、27 篇 + `inventory-5-state` / `inventory-6-full`;Task 4 跑六类门禁并写 NOTES;Task 5 由用户目视 6 个 live 并抽查正文。 + +**影响范围**——新增 `docs/advanced/ii/ui/` 下 6 个 `.md` 与 `demos/ui/` 下 6 个 `.tsx`;追加侧边栏「完整示例」6 条;追加 NOTES。不动 `packages/`、`packages-user/`、`src/`、前四批已验收的 21 篇与 19 个 demo、ROADMAP / STATE。 + +**必须请用户确认:** + +| 项 | 建议值 | +|----|--------| +| 六篇文件名 | `inventory-example-1-skeleton.md` … `inventory-example-6-animation-and-register.md`(沿用 10-43 命名总表) | +| 六篇侧边栏名 | 示例(一)目标与骨架 / (二)道具网格 / (三)详情区 / (四)滚动与列表 / (五)交互与状态 / (六)动画、拆分与注册 | +| demo 目录与命名 | `demos/ui/inventory-1-skeleton.tsx`、`-2-grid.tsx`、`-3-detail.tsx`、`-4-scroll.tsx`、`-5-state.tsx`、`-6-full.tsx` | +| 面板尺寸 | 720×480 根容器 | +| 组件拆分(第 22 篇定下,后续不改) | `InventoryPanel` / `ItemGrid` / `ItemCell` / `ItemDetail` / `ActionBar` | +| 假数据 | 8–12 个道具,用 `g-rect` / `g-rectr` / `text` 绘制图标与名称,不引入真实素材 | +| 第 25 篇的滚动方案 | 先给 `Scroll` 平铺(推荐),末尾用一小节对比 `ListPage` 左列表右详情;两者都讲、不二选一 | +| 第 27 篇的注册与打开 | `export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)` + 打开处替换;不写全局注册表 | + +同时说明:六篇的 live 是**逐级递增的六个独立 demo**(不是同一个文件改六次),读者可以在每篇看到「到这一步为止」的样子;第 27 篇的 `inventory-6-full.tsx` 是最终版,也是 10-48 的审阅终点。**参考文件:`packages/render/src/core/item.ts`、`core/container.ts`、`render-vue/src/props.ts`、`system/src/ui/controller.ts`、`system/src/ui/ui.ts`、`client-base/src/components/list.tsx`、`scroll.tsx`、`textbox.tsx`、`use/hotkey.ts`、`client-modules/src/render/use.ts`(渐变工具);策略:写作前逐条 `git hash-object -- ` 与 NOTES 的哈希基线比对,任一变化或工作树被改即停下并问用户。** **未确认前不得修改任何文件**;本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释;不 commit。然后停下等待「可以执行」四个字。 + 尚无产物;本任务只汇报六步增量、demo 命名、组件拆分与示例技术选型。 + 确认:①是否同意六篇的增量划分与 6 个 demo 命名;②组件拆分五个名字是否可用;③第 25 篇「`Scroll` 为主 + `ListPage` 对比」是否可接受;④假数据与 720×480 尺寸是否可接受。 + 回复「可以执行」以继续(可同时给出命名或拆分调整);其它回复视为未批准。 + 用户已回复「可以执行」,且六篇命名、6 个 demo 命名、五个组件名、第 25 篇取舍、面板尺寸五项已确定。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,六篇与 6 个 demo 的命名、组件拆分、第 25 篇取舍已确定。 + + 用户回复「可以执行」且待定项已定。 + + + + Task 1: 示例(一)目标与骨架 /(二)道具网格 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx, docs/.vitepress/components/demos/ui/inventory-2-grid.tsx, docs/.vitepress/config.ts + 本计划的 Task 0 已记录 `用户确认(10-47):可以执行`;10-46 已验收且构建 green。本任务负责把该确认与用户原文追加进 NOTES。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 22、23 篇;Author Entry;UI System 的 open / close)、docs/advanced/ii/ui/ui-template.md(模板与 Props 基类)、docs/advanced/ii/ui/props.md(`ItemCell` props 写法)、docs/advanced/ii/ui/conditional-and-list-rendering.md(`.map()` 与 `key` 规则)、dev.md:116-123 + 先向 NOTES 末尾追加 `## 10-47 命名确认`(`用户确认(10-47):可以执行` + 下一行 `用户原文:` + 六篇与 6 个 demo 最终名 + 五个组件名 + 面板尺寸),并重跑本任务参考文件的哈希比对追加结果。然后写前两篇与两个 demo。 + +**(1)`inventory-example-1-skeleton.md`(第 22 篇)**:先给目标与最终效果(文字描述 + 一张结构示意,不用图片),再给**文件拆分**:`inventory-panel.tsx` 里放 `InventoryPanel`,同目录下 `item-grid.tsx` / `item-cell.tsx` / `item-detail.tsx` / `action-bar.tsx`(正文说明每个文件负责什么)。然后写骨架: +- 720×480 根容器 + `g-rectr` 背景 + 标题文字 + 关闭按钮(点击 `props.controller.close(props.instance)`)。 +- 内容区用两个占位容器(左网格 / 右详情),先各放一行 `text` 占位。 +- Props:`interface InventoryPanelProps extends IGameUIPropsBase, DefaultProps {}`,`props: ['controller', 'instance', 'state']`,`export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)`。 +- 打开处:给 `client.sceneController.open(InventoryUI, {})` 与 `props.controller.open(InventoryUI, {})` 两种调用。 +live 用 `inventory-1-skeleton`。`## 边界与注意`:骨架阶段就把组件拆分定下来,后面只填内容;不用真实素材,图标一律用图形 + 文字;关闭按钮必须在骨架阶段就能用,否则后面无法验证。 + +**(2)`inventory-example-2-grid.md`(第 23 篇)**:先给数据模型 `interface Item { id: string; name: string; count: number; desc: string }` 与一份假数据;再写 `ItemCell`(props:`item` / `selected` / `onSelect`,复用第 13 篇的写法),格子用 `g-rectr` + `text` 画名称与数量,选中用边框或 `alpha` 区分;再写 `ItemGrid` 用 `.map()` 排出 5 列网格,`selectedId` 用 `ref`。讲 `key`:这一页的列表顺序固定、格子无内部状态,**先不加** `key`,并说明原因;如果读者后续要增删,再加。live 用 `inventory-2-grid`(点击格子选中)。`## 边界与注意`:网格列宽与间距用常量算,不要手写每格坐标;选中态只由 `selectedId` 决定,不要在每个格子里各存一份;`.map()` 返回的每一项结构必须一致。 + +**(3)两个 demo**:`inventory-1-skeleton.tsx`(`Inventory1Skeleton`)只显示骨架与关闭按钮(关闭按钮在 live 里可改为显示一行提示,因为没有真实 UI 栈);`inventory-2-grid.tsx`(`Inventory2Grid`)在骨架上加网格与选中态。两者都要能被单独看懂,且第 2 个必须是「第 1 个 + 网格」。默认导出、只 import vue 与元素标签、无 DOM 属性。 + +**(4)侧边栏**:追加 `{ text: '完整示例', collapsed: false, items: [...] }`,先放两篇。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; if($np -notmatch '(?m)^用户原文:\S'){ Write-Error 'NO-CONFIRM-QUOTE' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/inventory-example-1-skeleton.md":["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar","IGameUIPropsBase","DefaultProps","GameUI","sceneController.open","720","480"],"docs/advanced/ii/ui/inventory-example-2-grid.md":["ItemCell","ItemGrid",".map(","selectedId","g-rectr","key"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["inventory-1-skeleton.tsx","inventory-2-grid.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-1-skeleton","/advanced/ii/ui/inventory-example-2-grid","/advanced/ii/ui/ui-performance","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(cfg.indexOf("完整示例")<0)bad.push("CFG-NO-PART5");if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T1-OK' + non-zero exit, or output contains "NO-CONFIRM-10-47", "NO-CONFIRM-QUOTE", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T1-OK" + + NOTES 追加 10-47 命名确认与哈希比对;骨架篇含五个组件名、Props 基类、`GameUI` 注册、两种打开处、720×480;网格篇含数据模型、`ItemCell` / `ItemGrid`、`.map(`、`selectedId`、`g-rectr` 与 `key` 取舍说明;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出且无 DOM 属性;侧边栏新增「完整示例」两条且既有条目未丢;构建 green、无 dead link。 + 示例(一)(二)完成,组件拆分与网格落地。 + + + + Task 2: 示例(三)详情区 /(四)滚动与列表 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/.vitepress/components/demos/ui/inventory-3-detail.tsx, docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-47):可以执行`;Task 1 两篇与「完整示例」分组已存在且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 24、25 篇;Built-in Components 的 `TextContent` / `Scroll` / `Page` / `ListPage`)、docs/advanced/ii/ui/builtin-text-and-input.md(`TextContent` 的 `width` 必填与 `autoHeight`)、docs/advanced/ii/ui/builtin-list-and-containers.md(`Scroll` 只对直接子元素生效、`ListPage` 用法)、docs/.vitepress/components/demos/ui/inventory-2-grid.tsx + 写第 24、25 篇与两个 demo,均在上一步之上增量。 + +**(1)`inventory-example-3-detail.md`(第 24 篇)**:写 `ItemDetail`: +- 布局:右侧面板的背景、名称、数量、描述区域;用 `g-rectr` / `text` 搭出来。 +- 用 `computed` 取当前道具:`const selectedItem = computed(() => items.value.find(v => v.id === selectedId.value))`(数据与选中态从父组件传入或提升到父组件,按第 22 篇的拆分决定)。 +- 条件显示:没有选中时显示「请选择道具」;有选中时显示详情。**优先 `hidden`**(两块都渲染、用 `hidden` 切换),并说明为什么这里适合 `hidden`(切换频繁、需要保留状态)。 +- 长描述用 `TextContent` 并给 `width`(必填)与 `autoHeight`;说明为什么不用文字元素硬排(不换行)。 +live 用 `inventory-3-detail`(选中不同格子,详情随之更新;无选中时提示)。**live 与正文代码块不是同一份代码**:live 用元素层等价画面(`text` + `alpha` / 尺寸放着,不引入 `@user/client-base` 的内置组件),正文代码块才用 `TextContent`;正文必须用一句话说明这一点,避免读者以为 live 就是那一段代码。`## 边界与注意`:`computed` 里不要写副作用;`find` 返回 `undefined` 时要处理;`TextContent` 不给 `width` 不能用;两块都渲染时注意 `zIndex` 与遮挡。 + +**(2)`inventory-example-4-scroll.md`(第 25 篇)**:讲道具变多之后的两条路: +- `Scroll` 平铺(推荐):把网格的每一格作为 `Scroll` 的**直接子元素**(不要用一个容器包住全部内容),给 `Scroll` 的 `loc` 与 `padEnd`;用 `ref` 拿 `scrollTo` / `getScrollLength` 做一个「滚到最上面」按钮。 +- `ListPage` 左列表右详情:把现有网格换成 `ListPage`,讲 `basis` / `right` / `close` 与动态 slot;说明它在「左列表右详情」场景下省掉自己算分栏。 +- 给一张「什么时候用 `Scroll`、什么时候用 `ListPage`、什么时候用 `Page`」的判定表。 +live 用 `inventory-4-scroll`(20–50 个假道具可滚动,滚动条与滚轮可用)。**同样地,live 用元素层等价画面演示滚动**(`Scroll` 只在正文代码块展示),正文用一句话点明「live 展示的是滚动效果,代码块给出 `Scroll` / `ListPage` 的真实写法」。`## 边界与注意`:`Scroll` 里包一层容器会让虚拟滚动失效;列表项高度不一致时 `padEnd` 可能要调;`ListPage` 的 slot 按选中 key 渲染,key 必须与 `list` 里的 id 对应;容器自定义标签只写 `container-custom`。 + +**(3)两个 demo**:`inventory-3-detail.tsx`(`Inventory3Detail`)= 上一步 + 详情区;`inventory-4-scroll.tsx`(`Inventory4Scroll`)= 上一步 + 滚动列表。都要能被单独看懂且体现增量。默认导出、无 DOM 属性。 + +**(4)侧边栏**:在「完整示例」分组追加两篇。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/];const need={"docs/advanced/ii/ui/inventory-example-3-detail.md":["ItemDetail","computed(","hidden","TextContent","width","autoHeight","请选择道具"],"docs/advanced/ii/ui/inventory-example-4-scroll.md":["Scroll","ListPage","Page","scrollTo","getScrollLength","直接子元素","container-custom","padEnd"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});["inventory-3-detail.tsx","inventory-4-scroll.tsx"].forEach(function(f){const p="docs/.vitepress/components/demos/ui/"+f;if(!fs.existsSync(p)){bad.push("NO-DEMO:"+f);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+f);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+f)});const d4=fs.existsSync("docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx")?rd("docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx"):"";if(d4.indexOf("Scroll")<0&&d4.indexOf("scroll")<0)bad.push("DEMO4-NO-SCROLL");const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-3-detail","/advanced/ii/ui/inventory-example-4-scroll","/advanced/ii/ui/inventory-example-2-grid","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "NO-CONFIRM-10-47", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "DEMO4-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T2-OK" + + 详情篇含 `ItemDetail`、`computed`、`hidden` 优先、`TextContent` + `width` + `autoHeight`、无选中提示;滚动篇含 `Scroll` / `ListPage` / `Page` 三者取舍、`scrollTo` / `getScrollLength`、`padEnd`、`Scroll` 只对直接子元素生效、`container-custom`;两篇单 H1、有边界节、CRLF、接 live、无被禁写法;两个 demo 默认导出且无 DOM 属性、第 4 个 demo 含滚动;侧边栏补两条且既有条目未丢;构建 green、无 dead link。 + 示例(三)(四)完成,详情区与滚动落地。 + + + + Task 3: 示例(五)交互与状态 /(六)动画、拆分与注册 + 两个 demo + 侧边栏 + docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, docs/.vitepress/components/demos/ui/inventory-5-state.tsx, docs/.vitepress/components/demos/ui/inventory-6-full.tsx, docs/.vitepress/config.ts + NOTES 含 `用户确认(10-47):可以执行`;Task 2 两篇已落盘且构建 green。 + 10-CUSTOM-UI-RESEARCH.md(Per-page Notes 第 26、27 篇;UI System 的 `keep` / `setBackground`;Performance 的 `hidden` 与 `alpha`)、docs/advanced/ii/ui/reactivity.md(`watch` 用法)、docs/advanced/ii/ui/hotkey-in-ui.md(`useKey(...)!` 口径)、docs/advanced/ii/ui/layer-transform-performance.md(`alpha` / `scale` / `hidden`)、docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx、packages-user/client-modules/src/render/use.ts(渐变工具签名) + 写第 26、27 篇与两个 demo,完成整条示例。 + +**(1)`inventory-example-5-state.md`(第 26 篇)**:写 `ActionBar` 与状态驱动: +- 「装备」按钮:`equippedId` 用 `ref`,点一下把当前选中道具设为已装备;已装备的格子在 `ItemCell` 上用边框或 `alpha` 表现。 +- 「使用」按钮:`items` 里对应道具 `count` 减一;数量为 0 时按钮不可用(用 `alpha` + `hidden` 表现禁用视觉,并让点击回调直接返回)。 +- `computed` 派生「当前是否能使用 / 是否能装备」;`watch` 做一个副作用(例如数量变化时更新一行提示文字),并说明什么时候该用 `watch`、什么时候该用 `computed`。 +- 键盘收口:`const key = useKey(props.state.hotkey.system)!;`,把 `@common/exit` 接到关闭面板;说明组件卸载会自动离开作用域。若 live 环境没有按键系统,页面注明「live 里用关闭按钮替代,按键写法见代码块」。 +- `noevent` 遮罩:面板背后放一层遮罩让点击不穿透;说明 `noevent` 与 `hidden` 的区别。 +live 用 `inventory-5-state`(点击装备 / 使用,数量与提示变化)。`## 边界与注意`:不要在 `watch` 里改同一个状态造成循环;按钮禁用只是视觉 + 早返回,不要靠 `hidden` 藏起来当禁用;`useKey` 只在 `setup` 里调用;遮罩层注意 `zIndex`。 + +**(2)`inventory-example-6-animation-and-register.md`(第 27 篇)**:收尾: +- 动画:**live 用 `requestAnimationFrame`(配 `onUnmounted` 取消)**让选中格的边框 / 详情区透明度平滑变化——不依赖任何返回可空值的渐变控制器,避免 `null` 分支;给出 `onUnmounted` 清理;说明动画只改 `alpha` / `scale` / 颜色,不要每帧重建组件。若正文额外展示仓库的渐变工具(`transitioned` 一类),**必须写明其返回值是 `ITransitionedController | null` 并做 null 判断**,且 live 不得使用它。 +- 拆分回顾:把前五步的代码按第 22 篇的结构落到五个文件,给**最终文件结构**(目录树)与每个文件的职责。 +- 注册与打开:`export const InventoryUI = new GameUI('inventory-panel', InventoryPanel)`;打开处替换(游戏内主 UI 栈用 `props.state.mainUIController.open(InventoryUI, {})`,场景 UI 用 `controller.open`);`keep` 防闪烁的用法一句带过并链接第 19 篇。 +- 性能自查:用第 21 篇的清单逐条对照(`hidden` 优先、列表 `Scroll`、`key` 规则、组件粒度),给一张勾选表。 +- 最后一段:完整面板的 live。 +live 用 `inventory-6-full`(网格 + 详情 + 滚动 + 装备 / 使用 + 关闭 + 动画)。`## 边界与注意`:渐变在卸载后必须停;拆分后 Props 要逐层传,不要用全局变量绕过;注册只是把名字和组件绑在一起,不写入全局表,因此不要按名字取 UI;最终 live 跑不起来不删内容,保留代码与说明。 + +**(3)两个 demo**:`inventory-5-state.tsx`(`Inventory5State`)= 上一步 + 交互与状态;`inventory-6-full.tsx`(`Inventory6Full`)= 完整面板,必须包含网格、详情、滚动、装备 / 使用、关闭、动画。默认导出、无 DOM 属性;动画**统一用 `requestAnimationFrame` + `onUnmounted` 取消**(不要在 live 里用返回 `ITransitionedController | null` 的渐变工具),不要引入新依赖。 + +**(4)侧边栏**:在「完整示例」分组追加最后两篇。只做加法。 + +写完跑 `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const need={"docs/advanced/ii/ui/inventory-example-5-state.md":["ActionBar","ref(","computed(","watch(","useKey(","@common/exit","noevent","equippedId","alpha"],"docs/advanced/ii/ui/inventory-example-6-animation-and-register.md":["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar","GameUI","onUnmounted","alpha","scale","hidden","keep"]};Object.keys(need).forEach(function(f){if(!fs.existsSync(f)){bad.push("MISSING:"+f);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+f);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+f);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+f+":"+r)});need[f].forEach(function(k){if(s.indexOf(k)<0)bad.push("KEY:"+f+":"+k)});if(!/\x3cClientOnly\x3e/.test(s))bad.push("CLIENTONLY:"+f);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+f);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+f)});const d5="docs/.vitepress/components/demos/ui/inventory-5-state.tsx";const d6="docs/.vitepress/components/demos/ui/inventory-6-full.tsx";[[d5,["selectedId"]],[d6,["selectedId","InventoryPanel"]]].forEach(function(pair,i){const p=pair[0];if(!fs.existsSync(p)){bad.push("NO-DEMO:"+i);return}const s=rd(p);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+i);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+i);pair[1].forEach(function(k){if(s.indexOf(k)<0)bad.push("DEMO-KEY:"+i+":"+k)})});const cfg=rd("docs/.vitepress/config.ts");["/advanced/ii/ui/inventory-example-5-state","/advanced/ii/ui/inventory-example-6-animation-and-register","/advanced/ii/ui/inventory-example-4-scroll","/advanced/iii/"].forEach(function(k){if(cfg.indexOf(k)<0)bad.push("CFG:"+k)});if(bad.length){console.error("PAGE-ASSERT:"+bad.join("|"));process.exit(1)}console.log("PAGES-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'PAGE-ASSERT-FAIL' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK' + non-zero exit, or output contains "NO-CONFIRM-10-47", "PAGE-ASSERT", "MISSING:", "H1:", "EDGE:", "FORBID:", "KEY:", "CLIENTONLY:", "LOADER:", "CRLF:", "NO-DEMO", "DEMO-", "CFG:", "BUILD-FAIL", "NO-BUILD-COMPLETE", or "DEAD-LINK"; or output lacks "T3-OK" + + 交互篇含 `ActionBar` / `equippedId` / `ref` / `computed` / `watch` / `useKey(...)` / `@common/exit` / `noevent`,并说明禁用只是视觉 + 早返回;动画注册篇含五个组件名、`GameUI` 注册、`onUnmounted` 清理、`alpha` / `scale` / `hidden` 与 `keep`,并给最终文件结构与性能自查表;两篇单 H1、有边界节、CRLF、接 live、无被禁写法(含 `GameUI.get`);两个 demo 默认导出、无 DOM 属性、第 6 个是完整面板;侧边栏补两条且既有条目未丢;构建 green、无 dead link。 + 示例(五)(六)完成,完整面板可运行。 + + + + Task 4: 六类门禁收口 + NOTES 记录 + 全批交叉核对 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1..3 的 6 篇与 6 个 demo 已落盘、侧边栏 6 条齐全、构建 green。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录区与前面四批记录)、docs/advanced/ii/ui/(本批 6 篇 + 前四批 21 篇)、docs/.vitepress/components/demos/ui/、docs/.vitepress/config.ts + 按固定顺序跑门禁并记录: + +1. `cmd /c "pnpm exec prettier --write docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts"`,随后同路径 `--check`。 +2. `cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`:0 error / 0 warning。 +3. `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`:`docs/` 路径 0 报错;引擎既有报错记条数与摘要。 +4. 静态断言:6 篇单 H1 / `## 边界与注意` / 无被禁写法 / 全部接 live / 6 个 demo 默认导出且无 DOM 属性(只允许 vue、元素标签与 `@motajs/system`;不得出现其它 `@motajs/*` 或任何 `@user/*`) / 侧边栏 27 条(10-43 的 6 + 10-44 的 6 + 10-45 的 4 + 10-46 的 5 + 本批 6)齐全 / 既有条目与高级 III 未丢 / 第 22 与第 27 篇的五个组件名一致。 +5. `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`:green、`build complete`、0 dead link。 +6. 向 NOTES 的 `## 门禁记录` 追加 `### 10-47 门禁`:六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、本批 6 篇与 6 个 demo 清单。 +7. **全批交叉核对**(写进该小节,逐条给结论):①27 篇是否都在侧边栏出现且无重复;②六个 Part 分组的顺序是否与 10-43 命名总表一致;③`hidden` 口径在第 8 / 12 / 21 / 24 篇是否一致;④`v-model:xxx` 口径在第 13 / 17 / 18 篇是否一致;⑤第 22 与第 27 篇的组件拆分是否一致;⑥是否有任何页面出现被禁写法。若发现不一致,**只记录、不改前几批正文**,留给 10-48 的独立读者审阅记录,由用户在 10-49 的修订环节裁决。 + +本任务不改本批正文语义。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); if($np -notmatch '(?m)^用户确认(10-47):可以执行\s*$'){ Write-Error 'NO-CONFIRM-10-47' }; $paths='docs/advanced/ii/ui docs/.vitepress/components/demos/ui docs/.vitepress/config.ts'; $pw = cmd /c "pnpm exec prettier --write $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc = cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el = cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc = cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr = @($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out = cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $js='const fs=require("fs");const bad=[];function rd(f){return fs.readFileSync(f,"utf8")}const forbid=[/custom-container/,/MotaRenderer/,/createRendererFor/,/registerElement/,/IUIPropsBase/,/core\./,/onUpdate:/,/\bv-if=/,/\bv-for=/,/\bv-show=/,/GameUI\.get/];const md=["inventory-example-1-skeleton","inventory-example-2-grid","inventory-example-3-detail","inventory-example-4-scroll","inventory-example-5-state","inventory-example-6-animation-and-register"];md.forEach(function(m){const f="docs/advanced/ii/ui/"+m+".md";if(!fs.existsSync(f)){bad.push("MISSING:"+m);return}const s=rd(f);if((s.match(/^# /gm)||[]).length!==1)bad.push("H1:"+m);if(s.indexOf("## 边界与注意")<0)bad.push("EDGE:"+m);forbid.forEach(function(r){if(r.test(s))bad.push("FORBID:"+m)});if(s.indexOf("\x3cClientOnly\x3e")<0)bad.push("CLIENTONLY:"+m);if(!/\(\)\s*=>\s*import\(/.test(s))bad.push("LOADER:"+m);if(!/\r\n/.test(s)||/[^\r]\n/.test(s))bad.push("CRLF:"+m)});["inventory-1-skeleton","inventory-2-grid","inventory-3-detail","inventory-4-scroll","inventory-5-state","inventory-6-full"].forEach(function(m){const f="docs/.vitepress/components/demos/ui/"+m+".tsx";if(!fs.existsSync(f)){bad.push("NO-DEMO:"+m);return}const s=rd(f);if(!/export\s+default/.test(s))bad.push("DEMO-DEFAULT:"+m);if(/style=|class=/.test(s))bad.push("DEMO-DOM:"+m);if(/from\s+[\x22\x27]@motajs\/(?!system[\x22\x27])/.test(s))bad.push("DEMO-ENGINE:"+m);if(/from\s+[\x22\x27]@user\//.test(s))bad.push("DEMO-USER:"+m)});const cfg=rd("docs/.vitepress/config.ts");const all=["ui-template","ui-template-ts","container-and-coordinates","basic-shapes","curves-and-paths","text","image-and-texture","layer-transform-performance","reactivity","events","hotkey-in-ui","conditional-and-list-rendering","props","component-tsx","component-ts","slots-and-attrs","builtin-text-and-input","builtin-list-and-containers","ui-controller-and-stack","replace-builtin-ui","ui-performance","inventory-example-1-skeleton","inventory-example-2-grid","inventory-example-3-detail","inventory-example-4-scroll","inventory-example-5-state","inventory-example-6-animation-and-register"];all.forEach(function(m){const hit=(cfg.match(new RegExp("/advanced/ii/ui/"+m.replace(/[-.]/g,"\\$&")+"[\x27\x22]","g"))||[]).length;if(hit<1)bad.push("CFG-MISSING:"+m);if(hit>1)bad.push("CFG-DUP:"+m)});if(cfg.indexOf("custom-range")<0||cfg.indexOf("/advanced/iii/")<0)bad.push("CFG-LOST-SIBLING");const p22=rd("docs/advanced/ii/ui/inventory-example-1-skeleton.md");const p27=rd("docs/advanced/ii/ui/inventory-example-6-animation-and-register.md");["InventoryPanel","ItemGrid","ItemCell","ItemDetail","ActionBar"].forEach(function(k){if(p22.indexOf(k)<0||p27.indexOf(k)<0)bad.push("SPLIT-DRIFT:"+k)});if(bad.length){console.error("GATE:"+bad.join("|"));process.exit(1)}console.log("STATIC-OK")'; node -e $js; if($LASTEXITCODE -ne 0){ Write-Error 'STATIC-ASSERT-FAIL' }; if($np -notmatch '(?m)^### 10-47 门禁'){ Write-Error 'NOTES-NO-GATE-SECTION' }; if($np -notmatch '路径类型报错 0'){ Write-Error 'NOTES-NO-DOCS-TYPECHECK' }; if($np -notmatch '既有引擎报错'){ Write-Error 'NOTES-NO-ENGINE-NOTE' }; if($np -notmatch '全批交叉核对'){ Write-Error 'NOTES-NO-CROSSCHECK' }; 'T4-OK' + non-zero exit, or output contains "NO-CONFIRM-10-47", "PRETTIER-WRITE-FAIL", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "GATE:", "STATIC-ASSERT-FAIL", "CFG-DUP", "SPLIT-DRIFT", "NOTES-NO-"; or output lacks "T4-OK" + + prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径类型报错 0;静态断言全绿(6 篇单 H1 / 边界节 / 无被禁写法 / 全部接 live / 6 个 demo 默认导出、无 DOM 属性、只 import vue + 元素标签 +(可选)`@motajs/system` / 27 条侧边栏链接各出现一次且无重复 / 既有条目与高级 III 未丢 / 第 22 与第 27 篇组件名一致);构建 green、无 dead link;NOTES 有 `### 10-47 门禁`、`全批交叉核对` 小节与类型检查 / 引擎报错摘要。 + Part 5 六篇 6 demo 通过六类门禁,全批 27 篇已在侧边栏就位并有交叉核对记录。 + + + + Task 5: 用户目视 6 个 live 并抽查六篇正文 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 4 通过(六类门禁全绿、构建产物已生成、NOTES 已记录、交叉核对已完成)。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(门禁记录与交叉核对)、docs/advanced/ii/ui/(本批 6 篇)、docs/.vitepress/components/demos/ui/(本批 6 个 demo) + 请用户用 `cmd /c "pnpm docs:dev"`(或 `cmd /c "pnpm docs:preview"`)打开本批 6 篇,逐条确认:①侧边栏「完整示例」6 条可点开;②第 1 个 live 是骨架 + 关闭;③第 2 个 live 有网格且能选中;④第 3 个 live 选中后详情更新、无选中时有提示;⑤第 4 个 live 能滚动;⑥第 5 个 live 装备 / 使用生效、数量变化;⑦第 6 个 live 是完整面板(网格 + 详情 + 滚动 + 装备 / 使用 + 关闭 + 动画);⑧逐篇对照:每一步都是「上一步 + 增量」,没有另起一套实现;⑨第 27 篇的最终文件结构与第 22 篇一致。通过时在 NOTES 的 `## 人工验证记录` 追加独占一行 `用户人工验证(10-47):通过` + 下一行 `用户原文:`;发现问题逐条记入 NOTES 并标 `状态:待处理`,回到对应任务修复、重跑 Task 4 后复验。只有用户明确通过才可进入 10-48 的独立读者审阅;本次 live 的最终全站复验仍由 10-49 Task 4 覆盖。 + 6 篇正文与 6 个逐级递增的 live demo,最终版是完整背包面板。 + 按上面①–⑨逐条检查;重点看六步是否真的递增、最终面板是否可用、第 22 与第 27 篇的拆分是否一致。 + 若全部通过,回复「通过」;若有问题,请逐条描述现象(可附页面路径与控制台报错)。 + 用户明确回复 6 篇可读、6 个 live 正常且递增关系清楚,并已把结论记入 NOTES;否则问题清单已记录并进入修复循环。 + + 用户已明确确认六篇增量关系成立、最终面板可用,并已把结论记入 NOTES。 + + 用户人工验证结论已记录。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 构建期(SSR)→ live demo | 六个 demo 由 loader 动态 import;页面只静态 import 包装组件 | +| demo → 假数据 | 只使用本地写死的假道具,不读存档、不发请求、不持久化 | +| 文档 → 读者 | 读者会照抄六个文件结构;拆分不一致会让读者拼不起来 | +| 侧边栏 → 页面 | 每条 link 必须对应已存在页面 | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-147 | Denial of Service(构建不可用) | 六个 `.tsx` demo | high | mitigate | 全部由 loader 动态 import、`` 包裹;构建门禁必须 `build complete` | +| T-10-148 | Tampering | 侧边栏 27 条链接 | medium | mitigate | 静态断言逐条计数:每条恰好出现一次(缺失与重复都失败);既有条目与高级 III 未丢 | +| T-10-149 | Repudiation | 组件拆分前后不一致 | medium | mitigate | 静态断言比对第 22 与第 27 篇的五个组件名;不一致即失败 | +| T-10-150 | Information Disclosure | 示例泄露内部实现 | low | mitigate | 静态断言禁渲染器类名 / 标签注册 / core 命名空间 / `GameUI.get`;只写应用层用法 | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包(动画只用 vue 或仓库已有工具);缺依赖即停止报告 | + + + +- 确认门禁:NOTES 含 `用户确认(10-47):可以执行` + `用户原文:`;Task 5 后含 `用户人工验证(10-47):通过` + `用户原文:`,无 `状态:待处理`。 +- 增量门禁:六篇按顺序递增,每篇只在本步加一段;第 22 与第 27 篇的五个组件名一致。 +- 内容门禁:6 篇单 H1、`## 边界与注意`、CRLF;无 `custom-container`、渲染器类名、`createRendererFor`、`registerElement`、`IUIPropsBase`、core 命名空间、`onUpdate:`、模板条件/循环/隐藏指令属性、`GameUI.get`。 +- 示例门禁:6 篇全部接 live;6 个 demo 默认导出、无 DOM 属性;最终 demo 含网格 / 详情 / 滚动 / 交互 / 关闭 / 动画。 +- 类型 / 构建 / 格式门禁:`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错;`pnpm docs:build` green、0 dead link;prettier `--check` 通过;ESLint 0/0。 +- 越界门禁:未改 `packages/` / `packages-user/` / `src/`;未改前四批已验收内容;未改 `10-01`..`10-46` 计划;未 commit;ROADMAP / STATE 本计划不改。 + + + +- 读者能按六篇顺序把背包 / 装备面板跑起来,并且知道每一步新增了什么。 +- 27 篇正文全部在侧边栏就位、无重复、无 dead link;全批交叉核对结论在案。 +- 六类门禁全绿并有记录;用户目视通过;未改源码、未 commit。 + + + +Create `.planning/phases/10-docs-restructure/10-47-SUMMARY.md` when done + + +## 编号变更(2026-11-01) + +本文件写作期提到的「10-49 的用户修订裁决」「10-49 Task 4」与「10-50」,现按下列映射理解(原文保持不变): + +- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`)。 +- 用户修订、最终门禁、全站 live、落位评估与收尾 → `10-54-PLAN.md`。 +- 新增的 `10-49`..`10-52` 是 25 篇的 Part 0–1 / 2–3 / 4 / 5 深度扩写(D-93)。 +- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。 diff --git a/.planning/phases/10-docs-restructure/10-47-SUMMARY.md b/.planning/phases/10-docs-restructure/10-47-SUMMARY.md new file mode 100644 index 0000000..031502f --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-47-SUMMARY.md @@ -0,0 +1,131 @@ +--- +phase: 10-docs-restructure +plan: 47 +subsystem: docs +tags: + - docs + - vitepress + - ui + - inventory-example +requires: + - 10-46 +provides: + - advanced-ii-ui-part5 + - inventory-example-pages + - inventory-demos +affects: + - docs/advanced/ii/ui + - docs/.vitepress/config.ts +tech-stack: + added: [] + patterns: + - client-only-live-demo + - progressive-incremental-example +key-files: + created: + - docs/advanced/ii/ui/inventory-example-1-skeleton.md + - docs/advanced/ii/ui/inventory-example-2-grid.md + - docs/advanced/ii/ui/inventory-example-3-detail.md + - docs/advanced/ii/ui/inventory-example-4-scroll.md + - docs/advanced/ii/ui/inventory-example-5-state.md + - docs/advanced/ii/ui/inventory-example-6-animation-and-register.md + - docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx + - docs/.vitepress/components/demos/ui/inventory-2-grid.tsx + - docs/.vitepress/components/demos/ui/inventory-3-detail.tsx + - docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx + - docs/.vitepress/components/demos/ui/inventory-5-state.tsx + - docs/.vitepress/components/demos/ui/inventory-6-full.tsx + modified: + - docs/.vitepress/config.ts + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +decisions: + - 六篇按「上一步 + 一小段增量」推进,配六个独立递增的 live,而不是同一个 demo 改六次。 + - 组件拆分从第 22 篇定死为 InventoryPanel / ItemGrid / ItemCell / ItemDetail / ActionBar,第 27 篇只回顾不改结构。 + - 面板尺寸 720×480,假数据 10–40 个道具,只用 g-rect / g-rectr / text 绘制。 + - 第 25 篇以 Scroll 平铺为主,ListPage 作左列表右详情对比,并给 Scroll / ListPage / Page 判定表。 + - 第 27 篇动画在 live 中用 requestAnimationFrame + onUnmounted 取消,不依赖可空的渐变控制器;正文提及 transitioned 时要求判空。 + - 文档站缺少 client-base 渲染器时,live 用元素层等价画面,正文代码块保留 TextContent / Scroll / ListPage 的真实写法。 +metrics: + duration: ~16m + completed: 2026-10-31 +status: complete +human_verification: deferred-to-10-49 +actuals: + tokens: 23000 + tasks: 5 + commits: 0 + plan_head_before: b94b4c3b41da8184312bc9f264654dc9a54adf69 +--- + +# Phase 10 Plan 47: 完整示例(背包 / 装备面板) Summary + +用六篇递增文档与六个逐级 live,把完整的背包 / 装备面板从骨架写到动画、拆分与注册;侧边栏新增「完整示例」分组,六类门禁全绿。 + +## What Was Built + +- **第 22 篇「示例(一)目标与骨架」**:最终效果、五文件拆分、720×480 骨架、标题与关闭按钮、ItemGrid / ItemDetail 占位、Props 基类与 `GameUI('inventory-panel', InventoryPanel)` 注册、两种打开方式。 +- **第 23 篇「示例(二)道具网格」**:`Item` 数据模型与 10 个假道具、`ItemCell` 的 props / emits、`ItemGrid` 的 `.map()` 与行列计算、`selectedId` 提升到父组件、`key` 取舍说明。 +- **第 24 篇「示例(三)详情区」**:`computed` 派生选中项、`ItemDetail` 的名称 / 数量 / 描述、`hidden` 优先的未选中提示、`TextContent` 的 `width` 与 `autoHeight`、live 与正文代码块差异说明。 +- **第 25 篇「示例(四)滚动与列表」**:`Scroll` 平铺(直接子元素、`padEnd`、`scrollTo` / `getScrollLength`)、`ListPage` 左列表右详情(`basis` / `right` / `close` / slot)、`Scroll` / `ListPage` / `Page` 判定表。 +- **第 26 篇「示例(五)交互与状态」**:`ActionBar`、`equippedId`、`ref` / `computed` / `watch`、使用后数量减一、`useKey(...)!` 接 `@common/exit`、`noevent` 遮罩。 +- **第 27 篇「示例(六)动画、拆分与注册」**:`requestAnimationFrame` + `onUnmounted` 动画、`transitioned` 可空说明、最终文件结构、`GameUI` 注册与主 UI 栈 / 场景 UI 打开、`keep` 提示、性能自查表、完整面板 live。 +- **六个 demo**:从 `inventory-1-skeleton` 到 `inventory-6-full`,每一步只增加上一篇的内容;第 6 个含网格、详情、滚动、装备 / 使用、关闭与动画。 +- **侧边栏**:`docs/.vitepress/config.ts` 的「自定义 UI 与渲染」内新增「完整示例」分组 6 条,原有 21 条与高级 III 均保留。 + +## Verification + +| 门禁 | 结果 | +|------|------| +| prettier `--write` / `--check` | exit 0;`All matched files use Prettier code style!` | +| ESLint | 0 error / 0 warning | +| `vue-tsc --noEmit -p docs/tsconfig.json` | `docs/` 路径类型报错 0;既有引擎报错 11 条(非本轮引入) | +| 静态断言 | `STATIC-OK`;27 条侧边栏链接各出现一次、无重复;6 篇单 H1 / 边界节 / CRLF / live;6 个 demo 默认导出、无 DOM 属性、只 import vue | +| `pnpm docs:build` | green,`build complete in 24.63s.`,无 dead link | +| 全批交叉核对 | 27 篇齐全;六个 Part 顺序一致;`hidden`、`v-model:xxx`、第 22/27 拆分、被禁写法六项均通过 | + +## Deviations from Plan + +### Process / Checkpoint + +**1. Task 5(live 人工验证)按调度指令跳过并顺延** +- **Found during:** 执行上下文 +- **Issue:** 10-47 末尾的 `checkpoint:human-verify` 要求用户目视 6 个 live;调度指令要求在 10-48 独立读者审阅与 10-49 用户修订前停下。 +- **Fix:** 未写「用户人工验证(10-47):通过」,NOTES 记录「live 人工验证(10-47):待最终人工审阅」。Task 5 未执行。 +- **Files modified:** `.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md` + +**2. 正文 / demo 采用内联执行,而非派发子代理** +- **Found during:** Task 1 开始前 +- **Issue:** 本执行环境未提供子代理派发工具;计划约定正文 / demo 由子代理执行。 +- **Fix:** 按调度器可直接编辑的能力内联落盘,并在执行开始时声明「内联执行」;未调用 `opencode` 命令。 +- **Files modified:** 本计划全部产物 + +**3. 未执行 git add / commit / push / stash / 分支切换** +- **Found during:** 全流程 +- **Issue:** 标准执行器流程要求逐任务提交与最终元数据提交;本次调度指令明确不提交。 +- **Fix:** 所有改动保留在工作树;SUMMARY 中 `commits: 0`,未改 STATE / ROADMAP。 +- **Files modified:** 无 + +## Known Limitations + +- 文档站缺少 `packages-user/client-base/src/renderer`,无法静态 import 内置组件。第 24 / 25 篇 live 用元素层等价画面(`text`、`alpha`、尺寸与滚动窗口)演示,正文代码块保留 `TextContent` / `Scroll` / `ListPage` 的真实写法;两篇正文均已写明「live 与正文代码块不是同一份代码」。这是 10-46 已记录的既有中间态,不是本计划引入的缺陷。 + +## Threat Flags + +None — 六个 demo 只 import `vue` 与本框架元素标签,使用本地假数据,不读写存储、不发请求、不引入新依赖。 + +## Self-Check: PASSED + +- [x] 6 篇正文与 6 个 demo 全部存在 +- [x] 侧边栏共 27 条 `/advanced/ii/ui/` 链接,27 个唯一值,无重复 +- [x] prettier / ESLint / docs 类型 / 静态断言 / 构建全部通过 +- [x] NOTES 含 10-47 确认、参考哈希、门禁记录与全批交叉核对 +- [x] 未执行 10-48 / 10-49;未提交 git;未改 `packages/` / `packages-user/` / `src/` + +## 编号变更(2026-11-01) + +本文件中的 `deferred-to-10-49` 与「10-49 用户修订前停止」是写作期编号;重排后: + +- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`)。 +- 用户修订与收尾 → `10-54-PLAN.md`。 +- 新增 `10-49`..`10-52` 为 25 篇的 Part 0–1 / 2–3 / 4 / 5 深度扩写(D-93);`10-48` 仍为 pre-review 修复。 +- 本文件的 live 复验仍由 `10-54` Task 4 的全站 live 统一覆盖;历史正文不改写。 diff --git a/.planning/phases/10-docs-restructure/10-48-PLAN.md b/.planning/phases/10-docs-restructure/10-48-PLAN.md new file mode 100644 index 0000000..2dd59bd --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-48-PLAN.md @@ -0,0 +1,414 @@ +--- +phase: 10-docs-restructure +plan: 48 +type: execute +wave: 6 +depends_on: + - 10-47 +files_modified: + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + - docs/.vitepress/config.ts + - docs/advanced/ii/index.md + - docs/advanced/index.md + - docs/advanced/ii/ui/ui-template.md + - docs/advanced/ii/ui/container-and-coordinates.md + - docs/advanced/ii/ui/basic-shapes.md + - docs/advanced/ii/ui/curves-and-paths.md + - docs/advanced/ii/ui/text.md + - docs/advanced/ii/ui/image-and-texture.md + - docs/advanced/ii/ui/layer-transform-performance.md + - docs/advanced/ii/ui/reactivity.md + - docs/advanced/ii/ui/events.md + - docs/advanced/ii/ui/hotkey-in-ui.md + - docs/advanced/ii/ui/conditional-and-list-rendering.md + - docs/advanced/ii/ui/props.md + - docs/advanced/ii/ui/component-tsx.md + - docs/advanced/ii/ui/slots-and-attrs.md + - docs/advanced/ii/ui/builtin-text-and-input.md + - docs/advanced/ii/ui/builtin-list-and-containers.md + - docs/advanced/ii/ui/ui-controller-and-stack.md + - docs/advanced/ii/ui/replace-builtin-ui.md + - docs/advanced/ii/ui/ui-performance.md + - docs/advanced/ii/ui/inventory-example-1-skeleton.md + - docs/advanced/ii/ui/inventory-example-2-grid.md + - docs/advanced/ii/ui/inventory-example-3-detail.md + - docs/advanced/ii/ui/inventory-example-4-scroll.md + - docs/advanced/ii/ui/inventory-example-5-state.md + - docs/advanced/ii/ui/inventory-example-6-animation-and-register.md + - docs/advanced/ii/ui/ui-template-ts.md + - docs/advanced/ii/ui/component-ts.md + - docs/.vitepress/components/demos/ui/template-demo.tsx + - docs/.vitepress/components/demos/ui/container-demo.tsx + - docs/.vitepress/components/demos/ui/shapes-demo.tsx + - docs/.vitepress/components/demos/ui/curves-demo.tsx + - docs/.vitepress/components/demos/ui/text-demo.tsx + - docs/.vitepress/components/demos/ui/texture-demo.tsx + - docs/.vitepress/components/demos/ui/layer-demo.tsx + - docs/.vitepress/components/demos/ui/reactivity-demo.tsx + - docs/.vitepress/components/demos/ui/events-demo.tsx + - docs/.vitepress/components/demos/ui/conditional-demo.tsx + - docs/.vitepress/components/demos/ui/props-demo.tsx + - docs/.vitepress/components/demos/ui/component-demo.tsx + - docs/.vitepress/components/demos/ui/slots-demo.tsx + - docs/.vitepress/components/demos/ui/builtin-text-demo.tsx + - docs/.vitepress/components/demos/ui/builtin-list-demo.tsx + - docs/.vitepress/components/demos/ui/controller-demo.tsx + - docs/.vitepress/components/demos/ui/strategy-demo.tsx + - docs/.vitepress/components/demos/ui/perf-demo.tsx + - docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx + - docs/.vitepress/components/demos/ui/inventory-2-grid.tsx + - docs/.vitepress/components/demos/ui/inventory-3-detail.tsx + - docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx + - docs/.vitepress/components/demos/ui/inventory-5-state.tsx + - docs/.vitepress/components/demos/ui/inventory-6-full.tsx + - docs/.vitepress/components/demos/ui/ts-component-demo.tsx +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 96000 + raw_tokens: 60000 + tasks: 6 + confidence: low +must_haves: + truths: + - "删去 2 篇独立 TS 页与 1 个 TS demo 后,`docs/advanced/ii/ui` 恰好 25 篇 Markdown、`docs/.vitepress/components/demos/ui` 恰好 24 个 `.tsx`;侧边栏、两页导览与全批交叉引用同步到 25 条(D-46 / D-78 / D-89 / D-90 不变)" + - "相关页面的 TSX 示例后附有简短 TS 元素层演示(至少覆盖模板、容器、图形、文字、组件 TSX 篇之后、UIController/UI 栈);演示不写 Vue 组件、不写类型标注、不要求运行;不新增独立页面或 demo" + - "全批不出现全局 `client`:所有打开 / 关闭示例从 `props.state` 取 ClientCore(如 `props.state.sceneController.open(...)`);模板与 UIController 篇明确说明没有全局 `client`" + - "25 篇正文的所有代码块与 24 个 demo 都补了有价值注释;注释只新增、不修改既有注释;只新增整行 `//` 或单行 `{/* ... */}` 注释,不改变任何非注释代码" + - "最终门禁:prettier `--write` / `--check` 通过、ESLint 0/0、`vue-tsc -p docs/tsconfig.json` 的 `docs/` 路径 0 报错、`pnpm docs:build` green + `build complete` + 0 dead link、`public/_docs/advanced/ii/ui` 恰好 25 个 HTML" + - "10-48 在修复结束即停止:不进入 10-49 独立读者审阅、不写 SUMMARY / ROADMAP / STATE、不改 `packages*` / `src`、不 commit" + artifacts: + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 10-48 修复范围、基线、删除清单、25/24 计数、注释代码哈希与门禁)" + - "docs/advanced/ii/ui(25 篇正文,含内联 TS 片段、无全局 client、代码块注释)" + - "docs/.vitepress/components/demos/ui(24 个 demo,含注释)" + - "docs/.vitepress/config.ts、docs/advanced/ii/index.md、docs/advanced/index.md(25 条侧边栏与导览、篇号引用一致)" + key_links: + - "先记基线再删改:修复前 docs / demo 快照哈希与 ROADMAP / STATE 哈希必须在第一次删除之前落盘" + - "删除与内联同步:删掉独立 TS 页后,模板、容器、图形、文字、组件、UIController 六处必须补上简短 TS 片段,否则读者失去元素层入口" + - "客户端取法统一:任何示例写全局 `client` 都会让读者在真实组件里找不到该对象;必须改为 `props.state`" + - "注释只加不改:用整行注释 + 去注释代码哈希证明行为未变;修改既有注释或改代码都会使哈希不一致" + - "修复与审阅分离:10-48 只做三项 pre-review 修复,读者审阅仍由 10-49 独立执行" +--- + +> **编号变更(2026-11-01):** 本文件中的旧 10-49 / 10-50 分工已重排,完整映射见文末「编号变更」小节。 + + +本计划是新增的 pre-review 修复计划,只承担用户在独立审阅前点名的三项修复: + +- 三项修复都必须在 10-49 独立读者审阅之前完成,否则读者会读到已被删除的页面、全局 `client` 与无注释示例,审阅结论会混入已知缺陷。 +- 6 个任务对应不能合并的顺序:用户关卡 → 删除与计数收口 → `client` 取法统一 → Part 0–1 注释 → Part 2–5 注释 → 门禁与记录。注释任务必须排在删除与 `client` 修复之后,才能对最终文本补注释并证明行为未变。 +- 不删减任何已验收内容:除删除 2 篇独立 TS 页与 1 个 TS demo、内联 TS 片段、`client` 取法与注释外,10-43..10-47 的正文语义、示例结构、live 与 demo 行为全部保留。 +- 本计划只追加 NOTES、修改 `docs/` 与 `docs/.vitepress/`;不写 SUMMARY、不改 ROADMAP / STATE、不 commit,审阅由 10-49、修订由 10-50 执行。 + + + +在独立读者审阅之前完成三项修复:①删去 `ui-template-ts.md`、`component-ts.md` 与 `ts-component-demo.tsx`,在相关页面内联简短 TS 元素层演示,把全批收口为 25 篇正文 / 24 个 demo;②去掉所有全局 `client`,改为从 `props.state` 取 ClientCore,并在模板与 UIController 篇说明原因;③给 25 篇正文的所有代码块与 24 个 demo 补有价值注释。 + +Purpose: 独立读者只读文档、不读源码(D-46 / D-89)。如果文档还留着独立 TS 页、全局 `client` 或无注释的长示例,读者会被结构问题与不可运行的写法挡住,无法把问题集中在内容本身。把这三项修复前置成独立计划,才能让 10-49 的审阅结论干净可用。 +Output: 修复后的 25 篇正文、24 个 demo、侧边栏与导览,以及 NOTES 中的基线、删除清单、计数、注释代码哈希与门禁记录。**不写 SUMMARY、不改 ROADMAP / STATE、不改源码、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/STATE.md +@.planning/ROADMAP.md +@.planning/phases/10-docs-restructure/10-CONTEXT.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md +@.planning/phases/10-docs-restructure/10-47-PLAN.md +@.planning/phases/10-docs-restructure/10-47-SUMMARY.md +@docs/advanced/ii/index.md +@docs/advanced/index.md +@docs/.vitepress/config.ts + +**流程约定:** +- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-47` 计划文件与 POC 文件、不改 `ROADMAP.md` / `STATE.md`、不改 `packages/` / `packages-user/` / `src/`。 +- **Task 0 是硬关卡**:汇报修复范围、删除清单、25/24 计数、内联位置、注释规则与门禁,等用户明确回复「可以执行」。 +- 改文件前声明「内联执行」还是「派发子代理执行」;本计划所有正文与 demo 写入一律派发子代理执行。 +- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 注释;不 commit(D-90)。 +- 本计划**不进入审阅**:修复结束即停止;独立读者审阅由 10-49 执行,用户修订与收尾由 10-50 执行。 +- 参考哈希基线保持不动:`10-CUSTOM-UI-NOTES.md` 的 `## 参考清单哈希基线` 与各批复核表是写作期记录,不得改写。 +- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。 + +**本批事实:** +- 10-43..10-47 已执行,当前工作区为 27 篇正文与 25 个 demo;本计划执行后应为 25 篇正文与 24 个 demo。 +- 侧边栏在 `docs/.vitepress/config.ts` 的高级 II 分组内,两层嵌套:子分组 → 6 个 Part → 篇目。 +- 两页导览:`docs/advanced/ii/index.md`(本层包含什么、阅读路径)与 `docs/advanced/index.md`(三层结构、边界)。 +- 25 篇正文的 Part 划分:Part 0 起步 1 篇;Part 1 元素与布局 6 篇;Part 2 交互与数据 4 篇;Part 3 组件化 3 篇;Part 4 内置组件与 UI 系统 5 篇;Part 5 完整示例 6 篇。 + + + + + + Task 0: 汇报三项修复范围、删除清单、25/24 计数、内联位置、注释规则与门禁,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CONTEXT.md(D-46 / D-78 / D-89 / D-90)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、六 Part 顺序与前五批门禁)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-RESEARCH.md(UI 子分组范围)、.planning/phases/10-docs-restructure/10-47-PLAN.md 与 10-47-SUMMARY.md、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/ui-template-ts.md、docs/advanced/ii/ui/component-ts.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/ui-controller-and-stack.md + 向用户做四段汇报并停下等待: + +**要做什么**——只做三项 pre-review 修复:①删去 `docs/advanced/ii/ui/ui-template-ts.md`、`docs/advanced/ii/ui/component-ts.md` 与 `docs/.vitepress/components/demos/ui/ts-component-demo.tsx`,从侧边栏与两页导览删去对应 2 条与链接,并在模板、容器、图形、文字、组件 TSX 篇、UIController/UI 栈六处内联简短 TS 元素层演示;全批收口为 25 篇正文 / 24 个 demo。②去掉全局 `client`,所有示例改为从 `props.state` 取 ClientCore,并在模板与 UIController 篇说明「没有全局 client」。③给 25 篇正文的所有代码块与 24 个 demo 补有价值注释。**本计划不进入读者审阅、不写 SUMMARY / ROADMAP / STATE、不改源码、不 commit。** + +**为什么**——独立读者只读文档、不读源码;独立 TS 页会让 Part 0 / Part 3 的入口分裂,全局 `client` 在真实组件里不存在,无注释的长示例会让读者无法判断关键行。三项修复必须在 10-49 审阅前完成,审阅结论才不会被结构问题污染。 + +**大致怎么做**——Task 1 先写 NOTES 基线(修复前 docs / demo 快照、ROADMAP / STATE 哈希、基线 HEAD),再删除 2 页与 1 个 demo、删侧边栏与导览链接、补六处内联 TS 片段、把篇号引用按删除后的顺序重排;Task 2 全批替换 `client.` 为 `props.state.` 并改模板 / controller 文案;Task 3 给 Part 0–1 的 7 篇与 7 个 demo 补注释并记录去注释代码哈希;Task 4 给 Part 2–5 的 18 篇与 17 个 demo 补注释并记录哈希;Task 5 跑 prettier / ESLint / docs 类型 / 构建 / 25 个 HTML / 静态断言,写入 NOTES 后停止。 + +**影响范围**——删除 3 个文件;修改 `docs/advanced/ii/ui/` 下 25 篇正文、`docs/.vitepress/components/demos/ui/` 下 24 个 demo、`docs/.vitepress/config.ts`、`docs/advanced/ii/index.md`、`docs/advanced/index.md`;只追加 `10-CUSTOM-UI-NOTES.md`。不动 `packages/`、`packages-user/`、`src/`、`10-01`..`10-47` 计划文件、POC 文件、`ROADMAP.md`、`STATE.md`、任何既有 JSDoc / 注释。 + +**请用户确认:** +1. **删除范围**:只删 `ui-template-ts.md`、`component-ts.md`、`ts-component-demo.tsx`;不删其它页面或 demo。 +2. **内联范围**:只在 `ui-template.md`、`container-and-coordinates.md`、`basic-shapes.md`、`text.md`、`component-tsx.md`、`ui-controller-and-stack.md` 六处的 TSX 示例后追加简短 `ts` 片段;不新增独立页面 / demo,不要求运行。 +3. **client 取法**:全批示例不出现全局 `client`;`client.sceneController.open(...)` 改为 `props.state.sceneController.open(...)`;模板与 UIController 篇写明「没有全局 client,UI 组件通过传入的 `props.state` 拿到 ClientCore」。 +4. **注释规则**:只新增整行 `//` 或单行 `{/* ... */}` 注释,不修改既有注释;注释说明目的、关键步骤、关键属性 / 参数 / 生命周期;禁止「// 设置属性」这类无信息注释;不改变任何非注释代码。 +5. **计数与门禁**:25 篇正文 / 24 个 demo / 25 个 HTML;prettier、ESLint 0/0、`docs/` 路径 0 类型错误、`pnpm docs:build` green、0 dead link。 +6. **停止条件**:修复结束即停止,不进入 10-49 审阅;不写 SUMMARY / ROADMAP / STATE;不改导览以外内容;不 commit。 +7. 本次修改方式为**派发子代理执行**;不得调用 `opencode` 命令;不得修改既有注释。 + +**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。 + 尚无产物;本任务只汇报三项修复范围、删除清单、计数、内联位置、注释规则与门禁。 + 确认:①只删 2 页 1 demo;②只补六处内联 TS;③全批无全局 client;④注释只加不改、无无信息注释;⑤25/24/25 计数与门禁;⑥修复结束即停止、不写 SUMMARY / ROADMAP / STATE、不 commit;⑦派发子代理。 + 回复「可以执行」以继续;其它回复视为未批准。 + 用户已回复「可以执行」,且删除范围、内联位置、client 取法、注释规则、计数与门禁、停止条件六项已确定。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,三项修复的范围、删除清单、内联位置、注释规则、计数门禁与停止条件均已确认。 + + 用户回复「可以执行」且待定项已定。 + + + + Task 1: 基线快照 + 删除 2 页 1 demo + 侧边栏 / 导览 / 篇号收口 + 六处内联 TS + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md, docs/advanced/ii/ui/ui-template-ts.md, docs/advanced/ii/ui/component-ts.md, docs/.vitepress/components/demos/ui/ts-component-demo.tsx, docs/.vitepress/config.ts, docs/advanced/ii/index.md, docs/advanced/index.md, docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md + `10-CUSTOM-UI-NOTES.md` 含 `用户确认(10-47):可以执行`;`10-47-SUMMARY.md` 存在;用户已在 Task 0 回复「可以执行」;`docs/advanced/ii/ui` 下当前 27 篇 `.md`、demos 下当前 25 个 `.tsx`。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、六 Part 顺序、参考哈希基线)、.planning/ROADMAP.md(Phase 10 的 `**Plans:**` 行与受保护行)、.planning/STATE.md(frontmatter)、docs/advanced/ii/index.md、docs/advanced/index.md、docs/.vitepress/config.ts、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/container-and-coordinates.md、docs/advanced/ii/ui/basic-shapes.md、docs/advanced/ii/ui/text.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/ui-controller-and-stack.md + **先写基线,再删除;哈希必须早于第一次删除。** + +**(1)向 NOTES 末尾追加 `## 10-48 pre-review 修复` 小节**,依次写入以下固定行(各独占一行,后续任务与 verify 按字面量断言): +1. `修复范围:` + `①删去 2 篇独立 TS 页与 1 个 TS demo 并内联 TS 片段;②去掉全局 client、改用 props.state;③给 25 篇正文代码块与 24 个 demo 补注释。` +2. `删除清单:` + `docs/advanced/ii/ui/ui-template-ts.md、docs/advanced/ii/ui/component-ts.md、docs/.vitepress/components/demos/ui/ts-component-demo.tsx`。 +3. `基线 HEAD(10-48 记录):` + `git rev-parse HEAD` 的完整 sha。 +4. `修复前 docs 快照哈希:` + 对 `docs/advanced/ii/ui` 下全部 `.md`(当前 27 篇)+ `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取哈希:按完整路径排序、逐个 `git hash-object -- `、用 `,` 拼接后取 SHA-256(小写 hex,64 位)。参考命令与 10-49 Task 1 相同。 +5. `修复前 demo 快照哈希:` + 对 `docs/.vitepress/components/demos/ui` 下全部 `.tsx`(当前 25 个)取哈希:按完整路径排序、逐个 `git hash-object -- `、用 `,` 拼接后取 SHA-256(小写 hex,64 位)。参考命令:`$demo = Get-ChildItem -Recurse -File -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx; $files = @($demo) | Sort-Object FullName; $joined = ($files | ForEach-Object { (git hash-object -- $_.FullName) }) -join ','; $sha = [BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($joined))).Replace('-','').ToLower()`。 +6. `ROADMAP 受保护行哈希:` + 对 ROADMAP 受保护行取 SHA-256(匹配 `^\s*-\s\[[ x]\]\s+10-(06|11|12)-PLAN\.md` 的三行,以及 `^\*\*10-42 增量说明:` 开头的一行;64 位小写 hex)。 +7. `ROADMAP 全文哈希:` + 对 `.planning/ROADMAP.md` 全文 UTF-8 字节取 SHA-256(64 位小写 hex)。 +8. `STATE 全文哈希:` + 对 `.planning/STATE.md` 全文 UTF-8 字节取 SHA-256(64 位小写 hex)。 + +**(2)删除文件**:删除 `docs/advanced/ii/ui/ui-template-ts.md`、`docs/advanced/ii/ui/component-ts.md`、`docs/.vitepress/components/demos/ui/ts-component-demo.tsx`。不得删除 `template-demo.tsx`(`ui-template.md` 仍在使用)。 + +**(3)侧边栏**:从 `docs/.vitepress/config.ts` 删除两个条目——`同一 UI 的 TS 元素层写法`(`/advanced/ii/ui/ui-template-ts`)与 `组件(TS 直调)`(`/advanced/ii/ui/component-ts`)。只删这两个条目,不改 6 个 Part 的标题与顺序,不删其它条目。 + +**(4)两页导览**: +- `docs/advanced/ii/index.md`:把「另有『自定义 UI 与渲染』子分组 27 篇」改为「25 篇」;把入口句改为只从 [UI 通用模板](./ui/ui-template.md) 开始,删去 `[同一 UI 的 TS 元素层写法](./ui/ui-template-ts.md)` 链接与「与」连接;把「第 21 篇」改为「第 19 篇」。 +- `docs/advanced/index.md`:把「第 21 篇」改为「第 19 篇」。该页没有 TS 页链接;若发现 `ui-template-ts` / `component-ts` 字样一并删除。 + +**(5)删除跨页链接**:`docs/advanced/ii/ui/container-and-coordinates.md` 末尾的「完整写法见[同一 UI 的 TS 元素层写法](./ui-template-ts.md)」改为「元素层的 `appendChild` 与 `removeChild` 可以在运行时增删子元素;日常布局仍然优先用 TSX 描述结构。」不得保留指向已删除页面的链接。 + +**(6)按删除后的顺序重排篇号引用**(删除 2 篇后 old→new 映射:3→2、4→3、5→4、6→5、7→6、8→7、9→8、10→9、11→10、12→11、13→12、14→13、16→14、17→15、18→16、19→17、20→18、21→19、22→20、23→21、24→22、25→23、26→24、27→25)。按下表逐条改,**不得全局替换数字**(22→20 与 20→18 会互相覆盖): +- `basic-shapes.md`:`第 10 篇「事件与交互」` → `第 9 篇「事件与交互」`。 +- `container-and-coordinates.md`:`第 8 篇「层级、变换与性能」` → `第 7 篇「层级、变换与性能」`。 +- `events.md`:`第 4 篇「基础图形」` → `第 3 篇「基础图形」`。 +- `inventory-example-1-skeleton.md`:`第 19 篇「UIController 与 UI 栈」` → `第 17 篇「UIController 与 UI 栈」`。 +- `inventory-example-2-grid.md`:`第 13 篇「props」` → `第 12 篇「props」`。 +- `inventory-example-6-animation-and-register.md`:`第 22 篇的结构` → `第 20 篇的结构`;`第 22 篇完全一致` → `第 20 篇完全一致`;`第 20 篇「修改 / 替换内置 UI」` → `第 18 篇「修改 / 替换内置 UI」`;`第 19 篇「UIController 与 UI 栈」` → `第 17 篇「UIController 与 UI 栈」`;`按第 21 篇的清单` → `按第 19 篇的清单`。 +- `layer-transform-performance.md`:`第 12 篇「条件渲染与循环渲染」` → `第 11 篇「条件渲染与循环渲染」`;`第 7 篇「图片与最小纹理」` → `第 6 篇「图片与最小纹理」`。 +- `reactivity.md`:`第 13 篇「props」` → `第 12 篇「props」`(按该页实际标题文字匹配)。 +- `slots-and-attrs.md`:`第 17 篇「内置组件:文本与输入」` → `第 15 篇「内置组件:文本与输入」`。 +- `text.md`:`第 17 篇「内置组件:文本与输入」` → `第 15 篇「内置组件:文本与输入」`。 +- `ui-performance.md`:`第 8 篇「层级、变换与性能」` → `第 7 篇「层级、变换与性能」`;`第 12 篇「条件渲染与循环渲染」` → `第 11 篇「条件渲染与循环渲染」`;`第 7 篇「图片与最小纹理」` → `第 6 篇「图片与最小纹理」`。 + +**(7)六处内联 TS 元素层演示**(只加 `ts` 代码块,不写 Vue 组件、不写类型标注、不要求运行;每段不超过 20 行;先写简短注释,Task 3 再补足): +- `ui-template.md`:在第一个 TSX 模板代码块之后、「代码里只有三个元素」之前,加一段:`new Container()` 设 `loc(0, 0, 480, 320)`,`new Rect()` 设 `pos` / `size` / `setFillStyle`,`new Text()` 设 `pos` / `setText` / `setStyle`,最后 `appendChild(rect, text)`。 +- `container-and-coordinates.md`:在「一个嵌套示例」的 TSX 代码块之后,加一段:创建根容器与子容器,用 `pos` / `size` 设几何,用 `appendChild` 挂子容器与矩形,说明子元素坐标相对父容器。 +- `basic-shapes.md`:在「四个图形」一节的 TSX 示例之后,加一段:`new Rect()`、`new Circle()`、`new Ellipse()`、`new Line()` 各设几何与填充 / 描边;类名以该页已用元素对应的元素层类为准。 +- `text.md`:在「一行文字」的 TSX 代码块之后,加一段:`new Text()` 设 `pos`、`setText`、`setStyle`、`setFont(new Font(...))`。 +- `component-tsx.md`:在「一个完整组件的结构」的 TSX 代码块之后、「各段职责固定」之前,加一段:不用 `defineComponent`,直接用 `Container`、`Rect`、`Text` 搭出与 `ItemCell` 相同的画面,并用 `appendChild` 组合。 +- `ui-controller-and-stack.md`:在「场景 UI 与主 UI」的表格之后,加一段:`props.state.sceneController.open(TitleUI, {})`、`props.state.mainUIController.open(InventoryUI, {})`、`props.state.mainUIController.close(instance)`;注释说明两个控制器都来自 `props.state`,没有全局 `client`。 + +**(8)本任务只做上述删改与内联,不补全量注释、不改 `client` 的其它出现(Task 2 处理)、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。** 完成后在 NOTES 的 `## 10-48 pre-review 修复` 下追加 `删除完成:3 个文件` 与 `页面计数(删除后):25`、`demo 计数(删除后):24`。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); foreach($k in @('## 10-48 pre-review 修复','修复范围:','删除清单:','基线 HEAD(10-48 记录):','修复前 docs 快照哈希:','修复前 demo 快照哈希:','ROADMAP 受保护行哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','删除完成:3 个文件','页面计数(删除后):25','demo 计数(删除后):24')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-48 记录):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('修复前 docs 快照哈希','修复前 demo 快照哈希','ROADMAP 受保护行哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; foreach($d in @('docs/advanced/ii/ui/ui-template-ts.md','docs/advanced/ii/ui/component-ts.md','docs/.vitepress/components/demos/ui/ts-component-demo.tsx')){ if(Test-Path -LiteralPath $d){ Write-Error "NOT-DELETED $d" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:' + $md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:' + $demo.Count) }; $cfg=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/.vitepress/config.ts')); $cfgLinks=([regex]::Matches($cfg,'/advanced/ii/ui/[a-z0-9-]+')).Count; if($cfgLinks -ne 25){ Write-Error ('CFG-COUNT:' + $cfgLinks) }; if($cfg -match 'ui-template-ts|/advanced/ii/ui/component-ts[\x27\x22]'){ Write-Error 'CFG-STILL-TS' }; $idx=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/index.md')); if($idx -match 'ui-template-ts|27 篇'){ Write-Error 'INDEX-STILL-OLD' }; if($idx.IndexOf('25 篇') -lt 0){ Write-Error 'INDEX-NO-25' }; $top=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/index.md')); if($top -match 'ui-template-ts|component-ts'){ Write-Error 'TOP-STILL-TS' }; $all=Get-ChildItem docs -Recurse -File -Include *.md,*.ts | Select-String -Pattern 'ui-template-ts|component-ts\.md|/advanced/ii/ui/component-ts(?!x)' ; if($all){ $all | ForEach-Object { Write-Output $_.Path }; Write-Error 'STILL-REFERENCE-DELETED' }; $cc=[IO.File]::ReadAllText((Resolve-Path -LiteralPath 'docs/advanced/ii/ui/container-and-coordinates.md')); if($cc -match 'ui-template-ts'){ Write-Error 'CONTAINER-STILL-LINK' }; foreach($pair in @(@('docs/advanced/ii/ui/basic-shapes.md','第 10 篇「事件与交互」','第 9 篇「事件与交互」'),@('docs/advanced/ii/ui/container-and-coordinates.md','第 8 篇「层级、变换与性能」','第 7 篇「层级、变换与性能」'),@('docs/advanced/ii/ui/events.md','第 4 篇「基础图形」','第 3 篇「基础图形」'),@('docs/advanced/ii/ui/inventory-example-1-skeleton.md','第 19 篇「UIController 与 UI 栈」','第 17 篇「UIController 与 UI 栈」'),@('docs/advanced/ii/ui/inventory-example-2-grid.md','第 13 篇「props」','第 12 篇「props」'),@('docs/advanced/ii/ui/layer-transform-performance.md','第 12 篇「条件渲染与循环渲染」','第 11 篇「条件渲染与循环渲染」'),@('docs/advanced/ii/ui/slots-and-attrs.md','第 17 篇「内置组件:文本与输入」','第 15 篇「内置组件:文本与输入」'),@('docs/advanced/ii/ui/text.md','第 17 篇「内置组件:文本与输入」','第 15 篇「内置组件:文本与输入」'),@('docs/advanced/ii/ui/ui-performance.md','第 8 篇「层级、变换与性能」','第 7 篇「层级、变换与性能」')){ $p=$pair[0]; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t.IndexOf($pair[1]) -ge 0){ Write-Error ("OLD-REF:" + $p + ":" + $pair[1]) }; if($t.IndexOf($pair[2]) -lt 0){ Write-Error ("NEW-REF-MISSING:" + $p + ":" + $pair[2]) } }; foreach($p in @('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/ui-controller-and-stack.md')){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -notmatch '(?m)^```ts\s*$'){ Write-Error ("NO-INLINE-TS:" + $p) } }; 'T1-OK' + non-zero exit, or output contains "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NOT-DELETED", "MD-COUNT", "DEMO-COUNT", "CFG-COUNT", "CFG-STILL-TS", "INDEX-STILL-OLD", "INDEX-NO-25", "TOP-STILL-TS", "STILL-REFERENCE-DELETED", "CONTAINER-STILL-LINK", "OLD-REF", "NEW-REF-MISSING", "NO-INLINE-TS"; or output lacks "T1-OK" + + NOTES 的 `## 10-48 pre-review 修复` 含基线八行(修复范围、删除清单、基线 HEAD、修复前 docs 快照、修复前 demo 快照、ROADMAP 受保护行、ROADMAP 全文、STATE 全文)与 `删除完成:3 个文件`、`页面计数(删除后):25`、`demo 计数(删除后):24`;3 个文件已删除;`docs/advanced/ii/ui` 恰好 25 篇、demos 恰好 24 个;配置 25 条 UI 链接且无 TS 页条目;两页导览无 TS 页链接、`ii/index` 为 25 篇;六处已加 `ts` 内联片段;篇号引用按映射更新;未改 ROADMAP / STATE。 + 删除、侧边栏 / 导览 / 篇号收口与六处内联 TS 完成,基线已落盘。 + + + + Task 2: 去掉全局 client,全批改为 props.state,并补模板 / UIController 文案 + docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md + Task 1 已删除 2 页 1 demo 并完成计数收口;当前 25 篇正文已落盘。 + docs/advanced/ii/ui/ui-template.md(打开与关闭一节)、docs/advanced/ii/ui/ui-controller-and-stack.md(场景 UI 与主 UI 表)、docs/advanced/ii/ui/inventory-example-1-skeleton.md(打开处)、packages-user/client-base/src/types.ts(`IGameUIPropsBase.state` 与 `IClientBase.sceneController` / `mainUIController`,只读确认 `props.state` 可用) + **先全批扫描,再逐处替换;不得保留全局 `client`。** + +1. 用 `Get-ChildItem docs/advanced/ii/ui -Filter *.md | Select-String -Pattern '(? + + $ErrorActionPreference='Stop'; $hits=@(Get-ChildItem docs/advanced/ii/ui -Filter *.md -File | Select-String -Pattern '(? + non-zero exit, or output contains "GLOBAL-CLIENT-REMAINS", "NO-PROPS-STATE", "TPL-NO-GLOBAL-NOTE", "CTL-NO-GLOBAL-NOTE"; or output lacks "T2-OK" + + 25 篇正文无 `client.` 成员访问(`@user/client-base` 包名除外);`ui-template.md`、`ui-controller-and-stack.md`、`inventory-example-1-skeleton.md` 含 `props.state.sceneController`;模板与 controller 篇含「没有全局」说明与 `props.state` 取法;未引入新的局部 `client` 变量;未改 ROADMAP / STATE。 + 全批去掉全局 client,模板与 UIController 篇文案已说明 props.state 取法。 + + + + Task 3: Part 0–1 的 7 篇正文与 7 个 demo 补注释(只加注释) + docs/advanced/ii/ui/ui-template.md, docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, docs/.vitepress/components/demos/ui/template-demo.tsx, docs/.vitepress/components/demos/ui/container-demo.tsx, docs/.vitepress/components/demos/ui/shapes-demo.tsx, docs/.vitepress/components/demos/ui/curves-demo.tsx, docs/.vitepress/components/demos/ui/text-demo.tsx, docs/.vitepress/components/demos/ui/texture-demo.tsx, docs/.vitepress/components/demos/ui/layer-demo.tsx, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1 与 Task 2 已完成(25 篇收口、`client` 已替换、六处内联 TS 已加);本任务开始前未补过注释。 + dev.md(注释规范:`// ` 空格、只写有价值注释、不得修改既有注释、CRLF)、docs/advanced/ii/ui/ui-template.md、docs/advanced/ii/ui/container-and-coordinates.md、docs/advanced/ii/ui/basic-shapes.md、docs/advanced/ii/ui/curves-and-paths.md、docs/advanced/ii/ui/text.md、docs/advanced/ii/ui/image-and-texture.md、docs/advanced/ii/ui/layer-transform-performance.md、对应 7 个 demo + **先记录去注释代码哈希,再只加整行注释。** + +**(1)记录基线**:先对 7 篇正文与 7 个 demo 跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,让基线处于格式化状态;再按以下算法计算聚合哈希并写入 NOTES 的 `## 10-48 pre-review 修复` 下: +- 单文件代码内容 = 文件文本删除所有匹配 `^\s*//.*$` 的行与匹配 `^\s*\{/\*.*\*/\}\s*$` 的行(只删整行注释;不动行内代码)。 +- 单文件哈希 = 对代码内容的 UTF-8 字节取 SHA-256(小写 hex)。 +- 聚合哈希 = 对「按完整路径排序后的 `path:单文件哈希` 用换行拼接」取 SHA-256(小写 hex,64 位)。 +- 写入独占一行 `Part 0-1 注释前代码哈希:<64 位 hex>`。 + +**(2)补注释**(只新增整行 `//` 或单行 `{/* ... */}`,不得写行尾注释、不得改既有注释、不得改任何非注释代码): +- 每段代码块至少一条注释;超过 15 行的代码块至少 3 条,按逻辑段说明「这段在做什么、为什么这样做、关键属性 / 参数从哪里来」。 +- 注释必须有信息量:说明目的、关键步骤、关键属性 / 参数 / 生命周期;禁止「// 设置属性」「// 定义变量」「// 循环」这类复述代码的注释(`dev.md` 注释规范)。 +- 正文页面重点:`ui-template.md` 说明 Props 基类 / props 列表 / GameUI 注册 / 内联 TS 的等价关系;`container-and-coordinates.md` 说明原点、父容器相对坐标、锚点与 `appendChild`;`basic-shapes.md` 说明四个图形的几何参数、`fill` / `stroke` 是模式开关、`actionStroke` 只改命中;`curves-and-paths.md` 说明控制点与路径构造;`text.md` 说明字体构造、锚点居中、不会自动换行;`image-and-texture.md` 说明纹理创建时机与释放;`layer-transform-performance.md` 说明 `zIndex`、变换与缓存边界。 +- demo 重点:文件头说明这个 live 演示什么;`ref` / `computed` / `onMounted` / `onUnmounted` 处说明生命周期与清理;事件处理处说明触发条件;纹理 / 定时器 / 监听必须有对应释放注释。 +- 对已经存在的注释逐字保留;需要补充时在相邻位置新增,不改原文。 + +**(3)复核**:再跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,然后按同一算法计算聚合哈希,写入独占一行 `Part 0-1 注释后代码哈希:<64 位 hex>`;该值必须与 `Part 0-1 注释前代码哈希:` 完全相同。若不同,说明改到了非注释代码或 prettier 重排了代码,必须回退该处再重算,不得只改哈希值。 + +**(4)本任务不跑构建、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。** + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $m1=[regex]::Match($np,'(?m)^Part 0-1 注释前代码哈希:([0-9a-f]{64})'); $m2=[regex]::Match($np,'(?m)^Part 0-1 注释后代码哈希:([0-9a-f]{64})'); if(-not $m1.Success -or -not $m2.Success){ Write-Error 'NO-PART01-HASH' }; if($m1.Groups[1].Value -ne $m2.Groups[1].Value){ Write-Error 'PART01-CODE-CHANGED' }; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); $demos=@('template-demo','container-demo','shapes-demo','curves-demo','text-demo','texture-demo','layer-demo'); $js='const fs=require("fs");const pages=' + ($pages | ConvertTo-Json -Compress) + ';const demos=' + ($demos | ConvertTo-Json -Compress) + ';const bad=[];const isC=l=>/^\s*\/\//.test(l)||/^\s*\{\/\*.*\*\/\}\s*$/.test(l);pages.forEach(f=>{const s=fs.readFileSync(f,"utf8");const re=/```[^\n]*\r?\n([\s\S]*?)```/g;let m;let i=0;while((m=re.exec(s))){i++;const lines=m[1].split(/\r?\n/);const code=lines.filter(l=>l.trim()!=="");const cs=code.filter(isC).length;if(cs<1)bad.push("BLOCK-NO-COMMENT:"+f+":"+i);if(code.length>15&&cs<3)bad.push("BLOCK-FEW-COMMENTS:"+f+":"+i);}});demos.forEach(d=>{const f="docs/.vitepress/components/demos/ui/"+d+".tsx";const lines=fs.readFileSync(f,"utf8").split(/\r?\n/);const cs=lines.filter(isC).length;const need=lines.length>200?6:(lines.length>80?4:2);if(cs + non-zero exit, or output contains "NO-PART01-HASH", "PART01-CODE-CHANGED", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "COMMENT-ASSERT-FAIL"; or output lacks "T3-OK" + + Part 0–1 的 7 篇正文每个代码块至少一条有价值注释、超 15 行的块至少 3 条;7 个 demo 按长度至少有 2 / 4 / 6 条注释;NOTES 有 `Part 0-1 注释前代码哈希` 与 `Part 0-1 注释后代码哈希` 且两者相同;既有注释逐字未改;未改任何非注释代码;CRLF 与 prettier 后续可过。 + Part 0–1 的 7 篇正文与 7 个 demo 注释补齐,代码哈希未变。 + + + + Task 4: Part 2–5 的 18 篇正文与 17 个 demo 补注释(只加注释) + docs/advanced/ii/ui/reactivity.md, docs/advanced/ii/ui/events.md, docs/advanced/ii/ui/hotkey-in-ui.md, docs/advanced/ii/ui/conditional-and-list-rendering.md, docs/advanced/ii/ui/props.md, docs/advanced/ii/ui/component-tsx.md, docs/advanced/ii/ui/slots-and-attrs.md, docs/advanced/ii/ui/builtin-text-and-input.md, docs/advanced/ii/ui/builtin-list-and-containers.md, docs/advanced/ii/ui/ui-controller-and-stack.md, docs/advanced/ii/ui/replace-builtin-ui.md, docs/advanced/ii/ui/ui-performance.md, docs/advanced/ii/ui/inventory-example-1-skeleton.md, docs/advanced/ii/ui/inventory-example-2-grid.md, docs/advanced/ii/ui/inventory-example-3-detail.md, docs/advanced/ii/ui/inventory-example-4-scroll.md, docs/advanced/ii/ui/inventory-example-5-state.md, docs/advanced/ii/ui/inventory-example-6-animation-and-register.md, docs/.vitepress/components/demos/ui/reactivity-demo.tsx, docs/.vitepress/components/demos/ui/events-demo.tsx, docs/.vitepress/components/demos/ui/conditional-demo.tsx, docs/.vitepress/components/demos/ui/props-demo.tsx, docs/.vitepress/components/demos/ui/component-demo.tsx, docs/.vitepress/components/demos/ui/slots-demo.tsx, docs/.vitepress/components/demos/ui/builtin-text-demo.tsx, docs/.vitepress/components/demos/ui/builtin-list-demo.tsx, docs/.vitepress/components/demos/ui/controller-demo.tsx, docs/.vitepress/components/demos/ui/strategy-demo.tsx, docs/.vitepress/components/demos/ui/perf-demo.tsx, docs/.vitepress/components/demos/ui/inventory-1-skeleton.tsx, docs/.vitepress/components/demos/ui/inventory-2-grid.tsx, docs/.vitepress/components/demos/ui/inventory-3-detail.tsx, docs/.vitepress/components/demos/ui/inventory-4-scroll.tsx, docs/.vitepress/components/demos/ui/inventory-5-state.tsx, docs/.vitepress/components/demos/ui/inventory-6-full.tsx, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 3 已完成并写入 `Part 0-1 注释后代码哈希`;任务开始前 Part 2–5 未补过注释。 + dev.md(注释规范)、docs/advanced/ii/ui/reactivity.md、docs/advanced/ii/ui/events.md、docs/advanced/ii/ui/hotkey-in-ui.md、docs/advanced/ii/ui/conditional-and-list-rendering.md、docs/advanced/ii/ui/props.md、docs/advanced/ii/ui/component-tsx.md、docs/advanced/ii/ui/slots-and-attrs.md、docs/advanced/ii/ui/builtin-text-and-input.md、docs/advanced/ii/ui/builtin-list-and-containers.md、docs/advanced/ii/ui/ui-controller-and-stack.md、docs/advanced/ii/ui/replace-builtin-ui.md、docs/advanced/ii/ui/ui-performance.md、六个 inventory 示例页与对应 17 个 demo + **先记录去注释代码哈希,再只加整行注释。** + +**(1)记录基线**:先对 18 篇正文与 17 个 demo 跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`;再使用与 Task 3 完全相同的算法(删除整行 `//` 与单行 `{/* ... */}` 注释后计算单文件 SHA-256,再对排序后的 `path:hash` 取聚合 SHA-256),写入独占一行 `Part 2-5 注释前代码哈希:<64 位 hex>`。 + +**(2)补注释**(规则与 Task 3 相同:只新增整行 `//` 或单行 `{/* ... */}`;不改既有注释;不改非注释代码;禁止无信息注释): +- `reactivity.md`:说明哪些值需要 `ref` / `computed`、何时触发重渲染、为什么不要在渲染函数里做重活。 +- `events.md`:说明事件绑定位置、参数来源、命中与 `actionStroke` 的关系、阻止冒泡 / 清理监听的边界。 +- `hotkey-in-ui.md`:说明 `useKey` 取到的按键系统、分组注册与注销的时机。 +- `conditional-and-list-rendering.md`:说明 `v-if` / `v-for` 在本框架中的等价写法、列表 key 的使用边界(`dev.md`:仅重排 / 插入 / 删除且需要保留身份时用)。 +- `props.md`:说明 Props 接口、`SetupComponentOptions`、默认值与响应式读取。 +- `component-tsx.md`:说明六段结构、`computed`、`emit` / `expose` 与生命周期;内联 TS 片段说明与 TSX 的等价关系。 +- `slots-and-attrs.md`:说明透传内容与属性的边界、什么时候需要插槽。 +- `builtin-text-and-input.md`、`builtin-list-and-containers.md`:说明内置组件的 props、暴露方法、数据来源与容器组合方式。 +- `ui-controller-and-stack.md`:说明四层模型、`open` / `close` / `hide` / `show`、显示策略、背景 `keep`、两个控制器都来自 `props.state`。 +- `replace-builtin-ui.md`:说明替换发生在打开处或包装层、为什么没有全局注册入口。 +- `ui-performance.md`:说明缓存、显示策略与引擎级性能边界。 +- 六个 inventory 页面:说明每一步新增的文件、组件职责、共享状态与注册 / 打开时机。`inventory-example-6-animation-and-register.md` 的 `text` 文件结构块在首行加 `// 目录结构:五个文件各负责一段`,不改树本身;该块的注释只用于说明结构,不引入代码。 +- 17 个 demo:文件头说明演示目标;`ref` / `computed` / `onMounted` / `onUnmounted` / 事件处理 / 定时器 / 纹理创建处说明生命周期与清理;长 demo(>200 行)至少 6 条,80–200 行至少 4 条,≤80 行至少 2 条。 + +**(3)复核**:再跑一次 `cmd /c "pnpm exec prettier --write <这些文件>"`,重新计算聚合并写入 `Part 2-5 注释后代码哈希:<64 位 hex>`;必须与 `Part 2-5 注释前代码哈希:` 完全相同。不同则回退非注释改动后重算。 + +**(4)本任务不跑构建、不改 ROADMAP / STATE、不写 SUMMARY、不 commit。** + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $m1=[regex]::Match($np,'(?m)^Part 2-5 注释前代码哈希:([0-9a-f]{64})'); $m2=[regex]::Match($np,'(?m)^Part 2-5 注释后代码哈希:([0-9a-f]{64})'); if(-not $m1.Success -or -not $m2.Success){ Write-Error 'NO-PART25-HASH' }; if($m1.Groups[1].Value -ne $m2.Groups[1].Value){ Write-Error 'PART25-CODE-CHANGED' }; $pages=@('docs/advanced/ii/ui/reactivity.md','docs/advanced/ii/ui/events.md','docs/advanced/ii/ui/hotkey-in-ui.md','docs/advanced/ii/ui/conditional-and-list-rendering.md','docs/advanced/ii/ui/props.md','docs/advanced/ii/ui/component-tsx.md','docs/advanced/ii/ui/slots-and-attrs.md','docs/advanced/ii/ui/builtin-text-and-input.md','docs/advanced/ii/ui/builtin-list-and-containers.md','docs/advanced/ii/ui/ui-controller-and-stack.md','docs/advanced/ii/ui/replace-builtin-ui.md','docs/advanced/ii/ui/ui-performance.md','docs/advanced/ii/ui/inventory-example-1-skeleton.md','docs/advanced/ii/ui/inventory-example-2-grid.md','docs/advanced/ii/ui/inventory-example-3-detail.md','docs/advanced/ii/ui/inventory-example-4-scroll.md','docs/advanced/ii/ui/inventory-example-5-state.md','docs/advanced/ii/ui/inventory-example-6-animation-and-register.md'); $demos=@('reactivity-demo','events-demo','conditional-demo','props-demo','component-demo','slots-demo','builtin-text-demo','builtin-list-demo','controller-demo','strategy-demo','perf-demo','inventory-1-skeleton','inventory-2-grid','inventory-3-detail','inventory-4-scroll','inventory-5-state','inventory-6-full'); $js='const fs=require("fs");const pages=' + ($pages | ConvertTo-Json -Compress) + ';const demos=' + ($demos | ConvertTo-Json -Compress) + ';const bad=[];const isC=l=>/^\s*\/\//.test(l)||/^\s*\{\/\*.*\*\/\}\s*$/.test(l);pages.forEach(f=>{const s=fs.readFileSync(f,"utf8");const re=/```[^\n]*\r?\n([\s\S]*?)```/g;let m;let i=0;while((m=re.exec(s))){i++;const lines=m[1].split(/\r?\n/);const code=lines.filter(l=>l.trim()!=="");const cs=code.filter(isC).length;if(cs<1)bad.push("BLOCK-NO-COMMENT:"+f+":"+i);if(code.length>15&&cs<3)bad.push("BLOCK-FEW-COMMENTS:"+f+":"+i);}});demos.forEach(d=>{const f="docs/.vitepress/components/demos/ui/"+d+".tsx";const lines=fs.readFileSync(f,"utf8").split(/\r?\n/);const cs=lines.filter(isC).length;const need=lines.length>200?6:(lines.length>80?4:2);if(cs + non-zero exit, or output contains "NO-PART25-HASH", "PART25-CODE-CHANGED", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "COMMENT-ASSERT-FAIL"; or output lacks "T4-OK" + + Part 2–5 的 18 篇正文每个代码块至少一条有价值注释、超 15 行的块至少 3 条;17 个 demo 按长度至少有 2 / 4 / 6 条注释;NOTES 有 `Part 2-5 注释前代码哈希` 与 `Part 2-5 注释后代码哈希` 且两者相同;既有注释逐字未改;未改任何非注释代码。 + Part 2–5 的 18 篇正文与 17 个 demo 注释补齐,代码哈希未变。 + + + + Task 5: 门禁(prettier / ESLint / docs 类型 / 构建 / 25 HTML / 静态断言 / 哈希)+ NOTES 记录 + 停止 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1–4 已完成;NOTES 含删除清单、25/24 计数、两组注释代码哈希;`client` 已清零;六处内联 TS 已加。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-48 pre-review 修复` 全部基线)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/index.md、docs/.vitepress/config.ts + **顺序不可颠倒;本任务只校验与记录,不改正文内容(prettier 格式化除外)。** + +1. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii docs/.vitepress/components/demos/ui docs/.vitepress/config.ts docs/advanced/index.md"`,再跑同路径 `--check`。 +2. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 exit 0 且输出无 `error` / `warning`。 +3. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,只要求 `docs/` 路径 0 个 `error TS`;既有引擎报错不计入本次失败,但要记录条数。 +4. **静态断言**:25 篇 `.md`、24 个 `.tsx`;3 个被删文件不存在;全批无 `client.` 成员访问、无 `ui-template-ts` / `component-ts.md` 引用;配置 25 条 UI 链接;`ii/index` 含 `25 篇`、无 `27 篇`;25 篇与 24 个 demo 的每段代码块都有注释;所有 `.md` 与 `.tsx` 为 CRLF;25 篇均有单 H1 与 `## 边界与注意`;24 个 demo 均有 `export default` 且无 `style=` / `class=` DOM 属性。 +5. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,要求 exit 0、输出含 `build complete`、不含 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。 +6. **哈希复核**:重算 `ROADMAP 受保护行哈希`、`ROADMAP 全文哈希`、`STATE 全文哈希`,必须与 Task 1 基线逐字相同;重算 `Part 0-1` 与 `Part 2-5` 的去注释聚合哈希,必须与 NOTES 记录的「注释前 / 注释后」一致。 +7. **写 NOTES**:在 `## 10-48 pre-review 修复` 下追加: + - `修复后 docs 快照哈希:` + 25 篇 UI 正文 + 两页导览按 Task 1 算法重算的 SHA-256。 + - `修复后 demo 快照哈希:` + 24 个 demo 按 Task 1 算法重算的 SHA-256。 + - `页面计数:25`、`demo 计数:24`、`构建产物:25`。 + - `10-48 门禁:prettier 通过;ESLint 0/0;docs 类型 0 报错;构建 green;0 dead link;25 HTML;静态断言通过。` + - `停止点:10-48 修复结束,未进入 10-49 独立审阅;未改 ROADMAP / STATE;未写 SUMMARY;未 commit。` +8. **立即停止**:不创建 `10-48-SUMMARY.md` / `10-49-READER-REVIEW.md` / `10-50-USER-REVIEW.md` / 任何 SUMMARY,不进入读者审阅,不改 ROADMAP / STATE,不 commit。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); foreach($k in @('修复后 docs 快照哈希:','修复后 demo 快照哈希:','页面计数:25','demo 计数:24','构建产物:25','10-48 门禁:','停止点:10-48 修复结束')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; foreach($h in @('修复后 docs 快照哈希','修复后 demo 快照哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; if($np -notmatch '(?m)^基线 HEAD(10-48 记录):[0-9a-f]{7,40}'){ Write-Error 'NO-BASE-HEAD' }; $baseDocs=[regex]::Match($np,'(?m)^修复前 docs 快照哈希:([0-9a-f]{64})'); if(-not $baseDocs.Success){ Write-Error 'NO-PRE-DOCS' }; $baseDemo=[regex]::Match($np,'(?m)^修复前 demo 快照哈希:([0-9a-f]{64})'); if(-not $baseDemo.Success){ Write-Error 'NO-PRE-DEMO' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:' + $md.Count) }; if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:' + $demo.Count) }; foreach($d in @('docs/advanced/ii/ui/ui-template-ts.md','docs/advanced/ii/ui/component-ts.md','docs/.vitepress/components/demos/ui/ts-component-demo.tsx')){ if(Test-Path -LiteralPath $d){ Write-Error "NOT-DELETED $d" } }; $hits=@(Get-ChildItem docs/advanced/ii/ui -Filter *.md -File | Select-String -Pattern '(?s.split(/\r?\n/).filter(l=>!/^\s*\/\//.test(l)&&!/^\s*\{\/\*.*\*\/\}\s*$/.test(l)).join("\n");const h=s=>crypto.createHash("sha256").update(s,"utf8").digest("hex");const agg=fs=>h(fs.slice().sort().map(f=>f+":"+h(strip(fs.readFileSync(f,"utf8")))).join("\n"));const np=fs.readFileSync(".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md","utf8");const get=k=>{const m=new RegExp("^"+k+":([0-9a-f]{64})","m").exec(np);return m?m[1]:""};const bad=[];if(get("Part 0-1 注释前代码哈希")!==agg(p01))bad.push("PART01-PRE-RECOMPUTE");if(get("Part 0-1 注释后代码哈希")!==agg(p01))bad.push("PART01-POST-RECOMPUTE");if(get("Part 2-5 注释前代码哈希")!==agg(p25))bad.push("PART25-PRE-RECOMPUTE");if(get("Part 2-5 注释后代码哈希")!==agg(p25))bad.push("PART25-POST-RECOMPUTE");const isC=l=>/^\s*\/\//.test(l)||/^\s*\{\/\*.*\*\/\}\s*$/.test(l);const pages=[...p01.filter(f=>/\.md$/.test(f)),...p25.filter(f=>/\.md$/.test(f))];pages.forEach(f=>{const s=fs.readFileSync(f,"utf8");const re=/```[^\n]*\r?\n([\s\S]*?)```/g;let m;let i=0;while((m=re.exec(s))){i++;const code=m[1].split(/\r?\n/).filter(l=>l.trim()!=="");const cs=code.filter(isC).length;if(cs<1)bad.push("BLOCK-NO-COMMENT:"+f+":"+i);if(code.length>15&&cs<3)bad.push("BLOCK-FEW-COMMENTS:"+f+":"+i);}});const demos=[...p01.filter(f=>/\.tsx$/.test(f)),...p25.filter(f=>/\.tsx$/.test(f))];demos.forEach(f=>{const lines=fs.readFileSync(f,"utf8").split(/\r?\n/);const cs=lines.filter(isC).length;const need=lines.length>200?6:(lines.length>80?4:2);if(cs&1; if($LASTEXITCODE -ne 0){ $pw | Write-Output; Write-Error 'PRETTIER-WRITE-FAIL' }; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not ($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:' + $built.Count) }; $roadText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/ROADMAP.md')); $roadHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($roadText))).Replace('-','').ToLower(); $mr=[regex]::Match($np,'(?m)^ROADMAP 全文哈希:([0-9a-f]{64})'); if(-not $mr.Success){ Write-Error 'NO-ROADMAP-HASH' } elseif($mr.Groups[1].Value -ne $roadHash){ Write-Error 'ROADMAP-MODIFIED' }; $stText=[IO.File]::ReadAllText((Resolve-Path -LiteralPath '.planning/STATE.md')); $stHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($stText))).Replace('-','').ToLower(); $ms=[regex]::Match($np,'(?m)^STATE 全文哈希:([0-9a-f]{64})'); if(-not $ms.Success){ Write-Error 'NO-STATE-HASH' } elseif($ms.Groups[1].Value -ne $stHash){ Write-Error 'STATE-MODIFIED' }; $prot=@(Get-Content -LiteralPath '.planning/ROADMAP.md' | Where-Object { $_ -match '^\s*-\s\[[ x]\]\s+10-(06|11|12)-PLAN\.md' -or $_ -match '^\*\*10-42 增量说明:' }) -join "`n"; $protHash=[BitConverter]::ToString([Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($prot))).Replace('-','').ToLower(); $mp=[regex]::Match($np,'(?m)^ROADMAP 受保护行哈希:([0-9a-f]{64})'); if(-not $mp.Success){ Write-Error 'NO-PROTECTED-HASH' } elseif($mp.Groups[1].Value -ne $protHash){ Write-Error 'ROADMAP-PROTECTED-CHANGED' }; foreach($s in @('10-48-SUMMARY.md','10-49-SUMMARY.md','10-50-SUMMARY.md')){ if(Test-Path -LiteralPath ('.planning/phases/10-docs-restructure/' + $s)){ Write-Error ('UNEXPECTED-SUMMARY:' + $s) } }; 'T5-OK' + non-zero exit, or output contains "NOTES-MISSING", "BAD-HASH", "NO-BASE-HEAD", "NO-PRE-", "MD-COUNT", "DEMO-COUNT", "NOT-DELETED", "GLOBAL-CLIENT-REMAINS", "CFG-COUNT", "CFG-STILL-TS", "INDEX-STILL-OLD", "INDEX-NO-25", "PART01-", "PART25-", "BLOCK-NO-COMMENT", "BLOCK-FEW-COMMENTS", "DEMO-FEW-COMMENTS", "DEMO-DEFAULT", "DEMO-DOM", "CODE-HASH-ASSERT-FAIL", "PRETTIER-", "ESLINT-", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "ROADMAP-MODIFIED", "STATE-MODIFIED", "NO-ROADMAP-HASH", "NO-STATE-HASH", "NO-PROTECTED-HASH", "ROADMAP-PROTECTED-CHANGED", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK" + + prettier `--write` / `--check` 通过;ESLint 0/0;`docs/` 路径 0 类型错误;构建 green、`build complete`、0 dead link;`public/_docs/advanced/ii/ui` 恰好 25 个 HTML;25 篇 / 24 demo / 25 条侧边栏;3 个文件已删;全批无全局 `client`、无被删页引用;每段代码块与每个 demo 有注释;两组去注释代码哈希重算一致;ROADMAP / STATE 全文与受保护行哈希未变;NOTES 有 `修复后 docs / demo 快照哈希`、`页面计数:25`、`demo 计数:24`、`构建产物:25`、`10-48 门禁:`、`停止点:10-48 修复结束...`;未创建任何 SUMMARY。 + 三项修复完成并通过全部门禁,10-48 在审阅前停止。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 修复 → 已验收正文 | 只允许三项修复;其它语义与示例结构不得改动 | +| 删除 → 侧边栏 / 导览 / 交叉引用 | 删除页面后必须同步所有入口与篇号,否则出现 404 或错误指代 | +| 内联 TS → 页面结构 | 只能追加代码块,不得新增独立页面 / demo / live | +| 注释 → 代码行为 | 只新增整行注释;非注释代码不得改变 | +| 10-48 → 账本 | 不写 SUMMARY / ROADMAP / STATE、不 commit | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-162 | Tampering | 删除范围 | high | mitigate | 明确只删 2 页 1 demo;Task 1 / 5 校验 MD=25、DEMO=24、被删文件不存在 | +| T-10-163 | Tampering | 内联 TS 变成新页面 / demo | high | mitigate | 只允许六处 `ts` 代码块;Task 5 校验文件计数与无新增 demo | +| T-10-164 | Spoofing | 全局 `client` 残留 | high | mitigate | Task 2 全批扫描 `(? + + +- 关卡门禁:Task 0 已获「可以执行」;NOTES 含 `用户确认(10-47):可以执行`。 +- 删除门禁:只删 2 页 1 demo;`docs/advanced/ii/ui` 恰好 25 篇、demos 恰好 24 个;侧边栏 25 条;两页导览无被删链接;篇号引用按映射更新。 +- 内联门禁:六处 `ts` 代码块存在;未新增页面 / demo / live。 +- client 门禁:25 篇无 `client.` 成员访问;模板与 UIController 篇说明 `props.state` 与「没有全局 client」。 +- 注释门禁:25 篇每段代码块至少一条有价值注释、超 15 行至少 3 条;24 个 demo 按长度至少 2 / 4 / 6 条;既有注释逐字未改。 +- 行为门禁:Part 0-1 与 Part 2-5 的去注释聚合哈希在注释前后一致,且 Task 5 重算一致;prettier 只做格式化。 +- 构建门禁:prettier `--check`、ESLint 0/0、`docs/` 路径 0 类型错误、`pnpm docs:build` green + `build complete` + 0 dead link、25 个 HTML。 +- 越界门禁:ROADMAP / STATE 全文与受保护行哈希与 Task 1 一致;未创建任何 SUMMARY;未改 `packages*` / `src`;未 commit。 +- 停止门禁:NOTES 有 `停止点:10-48 修复结束,未进入 10-49 独立审阅;未改 ROADMAP / STATE;未写 SUMMARY;未 commit。` + + + +- 独立 TS 页与 TS demo 已删除,六处内联 TS 片段就位,全批为 25 篇正文 / 24 个 demo。 +- 全批无全局 `client`,模板与 UIController 篇说明 `props.state` 取法。 +- 25 篇正文的所有代码块与 24 个 demo 都有有价值注释,且非注释代码未变。 +- prettier / ESLint / docs 类型 / 构建 / 25 个 HTML 全部通过;ROADMAP / STATE 未被改动;未 commit。 +- 10-48 在修复结束即停止,独立读者审阅留给 10-49。 + + + +本计划**不写 SUMMARY**。完成后在对话中报告删除清单、25/24 计数与门禁结果,然后停止;独立读者审阅由 `10-49-PLAN.md` 执行,用户修订与收尾由 `10-50-PLAN.md` 执行。 + + +## 编号变更(2026-11-01) + +本文件写作期把「独立读者审阅」称为 10-49、把「用户修订与收尾」称为 10-50;重排后按下列映射理解(原文保持不变): + +- 读者审阅 → `10-53-PLAN.md`(Round 2/3;Round 1 记录保留在 `10-49-READER-REVIEW.md`,本文件写作期的 `10-49-READER-REVIEW.md` 指针仍有效)。 +- 用户修订、最终门禁、全站 live、落位评估与收尾 → `10-54-PLAN.md`。 +- 新增的 `10-49`..`10-52` 是 Part 0–1 / 2–3 / 4 / 5 的深度扩写(D-93);`10-48` 仍是 pre-review 修复。 +- 旧 `10-49-PLAN.md` / `10-50-PLAN.md` 已被新计划替换;本文件不因编号变更而改正文。 + diff --git a/.planning/phases/10-docs-restructure/10-49-PLAN.md b/.planning/phases/10-docs-restructure/10-49-PLAN.md new file mode 100644 index 0000000..e252513 --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-49-PLAN.md @@ -0,0 +1,351 @@ +--- +phase: 10-docs-restructure +plan: 49 +type: execute +wave: 7 +depends_on: + - 10-48 +files_modified: + - docs/advanced/ii/ui/ui-template.md + - docs/advanced/ii/ui/container-and-coordinates.md + - docs/advanced/ii/ui/basic-shapes.md + - docs/advanced/ii/ui/curves-and-paths.md + - docs/advanced/ii/ui/text.md + - docs/advanced/ii/ui/image-and-texture.md + - docs/advanced/ii/ui/layer-transform-performance.md + - .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +autonomous: false +requirements: [] +user_setup: [] +estimate: + tokens: 72000 + raw_tokens: 43000 + tasks: 6 + confidence: low +must_haves: + truths: + - "Part 0–1 的 7 篇按 D-93 补齐深度:渲染树模型、事件模型、元素/组件具体用法与设计原因、示例后解释四类内容逐页判定并落表(D-93 第 1–4 条)" + - "扩写不新增、不删除页面,仍为 25 篇正文与 24 个 demo;不新增导航、不改侧边栏、不改 demo(D-88 / D-93)" + - "每篇长度由内容决定:~300 行只是体量参考,不设下限也不设上限,不因低于 300 行判失败;不注水、不堆接口表(D-88)" + - "Round 1 的 116 条提问与 178 行分节概率只作内部输入(10-49-READER-REVIEW.md),不交给用户,也不作为唯一修改清单;扩写按 D-93 系统检查(D-91 / D-93 第 5 条)" + - "扩写只改本计划列出的 7 篇正文与 NOTES;其余 18 篇正文、两份导览、`docs/.vitepress/`、demo、`packages/`、`packages-user/`、`src/` 一律不改" + - "本计划不写 SUMMARY、不改 ROADMAP / STATE、不 commit;完成后停在扩写,不进入读者循环与用户审阅" + artifacts: + - "docs/advanced/ii/ui/ui-template.md(渲染树映射、事件入口、组件/元素/生命周期、文件放置与注册)" + - "docs/advanced/ii/ui/{container-and-coordinates,basic-shapes,curves-and-paths,text,image-and-texture,layer-transform-performance}.md(按 D-93 补齐模型、事件、组件用法与示例解释)" + - ".planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(追加 `## 10-49 深度扩写(Part 0–1)`:基线、D-93 覆盖表、体量参考、门禁、停止点)" + key_links: + - "先建 D-93 覆盖表再动笔:没有逐页判定,扩写会退化成补几个读者问题,无法保证 25 篇同一深度口径(D-93 第 5 条)" + - "渲染树模型必须先于事件与组件:坐标、zIndex、命中顺序都挂在树上,先讲接口会让读者背结论(D-82 / D-93 第 1 条)" + - "示例后必须解释:代码只说明「怎么写」,解释才说明「在渲染树/事件/组件模型里的位置与理由」(D-93 第 4 条)" + - "体量只记录不设门禁:把 ~300 行当硬指标会诱导注水,违反 D-88" +--- + + +本计划承担 25 篇中的 Part 0–1(7 篇)。扩写按 Part 分组而不是按 25 篇平均切分: + +- Part 0–1 是「先能画出来」的地基(模板、坐标、图形、曲线、文字、图片、层级),7 篇共享同一套渲染树与命中模型,放在一个计划里才能一次讲清共用概念,后面的页面只引用不重复。 +- 25 篇按每计划 ≤8 篇切分为 7 / 7 / 5 / 6 四份扩写计划:10-49(Part 0–1)、10-50(Part 2–3)、10-51(Part 4)、10-52(Part 5)。25 篇无法在 3 份计划内满足 ≤8 篇,故为 4 份,而不是压缩单篇深度。 +- 四份扩写计划串行(wave 7→10),原因是它们共享同一份 `10-CUSTOM-UI-NOTES.md` 与同一套 `pnpm docs:build` 产物目录;并行会互相覆盖记录与构建输出。篇目本身不重叠,串行只为保护记录与构建,不改变每篇的写作口径。 +- 本计划只写 7 篇正文与 NOTES;不写 SUMMARY、不改 ROADMAP / STATE、不改 demo、不 commit。 + + + +按 D-93 把 Part 0–1 的 7 篇从「能照着抄」扩写到「能自己写」:讲清渲染树如何建立、坐标与变换如何沿树传递、`zIndex` 与绘制/命中顺序、元素生命周期与缓存/脏更新、组件如何映射成渲染树;讲清命中测试、捕获/冒泡、enter/leave、`noevent` / `actionStroke` 与嵌套传播;讲清每个元素/组件的具体用法、典型组合、注意事项与设计原因;每次给出代码后解释它在模型中的位置与理由。 + +Purpose: 当前 7 篇已能完成基本操作,但读者仍会在「文件放哪、坐标相对谁、谁先接事件、缓存什么时候脏、组件怎么变成元素」上卡住;只补参数表无法让读者独立改写示例(D-93)。 +Output: 7 篇扩写后的正文 + NOTES 中的基线、D-93 覆盖表、体量参考与门禁记录。**不新增/删除页面、不改 demo、不改其它 18 篇、不写 SUMMARY / ROADMAP / STATE、不 commit。** + + + +@C:/Users/13194/.config/opencode/gsd-core/workflows/execute-plan.md +@C:/Users/13194/.config/opencode/gsd-core/templates/summary.md + + + +@AGENTS.md +@dev.md +@.planning/STATE.md +@.planning/ROADMAP.md +@.planning/phases/10-docs-restructure/10-CONTEXT.md +@.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md +@.planning/phases/10-docs-restructure/10-48-PLAN.md +@.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md +@docs/advanced/ii/index.md +@docs/advanced/index.md +@docs/.vitepress/config.ts + +**流程约定:** +- 只修改本计划 `files_modified` 内文件;不改 `10-01`..`10-48` 计划与 SUMMARY、不改 POC 文件、不改 `docs/` 其它页面与 demo、不改 `packages/` / `packages-user/` / `src/`。 +- **Task 0 是硬关卡**:汇报扩写范围、D-93 逐条口径、Round 1 内部输入的使用边界、体量口径与停止条件,等用户明确回复「可以执行」。 +- 修改方式为**派发子代理执行**;改文件前先声明本次写入是内联还是派发。正文扩写一律派发子代理。 +- 不得调用 `opencode` 命令;不得修改既有 JSDoc / 代码注释;不 commit(D-90)。 +- 写作口径按 D-59..D-74、D-77..D-88、D-91..D-93;示例注释按 D-65,代码块保留完整类上下文按 D-70,不写源码叙述按 D-80,不写使用概率元信息按 D-79。 +- `pnpm` 在 PowerShell 5.1 下需经 `cmd /c "..."` 执行。 + +**本批事实(执行时以这些为准):** +- 10-43..10-47 已执行完成,10-48 已完成 pre-review 修复;10-49 Round 1 独立读者审阅已完成,记录在 `10-49-READER-REVIEW.md`(25 篇、116 条提问、178 行分节概率),docs 未改。 +- 本计划只做 Part 0–1 的**深度扩写**,不是读者审阅;读者循环在第 10-53 计划执行,用户审阅在第 10-54 计划执行。 +- 25 篇位于 `docs/advanced/ii/ui/`,24 个 demo 位于 `docs/.vitepress/components/demos/ui/`;侧边栏 25 条在 `docs/.vitepress/config.ts`。 +- 参考哈希基线(`## 参考清单哈希基线` 与各批复核表)是写作期记录,本计划不读源码改源码,也不得改写这些哈希记录。 +- 相关源码只用于**核对模型事实**,不写进正文:`packages/render/src/core/{item,container,event,graphics,render,transform}.ts`、`packages/render-vue/src/{renderer,tag,elements,props}.ts`、`packages/system/src/ui/{ui,controller,instance,types}.ts`、`packages-user/client-base/src/types.ts`、`src/client/ui/index.ts`。 + + + + + + Task 0: 汇报 Part 0–1 扩写范围、D-93 口径与停止条件,等待「可以执行」 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + .planning/phases/10-docs-restructure/10-CONTEXT.md(D-88、D-90、D-91、D-92、D-93)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构:25 篇、116 条提问、178 行分节概率)、.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(命名总表、门禁、10-48 基线)、.planning/phases/10-docs-restructure/10-48-PLAN.md(停止点)、docs/advanced/ii/ui/ 下 7 篇现文、docs/.vitepress/config.ts + 向用户做四段汇报并停下等待: + +**要做什么**——只做一件事:按 D-93 深度扩写 Part 0–1 的 7 篇(`ui-template`、`container-and-coordinates`、`basic-shapes`、`curves-and-paths`、`text`、`image-and-texture`、`layer-transform-performance`)。不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不进入读者循环,不进入用户审阅。 + +**为什么**——这 7 篇是后面 18 篇的地基,但当前主要回答「怎么写」,没有系统回答「渲染树是什么、坐标和变换沿树怎么传、谁先接事件、缓存什么时候脏、组件怎么变成元素」。只补读者列出的问题会漏掉同类缺口,所以按 D-93 逐页判定四类内容,而不是按问题清单打补丁。 + +**大致怎么做**——Task 1 先把基线、D-93 覆盖表(7 篇 × 渲染树/事件/元素组件/示例解释)与体量参考写进 NOTES;Task 2 扩写 Part 0 的模板篇;Task 3 扩写坐标、图形、曲线 3 篇;Task 4 扩写文字、图片、层级 3 篇;每篇都要求「先模型、再用法、示例后解释」;Task 5 跑门禁、做 D-93 抽查、记录体量并停止。 + +**影响范围**——只改上述 7 篇正文与 `10-CUSTOM-UI-NOTES.md`。不改其余 18 篇、两份导览、侧边栏、24 个 demo、`packages/` / `packages-user/` / `src/`、既有 JSDoc/注释、ROADMAP / STATE;不写 SUMMARY;不 commit。 + +**D-93 逐条口径(将写入 NOTES 覆盖表):** +1. 渲染树模型:根/容器/子元素树、坐标与变换沿树传递、`zIndex` 与绘制/命中顺序、元素生命周期、缓存/脏更新、组件如何映射成渲染树。 +2. 事件模型:命中测试、捕获与冒泡顺序、enter/leave、`noevent` / `actionStroke`、事件对象、嵌套容器中的传播。 +3. 元素/组件用法:具体使用方式、重要功能、典型组合与场景、注意事项、为什么这样设计;不能只写「能做什么 / 参数有什么」。 +4. 示例与解释并重:每次给代码后解释它在渲染树/事件/组件模型中的位置与理由,不能只给可复制代码。 + +**体量口径**——每篇长度由内容决定;用户提到的「每篇大概 300 行」只是体量/深度参考,不是门禁。内容本来少的页面不注水,低于 300 行不判失败;高于 300 行也不判失败(D-88)。 + +**Round 1 的使用边界**——`10-49-READER-REVIEW.md` 的 116 条提问只作内部输入,不交给用户,也不能只修这些;扩写必须按 D-93 系统检查。读者循环在 10-53 才执行。 + +**请用户确认:** +1. 扩写范围是 Part 0–1 的 7 篇;不新增/删除页面与 demo,不改其它 18 篇与导览。 +2. 四类 D-93 内容逐页判定;不适用的格子写「不适用:理由」,不能留空或写「待补」。 +3. 体量只记录不设门禁;不因低于 300 行失败,也不为凑行数注水。 +4. 停止条件:扩写与门禁结束即停止;不进入读者循环、不写 SUMMARY / ROADMAP / STATE、不 commit。 +5. 本次修改方式为**派发子代理执行**;不改既有注释;不调用 `opencode` 命令。 + +**未确认前不得创建或修改任何文件。** 然后停下等待用户明确回复「可以执行」四个字;其它回复视为未批准。 + 尚无产物;本任务只汇报扩写范围、D-93 口径、体量口径、Round 1 使用边界与停止条件。 + 确认:①7 篇范围与「不新增/删除页面、不改 demo、不改其它 18 篇」;②四类 D-93 内容逐页判定、允许「不适用:理由」但不允许留空;③~300 行只是参考、不设门禁、不注水;④Round 1 仅内部输入、读者循环在 10-53;⑤扩写结束即停、不写 SUMMARY / ROADMAP / STATE、不 commit;⑥派发子代理执行、不改既有注释。 + 回复「可以执行」以继续;其它回复视为未批准。 + 用户已回复「可以执行」,且扩写范围、D-93 四类口径、体量口径、Round 1 使用边界、停止条件、派发方式六项已确定。用户未回复前不得创建或修改任何文件。 + + 用户已回复「可以执行」,且扩写范围、D-93 口径、体量口径、Round 1 边界、停止条件、派发方式均已确认。 + + 用户回复「可以执行」且六项待定项已定。 + + + + Task 1: 扩写前基线 + D-93 覆盖表 + 体量参考(不改正文) + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + `10-CUSTOM-UI-NOTES.md` 含 `读者审阅:已完成`;`10-49-READER-REVIEW.md` 存在且为 25 篇、116 条提问、178 行分节概率;用户已在 Task 0 回复「可以执行」。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(末尾 10-49 审阅小节与命名总表)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(只读结构,不改内容)、.planning/ROADMAP.md、.planning/STATE.md、docs/advanced/ii/ui/ 下 7 篇现文与其余 18 篇文件名 + **本任务只建基线与覆盖表,绝对不改 `docs/` 正文、不改 ROADMAP / STATE。** + +向 `10-CUSTOM-UI-NOTES.md` 末尾追加 `## 10-49 深度扩写(Part 0–1)` 小节,依次写入以下固定格式的行(各独占一行,后续任务与 verify 按字面量断言): + +1. `扩写范围:` + `docs/advanced/ii/ui/` 下 7 篇(Part 0–1),逐条列出完整路径;写「不新增/删除页面,仍为 25 篇正文 + 24 个 demo;不改其它 18 篇与两份导览」。 +2. `Round 1 内部输入:` + `10-49-READER-REVIEW.md(25 篇、116 条提问、178 行分节概率);仅内部输入,不交给用户,不作为唯一修改清单`。 +3. `基线 HEAD(10-49 深度扩写):` + `git rev-parse HEAD` 的完整 sha。 +4. `扩写前本批页面聚合哈希:` + 对上述 7 篇取聚合 SHA-256(小写 hex,64 位)。算法:按 `docs/advanced/ii/ui/...` 相对路径字符串排序,逐个对文件字节取 SHA-256,拼成 `相对路径:hash` 后用 LF 连接,再取 SHA-256。 +5. `本批外文件聚合哈希:` + 对其余 18 篇正文 + `docs/advanced/ii/index.md` + `docs/advanced/index.md` 取同一算法的聚合 SHA-256(小写 hex,64 位)。用于证明本计划没有碰批外文档。 +6. `ROADMAP 全文哈希:` 与 `STATE 全文哈希:` + 各自 UTF-8 全文的 SHA-256(小写 hex,64 位)。用于证明本计划没碰两个账本。 +7. `### D-93 覆盖表` + 一张 7 行表格,表头逐字为 `| 篇目 | 渲染树模型 | 事件模型 | 元素/组件用法 | 示例后解释 | 现状行数 |`;每行「篇目」写完整相对路径;四类内容格先写 `待补`,若确不适用写 `不适用:<一句理由>`;「现状行数」写当前 `Get-Content` 行数。 +8. `体量参考(非门禁):` + 7 篇当前总行数与平均行数,并明确写「~300 行仅为参考,不设下限/上限;不因低于 300 行失败,也不为凑行数注水(D-88)」。 +9. `停止点:10-49 只做 Part 0–1 深度扩写;不改 10-50..10-54、不改 docs 其它页与 demo、不写 SUMMARY / ROADMAP / STATE、不 commit。` + +**本任务不得修改任何 `docs/` 文件、不得改 ROADMAP / STATE、不得派发扩写子代理。** 写完立即结束本任务。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '读者审阅:已完成'){ Write-Error 'NO-1049-REVIEW-MARK' }; if(-not(Test-Path -LiteralPath '.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md')){ Write-Error 'MISSING-REVIEW' }; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($k in @('## 10-49 深度扩写(Part 0–1)','扩写范围:','Round 1 内部输入:','基线 HEAD(10-49 深度扩写):','扩写前本批页面聚合哈希:','本批外文件聚合哈希:','ROADMAP 全文哈希:','STATE 全文哈希:','D-93 覆盖表','体量参考(非门禁):','停止点:10-49 只做')){ if($np.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($np -notmatch '(?m)^基线 HEAD(10-49 深度扩写):[0-9a-f]{7,40}'){ Write-Error 'BAD-BASE-HEAD' }; foreach($h in @('扩写前本批页面聚合哈希','本批外文件聚合哈希','ROADMAP 全文哈希','STATE 全文哈希')){ if($np -notmatch ('(?m)^'+$h+':[0-9a-f]{64}')){ Write-Error "BAD-HASH $h" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; $rows=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/' }); if($rows.Count -ne 7){ Write-Error ('MATRIX-ROWS:'+$rows.Count) }; foreach($p in $pages){ if($np.IndexOf($p) -lt 0){ Write-Error "NO-PAGE-ROW $p" }; if(-not ($rows | Where-Object { $_.IndexOf($p) -ge 0 })){ Write-Error "NO-MATRIX-ROW $p" } }; foreach($r in $rows){ $c=@($r.Trim('|') -split '\|'); if($c.Count -lt 6){ Write-Error 'MATRIX-COLS' }; for($i=0;$i -lt 6;$i++){ if([string]::IsNullOrWhiteSpace($c[$i])){ Write-Error 'MATRIX-EMPTY' } } }; if($np -notmatch '116 条提问'){ Write-Error 'NO-ROUND1-COUNT' }; if($np -notmatch '178 行分节概率'){ Write-Error 'NO-PROB-COUNT' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; 'T1-OK' + non-zero exit, or output contains "NO-1049-REVIEW-MARK", "MISSING-REVIEW", "NOTES-MISSING", "BAD-BASE-HEAD", "BAD-HASH", "NO-MATRIX-SECTION", "MATRIX-ROWS", "NO-PAGE-ROW", "NO-MATRIX-ROW", "MATRIX-COLS", "MATRIX-EMPTY", "NO-ROUND1-COUNT", "NO-PROB-COUNT", "MD-COUNT", "DEMO-COUNT"; or output lacks "T1-OK" + + NOTES 有 `## 10-49 深度扩写(Part 0–1)` 与九项固定行;`### D-93 覆盖表` 含 7 篇完整路径、表头六列、四类内容格非空(`待补` 或 `不适用:理由`)、现状行数为数字;Round 1 的两个计数(116 / 178)已记录且明确「仅内部输入」;四个聚合/账本哈希均为 64 位小写 hex;`docs/advanced/ii/ui` 仍为 25 篇、demo 仍为 24 个;未改任何 `docs/` 正文、未改 ROADMAP / STATE。 + 扩写基线与 D-93 覆盖表已落盘,正文未动。 + + + + Task 2: 扩写 Part 0 模板篇(组件如何映射成渲染树) + docs/advanced/ii/ui/ui-template.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 1 已写入 `## 10-49 深度扩写(Part 0–1)` 与 D-93 覆盖表;7 篇现文未被改动。 + docs/advanced/ii/ui/ui-template.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅 ui-template.md 的提问,不向用户转述)、packages/render-vue/src/renderer.ts(createElement / insert / remove / createText 的映射)、packages/render-vue/src/tag.ts(内置标签到元素类的注册)、packages/system/src/ui/{ui,controller,instance,types}.ts(GameUI、open/close、props 注入)、packages-user/client-base/src/types.ts(IGameUIPropsBase.state)、src/client/ui/index.ts(UI 文件的导出入口) + **只改 `ui-template.md` 与 NOTES;本任务不碰其它 6 篇、不碰 demo。** + +在保留现有正确内容的前提下扩写,按读者理解顺序组织(D-84),至少补齐以下四块,并保证每块先讲模型再讲用法: + +1. **模板在渲染树里的位置**:新增 `## 这份模板在渲染树里的位置`。讲清 Vue 组件树 → render 函数返回的 VNode → 元素层渲染树(根节点 → `container` → `g-rect` / `text`)的映射;`createElement` 把标签变成元素实例,`insert` 挂到父节点,`remove` 销毁子树;组件重渲染只更新属性,不重建整棵树。解释为什么不能把裸文字写在 `container` 里(文字 VNode 会被当成文字元素并告警,空白会变成注释节点),以及 `container` 作为根子树与画布根的关系。 +2. **事件从哪里进入**:新增 `## 事件从哪里进入`。用一小段说明:点击从画布根开始,按 `zIndex` 与子元素顺序找到最上层被点到的元素,再沿容器向外冒泡;`container` 是捕获单位;面板被打开后,它的根容器就是这棵子树的入口。只讲入口,捕获/冒泡的完整规则指向 `./events.md#捕获与冒泡`,不在这里重抄。 +3. **组件、元素与打开方式**:新增 `## 组件、元素与打开方式`。讲清 `controller` / `instance` / `state` 三个基础 props 的来源;`instance` 是这次打开产生的实例句柄,`close` 要凭它关闭;`open` 的第二个参数只放你自己声明的 props(不是 `controller` / `instance` / `state`);`GameUI` 是 `{ name, component }` 对象,打开时传对象而不是靠名字查找——先核对 `packages/system/src/ui/ui.ts`,若与现有「靠名字识别」表述冲突,按 D-72 以源码注释为准并在对话中报告,不把冲突写进正文;同时说明静态查表列表并未自动填充,不要依赖名字反查。补文件放置与注册:游戏 UI 放在 `src/client/ui/.tsx`,在 `src/client/ui/index.ts` 导出,客户端入口通过该出口拿到模块;不要写成「放哪都行」。 +4. **两条写法怎么选**:新增 `## 两条写法怎么选`。把 TSX 与手写元素层两条路线放在同一棵渲染树下比较:TSX 负责组件、响应式与生命周期,手写元素层适合极底层的一次性结构;两者可以混用,但混用时谁负责挂载、谁负责销毁要说清。 + +**写法硬要求:** +- 每次给代码后必须用一段解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条),不能只给可复制代码。 +- 代码块保留完整类/函数上下文(D-70),注释解释关键行为(D-65);不要写「模板」「[需改]」等标记(D-83)。 +- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写「v1 / 简化版 / 以后再做」这类降级表述。 +- 不新增/删除页面或 demo;不因凑 300 行注水(D-88)。现文中的正确内容保留,不整篇重写。 + +**完成后更新 NOTES 的 D-93 覆盖表**:把 `ui-template.md` 行的四类内容格改为 `已讲`(确不适用才保留 `不适用:理由`),并追加一行 `自查:docs/advanced/ii/ui/ui-template.md — 渲染树:…;事件:…;组件/元素:…;示例解释:…`(每项一句,说明新增位置)。再在该小节追加 `已完成扩写:docs/advanced/ii/ui/ui-template.md` 与本任务点名的门禁结果。 + + $ErrorActionPreference='Stop'; $p='docs/advanced/ii/ui/ui-template.md'; if(-not(Test-Path -LiteralPath $p)){ Write-Error 'MISSING-PAGE' }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); foreach($k in @('渲染树','事件','组件','实例','src/client/ui','index.ts','为什么')){ if($t.IndexOf($k) -lt 0){ Write-Error "PAGE-MISSING $k" } }; if($t -match '(?m)^##\s*(模板|需改)'){ Write-Error 'TEMPLATE-MARKER' }; if($t -match '简化版|以后再做|v1'){ Write-Error 'SCOPE-REDUCTION' }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; if($np -notmatch '(?m)^已完成扩写:docs/advanced/ii/ui/ui-template\.md\s*$'){ Write-Error 'NO-DONE-MARK' }; if($np -notmatch '(?m)^自查:docs/advanced/ii/ui/ui-template\.md'){ Write-Error 'NO-SELF-CHECK' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match '^\| docs/advanced/ii/ui/ui-template\.md' }); if($row.Count -ne 1){ Write-Error 'NO-MATRIX-ROW' }; if($row[0] -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $pc=cmd /c "pnpm exec prettier --check docs/advanced/ii/ui/ui-template.md" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T2-OK' + non-zero exit, or output contains "MISSING-PAGE", "PAGE-MISSING", "TEMPLATE-MARKER", "SCOPE-REDUCTION", "NO-DONE-MARK", "NO-SELF-CHECK", "NO-MATRIX-ROW", "MATRIX-STILL-PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T2-OK" + + `ui-template.md` 新增渲染树位置、事件入口、组件/元素/打开方式、两条写法怎么选四块内容;讲清组件→VNode→元素树映射、为什么不能写裸文字、`props` 三个基础项、`open` 第二参数、`instance` 与 `close`、`GameUI` 对象、文件放 `src/client/ui/` 并导出;每次代码后有模型解释;无「模板 / 需改 / 简化版 / v1 / 以后再做」;NOTES 的覆盖表该行为 `已讲` 且有 `自查:` 与 `已完成扩写:` 行;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。 + 模板篇已按 D-93 扩写并记录,构建通过。 + + + + Task 3: 扩写坐标、图形、曲线 3 篇(渲染树、命中与组合) + docs/advanced/ii/ui/container-and-coordinates.md, docs/advanced/ii/ui/basic-shapes.md, docs/advanced/ii/ui/curves-and-paths.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 2 已完成并写入 `已完成扩写:docs/advanced/ii/ui/ui-template.md`;其 cover 表行已无 `待补`;`docs/advanced/ii/ui` 仍为 25 篇。 + docs/advanced/ii/ui/{container-and-coordinates,basic-shapes,curves-and-paths}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 3 篇的提问)、packages/render/src/core/{item,container,graphics,transform}.ts(坐标/变换继承、zIndex 排序、命中、`actionStroke`、图形模式)、packages/render/src/core/event.ts(`noevent`、事件对象字段) + **只改这 3 篇与 NOTES;不碰其它篇目与 demo。** + +三篇都按「先模型、再用法、示例后解释」扩写,保留现有正确内容,补齐以下要点: + +**(1)`container-and-coordinates.md`** +- 新增 `## 渲染树:根、容器与子元素`:根容器 → 子容器 → 叶子元素的树;父子通过挂载建立;容器同时是布局单位与事件捕获单位;`zIndex` 只在同一父级的兄弟之间排序,父级的 `zIndex` 带着整棵子树与父级的兄弟比较,子元素不能越过父级去盖住旁支。 +- 新增 `## 坐标与变换如何沿树传递`:子坐标在父容器的局部坐标系里;父级的平移/缩放/旋转会复合到子级;锚点决定元素自身哪个点落在 `x/y` 上,也是变换中心;嵌套时不要用「累加屏幕坐标」的心算,按树逐层理解。 +- 新增 `## 事件在嵌套容器中的路径`:命中从根向内找最上层元素,捕获从根向命中元素,冒泡从命中元素向根;容器在捕获阶段把事件交给子级;`stopPropagation` 只停止继续传播,不阻止同一元素上的其它监听器;`noevent` 的子树整个不参与命中(不是只跳过自身)。 +- 新增 `## 生命周期与缓存`:`appendChild` / `removeChild` / 销毁的关系;容器默认缓存,子元素变化要通过脏标记向上传递,父级缓存才会重绘;`hidden` 保留实例与状态但跳过绘制与命中,三元卸载会销毁子树。 +- 新增 `## 坐标基准与画布`:说明 `[0, 0, 480, 320]` 是渲染目标(画布)坐标,不是浏览器窗口 CSS 像素;窗口大小变化时是否缩放由客户端画布决定,不要假设「写 480 就一定占满屏幕」;需要适配时按画布尺寸算,不要按窗口算。核对 `packages/render/src/core/render.ts` 与客户端画布设置后再写,不确认的数字不写。 + +**(2)`basic-shapes.md`** +- 新增 `## 图形在渲染树里的位置`:图形是叶子元素,挂在容器下;绘制顺序由兄弟 `zIndex` 与插入顺序决定;命中按图形几何而不是包围盒。 +- 扩写 `## 填充与描边` 为 `## 填充、描边与命中`:讲清模式判定(`fill` 与 `stroke` 同时开 → 填充+描边;只开一个 → 对应模式;都不开 → 默认填充;`strokeAndFill` 的优先级);默认颜色;`actionStroke` 只把描边算命中,内部区域下穿;同时开两个开关不会互相覆盖,而是组合。 +- 新增 `## 图形作为界面零件`:槽位底板、分隔线、按钮底、半透明遮罩的典型组合;每种组合说明为什么用这个图形、命中要注意什么。 +- 新增 `## 为什么矩形没有圆角`:明确 `g-rect` 不支持圆角,圆角用 `g-rectr`(见曲线篇),避免读者给 `g-rect` 加 `radius`。 +- 补元素层类的来源:`Rect` / `Circle` / `Ellipse` / `Line` 从 `@motajs/render` 导入;TSX 标签由渲染器内置注册,不需要逐个 import。 + +**(3)`curves-and-paths.md`** +- 新增 `## 路径与曲线的坐标基准`:贝塞尔/二次曲线/路径没有 `loc`,点坐标相对父容器;要整体移动就包一层容器;`Path2D` 是浏览器全局对象,不是本框架导出。 +- 新增 `## 路径在渲染树与命中中的位置`:路径是叶子元素;命中按路径几何;`actionStroke` 只命中描边;`Path2D` 不能序列化,不能进存档。 +- 扩写 `## 圆角矩形`:把 `circle` 1–4 项、`ellipse` 2/4/6/8 项的角与值映射讲清(按源码/类型定义核对,不凭猜测);给一个「只有左上与右下圆角」的例子并解释映射。 +- 新增 `## 什么时候用路径`:自定义边框、异形底板、装饰线;与基础图形的取舍(能用矩形/圆角就不要上路径,命中与维护都更简单)。 + +**写法硬要求:** +- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整上下文(D-70),注释充足(D-65)。 +- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。 +- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。 +- 完成后更新 NOTES 覆盖表中这 3 篇的四类内容格为 `已讲`(或 `不适用:理由`),各追加一行 `自查: — …` 与 `已完成扩写:`,并记录本任务门禁结果。 + + $ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $c=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('渲染树','坐标','变换','事件','zIndex','缓存','画布')){ if($c.IndexOf($k) -lt 0){ Write-Error "CONTAINER-MISSING $k" } }; $s=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('渲染树','命中','actionStroke','填充','描边','g-rectr','@motajs/render')){ if($s.IndexOf($k) -lt 0){ Write-Error "SHAPES-MISSING $k" } }; $v=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('坐标','Path2D','命中','圆角','容器')){ if($v.IndexOf($k) -lt 0){ Write-Error "CURVES-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths='docs/advanced/ii/ui/container-and-coordinates.md docs/advanced/ii/ui/basic-shapes.md docs/advanced/ii/ui/curves-and-paths.md'; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T3-OK' + non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "CONTAINER-MISSING", "SHAPES-MISSING", "CURVES-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T3-OK" + + 三篇分别补齐:坐标篇的渲染树/变换继承/嵌套事件路径/生命周期缓存/画布基准;图形篇的渲染树位置/填充描边命中判定/界面零件组合/无圆角说明/元素类导入;曲线篇的坐标基准/Path2D/命中/圆角映射/使用取舍。每次代码后有模型解释;无降级/占位表述;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` 与 `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。 + 坐标、图形、曲线 3 篇已按 D-93 扩写并记录,构建通过。 + + + + Task 4: 扩写文字、图片、层级 3 篇(叶子元素、纹理与脏更新) + docs/advanced/ii/ui/text.md, docs/advanced/ii/ui/image-and-texture.md, docs/advanced/ii/ui/layer-transform-performance.md, .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 3 已完成并写入 3 条 `已完成扩写:`;覆盖表无 `待补`;docs 仍为 25 篇 / 24 demo。 + docs/advanced/ii/ui/{text,image-and-texture,layer-transform-performance}.md(现文全文)、.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md(仅这 3 篇的提问)、packages/render/src/{style/font.ts,core/misc.ts,assets/texture.ts,core/item.ts}(Font/Text/Texture、尺寸测量、缓存与脏更新)、packages-user/client-base/src/material/*(纹理/素材来源;确认后再写具体加载方式) + **只改这 3 篇与 NOTES;不碰其它篇目与 demo。** + +三篇按「先模型、再用法、示例后解释」扩写,保留现有正确内容,补齐: + +**(1)`text.md`** +- 新增 `## 文字元素与渲染树`:文字是叶子元素;不能把裸文字写在 `container` 里;文字元素有自己的测量尺寸与命中矩形。 +- 扩写 `## 字体` 与 `## 尺寸与居中`:`Font` 构造参数顺序与默认值、`Font.defaults()` / `Font.clone` 的用途;文字宽高由测量决定,给 `width/height` 不裁剪;描边计入尺寸;锚点 0.5 时 `x/y` 落在中心;`loc` 里的锚点与外面 `anchorX/anchorY` 重复时以属性写法为准(核对 `packages/render/src/core/misc.ts` 的属性合并顺序后再写)。 +- 新增 `## 文字作为界面零件`:标题、标签、按钮文字、数值显示;说明多行文本应使用内置文本组件而不是手写多个 `text`。 +- 新增 `## 为什么文字默认不缓存`:文字内容变化频繁,缓存会让每次改字都重绘离屏画布;需要缓存时显式开,并说明代价。 + +**(2)`image-and-texture.md`** +- 新增 `## 图片元素与纹理`:图片元素接收纹理对象,`loc` 决定画多大,纹理会拉伸铺满;命中按图片矩形。 +- 新增 `## 纹理从哪里来`:`Texture` 接受 `HTMLCanvasElement` / `ImageBitmap` / `HTMLImageElement`;给出加载 PNG 图标的完整路径(创建 `Image`、等待加载完成、再构造纹理),说明加载是异步的,未完成时不要拿空纹理去画;如果项目有素材/纹理管理器,按 `packages-user/client-base/src/material/*` 的实际接口写,不确认的 API 不写。 +- 新增 `## 像素图与高清缓存`:`hd` / `anti` / `noanti` 的用途;像素图要关抗锯齿并尽量整数缩放;缓存对静态图标有利、对频繁换帧的动画纹理不利。 +- 新增 `## 图片作为界面零件`:图标、道具格、背景图;典型组合与注意事项(尺寸、透明边、像素对齐)。 +- 补 `import` 来源:`Texture` 从 `@motajs/render` 导入。 + +**(3)`layer-transform-performance.md`** +- 新增 `## 渲染树、层级与绘制顺序`:兄弟按 `zIndex` 排序,绘制从小到大(后画覆盖先画),命中从大到小(最上层先接);父级 `zIndex` 带着整棵子树参与父级兄弟的排序;子元素不能越过父级盖住旁支。 +- 新增 `## 变换沿树传递`:`scale` / `rotate` / `alpha` 作用在元素自身坐标系,锚点是变换中心;父级变换复合到子级;事件里的 `offsetX/offsetY` 是变换后反算回元素局部坐标的结果,`absoluteX/absoluteY` 是画布坐标。 +- 新增 `## 缓存与脏更新`:容器默认缓存;元素属性变化会把脏标记沿父链上传,父级缓存才重绘;父级缓存命中时子级变化不会自动穿透,除非子级把父级标脏;`nocache` 优先级高于 `cache`;给出「静态复杂面板适合缓存、频繁变化子树不适合」的判断,并给一个错误示范(给会变的文字/图标容器开缓存)。 +- 新增 `## 事件坐标与变换`:缩放/旋转后点击落在哪里、`offsetX` 为什么不是屏幕坐标、嵌套变换下如何用 `absoluteX` 做跨元素判断。 +- 保留并强化 `hidden` 与三元卸载的对比表;补「`hidden` 不改变布局流,因为这里没有 DOM 布局流,只有树上的绘制与命中」这一句,直接回答读者对布局流的疑问。 + +**写法硬要求:** +- 每次代码后解释它在渲染树/事件/组件模型中的位置与理由(D-93 第 4 条);代码块保留完整类/函数上下文(D-70);注释充足(D-65)。 +- 不写源码叙述(D-80)、不写使用概率元信息(D-79)、不写降级/占位表述;不新增/删除页面或 demo;不注水(D-88)。 +- 与源码/注释冲突时按 D-72:以方法注释为准,只在对话中报告,不写进正文。 +- 完成后更新 NOTES 覆盖表中这 3 篇的四类内容格为 `已讲`(或 `不适用:理由`),各追加 `自查:` 与 `已完成扩写:`,并记录本任务门禁结果。 + + $ErrorActionPreference='Stop'; $pages=@('docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($p in $pages){ if(-not(Test-Path -LiteralPath $p)){ Write-Error "MISSING $p" }; $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match '简化版|以后再做|v1'){ Write-Error "SCOPE-REDUCTION $p" } }; $t1=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[0])); foreach($k in @('渲染树','Font','锚点','缓存','测量')){ if($t1.IndexOf($k) -lt 0){ Write-Error "TEXT-MISSING $k" } }; $t2=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[1])); foreach($k in @('Texture','HTMLImageElement','ImageBitmap','像素','命中','加载')){ if($t2.IndexOf($k) -lt 0){ Write-Error "IMAGE-MISSING $k" } }; $t3=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $pages[2])); foreach($k in @('zIndex','变换','缓存','脏','offsetX','absoluteX','hidden')){ if($t3.IndexOf($k) -lt 0){ Write-Error "LAYER-MISSING $k" } }; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; foreach($p in $pages){ if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" }; if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" } }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); foreach($p in $pages){ $row=@($m.Groups[1].Value -split "`r?`n" | Where-Object { $_ -match ('^\| '+[regex]::Escape($p)) }); if($row.Count -ne 1){ Write-Error "NO-MATRIX $p" }; if($row[0] -match '待补'){ Write-Error "PENDING $p" } }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; $paths='docs/advanced/ii/ui/text.md docs/advanced/ii/ui/image-and-texture.md docs/advanced/ii/ui/layer-transform-performance.md'; $pc=cmd /c "pnpm exec prettier --check $paths" 2>&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; 'T4-OK' + non-zero exit, or output contains "MISSING ", "SCOPE-REDUCTION", "TEXT-MISSING", "IMAGE-MISSING", "LAYER-MISSING", "NO-DONE", "NO-SELF-CHECK", "NO-MATRIX", "PENDING", "MD-COUNT", "DEMO-COUNT", "PRETTIER-FAIL", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK"; or output lacks "T4-OK" + + 文字篇补齐渲染树位置、Font/测量/锚点、界面零件、默认不缓存;图片篇补齐纹理来源与 PNG 加载、像素图设置、命中、常用零件、`Texture` 导入;层级篇补齐 zIndex 同父排序与子树、变换继承、缓存脏更新、事件坐标与变换、`hidden` 与布局流。每次代码后有模型解释;NOTES 覆盖表 3 行为 `已讲` 且有 `自查:` 与 `已完成扩写:`;25 篇 / 24 demo 不变;prettier 与构建通过、0 dead link。 + 文字、图片、层级 3 篇已按 D-93 扩写并记录,构建通过。 + + + + Task 5: 门禁 + D-93 抽查 + 体量记录 + 停止 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md + Task 2–4 已把 7 篇的四类内容格改为 `已讲`(或 `不适用:理由`),并各写入 `自查:` 与 `已完成扩写:`;docs 仍为 25 篇 / 24 demo。 + .planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md(`## 10-49 深度扩写(Part 0–1)` 全部内容)、docs/advanced/ii/ui/ 下 7 篇、.planning/ROADMAP.md、.planning/STATE.md + **只校验、记录与停止;除 NOTES 外不改任何文件。** + +1. **D-93 抽查**:逐篇读 7 篇,按四类内容核对「是否讲清模型/事件/组件用法/示例解释」。每篇写一行 `D-93 抽查: — 通过` 或 `D-93 抽查: — 发现缺口(缺口一句)`;有缺口先回到对应 Task 修到通过,不得把缺口留到读者循环。 +2. **结构门禁**:`docs/advanced/ii/ui` 仍为 25 篇 `.md`;demo 仍为 24 个 `.tsx`;7 篇均为 CRLF;7 篇均无 `待补` 覆盖格;每篇均有 `自查:` 与 `已完成扩写:`;无「模板 / 需改 / 简化版 / v1 / 以后再做」。 +3. **聚合哈希门禁**:用 Task 1 的同一算法重算 `本批外文件聚合哈希` 与 `ROADMAP 全文哈希` / `STATE 全文哈希`,必须与 Task 1 逐字一致;重算 `扩写前本批页面聚合哈希` 对应的「扩写后本批页面聚合哈希」,必须与扩写前不同(证明 7 篇确实改了)。 +4. **prettier**:`cmd /c "pnpm exec prettier --write docs/advanced/ii/ui"` 后跑同路径 `--check`。 +5. **ESLint**:`cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui"`,要求 exit 0 且输出不含 `error` / `warning`。 +6. **docs 类型**:`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"`,只要求 `docs/` 路径 0 条 `error TS`;既有引擎报错只记录条数,不要求本计划修。 +7. **构建**:`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`,要求 exit 0、输出含 `build complete`、不含 `dead link`;`public/_docs/advanced/ii/ui` 下 `.html` 恰好 25 个。 +8. **写 NOTES**:在 `## 10-49 深度扩写(Part 0–1)` 下追加: + - `扩写后本批页面聚合哈希:` + 64 位小写 hex(与扩写前不同)。 + - `体量参考(扩写后):` + 7 篇逐篇行数与总行数;再次写明「不设 300 行门禁,低于 300 行不失败」(D-88)。 + - `### 10-49 门禁` + 上述六类命令与结果、`docs/ 路径类型报错 0`、既有引擎报错条数、构建耗时、25 个 HTML、D-93 抽查逐篇结论。 + - `停止点:10-49 扩写结束;未进入 10-53 读者循环;未写 SUMMARY / ROADMAP / STATE;未改 10-50..10-54;未 commit。` +9. **立即停止**:不创建任何 SUMMARY、不改 ROADMAP / STATE、不 commit、不派发读者;读者循环由 10-53 执行。 + + $ErrorActionPreference='Stop'; $n='.planning/phases/10-docs-restructure/10-CUSTOM-UI-NOTES.md'; $np=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $n)); $sec=[regex]::Match($np,'(?ms)^## 10-49 深度扩写(Part 0–1)\s*\r?\n(.*?)(?=^## |\z)').Groups[1].Value; $pages=@('docs/advanced/ii/ui/ui-template.md','docs/advanced/ii/ui/container-and-coordinates.md','docs/advanced/ii/ui/basic-shapes.md','docs/advanced/ii/ui/curves-and-paths.md','docs/advanced/ii/ui/text.md','docs/advanced/ii/ui/image-and-texture.md','docs/advanced/ii/ui/layer-transform-performance.md'); foreach($k in @('扩写后本批页面聚合哈希:','体量参考(扩写后):','### 10-49 门禁','D-93 抽查:','停止点:10-49 扩写结束')){ if($sec.IndexOf($k) -lt 0){ Write-Error "NOTES-MISSING $k" } }; if($sec -notmatch '(?m)^扩写后本批页面聚合哈希:[0-9a-f]{64}'){ Write-Error 'NO-POST-HASH' }; $mpre=[regex]::Match($sec,'(?m)^扩写前本批页面聚合哈希:([0-9a-f]{64})'); $mpost=[regex]::Match($sec,'(?m)^扩写后本批页面聚合哈希:([0-9a-f]{64})'); if(-not $mpre.Success -or -not $mpost.Success){ Write-Error 'NO-BATCH-HASH' }; if($mpre.Groups[1].Value -eq $mpost.Groups[1].Value){ Write-Error 'BATCH-UNCHANGED' }; $m=[regex]::Match($sec,'(?ms)^### D-93 覆盖表\s*\r?\n(.*?)(?=\r?\n### |\r?\n## |\z)'); if(-not $m.Success){ Write-Error 'NO-MATRIX-SECTION' }; if($m.Groups[1].Value -match '待补'){ Write-Error 'MATRIX-STILL-PENDING' }; foreach($p in $pages){ if($np -notmatch ('(?m)^自查:'+[regex]::Escape($p))){ Write-Error "NO-SELF-CHECK $p" }; if($np -notmatch ('(?m)^已完成扩写:'+[regex]::Escape($p)+'\s*$')){ Write-Error "NO-DONE $p" } }; $d93bad=@(); foreach($p in $pages){ $d93lines=@($sec -split "`r?`n" | Where-Object { $_ -match ('^D-93 抽查:'+[regex]::Escape($p)) }); if($d93lines.Count -eq 0){ $d93bad += ($p+':NO-LINE') } elseif($d93lines[-1] -match '发现缺口'){ $d93bad += $p } }; if($d93bad.Count -gt 0){ Write-Error ('D93-GAP '+($d93bad -join ',')) }; $md=@(Get-ChildItem -LiteralPath 'docs/advanced/ii/ui' -Filter *.md -File); if($md.Count -ne 25){ Write-Error ('MD-COUNT:'+$md.Count) }; $demo=@(Get-ChildItem -LiteralPath 'docs/.vitepress/components/demos/ui' -Filter *.tsx -File); if($demo.Count -ne 24){ Write-Error ('DEMO-COUNT:'+$demo.Count) }; foreach($p in $pages){ $t=[IO.File]::ReadAllText((Resolve-Path -LiteralPath $p)); if($t -match "(?&1; if($LASTEXITCODE -ne 0){ $pc | Write-Output; Write-Error 'PRETTIER-FAIL' }; $el=cmd /c "pnpm exec eslint docs/.vitepress/components/demos/ui" 2>&1; if($LASTEXITCODE -ne 0){ $el | Write-Output; Write-Error 'ESLINT-FAIL' }; if(($el | Out-String) -match 'warning|error'){ Write-Error 'ESLINT-OUTPUT' }; $tc=cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json" 2>&1; $docErr=@($tc | Where-Object { $_ -match '^docs/.*error TS' }); if($docErr.Count -gt 0){ $docErr | Write-Output; Write-Error 'DOCS-TYPE-ERROR' }; $out=cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build" 2>&1; if($LASTEXITCODE -ne 0){ $out | Write-Output; Write-Error 'BUILD-FAIL' }; if(-not($out -match 'build complete')){ Write-Error 'NO-BUILD-COMPLETE' }; if($out -match 'dead link'){ Write-Error 'DEAD-LINK' }; $built=@(Get-ChildItem -LiteralPath 'public/_docs/advanced/ii/ui' -Filter *.html -File -ErrorAction SilentlyContinue); if($built.Count -ne 25){ Write-Error ('PAGE-NOT-BUILT:'+$built.Count) }; foreach($s in @('10-49-SUMMARY.md','10-53-SUMMARY.md','10-54-SUMMARY.md')){ if(Test-Path -LiteralPath ('.planning/phases/10-docs-restructure/'+$s)){ Write-Error ('UNEXPECTED-SUMMARY:'+$s) } }; 'T5-OK' + non-zero exit, or output contains "NOTES-MISSING", "NO-POST-HASH", "NO-BATCH-HASH", "BATCH-UNCHANGED", "NO-MATRIX-SECTION", "MATRIX-STILL-PENDING", "NO-SELF-CHECK", "NO-DONE", "D93-GAP", "MD-COUNT", "DEMO-COUNT", "LF-ONLY", "SCOPE-REDUCTION", "POST-HASH-MISMATCH", "ROADMAP-MODIFIED", "STATE-MODIFIED", "PRETTIER-FAIL", "ESLINT-FAIL", "ESLINT-OUTPUT", "DOCS-TYPE-ERROR", "BUILD-FAIL", "NO-BUILD-COMPLETE", "DEAD-LINK", "PAGE-NOT-BUILT", "UNEXPECTED-SUMMARY"; or output lacks "T5-OK" + + 7 篇的 D-93 覆盖格无 `待补`、逐篇有 `自查:` 与 `已完成扩写:`、`D-93 抽查` 无「发现缺口」;`扩写后本批页面聚合哈希` 与扩写前不同且与重算一致;`本批外文件聚合哈希`、ROADMAP / STATE 全文哈希与基线一致;25 篇 / 24 demo 不变;7 篇 CRLF、无降级表述;prettier / ESLint 0/0 / `docs/` 路径 0 类型错误 / 构建 green + 0 dead link / 25 个 HTML;NOTES 有 `体量参考(扩写后)`(不设 300 行门禁)、`### 10-49 门禁`、`停止点:10-49 扩写结束`;未创建任何 SUMMARY。 + Part 0–1 扩写完成并通过门禁,停在读者循环之前。 + + + + + +## Trust Boundaries + +| Boundary | Description | +|----------|-------------| +| 写作者 → 正文 | 扩写必须按 D-93 讲模型与理由,不能退化成参数表或读者问题补丁 | +| 本计划 → 批外文档 | 只允许改 7 篇;其余 18 篇、导览、demo、侧边栏不得改动 | +| 正文 → 源码 | 源码只用于核对模型事实;不写源码叙述,不把注释冲突写进正文 | +| 本计划 → 账本 | 不写 SUMMARY、不改 ROADMAP / STATE、不 commit | + +## STRIDE Threat Register + +| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan | +|-----------|----------|-----------|----------|-------------|-----------------| +| T-10-168 | Tampering | 批外文档被改动 | high | mitigate | Task 1 记录 `本批外文件聚合哈希`;Task 5 重算比对,不一致即停 | +| T-10-169 | Tampering | 页面被新增 / 删除 | high | mitigate | 每次 verify 断言 `docs/advanced/ii/ui` 25 篇、demo 24 个;不新增导航 | +| T-10-170 | Repudiation | 扩写退化为只补读者问题 | high | mitigate | Task 1 建 D-93 四类覆盖表;每篇覆盖格必须 `已讲` 或 `不适用:理由`;Task 5 抽查 | +| T-10-171 | Tampering | 为凑 300 行注水 | medium | mitigate | 体量只记录不设门禁;D-88 写入 NOTES;禁止接口表堆砌与降级表述 | +| T-10-172 | Information Disclosure | 把 Round 1 读者记录交给用户 | medium | mitigate | Round 1 只作内部输入;本计划不产出用户可读的审阅摘要;10-54 明确不提供读者记录 | +| T-10-173 | Repudiation | 越界写 SUMMARY / ROADMAP / STATE | medium | mitigate | Task 5 校验 ROADMAP / STATE 全文哈希与基线一致;禁止创建 SUMMARY | +| T-10-SC | Tampering | 包管理器安装 | high | mitigate | 不安装任何新包;缺依赖即停止报告 | + + + +- 关卡门禁:Task 0 已获「可以执行」;NOTES 含 `读者审阅:已完成`。 +- 基线门禁:Task 1 写入 7 篇范围、Round 1 计数、基线 HEAD、两个聚合哈希、两个账本哈希、D-93 覆盖表、体量参考。 +- 覆盖门禁:7 篇四类内容格为 `已讲` 或 `不适用:理由`,无 `待补`;每篇有 `自查:` 与 `已完成扩写:`;Task 5 的 `D-93 抽查` 无「发现缺口」。 +- 范围门禁:`docs/advanced/ii/ui` 25 篇、demo 24 个;`本批外文件聚合哈希` 与基线一致;未改导览、侧边栏、`packages*` / `src`。 +- 质量门禁:7 篇 CRLF;prettier `--check`;ESLint 0/0;`docs/` 路径 0 类型错误;`pnpm docs:build` green + `build complete` + 0 dead link;25 个 HTML。 +- 体量门禁:只记录逐篇行数与总行数;不设 300 行下限/上限;不因低于 300 行失败。 +- 停止门禁:NOTES 有 `停止点:10-49 扩写结束`;未创建 SUMMARY;ROADMAP / STATE 哈希未变;未 commit。 + + + +- Part 0–1 的 7 篇按 D-93 讲清渲染树、事件、元素/组件用法与设计原因,每次代码后有模型解释。 +- 读者能从这 7 篇独立复述「组件怎么变成渲染树、坐标/变换怎么传、谁先接事件、缓存什么时候脏」,并能改写示例而不只是照抄。 +- 没有新增/删除页面与 demo,没有改动批外文档、导览、侧边栏、源码。 +- 门禁全绿,体量只作参考记录,本计划停在读者循环之前。 + + + +本计划**不写 SUMMARY**。完成后在对话中报告 7 篇的扩写清单、逐篇行数(体量参考)、D-93 抽查结论与门禁结果,然后停止。读者循环由 `10-53-PLAN.md` 执行,用户审阅由 `10-54-PLAN.md` 执行。 + diff --git a/.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md b/.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md new file mode 100644 index 0000000..7f67c3c --- /dev/null +++ b/.planning/phases/10-docs-restructure/10-49-READER-REVIEW.md @@ -0,0 +1,384 @@ +# 高级 II · UI 25 篇独立读者审阅记录(10-49) + +独立读者按 Part 0→5 顺序只读 25 篇的提问记录,未修改任何文档。 + +## 读者人格(逐字) + +你是一位刚读完中级教程、想给自己的魔塔做一套自定义界面的作者。你完全没写过 UI,不知道 canvas 是什么,也不会 Vue 的组件写法;你只掌握了基础 TS/JS、函数、对象、数组和一点点模板语法。你手里只有这套文档,不能看源码,也没有人可以问。你的任务不是评价文档好坏,而是老老实实按顺序读,读到哪里卡住就记下:我在哪一段卡住、我从文档里已经知道什么、我还缺什么才能继续往下做。 + +## 阅读范围 + +- `docs/advanced/ii/ui/ui-template.md` — 进入前提:会写 TS 函数和对象,想先让一个面板显示出来;不知道 canvas 与 DOM 的区别。 +- `docs/advanced/ii/ui/container-and-coordinates.md` — 进入前提:已有一个能显示的 `container`、`g-rect`、`text`,想弄清楚 `loc` 六元组和嵌套坐标。 +- `docs/advanced/ii/ui/basic-shapes.md` — 进入前提:已会摆容器,想画色块、边框、分隔线。 +- `docs/advanced/ii/ui/curves-and-paths.md` — 进入前提:已会矩形、圆和直线,想画曲线、路径、圆角。 +- `docs/advanced/ii/ui/text.md` — 进入前提:已会图形,想显示单行文字、字体和居中。 +- `docs/advanced/ii/ui/image-and-texture.md` — 进入前提:已会文字和图形,想显示图标、贴图、像素画。 +- `docs/advanced/ii/ui/layer-transform-performance.md` — 进入前提:已会摆元素,想处理遮挡、缩放旋转、显示开关和缓存。 +- `docs/advanced/ii/ui/reactivity.md` — 进入前提:已能写静态界面,想让数据变化自动更新画面。 +- `docs/advanced/ii/ui/events.md` — 进入前提:已会响应式,想接点击、悬停、滚轮。 +- `docs/advanced/ii/ui/hotkey-in-ui.md` — 进入前提:已会点击事件,想接 Esc、Enter 这类按键。 +- `docs/advanced/ii/ui/conditional-and-list-rendering.md` — 进入前提:已会事件和响应式,想按条件显示、循环生成列表。 +- `docs/advanced/ii/ui/props.md` — 进入前提:已会写单个组件,想拆父子组件传数据。 +- `docs/advanced/ii/ui/component-tsx.md` — 进入前提:已会 props,想写完整组件、生命周期和 `expose`。 +- `docs/advanced/ii/ui/slots-and-attrs.md` — 进入前提:已会组件,想让父组件塞内容、透传属性。 +- `docs/advanced/ii/ui/builtin-text-and-input.md` — 进入前提:已会自己拼组件,想用现成的换行文本、说明框、输入框。 +- `docs/advanced/ii/ui/builtin-list-and-containers.md` — 进入前提:已用过文本与输入组件,想用现成的列表、分页、滚动、一次性弹窗。 +- `docs/advanced/ii/ui/ui-controller-and-stack.md` — 进入前提:已能打开一个面板,想管多个面板的叠放、背景和主 UI。 +- `docs/advanced/ii/ui/replace-builtin-ui.md` — 进入前提:已会 UI 栈,想把设置、存档、工具栏换成自己的。 +- `docs/advanced/ii/ui/ui-performance.md` — 进入前提:已能搭面板和栈,想知道哪里会卡、哪些开关能省。 +- `docs/advanced/ii/ui/inventory-example-1-skeleton.md` — 进入前提:已学完零件(模板、元素、响应式、事件、组件、内置组件、栈),但没把它们装成一个面板;本篇给目标与骨架。 +- `docs/advanced/ii/ui/inventory-example-2-grid.md` — 进入前提:已有 720×480 骨架和左右两个占位区,但不知道道具数据、格子和网格怎么填。 +- `docs/advanced/ii/ui/inventory-example-3-detail.md` — 进入前提:已有可点击选中的 5 列网格,但右侧仍是占位,不知道详情怎么接选中项。 +- `docs/advanced/ii/ui/inventory-example-4-scroll.md` — 进入前提:网格与详情能用,但道具一多左侧放不下。 +- `docs/advanced/ii/ui/inventory-example-5-state.md` — 进入前提:面板能看能选,但还不能装备、使用、关闭。 +- `docs/advanced/ii/ui/inventory-example-6-animation-and-register.md` — 进入前提:功能基本齐了,要做动画、落回五个文件、注册成 UI。 + +## 逐篇提问 + +| 篇目 | 位置 | 我已经从文档知道什么 | 我还缺什么 | 我照着做会预期什么 | +| --- | --- | --- | --- | --- | +| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(开头两段与完整模板代码块) | 界面是画布上的框架元素,不是 DOM;TSX 写结构、Vue 管组件与响应式;模板由 Props 类型、Props 列表、组件、`GameUI` 注册四部分组成;四个 import 分别来自 `vue`、`@motajs/system`、`@motajs/render-vue`、`@user/client-base`;注册名是 `'my-panel'`。 | 这个 `.tsx` 文件该放在哪个目录、文件名有没有约束、构建或游戏如何发现它;`export const MyPanelUI` 之后是否还要在别处被 import 或登记;这四个包别名在我的项目里是否已存在、要不要配置。 | 新建一个文件、原样粘进去保存,游戏里就应该能出现面板——但不知道保存后去哪里看,也不知道要不要重启、重新构建或额外注册。 | +| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(`defineComponent` 与 `satisfies` 那一段) | `props` 列表至少含 `controller`、`instance`、`state`;setup 返回 render 函数;组件用 `defineComponent` 包起来;Props 接口同时继承 `IGameUIPropsBase` 与 `DefaultProps`。 | `defineComponent` 的两个参数各是什么、外层那个 `props` 参数从哪里来、为什么里面还要 `return () =>` 再包一层;`satisfies` 与泛型在这里起什么作用;JSX 里 `{/* */}` 注释、`` 只有属性名的写法是什么语法;想加自己的字段时改接口还是改列表。 | 原样复制能跑;一旦想改结构或加字段就可能写错,而且按文档提醒属性名写错不报错,我不知道该怎么自查。 | +| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(三个元素的说明与 `loc`) | `loc` 前两项是左上角坐标、后两项是宽高;`g-rect` 要 `fill` 才有填充、`fillStyle` 才是颜色;`text` 的内容放 `text` 属性;`container` 是布局单位也是事件捕获单位。 | 坐标原点在哪、单位是不是像素、`loc` 相对父容器还是相对画布;`480×320` 与游戏画布或窗口是什么关系;面板会出现在屏幕的哪个位置;`g-` 前缀是什么意思;窗口变化后会不会被拉伸或裁掉。 | 按示例填 `480×320` 界面能显示,但不知道会不会超出可视区、换个尺寸该按什么基准算,也不知道面板默认落点在左上还是居中。 | +| docs/advanced/ii/ui/ui-template.md | ## 一个最小 UI(等价的原生元素代码块) | 同一画面可以用 `Container`、`Rect`、`Text` 手动 `pos`/`size`/`setFillStyle`/`setText`,再 `appendChild` 挂到根容器上。 | 这些类从哪个包 import(上一段只 import 了 `defineComponent`、`GameUI`、`SetupComponentOptions`、`DefaultProps`、`IGameUIPropsBase`);`root` 创建后挂到哪里才可见、是否必须写在某个 `GameUI` 的 render 里;这条路线还需要 `GameUI` 注册吗;两条路线该选哪条、能否混用。 | 直接抄这段会得到一份能编译、但不知道如何让它显示、也不知道缺哪些 import 的代码;也不确定它是不是「不写 Vue 的正式方案」。 | +| docs/advanced/ii/ui/ui-template.md | ## 只改哪几行 与 ## 打开与关闭 | 打开有三处:场景 UI 用 `props.state.sceneController.open(MyPanelUI, {})`、另一个 UI 内用 `props.controller.open(...)`、关闭自己用 `props.controller.close(props.instance)`;主 UI 栈用 `props.state.mainUIController.open(...)`,细节留到后面;没有全局 `client`。 | 第一次让面板出现该挑哪一个;表格写的「主入口 / 另一个 UI 内 / 主 UI 栈」与下一节三个代码段(场景 UI / 另一个 UI / 关闭自己)怎么对应;`open` 第二个参数 `{}` 里能放什么、放进去后怎么在面板里取到;`instance` 是什么、为什么 `close` 要传它;`sceneController` 与 `mainUIController` 从哪来、有什么区别。 | 会在场景 UI 与主 UI 栈之间犹豫,可能先抄场景那条;但不知道面板出现后是否被主界面盖住、是否与主界面同时存在,也不知道怎么把自己的参数带进面板。 | +| docs/advanced/ii/ui/container-and-coordinates.md | 坐标从哪里来 | 根容器左上角是原点,向右为正 x、向下为正 y;子元素相对父容器,每层重新平移 | 这个“根容器”是不是就是游戏画面?我写的 `[0, 0, 480, 320]` 和游戏窗口是什么关系,会不会被缩放 | 把根容器贴到左上角,界面就出现在画面左上角 | +| docs/advanced/ii/ui/container-and-coordinates.md | loc 与锚点 | `loc` 是 x、y、width、height、anchorX、anchorY 六元组,后三项可省略;`anc` 是简写;默认尺寸 200×200 | “后三项可以省略”到底指 height、anchorX、anchorY 三项,还是只指两个锚点?如果我省略宽高,是不是就变成 200×200 | 省略锚点后元素仍在左上角;省略宽高后元素是 200×200 | +| docs/advanced/ii/ui/container-and-coordinates.md | 一个嵌套示例 | 两段等价写法,一段 TSX、一段 `appendChild`;子坐标相对父容器 | 这段 TSX 应该放在哪里?第 1 篇的模板里有 `return () => (...)`,这里却是裸露的标签;`container`、`g-rect` 是全局可用还是要 import | 把嵌套示例整段塞进 render 函数就能看到两个区域 | +| docs/advanced/ii/ui/container-and-coordinates.md | 层级 | `zIndex` 越大越靠上,也影响命中;不改变坐标 | 两个不同父容器里的子元素,`zIndex` 还能互相比较吗?我想让 A 容器里的提示框盖住 B 容器,只给提示框大 `zIndex` 够不够 | 给提示框加大 `zIndex` 就能盖住旁边的容器 | +| docs/advanced/ii/ui/basic-shapes.md | 四个图形 | `g-rect`、`g-circle`、`g-ellipse`、`g-line` 及各自几何属性;元素层对应 `Rect`、`Circle`、`Ellipse`、`Line` | 元素层的这些类从哪里 import?TSX 里的标签又从哪里来?文档只给了类名,没有 import 行 | 照抄类名就能 new 出来并挂到容器上 | +| docs/advanced/ii/ui/basic-shapes.md | 填充与描边 | `fill`、`stroke`、`strokeAndFill` 是模式开关,颜色在 `fillStyle`、`strokeStyle`;线宽、虚线、端点、连接样式 | 如果我同时写 `fill` 和 `stroke` 两个开关,而不是 `strokeAndFill`,会得到什么?文档没说冲突时谁优先 | 同时写两个开关也能得到填充加描边 | +| docs/advanced/ii/ui/basic-shapes.md | 圆角与命中 | 圆和椭圆用 `radius`、`radiusX`、`radiusY`;`actionStroke` 只让描边响应点击 | 这节标题叫“圆角与命中”,可我真正想找的是“矩形圆角”,这里没有;我会以为 `g-rect` 也能给圆角 | 给 `g-rect` 加 radius 想得到圆角矩形,结果文档没这条属性 | +| docs/advanced/ii/ui/curves-and-paths.md | 三次贝塞尔 / 二次贝塞尔 | `g-bezier` 八元数组、`g-quad` 六元数组,顺序固定,长度错不报错但画错 | 这两个元素没有 `loc`,那曲线画在哪个坐标系?我想把整条曲线挪个位置,是改所有点,还是外面包一层容器 | 曲线坐标相对父容器原点,想移动就包容器 | +| docs/advanced/ii/ui/curves-and-paths.md | 路径 | `g-path` 的 `path` 必须是 `Path2D`,不能传字符串;用 `moveTo`、`lineTo` 组路径 | `Path2D` 从哪里来?是浏览器全局对象还是要 import?我的 TS 环境里直接写 `new Path2D()` 会不会报找不到名字?路径能不能用 `loc` 平移 | 直接 `new Path2D()` 就能用,路径从父容器原点开始画 | +| docs/advanced/ii/ui/curves-and-paths.md | 圆角矩形 | `g-rectr` 用 `circle` 或 `ellipse` 指定圆角;`circle` 支持 1 到 4 项,`ellipse` 支持 2、4、6、8 项 | `circle` 三项时“按顺序细分”具体是三口角各一个、第四个跟着谁?`ellipse` 每两个值对应哪个角?我无法从文字推出角与值的映射 | 三项圆角能猜到顺序,但实际四角效果只能试 | +| docs/advanced/ii/ui/text.md | 一行文字 | `text` 属性放内容,`fillStyle` 默认白色;描边用 `strokeStyle` 与 `strokeWidth`,描边计入尺寸 | `Text`、`Font` 从哪个包 import?TSX 里能不能直接写字号,还是一定要造 `Font` 实例 | 照抄 `new Text()` 和 `new Font()` 就能用,但 import 行要自己猜 | +| docs/advanced/ii/ui/text.md | 字体 | `Font` 构造参数顺序 `(family, size, sizeUnit, weight, italic)`;默认值用 `Font.defaults()`,改少量用 `Font.clone` | 怎么设置全局默认字体?`Font.defaultFamily` 这些静态默认值可不可以直接赋值?我只能每个文字都 clone 一遍 | 改静态默认值就能全局生效,或者只能逐个传 `font` | +| docs/advanced/ii/ui/text.md | 尺寸与居中 | 文字宽高由测量决定,给 `width`、`height` 不裁剪;锚点 0.5 让 x、y 落在中心 | 示例同时写了 `loc` 里的两个锚点和外面的 `anchorX`、`anchorY`,重复时以哪个为准?垂直居中算不算行高和描边 | 两种写法结果一样;但如果不一样我也不知道该信哪个 | +| docs/advanced/ii/ui/image-and-texture.md | 图片元素需要什么 | `image` 属性接收纹理对象,`loc` 决定画多大,纹理会被拉伸铺满 | 我只有一张 PNG 图标文件,怎么把它变成纹理对象?文档只教了用 canvas 现画一张,没有讲加载文件 | 我能显示文档里画的棋盘,但放不进自己的图标 | +| docs/advanced/ii/ui/image-and-texture.md | 造一张最小纹理 | `Texture` 来自 `@motajs/render`,接受 `HTMLCanvasElement`、`ImageBitmap`、`HTMLImageElement`;用 `document.createElement('canvas')` 画棋盘 | 我不知道 canvas 是什么,`getContext('2d')`、`fillRect` 只是照抄;文档还提到 `onMounted`,但没介绍它是什么、在哪里写 | 复制这段代码能出棋盘,但换图片源时卡住 | +| docs/advanced/ii/ui/image-and-texture.md | 像素图设置 | `noanti` 关抗锯齿且优先于 `anti`,`hd={false}` 关高清缓存,两者一起关才有硬边 | “高清缓存 / 逻辑像素”是什么意思?如果我的 UI 整体被缩放,`hd={false}` 会不会反而糊 | 像素图按文档设置后边缘变硬 | +| docs/advanced/ii/ui/image-and-texture.md | 应用层素材标签 | 存在 `icon`、`winskin`、`map-render` 三个标签,分别用于图标、窗口皮肤、地图渲染 | 它们“按应用层素材约定使用”,可约定在哪?没有链接也没有示例;我正想做物品图标,却无法从这里继续 | 想用 `icon` 显示物品图标,但不知道标签怎么写、素材放哪 | +| docs/advanced/ii/ui/layer-transform-performance.md | 遮挡:zIndex | `zIndex` 大者后绘制、先命中;不改变坐标与父布局 | 跨容器时是否同一套层叠?父容器没设 `zIndex`,子元素的大 `zIndex` 能不能压过另一个后绘制的容器 | 提示框放在列表容器里也能盖住外层其他区域 | +| docs/advanced/ii/ui/layer-transform-performance.md | 变换:scale、rotate 与 alpha | `scale` 必须两元数组,`rotate` 用弧度,`alpha` 为 0 到 1,绕锚点变换 | 缩放容器时子元素和命中区域会一起缩放吗?旋转后点击区域还是原来的矩形吗 | 缩放容器后里面文字和按钮都跟着缩,点击位置也对 | +| docs/advanced/ii/ui/layer-transform-performance.md | 显示开关:优先 hidden | `hidden` 不显示不交互但保留状态;三元会卸载并重置状态;给了选用场景清单 | `const open = ref(true)` 里的 `ref` 从哪来?这一篇在第 8 篇之前就用了响应式和 `onClick`,我照抄会不知道缺什么 | 照抄开关示例就能点开面板,但实际会因没引入 `ref` 卡住 | +| docs/advanced/ii/ui/layer-transform-performance.md | 缓存:cache 与 nocache | 默认缓存 `container`、`custom`、`container-custom`;默认不缓存 `text`、`image`、`template` 和全部 `g-*`;`nocache` 优先 | 缓存后“让元素知道自己脏了才会重绘”,可怎么让它知道?改文字、换颜色、滚动列表后要不要手动标脏 | 给静态面板开缓存会变快,但动态内容可能停在旧画面且我不知道怎么修 | +| docs/advanced/ii/ui/layer-transform-performance.md | `noevent:可见但不接收交互`;`filter 与 composite` | `noevent` 继续绘制但跳过命中,事件下穿,`cursor` 失效;`filter` 与 `composite` 两个属性存在,接受滤镜字符串与混合模式,取值很多、入门不必记 | 把 `noevent` 加在容器上,是整棵子树都不接收,还是只容器自身?遮罩里的子元素还能点吗;具体有哪些可用值?文档明确说再查,但没说去哪里查 | 弹窗遮罩加 `noevent` 后,下面所有按钮恢复可点;做暗色遮罩用 `alpha` 就够,暂时不用这两个 | +| docs/advanced/ii/ui/reactivity.md | `## ref:带 value 的盒子`(第 15–35 行示例) | `ref` 读写要写 `.value`;点击改 `count.value`,渲染函数里读它就记录依赖;`defineComponent` 返回 render 函数 | 第 1 篇说 UI 组件必须继承 `IGameUIPropsBase` 配 `DefaultProps`、props 列表要有 controller/instance/state、还要 `new GameUI(...)` 注册;这里的 `defineComponent(() => ...)` 既没有 props 参数也没有第二参数和注册。我不知道它算不算一个能打开的 UI | 直接把这段当面板用,发现没有可打开的入口;套回第 1 篇模板后,又不知道 `ref` 该写在 setup 的哪一步、结构怎么并进原来那份 TSX | +| docs/advanced/ii/ui/reactivity.md | `## reactive:一整块对象`(第 50–71 行) | `reactive` 返回代理,字段读写不用 `.value`;不能整体替换;解构丢响应式,要逐字段赋值 | 这段 `const panel = reactive(...)` 写在哪一层?模块顶层、`setup` 内、还是渲染函数外?写模块顶层时,打开两个面板会不会共用同一份 `panel` | 放在模块顶层后,开两个面板改一个另一个跟着变;或者放在组件内却每次重渲染都被重建,两种结果我都不知道哪个才是文档意图 | +| docs/advanced/ii/ui/reactivity.md | `## watch:副作用`(第 103–117 行) | `watch(源, (next, prev) => ...)`,数据变化后执行回调,适合日志/同步/一次性动作 | 组件卸载时 watch 要不要手动停?文档只对快捷键作用域说了自动清理,对 watch 一句没提 | 反复开关面板后旧回调还在跑、越积越多;我不知道该不该把返回的停止函数存起来 | +| docs/advanced/ii/ui/reactivity.md | `## 什么时候用 shallowRef 与 markRaw`(第 119–126 行) | 大对象整体替换用 `shallowRef`;外部实例用 `markRaw`;不确定就先用 `ref`/`reactive` | 第 6 篇的 `Texture`、画布这类对象算不算「外部实例」,要不要 `markRaw` 包一层再塞进组件?两篇之间没有一句话把它们接起来 | 把纹理放进 `ref` 后不确定会不会被 Vue 深层代理、会不会变慢或行为异常,只能先不管 | +| docs/advanced/ii/ui/reactivity.md | `## props 不要解构`(第 128–140 行) | 不要解构 `props`,直接读 `props.title`;完整写法在第 12 篇 | 本篇所有示例都没出现 props 参数,我不知道在 `defineComponent(() => ...)` 里 `props` 从哪来、要不要先声明 props 列表才收得到 `title` | 照着写 `props.title` 会拿不到值或类型报错,只能先跳过这段、等第 12 篇 | +| docs/advanced/ii/ui/events.md | `## 事件对象`(第 32–59 行) | `offsetX/offsetY` 相对触发元素,`absoluteX/absoluteY` 相对画布;`identifier` 区分多指;`type` 是按键种类;`buttons` 是位组合,判断左键要用位运算 | `type` 的可选值到底是什么(数字、字符串还是枚举)?判断左键该写 `ev.type === ?`?`buttons` 的左键位掩码是多少?文档只说「用位运算」,没给常量 | 想实现「只响应左键」时无从下手,只能先对所有按键都响应,或者去猜魔法数字 | +| docs/advanced/ii/ui/events.md | `## 捕获与冒泡`(第 61–77 行) | 捕获从外层向内、冒泡从内向外;`stopPropagation()` 分阶段阻止且不阻止同一元素其它监听器;示例给了父 `onClickCapture` + 子 `onClick` | 示例里父容器的捕获和子元素的冒泡到底谁先执行?正文那句「子元素先捕获、父元素后冒泡」让我拿不准顺序;同一元素上 `onClick` 与 `onClickCapture` 的相对顺序也没说 | 照抄写日志时,最后显示的值和我以为的执行顺序相反,我却判断不出是自己理解错还是写法有问题 | +| docs/advanced/ii/ui/events.md | `## 一组完整的交互`(第 116–154 行) | 用 `ref` 驱动颜色、光标、滚轮累计;事件回调只改 `ref`,画面由渲染函数按当前值生成 | 这段同样是裸 `defineComponent`,没有 props、没有 GameUI 注册,我不知道它作为「完整交互」能不能直接挂进游戏;也不知道 `onWheel` 在子元素铺满父容器时还能不能触发 | 放进文档 demo 能跑,搬进真实面板后整块打不开,或者滚轮完全没反应 | +| docs/advanced/ii/ui/events.md | `## enter 与 leave 不走普通冒泡`(第 79–81 行) | enter/leave 由根节点悬停集合统一触发,不按普通冒泡传递;父级要感知就自己在父级挂 | 鼠标从父容器移到它的子元素上,会不会触发父级 leave 再 enter?父子之间的悬停边界怎么算?文档没给判定 | 做悬停高亮时,鼠标扫过子元素导致父级反复 enter/leave,画面闪烁,我不知道该怎么规避 | +| docs/advanced/ii/ui/events.md | `## actionStroke:只把描边算作命中`(第 112–114 行) | 加 `actionStroke` 后只有描边算命中,内部区域下穿 | 描边只有 1px 时,命中区是不是也只有 1px、有没有最小命中宽度?第 3 篇说它不改绘制,但没说命中宽度是否跟 `lineWidth` 走 | 细边框几乎点不中;我不知道该不该配合加大 `lineWidth`,加大又会让视觉变粗 | +| docs/advanced/ii/ui/hotkey-in-ui.md | `## useKey:拿到当前组件的作用域`(第 21–28 行) | `useKey` 必须在 `setup` 中同步调用,返回当前组件的按键实现对象;组件卸载自动离开;可以直接用非空断言 `!` | `useKey` 从哪个包 import?这段没有 import;`props.state.hotkey.system` 这条路径也没解释(第 1 篇只说 `props.state` 是 ClientCore);这段该放在 `defineComponent` 的哪个位置也没说 | 复制后编译报 `useKey` 未定义,或者 `props` 在该作用域根本不存在 | +| docs/advanced/ii/ui/hotkey-in-ui.md | `## implement:把指令接到回调`(第 32–46 行) | `implement` 可连续调用、返回对象本身;同一次挂载对同一指令重复 implement 会覆盖 | 指令 id 拼错、或指令还没注册就 implement,会发生什么(报错还是静默)?文档没说 | 写了 `@common/exit` 按 Esc 没反应,我分不清是 id 错、作用域没挂上,还是被上层界面抢先处理了 | +| docs/advanced/ii/ui/hotkey-in-ui.md | `## 触发方式:HotkeyEmitMode`(第 74–82 行) | 三种模式:默认 `KeyUp` 抬起、`Once` 按下一次、`Continuous` 按住持续并配合 `interval` 控制最小间隔 | `interval` 写在哪个字段、单位是毫秒还是帧、默认多少?`addCommand` 的完整配置项也没列全(目前只见过 defaults/mode/priority/block) | 想做「按住连续翻页」时不知道 `interval` 怎么填,只能反复试数字 | +| docs/advanced/ii/ui/hotkey-in-ui.md | `## 优先级与阻断`(第 84–95 行) | `priority` 越高越先执行,目前只对抬起触发有效;`block` 阻断更低优先级;同优先级全部执行、不互相阻断 | 同时挂着多个界面(主界面 + 弹出面板)时,它们的按键作用域怎么排序?`priority` 是全局比较还是只在同一作用域内比较?文档没说 | 面板打开时按 Esc,可能同时关掉面板和下层界面,或者关掉的根本不是我以为的那一层 | +| docs/advanced/ii/ui/hotkey-in-ui.md | `## 注册新指令与分组`(第 48–72 行) | `addCommand(id, 显示名, { defaults, mode })`;`setGroup(id, 显示名, [指令])`;`defaults` 是二维数组,组内最后一个是主按键,前面的要先按住;不分组也能用 | 组合键的实际写法没有示例(例如 Ctrl+S);`KeyCode` 还有哪些值、能不能用字符串代替也没说 | 想加 Ctrl 组合键时不知道数组该怎么排,只能先只做单键 | +| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 循环:用 map 生成元素`(第 50–65 行) | TSX 没有循环指令,用 `labels.map(...)` 返回元素数组;固定顺序、无内部状态的列表不需要 key | 这段 `{ labels.map(...) }` 应放在渲染函数的哪个位置、外面要不要包 `container`?示例是游离表达式,不是完整 return;map 出来的元素是否必须有父容器也没说 | 直接贴进 render 会结构不对,或者元素没有父容器导致定位异常 | +| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## key:只在需要保留身份时加`(第 67–96 行) | 会增删、重排且需要保留身份时用稳定 id 作 key;不要用数组下标代替会变化的身份;无状态固定列表不加 | 怎么在 `ref` 数组上做增删(push / splice / 整体替换)才会触发更新?文档只给了初始 `ref([...])` 和渲染,没有修改示例 | 往 `rows.value` 里 push 一项后界面不刷新,或刷新行为和预期不同,只能猜哪种改法有效 | +| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 三种写法怎么选`(第 98–105 行) | 四种组合的条件与结果对照:hidden 保留状态、三元重置、固定列表 map 不要 key、动态列表 map + key | 列表项如果是自定义组件(不是 `text` / `g-rect`),key 写在哪一层、是否和普通元素一样?表格没覆盖组件项 | 给组件列表加 key 时不确定加在组件标签上还是外层容器上,可能加错层级导致状态仍然错位 | +| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 条件:优先 hidden`(第 5–25 行) | `hidden` 不显示、不交互但保留元素与状态;频繁开关的面板用它 | `hidden` 的元素还占不占布局位置、会不会影响兄弟元素定位?第 2 篇说坐标相对父容器,我猜不影响,但这一篇没有确认 | 隐藏上方区域后,不确定下面的元素会不会上移;如果会,我就得改用三元 | +| docs/advanced/ii/ui/conditional-and-list-rendering.md | `## 边界与注意`(第 125–130 行) | hidden 元素仍在树里;三元成本在初始化与状态重置;map 每项结构要稳定;key 不是性能开关也不是修重挂载的手段 | 「不要在同一处混用不同标签却不给 key」和前文「固定顺序无状态不需 key」的边界在哪?什么算「混用不同标签」 | 列表里同时有 `text` 与 `g-rect` 时,不确定要不要补 key,加了又怕违背「无状态不要加」 | +| docs/advanced/ii/ui/props.md | L35–L48:`SetupComponentOptions` 与 `defineComponent<...>` 的三个泛型 | 第 1 篇的模板只写了一个泛型 `defineComponent(props => ..., propsList)`;第 12 篇说要先声明 Props 接口,再把用到的键列进 `props` 数组。 | 第二个泛型 `ItemCellEmits` 和第三个 `keyof ItemCellEmits` 分别代表什么;`keyof` 在这里为什么能当第三个参数;什么时候必须写满三个、什么时候一个就够。文档没有一处把泛型顺序讲成一句话。 | 照抄 `ItemCell` 能跑;但自己新建一个组件时不知道该复制几个泛型,可能只写一个泛型、把 `emits` 漏掉,或把 `keyof` 写错位置。 | +| docs/advanced/ii/ui/props.md | L91–L93 与 L175–L182:父组件写 `v-model:selected={pickedA.value}` / `v-model:open={open.value}` | 第 1、11、13 篇都反复说“TSX 里没有模板指令”;第 12 篇说 `update:xxx` 只通过 `v-model:xxx` 消费,等价于“传入值并在子组件发出 `update:xxx` 时写回”。 | 既然 TSX 里没有模板指令,`v-model:selected` 这串东西在 JSX 属性位置到底怎么被识别;它写回的是 `pickedA.value` 还是 `pickedA`;为什么同篇又说“属性名必须 camelCase”,而这里 `v-model:selected` 带冒号。 | 照写后不确定 `v-model:selected` 会真正建立双向绑定,还是被当成一个普通属性透传下去;可能退回去手写 `selected` 加 `onUpdate:selected`,又和文档“不要写成手动监听”冲突。 | +| docs/advanced/ii/ui/props.md | L233:边界与注意里的“属性会落到 `attrs` 而不是 `props`” | 第 1 篇说 props 数组少写一个键就拿不到值;第 12 篇说漏写键名等于没传。 | `attrs` 是什么、在哪个对象上、是不是自动生效;这一篇只提了一句,定义要到第 14 篇才出现。 | 传了 `size` 却没生效时,不知道该先查 `props` 数组、`attrs`,还是属性名大小写;照抄时容易把“漏写键名”误判成组件没渲染。 | +| docs/advanced/ii/ui/props.md | L112–L129:`const size = props.size ?? 64` 与 `computed(() => props.size ?? 64)` 的差别 | 知道默认值用 `??`,不能给 props 赋值;setup 顶部读一次只保留挂载时的值,`computed` 会跟着 props 更新。 | 示例里的 `size` 正好是“不会变的基础尺寸”,但父组件示例又给三个格子传了不同的 `size`;如果父组件之后改 `size`,哪个写法会重画、哪个不会,需要自己从“读一次”推断。 | 照抄 `const size = props.size ?? 64` 并把 `size` 用在 `loc` 里,父组件后续改 `size` 时格子不变化,容易当成渲染失败。 | +| docs/advanced/ii/ui/props.md | L78–L94:父组件直接写 ``,但没有 import 片段 | 知道 TSX 里元素标签是小写的 `g-rect`/`text`;知道父组件准备数据、子组件通过 props 接收。 | 大小写标签的规则没有被明确说出;`ItemCell` 从哪里 import、组件和普通元素在 TSX 里靠什么区分;父组件这段代码是否要放进 render 函数。 | 复制父组件片段时会缺 import,或把 `` 当普通元素理解,导致不知道该怎么在页面里注册/引入子组件。 | +| docs/advanced/ii/ui/component-tsx.md | L31–L44 与 L111–L133:有的 `defineComponent` 带第二个参数,有的不带 | 第 12 篇的 `ItemCell` 和本篇的 `ItemCell`/`Card` 都传了第二个参数 `itemCellProps`/`cardProps`;本篇 `Ticker` 写的是 `defineComponent(() => {...})`,没有第二个参数。 | 第二个参数在什么时候可以省略;没有 props 的组件是否必须写一个空 options;省略后还会不会生成 props 数组、`emit` 还能不能用。文档只展示了两种写法,没有给判断规则。 | 自己写一个无 props 的小组件时,可能完全不写第二个参数;一旦以后要加 prop,又不知道是该补 options 还是靠别的方式声明。 | +| docs/advanced/ii/ui/component-tsx.md | L157–L212:`expose` 与父组件 `const card = ref()`、`` | 知道 `emit` 是子发父、`expose` 是父调子;知道第 8 篇的 `ref` 是带 `.value` 的响应式盒子。 | `ref()` 什么时候被赋值、由谁赋值;`expose` 暴露的对象和 `ref` 之间是谁绑定的;父组件片段只 import 了 `ref`,`CardExpose`/`Card` 从哪来;`ref={card}` 在 TSX 里是不是普通属性。 | 照抄后点按钮调用 `card.value?.focus()` 可能一直是 `undefined`,或 `card.value` 拿到的是整个组件实例而不是 `{ focus }`;不知道要不要等 `onMounted`。 | +| docs/advanced/ii/ui/component-tsx.md | L104–L141:`onMounted` / `onUnmounted` 与 `window.setInterval` | 知道生命周期钩子要在 setup 体内同步调用;在 `onMounted` 里建监听/定时器,在 `onUnmounted` 里清;第 6 篇也提过纹理放 `onMounted`。 | “同步调用”具体指不能放在 `await` 之后还是不能放在回调里;`window.setInterval` 返回的 `number` 与浏览器/Node 类型差异;示例的 `let timer: number \| undefined` 为什么不用 `null`。 | 照抄定时器能跑;但把 `onMounted` 写进一个 `async` 函数或事件回调时,会静默不生效,读者不知道是自己写错还是环境问题。 | +| docs/advanced/ii/ui/component-tsx.md | L216–L230:组件与 UI 的区别表 | 知道普通组件只需继承 `DefaultProps`,UI 必须同时继承 `IGameUIPropsBase` 与 `DefaultProps`,且 props 数组包含 `controller`/`instance`/`state`;知道 UI 由 `GameUI` 注册。 | 把面板拆成普通组件后,`controller`/`instance`/`state` 要不要作为 props 往下传;普通组件如果需要关闭面板,应该自己发 emit 还是接收 controller。 | 按“普通组件不需要这三个值”去拆背包面板,拆到一半发现子组件里的关闭按钮拿不到 `controller`,再回头改 props 接口。 | +| docs/advanced/ii/ui/slots-and-attrs.md | L24–L37:`SlotsType`、`defineComponent` 的四个泛型 | 第 12/13 篇已经见过一个泛型和三个泛型;知道 props 接口、emits 接口。 | 第二个泛型 `{}`、第三个 `string`、第四个 `PanelSlots` 各对应什么;为什么这里没有 emits 却要写 `string`;四个泛型的顺序从哪来。文档没有解释 `string`,也没有解释 `SlotsType` 与第四个泛型的关系。 | 照抄 `Panel` 能编译;自己写一个同时有 emits 和 slots 的组件时,不知道 `emits` 该放第二个还是第三个泛型,容易把类型放错位置导致 props/emit 推断全错。 | +| docs/advanced/ii/ui/slots-and-attrs.md | L29–L35 与 L113–L122:手写 `PanelOptions` / `FieldOptions` 代替 `SetupComponentOptions` | 第 12 篇明确说第二个参数由 `SetupComponentOptions` 约束,`props` 数组和 `emits` 数组都在这里声明;第 13 篇也照这个写法。 | 为什么第 14 篇改成自己声明 `interface PanelOptions { props: (keyof PanelProps)[] }` 和 `interface FieldOptions { props: ...; inheritAttrs: boolean }`;两套写法是否等价、能不能混用;`props: []` 空数组是否合法。 | 照抄 `Panel` 后,再写下一个组件时不知道应该用 `SetupComponentOptions` 还是手写 options;可能两套都写,或漏掉 `emits` 的类型约束。 | +| docs/advanced/ii/ui/slots-and-attrs.md | L61–L90:默认 slot 用标签之间内容,具名 slot 用子节点位置上的对象 `{{ title: ..., default: ... }}` | 知道 slot 在 TSX 里是函数;子组件用 `slots.default?.()`、`slots.title?.(...)` 调用;知道 `?.` 不能省。 | 父组件把具名 slot 写成“标签之间的一个对象”依据是什么;这个对象会被当成普通子节点、还是被 Vue 识别成 slots;默认 slot 的 `` 与具名 slot 的对象能否同时出现、顺序有没有要求。 | 照抄具名 slot 时可能把对象当成普通 children 传下去,结果 Panel 里什么都不显示;或者默认内容与具名对象混写后只有一个生效。 | +| docs/advanced/ii/ui/slots-and-attrs.md | L106–L137:`attrs` 与 `{...attrs}` 透传、`inheritAttrs: false` | 知道没有被 props 声明、也没有被 emits 消费的属性会进入 `attrs`;可以 `{...attrs}` 原样交给内部元素;属性名仍然是 camelCase,透传不做转换。 | `attrs` 是不是响应式、父组件后续改属性时内部 `` 会不会更新;`loc` 这种数组属性展开后是否原样可用;`inheritAttrs` 默认行为下属性会不会“既落根元素又落 text”两份;示例里的 `Font` 没有 import。 | 写 `` 后,不确定属性最终落在 `Field` 的根元素还是内部 `text`,可能看到重复定位或样式不生效。 | +| docs/advanced/ii/ui/slots-and-attrs.md | L98–L102:作用域 slot 的数据由子组件传入 | 知道子组件调用 `slots.default?.({ count: 3 })`,父组件函数参数里拿到 `data`;知道 slot 类型写成 `(data: PanelData) => VNode`。 | 父组件函数参数的类型如何与子组件的 `PanelData` 对齐;如果父组件不写类型、或子组件改了传参结构,TS 会不会报错、运行时会不会静默变成 `undefined`。 | 照抄后能显示;但把 `count` 改名或加字段时,父组件可能仍按旧字段读,画面显示 `undefined` 而不知道是类型没接上。 | +| docs/advanced/ii/ui/builtin-text-and-input.md | `## TextContent:会换行的文字` 中 `loc={[40, 40]}` 与 `width={360}` | 知道 `width` 是必填的最大宽度,`autoHeight` 让高度跟内容走,`loc` 负责定位 | 不知道 `loc` 里的宽高和 `width` 是什么关系;`autoHeight` 时 `loc` 的 height 还要不要写;不写 height 会不会落到默认 200 | 照抄后能看到文字,但一旦想把它放进固定高度的区域,就不知道该改 `loc` 还是改 `width`,也不知道最终高度由谁决定 | +| docs/advanced/ii/ui/builtin-text-and-input.md | `## TextContent` 中 `interval={40}` | 知道 `interval` 是逐字显示的间隔,省略或为 0 时直接显示全部 | 不知道单位是毫秒还是别的;40 是快还是慢;也不知道能不能中途改速度 | 复制后只能凭感觉调数字;想做“快进/慢速”时没有依据 | +| docs/advanced/ii/ui/builtin-text-and-input.md | `## Textbox:带背景与标题的说明框` 中 `TextboxStore.get('task-box')` | 知道组件内部为每个文本框建了 `TextboxStore`,可按 id 取回控制器并 `setText` | 不知道在哪里给 `Textbox` 设置这个 id;示例里的 `Textbox` 没有 `id`、`name` 或类似属性 | 照抄 `TextboxStore.get('task-box')` 会拿不到东西,因为我不知道该把 `'task-box'` 写在哪 | +| docs/advanced/ii/ui/builtin-text-and-input.md | `## Input:在画布上输入` 的“点击位置创建真实的输入框并对齐到画布,失焦后收起” | 知道 `Input` 用 `v-model:value`,有 `multiline`、`placeholder`、`border` 等属性 | 不知道“收起”后画布上还显示什么;值还在不在;如果一个表单有五个字段,点第二个时第一个会不会消失 | 以为 `Input` 是常驻输入框,实际点别处就看不到,可能做出“字段消失”的界面而不知道为什么 | +| docs/advanced/ii/ui/builtin-text-and-input.md | `## 特殊组件 InputBox:单次输入` 与 `## 边界与注意` | 知道 `getInput` 返回 `Promise`,`getInputNumber` 返回 `Promise`,确认后 `await` 拿结果;边界说面板提前关掉要自己处理“没有结果” | 不知道取消或关闭弹窗时 Promise 是 resolve 空串、resolve undefined,还是 reject;也不知道 `getInputNumber` 解析失败时返回什么 | 写 `const name = await getInput(...)` 后无法区分“用户没输入”和“用户输了个空串”,`try/catch` 也不知道该不该写 | +| docs/advanced/ii/ui/builtin-list-and-containers.md | `## List:可选中的列表` 的“初始选中项以列表第一项为准” | 知道 `list` 是 `[id, 文本]`,`v-model:selected` 绑定选中 id;点击行会切换;初始以第一项为准,挂载后改绑定不会重选 | 不知道示例里 `ref('weapon')` 到底有没有作用;如果我从存档恢复 `'armor'`,该走什么“列表自己的交互”;父组件怎么知道实际选中了第一项 | 设 `selected.value = 'armor'` 后界面仍选第一项,父组件拿到的是 `'armor'` 还是 `'weapon'` 无法确定 | +| docs/advanced/ii/ui/builtin-list-and-containers.md | `## ListPage:左列表、右详情` 的 `close`、`closeLoc` | 知道 `close` 显示关闭按钮,`closeLoc` 调整按钮位置,`right` 把列表放右边,`basis` 是左侧比例 | 不知道 `closeLoc` 的取值格式和坐标系:是相对 `ListPage` 的四元组,还是绝对画布坐标;也没有示例 | 想移动关闭按钮时不知道写什么,只能不动或反复试 | +| docs/advanced/ii/ui/builtin-list-and-containers.md | `## Page:分页` 的默认 slot 写法 | 知道页码从 0 开始,`pages` 是总页数,默认 slot 收到页码索引;14 篇学过默认 slot 内容写在标签之间、具名 slot 用对象 | 不知道这里为什么把函数直接当 children(`{(index) => ...}`),而 `ListPage` 用 `{{ default: fn }}`;两种写法分别什么时候用 | 照 `Page` 写函数、照 `ListPage` 写对象,混用时可能什么都不显示,也不知道该改哪边 | +| docs/advanced/ii/ui/builtin-list-and-containers.md | `## Scroll:只对直接子元素做虚拟滚动` 的“只渲染视口附近的直接子元素” | 知道子元素要平铺,不能用一个容器包住全部;每个子元素有自己的 `loc`;暴露 `scrollTo` 与 `getScrollLength` | 不知道 `Scroll` 怎么得到总高度和行高:是靠子元素 `loc` 推出来,还是要额外给高度;变高行怎么办;`scrollTo(y)` 的 y 是内容像素还是行号 | 平铺 30 行能滚,但想“跳到第 20 行”时不知道 y 该算成 `20 * 28` 还是别的;滚动条长度也无法预期 | +| docs/advanced/ii/ui/builtin-list-and-containers.md | `## 特殊组件 ConfirmBox 与 Choices` | 知道 `getConfirm` 返回 `Promise`,`getChoice` 返回选中 key;`maxHeight` 超了会分页;`selected` 是默认索引 | 不知道用户直接关掉弹窗时返回什么;`getChoice` 取消时是 undefined 还是 reject;`getConfirm` 的完整参数顺序也没有单独列出来 | `if (yes)` 可能永远等不到结果,或 `choice` 类型对不上;不敢把一次性弹窗接到关键流程里 | +| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 打开与关闭` 与 `## 背景` 的 `showBack` / `showingBack()` / `showBackground` / `hideBackground` | 知道 `active` 和 `showBack` 是引用值,TSX 里读 `.value`;`showingBack()` 返回背景最终是否显示;`hideBackground` / `showBackground` 是用户设置 | 不知道 `showBack.value` 和 `showingBack()` 什么时候会不同;想显示“背景现在可见吗”到底读哪个;四个名字太像,分不清谁改用户设置、谁读系统状态 | 在文字里写 `props.controller.showBack.value`,可能读到的是用户开关而不是最终结果,背景明明没显示却显示“已显示” | +| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 显示策略` 的 `showCustom(new MyStrategy())` | 知道默认 `lastOnly`,`showAll` 全部显示,`showCustom` 接收自定义策略;关闭时是否连带关闭由策略决定 | 不知道 `MyStrategy` 要实现什么接口、有哪些方法、返回什么;文档没有给最小自定义策略示例 | 需要“只叠两层、第三层替换第二层”这类特殊叠放时无法下手,只能退回 `lastOnly` 或 `showAll` | +| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 基础 props 注入` 的 `setPropsBaseCreator` | 知道控制器通过它给每个实例注入基础参数;示例返回 `{ instance, controller }`;UI 的 props 数组必须有 `controller`、`instance`、`state` | 不知道 `state` 是系统另外注入,还是也要 creator 返回;自定义 creator 会不会把 `state` 弄丢;`state` 到底从哪来 | 照示例写 creator 后,所有 `props.state.sceneController.open(...)` 都可能变成 undefined,但文档没有提示这一点 | +| docs/advanced/ii/ui/ui-controller-and-stack.md | `## 当前没有全局注册 / 覆盖入口` 与第 1 篇的 `new GameUI('my-panel', ...)` | 知道 `GameUI` 把名字和组件绑在一起;打开时靠传进去的对象;当前构造 `GameUI` 不会自动登记,所以不能按名字取回内置 UI | 不知道名字现在还有什么用;重名会不会冲突;是否必须唯一;调试时能不能靠名字找到实例 | 以为名字可以用来按名打开或覆盖,结果发现只能持有对象;如果两个 UI 同名,我不知道会不会出问题 | +| docs/advanced/ii/ui/ui-controller-and-stack.md | `## keep:切换时不闪背景` | 知道 `keep()` 在 close 与 open 的间隙保持背景,`safelyUnload()` 栈空才关,`unload()` 无条件关 | 不知道如果中间 `open` 抛错、提前 return 或用户取消,需不需要 `try/finally` 保证 unload;keep 对象能不能重复使用 | 切换流程一旦失败,背景可能一直留着;我不知道该怎么恢复,只能刷新整个界面 | +| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法一:在打开处替换` | 知道内置 UI 指 `src/client/ui` 的应用层界面,例如设置、存档、工具栏;替换就是找到 `open` 那一行,把 `SaveUI` 换成 `MySaveUI` | 不知道 `SaveUI` 从哪个模块 import、导出名是什么;文档只给名字,没有给路径;我也不能读源码 | 想替换存档界面,却找不到可以 import 的 `SaveUI`;只能猜路径,猜错就编译失败 | +| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法二:包装组件` 的 `defineComponent((props, { attrs, slots, emit }) => ...)` | 知道包装要转发 props、attrs、slots、emits,对外契约不变;`OriginalPanel` 是原组件 | 不知道包装组件没有 `props` 数组时,父组件传的值到底进 `props` 还是 `attrs`;`{...props}` 与 `{...attrs}` 会不会重复;没有声明 `emits` 能不能 `emit('change')` | 照抄后父组件的某些设置不生效,或 `change` 事件不触发;我不知道该补 `SetupComponentOptions` 还是该改展开顺序 | +| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法二` 的 `interface MyPanelProps extends OriginalPanelProps {}` | 知道要保留原契约,所以包装的 Props 继承原 Props | 不知道 `OriginalPanelProps` 从哪里来;如果原 UI 是用 `GameUI` 注册的,包装的是里面的组件还是 `GameUI` 本身;原组件的 props 类型有没有导出 | 写不出 `extends OriginalPanelProps`,也不知道该不该自己重写一份 Props;包装方案卡在第一步 | +| docs/advanced/ii/ui/replace-builtin-ui.md | `## 改法三:改显示策略或背景` | 知道 `showAll()` 让栈里 UI 同时显示,`setBackground` 换稳定背景;这些是控制器接口 | 不知道这些调用应该写在哪一层:主入口、场景 UI、还是某个面板里;如果我只想改内置设置面板的叠放,而不改它的组件,代码放哪里才会影响它 | 把 `showAll()` 写在自己面板里,可能只影响当前控制器;不确定是否影响内置 UI 所在的栈 | +| docs/advanced/ii/ui/replace-builtin-ui.md | `## 运行效果` | 知道示例并排对比 `lastOnly` 与 `showAll` 的叠放效果 | 示例没有演示“替换”本身:看不到 `MySaveUI` 替换 `SaveUI`,也看不到包装组件转发 props 的效果 | 看完仍无法确认自己的替换是否成功,只能等真正接到客户端里试 | +| docs/advanced/ii/ui/ui-performance.md | `## 症状与排查` 与 `## 边界与注意` 的“先测再改” | 知道卡顿先查大子树和缓存,切页闪烁查背景和 keep,频繁重建查 open/close,列表掉帧查是否平铺 | 不知道怎么测:没有 FPS、帧耗时、绘制次数、日志或性能面板的用法;也没有“改前/改后”怎么对比 | 只能凭感觉改,改完不知道是真的更快还是心理作用;症状表给了方向但没法验证 | +| docs/advanced/ii/ui/ui-performance.md | `## 缓存:cache 与 nocache` | 知道 `container`、`custom`、`container-custom` 默认缓存;`text`、`image`、`g-*` 默认不缓存;`nocache` 优先 | 不知道如果 `container` 里有每帧变化的 `text`,父容器的默认缓存会不会让整块不更新;要不要给父 `container` 加 `nocache`;脏标记会不会传到缓存的父级 | 做动画文字时可能文字不刷新;不知道该关父容器缓存还是把文字拆出去 | +| docs/advanced/ii/ui/ui-performance.md | `## 列表与分页` 的“规则见 `dev.md`” | 知道大量列表优先 `Scroll`、分页优先 `Page`;`key` 只在会重排、插入、删除且需要保留身份时加;11 篇也讲过类似规则 | 不知道 `dev.md` 是什么、在哪里;我手里只有这套 UI 文档;`Scroll` 示例又给每行加了 `key={index}` | 读到“见 dev.md”会停一下;不确定该按 11 篇的规则还是按 `Scroll` 示例写 `key` | +| docs/advanced/ii/ui/ui-performance.md | `## 基础 props` 的“自定义 `createPropsBase`” | 知道每个实例渲染都会走一次基础参数创建,creator 里不要做重活;读状态、算大数组、创建对象放到别处 | 不知道 `createPropsBase` 和 17 篇的 `setPropsBaseCreator` 是不是同一个东西;自定义时方法名到底写哪个;怎么把“现成的值”装进去也没有示例 | 按 19 篇的名字去找方法找不到,或写错名字不生效;也不知道该在哪里预先算好值 | +| docs/advanced/ii/ui/ui-performance.md | `## UI 栈` 的“`keep` 用完必须卸载” | 知道能 `hide`/`show` 就不重建;稳定背景用 `setBackground` 移出栈;`keep` 只在关一个开一个的间隙用,用完 `safelyUnload()` 或 `unload()` | 不知道异常路径怎么保证卸载;如果中间 `open` 失败,`keep` 是否还在;要不要 `try/finally` | 和 17 篇一样,切换失败后背景一直留着,不知道怎么恢复 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 先把文件拆好`(五个文件的表格 + “其余四个文件先留空或放占位组件”) | 最终拆成 5 个文件;`InventoryPanel` 是唯一被 `GameUI` 注册的组件,其余四个是普通子组件;本篇只写 `inventory-panel.tsx`。 | 这 5 个文件该放在项目的哪个目录、文件名和路径有什么约定、其它四个占位文件最小要写成什么样才能通过编译;全篇没有出现任何 `import` 路径或目录说明。 | 我会在自己项目里新建一个目录放这 5 个文件,但不知道构建会不会自动找到它们;四个空文件可能直接编译失败,连骨架都跑不起来。 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 骨架代码`(``) | `fill` / `stroke` / `strokeAndFill` 是模式开关,颜色由 `fillStyle` / `strokeStyle` 给;`g-rectr` 默认填充;圆角用 `circle`。 | 同时写 `fill` 和 `stroke`(而不是写 `strokeAndFill`)时,到底是“填充+描边”还是其中一个盖过另一个;文档分别讲过三种模式,却没讲两个开关同时出现。 | 我会照抄得到一块带蓝色描边的深色圆角面板;如果两个开关不能并存,我可能只得到填充或只得到描边,而且不会报错,很难判断哪里不对。 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 骨架代码`(根 ``)与 `## 运行效果` | `loc` 前两项是左上角、后两项是宽高;默认尺寸 200×200;live 按 720×480 展示。 | 720×480 是 UI 自己的逻辑尺寸,还是必须等于游戏画布尺寸;UI 比画布大或小时会不会被裁剪或缩放;我自己的魔塔画布不是 720×480 时该怎么定尺寸。 | 我会直接把根容器写成 720×480,但在自己游戏里可能只看到左上角一块,或者整块被拉伸;文档没有告诉我该按画布还是按面板设计尺寸。 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 打开它` | 场景 UI 用 `props.state.sceneController.open`;另一个 UI 内用 `props.controller.open`;主 UI 栈用 `props.state.mainUIController.open`;没有全局 `client`。 | 如果我不在 UI 组件里(比如游戏主入口、场景脚本),手上没有 `props`,该从哪里拿 `sceneController` / `mainUIController`;文档只说“在主入口你持有的客户端核心实例上调用”,没给主入口长什么样,也没说客户端核心实例怎么获得。 | 我写完骨架后不知道把打开代码贴到哪里;在 UI 组件外写 `props.state` 会直接报错,我只能回头猜或去翻别的章节。 | +| docs/advanced/ii/ui/inventory-example-1-skeleton.md | `## 先把文件拆好`(“留空或放占位组件”) | 四个子组件后续逐篇补全;`InventoryPanel` 负责组合它们。 | 占位组件最小要满足什么(要不要 `defineComponent`、要不要声明 `props`)才能被 `import` 又不报错;文档没有给占位写法。 | 我可能建四个空 `.tsx`,一 `import` 就编译失败;或者随便写个组件但 `props` 对不上,后面替换时还要回头改骨架。 | +| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemGrid:按行列排列`(外层 ``) | `container` 的 `loc` 是 x/y/w/h;不写尺寸默认 200×200;`container` 是布局单位与事件捕获单位;子元素坐标相对父容器。 | 宽高为 0 的容器会不会裁剪子元素、会不会让子元素无法命中;文档从没说过 `container` 是否裁剪溢出内容。 | 我照抄一个 0×0 容器包住网格;如果容器裁剪,我会看到一片空白,点击也没反应;如果它只是布局壳,则一切正常。我无法从文档判断是哪一种。 | +| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemGrid:按行列排列`(每个格子外包 ``,没给宽高) | 不写宽高默认 200×200;`container` 参与命中;`zIndex` 决定遮挡与命中先后。 | 这个 200×200 的外壳会不会盖住相邻格子、把点击算到错误的格子上;命中区域是按容器自身矩形,还是只按可见子元素。 | 我的格子间距只有 8,外壳 200×200 会互相重叠;点第二格可能被第一格的外壳接住,选中项乱跳。文档没有说明该不该给外壳补 `size`。 | +| docs/advanced/ii/ui/inventory-example-2-grid.md | `## 放回面板`(`items.find(...)`;对照下一篇的 `items.value.find(...)`) | 选中项用 `computed` 从 `items` 与 `selectedId` 派生;`find` 找不到返回 `undefined`。 | `items` 在最终代码里到底是普通数组还是 `ref`;本篇写 `items.find`,下一篇写 `items.value.find`,我不知道假数据该定义成哪一种、`computed` 里该不该写 `.value`。 | 我照本篇写可能得到“`items.find` 不是函数”或响应式不更新;照下一篇写又要改数据定义。我只能二选一赌一个。 | +| docs/advanced/ii/ui/inventory-example-2-grid.md | `## ItemCell:一个格子`(`const size = props.size ?? 66;`) | `props` 是响应式的、不能解构;随数据变化的派生值应放 `computed`;尺寸这类不变的基础值可以在 setup 读一次。 | `cellSize` 会不会在运行时变(`边界与注意` 提到“网格区域尺寸变化时重新算列数”,暗示会变);如果父组件改 `cellSize`,`ItemCell` 里只读一次的 `size` 会不会保持旧值。 | 我先照抄;窗口或区域变化后只有列数变了,格子尺寸不跟着变,出现重叠或留白。我不确定是否该主动改成 `computed`。 | +| docs/advanced/ii/ui/inventory-example-2-grid.md | `## 放回面板` + `## 边界与注意`(选中与未选中) | `selectedId` 初始为 `'potion-red'`;点击只会上报有效 id;详情篇要用 `undefined` 表示未选中。 | 在这个面板里怎样才会进入“没有选中”的状态;本篇没有任何清除选中的入口,文档也没说后面会加。 | 我会以为点空白处或再点一次可以取消,但代码里没有;到了详情篇看到“请选择道具”的提示,我不知道它何时会出现,也不知道要不要自己补一个取消按钮。 | +| docs/advanced/ii/ui/inventory-example-3-detail.md | `## 选中项由父组件派生`(`items.value.find`) | `selectedItem` 是 `computed`;`ItemDetail` 的 `item` 可选;`find` 返回 `undefined` 时显示提示。 | `items` 的数据形态。我在上一篇刚看到 `items.find`,这一篇变成 `items.value.find`;我不知道最终 `InventoryPanel` 里 `items` 是 `ref` 还是普通数组,也不知道假数据该放哪。 | 我按这一篇把 `items` 写成 `ref`,上一篇的 `items={items}` 就要改成 `items.value`;改动会牵连 grid 段代码,而文档没有给合并后的完整版本。 | +| docs/advanced/ii/ui/inventory-example-3-detail.md | `## ItemDetail:右侧面板`(两个没有 `loc` 的 `