# 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 对齐）

实现并导出：

```ts
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 更新记录变更文件