mindfulness/spec_kit/Text Wrap/modules/width-measurement/spec.md

width-measurement（子模块规范）

子模块名称

width-measurement（宽度测量与降级）

目标描述

提供统一的宽度测量接口与缓存策略，并定义“宽度不可用”时的确定性降级行为（approx mode），确保 APP 与 WIDGET 在测量能力差异下仍能：

• 保持搜索/评分流程可运行
• 输出可解释（meta 打点）
• 性能稳定（缓存与上限）

输入/输出定义

输入

• context: 'APP' | 'WIDGET'
• fontSpec?: { fontSize: number; fontWeight?: string; fontFamily?: string }
• measureWidth?: (text: string, fontSpec) => number（可选注入）
• text: string
• slice?: { start: number; end: number }（可选：段落切片测量）

输出

• width: number | null
  • 当不可用/失败时返回 null（触发 approx mode）
• meta?: { isApprox: boolean; reason?: 'WIDTH_UNKNOWN' | 'MEASURE_FAILED' }

并提供缓存约定（逻辑输出）：

• 字符串测量缓存 key：(text, fontSpecKey, contextProfile)
• 切片测量缓存 key：(start, end, fontSpecKey, contextProfile)

验收标准（可验证）

• 测量一致：在 APP 注入 measureWidth 时，同一输入重复测量命中缓存（不会重复计算）
• 失败降级：measureWidth 缺失/抛错/返回 NaN 时：
  • 输出 width=null
  • meta 标记 isApprox=true 且 reason 可追踪
• approx mode 口径一致：
  • EN：宽度近似值使用 wordCount
  • TC：宽度近似值使用 charCount（或 grapheme 数）
• 确定性：相同输入在相同 contextProfile 下，测量与降级行为一致

依赖与关联

• 被依赖：search-engine-app、search-engine-widget、overflow-fallback
• 依赖：core-contract（fontSpecKey 规范化、切片文本重组）