nextclaw: Skill for Claude Code

React Rendering Lifecycle Safety

目标

React 数据更新不应自动等价为结构重建。除非产品明确要求重置，流式输出、查询刷新、回调换引用和状态切换都必须保留历史内容与状态型表面的元素身份。

核心模型：React 用 type + key + 父级位置 识别元素。三者任一发生变化，都可能卸载旧 subtree 并重新挂载；memo、useMemo 和 useCallback 不能改变这条身份规则。

强制合同

1. 组件类型必须稳定

• 会作为 JSX 类型、Markdown renderer、component map entry 或 render registry value 使用的组件，默认在模块级声明。
• 动态数据、文案和回调通过 props、Context 或稳定 owner 读取；不得通过重新创建组件类型传递动态值。
• 禁止在组件 render、带动态依赖的 useMemo / useCallback 或普通 factory 中创建组件函数，再把它作为 JSX 类型或第三方 renderer 交给 React。
• useMemo(() => ({ p: () => ... }), [callback]) 仍会在依赖变化时生成新的组件类型；它只缓存值，不提供组件身份合同。

2. key 和父级结构必须表达业务身份

• key 使用稳定业务 ID，不使用数组索引、时间戳、streaming 状态、加载阶段或每次 render 新生成的值。
• pending -> streaming -> final、查询刷新、排序反馈和局部内容追加，不得改变同一业务实体的 key。
• 不要因为状态变化在互不相同的 wrapper / group / portal 结构之间搬运同一 subtree；确需改变父级结构时，先判断是否会重置内部状态。

3. 状态型表面是硬生命周期边界

• iframe、Panel App、editor、canvas、audio、video、WebGL、文件预览和持有浏览器 selection 的文本节点，默认必须保留 DOM 实例。
• 动态分组、折叠、消息聚合和流程摘要不能吞并或跨越这些边界。
• 只有明确的重置、关闭、切换实体或用户主动刷新才能 remount；必须用语义化 key 或显式 reset action 表达，并有测试证明。

4. 后台同步不得接管用户交互状态

• 用户未操作时，不得调用 focus()、改写 DOM selection、恢复旧焦点或关闭当前弹层。
• editor/store/query 的后台同步只更新其拥有的数据；浏览器 activeElement、文字选区和外部弹层不归输入 owner 自动接管。
• 不要在每个 Popover、搜索框或预览区保存/恢复焦点来掩盖上游违约；先修真正触发 focus、selection 或 remount 的 owner。

5. Editor 框架必须独占实时输入状态

• 集成 Lexical、ProseMirror 等 editor 时，先确认框架已拥有的 beforeinput、input、composition、selection 和平台兼容管线；业务层不得再次拦截同一原生事件并从外部快照重建文档。
• React/store 中的 draft 默认是发送、持久化或恢复投影，不是普通键入期间与 editor 并列的第二个可写文档 owner。
• 普通文字、IME 候选词替换、删除和换行优先走 editor 原生命令；只有明确 reset/restore/token 等程序化意图才能写回 editor，并用精确 update tag/source 区分，禁止用定时器或整帧布尔锁忽略 update。
• 若自定义原子节点删除，直接修改目标 editor node，不得先线性化全文再清空 root 重建 selection。

实现检查

修改 React 渲染链路前，逐项确认：

1. 哪些 props、query wrapper、callbacks 会在流式或刷新期间换引用。
2. 这些动态值是否参与创建组件类型、renderer map、key 或父级分组。
3. 哪些 subtree 持有浏览器状态或第三方运行时状态，必须视为硬边界。
4. loading / pending / streaming / final / error 是否只改变 props 和可见内容，而不替换同一实体的结构身份。
5. 是否存在因历史焦点问题留下的 onFocusOutside.preventDefault()、selection restore 或定时 focus 补丁；根因修复后应删除。
6. editor 是否同时被原生事件、React handler 和外部 draft 回灌多路写入；若是，先收敛实时 owner，再讨论事件特判。