ArtPlayer/refactor/changes/2026-09-16-SITE-05-search.md

# SITE-05 搜索交互与依赖修复

起点：`61fe8deb5923de72740bce00e0734dcc93a05cb2`。这是 SITE-05 的实施检查点，
尚未完成全站链接、全部搜索锚点、编辑器及声明注入验收，不进入正式复盘。

## 实际问题与修改

旧搜索能返回结果，不能把 flexsearch peer 警告写成搜索已失效。浏览器复现 Enter
导航后触发表单原生提交，URL 多出 `?` 且整页重载；有输入时 Escape 无法关闭。
新增回归在未修复构建上中英文各失败一次。保留当前第三方插件的索引、结果 URL、
模板和 CSS，通过包内 `build/search.ts` 在 Vue 编译前修复交互：取消表单默认提交，
按实际可见结果次序导航；无结果 Enter 不跳转；查询变化重置选择；Escape 关闭并
恢复按钮焦点。输入法组合键不触发选择，输入框等待 Vue DOM 更新再聚焦。
快捷键监听有卸载清理，异步索引导入有卸载守卫；加载前输入不读取未初始化索引。
卸载守卫属于本次源码修正，当前浏览器用例没有单独模拟组件卸载，不扩大验证结论。

适配器校验安装包组件的完整 SHA-256，统一 CRLF/LF 后要求每项补丁恰好匹配一次。
升级第三方必须人工复核补丁，不能只改哈希。既有第三方代码及署名留在原包，不复制
到自有源码、不修改 node_modules。首次实现遗漏 CRLF 匹配，随后聚焦回调排在 DOM
更新之前，均被测试捕获并修复；两个失败阶段的完整报告保留。最终没有放宽断言、
超时或加自动重试。播放器运行时、声明及公共分发 API 不变。

文档站 devDependency flexsearch 从 0.8.158 对齐到 0.7.43，满足插件的 ^0.7.31；
插件自身内置索引实现，peer 对齐不冒充索引或中文分词改进。原有精确 token 行为
保留，不承诺任意中文子串匹配。VitePress 未启用的托管 Algolia/search-insights
依赖仍有 peer 警告；本地搜索验收不代表托管提供方可用，不为消除警告引入服务依赖。

Yarn workspace add 曾忽略根级 dom-webcodecs resolution，根级 install 恢复了已批准
的 0.1.19；一次写锁文件出现 UNKNOWN，原命令重跑成功。最终锁 diff 仅 flexsearch
一个直接选择器，未带入无关 SDK 类型变化。唯一根 yarn.lock、根 resolution 保留。

## 验证与边界

Node 24.21.0 / Yarn 1.22.22：

- 根级冻结安装退出 0，锁文件 SHA-256 前后一致；严格工具链检查通过。
- `yarn build:docs` 通过：VitePress 10.34 秒、Yarn 12.03 秒，生成文件通过构建更新。
- `yarn test:site-build`：8/8，0 失败/跳过；包含实际 Vue 编译和第三方输入漂移拒绝。
- `yarn typecheck:docs-tools` 与修改源文件/测试的只读 ESLint 通过。
- `yarn test:browser:source document-search.spec.js document-site.spec.js --workers=1`：
  三引擎、中英文共 12/12，52.27 秒，0 失败/跳过/重试。覆盖鼠标精确语言 URL、
  英文 API 和中文完整 token、键盘选择/循环、Escape/焦点、无结果及无整页重载。
- 文档 inventory、demo 路径及风险登记校验通过；外部 HTTPS 在上述浏览器测试中
  隔离，结果不代表广告服务、真机或完整播放器验收。

结构化记录见 [site05-search.json](../baselines/site05-search.json)。包 README 已维护
适配器地图、版本、升级约束和重跑命令。SITE-05 由 todo 转 doing；SITE-07 字体来源
核实从本地功能检查的启动依赖移为 SITE-06 最终交付的直接依赖，未取消许可门槛。
任务仍 225 done /22 doing /38 todo。共享锁和测试变更使旧候选输入指纹过期，REL-02
需在本批站点工具工作稳定后刷新 21 库候选，不沿用旧 build 通过结论批准发布。
下一步继续全量链接、搜索锚点、编辑器与声明验证。回退本提交恢复搜索行为、peer、
生成文件及任务依赖。未推送、部署或发布。