add full-screen gift effects

docs/components/README.md

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

docs/components/gift-effect.md

@@ -0,0 +1,30 @@
+# 全屏礼物特效组件
+
+`gift_effect` 是每个账户自动拥有且不可删除的单例组件。它消费账户级直播源中的 `live.gift` 和
+`live.guard.buy`，使用独立只读 token 作为透明 OBS 浏览器源；不订阅
+`live.gift.combo`，避免一次连击重复触发完整特效。
+
+## 展示行为
+
+普通礼物从视口左侧生成一组带青玉、金色星尘拖尾的流星，礼物图片或 GIF 是流星主体，并从右侧完全飞出。原始价值按
+`highValueThreshold` 和 `featuredValueThreshold`
+分为普通、高价、特别高价三档，每档分别设置流星数量、基准尺寸和飞行速度。图片加载失败时使用内置星光图形，不依赖外部主题素材。
+
+舰长、提督或总督使用同一个 `live.guard.buy`
+路径，临时显示不透明星河、闪耀粒子、身份和用户昵称。多个普通礼物可并发；大航海展示选择最新事件。
+
+## 尺寸与性能
+
+OBS 建议从 `1920×1080` 开始，但渲染器没有固定画布。`ResizeObserver`
+按浏览器源实际宽高缩放流星，宽屏、竖屏或自定义分辨率都保持全视口透明。控制台可调整：
+
+- 三档数量、尺寸和速度；
+- 拖尾强度和最大并发特效数；
+- 大航海星数和全屏持续时间；
+- 低性能模式（限制粒子和流星数量）。
+
+## 扩展主题
+
+后端设置的 `themeId` 使用稳定 kebab-case ID。前端主题统一在 `apps/overlay/src/giftThemes.ts`
+注册颜色、动效标识和本地化资源键；主题 CSS 只作用于
+`.gift-effect-overlay`，不得改变页面根背景或控制台。新增主题时同时扩展 Rust/TypeScript 类型、设置迁移、两种语言资源和降级测试。

docs/protocol.md

@@ -110,6 +110,11 @@ close 结束连接。
 `live.gift` 与 `live.gift.combo` 不是两笔礼物。需要持久化计数的组件通常只消费
 `live.gift`；连击事件用于更新同一张视觉卡片。
 
+`gift_effect` 只订阅 `live.gift` 与 `live.guard.buy`。礼物档位由 sanitized settings 中的
+`highValueThreshold` 和 `featuredValueThreshold` 决定；浏览器使用 `gift.imageUrl` 或
+`gift.animationUrl`
+作为流星主体，图片失效时必须使用本地星光占位。该组件不维护状态快照，重连后只展示新到达的实时事件。
+
 ## 表情分段
 
 `live.danmaku.payload.segments` 是判别联合：