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

overflow-fallback（任务清单）

目标：统一实现 ELLIPSIS/CLIP/SYSTEM_DEFAULT 的溢出与兜底语义（文档 12.x），输出稳定可解释的 meta。

0. 对齐与准备

• 阅读并对齐口径
  • 阅读 spec_kit/Text Wrap/modules/overflow-fallback/spec.md
  • 阅读 spec_kit/Text Wrap/modules/overflow-fallback/plan.md
  • 阅读 设计说明文档/文档换行算法.md 的 12.x/14 章节
• 创建客户端模块目录
  • 新建 client/src/features/textWrap/overflow/

1. 类型与对外接口

• 新建 client/src/features/textWrap/overflow/types.ts
  • 定义 OverflowMode = 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT'
  • 定义 FallbackType = 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT'
  • 定义 OverflowType = 'NONE' | 'ELLIPSIS' | 'CLIP'
  • 定义 OverflowReason（至少包含：NO_CANDIDATE/WIDTH_UNKNOWN/TOO_LONG/WIDOW/PARTICLE）
  • 定义 PartialLayoutInput：breaks + lines[{start,end,text?}]
  • 定义 ApplyOverflowFallbackInput/Result
• 新建 client/src/features/textWrap/overflow/index.ts
  • 统一导出 types 与入口 applyOverflowFallback()

2. ELLIPSIS 核心逻辑

• 新建 client/src/features/textWrap/overflow/ellipsis.ts
  • 实现 cleanLineBeforeEllipsis(line, lang)：
    • trim 末尾空白，避免 " …"
    • TC：若末尾是 ，。！？；：、，移除该标点，避免 "，…"
  • 实现 applyEllipsisToLastLine(...)：
    • 仅处理最后一行
    • EN 回退单位=整词；TC 回退单位=grapheme
    • 若提供测量能力：加省略号后必须重新测量，超宽则循环回退再测量
    • 若测量不可用：直接输出（确定性）

3. 入口：applyOverflowFallback

• 新建 client/src/features/textWrap/overflow/fallback.ts
  • 实现 applyOverflowFallback(input)：
    • overflow 判定：partialLayout 是否覆盖到 N
    • SYSTEM_DEFAULT（12.4A）：返回单行原文 + meta.fallback_type=SYSTEM_DEFAULT
    • CLIP：截断到 maxLines
    • ELLIPSIS：调用 ellipsis 逻辑
    • meta 输出：fallback_type/overflow_type/reason

4. 单测（Vitest）

• 新建 client/src/features/textWrap/overflow/__tests__/overflowFallback.test.ts
  • SYSTEM_DEFAULT 语义
  • CLIP 截断行为
  • ELLIPSIS 清理规则（不输出 " …"、不输出 "，…"）
  • ELLIPSIS 测量回退：mock measureWidthImpl，让超宽时按 token 回退直到不超宽

5. 收尾

• 跑测试与类型检查
  • npm test
  • npx tsc --noEmit
• 将本 tasks.md 全部勾选完成
• 更新 spec_kit/overview.md
  • 标记 overflow-fallback 已完成编码（阶段性）
  • 写入变更文件清单