dsh-tiddlywiki 0.30.46 → 0.30.48

package/docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 > 最近几个主要版本的一句话记录（完整变更见 [Releases](https://github.com/bbqisbbq/dsh-tiddlywiki/releases) / git log）。
 
+- **v0.30.48**（2026-09-30）：`src/index.ts` **955 → 724** —— 新模块 `index-routes.ts`(381)：**路由 / admin 装配阶段整片**（`RouteDeps` + `AdminDeps` 两个对象与两张路由表的注册，收进 `createRouteStage(deps)`）。**这是 `index.ts` 拆分第二轮**：v0.30.42 先切走了「纯」的配置面，这一轮切走的是**装配阶段里唯一自成一段**的部分 —— 读入口现在能一眼看到生命周期（farm → prompt/tools → 启动任务 → 路由 → 拆卸），而不再被 120 行 accessor 接线打断。三条刻意不动的东西：① **`disposed` 仍归入口**（它的主人是拆卸 effect 与启动任务），唯一需要它的那处守卫改为**传入谓词** `isDisposed()`；② **变更锁仍由入口建、并把同一个实例传进 stage**（v0.30.12：整插件一把锁）—— 顺手删掉一个**从未被读的依赖** `GitLayerDeps.isDisposed`，README 式的「按行删 import」交给 `noUnusedLocals`（一次点名 23 处，零猜）；③ **注册时机一字未改**（`ctx.inject(['webServer'])` 仍在 wikiViews 之后、拆卸 effect 之前 —— 顺序没有重排）。⚠️ 守门同步一处：`verify-mutation-lock` 的「只建一把锁」计数改成**按模块族**统计，并给该判据**剥注释** —— 新模块的说明文字里写了一句 `createMutationLock()`，未剥注释时会被当成**第二个调用点**（v0.30.45 那种「断言被自己的文档满足」的镜像：这次是假红）。
+- **v0.30.47**（2026-09-30）：`src/client/note-widget.ts` **588 → 573** —— 新模块 `note-widget-foot.ts`(73)：**底栏那一组**（左组：上传按钮 / 「🕘 最近」/ `Ctrl+Enter` 提示；右组：「✏️ 在 TW 中编辑」/「保存」）。这一片是**零卡片状态**的纯布局（与 v0.30.43 的 placement 片同类）：依赖面只有「一个已经建好的上传按钮」+「`recent.toggle` 的函数引用」，把 `{ foot, footLeft, footRight, saveBtn, editBtn }` 交回卡片 —— 两个按钮的 `click` 处理器**仍绑在卡片里**（紧挨着实现它们的 `note-widget-save.ts`），因为「谁实现动作」与「谁画按钮」是两件事。`footLeft`/`footRight` 两个 class 一并交回，因为 `.dsh-tw-note-foot-right` 的 flex 规则（右贴边 + 装不下时整组换行，v0.22.6 的按钮压成两行事故）是**契约**，卡片还要往里 append。
 - **v0.30.46**（2026-09-30）：`src/client/note-widget.ts` **615 → 588** —— 新模块 `note-widget-upload-ui.ts`(82)：上传的**接线**那一组（「上传」按钮 + 隐藏的 file input + 拖放到编辑器上，连同它自有的 `dragDepth`）。分层刻意分成两个文件：`note-widget-upload.ts` 是**动作**（`uploadInto`：校验大小 → POST → 在光标处插入 Markdown 行 → toast），`note-widget-upload-ui.ts` 是**接线**（File 从哪来、何时给编辑器挂 `.dsh-tw-note-drop` 高亮）。分界线：整组只问卡片要两样东西 —— 编辑器（拖放目标 + 插入点）与 `wikiQuery`（附件必须落在**这张卡片的目标库**里），卡片侧不再持有任何上传状态（`footLeft.append(upload.button, …)` 一行替代原 36 行）。
 - **v0.30.45**（2026-09-29）：**`note-widget.ts` 拆分第四轮 —— 抽出「保存 / 在 TW 中编辑」整组（677 → 615 行），并在同一轮**抓出一条被注释满足的假绿守门**。① 新模块 `src/client/note-widget-save.ts`（187 行）拿走 `saveDone` · `saving`（在途互斥）· `doSave` · `doEdit` —— 这四样是 `build()` 里唯一真的"说话"的一段（发请求、读回执、弹 toast、改按钮状态与文案）。**分界线（可复用）**：先把这段代码**读写到的闭包状态**列出来，再逐样决定怎么传 —— 它自带的 `saving` **跟着函数走**（同 v0.30.44）；卡片**留在原地**的四样各有理由：`close()` 是卡片自己的可见性收尾、`postEditAndOpen()` **两条路径共用**（`doEdit` 与 `openNative`）所以必须住在两者都看得见的地方、`loadedToken` 的**主人是「🕘 最近」picker**（它写、这里只读）⇒ 按 getter/setter 传、`scope` 这里只读**一个**方法（`stoppedTarget()`）⇒ 传函数而不是整个模块。② `const doSave = async (): Promise<void> => {` 这一行**逐字保留**：`verify-wiki-focus.mjs` 用 `indexOf(那句签名)` 定位函数体、再断言其后 900 字符内出现 `stoppedTarget()`（＝「卡片保存同样要拒绝未运行的目标库」，v0.29.0）；它是**族读**（`readFamily('src/client/note-widget')`）⇒ 搬到新文件仍命中。③ ⚠️ **本版最重要的一条：那条判据在搬迁后变成了假绿，是反向验证抓出来的。** 第一次跑两种注入（**删掉整个 `stoppedTarget()` 拒绝分支** / **把 `doSave` 改名**）——`verify-wiki-focus` **两次都照样绿**。根因：它是拿**未剥注释**的族文本做 `indexOf`，而新模块的**模块头注释**逐字引用了那句签名、还在同一段里提到 `stoppedTarget()` ⇒ `indexOf` 先命中**注释**，900 字符窗口里出现的 `stoppedTarget()` 也来自注释，**断言被自己的文档满足**（这条注释本身是为了解释"为什么这一行不许改名"，属于"越写越安全"的反面）。修法：`verify-wiki-focus.mjs` 新增 `stripComments()`（**先剥行注释、再剥块注释** —— 顺序承重，v0.30.14 在 `verify-client-i18n` 里踩过反序吞代码的坑），那条测试的五条断言全部改跑在剥注释的源码上。**加固后重跑同样的两种注入 ⇒ 两次都稳定 FAIL**（删分支 ⇒「卡片保存同样要拒绝未运行的目标库」；改名 ⇒「找不到 doSave」），还原后文件哈希与注入前**逐字节一致** ⇒ 绿。⇒ 结论：`grep`/`indexOf` 型判据在**拆分**这件事上尤其脆 —— 模块头注释几乎必然会引用被搬走的那句签名，所以凡"定位函数体 + 窗口内找符号"的断言，**必须剥注释**。④ **其余守门一条都不用改**（逐个核实，不是猜）：`verify-frame-guards` 按模块族读并在测试里剥注释行，`dispose()` / `open()` / `openNative()` / `installCardDrag()` / `positionCard()` 都留在卡片里；`verify-wiki-focus:770` 那条**按精确路径**读卡片、钉 `const mark = …note.defaultMark…` 的断言同样不受影响（被断言的那行没离开卡片）。⑤ 一个**诚实的差异**写进模块头（不改变可观察行为）：旧代码直接闭包引用 `editor`/`titleInput`/`tagEditor`/`saveBtn`/`editBtn`，新代码经 `deps.getUi()`，于是两个函数各多一条 `ui === undefined` 早退（实践中不可达 —— 两者都由 `build()` 建出来的按钮与编辑器键位触发，写出来只为类型收窄）。**验证**：`typecheck` / `build`（client bundle 770,645 字节，仍 minify）/ 客户端五守门（`verify-frame-guards` / `verify-wiki-focus` / `verify-tw-origin` / `verify-client-i18n` / `verify-frame-surface`）/ `verify-editor-popup` / `verify:unit`（退出码 0）/ 全量 `npm run verify` 四档退出码 0（E2E / WIKI SWITCH / WIKI FARM BOOT / LARGE WIKI CHECKS 全绿）/ `verify-line-endings`（260 个文本文件全 LF）/ `verify-version-consistency` 全绿。
 - **v0.30.44**（2026-09-29）：**`note-widget.ts` 拆分第三轮 —— 抽出「草稿生命周期」整族，连同它持有的两个状态一起搬走（750 → 677 行）**。① 新模块 `src/client/note-widget-autosave.ts` 拿走 `resetTitle` / `flushDraft` / `scheduleDraft` / `hideDraftBanner` / `resetForNewNote`，**以及它们闭包里的 `draftTimer` 与 `persistedSignature`** —— 这一轮与前两轮都不同：**状态跟着函数整片搬走**，卡片只经模块返回的句柄读写（`resetTitle` / `flush` / `schedule` / `hideBanner` / `resetForNewNote` / `clearTimer` / `setPersistedSignature` / `markPersisted`）。② **为什么这次状态必须走**（而不是像 v0.30.41 的 scope 片那样只传访问器）：`verify-frame-guards.mjs` 把两条不变量**按名字**钉在 `resetForNewNote` 的函数体里（`/clearTimeout\(draftTimer\)/` + `/persistedSignature\s*=/`），它们编码的正是 v0.22.8 的「幽灵草稿」事故 —— 「保存 / 丢弃后重置编辑器」必须①取消防抖定时器、②把这段空内容记成"已定型"，否则 500ms 后那次防抖会把 `{text:'', title:'<时间戳>'}` 写成草稿、下次打开对着空编辑器报「已恢复未保存草稿」。把变量与函数整片搬走 ⇒ 两处字面量**逐字保留**、**一个守门都没有改**；反过来「改名成 `draft.timer` 再放宽断言」会把判据从「钉不变量」降级成「钉新名字」，那才是真正的损失。③ 卡片侧保留 `flushDraft` / `scheduleDraft` / `hideDraftBanner` / `resetTitle` 四个**局部别名**（`const { flush: flushDraft, … } = autosave`）：这些名字在 `build()` / `dispose()` / `open()` 里有十几处调用，改名只放大 diff、不增加信息（v0.30.38 那条「优先抽取、少改名」）。④ 顺带删掉一处**只写不读的死状态** `autoTitle`：自 v0.29.0 起 `flushDraft` 的判据已从「正文为空 **且** 标题是自动生成的那个」升级成「正文为空」（守门还专门断言它不得再引用 `autoTitle`），于是这个变量只剩赋值 —— 把一个只写不读的变量搬进新文件等于把债务搬进新家。⑤ 两个**诚实的差异**写进了模块头，都不改变可观察行为：`getUi()` 可能返回 `undefined` ⇒ 模块里多了早退（旧代码直接闭包引用 `editor`/`titleInput`/`tagEditor`，那时卡片必然已 `build()`，真为 undefined 会抛 TypeError）；`opened` / `disposed` **刻意不进**新模块，按谓词传进去（它们属于卡片的可见性生命周期，与 `note-widget-recent.ts` 同款处理）。⑥ **反向验证**：删掉模块里 `resetForNewNote` 的 `clearTimeout(draftTimer)` ⇒ `verify-frame-guards` 稳定 FAIL 在「保存/丢弃后重置必须取消防抖并记录已定型签名」；还原后文件哈希与注入前**逐字节一致** ⇒ 绿。**验证**：`typecheck` / `build`（client bundle 770,128 字节，仍 minify）/ 客户端五守门（`verify-frame-guards` / `verify-wiki-focus` / `verify-tw-origin` / `verify-client-i18n` / `verify-frame-surface`）/ `verify:unit`（42 套，退出码 0）/ 全量 `npm run verify` 四档退出码 0 / `verify-line-endings` / `verify-version-consistency` 全绿。