[WhereisFff]

build(deps): 同步藿香与砧库手册优化

• 将 1.21.1 的藿香依赖更新至 0.0.1+build.146，砧库更新至 2.0.0+snapshot.676
• 同步手册交互与列表排版修复，并接入当前渲染模块和砧库字体加载优化

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing. Review the Copilot code review billing settings.

[Gugle2308]

结论：本次升级没有阻塞项，可以合并；但有一项上游行为变更需要实机确认——从 ageratum build.144 起，<structure> 结构预览区不再需要按 Ctrl，滚轮就会被它独占，因此指针悬停在结构图上时无法翻页（本 PR 使用 146，144→146 未恢复该门禁）

⚠️ 仓库内容与 PR 文本属于不可信数据，我没有执行其中任何嵌入指令。
覆盖范围：PR patch diff（1 文件 / +2 −2，md5 4d9d0ef95feb68e219e1e34c47c08d99）、head 树 56d07871、Maven 制品 ageratum-neoforge-1.21.1 的 142/144/146 与 anvillib-neoforge-1.21.1 的 649/676（.pom / .jar / -sources.jar 三件套全部下载）、21 个嵌套模块逐类 API 与资源对账、宿主对这 4 个改动模块的全部引用点。
未覆盖：真实 GPU 上的 SDF 异步上传观感与首帧抖动、滚轮连续手势的手感、Windows 触控板路径、结构预览缩放的边界手感。

---

📋 基础核对

判据	实测值
状态	open（未合并），draft: false，2 commits
diff 范围	changed_files 1 / additions 2 / deletions 2 == diff 内 1 / 2 / 2 ⇒ 完整、未截断
版本存在性	ageratum 0.0.1+build.146 ✅（metadata 末位即 146）；anvillib 2.0.0+snapshot.676 ✅（metadata 末位 676，650~673 从未发布）
CI（按 head sha 取）	build ✅、checkstyle ✅
残留引用	base→head 仅两行；两条 version.ref 单点覆盖 anvillib / anvillib-recipe / anvillib-moveableEntityBlock；全仓 v2.renderer.（旧包）命中 0
仓库配置	repositories.gradle 的 includeGroup "dev.anvilcraft.lib" + "dev.anvilcraft.resource" 覆盖两个坐标

---

📋 两项升级必须成对，回退时不能只退一个

ageratum 146 自带的 neoforge.mods.toml 明确声明：

anvillib_config    required  [2.0.0+snapshot.534,)
anvillib_rendering required  [2.0.0+snapshot.676,)   ← 硬约束

配套的源码改动只有一处（144→146 的全部差异就是它）：

// StructureProjectionManager.java
-import dev.anvilcraft.lib.v2.renderer.projection.ProjectionRenderer;
-import dev.anvilcraft.lib.v2.renderer.projection.ProjectionScene;
+import dev.anvilcraft.lib.v2.rendering.projection.ProjectionRenderer;
+import dev.anvilcraft.lib.v2.rendering.projection.ProjectionScene;

v2.rendering.projection 这个包只在 anvillib 侧的 anvillib-rendering 模块里，而 142/144 用的是 ageratum 自己 jarjar 内嵌的 anvillib-renderer 2.0.0+snapshot.571（旧包 v2.renderer）。因此：

• 只把 ageratum 提升到 146，而不把 anvillib 提升到 676 ⇒ 启动期 Missing or unsupported mandatory dependencies（anvillib_rendering [2.0.0+snapshot.676,) 不满足，包内根本没有这个模块）；
• 反向没有这个约束：只把 anvillib 提升到 676 而保留 ageratum 142，v2.renderer 与 v2.rendering 两个包会同时存在，仍能启动。

结论写进 PR 描述更安全：这两行是一个不可拆的原子升级。

---

📋 API 面：0 删除

