tiye · Oct 31, 2026 · Oct 28, 2026 · Oct 31, 2026
diff --git a/.github/workflows/upload.yaml b/.github/workflows/upload.yaml
@@ -44,13 +44,16 @@ jobs:
 
     - name: Validate Calcit snapshot
       run: |
+        set -euo pipefail
         calcit calcit.cirru edit format
-        git diff --exit-code -- calcit.cirru
+        git diff --exit-code --quiet -- calcit.cirru
         calcit --check-only --all-defs --format json
         calcit --check-only --ns app.main --ns app.config --ns app.schema --ns app.updater --format json
         calcit fix --workflow strict --verify --format json | jq -e '.data.workflow.status == "passed" and .diagnostics == []'
         calcit analyze weak-types --only dynamic-method --summary-only --format json | jq -e '.data.summary.findings == 0'
         calcit analyze weak-types --only deprecated-call --summary-only --format json | jq -e '.data.summary.calls == 0'
+        calcit docs check-md docs/guide.md --failures-only
+        calcit docs check-md docs/guide/dom-events.md --failures-only
 
     - name: Compile and build web app
       env:

diff --git a/README.md b/README.md
@@ -1,19 +1,15 @@
 
 # Respo Guidebook
 
-配对正式 Calcit CLI / `@calcit/procs` 0.31.0，以及已发布的 Docs Workflow 0.0.38、
-Respo 0.17.0-alpha.2、Reel 0.7.0-alpha.2、UI 0.9.0-alpha.2 和 JS-FFI 0.2.5。
-工具链为正式版本，模块图仍有预发布版本；不把两者统称为全图稳定。升级后重新安装依赖并完整
-刷新页面，不混用旧 CLI/alpha runtime。UI 0.9 基础样式可能影响外观。源码仅使用
-`calcit.cirru` 与 `deps.cirru`，不生成 compact/package.cirru。
+使用者注意：本轮将站点 Calcit CLI / `@calcit/procs` 从 **0.31.0** 配对正式 **0.32.1**，采用已发布 Docs Workflow **0.0.40**、Respo **0.17.1**、UI **0.9.0** 和 JS-FFI **0.2.9**。Reel **0.7.0-alpha.5**、Markdown **0.5.0-alpha.5**、Router **0.9.0-alpha.4** 仍为已发布 alpha，不声称完整依赖图均为正式版。升级后重新安装完整精确依赖图并刷新页面，UI 样式可能变化。源码仍仅使用 `calcit.cirru`，依赖以 `deps.cirru` 为准，不恢复 compact/package.cirru。
 
 Guide 说明当前 Ref/watch、Option、event handler/app dispatch、名义 Store 和宿主边界。
 旧 Beginner Guide、部分 Guide 实现说明和 API 仍有历史片段，尚未全部迁移或独立执行；站点构建通过不代表
 所有旧示例都可用于当前版本。新应用以维护中的模板和已发布接口为准。
 
 ## 开发与验收
 
