taffy 0.12→0.14 升级（误换列 #82 根因修复载体：collect_flex_lines definite-main-size 门控）

[15wtyuan]

内容

taffy 0.12.2 → 0.14.0 升级。原始 bug（列方向 flex-wrap 容器内子项高度逐帧动画时某一帧误判超高换列）根因已定位为 taffy 0.12 内部缺陷，0.14.0 含对症修复，本票转为升级票作为修复载体。根因取证全文见 2026-08-27 调研 comment（机制链 + 源码锚点 + 触发条件二分实录）。

升级范围（编译实测的成本清单）

• compute_layout_with_measure 闭包改 (LayoutInput, NodeId, ctx, &Style) -> LayoutOutput（#1091）——crates/core/src/layout/mod.rs measure 闭包区重写（~30 处错误集中于此）。
• Style::min_size/max_size → LengthPercentageAuto（#1099）；tagged-pointer 类型 expand()（#1129，lp() 的 into_raw hack 可换正规 API）。
• Layout::content_size → scrollable_overflow_rect（#1118）——scroll overlap 计算面排查。
• LayoutOutput::first_baselines → baselines: Baselines（#1107）；numeric helper Into<f64>（0.13 #974）。
• serde/pkg 连锁：taffy Style 序列化格式变化 → ResolvedStyle.taffy_style 进 pkg.bin 格式变 → pkg format_version bump + headless fixtures 重打。
• flexbox_balance 成为 default feature——围栏未放 flex-wrap:balance 值集（CSS IFC 换行控制全集（white-space / overflow-wrap / word-break / text-wrap） #73 已拒），不受影响；升级时核对 default features 面。

验收判据

1. HTML=<改版前 layout-anim 页> cargo run -p loomgui_core --example dump_layout_anim_jitter 逐帧 0 异常帧；
2. 复现升格 core 守卫单测（逐帧断言列宽/子项 x 恒定）——0.12 期可先落 #[ignore] 版，升级后转绿防回归；
3. 布局差分守卫（rect-diff 十页/worktree 对拍）不回归；
4. cargo bench -p loomgui_core（solve 每帧重建 taffy 树（坑 186） #29 基准）增量 solve 稳态无明显劣化（0.14 changelog 自述缓存更正确但有性能代价，须实测）；
5. cargo test 全绿 + showcase PlayMode 逐项过（布局面全球性变化，showcase 是肉眼回归网）。

排期

2026-08-27 用户裁决：本票转为升级票；排在 #74（<a> Link）之后开工。showcase layout-anim 页保持纯 div（语义修正，不回退）。

[15wtyuan]

根因已定位（taffy 调试日志铁证）

复现三要素（自包含 example dump_layout_anim_jitter.rs + HTML 环境变量喂页面，逐帧二分所得）：

1. 列方向 wrap 容器：flex-direction:column + flex-wrap:wrap（showcase 现场是类规则 row+wrap 被 inline 只覆写 direction）。
2. 该容器带 min-height（现场 92px，来自 .stage 类）。
3. 祖先有滚动容器（overflow-y:auto 的 .body）——taffy 对滚动容器子树做 min-content 测量。

机制

异常帧中 wrap 容器（NodeId 4294967300）收到一次测量：

available_space Size { width: MinContent, height: Definite(92.0) }
FLEX: Column → collect_flex_lines（main = Definite(92)）
  button flex_basis 20.96 + gap 10 + panel(动画高度) 81.70 = 112.66 > 92 → 换行

链条：

• 滚动容器祖先 → taffy 对子树做 min-content 测量；
• 外层 row 以 MinContent 约束测 inner 的 cross（高度）；
• taffy flexbox.rs ~L688：MinContent 约束下若子项有 min-size，可用空间转成 Definite(min)（inner 的 min-height:92 → Definite(92)）；
• inner 的 collect_flex_lines 在 Definite(92) 下做行收集（MaxContent 才永不换行）→ 内容超过 92 → 面板换到第二「列」（按钮右侧）；
• 该测量相位的换行几何泄漏进当帧最终布局（下一帧最终 pass 用正常 available 覆写 → 一帧抖动）。
• 容器高度反而正常（235=内容高）：determine_container_main_size 对 lines>1 取 max(最长行, available)——混合态特征吻合。

