05-18 用 Algebraic Effect 改进 React.js 框架设计的探索(一)

[tiye]

这份文档整理这个仓库在前端框架方向上的一组实验经验。它不是要证明“React 可以被 Koka 重写”，也不是要给出一个已经定型的新框架，而是想回答一个更具体的问题：

如果把 Algebraic Effect 当成前端架构里的第一等工具，组件、事件、局部状态、异步流程、测试边界，会发生什么变化？

这份总结仍然从“组件怎么写”开始，因为组件仍然是这类框架最重要的入口。但和前几个版本相比，现在更值得总结的已经不只是 hook，而是“组件约束”本身：哪些地方继续像 React，哪些地方故意不照着 React 走。

1. 组件首先仍然应该是普通函数

这次探索里最不想丢掉的，是 React 最有价值的一点：组件大部分时候应该仍然像普通函数。

在这个仓库里，组件函数依旧主要做三件事：

• 读取当前 model
• 组合 vnode
• 在需要的地方声明局部状态、事件和效果

例如 Todo 面板的入口仍然是一个返回 vnode 的函数：

alias todo_view_effect = <push_hook_scope,pop_hook_scope,use_state_pair,use_effect,register_listener<model,browser_event_effect>,div>

pub fun render_todo_panel(item : model) : todo_view_effect vnode
  component(todo_effect_scope(), fn() {
    val panel_scope = todo_effect_scope()
    val visible = tasks_for(model_filter_name(item), model_tasks(item))
    val total = count_all(model_tasks(item))
    use_effect([model_notice(item), model_draft(item), total.show], fn(root_id) {
      if is_recent_add(item) then browser_focus(root_id, "draft") else ()
    })
    panel("Todo", model_notice(item), "todo", "todo-panel", [
      ...
    ])
  })

这里最关键的经验不是语法，而是约束：

• 组件本身不应该先退化成 framework object
• 组件应当继续保持“输入 state，输出视图”的主结构
• Algebraic Effect 应该增强组件的表达能力，而不是吞掉组件本身

如果一个 Effect 系统让组件写法比 React 组件更绕、更难定位职责，那通常不是进步。

2. 组件 API 现在更像“受约束的 React”

这个仓库现在有意识地把一部分复杂度下沉到了框架层：

• node_class(...)
• text_class(...)
• button_class(...)
• text_input(...)

这样业务组件不再反复写一大串：

• tag
• attrs
• listeners
• 空字符串 text
• Nil

例如现在的 Todo 输入区更接近“受约束的 React props 写法”：

node_class("div", "composer", "composer-row", [
  text_input("draft", "input", model_draft(item), "Add a task or effect experiment...", Nil, [
    on_named_input(panel_scope, "draft-input", fn(value, owner) set_draft(owner, value)),
    dispatch_todo_enter(Add_task),
  ]),
  button_class("add-task", "button button-primary", [dispatch_todo_click(Add_task)], "Add"),
])

这里值得强调的不是“它长得像 JSX”，而是：

• 组件仍然是普通函数
• framework 层允许稍微更复杂
• 目的是让业务组件更短、更稳定、更少样板

这和 React 很像，但比 React 更强调“框架可以更厚一些，换来业务层更薄”。

3. 组件的几种典型用法

这次实验最后比较稳定的组件用法，可以分成下面几类。

3.1 纯渲染组件

最简单的一层，仍然只是根据参数返回 vnode。这类组件不需要本地状态，也不需要特殊能力。

适合承载：

• 布局壳子
• 摘要信息
• 纯展示列表
• 只拼接 props 的子节点

这种组件的意义在于，它让框架保持“默认简单”。不是所有组件都该被 hook、listener、effect row 包起来。

3.2 带局部状态的组件

第二类组件需要临时 UI 状态，比如：

• 某个任务是否进入编辑态
• 编辑框中的草稿值
• 某张 incident 卡片是否展开

这一层现在的做法是：

• 用 component(scope, render) 给组件声明稳定作用域
• 在组件内部用 use_state(...)、use_state_pair(...)
• 让框架按组件作用域加 hook index 管理本地状态

例如任务项组件：

pub fun task_item_view(item : task) : todo_view_effect vnode
  component(task_hook_scope(item), fn() {
    val (editing, set_editing) = use_state_pair(flag_state_codec, False)
    val (draft, set_draft) = use_state_pair(text_state_codec, task_title(item))
    ...
  })

这里得到的经验很明确：

• state/effect hooks 可以继续走 React 那种“稳定顺序 + index”的思路
• 但前提是要有明确的组件作用域
• 作用域不应该让业务代码手动维护一长串 slot path