-Node 24、Yarn 4.18.0、正式 0.31.0 CLI：
+Node 24、Yarn 4.18.0、正式 0.32.1 CLI：
 
 ```bash
 corepack enable
@@ -27,12 +23,12 @@ yarn dev
 
 `yarn build` 默认使用相对资源路径，`VITE_BASE_URL` 可指定前端 CDN 根路径。CI
 检查所有定义、公开 namespace、完整 strict、旧调用与动态方法，构建 SPA/mdBook
-并保存 PR 预览。原项目没有定义附带测试，零个测试不等于业务覆盖；浏览器导航、
+并保存 PR 预览。当前 Guide 计数器与 DOM Events 数据解码示例由官方代码块检查覆盖；原项目没有定义附带测试，零个测试不等于业务覆盖；浏览器导航、
 搜索与刷新需另行验收。页面 `hud!` 错误展示保留。
 
 默认 entry 的 dispatch-op 显式绑定原有 renderer 的 Dynamic 宿主入口；
 非 Enum 输入仍被拒绝，业务 payload 仍受检后构造 Docs Workflow 的具名 Op。
-Store/Op、全部定义 schema 与处理函数未改，不以关闭证明审计或增加断言绕过 strict。
+14 个定义的 schema 与 Store/Op 合同保持；官方 formatter 转换 renderer 的一处类型提示，业务表达式不变，不以关闭证明审计或增加断言绕过 strict。
 
 ## 部署边界
 
@@ -41,13 +37,16 @@ action 内置校验，不新增脚本。原 SPA/mdBook 的 rsync 目录均保持
 `/web-assets/repo/Respo/guidebook`，无服务端部署。本 PR 不自动合并或发版。
 组织级 COS secrets 需要授权本仓库；PR 不读取部署凭据、不运行 COS 或 rsync。
 原 SHA256 校验的 rsync/mdBook 安装、SSH 主机校验和 main 部署条件保留。
+CI 的类型步骤显式启用 pipefail，保留上游 Calcit 失败退出码；canonical diff 仅静默输出。
+npm 新版本解析使用统一一小时包龄，无包级豁免；已有 lock 的 immutable 重放不重新检查包龄。
 
 ```bash
