deepseek-harness/missions/tasks/20260721-p1-fw-react/notes.md

fw-react 实现计划（web-react 包；契约=api-contracts v3 §2）

2026-07-21 预习完成。权威序：v3 §2/§1 → architecture §11/§13/§17 → dispatch 任务行+§2 → conventions → t0-checklist。 状态 2026-07-22：v3 §2 全部完工。七刀：e873a846e 依赖+.d.ts / e7384bc6e bind / c7d20d53a store 引擎 / 219ce8af9 useInvoke / f8890b960 bind.spec / 4de74fac5 SessionProvider+RootBindingProvider / 67679d870 scopedSlots。5 spec 35 测全绿，包内 typecheck 绿。 与计划的偏差：①immer 走 update() 内 produce 而非 immer 中间件（中间件 setState mutator 泛型与 vanilla StoreApi 冲突；行为面同）；②仲裁采纳 renderBody/RootBindingProvider（932716e02）。 待 T1/T2：换真 ui-slots core 重跑 scoped-slots.spec；补 @ts-expect-error 越权负样本 已落（f2eb2287c；初版 a367d78a3 被主会话 reset 误剥、暂存区无损重落，主会话认账并立规：共享 worktree 全员零历史改写）。剩：UseSession 收窄对齐 rt-core 的 ConversationSnapshot（rt-core 类型归家时 main 会叫）。 终态：6 spec / 39 测全绿；tsc -b 绿。待命=T2 后机动支援（convo-b Profiler 断言/W5 验收）。

1. createSnapshotStore（store 子路径）

zustand 留 ~4.4.7 不升 v5：我们只用 vanilla createStore + 中间件层，自己经 uSES 出 hook，v5 的变化全在它的 React useStore 层（我们不用）；mutative 换 immer 无 P-I 级收益。不动=无需仲裁，报备即可。

中间件链（外→内）：persist?(rafFlush?(subscribeWithSelector(immer(init))))

• 顺序理由：rafFlush 必须在 subscribeWithSelector 外侧——sws 初始化时捕获当时的 api.subscribe 作为底座；rafFlush 先跑（外侧）才能让 sws 的 selector 订阅也走合批面。persist 不碰 subscribe，放最外。
• rafFlush 设计（自研，真中间件形态）：
  • 持自己的 listeners Set；替换 api.subscribe 为「注册进自己的 Set」；
  • 用捕获的原始 subscribe 注册唯一一个内部监听：置脏标记 + requestAnimationFrame(flush)（已排帧则跳过）；
  • flush：清脏标记后逐个通知自己的 Set。一帧内 N 次 setState = 1 次通知。
  • flush:'sync'（省略该中间件）= 每 setState 同步通知。默认 'sync'：契约未定默认；受控输入（drafts textarea）与用户手势要求同 tick 通知（architecture §5 Notifier 纪律：延迟到微任务/帧会 DOM 回滚+光标跳尾）。帧驱动 store（sessions.list 等）由创建方显式传 'raf'。→ 报备 main，契约若想钉死默认值再补一句。
  • raf 缺席环境（node 单测）回退 queueMicrotask；测试用假 raf 注入计数。
  • 已知取舍（注释入码）：'raf' 模式下同帧内新挂载组件读到新 state 而旧组件未收通知——帧级瞬时不一致，与对象层 Notifier 微任务合批同性质；只用于帧驱动 store。
• immer：官方 zustand/middleware/immer，update(mutator)=setState(mutator)（recipe 形态）、set(next)=setState(next, true)（整体替换）。
• dev freeze：immer 产物自带 freeze；set(next) 整体替换绕过 immer → dev 下（process.env.NODE_ENV!=='production'）deepFreeze(next)。
• persist：opt-in {name} → zustand persist + localStorage（纯 CSR，无 SSR 分支）。
• 门面（SnapshotStore）：getSnapshot=api.getState、subscribe（走合批面）、update、set、useSelector=bindSnapshotSelector(this)。

2. bindSnapshotSelector（uSES 桥）

• 引擎：use-sync-external-store/shim/with-selector 的 useSyncExternalStoreWithSelector（zustand 4.x 既有传递依赖，需在 web-react package.json 补显式 dep + @types devDep——离线可解，包已在 store 里）。
• 绑定时（每 store/Session 构造一次）闭包生成稳定的 sub=(cb)=>w.subscribe(cb) 与 getSnap=()=>w.getSnapshot()——方法经箭头闭包绑定 this（直接传 w.subscribe 会丢 this），且闭包只建一次=引用永稳。
• uSES 契约四条落点：①getSnapshot 纯读缓存引用（源头保证：Session 恒返缓存、store 返 zustand state）；②subscribe 稳定（上条闭包）；③纯 CSR 不传 getServerSnapshot；④等值短路：eq 缺省=Object.is（with-selector 语义），对象切片调用方传 shallowEqual。selector 结果 memo 由 with-selector 自持（state ref + selector/eq 同一性缓存），并发重放安全（getSnapshot 幂等，无 render 期副作用）。
• shallowEqual = re-export zustand/shallow。

3. scopedSlots 工厂（renderSlot 出口）

