# integration（子模块规范）

## 子模块名称

integration（Home / Widget 接入）

## 目标描述

把 `wrapText()` 模块以一致参数口径接入到两端渲染链路中，并定义 UI 侧对 meta 的处理规则，确保：

- Home 与 Widget 使用同一套配置/词库/版本号（`configVersion`）
- 同场景下输出一致；不同测量能力导致差异时“可解释且可治理”
- SYSTEM_DEFAULT 的语义不被 UI 误用

## 输入/输出定义

### 输入

- Home（APP）侧输入：
  - `text/lang/availableWidth/maxLines/fontSpec/context='APP'`
  - 可选：`constraints/overflowMode/lineMode/configVersion/debug`
- Widget（WIDGET）侧输入：
  - `text/lang/availableWidth(profile)/maxLines/context='WIDGET'`
  - 可选：`constraints/overflowMode/configVersion/debug`

### 输出

- UI 渲染消费：
  - `lines[]`：逐行渲染或插入 `\n`
  - `wrappedText`：用于一次性渲染或日志/缓存
  - `meta`：用于调试、打点、兜底策略选择

## 验收标准（可验证）

- **参数映射一致**：
  - 两端对 `lang/context/availableWidth/maxLines/overflowMode/lineMode` 的默认值与映射一致
  - `configVersion` 必须随结果一起回传到 meta 或打点
- **UI 兜底语义正确**：
  - 当 `meta.fallback_type=SYSTEM_DEFAULT` 时：
    - UI 允许选择“交给系统排版”（例如不插入 `\n` 或忽略 `lines[]`）
    - 但不改变算法层返回值
- **缓存与复用**：
  - Home 可对同文案同参数缓存 `wrappedText/lines/breaks`
  - Widget 可对固定 profile 文案缓存结果（避免频繁计算）
- **回归可对齐**：
  - Golden Cases 在 Home 与 Widget（固定 profile）下可跑通并对齐预期

## 依赖与关联

- **依赖**：全部核心模块（`core-contract`、`breakpoint-candidates`、`search-engine-*`、`scoring-tiebreak`、`overflow-fallback`、`golden-tests`）
- **被依赖**：无（最终落地层）