lxc-streamutils/apps/overlay/README.md

React 控制台与 OBS 前端

Vite 在 Docker build stage 编译本目录，最终静态文件由 Rust 同域托管。生产容器不包含 Node。

路由

路由	权限	作用
/control/	登录用户	直播源、组件、测试、设置和 OBS token
/control/invitations	system admin	创建/撤销绑定房间的邀请码
/control/login	匿名	用户名 + TOTP/恢复码登录
/control/register	匿名受邀用户	邀请码注册与 TOTP enrollment
/control/setup	首次部署	创建唯一 system admin
/obs/:publicId	component token	透明 OBS 浏览器源

main.tsx 在初始化控制台前先识别 OBS 路由，因此 OBS 不会注册 PWA 或请求账户 session。

文件职责

文件	职责
src/api.ts	same-origin fetch、错误模型和兼容性 normalizer
src/auth.tsx	passwordless login、TOTP QR 与恢复码
src/control.tsx	tenant component studio 和 system-admin 邀请码页面
src/overlay.tsx	WebSocket、消息队列、礼物/表情和 OBS 自适应渲染
src/pwa.tsx	install prompt、离线状态、显式更新和敏感状态 blocker
src/types.ts	sanitized API view model 与 overlay settings
pwa/control-sw.js	/control/ 静态壳层的缓存策略

Secret 与状态

• TOTP Secret、恢复码、邀请码和新 OBS 地址只保存在当前 React state。
• API normalizer 不把未知对象直接传播到组件。
• API mutation 离线时立即失败，不进入 Background Sync。
• PWA 更新在 dirty form 或一次性 secret 可见时被阻止。
• OBS token 从 URL fragment 读取，只在 WebSocket 第一帧发送。
• OBS 收到坏 JSON、坏图片或未知事件时局部降级，不让浏览器源崩溃。

PWA

manifest、start URL 与 Service Worker scope 均为 /control/。worker 使用 network-first HTML 和 cache-first build assets；/api/*、/obs/*、WebSocket 和用户数据永不缓存。每次 Vite build 把同一个 build ID 注入浏览器 bundle 与 worker，发现更新后等待用户确认激活。

格式化与构建

npm run format
npm run format:check
npm run docs:check
npm run build

npm run format 使用仓库根目录的 Prettier 配置，同时格式化 TypeScript、TSX、CSS、HTML、JSON、Markdown、Compose YAML 和项目文档。

组件协议与弹幕姬行为分别见：

• 实时协议
• 弹幕姬组件