行为画像

• 每次动画只发生一帧；发生帧随 duration/页面细节漂移（f6/f12/f19/f20 均观测到），非固定进度/固定高度。
• Chrome 同结构 45 帧 0 异常：Blink 的 min-content 测量不把换行几何写进最终布局。
• 多因子敏感：去掉 min-height / 去 wrap / 无滚动祖先 /（某些配置下）外层有定尺寸兄弟，都会让它不触发——这解释了为什么最小化复现走了多轮。

修复方向

• core 短期：无干净修法（taffy 内部行为）——页面侧规避已落地（showcase layout-anim 内层容器不再借 .stage 类，无 wrap 残留）。
• 中期：给 taffy 上游报 issue（可附本仓库自包含复现）；或评估 taffy 版本升级是否已改此路径。
• 防再犯可评估：围栏对「column + wrap + min-height 组合」加 warning（语义脆弱组合提示作者）。

复现工具：HTML=<页面> cargo run -p loomgui_core --example dump_layout_anim_jitter（默认模板已含三要素，DUR 可调时长）。

[15wtyuan]

#82 根因定位（2026-08-27 调研批，读源 + 运行时取证双实锤）

结论：taffy 0.12 内部缺陷。wrap 容器在 sizing 测量轮里拿到的 Definite 主轴可用空间被当作换行约束，换列测量结果经节点缓存复用污染终态布局——同输入不同帧出不同终态。0.14.0 含对症修复（collect_flex_lines 新增「主尺寸不 definite 则不换行」门控）；core 喂参侧无可修处（style 集与 Chrome 等价）；修复载体 = 升级 taffy 0.14，待裁决。

机制链（taffy 0.12.2 源码 + debug 日志锚点）

1. collect_flex_lines（src/compute/flexbox.rs:872）：wrap 容器只要主轴可用空间是 AvailableSpace::Definite 就按它断行——不区分「容器自身主尺寸显式 definite」与「祖先测量轮传来的 Definite 可用空间」。
2. determine_flex_base_size（flexbox.rs:684-696）：交叉轴约束映射 MinContent → Definite(子项 style min-cross)。本例：inner（column+wrap、auto 高、CSS min-height:92px）在祖先的 COMPUTE CHILD MIN SIZE 轮拿到 available_space { width: MinContent, height: Definite(92.0) }——92 即它自己的 min-height。
3. 内容总高（按钮 + gap 10 + 面板动画高度）> 92 → 换列 → 测量结果 345.988（按钮+gap+面板横排）×194.68。debug 日志（帧 19, t=333ms）：该值成为 item.flex_basis 与 resolved_minimum_main_size → 污染终态，inner 终宽 346、面板跳到按钮右侧一帧。
4. 邻帧（18/20）同样的测量走缓存不同轮次组合，终态回到 320——闪烁 = 缓存复用与测量轮顺序交互，非 style/anim 数据错（票面已有排查，本次补上 taffy 内部路径实锤）。

触发条件的刀锋性（二分实录）

改版前页 → 1 异常帧（t=333ms，anim_h=194.68，与票面逐位一致）；只留第 1 节仍 1 帧；去 topbar / 去滚动容器 / 去 section 包装 / 去外层兄弟（反而 2 帧）均不清零；按钮朴素化（去 inline 样式）归零；单项回归：font-size:14px 即触发（默认字号不触发）。即：按钮高度落在特定值时，某帧的缓存约束恰好跨界。另：脱离 loomgui 管线的独立 taffy 0.12 mini-repro（同结构+同 37 帧高度序列，四轮逼近）不出现闪烁——flicker 依赖真实管线完整测量轮组合，升级验收以 dump_layout_anim_jitter 真管线为准。

为什么 core 自身修不可行