-cargo install mdbook
-cargo install mdbook-linkcheck
+# 与 CI 对齐 mdbook 0.4.14 / mdbook-linkcheck 0.7.6
 mdbook build
 ```
 
+已知 mdBook Cirru 高亮回退为纯文本，见 [Docs Workflow #95](https://github.com/calcit-lang/docs-workflow/issues/95)；当前构建不声称修复该限制。
+
 ## License
 
 MIT
diff --git a/calcit.cirru b/calcit.cirru
@@ -13,24 +13,24 @@
         'Site $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defstruct Site (:storage-key 'String)
           :examples $ []
-          :schema $ :: 'StructDef
+          :schema $ quote StructDef
         'dev? $ %{} 'CodeEntry (:doc |)
           :code $ quote $ def dev?
             = |dev $ .unwrap-or (get-env |mode) |release
           :examples $ []
-          :schema $ :: 'Bool
+          :schema $ quote Bool
         'site $ %{} 'CodeEntry (:doc |)
           :code $ quote $ def site (Site :storage-key |workflow)
           :examples $ []
-          :schema $ :: 'app.config/Site
+          :schema $ quote app.config/Site
       :ns $ %{} 'NsEntry (:doc |)
         :code $ quote $ ns app.config
     'app.main $ %{} 'FileEntry
       :defs $ {}
         '*reel $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defref *reel (typed/new-reel schema/store)
           :examples $ []
-          :schema $ :: 'Ref $ :: 'reel.typed/State 'docs-workflow.schema/Op 'docs-workflow.schema/Store
+          :schema $ quote $ Ref (reel.typed/State docs-workflow.schema/Op docs-workflow.schema/Store)
         'dispatch! $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn dispatch! (op)
             when config/dev? $ println |Dispatch: op
@@ -55,9 +55,7 @@
                   _ $ eprintln |Unknown-operation: op
             , &unit
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'Unit)
-            :args $ [] 'Enum
-            :features $ #{} :js-ffi
+          :schema $ quote $ Fn Enum (-> Unit) (:features :js-ffi)
         'main! $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn main! () (register-languages!)
             println "|Running mode:" $ if config/dev? |dev |release
@@ -69,25 +67,20 @@
             browser/set-interval! persist-storage! 60000
             println "|App started."
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'Unit)
-            :args $ []
-            :features $ #{} :js-ffi
+          :schema $ quote $ Fn (-> Unit) (:features :js-ffi)
         'mount-target $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn mount-target ()
             .query-selector (js-cast js/document dom/DomDocument) |.app
           :examples $ []
-          :schema $ :: 'Fn $ {}
-            :args $ []
-            :features $ #{} :js-ffi
-            :return $ :: 'JsNullish 'respo.dom/DomElement
+          :schema $ quote $ Fn
+            -> $ JsNullish respo.dom/DomElement
+            :features :js-ffi
         'persist-storage! $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn persist-storage! () (js/console.log |persist)
             browser/storage-set! (:storage-key config/site)
               format-cirru-edn $ :store @*reel
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'Unit)
-            :args $ []
-            :features $ #{} :js-ffi
+          :schema $ quote $ Fn (-> Unit) (:features :js-ffi)
         'reload! $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn reload! ()
             if (nil? build-errors)
@@ -98,23 +91,16 @@
               hud! |error build-errors
             , &unit
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'Unit)
-            :args $ []
-            :features $ #{} :js-ffi
+          :schema $ quote $ Fn (-> Unit) (:features :js-ffi)
         'render-app! $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defn render-app! ()
             render! (mount-target) (comp-container @*reel schema/docs)
               fn (op)
-                hint-fn $ {}
-                  :args $ [] 'Dynamic
-                  :return 'Unit
-                  :features $ #{} :js-ffi
+                hint-fn $ Fn Dynamic (-> Unit) (:features :js-ffi)
                 if (enum? op) (dispatch! op) (raise "|Expected an Enum render action")
                 , &unit
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'Unit)
-            :args $ []
-            :features $ #{} :js-ffi
+          :schema $ quote $ Fn (-> Unit) (:features :js-ffi)
       :ns $ %{} 'NsEntry (:doc |)
         :code $ quote $ ns app.main
           :require
@@ -177,20 +163,19 @@
                 DocNode :title |patch-instance! :key :patch-instance :content (load-doc |apis/patch-instance.md) :children $ []
               DocNode :title |Community :key :community :content (load-doc |community.md) :children $ []
           :examples $ []
-          :schema $ :: 'List 'docs-workflow.schema/DocNode
+          :schema $ quote $ List docs-workflow.schema/DocNode
         'load-doc $ %{} 'CodeEntry (:doc |)
           :code $ quote $ defmacro load-doc (filename)
             read-file $ str |docs/ filename
           :examples $ []
-          :schema $ :: 'Macro $ {}
-            :capabilities $ #{} :fs-read
-            :expansion $ :: 'Expr 'String
-            :required $ [] 'Syntax
+          :schema $ quote $ Macro Syntax
+            -> $ Expr String
+            :capabilities :fs-read
         'store $ %{} 'CodeEntry (:doc |)
           :code $ quote $ def store
             Store :states $ {} $ :cursor ([])
           :examples $ []
-          :schema $ :: 'docs-workflow.schema/Store
+          :schema $ quote docs-workflow.schema/Store
       :ns $ %{} 'NsEntry (:doc |)
         :code $ quote $ ns app.schema
           :require $ docs-workflow.schema :refer $ DocNode Store
@@ -199,8 +184,7 @@
         %{} 'CodeEntry (:doc |)
           :code $ quote $ defn updater (store op op-id op-time) (docs-updater/updater store op op-id op-time)
           :examples $ []
-          :schema $ :: 'Fn $ {} (:return 'docs-workflow.schema/Store)
-            :args $ [] 'docs-workflow.schema/Store 'docs-workflow.schema/Op 'String 'Number
+          :schema $ quote $ Fn docs-workflow.schema/Store docs-workflow.schema/Op String Number (-> docs-workflow.schema/Store)
       :ns $ %{} 'NsEntry (:doc |)
         :code $ quote $ ns app.updater
           :require $ docs-workflow.updater :as docs-updater
diff --git a/deps.cirru b/deps.cirru
@@ -1,10 +1,10 @@
 
-{} (:calcit-version |0.31.0)
+{} (:calcit-version |0.32.1)
   :version |0.0.4
-  :dependencies $ {} (|Respo/reel.calcit |0.7.0-alpha.2)
-    |Respo/respo-markdown.calcit |0.5.0-alpha.3
-    |Respo/respo-router.calcit |0.9.0-alpha.1
-    |Respo/respo-ui.calcit |0.9.0-alpha.2
-    |Respo/respo.calcit |0.17.0-alpha.2
-    |calcit-lang/docs-workflow |0.0.38
-    |calcit-lang/js-ffi |0.2.5
+  :dependencies $ {} (|Respo/reel.calcit |0.7.0-alpha.5)
+    |Respo/respo-markdown.calcit |0.5.0-alpha.5
+    |Respo/respo-router.calcit |0.9.0-alpha.4
+    |Respo/respo-ui.calcit |0.9.0
+    |Respo/respo.calcit |0.17.1
+    |calcit-lang/docs-workflow |0.0.40
+    |calcit-lang/js-ffi |0.2.9
diff --git a/docs/beginner-guide.md b/docs/beginner-guide.md
@@ -1,6 +1,6 @@
 > Historical tutorial: the old macro expansions, JavaScript access and dispatch
 > examples below predate current typed APIs. Start with **Guide** in the sidebar
-> for formal 0.31.0 contracts. This is not a standalone checked current app.
+> for formal 0.32.1 contracts. This is not a standalone checked current app.
 
 Want to explore by yourself?
 

diff --git a/docs/guide.md b/docs/guide.md
@@ -1,10 +1,6 @@
-# Guide: Calcit 0.31.0
+# Guide: Calcit 0.32.1
 
-This site pairs formal Calcit CLI / `@calcit/procs` **0.31.0**, Respo
-**0.17.0-alpha.2**, Reel **0.7.0-alpha.2** and Docs Workflow **0.0.38**.
-The CLI/runtime are formal releases; the module graph still includes prereleases. Use `calcit.cirru`
-for source and `deps.cirru` for published module versions; do not restore
-`compact.cirru` or `package.cirru`, or mix this runtime with an alpha CLI.
+This site pairs formal Calcit CLI / `@calcit/procs` **0.32.1** with released Docs Workflow **0.0.40**, Respo **0.17.1** and JS-FFI **0.2.9**. The published UI graph still includes Reel **0.7.0-alpha.5**, Markdown **0.5.0-alpha.5** and Router **0.9.0-alpha.4**; it is not an entirely stable-release graph. Install it using Caps strict and keep runtime and CLI paired. Use `calcit.cirru` for source and `deps.cirru` for module versions; do not restore `compact.cirru` or `package.cirru`.
 
 For a new application, start with the maintained
 [Respo template](https://github.com/Respo/respo-calcit-workflow). Check its own
@@ -25,9 +21,7 @@ ns example.counter
 defref *count 0
 
 defn increment! ()
-  hint-fn $ {}
-    :args $ []
-    :return 'Unit
+  hint-fn $ Fn $ -> Unit
   reset! *count $ inc @*count
   , &unit
 ```
