# grapheme-segmentation（子模块规范）

## 子模块名称

grapheme-segmentation（TC 字符簇分割）

## 目标描述

在 TC（中文/繁中）场景下，统一“按 grapheme cluster（字符簇）切分”的实现口径，确保：

- 不拆分 surrogate pair（代理对）
- 不拆分 ZWJ 序列（家庭 emoji 等）
- 不拆分 variation selector（VS16 等）
- 不拆分 skin tone modifier（肤色修饰符）
- 不拆分 regional indicator flags（国旗）
- 覆盖组合字符（如 `é`）

优先使用平台级 segmentation（如 ICU / 系统 API / `Intl.Segmenter`），无库时提供最低可用兜底。

## 输入/输出定义

### 输入

- `text: string`（已完成空白归一化的文本，或原始文本）
- `mode: 'PREFERRED' | 'FALLBACK'`

### 输出

- `clusters: string[]`
  - 每个元素为一个 grapheme cluster（用于 TC tokens）
- `meta?: { strategy: 'PLATFORM' | 'INTL_SEGMENTER' | 'FALLBACK'; hadFallback: boolean }`

## 验收标准（可验证）

至少通过以下回归样例（每个样例都必须“单 token 不拆”）：

- `👨‍👩‍👧‍👦`
- `🇸🇬`
- `👍🏽`
- `😮‍💨`
- `é`

并满足：

- **确定性**：同输入同输出（clusters 顺序与内容完全一致）
- **边界一致**：任意换行断点只允许发生在 `clusters` 边界

## 依赖与关联

- **被依赖**：`core-contract`（TC token 生成）、`breakpoint-candidates`
- **不依赖其他模块**