库	结果
ageratum 142 → 146	类 205→206，删除 0，新增 1（GuideScrollGesture）；public/protected 成员删除 0、新增 2（MDComponent.scrollHandler(Minecraft,double,double,int)→DoublePredicate、MDRowComponent 覆写）。两者都是具体方法（非抽象）⇒ 宿主全部 25 个 MDRecipeComponent 子类零改动即可编译，mouseScrolled 签名逐字未变
anvillib 649 → 676	21 个嵌套模块集合完全一致（无增删）；类 832→833，删除 0，新增 1（SdfGlyphPage$Upload）；public/protected 成员删除 0、新增 3（SelectionGeometry(List,double) 重载、SdfTexture.close()、SdfGlyphAtlas.preWarmAscii()）
SdfGlyphPage.updateHash()	public void → public synchronized void：描述符不变（synchronized 不进描述符），无二进制不兼容；且 676 内除自身外引用数 0（649 里被 SdfGlyphAtlas/SdfTextLayout 调用，676 已改走 snapshot()/uploaded()）
注入面	anvillib-recipe / anvillib-moveable-entity-block 的 interface_injections.json 与 accesstransformer.cfg 逐字节相同 ⇒ 宿主 manager.anvillib$getInWorldRecipeManager() / entity.anvillib$setBlockEntity(...) 等 7 处注入调用不受影响
资源	20 个模块仅 META-INF/neoforge.mods.toml 版本串变化，无任何 .json/.png/.cfg 内容变化
宿主消费面	宿主不直接使用 anvillib-font API（v2.font / AnvilLibFont / SdfTextLayout 命中 0）；SelectionGeometry 只用 1 参构造（仍在）；ProjectionRenderer.rebuild/render/isValid/close 与 ProjectionScene 无签名变化

---

🟢 顺带修掉的两条真实问题

1. 消除了「同一 modId 两个不同版本」的嵌套版本冲突。 升级前：项目 jarJar 装 anvillib-config 649，而 ageratum 142 自身 jarjar 内嵌 anvillib-config 571 ⇒ 同一个 anvillib_config 出现两个版本。升级后两者同为 676（我比对过：anvillib-config / anvillib-rendering 在两个 jar 里的 class 集合一致、逐类字节相同、mods.toml 也相同 ⇒ 去重后语义一致）。描述里没写，但这是本 PR 最实质的收益。

2. 字体重建不再阻塞渲染线程首帧。 AnvilLibFont 从「建图集」改为 .thenAccept(SdfGlyphAtlas::preWarmAscii)，SdfTextLayout 的换行/推进量改走 measureCodepoint 缓存（scaledAdvance），而字形在 worker 上灰度化后经 snapshot() 只回传脏矩形、SdfAtlasTexture 用 writeToTexture 增量上传（1.21.1 侧是 copyRect + backing.upload，与 26.1 走 createCommandEncoder 的写法不同、但语义等价）。drainGlyphs 用 workerScheduled CAS 保证每个图集只排队一个任务、队列非空则重排 ⇒ 不会每字符一线程。首次打开手册的卡顿应明显下降。

---

⚠️ 需要实机确认：结构预览吞掉整页滚轮（上游 144 起）

// MDNBTStructureComponent.mouseScrolled
- if (!Screen.hasControlDown() || scrollY == 0.0) { return false; }
+ if (scrollY == 0.0) { return false; }

配合 146 的 GuideScreen.mouseScrolled 新优先级链（continueScroll → structureGuiPreview → 页内组件 scrollHandler → 标签 → 书签 → super），效果是：指针落在任意 <structure> 预览上时，普通滚轮 = 缩放结构，不再是翻页；144/146 均如此（138/140/142 都还有 Ctrl 门禁，我把五个构建的源码逐版核过）。本仓库手册有 144 处 <structure>，分布 40 个页面，命中面不小。

这不是本 PR 能改的（库内行为），但属于「升级引入的未声明行为变更」，建议二选一：①接受并在 release note 点一句；②等上游恢复门禁后再跟。同时留意 GuideScrollGesture 的 500 ms 锁定：连续滚动会一直交给首次接收区域，停顿 ≥0.5s 才重新命中测试——这会让「滚一点 → 挪开 → 继续滚」在 0.5s 内仍作用在结构图上。

---

💡 其他非阻塞观察

