mindfulness/spec_kit/Text Wrap/modules/search-engine-widget/spec.md

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