修复语义需要「容器主尺寸是否 definite」这一 taffy sizing 轮内部状态（0.14 的 known_main_size_is_definite），core 喂参层没有对应接口；唯一近似（凡 wrap 容器禁换行）会破坏合法组合（wrap + 显式高度的换列网格）。我们喂给 taffy 的 style 集与 Chrome 等价（浏览器同结构不换列，票面 A/B）。

0.14.0 对症修复证据

• collect_flex_lines（0.14.0 flexbox.rs:1094）新增门控：if !is_wrap || !known_main_size_is_definite { 单行 }，注释原文 "Wrapping into multiple lines requires a definite main size"——正是 Chrome 行为，机制层消灭本 bug（无论测量轮拿到什么 Definite 可用空间都不换列）。
• 0.13.0 实查无此门（源码 grep known_main_size_is_definite = 0），引入版本钉死 0.14.0（2026-08-24 发布）。关联上游批：caching correctness（#1010/#1155，"Caching logic is now more correct"）+ sizing keywords 重构（#1099/#1103）。

升级成本面（0.12.2 → 0.14.0，本仓编译实测）

• compute_layout_with_measure 闭包改 (LayoutInput, NodeId, ctx, &Style) -> LayoutOutput（#1091）——错误全集中在 crates/core/src/layout/mod.rs measure 闭包区（~30 处），adapter 重写。
• Style::min_size/max_size 改 LengthPercentageAuto（#1099）；tagged-pointer 类型出 expand()（#1129）——lp() 的 into_raw hack 可换正规 API（变好）。
• Layout::content_size → scrollable_overflow_rect（#1118）——scroll overlap 计算面需排查。
• baselines 结构变（#1107）；numeric helper Into<f64>（0.13 #974）。
• serde/pkg 连锁：taffy Style 序列化格式变化 → ResolvedStyle.taffy_style 进 pkg.bin 格式变 → pkg format_version bump + headless fixtures 重打。
• flexbox_balance 成为 default feature——围栏未放 flex-wrap:balance 值集（CSS IFC 换行控制全集（white-space / overflow-wrap / word-break / text-wrap） #73 已拒），不受影响，升级时留意 default features 面即可。

处置

• 修复载体 = taffy 0.12→0.14 升级批（独立批，升级执行待裁决）；升级批第一验收判据 = HTML=<改版前页> dump_layout_anim_jitter 0 异常帧 + 本复现升格守卫单测（0.12 上写 #[ignore] 复现测试，升级后摘 ignore 转绿，防将来回归）。
• showcase layout-anim 页保持纯 div（wrap 是类借用残留，语义修正，已执行的规避保留）。
• 本批（调研）无代码改动；core 1180 lib 测试全绿、工作树干净。

[15wtyuan]

2026-08-27 裁决：#82 转为 taffy 0.12→0.14 升级票（修复载体）；排 #74 之后开工。

[15wtyuan]

2026-08-28 开工裁决（排活会）

• 时序：前置 <a> 标签与 Link 事件 #74 已关，本票即下一主工作项（红修复 afbc67d 单独先行推完即开工）。理由之一：P1 后续新控件（Tree 复合控件（role=tree/treeitem） #8 Tree 等）每叠一件，本票的验收面（showcase PlayMode 逐项 + rect-diff 十页）就变大——赶在新控件前换引擎，布局验证只做一遍。
• 守卫单测两段式：commit ① 在 0.12 上落复现单测（逐帧断言列宽/子项 x 恒定），手动跑证红后标 #[ignore] 入库；commit ② 升级 + 摘 ignore 转绿。红→绿即对症证据，且测试被证明过能失败（防永真守卫）。
• bench 三档验收线（solve 每帧重建 taffy 树（坑 186） #29 基准，稳态增量 solve）：劣化 ≤5% 直接收；5%~10% 停下归因、带实测数据回来用户定夺；>10% 默认 blocker，升级方案重新论证。
• showcase layout-anim 页保持纯 div（2026-08-27 裁决不变）。