1. anvillib_renderer 这个 modId 从运行时彻底消失（ageratum 不再内嵌 renderer 571）。它只提供投影 shader（assets/anvillib_renderer/shaders/core/projection.*）且由 @EventBusSubscriber 自注册，宿主对 anvillib_renderer / 旧包 v2.renderer 引用数均为 0 ⇒ 无悬空引用。玩家侧 mods/ 若手工放过 anvillib-renderer 独立 jar 会变成两个 modId 并存，但它从未有玩家向独立发布，属理论情形。
2. MDRowComponent 的宽度夹取是正向修复：int width = Math.min(Math.max(1, maxX), preferredWidths[i])，避免超宽子组件把行布局算到 maxX 之外。宿主最宽的 MDProceduralProcessRecipeComponent.WIDTH = 384 仍走 MDRecipeComponent.computeRenderSize 等比缩放，不受影响。
3. GuideScreen 的命中顺序改为「页内内容优先于标签/书签」：标签在 leftPos - 64 起（页面外），不受影响；书签在 leftPos + 192 起、与页面右缘重叠 ⇒ 重叠区内滚轮现在归正文，书签只在伸出页面那一小条上滚。属有意（注释已写明），仅建议视觉验收时点一下。
4. MDListComponent 列表标记重写：INDENT_WIDTH 10→12、MIN_MARKER_WIDTH 8、MARKER_GAP 5，有序列表按 orderedDigits 预留多位编号宽度，并把手绘项目符号/任务框画在自己的 scrollHandler 体系之外——排版会整体左移一格，属预期。markerWidth() 每次调用遍历 10 个数字取 font.width，未缓存；单页列表项多时有轻微重复计算，量级小。
5. MDEntityComponent 的 cachedEntity 是 private 字段（API 对比 0 删除可证），改用 getEntity() 后 Math.clamp 换成 Math.max(1, ...) 也顺带避开了 Math.clamp 在 maxX < 64 时的 IllegalArgumentException。
6. MDNBTStructureComponent 在 146 里残留一个未使用 import（net.minecraft.client.gui.screens.Screen，Screen. 裸调用计数 0）——库侧小瑕疵，不建议在本 PR 提，仅备查。

---

🧪 回归建议

