Plate 的 Slate v2 装饰路线图 Wave 9编辑器快照变更元数据SnapshotChange与 touched runtime id 发布机制【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文基于 Plate 仓库中的执行计划 2026-04-15-slate-v2-decoration-wave-9-execution.md深入拆解 Slate v2 装饰decoration路线图 Wave 9 的目标与落地细节为核心监听器引入附加式的变更元数据记录SnapshotChange统一“快速文本路径”与“事务发布路径”的发布点并以 clone freeze 策略修复了不可变快照契约中的选择区selection可变性漏洞。读完本文你可以理解富文本编辑器在“快照订阅 差异化变更元数据”这一架构决策背后的设计权衡、字段级契约语义以及配套的验证与验收流程。1. 问题背景监听器只发“快照”消费者只能“全面重算”Wave 9 是装饰路线图中的第 9 波核心目标是执行两项工作引自计划文档 Goal 一节Execute Wave 9 from the decoration roadmap: core change metadata and touched runtime-id publication.即为 core 增加变更元数据change metadata并发布被触及的运行时 idtouched runtime ids。为什么需要这一步计划文档的 Findings 一节给出了当时的现状诊断当时的 core 向监听器只发布snapshot完整编辑器状态快照不携带任何“这次到底改了什么”的信息slate-react侧现存的监听器消费者大多忽略 payload直接做宽范围重算mostly ignore payloads and just recompute broadlyslate-history历史/撤销重做插件是风险最高的存量消费者因为它需要对选择区/内容差异selection/content deltas作出反应。这个诊断在当前仓库结构中仍能找到对应物packages/slate包内部已按interfaces/、internal/、slate-history/等子目录组织其中 with-history.ts 所在的历史模块正是文档点名的最高风险消费者当前公开的 EditorApi 类型定义 editor-api.ts 中getDirtyPaths第 88 行用于“根据一次操作推导脏路径”shouldNormalize第 120 行接收dirtyPaths选项onChange第 131 行在编辑器变化时被调用——“脏路径 变更回调”正是 Wave 9 变更元数据在归一化与订阅两侧的基础设施官方 API 文档 editor-api.mdx 中同样收录了dirtyPaths相关说明在 React 侧useElementSelector.ts 中存在对编辑器快照的订阅逻辑印证了“selector/selector-store 类消费者依赖订阅事件”的现状。2. 范围、约束与执行阶段计划文档明确划定了本次执行的边界值得作为一次小型内核改造的范围模板来参考Scope范围packages/slatecore 的 listener / change 发布逻辑对现有Editor.subscribe(...)消费者的兼容性影响仅在实现倒逼时才补充定向测试与后续文档。Constraints约束no scope reduction不允许缩水范围old listener usage must keep working旧版监听器用法必须继续可用这是整个契约设计“附加式”的由来;no fake “post-RC” dodge不允许以“放到 RC 之后再说”为借口拖延——这是当前活跃的下一次装饰波次必须以新一轮验证、架构师评审architect review、deslop死代码/无效抽象审计以及 deslop 后复验收尾。Phases阶段全部完成阶段状态Ground context and wave scope摸清上下文与波次范围[x]Audit listener consumers and choose the change-record shape审计监听器消费者并选定变更记录形态[x]Implement Wave 9 core publication实现 Wave 9 核心发布[x]Verify with targeted and package-level evidence定向 包级证据验证[x]Architect review架构师评审[x]Deslop post-deslop re-verification审计并复验[x]注意文档 front matter 中status字段仍为in_progress但六个阶段复选框均已勾选且架构评审结论为APPROVED可以推断该波次实际已完成、状态字段未同步更新。3. 契约设计最小可辩护的附加式监听器签名对Editor.subscribe(...)消费方的审计覆盖了slate-history、Slate组件、useSlateSelector、projection / annotation / widget 各 store以及既有的 snapshot 与 transaction 测试。基于这份审计文档给出结论最小可辩护smallest defensible的监听器契约保持附加式SnapshotListener(snapshot, change?)第一个参数仍是编辑器状态快照保证旧消费者只关心 snapshot零改动继续工作第二个参数change?是可选的新增变更元数据新消费者可以按需消费旧消费者直接忽略。这一“向后兼容 增量信息”的签名设计是内核级 API 演进中典型的加法策略不破坏既有调用面同时为装饰层decoration layer后续波次提供了消费差异信息的入口。4. SnapshotChange 记录九个字段及其语义Wave 9 落地的是一份保守的SnapshotChange记录包含以下字段完整继承自计划文档 Findings 一节字段语义classes本次变更的操作类别dirtyPaths受影响的节点路径集合dirtyScope脏路径覆盖的范围作用域touchedRuntimeIds被触及的运行时 id见下节专门解释childrenChanged是否有子节点结构变化selectionChanged选择区是否变化marksChanged文本 mark 是否变化operations本批次应用的操作列表replaceEpoch替换纪元用于识别整段替换级别的大变更这些字段与内核现有能力形成呼应dirtyPaths对应EditorApi.getDirtyPaths(operation)editor-api.ts按操作推导脏路径的既有实现selectionChanged/marksChanged两个布尔位正好覆盖文档指出的slate-history最需要感知的两类差异。将operations与布尔位、路径集合并列放置让上层消费者可以在“只看布尔位快速剪枝”与“精读操作列表”之间自选粒度。5. touched runtime ids 的“刻意收窄”语义touchedRuntimeIds是 Wave 9 最具设计争议性的字段文档明确它在本波次被刻意保持窄语义共三种取值形态变更形态touchedRuntimeIds取值insert_text/remove_text精确的文本运行时 id被插入/删除文本所在 text 节点的运行时 id仅选择区变化、或仅 mark 变化[]空数组replace 及大范围结构性失效null这里用[]与null的区分承载了“无内容级触碰”和“无法精确描述触碰范围”两种不同语义空数组表示可以放心地认为没有任何文本运行时节点被触及null则表示发生了替换或大范围结构失效消费者应回退到宽范围处理策略。这种保守收窄避免了在不精确时给出误导性 id也为后续装饰波次如按 runtime id 做细粒度装饰失效判断留出了精确语义基础。同系列的 Wave 10 与 Wave 11 执行文档延续了这条装饰路线图。6. 统一发布点buildSnapshotChange 的“单点发布”文档记录了关键的实现决策buildSnapshotChange(...)now publishes once from both the fast text path and the transaction publish path.即buildSnapshotChange(...)成为唯一的变更元数据构造/发布入口同时服务两条路径快速文本路径fast text path纯文本插入/删除这类高频、轻量操作走的路径事务发布路径transaction publish path常规操作批次提交后的发布路径。两条路径共用一个构造器保证了元数据的计算规则尤其是touchedRuntimeIds的三态语义在高频路径与事务路径上一致不会出现“打字时和粘贴时元数据口径不同”的隐蔽 bug。从源码结构看当前 packages/slate/src 已将实现拆分为interfaces/、internal/editor/、internal/transforms/、slate-history/等子目录计划文档中记录的实现落点如packages/slate/src/core/apply.ts、packages/slate/src/core/transaction-helpers.ts对应逻辑已在后续重构中迁移至新的目录组织下。7. 不可变快照契约修复从可变 selection 到深度冻结Wave 9 过程中架构师评审抓出了一个遗留的契约漏洞这条排查路径对任何实现“不可变快照”的编辑器内核都有参考价值漏洞快速文本路径direct text fast path把可变的重算后 selection直接存进了已提交的快照里破坏了“快照不可变”承诺——事务物化路径transaction materialization path做了正确的深拷贝快速路径却没有对齐第一轮修复在发布快照前对快速路径的 selection 做clone freeze使其与事务物化路径行为一致根因级修复引入frozen point/range 辅助函数并把两个快照发布点都切换到这些辅助函数最终提交快照中的 selection 连point 的 path 都会被深度冻结deep-freeze point paths too。从“补一个 clone”走到“统一使用冻结辅助函数”的演进说明了内核 API 修复中根因修复优于补丁式修复只 clone selection 顶层对象而漏掉其内部 point 的 path 数组冻结契约仍是破的。8. 同批修复markdown-preview 退格回归变更元数据改造触碰到了 selection/Editable 包表面同批次顺带修复了一个 markdown-preview 场景下的回归现象markdown-preview 示例中 projected-bold 文本上按退格键backspace行为异常落点editable.tsxslate-react 侧的可编辑组件验证在 markdown-preview.test.ts 中新增了一条浏览器验证用例browser proof row。这说明内核订阅契约变更的影响面会沿slate-react组件表面外溢必须用端到端浏览器测试而非仅单元契约测试来收口。9. 验证与验收计划文档记录的证据链计划文档 Progress 一节完整记录了本次执行的新鲜证据fresh evidence可作为一次内核波次的验收清单参考验证项命令 / 手段结果快照契约测试pnpm exec mocha --require ./config/babel/register.cjs ./packages/slate/test/snapshot-contract.ts188 passing历史包契约测试pnpm exec mocha --require ./config/babel/register.cjs ./packages/slate-history/test/history-contract.ts35 passing依赖与构建pnpm install、pnpm turbo build --filter./packages/slate通过类型检查pnpm turbo typecheck --filter./packages/slate通过代码风格pnpm lint:fix通过浏览器集成测试bash ./scripts/run-slate-browser-local.sh 3100 /examples/markdown-preview pnpm exec playwright test playwright/integration/examples/markdown-preview.test.ts --projectchromium --workers13 passedIDE 诊断对受影响 Slate 文件执行 lsp diagnostics0 errors其中历史包的 35 条契约测试直接对应“slate-history是最高风险消费者”的判断——旧消费者兼容性不是靠口头承诺而是靠该包的契约测试保证。收尾阶段还包含deslop 复审结论是修复不可变 selection 之后没有再发现值得改动的死代码、重复逻辑或无意义抽象架构评审最终结论APPROVED。10. 小结与延伸Wave 9 的核心贡献可以概括为三点契约加法以SnapshotListener(snapshot, change?)的最小附加式签名让“只发快照”的旧世界平滑过渡到“快照 变更元数据”的新世界窄语义精确性SnapshotChange九字段记录中touchedRuntimeIds用精确 id / [] / null三态刻意表达精确度边界宁可保守也不误报契约完整性的根因修复快速文本路径与事务路径统一经buildSnapshotChange发布并通过 frozen point/range 辅助函数让提交快照的选择区深度冻结。对希望继续深入当前仓库的读者可以从以下路径继续装饰路线图的相邻波次Wave 10 执行计划、Wave 11 执行计划Slate v2 内核源码packages/slate/srcinterfaces/editor/editor-api.ts的getDirtyPaths/shouldNormalize/onChange为脏路径与变更回调的类型定义历史消费者实现with-history.ts编辑器 API 文档editor-api.mdx。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plate 的 Slate v2 装饰路线图 Wave 9：编辑器快照变更元数据（SnapshotChange）与 touched runtime id 发布机制
Plate 的 Slate v2 装饰路线图 Wave 9编辑器快照变更元数据SnapshotChange与 touched runtime id 发布机制【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本文基于 Plate 仓库中的执行计划 2026-04-15-slate-v2-decoration-wave-9-execution.md深入拆解 Slate v2 装饰decoration路线图 Wave 9 的目标与落地细节为核心监听器引入附加式的变更元数据记录SnapshotChange统一“快速文本路径”与“事务发布路径”的发布点并以 clone freeze 策略修复了不可变快照契约中的选择区selection可变性漏洞。读完本文你可以理解富文本编辑器在“快照订阅 差异化变更元数据”这一架构决策背后的设计权衡、字段级契约语义以及配套的验证与验收流程。1. 问题背景监听器只发“快照”消费者只能“全面重算”Wave 9 是装饰路线图中的第 9 波核心目标是执行两项工作引自计划文档 Goal 一节Execute Wave 9 from the decoration roadmap: core change metadata and touched runtime-id publication.即为 core 增加变更元数据change metadata并发布被触及的运行时 idtouched runtime ids。为什么需要这一步计划文档的 Findings 一节给出了当时的现状诊断当时的 core 向监听器只发布snapshot完整编辑器状态快照不携带任何“这次到底改了什么”的信息slate-react侧现存的监听器消费者大多忽略 payload直接做宽范围重算mostly ignore payloads and just recompute broadlyslate-history历史/撤销重做插件是风险最高的存量消费者因为它需要对选择区/内容差异selection/content deltas作出反应。这个诊断在当前仓库结构中仍能找到对应物packages/slate包内部已按interfaces/、internal/、slate-history/等子目录组织其中 with-history.ts 所在的历史模块正是文档点名的最高风险消费者当前公开的 EditorApi 类型定义 editor-api.ts 中getDirtyPaths第 88 行用于“根据一次操作推导脏路径”shouldNormalize第 120 行接收dirtyPaths选项onChange第 131 行在编辑器变化时被调用——“脏路径 变更回调”正是 Wave 9 变更元数据在归一化与订阅两侧的基础设施官方 API 文档 editor-api.mdx 中同样收录了dirtyPaths相关说明在 React 侧useElementSelector.ts 中存在对编辑器快照的订阅逻辑印证了“selector/selector-store 类消费者依赖订阅事件”的现状。2. 范围、约束与执行阶段计划文档明确划定了本次执行的边界值得作为一次小型内核改造的范围模板来参考Scope范围packages/slatecore 的 listener / change 发布逻辑对现有Editor.subscribe(...)消费者的兼容性影响仅在实现倒逼时才补充定向测试与后续文档。Constraints约束no scope reduction不允许缩水范围old listener usage must keep working旧版监听器用法必须继续可用这是整个契约设计“附加式”的由来;no fake “post-RC” dodge不允许以“放到 RC 之后再说”为借口拖延——这是当前活跃的下一次装饰波次必须以新一轮验证、架构师评审architect review、deslop死代码/无效抽象审计以及 deslop 后复验收尾。Phases阶段全部完成阶段状态Ground context and wave scope摸清上下文与波次范围[x]Audit listener consumers and choose the change-record shape审计监听器消费者并选定变更记录形态[x]Implement Wave 9 core publication实现 Wave 9 核心发布[x]Verify with targeted and package-level evidence定向 包级证据验证[x]Architect review架构师评审[x]Deslop post-deslop re-verification审计并复验[x]注意文档 front matter 中status字段仍为in_progress但六个阶段复选框均已勾选且架构评审结论为APPROVED可以推断该波次实际已完成、状态字段未同步更新。3. 契约设计最小可辩护的附加式监听器签名对Editor.subscribe(...)消费方的审计覆盖了slate-history、Slate组件、useSlateSelector、projection / annotation / widget 各 store以及既有的 snapshot 与 transaction 测试。基于这份审计文档给出结论最小可辩护smallest defensible的监听器契约保持附加式SnapshotListener(snapshot, change?)第一个参数仍是编辑器状态快照保证旧消费者只关心 snapshot零改动继续工作第二个参数change?是可选的新增变更元数据新消费者可以按需消费旧消费者直接忽略。这一“向后兼容 增量信息”的签名设计是内核级 API 演进中典型的加法策略不破坏既有调用面同时为装饰层decoration layer后续波次提供了消费差异信息的入口。4. SnapshotChange 记录九个字段及其语义Wave 9 落地的是一份保守的SnapshotChange记录包含以下字段完整继承自计划文档 Findings 一节字段语义classes本次变更的操作类别dirtyPaths受影响的节点路径集合dirtyScope脏路径覆盖的范围作用域touchedRuntimeIds被触及的运行时 id见下节专门解释childrenChanged是否有子节点结构变化selectionChanged选择区是否变化marksChanged文本 mark 是否变化operations本批次应用的操作列表replaceEpoch替换纪元用于识别整段替换级别的大变更这些字段与内核现有能力形成呼应dirtyPaths对应EditorApi.getDirtyPaths(operation)editor-api.ts按操作推导脏路径的既有实现selectionChanged/marksChanged两个布尔位正好覆盖文档指出的slate-history最需要感知的两类差异。将operations与布尔位、路径集合并列放置让上层消费者可以在“只看布尔位快速剪枝”与“精读操作列表”之间自选粒度。5. touched runtime ids 的“刻意收窄”语义touchedRuntimeIds是 Wave 9 最具设计争议性的字段文档明确它在本波次被刻意保持窄语义共三种取值形态变更形态touchedRuntimeIds取值insert_text/remove_text精确的文本运行时 id被插入/删除文本所在 text 节点的运行时 id仅选择区变化、或仅 mark 变化[]空数组replace 及大范围结构性失效null这里用[]与null的区分承载了“无内容级触碰”和“无法精确描述触碰范围”两种不同语义空数组表示可以放心地认为没有任何文本运行时节点被触及null则表示发生了替换或大范围结构失效消费者应回退到宽范围处理策略。这种保守收窄避免了在不精确时给出误导性 id也为后续装饰波次如按 runtime id 做细粒度装饰失效判断留出了精确语义基础。同系列的 Wave 10 与 Wave 11 执行文档延续了这条装饰路线图。6. 统一发布点buildSnapshotChange 的“单点发布”文档记录了关键的实现决策buildSnapshotChange(...)now publishes once from both the fast text path and the transaction publish path.即buildSnapshotChange(...)成为唯一的变更元数据构造/发布入口同时服务两条路径快速文本路径fast text path纯文本插入/删除这类高频、轻量操作走的路径事务发布路径transaction publish path常规操作批次提交后的发布路径。两条路径共用一个构造器保证了元数据的计算规则尤其是touchedRuntimeIds的三态语义在高频路径与事务路径上一致不会出现“打字时和粘贴时元数据口径不同”的隐蔽 bug。从源码结构看当前 packages/slate/src 已将实现拆分为interfaces/、internal/editor/、internal/transforms/、slate-history/等子目录计划文档中记录的实现落点如packages/slate/src/core/apply.ts、packages/slate/src/core/transaction-helpers.ts对应逻辑已在后续重构中迁移至新的目录组织下。7. 不可变快照契约修复从可变 selection 到深度冻结Wave 9 过程中架构师评审抓出了一个遗留的契约漏洞这条排查路径对任何实现“不可变快照”的编辑器内核都有参考价值漏洞快速文本路径direct text fast path把可变的重算后 selection直接存进了已提交的快照里破坏了“快照不可变”承诺——事务物化路径transaction materialization path做了正确的深拷贝快速路径却没有对齐第一轮修复在发布快照前对快速路径的 selection 做clone freeze使其与事务物化路径行为一致根因级修复引入frozen point/range 辅助函数并把两个快照发布点都切换到这些辅助函数最终提交快照中的 selection 连point 的 path 都会被深度冻结deep-freeze point paths too。从“补一个 clone”走到“统一使用冻结辅助函数”的演进说明了内核 API 修复中根因修复优于补丁式修复只 clone selection 顶层对象而漏掉其内部 point 的 path 数组冻结契约仍是破的。8. 同批修复markdown-preview 退格回归变更元数据改造触碰到了 selection/Editable 包表面同批次顺带修复了一个 markdown-preview 场景下的回归现象markdown-preview 示例中 projected-bold 文本上按退格键backspace行为异常落点editable.tsxslate-react 侧的可编辑组件验证在 markdown-preview.test.ts 中新增了一条浏览器验证用例browser proof row。这说明内核订阅契约变更的影响面会沿slate-react组件表面外溢必须用端到端浏览器测试而非仅单元契约测试来收口。9. 验证与验收计划文档记录的证据链计划文档 Progress 一节完整记录了本次执行的新鲜证据fresh evidence可作为一次内核波次的验收清单参考验证项命令 / 手段结果快照契约测试pnpm exec mocha --require ./config/babel/register.cjs ./packages/slate/test/snapshot-contract.ts188 passing历史包契约测试pnpm exec mocha --require ./config/babel/register.cjs ./packages/slate-history/test/history-contract.ts35 passing依赖与构建pnpm install、pnpm turbo build --filter./packages/slate通过类型检查pnpm turbo typecheck --filter./packages/slate通过代码风格pnpm lint:fix通过浏览器集成测试bash ./scripts/run-slate-browser-local.sh 3100 /examples/markdown-preview pnpm exec playwright test playwright/integration/examples/markdown-preview.test.ts --projectchromium --workers13 passedIDE 诊断对受影响 Slate 文件执行 lsp diagnostics0 errors其中历史包的 35 条契约测试直接对应“slate-history是最高风险消费者”的判断——旧消费者兼容性不是靠口头承诺而是靠该包的契约测试保证。收尾阶段还包含deslop 复审结论是修复不可变 selection 之后没有再发现值得改动的死代码、重复逻辑或无意义抽象架构评审最终结论APPROVED。10. 小结与延伸Wave 9 的核心贡献可以概括为三点契约加法以SnapshotListener(snapshot, change?)的最小附加式签名让“只发快照”的旧世界平滑过渡到“快照 变更元数据”的新世界窄语义精确性SnapshotChange九字段记录中touchedRuntimeIds用精确 id / [] / null三态刻意表达精确度边界宁可保守也不误报契约完整性的根因修复快速文本路径与事务路径统一经buildSnapshotChange发布并通过 frozen point/range 辅助函数让提交快照的选择区深度冻结。对希望继续深入当前仓库的读者可以从以下路径继续装饰路线图的相邻波次Wave 10 执行计划、Wave 11 执行计划Slate v2 内核源码packages/slate/srcinterfaces/editor/editor-api.ts的getDirtyPaths/shouldNormalize/onChange为脏路径与变更回调的类型定义历史消费者实现with-history.ts编辑器 API 文档editor-api.mdx。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考