所以这个仓库最后保留了两套 API：

• 推荐用的默认 API：use_state、use_state_pair、use_effect
• 需要显式路径时再用：use_named_state、use_named_effect

这相当于把“React 风格简洁调用”和“Respo 风格显式路径”做了一层分层，而不是二选一。

3.3 带局部副作用的组件

组件除了局部状态，还会有局部副作用，例如：

• 进入编辑态时自动 focus 某个 input
• 新增任务后对某个 DOM 节点打一个 pulse 动画

这一层继续沿用 hook 语义，用 use_effect(...) 表达：

use_effect([task_id(item).show, if editing then "editing" else "idle"], fn(root_id) {
  if editing then {
    browser_focus(root_id, task_draft_channel(item))
    browser_flash_marker(root_id, task_draft_channel(item), "effect-pulse")
  } else ()
})

这里的经验是：

• 组件内部的 DOM 后处理，依然适合 hook 形式
• Effect 的价值主要体现在“声明能力”，不在于替代 useEffect 这个交互模式本身
• 也就是说，Algebraic Effect 不一定要求你抛弃 React 已经验证有效的组件习惯

更好的方向通常是：保留交互习惯，重写能力边界。

3.4 发送全局 action 的组件

组件里的事件，并不都应该直接闭包修改状态。

这次实验后比较清晰的分层是：

• 全局业务状态变更，走 typed action dispatch
• 组件内部临时状态，允许走局部 closure listener

例如 Todo 里的这些按钮：

dispatch_todo_click(Add_task)
dispatch_todo_click(Toggle_task(task_id(item)))
dispatch_todo_click(Remove_task(task_id(item)))
dispatch_todo_click(Set_filter(value))

这里的好处是：

• 组件能清楚表达“我要发什么 action”
• 全局状态更新路径集中在 reducer / dispatcher
• 组件不需要知道完整的全局修改细节

这部分和 React 社区常见的 reducer / dispatch 思路是一致的，只是这里 action 可以继续进入带 effect 的 reducer 路径。

3.5 带局部 closure listener 的组件

另一些事件并不适合进全局 dispatch，例如：

• 当前任务编辑框的本地输入
• 取消编辑，只清理当前卡片的局部状态
• 某张 incident 卡片的展开 / 收起

这一层如果也强行塞进全局 action，会让临时 UI 状态的路径变得很重。

所以这里保留了 closure listener，但现在这部分已经从“三个独立 listener effect”收敛成了一个统一的注册能力：

• register_listener<model,browser_event_effect>

业务代码仍然通过：

• on_named_click(...)
• on_named_input(...)
• on_named_enter(...)

来声明 listener，但组件签名不再需要把 on_click / on_input / on_enter 一项项展开。

4. 为什么 listener 不沿用 hook 的 index 规则

这是这次探索里非常重要的一条结论。

直觉上，既然 use_state 和 use_effect 可以用 index，那 listener 似乎也可以这样做。但实际写 UI 会发现，listener 的稳定性来源和 hook 不一样。

原因很简单：

• listener 往往藏在 if/else 条件分支里
• 条件渲染非常容易让 listener 的出现顺序改变
• 如果 listener 靠 index 编号，会产生很隐蔽的错配

所以最终稳定下来的规则是：

• hooks 走 scope + index
• listeners 走 scope + event kind + semantic name

对应 API 是：

on_named_input(item_scope, "draft-input", fn(value, owner) ...)
on_named_click(item_scope, "cancel-edit", fn(owner) ...)

这是一条这次探索里非常重要的经验：

不要把所有组件内机制都压成 React hook 那一种 index 规则。

state/effect hooks 和 event listeners 的稳定性来源不同，应该区别对待。

5. 事件注册现在是怎么工作的

listener 现在不是直接把 closure 塞进 DOM，而是走一套更适合当前框架结构的注册流程。

5.1 组件里声明 listener

业务组件里写的是：

on_named_click(item_scope, "cancel-edit", fn(owner) ...)
on_named_input(item_scope, "draft-input", fn(value, owner) ...)

这些调用会：

1. 生成一个稳定 slot path
2. 带着 semantic_name 调用 register_listener(...)
3. 交给 run_event_registry(...) 去解释

5.2 run_event_registry(...) 收集 handler

run_event_registry(...) 会把 listener 注册请求收集成一张 registry：

• click handlers
• input handlers
• warning 列表

同时返回一个轻量 listener(kind, payload) 给 VDOM。

也就是说：

• 业务 closure 仍然保留在 Koka 侧
• DOM 里只保留稳定 payload

5.3 renderer 把 listener 变成 data-k-*

