Files

T

Maofeng ccad05fa5a docs(console): document Host-page and embedded build workflows

- explain the persistent Host and disposable iframe ownership model
- define SDK compatibility and PWA cache boundaries
- document independent debug servers and release embedding
- record Node, npm, NPM, and WASMELD_BUILD_WEB requirements
- update repository structure and startup commands

2026-07-30 09:22:55 +08:00

3.4 KiB

Raw Blame History

Wasmeld Console Web

管理面使用 Solid 和 Tailwind CSS v4。它不是传统单文档 SPA，而是由一个常驻 Host 文档和一个可替换 Page iframe 组成：

index.html / src/host
├── 导航、搜索、弹窗、通知
├── 管理 API 轮询和共享状态
└── page.html?view=<view>&instance=<n>
    └── src/pages/<view>

Host 始终只保留一个 iframe。切换一级页面时，Host 先发送 dispose，再销毁 iframe 并创建新的文档。页面所属的 Solid reactive owner、事件监听器、第三方 UI 库和页面局部缓存会随文档一起释放，避免长期导航后把各页面资源都留在同一个 JavaScript realm 中。

iframe 是资源生命周期边界，不是安全边界。Host 和 Page 都是 Wasmeld 自己构建并同源发布的可信代码；Wasm 服务的安全边界仍然在后端 Wasmtime Sandbox 和 Host Capability Registry 中。

src/host/          常驻 Host Shell 和 Host-owned dialogs
src/components/ui/ 跨页面复用的无业务 UI
src/lib/           API client、领域模型和纯函数
src/primitives/    Solid reactive primitives；Solid 不使用 React Hooks 约定
src/pages/         每个 iframe 页面一个目录和独立懒加载 chunk
src/sdk/           Host/Page postMessage 协议与两侧 client
src/styles/        Tailwind v4 theme 和共享组件样式

src/sdk/protocol.ts 中的 SDK_VERSION 是文档间协议版本。新增可选消息可以保持原版本；删除字段、改变字段语义或产生不兼容状态时必须升级版本，并让两侧同时发布。消息接收端同时检查 origin、source、channel 和 version，不接收任意窗口的控制命令。

开发

先在仓库根目录启动 Rust 后端：

cargo +stable run -p wasmeld-console

再启动 Web 开发服务器：

cd crates/wasmeld-console/web
npm ci
npm run dev

打开 http://127.0.0.1:3000。Vite 开发环境默认连接 http://127.0.0.1:8080；设置页可以覆盖该地址。Debug Cargo 构建不会调用 npm，因此 Rust 与 Web 的增量开发互不阻塞。

常用检查：

npm run format:check
npm run lint
npm test
npm audit --audit-level=high

发布与嵌入

Release 构建由 ../build.rs 自动执行：

cargo +stable build --release -p wasmeld-console

构建脚本使用 npm ci 严格读取 package-lock.json，将 Vite 输出写入 Cargo OUT_DIR，再由 Rust include_dir! 嵌入可执行文件。发布机器必须提供 Node.js 22.13+ 和 npm。可以用 NPM=/absolute/path/to/npm 指定 npm；只有需要调试嵌入行为时，才在非 Release 构建中设置 WASMELD_BUILD_WEB=1。

Release 管理 Listener 同时服务 /、/page.html、静态资源、PWA manifest 和 /sw.js。资源路径必须精确存在，不做 SPA fallback。带内容哈希的 assets/ 使用长期 immutable 缓存，其它入口使用 no-cache。

PWA 边界

一个 Host-owned service worker 管理整个应用：

构建时预缓存 Host、Page 和带哈希静态资源。
文档请求使用 network-first，离线时分别回退到 index.html 或 page.html。
/api/* 和 /healthz 永远走网络，不缓存运行状态或管理操作。
新 worker 激活时删除旧的 wasmeld-* 缓存。

PWA 只提供安装和静态壳离线能力。没有后端连接时页面会显示离线状态，不会用旧 API 响应伪造 Runtime 状态。

3.4 KiB Raw Blame History Unescape Escape

Wasmeld Console Web

目录

开发

发布与嵌入

PWA 边界

3.4 KiB

Raw Blame History