• scopedSlots(core, ...keys) 返回 { renderSlot }；renderSlot 返回内部组件 <SlotOutlet> 元素。运行时白名单双保险：key ∉ keys → throw（编译期由泛型 K 挡）。
• 订阅：SlotOutlet 内 useSyncExternalStore(cb=>core.subscribe(key,cb), ()=>core.getVersion(key))——version tick 驱动 core.entries(key) 重读（微任务合批归 core）。
• 按 kind 渲染：spec 缺失（define 前渲染）=throw fail loud；single：0 条→fallback??null；list：order 排序+only 过滤 id；keyed：entryKey 命中，无→fallback。
• 每 entry 包 ErrorBoundary（自写小类组件，fallback=极简错误占位含 key/entry id；框架级英文文案，不进 i18n）。
• props 三源合并：{...标配注入, ...cachedInject(binding), ...ownerProps}（owner 最后=可覆写，与契约顺序一致）。
  • 标配注入：session 坑注 useSession=binding.session.useSelector；root 坑无。
  • inject 缓存链：
    • session 坑：WeakMap<SlotEntry, WeakMap<SessionBinding, props>>——外层 key=entry 对象（依赖 fw-slots 保证 entry 对象跨 entries() 快照恒等，跨包假设，需与 fw-slots 钉死）；内层 key=binding 对象（runtime 保证 per-session 恒等引用）。session 拆除→binding 失引→WeakMap 自动回收。
    • root 坑：WeakMap<SlotEntry, props>，inject 只调一次。
  • session binding 来源=BindingContext（web-react 模块私有 React context，SessionProvider 写、SlotOutlet 读）；session 坑在 Provider 外渲染（context 空）=throw fail loud。
• P-I 单形态：无 Suspense，接口不留 renderSuspenseSlot（台账 6b）。

4. createSessionProvider / useInvoke

• SessionProvider：useCurrent() → 无 id 时 renderEmpty?.()??null；resolveBinding(id)（恒等引用）→ undefined 同走 empty；<BindingContext.Provider value={binding} key={id}> 重挂子树。
• useInvoke：pending 不走 setState（architecture §17 幂等五条）——per-hook 外部微 store（useRef 持 {count, listeners}）+ uSES 读 count>0；invoke 经 latest-ref 模式包 fn=引用永稳；并发重入用计数（多次在途 pending 恒真）；rejection 归 domain 层报错（事件回声），框架侧 console.error 兜底后复位 pending。

5. T0 桩对账（05756560b）

• store/index.ts：五件签名与 v3 §2 逐字一致 ✓。
• index.ts：结构一致；SessionId→string、Context→unknown、ConversationSnapshot→ConversationSnapshotLike 为声明的 T0 占位（桩注释已标 rt-core 替换）✓ 可接受。遗留类型归家问题：v3 §2 写 UseSession=SnapshotSelectorHook<ConversationSnapshot> 但 ConversationSnapshot 住 runtime（依赖方向 runtime→web-react，不可反向 import）——真类型的家需 rt-core/main 定（候选：类型下沉可共享位，或 runtime 侧收窄别名）。不阻塞我（实现全程泛型 T）。
• ui-slots 桩：OwnerProps=Partial<E['props']> & object 占位（精确 Omit 归 fw-slots）——我的越权/漏传 props 类型负样本在 fw-slots 真实现落地前只能部分生效，测试先写 @ts-expect-error 待激活。

6. 契约缺口（待 main 仲裁，不自行改接口）

1. SessionProvider「渲染 conversation+details 两坑」但 deps 无 slots 面：web-react 拿不到那两个 key（它们是 ui-layout 的 declare merge，web-react 引用=幽灵依赖，且违反白名单纪律「谁 own 谁 render」）。提议：deps 加 renderBody:(id:SessionId)=>ReactNode（装配方=ui-layout/壳闭包自己的 scopedSlots 供给），Provider 只管订 current+解析 binding+key 重挂+context。
2. root 坑 inject 的 RootBinding.ctx 无供给通道：scopedSlots(core,...keys) 签名里没有 ctx；sidebar 契约明写 b.ctx.layout 绑 actions。提议：web-react 补一个导出 RootBindingProvider: FC<{binding: RootBinding; children}>（React context，壳在 AppRoot 顶部挂一次），SlotOutlet 渲染 root 坑 inject 时读取；缺失=throw。

7. 测试计划（宽松期口径：关键逻辑有测）

• store.spec：结构共享（update 后未动分支引用不变）；raf 合批计数（假 raf：N 次 update=1 通知）；sync 模式同步通知；persist 往返；dev freeze 抛错；shallowEqual 语义。
• bind.spec（jsdom）：等值短路（eq bail 不重渲）；selector 变更响应；订阅引用稳定（重渲零重订）；StrictMode 双调安全。
• slots.spec（jsdom，假 SlotCore+假 binding）：三 kind 渲染矩阵；version tick 重读；ErrorBoundary 隔离（单 entry 炸不塌邻居）；inject 缓存命中计数（同 entry×session 只调一次；换 session 重调）；三源合并优先级；白名单运行时 throw+@ts-expect-error 负样本。
• provider.spec（jsdom）：current 切换重挂（key 语义）；binding 恒等透传；empty 分支。
• useInvoke.spec：pending 时序、并发重入计数、fn 变更后 invoke 引用不变。
• 工具面：vitest jsdom；渲染用 react-dom/client + act（若 workspace 已有 @testing-library/react 则用之，开工时查）。

8. 开工序（T0 广播后）

1. store 子路径全量+store.spec（可独立编译单元，最先落）。
2. bindSnapshotSelector+shallowEqual re-export+spec。
3. useInvoke+spec。
4. BindingContext+createSessionProvider+spec（缺口 #1 裁决前先按提议形态留内部实现位，导出面不动）。
5. scopedSlots+ErrorBoundary+缓存链+spec（缺口 #2 同上）。
6. T1 后删 ui-slots 桩换真包，激活类型负样本。