docs(10-42): add VitePress render demo POC plan and summary

2026-10-30 04:40:18 +08:00 · 2026-10-29 20:27:23 +08:00 · 2026-10-29 20:27:23 +08:00 · 3fb1f171b6
commit 3fb1f171b6
parent fc353302c0
5 changed files with 533 additions and 6 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -589,6 +589,7 @@ Plans:
 - [x] 10-30-PLAN.md — 高级 I 导览 7 → 9 + 侧边栏注册 + 两篇互链收口 + 全量构建
 - [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 页）

 **说明：** 每篇中级教程遵循 `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 "..."` 执行。

@ -597,3 +598,5 @@ Plans:
 **高级 II 说明（已完成）：** 第三批（10-21..10-27）按 D-67 / D-53 定位为「深入定制」**难度层**（难度标签，非领域分类），只写**数据端**内容；已建 `docs/advanced/ii/` **10 篇**（导览 + 8 个主题 + 点事件与图块事件）。写作按 D-59 库文档风格、D-60 简洁、D-61 主干与边界分离、D-62/D-70 代码块完整、D-63 模板顺序、D-64 只在需实现接口时给模板、D-65 注释充足、D-66 并列功能分开示例、D-69 内部实现章节后置；读者水平按 D-68（已理解绝大多数常用语法，认真阅读后能读明白一部分简单与中等复杂度系统，不预设资深开发者）。侧边栏分组名「高级 II · 深入定制」。渲染端 / 编辑器 / 状态栏 / 怪物图鉴按 D-47 非断链占位；高级 III 只用代码 span 或 `TODO(advanced-III)` 注释。10-25 负责导览与站点注册，10-26 执行独立读者审阅，10-27 执行用户主导修订循环，**用户已明确确认**（D-46 第 2 阶段）并于 2026-10-23 收尾。构建命令同上。

 **高级 I 补写说明（第四批，待执行）：** 按 D-75 / D-71，为高级 I 补两篇数据端文档——`docs/advanced/mover.md`（移动 Mover）与 `docs/advanced/face-handler.md`（FaceHandler 系列）。写作按高级 I 读者水平（D-57：了解基本语法、代码能力一般、不熟悉引擎内部架构）与 D-59..D-74 库文档风格；渲染端 / 编辑器按 D-47 非断链占位。10-28 / 10-29 并行写两篇（互引先用代码 span），10-30 负责导览 7 → 9、侧边栏注册与互链收口，10-31 执行独立读者审阅（沿用 10-19 已确认的高级 I 人格），10-32 执行用户主导修订循环，**用户明确确认后方可收尾**。文件名、页面标题、侧边栏显示名与示例标识符名以各计划 Task 0 的用户确认为准（D-13）。D-75 写的 `IMoveController` 与源码 `IMoverController` 不一致，以源码为准。
+
+**10-42 增量说明：** `10-42-PLAN.md` 是 Phase 10 的独立增量（VitePress 内嵌自定义渲染器 demo 最小 POC），单独追加：Phase 10 的 `**Plans:**` 计数行与第 1..5 批描述不因本计划改动（计数收口仍归 `10-41`），`10-33`..`10-41` 的收口仍由 `10-41` 负责，`10-06` / `10-11` / `10-12` 仍未勾选。POC 页 `docs/poc/render-demo.md` 与现有命名暂时保留，后续正式渲染端文档批次再决定删除或迁移。
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@ -5,9 +5,9 @@ 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-24T00:00:00.000Z"
-last_activity: 2026-10-24
-last_activity_desc: 高级 I 补写（Mover + FaceHandler）完成并经用户确认收尾
+last_updated: "2026-10-29T00:00:00.000Z"
+last_activity: 2026-10-29
+last_activity_desc: 10-42 文档内嵌渲染 demo POC 完成并经用户人工验证
 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-06 / 10-11 / 10-12 待补
+Plan: 第一批（中级 24 篇）、第二批（高级 I 7 篇）、第三批（高级 II 10 篇）、第四批（高级 I 补写 Mover/FaceHandler 2 篇）已收尾；10-42 文档内嵌渲染 demo POC 已完成并经用户验证；10-06 / 10-11 / 10-12 待补
 Status: In Progress
-Last activity: 2026-10-24 — 高级 I 补写完成并经用户确认收尾
+Last activity: 2026-10-29 — 10-42 文档内嵌渲染 demo POC 完成并经用户确认（人工验证通过）

-Progress: Phase 10 · 29/32 plans（中级 + 高级 I 9 篇 + 高级 II 已收尾；总览 / 初级 / 高级 III / API / Agent 参考仍待推进）
+Progress: Phase 10 · 29/32 plans（中级 + 高级 I 9 篇 + 高级 II 已收尾；总览 / 初级 / 高级 III / API / Agent 参考仍待推进）（另：10-42 文档内嵌渲染 demo POC 已完成并经用户验证，Phase 10 的计数收口仍归 10-41）

 ## Performance Metrics

@ -267,6 +267,7 @@ Recent decisions affecting current work:
 - Phase 9 added (2026-10-08): 最小浏览器可运行版本（在已完成且 Node 可运行/回放验证的数据端之上完成渲染端框架，并验证可在浏览器上运行）；Depends on Phase 8
 - 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

 ### Pending Todos

--- a/.planning/phases/10-docs-restructure/10-42-PLAN.md
+++ b/.planning/phases/10-docs-restructure/10-42-PLAN.md
--- a/.planning/phases/10-docs-restructure/10-42-POC-NOTES.md
+++ b/.planning/phases/10-docs-restructure/10-42-POC-NOTES.md
@ -0,0 +1,84 @@
+# 10-42 POC 记录：VitePress 内嵌自定义渲染器
+
+记录日期：2026-10-29
+
+## 命名清单（用户已确认）
+
+方案 A，逐项最终值如下（包装组件文件名、组件名、props、内部类型、demo 目录、两个 demo 文件名与组件名、POC 页面路径、config 新增键均已确认）：
+
+| 项 | 最终值 | 类型 / 默认值 |
+| --- | --- | --- |
+| 包装组件文件 | `docs/.vitepress/components/renderDemo.vue` | — |
+| 包装组件名 | `RenderDemo` | — |
+| 包装组件 props | `loader` / `width` / `height` / `scale` / `background` | `DemoLoader`（必填）/ `number`（480）/ `number`（320）/ `number`（1）/ `string`（`'#101418'`） |
+| 包装组件内部类型 | `RenderDemoProps` / `DemoLoader` / `DemoModule` | `interface` / `type` / `interface` |
+| demo 目录 | `docs/.vitepress/components/demos/` | — |
+| 渲染基础 demo | `basicRender.vue` | 组件名 `BasicRenderDemo` |
+| UISystem demo | `uiSystem.vue` | 组件名 `UISystemDemo` |
+| POC 页面 | `docs/poc/render-demo.md` | 不进 nav / sidebar |
+| 命名确认记录 | `.planning/phases/10-docs-restructure/10-42-POC-NOTES.md` | 本文件 |
+| config 新增键 | `vite.resolve.alias` / `vite.resolve.dedupe` / `vue.template.compilerOptions.isCustomElement` / `vite.plugins`（追加 `vuejsx`） | — |
+
+用户确认：可以执行
+用户原文：可以执行
+
+## 基线
+
+基线 HEAD：db726ff58d2fe4311704d375cd34a4b7e755eba3
+ROADMAP 基线 Plans 行：**Plans:** 29/32 completed（第一批：中级教程 24 篇 + 站点注册 + D-09 复审修订；第二批：高级 I 7 篇 + 注册 + 读者审阅 + 用户修订循环；第三批：高级 II 10 篇 + 注册 + 读者审阅 + 用户修订循环；第四批：高级 I 补写 Mover + FaceHandler 2 篇 + 注册 + 读者/用户修订，已完成）。**未完成 3 个**（第一批遗留）：`10-06`（中级全批验收）、`10-11`（中级读者审阅）、`10-12`（中级最终验收）——其范围已被后续 D-09 修订与高级 I/II 期间的最终状态覆盖，缺独立 SUMMARY，待补跑或并入后续验收。
+STATE 基线 total_plans： 134
+STATE 基线 completed_plans： 126
+
+以上基线项（ROADMAP 计数行原文 + STATE 两个计数原值 + HEAD）是「本次修改不得改动」的比对基准，不写死任何期望数字（10-41 可能已把 Phase 10 的计数改成 38/41，本计划只保证自己不改它）。
+
+## 门禁
+
+首次构建：green
+
+- 命令：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"`
+- 关键输出：`build complete in 19.38s.`；无 dead link 报告；仅有既有的 chunk 体积警告
+
+### Task 5 门禁结论
+
+| 门禁 | 命令 | 结论 |
+| --- | --- | --- |
+| prettier `--write` | `cmd /c "pnpm exec prettier --write docs/.vitepress/config.ts docs/.vitepress/components docs/poc/render-demo.md"` | 通过（exit 0） |
+| prettier `--check` | `cmd /c "pnpm exec prettier --check docs/.vitepress/config.ts docs/.vitepress/components docs/poc/render-demo.md"` | 通过（`All matched files use Prettier code style!`） |
+| ESLint | `cmd /c "pnpm exec eslint docs/.vitepress/components docs/.vitepress/config.ts"` | 0 error / 0 warning（exit 0，无规则命中） |
+| docs 类型检查 | `cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` | `docs/` 路径 0 报错；仅 `packages/` 既有报错 |
+| 静态断言 | 计划 Task 5 的 Node 断言组合（config / 包装组件 / 两个 demo / 页面 / `eslint.config.js` / 四个文件 CRLF） | `GATE-OK` |
+| 全量构建 | `cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` | green：`build complete`，无 dead link |
+| 产物 | `public/_docs/poc/render-demo.html` | 已生成（`Test-Path` = True） |
+
+注：首次 Task 5 构建曾因既有 `packages/system/src/hotkey/index.ts` 的失效 `export * from './hotkey'` 而 red；该文件已由用户自行修复，本次重跑构建 green。本计划未修改该文件。
+
+## 组件类型与 ESLint
+
+属性名保持 camelCase：docs demo 的 `g-*` / `container` / `text` 是 `isCustomElement` 的元素 vnode，`@vue/compiler-dom` 的 `v-bind` 不会对元素做 camelize——把 `fillStyle` / `strokeStyle` / `lineWidth` 改写成连字符会被原样编译成 `fill-style` 键；而 `packages/render/src/core/graphics.ts:255-263` 与 `packages/render/src/core/misc.ts:127-137` 的 `handleProps` 只匹配 camelCase 字面量，改名即失配、demo 不渲染，因此属性名一律保持 camelCase，连字符告警只能靠 ESLint 局部 override 放宽。
+eslint 覆盖范围：`eslint.config.js` 仅新增一个 `files: ['docs/.vitepress/components/**/*.vue']` 的 override（`vue/attribute-hyphenation: ['warn', 'never']`、`vue/one-component-per-file: 'off'`）；既有 `ignores` 与其它规则、`packages/` / `packages-user/` / `src/` 的 lint 范围均未改动。
+docs 类型检查：`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` 通过，`docs/` 路径 0 报错；`docs/tsconfig.json` 只服务 docs，不并入 `pnpm check:type`，根 `tsconfig.json` / `tsconfig.node.json` 未改。
+引擎既有类型错误：11 条（`packages/common/src/logger.ts` 缺 `main` 全局 3 条；`packages/render/src/core/types.ts` 缺 `CanvasStyle` 导入 8 条）；既有、非本轮引入、不得修，只记录不修复。
+
+## 待人工验证项
+
+1. 渲染基础 demo 出现 container 背景、矩形、圆与文字。
+2. 点击矩形 / 圆后计数与颜色可见变化（若点击无反应，先查根锚点是否被改动、canvas 是否被写内联宽高）。
+3. UISystem demo「打开 UI」能看到最小 UI，「关闭 UI」后栈长度归零、打开状态变为未打开。
+4. 站点内来回切换路由或反复进出该页后，两个 demo 仍能正常显示与交互，画面不叠加、控制台无 RAF / 事件相关报错。
+5. 控制台无 `logger` 错误（特别是 74 / 21 / 19）。
+6. 明确答复「POC 结束后该页 / 命名 / 落点是否保留」。
+
+## 待议项
+
+POC 结束后该页 / 命名 / 落点是否保留，由用户在 Task 6 决定；本记录不做决定。
+
+## 人工验证与提交状态
+
+用户人工验证：通过
+用户原文：pass
+
+页面 / 命名 / 落点决定：**暂时保留** `docs/poc/render-demo.md` 与现有命名、落点；后续正式渲染端文档批次再决定删除或迁移。
+
+当前 HEAD：e05cc55b957104e730421e3996adb5912143a253
+
+提交状态：本计划文件未被任何 commit 带入，且仍未提交——`git log <基线 HEAD>..HEAD -- <本计划文件>` 输出为空，`git status --porcelain` 对本计划六个关键路径仍有未提交输出。Task 1 的 `基线 HEAD：` 行保持 `db726ff58d2fe4311704d375cd34a4b7e755eba3` 不变；HEAD 前移来自用户并发提交。
--- a/.planning/phases/10-docs-restructure/10-42-SUMMARY.md
+++ b/.planning/phases/10-docs-restructure/10-42-SUMMARY.md
@ -0,0 +1,61 @@
+# Phase 10 Plan 42: VitePress 内嵌自定义渲染器 demo 最小 POC Summary
+
+## 一句话
+
+在保留 VitePress SSR 预渲染的前提下，用 DOM 包装组件 + `onMounted` 动态 import，把 `@motajs/render` / `@motajs/render-vue` 的自定义渲染器嵌进文档站；「渲染基础」与「UISystem」两个 demo 真实绘制、可交互、可安全卸载。
+
+## 解决的问题
+
+验证「文档内嵌可运行示例」在 `vitepress build docs` 的预渲染阶段是否可行：引擎模块顶层会碰 `document`（`core/utils.ts`、`core/graphics.ts`、`core/misc.ts`、`render-vue/src/tag.ts`），因此包装组件与页面顶层只能对引擎包动态 import，页面用 `<ClientOnly>` 跳过预渲染。POC 通过后，才值得评估 fence 插件与正式渲染端文档批次。
+
+## 最终落点与命名
+
+- 包装组件：`docs/.vitepress/components/renderDemo.vue`（组件名 `RenderDemo`；props `loader` / `width` / `height` / `scale` / `background`；内部类型 `RenderDemoProps` / `DemoLoader` / `DemoModule` / `AppHandle`）
+- 渲染基础 demo：`docs/.vitepress/components/demos/basicRender.vue`（`BasicRenderDemo`）
+- UISystem demo：`docs/.vitepress/components/demos/uiSystem.vue`（`UISystemDemo`）
+- POC 页面：`docs/poc/render-demo.md`（不进 nav / sidebar）
+- 配置：`docs/.vitepress/config.ts` 的 `vite.resolve.alias` / `dedupe` / `isCustomElement` / `vuejsx`
+- docs 局部 TS 项目：`docs/tsconfig.json`（不并入 `pnpm check:type`，根 `tsconfig.json` / `tsconfig.node.json` 未改）
+- ESLint docs override：`eslint.config.js`（只匹配 `docs/.vitepress/components/**/*.vue`）
+
+## 六类门禁
+
+- prettier：`--write` → `--check` 均通过（`All matched files use Prettier code style!`）。
+- ESLint：`cmd /c "pnpm exec eslint docs/.vitepress/components docs/.vitepress/config.ts"` 为 0 error / 0 warning，无 `vue/attribute-hyphenation` / `vue/one-component-per-file`；渲染属性保持 camelCase（`fillStyle` / `strokeStyle` / `lineWidth`），未为了 lint 改属性名。
+- docs 类型检查：`cmd /c "pnpm exec vue-tsc --noEmit -p docs/tsconfig.json"` 中 `docs/` 路径 0 报错；仅 11 条 `packages/` 既有报错（`packages/common/src/logger.ts` 缺 `main` 3 条、`packages/render/src/core/types.ts` 缺 `CanvasStyle` 8 条），既有、非本轮引入、不得修，只记录。
+- 构建：`cmd /c "pnpm exec tsx docs/.vitepress/init.ts && pnpm docs:build"` green，输出含 `build complete`，无 dead link。
+- 静态断言：计划 Task 5 的 Node 组合（config / 包装组件 SSR 边界 / 两个 demo / 页面 ClientOnly 与两个动态 loader / `eslint.config.js` override / 四文件 CRLF）为 `GATE-OK`。
+- 产物：`public/_docs/poc/render-demo.html` 已生成，且 POC 页不在 nav / sidebar。
+
+## 人工验证
+
+用户人工验证：通过
+用户原文：pass
+
+浏览器中确认：两个 demo 真实绘制、点击交互生效、UI 打开 / 关闭后栈长度归零、反复进出页面无残留、控制台无 `logger` 74 / 21 / 19。
+
+## 页面保留决定
+
+**暂时保留** `docs/poc/render-demo.md` 与现有命名、落点；后续正式渲染端文档批次再决定删除或迁移。
+
+## 未做事项
+
+- 不做 markdown fence 插件（POC 通过后再评估）。
+- 不写正式渲染端文档批次。
+- 不使用 `client-base` 的真实素材 / 组件。
+- 不把 POC 页加入 nav / sidebar。
+- 不改任何引擎源码（`packages/` / `packages-user/` / `src/` 均未改）；引擎既有类型错误只记录。
+- 本计划未产生任何 git commit / push。
+
+## HEAD 与提交状态
+
+BASE-HEAD: db726ff58d2fe4311704d375cd34a4b7e755eba3
+CURRENT-HEAD: e05cc55b957104e730421e3996adb5912143a253
+PLAN-FILES-COMMITTED: none
+
+判定口径：允许 HEAD 与基线不同——POC 期间用户有并发提交（例如 `refactor: 删除 legacy-ui 包`、`feat: 设置系统类型声明`）。本计划未产生 commit 的证明是：① `git log --oneline <基线 HEAD>..HEAD -- <本计划六个关键路径>` 输出为空（本计划文件没有被任何新 commit 带入）；② `git status --porcelain -- <同一组路径>` 仍有未提交输出（`docs/poc/render-demo.md`、`docs/tsconfig.json`、`docs/.vitepress/components`、`docs/.vitepress/config.ts`、`eslint.config.js`、`.planning/phases/10-docs-restructure/10-42-POC-NOTES.md`）。
+
+## Self-Check: PASSED
+
+- 产物与记录文件均存在：`docs/.vitepress/config.ts`、`docs/tsconfig.json`、`eslint.config.js`、三个组件、`docs/poc/render-demo.md`、本 SUMMARY、POC-NOTES、`ROADMAP.md`、`STATE.md`、`public/_docs/poc/render-demo.html`。
+- 本计划未产生 commit：`git log db726ff58d2fe4311704d375cd34a4b7e755eba3..HEAD -- <本计划六个关键路径>` 输出为空，`git status --porcelain` 对这些路径仍有输出。