@@ -52,7 +46,7 @@ handle `typed/decode-control` separately, and use `typed/record-op` for domain
 operations. `Date.now` is a host call, not a numeric constant; JS-FFI's
 `date-now-snapshot` exposes a checked `:timestamp` value.
 
-This app uses Docs Workflow's published **DocNode, Store and Op**, plus its
+This app uses Docs Workflow's **DocNode, Store and Op**, plus its
 updater. A second nominally distinct Store with identical fields is not
 interchangeable with that module's Store.
 
@@ -74,6 +68,6 @@ fragment or certify browser/WebSocket application behavior.
 The Beginner Guide, older implementation discussions under Guide, and several API
 chapters retain historical design notes. Their
 old macro expansions, direct JavaScript access and operation syntax are not
-copy-ready 0.31.0 code. Consult the paired published module's `calcit query def`
+copy-ready 0.32.1 code. Consult the paired published module's `calcit query def`
 and `query schema` views and the maintained template. Historical examples need
 section-by-section migration, not mechanical renaming without contract checks.
diff --git a/docs/guide/dom-events.md b/docs/guide/dom-events.md
@@ -1,48 +1,30 @@
 ## DOM events
 
-Here is a simple demo handling `input` events:
+当前 Respo `respo.schema/EventHandler` 接收两个参数：不可变的 `Map<Tag,Dynamic>` 事件数据与应用的 dispatch 函数。dispatch 只接收一个 entry `dispatch-op` 类型的值并返回 Unit；不要沿用旧 `(op, op-data)` 两参数调用方式。
 
