Files
marqdo/doc/design/browser-marqdo-wasm.md

15 KiB
Raw Permalink Blame History

浏览器 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
路线图 roadmap/browser-wasm.md
相关 ext-web.md · bytecode.md · web-assets-and-images.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<RunCapture> 无路径入口;cwd/fs_root 虚拟
RunOptions 浏览器默认 allow_fs_write=false, allow_exec=false, allow_net=false(net 经显式 bridge 再开)
load 导入 lib/** → embedded_lib;用户模块 → JS 注入的 HashMap<path, source>

后端优先级:

  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 作者面(示例)

---
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)。

L1 浏览器.交互装配(ext)可后置;C3 以 bridge + 返回 wire 表即可验收。


7. 异步模型(C4)

锁定:ADR 0003。

处理器返回 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

挂载示例:

`头` =

| 关系 | 地址 |
|------|------|
| module | /static/marqdo-bridge.js |

*p = > page.头装配 表=头*
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。

原则: 业务与交互 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)。

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。

原则: 唯一硬禁是作者手写业务 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 打印闭环