mindfulness/spec_kit/Text Wrap/modules/overflow-fallback/plan.md

overflow-fallback（技术计划）

1. 计划目标

实现统一的“溢出与兜底”策略模块，用于在以下情况给出确定性且可解释的返回：

• 搜索器无法在 <=maxLines 覆盖到结束边界 N
• lineMode=FIXED 需要刚好 maxLines 但无解
• 测量不可用或失败导致无法执行宽度派约束（尤其 Widget）

支持三种模式：

• ELLIPSIS：最后一行加省略号并保证不超宽（必要时回退移除 token 再加）
• CLIP：截断到 maxLines（不加省略号）
• SYSTEM_DEFAULT：算法层不插入换行，交给系统排版（仅在 meta 标记）

2. 对外输入/输出（与 spec 对齐）

2.1 输入

• tokens: Token[]
• partialLayout?: { breaks: number[]; lines: Array<{ start; end; text? }> }
  • 若提供：表示搜索器的 best-effort（可能未覆盖到 N）
• overflowMode: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT'
• availableWidth: number
• maxLines: number
• lang: 'TC' | 'EN'
• context: 'APP' | 'WIDGET'
• ellipsisToken: string（推荐 "…"，配置化）
• measure?: { contextProfile; fontSpec; measureWidthImpl; widgetEnableMeasure? }（用于“加省略号后再测量”）
• reason: 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'TOO_LONG' | 'WIDOW' | 'PARTICLE' | string

2.2 输出

统一返回：

• result: { lines: string[]; wrappedText: string; meta: { fallback_type; overflow_type; reason } }

其中：

• fallback_type: NONE | RELAX_RULES | SYSTEM_DEFAULT
• overflow_type: NONE | ELLIPSIS | CLIP

3. 核心行为细则（对应文档 12.x）

3.1 overflow 判定

在本模块内不重新跑搜索，仅基于输入判断：

• 若 partialLayout 覆盖到 N（即最后一行 end==N），则 overflow_type=NONE
• 否则为 overflow，按 overflowMode 执行

3.2 SYSTEM_DEFAULT（12.4A）

• 返回 lines=[原文单行]，wrappedText=原文
• meta.fallback_type='SYSTEM_DEFAULT'
• meta.overflow_type='NONE'（因为不再输出算法换行；由 UI 决定是否完全交给系统）
• meta.reason=输入 reason

3.3 CLIP

• 若 partialLayout 有 lines：取前 maxLines 行，重组 wrappedText=lines.join('\n')
• 若无：返回单行原文
• meta.overflow_type='CLIP'，fallback_type='NONE'，reason=输入 reason

3.4 ELLIPSIS（12.3/12.5）

仅处理最后一行：

1. 选取 baseLines：
   • 优先使用 partialLayout.lines（若为空则把全文当单行）
   • 截断到 maxLines（只在最后一行做 ellipsis）
2. 清理规则（固定，确定性）：
   • 不输出 " …"：最后一行末尾空白先 trim
   • 不输出 "，…"/"。…"：若最后一行末尾是常见 TC 标点（，。！？；：、），则移除该标点再加 ellipsis
3. 宽度检查（12.3）：
   • 若提供测量能力且启用：
     • 重新测量 lastLine+ellipsisToken
     • 若超宽：按语言回退单位移除 token 再加省略号并重测
       • EN：按整词（token）
       • TC：按 grapheme（token）
   • 若测量不可用：不做重测，直接输出（meta.reason 仍保留）

说明：首版不做“避免截断 emotionPhrase 的整段前移/整段省略”，该策略可在后续结合 scoring 决策升级，但必须保持确定性。

4. 代码落位（客户端）

• client/src/features/textWrap/overflow/
  • types.ts
  • ellipsis.ts
  • fallback.ts（入口：applyOverflowFallback）
  • index.ts
  • __tests__/overflowFallback.test.ts

5. 测试计划（Vitest）

• SYSTEM_DEFAULT：lines 单行，meta.fallback_type=SYSTEM_DEFAULT
• CLIP：超过 maxLines 时截断行数
• ELLIPSIS：
  • 末尾空白去除，不输出 " …"
  • 末尾 TC 标点去除，不输出 "，…"
  • 测量超宽时按 token 回退直到不超宽（用 mock measureWidthImpl）

6. 完成定义（DoD）

• 三种 overflowMode 行为稳定且可解释
• ELLIPSIS 的清理与回退测量实现完毕（可测）
• 输出 meta 字段满足文档 12/14 的治理需求