-```cirru
-input $ {}
-  :on-input $ fn (e dispatch!)
-    println (:value e)
-```
+事件转换以已发布 `respo.util.format/event->edn` 为准，不要复制旧版 `case-default` 与直接 JavaScript 属性读取的实现。常见 click、input/change、键盘事件的 `:type` 为对应 Tag；不认识的事件类型仍可能是 String。input/change 提供 `:value`、`:checked`，键盘字段由当前库填充，不能假定所有事件都有相同字段。
 
-`e` is a HashMap with several entries:
+Map 读取返回 Option。输入框应用预期文本时，可在这个真实开放边界收敛为 `Option<String>`：
 
 ```cirru
-def e $ {}
-  :type "|input"
-  :original-event event
+let
+    input-text $ fn (event)
+      hint-fn $ Fn (Map Tag Dynamic)
+        -> $ Option String
+      decode-map-as (get event :value)
+        quote $ Option String
+  assert= |hello $ .unwrap $ input-text
+    {} $ :value |hello
+  assert= true $ .none? $ input-text ({})
 ```
 
-The details:
+缺失 `:value` 返回 none；已有空字符串仍是 some，已有非 String 值会被 decoder 拒绝，不以任意空字符串隐藏错误。此原生示例验证事件数据读取，不模拟或证明浏览器事件的完整绑定与传播行为。
 
-```cirru
-defn event->edn (event)
-  ; js/console.log "|simplify event:" event
-  ->
-    case-default (.-type event)
-      {}
-        :msg (str "|Unhandled event: " (.-type event))
-        :type (.-type event)
-      |click $ {}
-        :type :click
-      |keydown $ {}
-        :key-code (.-keyCode event)
-        :type :keydown
-      |keyup $ {}
-        :key-code (.-keyCode event)
-        :type :keyup
-      |input $ {}
-        :value (aget (.-target event) "|value")
-        :type :input
-      |change $ {}
-        :value (aget (.-target event) "|value")
-        :type :change
-      |focus $ {}
-        :type :focus
-   assoc :original-event event
-```
+原始 DOM event 位于 `:event`，兼容字段 `:original-event` 也保留。它是宿主对象，整个事件 Map 不是 DOM event；浏览器属性读取应沿用 Respo/JS-FFI 的实际宿主合同，不能把 Map 强转为另一类型。事件绑定与传播策略也应查看实际库实现，不从这段数据示例推断。
+
+在项目中核对当前版本的 source of truth：
 
-Events are bound directly on the elements for simplicity and consistency. And it stops propagation when event is triggered.
+```bash
+calcit query def respo.schema/EventHandler
+calcit query def 'respo.util.format/event->edn'
+```
diff --git a/docs/home.md b/docs/home.md
@@ -4,7 +4,7 @@
 
 Inspired by React and Reagent.
 
-This site targets formal Calcit/procs **0.31.0**. Choose **Guide** in the sidebar
+This site targets formal Calcit/procs **0.32.1**. Choose **Guide** in the sidebar
 for current migration notes. Beginner Guide and older API chapters retain
 historical material; not every snippet is ported or independently type-checked.
 

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "packageManager": "yarn@4.18.0",
   "dependencies": {
-    "@calcit/procs": "0.31.0"
+    "@calcit/procs": "0.32.1"
   },
   "devDependencies": {
     "bottom-tip": "^0.1.5",

diff --git a/yarn.lock b/yarn.lock