更新换行算法和APP-PUSH

spec_kit/Text Wrap/modules/golden-tests/plan.md

@@ -0,0 +1,57 @@
+# golden-tests（技术计划）
+
+## 1. 计划目标
+
+建立可持续回归体系，覆盖：
+
+- **Golden Cases**：固定输入 → 固定输出（lines/wrappedText/meta），作为“可治理基线”
+- **性质测试（property tests）**：
+  - 确定性：同输入多次调用输出一致
+  - 近似单调性：availableWidth 变小不会让任一行变得更宽（同测量口径下）
+  - maxLines 不变差：maxLines 增加时至少不从可解变 overflow
+
+本模块产出测试数据与测试规则，不产出业务功能。
+
+## 2. 约束与策略
+
+### 2.1 测量可控
+
+- APP：使用稳定的测量 mock（例如 `width = text.length`）保证 CI 可运行
+- WIDGET：使用固定 profile 或 `widthMode=APPROX`（单位为 tokenCount/graphemeCount）
+
+### 2.2 Golden 的组织方式
+
+- 采用 TS fixture（便于类型校验与可读性）
+- Golden case 至少包含：
+  - `text/lang/context/availableWidth/maxLines/overflowMode/lineMode/configVersion`
+  - 期望：`expected.lines/expected.wrappedText`（可选 meta 断言）
+
+### 2.3 覆盖面（首版）
+
+首版优先覆盖“易回归且高价值”的样例集：
+
+- EN/TC 各若干条：短/长、含标点/无标点、含 emoji、含 shift/accum/self、极窄宽度
+
+> 说明：文档建议每种语言 20 条；首版先落最小可运行集合，后续迭代扩充但保持可解释与版本化。
+
+## 3. 测试实现结构（客户端）
+
+- `client/src/features/textWrap/golden/fixtures.ts`（Golden cases）
+- `client/src/features/textWrap/golden/__tests__/golden.test.ts`
+  - Golden 断言（lines/wrappedText）
+  - 性质测试（determinism/monotonic/maxLines）
+
+测试内暂时使用“测试版 wrapTextHarness”把已实现模块串起来：
+
+- normalize/tokenize（EN=tokenizeEN，TC=segmentGraphemes）
+- generateBreakpoints
+- search-engine-app / search-engine-widget
+
+待 integration 模块产出正式 `wrapText()` 后，再把测试入口切到正式函数（不改变期望数据）。
+
+## 4. 完成定义（DoD）
+
+- Golden fixtures + 测试可在 CI 一键运行
+- 至少包含 EN/TC 的基础样例与 3 类性质测试
+- overview 更新记录变更文件
+

spec_kit/Text Wrap/modules/golden-tests/spec.md

@@ -0,0 +1,57 @@
+# golden-tests（子模块规范）
+
+## 子模块名称
+
+golden-tests（Golden Cases 与性质测试）
+
+## 目标描述
+
+建立可持续的回归体系，保证换行算法满足：
+
+- 同输入同输出（确定性）
+- 跨端一致（在固定测量/宽度 profile 下）
+- 规则变更可控（通过 `configVersion` 回溯）
+
+本模块产出的是测试数据与测试规则，不产出业务功能。
+
+## 输入/输出定义
+
+### 输入
+
+- Golden Case 集合（建议 JSON/TS fixture）：
+  - `text`
+  - `lang`
+  - `context`
+  - `availableWidth`
+  - `maxLines`
+  - `fontSpec?`（APP）
+  - `constraints?`
+  - `overflowMode?`
+  - `configVersion`
+
+### 输出
+
+- 对每个 case 的期望输出：
+  - `expected.lines: string[]`
+  - `expected.wrappedText: string`
+  - 可选：`expected.meta.breaks`、`expected.meta.fallback_type/overflow_type/reason`
+
+并定义性质测试（property tests）：
+
+- **确定性**：同输入多次调用输出一致
+- **近似单调性**：`availableWidth` 变小不会让任一行变得更宽（在同测量模式下）
+- **maxLines 不变差**：`maxLines` 增加时至少不从可解变 overflow
+
+## 验收标准（可验证）
+
+- **覆盖度**：
+  - 每种语言至少 20 个样例：短/长、含标点/无标点、含 emoji、含 protectedPhrases、含 shift/accum/self、极窄宽度
+- **固定口径**：
+  - 测量可控：APP 用稳定的测量 mock（或固定字体与平台）；WIDGET 用固定 width profile
+- **CI 可运行**：在自动化环境可一键跑完（不依赖人工操作）
+
+## 依赖与关联
+
+- **依赖**：`core-contract`、`search-engine-*`、`scoring-tiebreak`、`overflow-fallback`
+- **被依赖**：`integration`（接入后验收也可引用 Golden）
+

spec_kit/Text Wrap/modules/golden-tests/tasks.md

@@ -0,0 +1,50 @@
+# golden-tests（任务清单）
+
+> 目标：建立 Golden Cases 与性质测试（determinism/monotonic/maxLines）回归体系，保证算法演进可控。
+
+## 0. 对齐与准备
+
+- [x] 阅读并对齐口径
+  - [x] 阅读 `spec_kit/Text Wrap/modules/golden-tests/spec.md`
+  - [x] 阅读 `spec_kit/Text Wrap/modules/golden-tests/plan.md`
+  - [x] 阅读 `设计说明文档/文档换行算法.md` 的 16.1/16.2 章节
+- [x] 创建客户端测试目录
+  - [x] 新建 `client/src/features/textWrap/golden/`
+
+## 1. Golden fixtures
+
+- [x] 新建 `client/src/features/textWrap/golden/fixtures.ts`
+  - [x] 定义 `GoldenCase` 类型（text/lang/context/availableWidth/maxLines 等）
+  - [x] 补充 EN/TC 基础样例集合（首版最小可运行）
+  - [x] 对每个 case 写入 `expected.lines/expected.wrappedText`
+
+## 2. 测试 harness（临时串联）
+
+- [x] 在测试中实现 `wrapTextHarness()`（仅用于测试）
+  - [x] normalizeWhitespace
+  - [x] EN tokenizeEN / TC segmentGraphemes
+  - [x] 使用“全断点集合”（1..N-1，首版避免候选裁剪影响）
+  - [x] APP：searchBestLayoutApp（测量 mock=length）
+  - [x] WIDGET：searchBestLayoutWidget（widthMode=APPROX，单位一致）
+
+## 3. Golden cases 测试
+
+- [x] 新建 `client/src/features/textWrap/golden/__tests__/golden.test.ts`
+  - [x] 遍历 fixtures，断言输出与 expected 完全一致
+
+## 4. 性质测试（property tests）
+
+- [x] 确定性：同输入运行多次输出一致
+- [x] 近似单调性：availableWidth 变小不会让任一行变得更宽（同测量 mock 下，用 width=string.length）
+- [x] maxLines 不变差：maxLines 增大时至少不从可解变 overflow（同测量 mock 下）
+
+## 5. 收尾
+
+- [x] 跑测试与类型检查
+  - [x] `npm test`
+  - [x] `npx tsc --noEmit`
+- [x] 将本 `tasks.md` 全部勾选完成
+- [x] 更新 `spec_kit/overview.md`
+  - [x] 标记 `golden-tests` 已完成（阶段性）
+  - [x] 写入变更文件清单
+