外观
升级 vendored 的 Cap 组件
ui/vendor/cap/ 是从 @cap.js/widget 的构建模板自建的产物，带一批必须保留的 本地改动。升级不是 npm update 就完事——npm run vendor:cap 会覆盖整个目录。
背景与每处改动的理由见 internals/captcha.md。
步骤
bash
npm i -D @cap.js/widget@<新版本>
npm run vendor:cap # 只做占位符替换，会覆盖 ui/vendor/cap/
git diff # 上游改了什么，一目了然git diff 里被覆盖掉的那些 LOCAL CHANGE 段落就是待办清单。逐条打回去：
| 改动 | 位置 |
|---|---|
| WASM 走本地资源 | cap.js getWasmModule()：上游默认 cdn.jsdelivr.net/npm/@cap.js/wasm@<ver>，改成 @cap.js/wasm 包里的 ?url 资源 |
| pako 兜底走本地资源 | cap.js _inflateRaw()，同样是 ?url 资源 |
| 删光 UI | createUI / animateLabel / shadow root / #div #trigger #troubleshootLink / trigger 上的 click·keydown·mousedown / handleProgress 的进度环与标签写入 / invalid 时的滚动与抖动 / #credits 与 #enforceCredits / 4 处 aria-label 写入；cap.css 整个文件删除 |
加 capUI 出口 | cap.js 的 set capUI / #emitUI / #uiView |
| upgrade own properties | cap.js constructor |
| 去掉 CommonJS/AMD 尾巴 | cap.js 末尾 |
| 类型只留类型 | cap.d.ts：删 Cap 类与 default 导出，保留 CapView |
worker.js 与 cap.d.ts 的其余部分保持与上游逐字一致。
升级后的检查
静态检查，四条：
bash
grep -r jsdelivr ui/vendor/cap # 无结果
grep -n "document.createElement" ui/vendor/cap/cap.js # 不应有界面节点残留
grep -n "WASM_VERSION" ui/vendor/cap/cap.js # 与 package.json 的 @cap.js/wasm 版本一致
grep -n "capUI" ui/vendor/cap/cap.js # setter / #emitUI / #uiView 都在第三条最容易漏：@cap.js/wasm 的版本必须与 cap.js 里原本的 WASM_VERSION 对齐， 否则解题器 ABI 不匹配。
构建检查：
bash
npm run check
npm run build:control
npm run build:auth
grep -rl jsdelivr apps/auth/dist/ # 必须无输出真实验证（自动化替代不了）：
在控制台登录页与授权页各跑一遍真实的人机验证，DevTools 网络面板里除 challenges.natlan.io 外不应有任何跨域请求，Console 里不应出现 Refused to …。
如果控件转圈超过 20 秒后超时，看 troubleshoot-csp.md。
别做的两件事
不要改回 import '@cap.js/widget'。 那份发布产物运行时会去 jsDelivr 取 WASM 与 pako，CSP 收不住——这是自建的全部理由。
不要把界面写回 vendor 里。 界面是 ui/forms/CapCheck.svelte，用共享设计令牌画， 和库里其他控件一样。vendor 只留解题一侧；两边的接口只有 el.capUI 一个回调。
涉及部署的一句提醒
升级会同时影响控制台与授权界面。控制台 push 即自动重建；授权界面必须手工重建投放 （见 deploy-auth.md）。忘掉这一步会让两个站跑在不同版本的解题器上。