docs(console-web): define browser tab state ownership

- distinguish Host-global, tab-shell, and Page-private state
- describe the cross-tab handshake and ordering guards
- document mounted and keep-alive Page synchronization rules
- record the BroadcastChannel fallback behavior
This commit is contained in:
Maofeng
2026-07-30 09:57:16 +08:00
parent 88a7fba0b0
commit 391901a71a
+24
View File
@@ -67,6 +67,30 @@ Host 会继续向隐藏的保活页面发送只读状态快照,但拒绝其管
立即显示最新 Runtime 状态,同时停用后的定时器不能意外触发注册、启停或 Deployment 立即显示最新 Runtime 状态,同时停用后的定时器不能意外触发注册、启停或 Deployment
操作。 操作。
## 浏览器 Tab 状态
同源普通 Tab 和已安装 PWA 窗口通过 `BroadcastChannel` 共享 Host 全局状态。状态按
所有权分为三层:
| 状态 | 跨 Tab | Host 到 Page | 生命周期 |
| ------------------------------------------ | -------- | --------------------- | --------------- |
| Runtime 快照、连接、API 地址、控制操作状态 | 始终共享 | 分发给已存在的 iframe | Host Tab |
| 当前路由、搜索、弹窗、toast、iframe LRU | 不共享 | 当前 Tab 自己管理 | Browser Tab |
| 页面筛选、表单、滚动位置、页面资源 | 不共享 | 不进入 Host | iframe document |
`src/host/tab-sync.ts` 使用独立版本的 Host Tab 协议:
- 每个 Host Tab 有随机 `sender` 和单调递增 `sequence`
- 新 Tab 发送 `hello`,已打开 Tab 立即返回当前 Host 全局状态。
- 所有 Host Tab 都可以发布,不依赖可能失效的 leader。
- 接收方拒绝自身消息、旧序列和字段不合法的消息。
- 应用远端状态时抑制本地广播 effect,避免 Tab 间回声循环。
- 浏览器不支持 `BroadcastChannel` 时退化为单 Tab,不影响页面和 API 操作。
Host 收到本地或远端全局状态后,只遍历当前 Tab 的 FrameCache。活动 iframe 和隐藏的
keep-alive iframe 会收到最新快照;从未打开或已被销毁的 Page 没有同步目标,创建并
发送 `ready` 后才取得当时的最新状态。Page 私有信号永远不会上传到 Host Tab channel。
## 开发 ## 开发
先在仓库根目录启动 Rust 后端: 先在仓库根目录启动 Rust 后端: