old backend core lib

docs/components/danmaku-overlay.md

@@ -14,6 +14,7 @@
 
 | 字段                     | 范围/单位   | 行为                       |
 | ------------------------ | ----------- | -------------------------- |
+| `themeId`                | 主题 ID     | 选择已安装的完整视觉主题   |
 | `fontScale`              | 50–300%     | 展开与收缩字号的统一比例   |
 | `maxVisible`             | 1–12        | 同时保留的消息卡数量       |
 | `collapseAfterSeconds`   | 2–120 秒    | 最新卡从展开态切换到紧凑态 |
@@ -28,6 +29,20 @@
 
 后端的 `OverlaySettings::sanitize` 是最终边界。控制台 range input 只改善交互，不能取代服务端校验。
 
+## 主题
+
+主题同时封装配色、花纹素材、装饰变体、粒子组合与动画名称。当前内置主题为
+`jade-scroll`（“青玉花卷”）；控制台仍以选择框呈现，新增主题后无需改变设置交互或卡片队列。
+
+增加主题时需要同步完成三处注册：
+
+1. 在后端 `OverlayThemeId` 中增加稳定 ID，使未知主题无法进入数据库。
+2. 在 `apps/overlay/src/themes/` 增加主题定义，并注册到 `overlayThemes`。
+3. 提供主题使用的 CSS 动画和素材；不要在 `Card` 中加入按主题 ID 分支。
+
+旧组件没有 `themeId` 时会自动使用
+`jade-scroll`。WebSocket 收到未知 ID 时前端也会安全降级到该主题，以支持前后端滚动部署。
+
 ## 卡片生命周期
 
 1. 新事件插入队首，以卷轴动画横向展开。