add configurable gift menu overlays

Add tenant-scoped gift menu settings, catalog-backed triggers, infinite OBS rendering, and guard assets. Normalize legacy and protobuf gift values for blind-box, battery-tier, and transaction-aware matching.

docs/components/README.md

@@ -1,7 +1,7 @@
 # 组件开发指南
 
-组件是“消费所属账户事件流的独立功能实例”。当前内建 `danmaku_overlay`、 `song_request` 与
-`gift_effect`，未来礼物墙或统计组件也应使用同一套契约。
+组件是“消费所属账户事件流的独立功能实例”。当前内建 `danmaku_overlay`、`song_request`、 `gift_effect`
+与 `gift_menu`，未来礼物墙或统计组件也应使用同一套契约。
 
 ## 一个组件由什么组成
 
@@ -56,4 +56,5 @@ Handler 面向“业务事实”。例如点歌请求、礼物累计或审计写
 - 组件 WebSocket 不得暴露其他组件列表或控制 API。
 
 当前组件的具体行为见 [`danmaku-overlay.md`](danmaku-overlay.md) 与
-[`song-request.md`](song-request.md)、[`gift-effect.md`](gift-effect.md)。
+[`song-request.md`](song-request.md)、[`gift-effect.md`](gift-effect.md) 与
+[`gift-menu.md`](gift-menu.md)。

docs/components/gift-menu.md

@@ -0,0 +1,33 @@
+# 礼物菜单组件
+
+`gift_menu`
+是每个账户自动拥有且不可删除的单例组件。它把直播间礼物或大航海投喂映射为主播提供的内容说明，并以独立只读 token 输出透明 OBS 浏览器源。
+
+## 目录与触发器
+
+账户直播监听器调用 Bilibili `giftPanel/roomGiftList`
+并定时刷新按账户隔离的内存目录；控制台读取同一份缓存，也可以主动刷新。接口无需 Cookie，返回礼物 ID、名称、价格、静态图和 GIF。字段说明见
+[礼物 API 文档](https://github.com/pskdje/bilibili-API-collect/blob/main/docs/live/gift.md)。上游失败时保留最后一次成功目录。
+
+菜单项按顺序保存在经过后端校验的组件 settings 中，最多 100 项，支持：
+
+- 指定礼物 ID；事件缺少 ID 时以保存的名称降级匹配；
+- 舰长、提督或总督；
+- 指定礼物单价，单位为电池，例如 `150`。
+
+礼物事件先匹配指定礼物 ID（事件缺少 ID 时匹配名称）；命中后只高亮具体礼物。如果没有具体礼物命中，才按单价电池数回退匹配。组件只消费
+`live.gift`，不消费连击更新，避免重复触发。Bilibili 接口中的 `price` 是金瓜子而不是电池；后端统一按
+`price / 100` 换算（例如 `100` 金瓜子为 `1` 电池）。盲盒事件优先使用 `blind_gift.original_*`
+的盲盒 ID、名称与原价，不使用开出的奖品价值。对于 protobuf
+`SEND_GIFT_V2`，后端复用同一礼物管线，并优先使用非零 `discount_price`
+作为实际支付单价；`transaction_id` 用作稳定事件 ID。当前 V2
+schema 没有提供盲盒原始 ID/名称，因此这类事件可以按实际电池价值回退匹配，但不能保证命中具体盲盒条目。
+
+## OBS 行为
+
+每行横向展示图标、触发条件与主播自定义说明。行数、行高、文字比例、滚动速度、高亮时长和动效强度均可调整。仅当内容超过实际视口高度时滚动；渲染器复制三组菜单并在等价位置间无缝归一化，实现最后一行之后紧接第一行。
+
+命中时浏览器选择距离当前滚动位置最近的匹配副本，将它平滑对齐到视口第一行、暂停自动滚动并播放流金渐变与星花粒子。触发用户名称作为整行前景居中显示，覆盖原礼物图标和说明，并允许长名称换行。滚动器保留亚像素余量，低速设置也保持线性。低性能模式和系统减少动态效果偏好会关闭装饰粒子。舰长、提督和总督使用随前端打包的透明图标。
+
+第一版主题 `jade-banquet` 复用仓库内已有且记录许可的花枝 SVG；新增主题必须在 `giftMenuThemes.ts`
+注册稳定 ID、资源键和局部 CSS 变量。

docs/protocol.md

@@ -115,6 +115,10 @@ close 结束连接。
 `gift.animationUrl`
 作为流星主体，图片失效时必须使用本地星光占位。该组件不维护状态快照，重连后只展示新到达的实时事件。
 
+`gift_menu` 同样只消费一次性 `live.gift` 与 `live.guard.buy`。命中配置后投影为
+`gift-menu.triggered`，payload 包含 `itemIds`、`viewer` 和
+`sourceEventId`。一个特定礼物和一个同价电池规则可以同时命中多个菜单项；客户端应全部高亮，并滚动到第一个匹配项。未命中的投喂不会进入该组件通道。
+
 ## 表情分段
 
 `live.danmaku.payload.segments` 是判别联合：