formatting and comments

docs/components/danmaku-overlay.md

@@ -0,0 +1,66 @@
+# `danmaku_overlay` 弹幕姬
+
+弹幕姬把一个租户直播源的互动事件投影为透明 OBS 消息墙。它是被动展示组件：不记账、不回复弹幕，也不把 WebSocket 当作持久化业务通道。
+
+## 订阅事件
+
+组件根据设置动态订阅：
+
+- 弹幕、进房、礼物与礼物连击、醒目留言、舰长、点赞、分享。
+- 关闭类别后，后端不为该组件投影对应事件，前端也会进行一次兼容性过滤。
+- 未归一化的 `live.unknown` 默认不进入弹幕姬。
+
+## 设置
+
+| 字段                     | 范围/单位   | 行为                       |
+| ------------------------ | ----------- | -------------------------- |
+| `fontScale`              | 50–300%     | 展开与收缩字号的统一比例   |
+| `maxVisible`             | 1–12        | 同时保留的消息卡数量       |
+| `collapseAfterSeconds`   | 2–120 秒    | 最新卡从展开态切换到紧凑态 |
+| `unfoldDurationMs`       | 200–5000 ms | 横向卷轴展开动画时间       |
+| `motionIntensity`        | 0–100%      | 卡片、流光与焦点动画强度   |
+| `particleCount`          | 0–12        | 每卡星花粒子数量           |
+| `particleSpeed`          | 25–300%     | 粒子动画速度               |
+| `lowPerformanceMode`     | boolean     | 关闭高成本动态效果         |
+| `highValueThreshold`     | 千分之一元  | 高价值礼物起点             |
+| `featuredValueThreshold` | 千分之一元  | 焦点礼物起点               |
+| `show*`                  | boolean     | 控制各事件类别订阅         |
+
+后端的 `OverlaySettings::sanitize` 是最终边界。控制台 range input 只改善交互，不能取代服务端校验。
+
+## 卡片生命周期
+
+1. 新事件插入队首，以卷轴动画横向展开。
+2. 用户名与内容在展开态分行显示，长内容完整换行。
+3. 新事件到达或超时后，旧卡变成紧凑态；内容不会隐藏。
+4. 紧凑态缩小字号并尽量压缩布局，但仍允许换行避免截断。
+5. 超过 `maxVisible` 的最旧卡才会离开队列。
+
+花纹由事件类型和事件 ID 的稳定 hash 选择。相邻卡会避开完全相同的款式；礼物连击更新沿用原卡片 key 和装饰，避免视觉跳动。
+
+## 礼物展示
+
+- `live.gift` 创建礼物卡；`live.gift.combo` 使用 `comboId` 更新同一张卡。
+- 元数据优先使用礼物目录中的静态图、GIF、币种和价格。
+- GIF 加载失败时降级为静态图片；静态图失败时隐藏图片但保留名称、数量和用户。
+- 普通、高价值和焦点礼物按 `totalPrice` 与两个阈值分级。
+- `priceCny` 只用于人类可读展示；整数 `totalPrice` 用于精确分级。
+
+## 弹幕表情
+
+文字和表情按 `segments` 顺序混排。表情 URL 来自消息本身或用户级表情目录补全；图片使用
+`no-referrer`，失败后显示原始表情文字。整条大表情可通过 `standalone` 使用更合适的尺寸。
+
+## OBS 自适应
+
+- 根背景完全透明，不存在 1920×1080 固定画布。
+- `ResizeObserver` 根据浏览器源实际宽高选择 `narrow`、`short` 或 `standard`。
+- 字号和间距使用 CSS custom properties 与 `clamp()`，OBS 自由缩放时不拉伸素材比例。
+- 建议从 `360×600`、`440×760`、`600×1080` 或 `720×320` 开始测试。
+- 低高度会减少视觉密度，但不会把仍在队列中的文字裁成省略号。
+
+## 测试页面
+
+控制台的事件测试直接构造 canonical
+`LiveEvent`，使用当前账户、source 和 component 走同一套订阅、handler、projection 与 EventHub。测试事件标记为
+`simulated=true`，不会发送到 Bilibili，也不会跨组件广播。