渲染后会落成：

• data-k-click
• data-k-input
• data-k-enter

5.4 DOM bridge 做事件委托

浏览器宿主层只做很薄的一层：

• 根节点事件委托
• 从目标节点读 data-k-*
• 调 Koka 导出的 dispatch bridge
• 再从当前 event_registry 里找到对应 closure 或 fallback action reducer

这和 React 一样，也使用 delegated event 的思路；但和 React 不同的是，这里不是沿 Fiber 树查 handler，而是通过稳定 payload 和当前 registry 做路由。

6. listener 的新约束：防重复和防语义漂移

listener 走 semantic id 以后，会有两个新的风险：

1. 同一个 id 被重复注册
2. 同一个 id 在不同分支里被复用为不同语义

所以 framework 层现在增加了两类 guard：

• duplicate listener warning
• semantic drift warning

它们在两个阶段生效：

• 单次 render 内注册时
• 多个 panel 的 registry 合并时

并且会在 app.kk 里统一打日志。

这条设计的重点不是“绝不允许出错”，而是：

• 让 listener 身份规则进入 framework 层
• 让冲突尽早暴露
• 不把这类细节完全留给业务组件自己兜底

这也是这条路线和 React 的一个明显差异：

React 默认把很多事件稳定性问题交给框架内部规则和用户习惯；这里则更愿意把 listener identity 设计成显式约束，并在运行时给出诊断。

7. 组件签名里的 Effect Row 到底带来了什么

如果只看组件表面，这套写法很像 React。但真正的差异，在函数类型上。

例如现在一个视图函数会显式写出自己需要什么：

• use_state_pair
• use_effect
• register_listener<model,browser_event_effect>
• div

这意味着组件依赖不再主要靠约定，而是直接进入类型。

这件事有两个直接后果。

第一，组件的能力边界更清楚。

你一眼就能知道这个组件：

• 会不会读写本地状态
• 会不会注册局部 listener
• 会不会触发浏览器或业务 side effect

第二，组件外层可以逐步把实现细节收口。

比如目前视图层用了 todo_view_effect、lab_view_effect 这种 alias，把底层 effect row 压成更短的签名。这样既保留了类型信息，又不至于让组件声明完全失控。

这比 React 常见的“看实现才知道组件依赖了什么 hook、什么 context、什么 service”要透明得多。

8. Algebraic Effect 真正改进 React 设计的地方

如果说组件写法本身没有被彻底颠覆，那么 Algebraic Effect 的真正价值，主要体现在下面几层。

8.1 把能力从“隐式依赖”变成“类型里的依赖”

例如 workflow 里会直接声明：

pub fun perform_sync(item : model) : <wait_ms,fetch_lab_snapshot,now_label,audit,div> model
pub fun send_reply(item : model, incident_id : int) : <wait_ms,post_lab_reply,now_label,audit,current_operator,div> model

这比 React 里常见的做法更清晰，因为在 React 里同样的依赖通常会散落在：

• hook 内部
• service module
• context provider
• callback 闭包
• 测试 mock 配置

而这里函数签名本身就说明了它需要：时间、服务调用、日志、当前操作者身份。

8.2 把异步流程留在一条 reducer 风格的路径里

perform_sync(...) 和 send_reply(...) 这类流程，本质上是前端里最容易散掉的部分。

在很多 React 项目里，这类逻辑最后会被拆成：

• 组件里的事件入口
• hook 里的 loading state
• service 调用
• then/catch 或 async callback
• mock service
• test helper

而在这里，它更像一条线性的状态转换函数：

1. 读局部草稿
2. 记录 audit
3. 等待 staged 时间
4. 请求 mock 服务
5. 读取当前时间和 ambient operator
6. 生成新的 immutable model

这就是 Algebraic Effect 对 React 架构最有启发的一点：

不是把异步藏起来，而是把它保留在 typed reducer path 里。

8.3 把 Context 从 provider 树变成显式 ambient capability

像 current_operator 这种上下文值，在 React 里通常会放进 Context。

这里的做法是把它建模成 val effect。这样得到的经验是：

• 上下文依赖仍然存在
• 但它不一定非得通过 provider tree 传递
• 它也可以作为一种显式的 ambient capability 出现在类型里

这比 Context 更强的一点，是测试时替换非常直接；更弱的一点，是生态习惯和可视化工具目前远不如 React 完整。

8.4 把测试变成“换 handler”，而不是“重写业务路径”

这也是这次探索里最实用的一点。

浏览器里，app.kk 会安装一套 handler：

