mindfulness/spec_kit/Text Wrap/spec.md

Text Wrap（大需求总览）

本文件只保留高层背景、总览与模块拆分；各子模块可独立实现与验收。 详细算法口径以 设计说明文档/文档换行算法.md（v1.2.1）为准。

1. Overview（背景/目标/非目标）

Home 页面与 iOS 桌面小组件（Widget）都会展示“情绪文案/正念短句”。若依赖系统默认换行，会出现不可控、不可解释、跨端不一致的问题。

本需求要求把“文案换行算法”从 UI 组件中独立成一个可复用模块，用于：

• Home 页面文案渲染
• Widget 文案渲染（允许测量能力不同，但规则与决策必须一致）

目标

• 确定性：同输入（含配置版本）必定同输出
• 跨端一致口径：索引体系、断点定义、关键词命中与 tie-break 规则完全一致
• 可治理：支持 debug meta、线上打点、Golden Case 回归
• 可复用：算法作为纯函数核心，UI 仅消费 lines[]/wrappedText/meta

非目标

• 不做语义理解/情绪识别/机器学习
• 不做通用排版引擎
• 不承诺 Widget 场景做到像 App 一样的像素级测量（Widget 可使用估算/常量）

2. 对外接口（统一口径）

模块对外暴露 wrapText()（纯函数）：

wrapText({
  text: string,
  lang: 'TC' | 'EN',
  availableWidth: number,
  maxLines: number,
  context: 'APP' | 'WIDGET',
  fontSpec?: { fontSize: number; fontWeight?: string; fontFamily?: string },
  overflowMode?: 'ELLIPSIS' | 'CLIP' | 'SYSTEM_DEFAULT',
  lineMode?: 'AUTO' | 'FIXED',
  constraints?: {
    protectedPhrases?: string[];
    forbiddenBreakRanges?: Array<{ start: number; end: number }>;
  },
  configVersion?: string,
  debug?: boolean
}) => {
  lines: string[];
  wrappedText: string;
  meta?: {
    configVersion?: string;
    fallback_type?: 'NONE' | 'RELAX_RULES' | 'SYSTEM_DEFAULT';
    overflow_type?: 'NONE' | 'ELLIPSIS' | 'CLIP';
    reason?: 'NO_CANDIDATE' | 'WIDTH_UNKNOWN' | 'WIDOW' | 'PARTICLE' | 'TOO_LONG';
    breaks?: number[];
    scoreTopTerms?: Array<{ key: string; delta: number; detail?: any }>;
  }
}

3. 模块拆分（modules）与依赖关系

3.1 modules/ 目录结构

spec_kit/Text Wrap/
├ spec.md
└ modules/
   ├ core-contract/spec.md
   ├ grapheme-segmentation/spec.md
   ├ width-measurement/spec.md
   ├ breakpoint-candidates/spec.md
   ├ scoring-tiebreak/spec.md
   ├ search-engine-app/spec.md
   ├ search-engine-widget/spec.md
   ├ overflow-fallback/spec.md
   ├ golden-tests/spec.md
   └ integration/spec.md

3.2 模块职责概览

• core-contract：EN/TC token 索引体系、文本重组、EN 关键词命中“全词等值”、配置/版本化与确定性比较口径 ✅
• grapheme-segmentation：TC 字符簇分割的推荐实现与无库兜底 + 回归样例 ✅
• width-measurement：测量接口、缓存、宽度不可用降级（approx mode）与打点 ✅
• breakpoint-candidates：候选断点生成（PUNCT/SPACE/BALANCE）、去重排序、约束过滤与规模上限 ✅
• scoring-tiebreak：评分项顺序、可解释 breakdown、tieKey/tie-break 规则与整数分/EPS ✅
• search-engine-app：APP 场景 DP + TopK 的确定性实现
• search-engine-widget：WIDGET 场景 Beam Search 的确定性实现
• overflow-fallback：ELLIPSIS/CLIP/SYSTEM_DEFAULT 语义、ellipsis 细则与兜底链路
• golden-tests：Golden Cases 与性质测试（确定性、近似单调性、maxLines 不变差）
• integration：Home/Widget 接入约定（参数映射、渲染策略、fallback 语义对齐）

4. 实现顺序（推荐）

目标是“先锁口径，再做搜索与评分，再做溢出与回归”，避免后期重构。

1. core-contract
2. grapheme-segmentation
3. width-measurement
4. breakpoint-candidates
5. scoring-tiebreak
6. search-engine-app
7. search-engine-widget
8. overflow-fallback
9. golden-tests
10. integration