# 浏览器 Marqdo(WASM 解释器)设计 > 2.7.0 维护说明:独立的 browser-hello 与 browser-media 演示已删除。下文保留既有能力设计与宿主边界,当前可运行工程使用 browser-app;底层计数器冒烟夹具位于 tests/wasm/counter.mq.md。Canvas、音频等仍是 lib/browser 的宿主能力,不宣称当前 browser-app 演示包含这些交互。 | | | |---|---| | 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 | | 日期 | 2026-09-01 | | ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) | | 路线图 | [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) | | 相关 | [ext-web.md](ext-web.md) · [bytecode.md](bytecode.md) · [web-assets-and-images.md](web-assets-and-images.md) · [table-cell-expressions.md](table-cell-expressions.md) | --- ## 0. 一句话 **源码只有 `.mq.md`;浏览器跑与 CLI 同构的 Marqdo VM(WASM);JS 只做宿主桥与加载器,不做业务语言。** --- ## 1. 目标与非目标 ### 1.1 目标 | # | 目标 | |---|------| | G1 | 浏览器内执行合法 `.mq.md`(至少 `# main` + 打印/绑定/分支/循环/表/调用) | | G2 | 与主机 **tree**(及后续 **bytecode**)金样在共享子集上 stdout/返回值一致 | | G3 | 作者用 GFM 表声明交互(选择器 / 事件 / 调用),对称于 `样式装配` | | G4 | 仓库源码树可不含业务 `.js`;允许提交或由工具生成 `marqdo.wasm` + 官方 loader | | G5 | `import lib/…` 在浏览器可用(嵌入式 `lib/` 或打包进 wasm) | ### 1.2 非目标(本波 / C0–C3) | # | 非目标 | |---|--------| | N1 | 在浏览器复刻 axum、`web_listen`、SQLite 服务端、admin UI | | N2 | `plugin.load` 加载原生 `.so` / 浏览器内 dlopen | | N3 | 把整站 `plugins/web` ABI 原样搬进 WASM | | N4 | 把 `.mq.md` 编译成独立机器码 WASM(异于「解释器上 WASM」) | | N5 | 强制内容站必须加载 WASM(纯 SSR 站可继续零客户端逻辑) | --- ## 2. 架构 ``` ┌─────────────────────────────────────────────────────────┐ │ Page (HTML shell from ext/web SSR or static) │ │ ┌──────────────┐ ┌─────────────────────────────────┐ │ │ │ DOM / CSS │ │ Official JS loader (thin) │ │ │ └──────▲───────┘ │ - WebAssembly.instantiate │ │ │ │ bridge │ - marqdo_run_source / on_event │ │ │ │ └──────────────┬──────────────────┘ │ │ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ │ marqdo.wasm │ │ │ │ │ parse → load → │ │ │ └──────────────│ Interpreter | Vm │ │ │ host_dom_* │ HostContext(browser)│ │ │ host_fetch_* │ embedded lib/ │ │ │ └─────────────────────┘ │ └─────────────────────────────────────────────────────────┘ Server (unchanged): marqdo run / plugins/web (axum) — SSR, DB, auth, full site ``` **原则:** 一套语言语义;**HostContext 分型**(`native` vs `browser`),不是两套语法。 --- ## 3. 与现有流水线对齐 主机今日(见 `src/lib.rs`): ``` path → fs::read → load_module → Interpreter|Vm → HostContext(native) ``` 浏览器目标: ``` source: &str (+ optional import map) → load_module_from_memory → Interpreter|Vm (capture stdout) → HostContext(browser caps) → { ok, stdout, value_json, error } ``` 公共库 API(C0/C1 必须落地): | API | 职责 | |-----|------| | `run_source(source, opts) -> Result` | 无路径入口;cwd/fs_root 虚拟 | | `RunOptions` 浏览器默认 | `allow_fs_write=false`, `allow_exec=false`, `allow_net=false`(net 经显式 bridge 再开) | | `load` 导入 | `lib/**` → `embedded_lib`;用户模块 → JS 注入的 `HashMap` | 后端优先级: 1. **C1:tree**(与默认 CLI 一致,调试简单) 2. **C2+:bytecode** 可选(体积/性能;金样双后端) --- ## 4. Cargo / 制品布局 ### 4.1 Feature 门(核心 crate `marqdo`) | Feature | 默认(native) | `wasm-core` | 作用 | |---------|----------------|-------------|------| | `cli` | on | off | `main` / clap 仅 bin | | `view` | on | off | `tiny_http` 文档浏览器 | | `net-host` | on | off | `ureq` HTTP 客户端 | | `plugin-host` | on | off | `libloading` 原生插件 | | `exec-host` | on | off | `std::process` / foreign | | `fs-host` | on | off | 真实磁盘读写(可读可后续经 VFS 桥) | | `wasm-core` | off | on | 浏览器子集编译开关 | `wasm32-unknown-unknown` 构建:**不得**链接 `libloading`、`ureq`、`tiny_http`、TTY `libc`。 ### 4.2 包 | 路径 | 角色 | |------|------| | `marqdo`(根) | 核心;feature-gate | | `crates/marqdo-wasm` | `cdylib`:`mq_*` ABI + `js/marqdo-bridge.js` | | `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) | | `examples/browser-app/` | 静态页 + wasm 冒烟 | | `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 | 发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。 --- ## 5. 宿主能力矩阵 | 能力 | Native | Browser C1 | Browser C3+ | |------|--------|------------|-------------| | `print` / 捕获 stdout | ✓ | ✓ → 可镜像 `console` | ✓ | | `input` | stdin / preset | **仅 preset / JS 喂入** | 可选 prompt 桥 | | builtins / 表 / 算术 | ✓ | ✓ | ✓ | | `lib/math` `lib/json` `lib/collection` | ✓ | ✓(embedded) | ✓ | | `lib/fs` 真磁盘 | ✓ | ✗ 明确报错 | 可选 OPFS/VFS 桥 | | `lib/net` ureq | ✓ | ✗ | `fetch` 桥(异步模型见 §7) | | `plugin.load` | ✓ | ✗ | ✗(改 L1 浏览器专用) | | `exec` / foreign | ✓ | ✗ | ✗ | | DOM / 事件 | ✗ | stub | **交互装配** | | `sleep` | thread | 0 或 JS timer(异步) | timer | 错误策略:**显式失败**(诊断字符串含 `unavailable in browser wasm`),禁止静默空成功。 --- ## 6. 交互装配(C3,对称样式装配) ### 6.1 作者面(示例) ```markdown --- import: json: lib/json.mq.md --- # main *`count` = 0* `wire` = | @ | 选择器 | 事件 | 调用 | |---|--------|------|------| | 1 | "#bump" | click | bump | **`wire`** ## bump *`count` = count + 1* *`label` = > str count* *`patch` = > json.set map=None key="#count" value=label* **> json.set map=None key="set_text" value=patch** ``` `# main` 的返回值是 **wire 表**(`@` 行向记录列表)。Loader 调用 `mq_boot`,再 `wireEvents`。 ### 6.2 桥约定 | 步骤 | API | |------|-----| | 启动 | `mq_boot(source)` → `{ ok, value }`;`value` = wire 列表或 `{ wire: [...] }` | | 事件 | Loader `addEventListener` → `mq_call(fn, {"event":"click"})` | | 回写 | 返回 Map 可含 `set_text`: `{ "#sel": "text" }`(仅 `textContent`) | 行键名认:`选择器`/`selector`、`事件`/`event`、`调用`/`call`。 含 `/` 的 CSS 等单元格仍 **引号优先**(见 [table-cell-expressions.md](table-cell-expressions.md))。 L1 `浏览器.交互装配`(ext)可后置;C3 以 bridge + 返回 wire 表即可验收。 --- ## 7. 异步模型(C4) 锁定:[ADR 0003](../adr/0003-browser-async-effects.md)。 处理器返回 Map 可含(与 `set_text` 并列): | 字段 | 含义 | 完成后 `mq_call` 实参 | |------|------|----------------------| | `fetch` | `{ url, method?, then, headers?, body? }` | `{ ok, status, body, error? }` | | `after` | `{ ms, then }` | `{ ok: true }` | Bridge:`applyEffects(exports, value)` — 先 DOM,再调度异步;**不**在 WASM 内阻塞。 示例见 `examples/browser-app/static/app.mq.md`。 --- ## 8. 安全 | 项 | 规则 | |----|------| | 默认能力 | 无磁盘写、无 exec、无任意 net | | 源码来源 | 同源或构建时嵌入;不默认 `eval` 远程不可信脚本除非站点显式开启 | | DOM | 仅经装配表/白名单 API;不暴露任意 `innerHTML` 字符串执行第三方脚本 | | CSRF / Cookie | 浏览器 Marqdo **不替代**服务端鉴权;cookie 仍走 HTTP | --- ## 9. 与 `ext/web` 分工 | 层 | 负责 | |----|------| | 服务端 `plugins/web` | 路由、DB、会话、SSR HTML、样式/头/图装配 | | 页面壳 | `头装配` 挂 `module` → `marqdo-bridge.js`;`static` 提供 `.wasm` | | 浏览器 L1 | `客户端挂载` / `client_embed`;效应约定见 ADR 0003 | | 核心 / crate | `run_source`、`BrowserSession`、`marqdo-wasm` ABI | 挂载示例: ```markdown `头` = | 关系 | 地址 | |------|------| | module | /static/marqdo-bridge.js | *p = > page.头装配 表=头* ``` ```bash marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js # app.static dir=static ``` 业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-app/`)。 --- ## 10. 测试与验收 | 级 | 内容 | |----|------| | 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 | | 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 | | 浏览器冒烟 | `examples/browser-app`:按钮点击 → Marqdo 函数 → 改 DOM 文本 | | 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` | --- ## 11. 文档与技能同步 - ADR 0002、本文、路线图 C0–C5。 - `.cursor/skills/marqdo/SKILL.md`:补充「浏览器 WASM / 交互装配 / 引号 CSS」。 - `CHANGELOG`:Unreleased 记录设计锁定与各 C 完成项。 --- ## 12. 风险 | 风险 | 缓解 | |------|------| | wasm 体积过大 | `release-wasm` profile(`opt-level=z` + LTO + strip);`marqdo wasm build` 打印 KiB,有则跑 `wasm-opt -Oz` | | 异步拖垮语言 | ADR 0003 效应表;不阻塞 WASM | | Feature-gate 伤 native | 默认 features = 今日行为;CI 全绿再合 | | 作者误以浏览器替代服务器安全 | 文档强调鉴权在服务端 | | 会话要 bytecode | **未做**:`BrowserSession` 固定 tree(缺 entry-env invoke);`run_source` 已支持 bytecode | --- ## 14. C5 硬化(已落地) | 项 | 状态 | |----|------| | `profile.release-wasm` + `marqdo wasm build` 体积报告 | done(~0.9 MiB) | | 可选 `wasm-opt` | done | | `run_source` bytecode 金样 | done | | 规范 bridge + 构建拷贝 | done(`crates/marqdo-wasm/js/`) | | Node ABI 冒烟 | done(`tests/wasm`) | | 站点 `头装配` / L1 `client_embed` | done | | 会话 bytecode / view 断点复用 | **非本版目标** | --- ## 16. 路线 D — 作者零 JS(Active) 路线图:[browser-wasm-d.md](../roadmap/browser-wasm-d.md)。 **原则:** 业务与交互 100% `.mq.md`;`marqdo-bridge.js` 仅宿主胶。作者仓库可不含自写 `.js`。 ### 16.1 一键挂载 | API | 含义 | |-----|------| | `mount({ wasmUrl, source \| sourceUrl, … })` | `loadWasm` → `boot` → `wireEvents` → 初始效应 | | `script[data-mq-source-url]` / `data-mq-wasm` | 模块脚本属性自启 | | `#marqdo-boot` | `application/json` 配置块 | | `data-mq-playground` | 官方 playground(`#src,#run,#out`),仍非业务 JS | `ext/web`:`client_embed` / `客户端挂载` 参数 `bridge`、`wasm`、`source`、`boot`(默认 true)。 ```bash marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js # app.static dir=static # intro 或主区嵌入 > web.client_embed source="/static/client.mq.md" ``` ### 16.2 DOM / 表单效应(D3) 与 `set_text` / `fetch` / `after` 并列(白名单;**默认无**任意脚本注入): | 字段 | 作用 | |------|------| | `set_text` | `textContent` | | `set_value` | input/textarea/select 的 `value` | | `set_attr` | 属性;值为 `null`/`false` 则 `removeAttribute` | | `set_class` | `className` 字符串 | | `toggle_class` | `{ "#sel": "cls" }` 切换 class | | `set_html` | **仅**键前缀 `#trusted` 的选择器才写 `innerHTML`;其它键忽略 | Wire 行可选 `值选择器` / `value_from`:事件触发时把该节点内容写入实参 `value`。 事件实参默认含:`event`、`value`、`checked`、`id`(来自 event.target);`submit` 另含 `fields` 表单字典。 L1:`web.dom_patch` / `网页.DOM补丁` 合并效应键;`web.text_patch` / `网页.文本补丁` 快捷 `set_text`。 ### 16.3 非目标(D) | # | 非目标 | |---|--------| | D-N1 | 用 Marqdo 重写 bridge 自身 | | D-N2 | 作者手写业务 JS / TS(官方桥内机制允许) | | D-N3 | ~~开放无前缀的 set_html~~(E 已允许任意选择器;内容由 MQ 产出) | --- ## 17. 路线 E — 前端能力补齐(Active) 路线图:[browser-wasm-e.md](../roadmap/browser-wasm-e.md)。 **原则:** 唯一硬禁是**作者手写业务 JS**。官方 bridge 可实现列表装配、路由、storage、WebSocket、内部模板/轻量 VDOM 等;作者只写 `.mq.md` + 效应表。 | 波 | 要点 | |----|------| | E1 | `set_style` / `focus` / `blur` / `scroll_into`;wire `委托`;键盘事件 | | E2 | `set_html` / `replace_children` / `render_list` | | E3 | `navigate` + `popstate`(选择器 `window`) | | E4 | `storage` `{ op, key, value?, scope?, then? }` | | E5 | `ws` `{ op: open\|send\|close, … }` | | E6 | `fetch_all` / `interval` / `clear_interval` / fetch `fields` | ### 17.1 效应速查(E) | 字段 | 含义 | |------|------| | `set_style` | `{ "#sel": { color: "red" } }` 或 `{ "#sel": "color:red" }` | | `focus` / `blur` | `"#sel"` 或选择器数组 | | `scroll_into` | `"#sel"` | | `set_html` / `append_html` / `replace_children` | 写/追加 HTML(MQ 产出;XSS 自负) | | `render_list` | `{ "#sel": { tag, items } }` | | `remove` | 选择器或数组,删除节点 | | `add_class` / `remove_class` | classList | | `navigate` | `{ url, replace?: bool }` | | `storage` | `{ op, key, value?, scope?: local\|session\|cookie, days?, then? }` | | `ws` | `{ op: open\|send\|close, … }` | | `fetch_all` | `{ requests: []\|map, then }` | | `interval` / `clear_interval` | 定时 | | `clipboard` / `download` | 剪贴板 / 触发下载 | | `fetch.fields` | → FormData | Wire 列:`委托` / `delegate` = 在容器上监听,目标须 `closest(delegate)`;选择器 `window` 绑 `window`。 ## 15. 决策摘要 | 问题 | 答案 | |------|------| | 路线? | **C**:解释器/VM → WASM | | 作者语言? | 仅 `.mq.md` | | JS 角色? | Loader + 宿主桥 | | 服务端? | 保留;不塞进浏览器 | | 第一步实现? | C0 门控可编译 + C1 `run_source` 打印闭环 |