• confirm_action 对应浏览器 confirm
• audit 对应浏览器日志
• wait_ms 对应浏览器侧模拟等待
• current_operator 对应浏览器环境给的值

测试里，则安装另一套 handler：

• wait_ms 不真的等待，只记录 delay
• fetch_lab_snapshot 返回 mock 数据
• post_lab_reply 直接回 mock 回复
• now_label 返回稳定时间戳
• audit 写入收集器

这样测试覆盖的是同一条业务逻辑，而不是“测试专用版本”的逻辑。

这比 React 里常见的大量 mock service、fake timer、render wrapper、provider scaffold 更统一。

9. 组件、事件、状态三者的分工，最后应该怎么落

走到目前这个版本，比较清楚的分工是：

9.1 组件负责描述 UI 和声明依赖

组件负责：

• 读当前模型
• 拼装子树
• 声明本地 hooks
• 声明事件入口
• 触发局部 DOM effect

组件不负责：

• 直接持有浏览器对象
• 隐式访问一堆全局单例
• 把所有业务流程塞进匿名 callback

9.2 全局状态变化尽量走 action dispatch

适合全局 action 的场景：

• 新增任务
• 切换 filter
• 切换任务 done
• 删除任务
• 触发 workflow sync
• 发送 incident reply

这里更接近 React reducer 思想。

9.3 局部临时交互允许走 closure listener

适合局部 closure 的场景：

• 输入框草稿变更
• 卡片展开 / 收起
• 取消编辑
• 只作用于当前组件 subtree 的轻量本地变更

这里不应该为了“架构统一”而强行全局化。

9.4 hook 和 listener 要用两种不同的稳定性策略

这是这次设计里最值得单独记住的一条：

• hook 的稳定性来自调用顺序，所以用 index
• listener 的稳定性来自语义身份，所以用名字

这条边界一旦混掉，条件渲染很快就会把事件系统搞乱。

10. 这条路线相对 React 的收益和代价

收益

• 组件能力边界更显式
• reducer / workflow 的依赖更可审计
• 测试和生产共用一套能力表面
• async UI 流程更容易保持在线性函数里
• listener identity 规则更明确
• framework 可以主动诊断部分事件冲突问题
• 框架层稍厚之后，业务组件样板明显减少

代价

• effect row 会让类型签名变长
• 初次阅读门槛比 React 高
• 事件系统需要更谨慎地区分全局 action 和局部 closure
• 工具链和生态远不如 React 完整
• 需要自己设计一套“哪些能力应当 effect 化”的边界
• 需要接受“并不是所有机制都该像 React hook 一样工作”

所以更准确的结论不是“Algebraic Effect 会取代 React”，而是：

Algebraic Effect 为 React 风格框架提供了一种更强的能力边界建模方式，而 listener identity、宿主集成、测试边界这些原本容易模糊的地方，也可以被更明确地设计出来。

11. 目前最值得保留的结论

如果把这次探索压缩成几条设计结论，我会保留下面这些。

1. 组件仍然应该以普通函数为中心，不要让 Effect 系统吞掉组件的直觉写法。
2. use_state / use_effect 可以继续保留 React 的 hook 使用习惯，但要加上稳定组件作用域。
3. 全局业务状态变化更适合 typed action dispatch。
4. 局部临时 UI 交互更适合 closure listener。
5. listener 不要默认使用 index；在条件渲染下，更稳定的方案是 scope + event kind + semantic name。
6. framework 可以接受稍微更复杂，只要它明显减少业务组件编码量和理解成本。
7. Algebraic Effect 最有价值的地方不是“替代 hook”，而是把能力、上下文、异步流程、测试边界都变成可声明、可替换的接口。
8. 浏览器宿主层应该尽量薄，把 DOM 和环境边界留在外面，把状态转换和流程逻辑留在 Koka 内部。

12. 如果继续往前做，可以重点看什么

如果继续沿这条路线探索，下一步最有价值的问题不是再造更多组件 API，而是继续压实边界：

• 能不能把 scope-aware listener helper 再往前推进，减少业务代码里的 item_scope / panel_scope
• 能不能把 run_local_state(...) 和 run_event_registry(...) 再包成更高层的组件 runner
• 能不能把 listener warning 在 dev/test 模式里升级成更严格的约束
• 能不能继续只在“明显减样板”的前提下，把更多视图 helper 下沉到 respo/core.kk

也就是说，真正值得继续深入的，不是“把 React API 一比一搬进 Koka”，而是借 React 的组件心智模型，重新设计副作用、能力边界和宿主集成方式。

这正是这个仓库目前最有价值的实验结果。

[zzz6519003]

@copilot 语义漂移是啥