# search-engine-widget（子模块规范）

## 子模块名称

search-engine-widget（WIDGET 搜索器：Beam Search）

## 目标描述

在 WIDGET 场景实现确定性 Beam Search：

- 每一行扩展时只保留 TopK partial layouts（beam）
- 每步扩展断点数 M 受控（更强裁剪）
- 支持 width unknown / approx mode
- 最终选择 pos==N 的最优解；无解走 `overflow-fallback`

## 输入/输出定义

### 输入

- `tokens: Token[]`
- `breakpoints: Breakpoint[]`
- `availableWidth: number`（可为常量 profile）
- `maxLines: number`
- `context: 'WIDGET'`
- `measure: { widthMode: 'MEASURE' | 'APPROX' }`
- `config: { beamK: number; expandM: number }`

### 输出

- `bestLayout: { breaks: number[]; lines: string[]; wrappedText: string; meta?: { breaks: number[]; scoreTopTerms?: ... } }`

## 验收标准（可验证）

- **确定性**：beam 扩展、剪枝、排序规则固定；同输入同输出
- **性能约束生效**：
  - beamK 默认 5
  - 每步扩展 M 默认不超过 12
- **宽度不可用降级一致**：
  - 进入 approx mode 时 meta 标记 `reason=WIDTH_UNKNOWN`
  - 搜索仍可运行并输出可解释结果

## 依赖与关联

- **依赖**：`core-contract`、`width-measurement`、`breakpoint-candidates`、`scoring-tiebreak`、`overflow-fallback`
- **被依赖**：`integration`、`golden-tests`