From 391901a71a95b240fa6a482a9ee6d321343e3ad6 Mon Sep 17 00:00:00 2001 From: Maofeng Date: Thu, 30 Jul 2026 09:57:16 +0800 Subject: [PATCH] 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 --- crates/wasmeld-console/web/README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/crates/wasmeld-console/web/README.md b/crates/wasmeld-console/web/README.md index 7d30e50..2973f0f 100644 --- a/crates/wasmeld-console/web/README.md +++ b/crates/wasmeld-console/web/README.md @@ -67,6 +67,30 @@ Host 会继续向隐藏的保活页面发送只读状态快照，但拒绝其管 立即显示最新 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 后端：