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

integration（技术计划）

1. 计划目标

实现对外统一入口 wrapText()（纯函数风格），把已完成的子模块串成可复用算法模块，供 Home（APP）与 Widget（WIDGET）调用：

• 参数口径统一：lang/context/availableWidth/maxLines/overflowMode/lineMode/configVersion/debug
• 输出统一：lines[]/wrappedText/meta，且 meta 可用于治理与 UI 兜底
• 当 meta.fallback_type=SYSTEM_DEFAULT 时，UI 可选择交给系统排版（算法层仅标记，不擅自改变 UI 行为）

2. 入口签名（与大 spec 对齐）

实现并导出：

wrapText({
  text,
  lang,
  availableWidth,
  maxLines,
  context,
  fontSpec?,
  overflowMode?,
  lineMode?,
  constraints?,
  configVersion?,
  debug?
}) => { lines, wrappedText, meta }

3. 组装流程（按执行顺序）

1. normalizeWhitespace（core-contract）
2. tokenize
   • EN：tokenizeEN
   • TC：segmentGraphemes → Token[]
3. breakpoint-candidates
   • generateBreakpoints（传入 constraints.forbiddenBreakRanges）
4. search
   • APP：searchBestLayoutApp（DP+TopK，测量优先）
   • WIDGET：searchBestLayoutWidget（Beam，默认 APPROX；可选 MEASURE）
5. overflow-fallback
   • 当搜索失败或未覆盖到 N：按 overflowMode 执行（ELLIPSIS/CLIP/SYSTEM_DEFAULT）
6. meta 汇总
   • breaks（若可得）
   • scoreTopTerms（debug=true 时）
   • fallback_type/overflow_type/reason
   • configVersion

4. 默认值与映射（固定，确定性）

• overflowMode：
  • APP 默认 CLIP
  • WIDGET 默认 ELLIPSIS
• lineMode：默认 AUTO
• configVersion：默认 'v1'（若调用方未传）
• WIDGET widthMode：默认 APPROX

5. 代码落位（客户端）

• client/src/features/textWrap/
  • wrapText.ts（入口实现）
  • types.ts（对外输入/输出类型）
  • index.ts（统一导出）

6. 测试与回归

• 将 golden-tests 的测试入口从测试 harness 切换为正式 wrapText()（期望不变）
• 增加 1 个 integration 单测：验证 SYSTEM_DEFAULT meta 语义不变

7. 完成定义（DoD）

• wrapText() 可在 APP/WIDGET 两种 context 下运行
• 输出 meta 字段可用于 UI 治理与回溯（含 configVersion）
• 全量 npm test 与 tsc --noEmit 通过
• overview 更新记录变更文件