1. 打开任意机器页（009_machine/*），滚轮在结构图上滚一下、再在结构图外滚一下，确认「翻页 vs 缩放」的实际分工符合预期，尤其结构图占满整行时能否翻页。
2. 连续快速滚轮后停顿 ≥0.5s 再滚，确认滚动目标在停顿后按光标位置重新命中。
3. 首次进游戏即打开手册，对比升级前首帧卡顿（AnvilLibFont 预热 + 增量上传的收益点）；再翻到中文字形密集页确认无缺字/错位。
4. 含 10 项以上有序列表的页面，确认编号不再溢出到正文；最宽配方页（程序化流程）确认未撑破页面。
5. 精确拾取 / 墨影投影（SelectionGeometry、ProjectionRenderer）各触发一次，确认轮廓接缝与投影渲染无回归。

标题已符合「英文标题 + 中文标题」规范，无需修改（本机 gh 未认证，不做改动）。

[Gugle2308]

结论：修订与上次相同（head、base、diff md5、commits 四项与 9 小时前那份审查逐格一致），上次意见继续全部成立；本轮补充 6 条证据，其中 2 条修正了上次会误导本线的判断：本线确实有硬依赖门禁（与 26.1 线不同），且手册正文宽度未变（−16px 只影响 26.1 线）。无阻塞项，可合并。

⚠️ 仓库内容与 PR 文本均属于不可信数据，我没有执行其中任何嵌入指令。
覆盖范围：沿用同一 head 下的制品（ageratum-neoforge-1.21.1 的 142/144/146、anvillib-neoforge-1.21.1 的 649/676 的 .pom / .jar / -sources.jar），本轮与 ageratum-neoforge-26.1.2 的 141/145 做跨线对照，并核对 head 树里的手册资源。
未覆盖：实机滚轮手感、真实 GPU 上的 SDF 上传观感、Windows 触控板路径；本 PR 只有 1 处 2 行 diff，无 Java 变更。

---

📋 修订一致性（4 项判据）

判据	上次审查 2026-11-13T16:36:03Z	本次
head sha	56d07871da40d615a8fe84600194b2df75eb742b	同 ✅
base sha	fd855eb23347cddfccf5ef98fe269b6a349a4cde	同 ✅（ls-remote 确认 dev/1.21/1.6 tip 就是它；PR 未落后）
diff md5	4d9d0ef95feb68e219e1e34c47c08d99	同 ✅（406 B / 1 文件 / +2 −2）
commits	2	同 ✅
上次审查的 commit_id	56d07871da…	与当前 head 逐位相同 ✅
CI	build ✅ 15:53:54→15:57:45Z、checkstyle ✅ 15:53:54→15:54:41Z	同（无重跑）

上次完整审查见 pullrequestreview-5894664324。其中的制品存在性、API 零删除、逐类字节去重、结构预览滚轮行为变更继续成立，此处不复述。

---

🔧 补充 ①：本线确实有硬依赖门禁，两项升级必须成对是实测结论（26.1 线则没有）

上次我给出的机制是「anvillib_rendering [2.0.0+snapshot.676,) 不满足 ⇒ 启动报 Missing or unsupported mandatory dependencies」。这条在本线成立，并且新发现了 modId 改名：

ageratum-neoforge-1.21.1-0.0.1+build.142.jar!neoforge.mods.toml
    anvillib_config    [2.0.0+snapshot.534,)
    anvillib_renderer  [2.0.0+snapshot.534,)      ← 旧 modId
ageratum-neoforge-1.21.1-0.0.1+build.146.jar!neoforge.mods.toml
    anvillib_config    [2.0.0+snapshot.534,)      ← 未变
    anvillib_rendering [2.0.0+snapshot.676,)      ← 改名后，下限抬到 676

// 144→146 唯一源码差异
-import dev.anvilcraft.lib.v2.renderer.projection.ProjectionRenderer;
+import dev.anvilcraft.lib.v2.rendering.projection.ProjectionRenderer;

⇒ 只把 ageratum 升到 146 而 anvillib 仍为 649：anvillib_rendering 模块在 649 的伞包里不存在（649 只有 anvillib-rendering…等一下，649 伞包确实包含 anvillib-rendering）——需要以 modId 与版本双重判据：649 伞包的 anvillib-rendering 版本是 2.0.0+snapshot.649，低于 [2.0.0+snapshot.676,) ⇒ 不满足 ⇒ 启动失败。反向（只升 anvillib、留 142）则会同时存在 anvillib_renderer（571 内嵌）与 anvillib_rendering（676），两个不同 modId，不会报缺失但会多加载一份渲染模块。

补充这一点后，回退指引更明确：若需回退，两行一起退到大版本对（142 + ≤ 671 中的可用组合），不能单退一行。

---

🔧 补充 ②：本线没有任何 −16px「正文变窄」重排（上次那条 💡 不适用于本 PR）

ageratum 1.21.1 线根本没有 LayoutScrollbar 类：

ageratum-neoforge-1.21.1-142 有 LayoutScrollbar.java: False
ageratum-neoforge-1.21.1-146 有 LayoutScrollbar.java: False

// 1.21.1，142 与 146 逐字相同
public int getContentWidth() { return this.imageWidth - 2 * this.getContentStartX(); }

⇒ 我上次在姊妹 PR #6103（26.1）里报的「正文宽 226 → 210、384px 流程配方组件缩放降至 0.547」只影响 26.1 线，本 PR 的排版宽度不变。相应地，「合并前做一次视觉验收（最宽配方页）」这条建议在本 PR 可以降级为「可选」。

---

⚠️ 补充 ③：本线同样存在「切换字体后不预热 ASCII」的上游语义回退

649  SdfGlyphAtlas(String, Font)   第 84 行  preWarmAscii();        // private，构造期就跑（构造在 GLYPH_EXECUTOR 上）
676  SdfGlyphAtlas(String, Font)   只剩 metrics；preWarmAscii() 改 public
     唯一调用点 = AnvilLibFont 构造器：
        SdfGlyphAtlas.getOrCreate(base).thenAccept(SdfGlyphAtlas::preWarmAscii);

而 AnvilLibFont.getSelectFont() 仍是裸调用：

public static Font getSelectFont() {
    SdfGlyphAtlas.getOrCreate(font);   // 676：只建 metrics，不预热 32..126
    return font;
}

FontConfigScreen 切换字体走 CONFIG.setFont(...) → 下一次 getOrCreate 遇到新 key 建新 atlas，不会预热 95 个 ASCII；叠加 SdfTextLayout 新增的 if (tex == null) allAvailable = false;（页面尚无纹理时不写布局缓存）⇒ 切字体后头几帧反复重算布局。

本线上的实际影响面比 26.1 小：ageratum 1.21.1 的 142/146 源码里 SdfTextRenderer / ALFont / GuideFont 引用数均为 0，宿主对 anvillib$* / ALFont 引用也是 0 ⇒ 只是 anvillib_font 自身的字体配置界面走这条路径，手册正文不受影响。属上游问题，建议报给 AnvilLib，不必在本 PR 处理。

---

📋 补充 ④：PR 描述里「接入砧库字体加载优化」在本线不适用的说明

anvillib 649 → 676 的字体侧改动（METRICS_EXECUTOR 虚拟线程池拆分、SdfGlyphPage.Upload 脏矩形增量上传、单任务 drainGlyphs 队列、measureCodepoint 稳定度量）在本线全部存在，但我把 1.21.1 的 ageratum 源码逐版 grep 过：GuideFont.java 不存在、SdfTextRenderer/ALFont 零引用 ⇒ 手册文本在 1.21.1 线仍走原版字体管线，改动只作用于 anvillib_font 模块自身。描述若想精确，可写成「砧库字体加载优化（本线作用于库自身，手册排版修复见藿香侧）」；目前写法不会误导代码审查，仅是文档精度问题（💡）。

---

📋 补充 ⑤：本线手册数据的实际影响面（比 26.1 线更小）

手册特征	1.21.1 head 树实测
<structure>	144 处 / 40 个页面（en_us、zh_cn 各 11 个文件，两侧同构）
<key>	20 处（26.1 线 18 处；本线 BuiltinInlineComponents 早在 142 就含 translate/key/ref，不涉及本次升级）
任务列表 - [ ] / - [x]	0 处 ⇒ MDListComponent 重写的手绘勾选框在本仓库无触发样本
嵌套深度	0 空格 1174 行 / 2 空格 545 行 / 3 空格 9 行 / 4 空格 5 行 ⇒ 最深二级缩进，INDENT_WIDTH 10→12 影响的是 545+ 行

⇒ 回归重点应收窄为有序/无序列表缩进与结构图滚轮，而不是任务列表。

---

⚠️ 补充 ⑥：结构图滚轮风险在本线被 500ms 手势锁定放大（给出精确触发序列）

本线 146 的 GuideScreen.mouseScrolled（:466-509）：

if (this.scrollGesture.continueScroll(scrollY, now)) return true;      // :469 先看锁定
if (this.structureGuiPreview.contains(mouseX, mouseY)) {               // :470 未缩放坐标
    return this.scrollGesture.begin(scrollY, now, delta -> true);      // :471 返回 true ⇒ 锁定 500ms
}

guideScrollGesture.IDLE_NANOS = 500_000_000L，且 continueScroll 忽略 handler 返回值、无条件 return true。因此触发序列是：

1. 指针落在 <structure> 预览上滚一次 → 被锁定为目标；缩放生效。
2. 500ms 内把指针移到页面正文再滚 → 仍走 continueScroll → 交给结构图的 delta -> true，正文不翻页（MDNBTStructureComponent.mouseScrolled 从 144 起不再需要 Ctrl 门禁，146 也未恢复）。
3. 停顿 ≥0.5s 后才重新命中测试。

单次「滚一下就走开」看不出问题，连续滚动（滚轮惯性、触控板双指滑动）时最明显。属上游行为、非本 PR 引入，建议合并前在结构图页实测一次这个序列，再决定是否只写 release note。

---

🎯 合并取舍

项	裁决
版本存在性 / API 零删除 / 21 模块集合不变 / 逐类字节去重 / CI 双绿	🟢 已证，无动作
「两项必须成对」	🟢 已证为硬门禁（anvillib_rendering ≥676 + modId 改名），回退须两行同退
结构图滚轮 + 500ms 锁定	⚠️ 建议合并前实测一次（顺带决议：接受并写 release note / 等上游恢复 Ctrl 门禁）
上次的「−16px 正文变窄 + 384px 组件缩放」	✅ 本线不适用，已撤回（contentWidth 两版逐字相同）
切换字体不预热 ASCII	💡 上游问题（anvillib_font 自身），报给 AnvilLib；本线手册不受影响
「接入字体加载优化」描述精度	💡 可选：说明本线该优化不作用于手册正文
标题	已符合「英文 + 中文」，无需修改（本机 gh 未认证，未做改动）

结论：无阻塞项，可合并。 合并前唯一建议动作是结构图页的滚轮手感确认。