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

overflow-fallback（子模块规范）

子模块名称

overflow-fallback（溢出与兜底）

目标描述

统一定义“无解/溢出”时的行为与返回语义，确保：

• APP 与 WIDGET 在无法覆盖全文时表现一致且可解释
• ELLIPSIS 的字符、清理规则与再次测量约束统一
• SYSTEM_DEFAULT 的返回语义明确（算法层不擅自改变 UI 行为）

输入/输出定义

输入

• tokens: Token[]
• partialBest?: Layout（搜索器找到的最佳 partial 或 best effort）
• overflowMode: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT'
• availableWidth: number
• maxLines: number
• lang: 'TC' | 'EN'
• context: 'APP' | 'WIDGET'
• ellipsisToken: string（推荐 "…"，必须配置化）
• measureWidth?: fn（用于“加省略号后再测量”）

输出

• result: { lines: string[]; wrappedText: string; meta: { fallback_type: 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT'; overflow_type: 'NONE' | 'ELLIPSIS' | 'CLIP'; reason: string } }

验收标准（可验证）

• overflow 判定一致：
  • 搜索无法在 <=maxLines 覆盖到结束边界 N，即为 overflow
• ELLIPSIS 规则一致：
  • 仅处理最后一行
  • 加省略号后必须再次检查不超宽（必要时回退移除 token 再加省略号）
  • EN 回退单位为整词；TC 回退单位为 grapheme
  • 清理规则：不输出 " …"；不输出 "，…"/"。…"（按配置决定是否移除末尾标点再加省略号，但必须固定）
• SYSTEM_DEFAULT 语义一致：
  • 仍返回 lines/wrappedText
  • 仅在 meta 标记 fallback_type=SYSTEM_DEFAULT
  • UI 可依据 meta 决定是否完全交给系统排版
• 确定性：同输入同输出（含 meta）

依赖与关联

• 依赖：core-contract（重组）、width-measurement（测量/降级）、scoring-tiebreak（避免截断短语的策略可复用评分）
• 被依赖：search-engine-app、search-engine-widget、integration、golden-tests