mindfulness/spec_kit/Text Wrap/modules/integration/spec.md

integration（子模块规范）

子模块名称

integration（Home / Widget 接入）

目标描述

把 wrapText() 模块以一致参数口径接入到两端渲染链路中，并定义 UI 侧对 meta 的处理规则，确保：

• Home 与 Widget 使用同一套配置/词库/版本号（configVersion）
• 同场景下输出一致；不同测量能力导致差异时“可解释且可治理”
• SYSTEM_DEFAULT 的语义不被 UI 误用

输入/输出定义

输入

• Home（APP）侧输入：
  • text/lang/availableWidth/maxLines/fontSpec/context='APP'
  • 可选：constraints/overflowMode/lineMode/configVersion/debug
• Widget（WIDGET）侧输入：
  • text/lang/availableWidth(profile)/maxLines/context='WIDGET'
  • 可选：constraints/overflowMode/configVersion/debug

输出

• UI 渲染消费：
  • lines[]：逐行渲染或插入 \n
  • wrappedText：用于一次性渲染或日志/缓存
  • meta：用于调试、打点、兜底策略选择

验收标准（可验证）

• 参数映射一致：
  • 两端对 lang/context/availableWidth/maxLines/overflowMode/lineMode 的默认值与映射一致
  • configVersion 必须随结果一起回传到 meta 或打点
• UI 兜底语义正确：
  • 当 meta.fallback_type=SYSTEM_DEFAULT 时：
    • UI 允许选择“交给系统排版”（例如不插入 \n 或忽略 lines[]）
    • 但不改变算法层返回值
• 缓存与复用：
  • Home 可对同文案同参数缓存 wrappedText/lines/breaks
  • Widget 可对固定 profile 文案缓存结果（避免频繁计算）
• 回归可对齐：
  • Golden Cases 在 Home 与 Widget（固定 profile）下可跑通并对齐预期

依赖与关联

• 依赖：全部核心模块（core-contract、breakpoint-candidates、search-engine-*、scoring-tiebreak、overflow-fallback、golden-tests）
• 被依赖：无（最终落地层）