diff --git a/CHANGELOG.md b/CHANGELOG.md index 80151df..e840384 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,7 @@ ### Added - **浏览器 Marqdo(路线 C)**: [ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [design](doc/design/browser-marqdo-wasm.md) · [roadmap C0–C5](doc/roadmap/browser-wasm.md)。 - **C0/C1**:`wasm-core` feature 门控;`run_source`;crate `crates/marqdo-wasm`(`mq_run` ABI);示例 [examples/browser-hello](examples/browser-hello/)。 +- **C2/C3**:`marqdo wasm build`;会话 `mq_boot`/`mq_call`;GFM wire 表 + `set_text` DOM 回写;[interact.html](examples/browser-hello/interact.html) 计数器示例。 ### Fixed - **Admin UI**:主区取消 `max-width:56rem` 限制,表格外包可横向滚动的 `.table-wrap`,单元格完整展示并自动换行;表单加宽且 textarea 可随内容增高。 diff --git a/crates/marqdo-wasm/README.md b/crates/marqdo-wasm/README.md index 778c1f4..31e492c 100644 --- a/crates/marqdo-wasm/README.md +++ b/crates/marqdo-wasm/README.md @@ -2,12 +2,18 @@ Raw `cdylib` exports — no `wasm-bindgen` CLI required. +| Export | Role | +|--------|------| +| `mq_alloc` / `mq_dealloc` | linear memory | +| `mq_run` | one-shot `# main` (C1) | +| `mq_boot` / `mq_call` | session + handlers (C3) | +| `mq_version` | version C string | + ```bash # from repo root +marqdo wasm build -o examples/browser-hello +# or: cargo build -p marqdo-wasm --target wasm32-unknown-unknown --release -cp target/wasm32-unknown-unknown/release/marqdo_wasm.wasm examples/browser-hello/ ``` -Open `examples/browser-hello/index.html` via a local static server (ES modules / fetch need http). - See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md). diff --git a/crates/marqdo-wasm/src/lib.rs b/crates/marqdo-wasm/src/lib.rs index 72c9b90..ee768ed 100644 --- a/crates/marqdo-wasm/src/lib.rs +++ b/crates/marqdo-wasm/src/lib.rs @@ -1,16 +1,26 @@ -//! Browser export surface for Marqdo (ADR 0002 / C1). +//! Browser export surface for Marqdo (ADR 0002 / C1–C3). //! -//! Raw `cdylib` ABI (no wasm-bindgen CLI required): -//! - `mq_alloc` / `mq_dealloc` — JS writes UTF-8 source into linear memory -//! - `mq_run` — `(ptr, len) -> ptr` to a length-prefixed UTF-8 JSON result +//! Raw `cdylib` ABI (no wasm-bindgen CLI): +//! - `mq_alloc` / `mq_dealloc` +//! - `mq_run` — one-shot `# main` (C1) +//! - `mq_boot` — start session; return value often a `wire` table (C3) +//! - `mq_call` — `(name_ptr, name_len, args_ptr, args_len) ->` JSON result (C3) +//! - `mq_version` //! -//! Result JSON: `{ ok, stdout, error, value }`. +//! Packed results: little-endian `u32` length + UTF-8 JSON +//! `{ ok, stdout, error, value }`. use std::alloc::{alloc, dealloc, Layout}; +use std::cell::RefCell; use std::ptr; use std::slice; -use marqdo::{run_source, RunOptions}; +use marqdo::{run_source, value_as_json, BrowserSession, RunOptions}; +use serde_json::json; + +thread_local! { + static SESSION: RefCell> = const { RefCell::new(None) }; +} /// Allocate `size` bytes in WASM linear memory (alignment 1). #[no_mangle] @@ -25,7 +35,7 @@ pub extern "C" fn mq_alloc(size: usize) -> *mut u8 { unsafe { alloc(layout) } } -/// Free a buffer previously returned by [`mq_alloc`] or [`mq_run`]. +/// Free a buffer previously returned by [`mq_alloc`], [`mq_run`], [`mq_boot`], or [`mq_call`]. #[no_mangle] pub extern "C" fn mq_dealloc(ptr: *mut u8, size: usize) { if ptr.is_null() || size == 0 { @@ -38,27 +48,84 @@ pub extern "C" fn mq_dealloc(ptr: *mut u8, size: usize) { unsafe { dealloc(ptr, layout) } } -/// Run Marqdo source. Input: UTF-8 at `ptr..ptr+len`. -/// Output: heap buffer = little-endian `u32` byte length + UTF-8 JSON. -/// Caller must `mq_dealloc` the returned pointer with `4 + json_len`. +/// One-shot run (C1). Does not keep a session. #[no_mangle] pub extern "C" fn mq_run(ptr: *const u8, len: usize) -> *mut u8 { - let source = if ptr.is_null() || len == 0 { - "" - } else { - match std::str::from_utf8(unsafe { slice::from_raw_parts(ptr, len) }) { - Ok(s) => s, - Err(e) => { - return pack_json(&serde_json::json!({ - "ok": false, - "stdout": "", - "error": format!("source is not utf-8: {e}"), - "value": null, - })); - } - } + let source = match read_utf8(ptr, len) { + Ok(s) => s, + Err(e) => return pack_json(&err_json(&e)), }; - pack_json(&run_to_json(source)) + pack_json(&run_to_json(&source)) +} + +/// Boot a session: run `# main`, keep entry env. Replaces any prior session. +#[no_mangle] +pub extern "C" fn mq_boot(ptr: *const u8, len: usize) -> *mut u8 { + let source = match read_utf8(ptr, len) { + Ok(s) => s, + Err(e) => return pack_json(&err_json(&e)), + }; + match BrowserSession::boot(&source) { + Ok((sess, value)) => { + let stdout = String::new(); + let value_json = match value_as_json(&value) { + Ok(j) => j, + Err(e) => return pack_json(&err_json(&e)), + }; + SESSION.with(|s| *s.borrow_mut() = Some(sess)); + pack_json(&json!({ + "ok": true, + "stdout": stdout, + "error": null, + "value": value_json, + })) + } + Err(e) => { + SESSION.with(|s| *s.borrow_mut() = None); + pack_json(&err_json(&format!("{e:#}"))) + } + } +} + +/// Call a function in the current session. +/// `args` is UTF-8 JSON object of named arguments (may be `{}`). +#[no_mangle] +pub extern "C" fn mq_call( + name_ptr: *const u8, + name_len: usize, + args_ptr: *const u8, + args_len: usize, +) -> *mut u8 { + let name = match read_utf8(name_ptr, name_len) { + Ok(s) => s, + Err(e) => return pack_json(&err_json(&e)), + }; + let args = match read_utf8(args_ptr, args_len) { + Ok(s) => s, + Err(e) => return pack_json(&err_json(&e)), + }; + SESSION.with(|cell| { + let mut guard = cell.borrow_mut(); + let Some(sess) = guard.as_mut() else { + return pack_json(&err_json("no session — call mq_boot first")); + }; + match sess.call(&name, &args) { + Ok(value) => { + let stdout = sess.take_stdout(); + let value_json = match value_as_json(&value) { + Ok(j) => j, + Err(e) => return pack_json(&err_json(&e)), + }; + pack_json(&json!({ + "ok": true, + "stdout": stdout, + "error": null, + "value": value_json, + })) + } + Err(e) => pack_json(&err_json(&format!("{e:#}"))), + } + }) } /// Package version (NUL-terminated C string in static memory — do not free). @@ -67,6 +134,14 @@ pub extern "C" fn mq_version() -> *const u8 { concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr() } +fn read_utf8(ptr: *const u8, len: usize) -> Result { + if ptr.is_null() || len == 0 { + return Ok(String::new()); + } + let bytes = unsafe { slice::from_raw_parts(ptr, len) }; + String::from_utf8(bytes.to_vec()).map_err(|e| format!("not utf-8: {e}")) +} + fn run_to_json(source: &str) -> serde_json::Value { let mut opts = RunOptions::default(); opts.allow_fs_write = false; @@ -75,21 +150,28 @@ fn run_to_json(source: &str) -> serde_json::Value { opts.sleep_limit_ms = Some(0); match run_source(source, &opts) { - Ok(cap) => serde_json::json!({ - "ok": true, - "stdout": cap.stdout, - "error": null, - "value": cap.value.as_display(), - }), - Err(e) => serde_json::json!({ - "ok": false, - "stdout": "", - "error": format!("{e:#}"), - "value": null, - }), + Ok(cap) => match value_as_json(&cap.value) { + Ok(value) => json!({ + "ok": true, + "stdout": cap.stdout, + "error": null, + "value": value, + }), + Err(e) => err_json(&e), + }, + Err(e) => err_json(&format!("{e:#}")), } } +fn err_json(msg: &str) -> serde_json::Value { + json!({ + "ok": false, + "stdout": "", + "error": msg, + "value": null, + }) +} + fn pack_json(v: &serde_json::Value) -> *mut u8 { let s = v.to_string(); let bytes = s.as_bytes(); diff --git a/doc/design/browser-marqdo-wasm.md b/doc/design/browser-marqdo-wasm.md index b52e22f..a2ef75c 100644 --- a/doc/design/browser-marqdo-wasm.md +++ b/doc/design/browser-marqdo-wasm.md @@ -152,27 +152,47 @@ source: &str (+ optional import map) ## 6. 交互装配(C3,对称样式装配) -作者面(示意,关键字以落地时 `ext` 双语名为准;**不在核心发明 `if`/`on` 关键字**): +### 6.1 作者面(示例) ```markdown -`交互` = +--- +import json:lib/json.mq.md +--- -| 选择器 | 事件 | 调用 | -|--------|------|------| -| "#btn" | click | handle_click | -| ".item" | click | select_item | +# 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`。 -1. 装配函数把表登记到 WASM 侧 registry。 -2. Loader 在 DOM 上 `addEventListener`;触发时调用导出 `marqdo_dispatch(event_id, payload_json)`。 -3. 调用解析为 Marqdo 函数(同页已 `load` 的模块内 `## handle_click`)。 -4. 返回值约定(C3 最小):`None` / 文本 / Map(如 `{dom:…}` 指令列表)由桥执行,**避免在核心写死 React**。 +### 6.2 桥约定 -值列含 `/` 的 CSS 等仍遵守 [table-cell-expressions.md](table-cell-expressions.md):**引号优先**(`"16/9"`)。 +| 步骤 | 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 表即可验收。 --- diff --git a/doc/roadmap/browser-wasm.md b/doc/roadmap/browser-wasm.md index 45335a0..b3b7885 100644 --- a/doc/roadmap/browser-wasm.md +++ b/doc/roadmap/browser-wasm.md @@ -2,7 +2,7 @@ | | | |---|---| -| 状态 | **进行中**(C0–C1 已落地;C2 示例页已有) | +| 状态 | **进行中**(C0–C3 已落地) | | 日期 | 2026-09-01 | | ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) | | 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) | @@ -16,90 +16,38 @@ | 阶段 | 内容 | 状态 | |------|------|------| -| **C0** | 设计锁定;Cargo feature 骨架;`wasm32` **check** 通过 | **done** | -| **C1** | `run_source` + `crates/marqdo-wasm`(`mq_run` ABI);hello 打印 | **done** | -| **C2** | 官方 loader + `examples/browser-hello`;可选 CLI 糖;head 挂载约定 | **partial**(示例+loader 已有) | -| **C3** | 交互装配(事件表 → 回调);最小 DOM 读写宿主 | pending | -| **C4** | `fetch`/定时器异步模型 ADR + 首版桥 | pending | -| **C5** | bytecode 后端可选;体积优化;与 view 调试对齐 | pending | - ---- - -## C0 — 可移植骨架 - -**目标:** native 默认行为不变;存在 `--features wasm-core --no-default-features` 使核心在 `wasm32-unknown-unknown` 上 `cargo check`。 - -**已落地:** - -- Features:`native`(默认)、`wasm-core`、`view`/`net-host`/`plugin-host`/`exec-host`/`fs-host`/`tty`/`cli` -- 可选依赖:`ureq`、`libloading`、`tiny_http`、`libc`、`clap` -- `run_source` / `load_module_from_source`(embedded `lib/`) - -**验收:** - -```bash -cargo check -p marqdo --target wasm32-unknown-unknown --no-default-features --features wasm-core -cargo test --test gold structure_hello -``` - ---- - -## C1 — 内存执行闭环 - -**目标:** 浏览器/测试调用 `run_source`,跑 `# main` + `> print`,拿回 stdout。 - -**已落地:** - -- `pub fn run_source`(tree + bytecode) -- crate `crates/marqdo-wasm`:`mq_alloc` / `mq_dealloc` / `mq_run` / `mq_version`(长度前缀 JSON,无需 wasm-bindgen CLI) -- 浏览器默认关 fs 写 / exec / net - -**验收:** - -```bash -cargo test -p marqdo-wasm -cargo test --lib run_source_hello -cargo build -p marqdo-wasm --target wasm32-unknown-unknown --release -``` +| **C0** | Cargo feature 骨架;`wasm32` check | **done** | +| **C1** | `run_source` + `mq_run` | **done** | +| **C2** | loader + `examples/browser-hello` + `marqdo wasm build` | **done** | +| **C3** | 会话 `mq_boot`/`mq_call`;wire 表;`set_text` DOM 回写 | **done** | +| **C4** | `fetch`/定时器异步模型 | pending | +| **C5** | bytecode / 体积 / view 调试 | pending | --- ## C2 — 示例页与挂载 -**目标:** 静态 HTML 打开即可跑 Marqdo。 - -**已有:** `examples/browser-hello/`(`index.html` + `loader.js` + README)。 -**仍缺:** `marqdo wasm build` CLI 糖;`page.head` 文档示例挂载。 +```bash +marqdo wasm build -o examples/browser-hello +cd examples/browser-hello && python3 -m http.server 8765 +``` --- ## C3 — 交互装配 -**目标:** 无手写业务 JS 的点击 → Marqdo 函数 → 改页面。 +- `BrowserSession` + `Interpreter::invoke_in_entry` +- ABI:`mq_boot` / `mq_call` +- 示例:`interact.html` + `counter.mq.md` +- Bridge:`wireEvents` / `applyDomPatch` -(见设计 §6) +**验收:** 打开 interact 页,点「加一」计数递增;源码仅为 `.mq.md` + 官方 bridge。 --- -## C4 — 异步 I/O +## C4 / C5 -**目标:** 受控 `fetch`(及 sleep)不阻塞语言谎言。 - ---- - -## C5 — 硬化 - -**目标:** bytecode、体积、`view` 调试对齐。 - ---- - -## 依赖关系 - -``` -C0 ──► C1 ──► C2 ──► C3 ──► C4 - │ │ - └──── C5 ◄─────┘ -``` +见设计文 §7 / §12。 --- @@ -107,4 +55,5 @@ C0 ──► C1 ──► C2 ──► C3 ──► C4 | 日期 | 记录 | |------|------| -| 2026-09-01 | ADR 0002 + 设计锁定;C0 feature-gate;C1 `run_source` + `marqdo-wasm` + browser-hello | +| 2026-09-01 | ADR 0002;C0–C1 | +| 2026-09-01 | C2 `wasm build`;C3 session + interact 示例 | diff --git a/examples/browser-hello/README.md b/examples/browser-hello/README.md index b7c38b9..df3ee42 100644 --- a/examples/browser-hello/README.md +++ b/examples/browser-hello/README.md @@ -1,16 +1,21 @@ -# browser-hello(WASM C1) +# browser-hello(WASM C1–C3) -在浏览器里跑 Marqdo `print`(路线 C)。 +浏览器内跑 Marqdo(路线 C)。 ```bash # 仓库根目录 -cargo build -p marqdo-wasm --target wasm32-unknown-unknown --release -cp target/wasm32-unknown-unknown/release/marqdo_wasm.wasm examples/browser-hello/ +cargo build -p marqdo --release +./target/release/marqdo wasm build -o examples/browser-hello cd examples/browser-hello python3 -m http.server 8765 -# 打开 http://127.0.0.1:8765/ ``` -- `loader.js` 仅为官方宿主桥(分配内存 / 调 `mq_run`),不是业务语言。 +| 页 | 说明 | +|----|------| +| [/](http://127.0.0.1:8765/) | C1:编辑源码 → `mq_run` 打印 | +| [/interact.html](http://127.0.0.1:8765/interact.html) | C3:`counter.mq.md` 交互表 → 点击改 DOM | + +- `marqdo-bridge.js`:官方宿主桥(`boot` / `call` / `wireEvents` / `applyDomPatch`) +- `counter.mq.md`:作者面只有 `.mq.md`(业务逻辑) - 设计:[browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md) diff --git a/examples/browser-hello/counter.mq.md b/examples/browser-hello/counter.mq.md new file mode 100644 index 0000000..04e1c40 --- /dev/null +++ b/examples/browser-hello/counter.mq.md @@ -0,0 +1,29 @@ +--- +title: browser counter (C3) +description: wire table + shared entry env; click updates DOM via set_text +import json:lib/json.mq.md +--- + +# main + +*`count` = 0* + +`wire` = + +| @ | 选择器 | 事件 | 调用 | +|---|--------|------|------| +| 1 | "#bump" | click | bump | +| 2 | "#reset" | click | reset | + +**`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** + +## reset +*`count` = 0* +*`patch` = > json.set map=None key="#count" value="0"* +**> json.set map=None key="set_text" value=patch** diff --git a/examples/browser-hello/index.html b/examples/browser-hello/index.html index 5431b75..9f48870 100644 --- a/examples/browser-hello/index.html +++ b/examples/browser-hello/index.html @@ -67,7 +67,7 @@

Marqdo

-

浏览器内 WASM 解释器(路线 C / C1):源码是 .mq.md,无业务手写 JS。

+

浏览器内 WASM 解释器(路线 C / C1):源码是 .mq.md,无业务手写 JS。交互示例 (C3)