From f2fd4fb34e3879afd1fcc6ab6e22cea183fb5e50 Mon Sep 17 00:00:00 2001 From: cflmy Date: Tue, 1 Sep 2026 10:06:56 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20lock=20browser=20Marqdo=20WASM=20plan?= =?UTF-8?q?=20(ADR=200002,=20C0=E2=80=93C5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Accept route C: ship the interpreter/VM on wasm32 with a thin JS host bridge, not transpile-to-JS. Add design, roadmap, and cross-links. Co-authored-by: Cursor --- CHANGELOG.md | 3 + README.md | 2 +- doc/adr/0002-browser-marqdo-wasm.md | 57 +++++++ doc/design/browser-marqdo-wasm.md | 254 ++++++++++++++++++++++++++++ doc/design/tech-stack.md | 2 +- doc/roadmap/browser-wasm.md | 135 +++++++++++++++ doc/roadmap/interpreter.md | 3 +- doc/roadmap/next-phase.md | 2 +- 8 files changed, 454 insertions(+), 4 deletions(-) create mode 100644 doc/adr/0002-browser-marqdo-wasm.md create mode 100644 doc/design/browser-marqdo-wasm.md create mode 100644 doc/roadmap/browser-wasm.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a5d3726..a0a87b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +### Added +- **浏览器 Marqdo(路线 C)设计锁定**:[ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [design/browser-marqdo-wasm.md](doc/design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md)(WASM 解释器,非编译到 JS)。 + ### Fixed - **Admin UI**:主区取消 `max-width:56rem` 限制,表格外包可横向滚动的 `.table-wrap`,单元格完整展示并自动换行;表单加宽且 textarea 可随内容增高。 - **`marqdo ext add`**:安装含原生插件的扩展时**先**定位/自动 `cargo build` 再拷贝 `.mq.md`,避免只装上文稿、运行时报 `native plugin not found`;扩大 `.so` 搜索路径。 diff --git a/README.md b/README.md index 98b3dfe..e452df1 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ marqdo catalog public -o .marqdo - **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}` - **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/) - **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix` -- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) +- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM 解释器](doc/adr/0002-browser-marqdo-wasm.md)(路线 C,实现中见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md)) ### 如何使用最新 Marqdo(v0.3.1) diff --git a/doc/adr/0002-browser-marqdo-wasm.md b/doc/adr/0002-browser-marqdo-wasm.md new file mode 100644 index 0000000..68474d5 --- /dev/null +++ b/doc/adr/0002-browser-marqdo-wasm.md @@ -0,0 +1,57 @@ +# ADR 0002:浏览器内 Marqdo = WASM 解释器(路线 C) + +| | | +|---|---| +| 状态 | **Accepted** | +| 日期 | 2026-09-01 | +| 决策者 | chaungming + 协作 | +| 相关 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) · [interpreter.md](../roadmap/interpreter.md) · [0001](0001-implementation-language.md) | + +--- + +## 背景 + +`ext/web` 已把站点装配成「源码以 `.mq.md` 为主、服务端 Rust 解释执行」。作者面仍缺**浏览器内**的同一语言:事件、局部状态、客户端 fetch/WS 回调今天要么手写 JS,要么完全不做。 + +候选路线: + +| 代号 | 做法 | +|------|------| +| **A** | 服务端驱动 + 极薄固定增强(类 HTMX) | +| **B** | 把 Marqdo **编译/翻译成 JavaScript** | +| **C** | 把 **Rust 解释器/字节码 VM 编成 WASM**,浏览器跑同一套语义 | + +产品叙事目标:**网络项目源码树可以只有 `.mq.md`**(JS/WASM 为生成或发行物,不是第二作者语言)。 + +--- + +## 决策 + +1. **选定路线 C**:浏览器内运行 **与主机同构的 Marqdo 语义**(parse → tree 和/或 bytecode VM),制品为 `marqdo.wasm` + 极薄 JS 宿主桥。 +2. **不选定 B 作为主路径**:翻译到 JS 易语义漂移,长期要维护两套后端;B 至多作实验,不替代 C。 +3. **A 不对立**:内容站 / SSR / 表单 POST 仍以服务端 `ext/web` 为主;C 负责「必须在客户端执行的 Marqdo」。 +4. **同一内核、两套宿主**:`server`(今日 CLI + axum 插件)与 `browser`(DOM / `fetch` / 定时器 / storage);**不是**把 axum、`plugins/web`、SQLite 服务端塞进浏览器。 +5. **另开设计与路线图**(见相关链接);实现按 **C0→C5** 切片,金样对齐主机行为。 +6. **与「编译 mq.md → WASM 机器码」区分**:本 ADR 是 **解释器/VM 上 WASM**;把 `.mq.md` 直接编译成独立 wasm 模块仍属 `interpreter.md` Phase III 可选项,**另案**,不替代本决策。 + +--- + +## 后果 + +- 核心库必须可 **feature-gate** 掉 `libloading` / `ureq` / `tiny_http` / TTY `libc` 等,以便 `wasm32-unknown-unknown` 链接。 +- 新增公共 API:`run_source`(内存源码 + 可选导入图),供 WASM 与测试共用。 +- 浏览器侧宿主 API 以表驱动「交互装配」暴露(对称于 `样式装配`);`ext/**` 仍不直接调 `host_*`。 +- 发行物可包含 `.wasm` / 生成的 loader;**作者仓库可不提交手写业务 JS**。 +- view 断点 / 静态文档站调试可复用同一 WASM 解释器(与 `next-phase.md` 所述一致)。 + +--- + +## 否决 / 非目标(本 ADR) + +| 方案 / 目标 | 原因 | +|-------------|------| +| 以 B(编译到 JS)为主交付 | 语义双轨;与「一种语言」冲突 | +| 浏览器内完整复刻 `plugins/web` 服务器 | 协议与权限模型不同;服务端仍 axum | +| 浏览器 `dlopen` 原生插件 | WASM 无 POSIX 动态库模型 | +| v1 消灭一切 JS 字节 | 胶水与发行 loader 允许存在;禁止的是**业务手写 JS** | +| 用 Daphne/ASGI 托管 Marqdo | 已否决,见 [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | diff --git a/doc/design/browser-marqdo-wasm.md b/doc/design/browser-marqdo-wasm.md new file mode 100644 index 0000000..175d53b --- /dev/null +++ b/doc/design/browser-marqdo-wasm.md @@ -0,0 +1,254 @@ +# 浏览器 Marqdo(WASM 解释器)设计 + +| | | +|---|---| +| 状态 | **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` + `wasm-bindgen` 导出 | +| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) | +| `examples/browser-hello/` | 静态页 + 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,对称样式装配) + +作者面(示意,关键字以落地时 `ext` 双语名为准;**不在核心发明 `if`/`on` 关键字**): + +```markdown +`交互` = + +| 选择器 | 事件 | 调用 | +|--------|------|------| +| "#btn" | click | handle_click | +| ".item" | click | select_item | + +*`_`` = > 浏览器.交互装配 表=`交互` * +``` + +语义: + +1. 装配函数把表登记到 WASM 侧 registry。 +2. Loader 在 DOM 上 `addEventListener`;触发时调用导出 `marqdo_dispatch(event_id, payload_json)`。 +3. 调用解析为 Marqdo 函数(同页已 `load` 的模块内 `## handle_click`)。 +4. 返回值约定(C3 最小):`None` / 文本 / Map(如 `{dom:…}` 指令列表)由桥执行,**避免在核心写死 React**。 + +值列含 `/` 的 CSS 等仍遵守 [table-cell-expressions.md](table-cell-expressions.md):**引号优先**(`"16/9"`)。 + +--- + +## 7. 异步模型(C4 才深化) + +Marqdo 今日调用多为**同步**。浏览器 `fetch` / 定时器是异步的。 + +C1–C3 约定: + +- 同步子集先完整。 +- `fetch`:C4 引入 **宿主 Promise → 续体** 或 **显式 `> 浏览器.请求` 返回 future 句柄 + 轮询/回调表**;需短 ADR 补丁,不在 C1 假装同步阻塞整个页面。 + +在续体方案落地前:网络仍以**服务端** `ext/web` / `lib/net`(native)为主。 + +--- + +## 8. 安全 + +| 项 | 规则 | +|----|------| +| 默认能力 | 无磁盘写、无 exec、无任意 net | +| 源码来源 | 同源或构建时嵌入;不默认 `eval` 远程不可信脚本除非站点显式开启 | +| DOM | 仅经装配表/白名单 API;不暴露任意 `innerHTML` 字符串执行第三方脚本 | +| CSRF / Cookie | 浏览器 Marqdo **不替代**服务端鉴权;cookie 仍走 HTTP | + +--- + +## 9. 与 `ext/web` 分工 + +| 层 | 负责 | +|----|------| +| 服务端 `plugins/web` | 路由、DB、会话、SSR HTML、样式/头/图装配 | +| 页面壳 | 输出时可选嵌入 `