diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index d96d4c0..12cb6ea 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -29,7 +29,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords. 7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division. 8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed. 9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4. -10. **Browser (route C):** client logic is Marqdo on WASM ([ADR 0002](../../../doc/adr/0002-browser-marqdo-wasm.md)); async I/O via return effects `fetch`/`after` ([ADR 0003](../../../doc/adr/0003-browser-async-effects.md)); official bridge is host glue only. +10. **Browser (route C/D):** client logic is Marqdo on WASM ([ADR 0002](../../../doc/adr/0002-browser-marqdo-wasm.md)); async I/O via return effects `fetch`/`after` ([ADR 0003](../../../doc/adr/0003-browser-async-effects.md)); official bridge is **host glue only**. **Author zero business JS** — use `web.client_embed` / `网页.客户端挂载` (`wasm` + `source` + `boot`) or `data-mq-source-url` so bridge `mount`s automatically ([roadmap D](../../../doc/roadmap/browser-wasm-d.md)). DOM effects: `set_text` / `set_value` / `set_attr` / `set_class` / `toggle_class` / `set_html` only on `#trusted*` selectors. ## Markup → meaning (v0.2) @@ -175,11 +175,11 @@ data/ # sqlite runtime (gitignore) **Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`. -**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.head` / `page.images` / `page.meta` → `app` with `route` / `static` / `icons` / `configure` / `listen`. +**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.head` / `page.images` / `page.meta` → `app` with `route` / `static` / `icons` / `configure` / `listen`. For client interactivity: `marqdo wasm build -o static`, then `web.client_embed source="/static/client.mq.md"` (or ZH `网页.客户端挂载`) in page HTML — **no author JS** ([browser-wasm-d.md](../../doc/roadmap/browser-wasm-d.md) · [web-client-site](../../examples/web-client-site/)). -**Shipped surface (W0–W7 + P3 + W8):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`). +**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`). -Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/). +Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/). Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md). diff --git a/.gitignore b/.gitignore index 1333141..732a2e1 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ spike/.pytest_cache/ # Built browser WASM (rebuild via crates/marqdo-wasm README) /examples/browser-hello/marqdo_wasm.wasm /examples/browser-hello/pkg/ +/examples/web-client-site/static/marqdo_wasm.wasm # Local sqlite / scratch /data/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 34a4f60..5ddbdba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,8 @@ ## Unreleased ### Added +- **路线 D(作者零 JS)**:[roadmap](doc/roadmap/browser-wasm-d.md) · 设计 §16。官方 bridge `mount` / `data-mq-*` 自启;`client_embed` 带 `wasm`/`source`/`boot`;DOM 效应 `set_value`/`set_attr`/`set_class`/`toggle_class`/`set_html(#trusted…)`;wire 传 `value`/`fields`;示例去业务 JS;`examples/web-client-site/`。 +- **路线 E(规划)**:[browser-wasm-e.md](doc/roadmap/browser-wasm-e.md) — 路由 / 存储 / 列表片段 / WebSocket / DOM·定时补齐;C+D **尚不能**替代大部分前端 JS。 ### Fixed diff --git a/README.md b/README.md index a862ef4..633afe3 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` -- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge;示例 [browser-hello](examples/browser-hello/);站点挂载 `web.client_embed` / `网页.客户端挂载`([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [ADR 0003](doc/adr/0003-browser-async-effects.md)) +- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge **自启**(路线 D 作者零业务 JS);`web.client_embed` / `网页.客户端挂载`;示例 [browser-hello](examples/browser-hello/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [ADR 0003](doc/adr/0003-browser-async-effects.md) · [路线 D](doc/roadmap/browser-wasm-d.md)) - 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md) ### 如何使用最新 Marqdo(v0.3.2) diff --git a/crates/marqdo-wasm/js/marqdo-bridge.js b/crates/marqdo-wasm/js/marqdo-bridge.js index f30a46e..98ac03a 100644 --- a/crates/marqdo-wasm/js/marqdo-bridge.js +++ b/crates/marqdo-wasm/js/marqdo-bridge.js @@ -1,11 +1,13 @@ /** - * Canonical Marqdo browser bridge (route C). Host glue only — not app logic. + * Canonical Marqdo browser bridge (route C/D). Host glue only — not app logic. * Copied to site dirs by `marqdo wasm build`. * * ABI: mq_alloc, mq_dealloc, mq_run, mq_boot, mq_call, mq_version * Packed results: u32le length + UTF-8 JSON { ok, stdout, error, value } * - * Effects (ADR 0003): set_text, fetch, after + * Effects (ADR 0003 + route D): set_text, set_value, set_attr, set_class, + * toggle_class, set_html (#trusted* only), fetch, after + * Mount: mount() / data-mq-* / #marqdo-boot auto-start (author zero JS) */ export function readCString(memory, ptr) { @@ -67,16 +69,196 @@ export async function loadWasm(url = "./marqdo_wasm.wasm") { return instance.exports; } -/** Apply C3/C4 return effects: set_text, fetch, after */ +function isPlainObject(v) { + return v != null && typeof v === "object" && !Array.isArray(v); +} + +/** Normalize mount options from plain object or DOM dataset. */ +export function normalizeMountOptions(raw = {}) { + const o = raw && typeof raw === "object" ? raw : {}; + const dataset = o.dataset || {}; + const wasmUrl = + o.wasmUrl || + o.wasm || + dataset.mqWasm || + dataset.wasm || + "./marqdo_wasm.wasm"; + const sourceUrl = + o.sourceUrl || + o.source_url || + dataset.mqSourceUrl || + dataset.sourceUrl || + ""; + let source = o.source != null ? o.source : dataset.mqSource || ""; + if (!source && typeof o.sourceInline === "string") source = o.sourceInline; + const playground = + o.playground || + dataset.mqPlayground || + dataset.playground || + ""; + const ready = + o.ready || + o.readySel || + dataset.mqReady || + ""; + const enable = + o.enable || + dataset.mqEnable || + ""; + const noBoot = + o.noBoot === true || + dataset.mqNoBoot === "1" || + dataset.mqNoBoot === "true"; + return { + wasmUrl: String(wasmUrl), + sourceUrl: sourceUrl ? String(sourceUrl) : "", + source: source ? String(source) : "", + playground: playground ? String(playground) : "", + ready: ready ? String(ready) : "", + enable: enable ? String(enable) : "", + noBoot, + onError: typeof o.onError === "function" ? o.onError : null, + }; +} + +/** + * Collect mount configs from `#marqdo-boot` JSON and `script[data-mq-*]`. + * Pure DOM scan — safe to call once after DOM ready. + */ +export function collectMountConfigs(doc = typeof document !== "undefined" ? document : null) { + if (!doc) return []; + const out = []; + const bootEl = doc.getElementById("marqdo-boot"); + if (bootEl) { + try { + const json = JSON.parse(bootEl.textContent || "{}"); + out.push(normalizeMountOptions(json)); + } catch (e) { + console.error("marqdo-boot JSON:", e); + } + } + const scripts = doc.querySelectorAll( + "script[data-mq-source-url], script[data-mq-source], script[data-mq-playground], script[data-mq-wasm]", + ); + for (const el of scripts) { + if (el.dataset.mqNoBoot === "1" || el.dataset.mqNoBoot === "true") continue; + const hasWork = + el.dataset.mqSourceUrl || + el.dataset.mqSource || + el.dataset.mqPlayground; + if (!hasWork && !el.dataset.mqWasm) continue; + if (!hasWork) continue; + out.push( + normalizeMountOptions({ + dataset: el.dataset, + wasmUrl: el.dataset.mqWasm, + sourceUrl: el.dataset.mqSourceUrl, + source: el.dataset.mqSource, + playground: el.dataset.mqPlayground, + ready: el.dataset.mqReady, + enable: el.dataset.mqEnable, + }), + ); + } + return out; +} + +/** Build mq_call args from a DOM event + optional value_from selector. */ +export function eventArgsFromDom(ev, valueFromSel) { + const t = ev && ev.target; + const args = { + event: ev && ev.type ? ev.type : "click", + }; + if (t && typeof t === "object") { + if ("value" in t && t.value != null) args.value = String(t.value); + if ("checked" in t) args.checked = !!t.checked; + if (t.id) args.id = String(t.id); + if (typeof t.textContent === "string" && !("value" in t)) { + args.text = t.textContent; + } + } + if (valueFromSel && typeof document !== "undefined") { + const src = document.querySelector(valueFromSel); + if (src) { + if ("value" in src) args.value = String(src.value); + else args.value = src.textContent != null ? String(src.textContent) : ""; + } + } + if (ev && ev.type === "submit" && t) { + const form = typeof t.closest === "function" ? t.closest("form") : t; + if (form && typeof FormData !== "undefined") { + try { + ev.preventDefault(); + } catch (_) { + /* ignore */ + } + const fields = {}; + for (const [k, v] of new FormData(form)) { + fields[k] = String(v); + } + args.fields = fields; + } + } + return args; +} + +/** Apply C3/C4/D3 return effects: DOM patches then fetch/after. */ export function applyDomPatch(value) { if (!value || typeof value !== "object") return; + if (typeof document === "undefined") return; + const setText = value.set_text || value.setText; - if (setText && typeof setText === "object") { + if (isPlainObject(setText)) { for (const [sel, text] of Object.entries(setText)) { const el = document.querySelector(sel); if (el) el.textContent = String(text); } } + + const setValue = value.set_value || value.setValue; + if (isPlainObject(setValue)) { + for (const [sel, v] of Object.entries(setValue)) { + const el = document.querySelector(sel); + if (el && "value" in el) el.value = String(v); + } + } + + const setAttr = value.set_attr || value.setAttr; + if (isPlainObject(setAttr)) { + for (const [sel, attrs] of Object.entries(setAttr)) { + const el = document.querySelector(sel); + if (!el || !isPlainObject(attrs)) continue; + for (const [name, raw] of Object.entries(attrs)) { + if (raw === null || raw === false) el.removeAttribute(name); + else el.setAttribute(name, String(raw)); + } + } + } + + const setClass = value.set_class || value.setClass; + if (isPlainObject(setClass)) { + for (const [sel, cls] of Object.entries(setClass)) { + const el = document.querySelector(sel); + if (el) el.className = String(cls); + } + } + + const toggleClass = value.toggle_class || value.toggleClass; + if (isPlainObject(toggleClass)) { + for (const [sel, cls] of Object.entries(toggleClass)) { + const el = document.querySelector(sel); + if (el && cls) el.classList.toggle(String(cls)); + } + } + + const setHtml = value.set_html || value.setHtml; + if (isPlainObject(setHtml)) { + for (const [sel, html] of Object.entries(setHtml)) { + if (!String(sel).startsWith("#trusted")) continue; + const el = document.querySelector(sel); + if (el) el.innerHTML = String(html); + } + } } /** @@ -180,12 +362,15 @@ export function wireEvents(exports, bootValue, { onError } = {}) { const sel = row["选择器"] || row.selector || row.sel; const ev = row["事件"] || row.event || "click"; const fn = row["调用"] || row.call || row.fn; + const valueFrom = + row["值选择器"] || row.value_from || row.valueFrom || row.from || ""; if (!sel || !fn) continue; const nodes = document.querySelectorAll(sel); nodes.forEach((node) => { - node.addEventListener(ev, () => { + node.addEventListener(ev, (domEv) => { try { - const result = call(exports, fn, { event: ev }); + const args = eventArgsFromDom(domEv, valueFrom); + const result = call(exports, fn, args); if (!result.ok) { if (onError) onError(result.error); else console.error(result.error); @@ -202,3 +387,154 @@ export function wireEvents(exports, bootValue, { onError } = {}) { } return rows.length; } + +function markReady(opts, message) { + if (opts.ready && typeof document !== "undefined") { + const el = document.querySelector(opts.ready); + if (el) { + el.classList?.remove?.("err"); + el.textContent = message; + } + } + if (opts.enable && typeof document !== "undefined") { + for (const sel of String(opts.enable).split(",")) { + const s = sel.trim(); + if (!s) continue; + document.querySelectorAll(s).forEach((n) => { + n.disabled = false; + n.removeAttribute("disabled"); + }); + } + } +} + +function markError(opts, err) { + const msg = String(err); + if (opts.onError) opts.onError(msg); + if (opts.ready && typeof document !== "undefined") { + const el = document.querySelector(opts.ready); + if (el) { + el.classList?.add?.("err"); + el.textContent = msg; + } + } else { + console.error(msg); + } +} + +function wirePlayground(exports, playgroundSpec, { onError } = {}) { + const parts = String(playgroundSpec) + .split(",") + .map((s) => s.trim()) + .filter(Boolean); + const sourceSel = parts[0] || "#src"; + const runSel = parts[1] || "#run"; + const outSel = parts[2] || "#out"; + const runBtn = document.querySelector(runSel); + const src = document.querySelector(sourceSel); + const out = document.querySelector(outSel); + if (!runBtn || !src) return 0; + runBtn.disabled = false; + runBtn.removeAttribute("disabled"); + runBtn.addEventListener("click", () => { + try { + const result = runSource(exports, src.value || ""); + if (out) { + out.classList?.toggle?.("err", !result.ok); + out.textContent = result.ok + ? (result.stdout || "(empty stdout)") + + (result.value != null && result.value !== "None" + ? `\n[return] ${typeof result.value === "string" ? result.value : JSON.stringify(result.value)}` + : "") + : result.error || "error"; + } + } catch (e) { + if (onError) onError(String(e)); + else if (out) { + out.classList?.add?.("err"); + out.textContent = String(e); + } + } + }); + return 1; +} + +/** + * One-shot: load wasm, boot session (or playground), wire events. + * @returns {{ exports, boot, wired }} + */ +export async function mount(rawOpts = {}) { + const opts = normalizeMountOptions(rawOpts); + const onError = (err) => markError(opts, err); + + let exports; + try { + exports = await loadWasm(opts.wasmUrl); + } catch (e) { + onError(e); + throw e; + } + + const ver = readCString(exports.memory, exports.mq_version()); + + if (opts.playground) { + const n = wirePlayground(exports, opts.playground, { onError }); + markReady(opts, `marqdo-wasm ${ver} · playground ready`); + return { exports, boot: null, wired: n }; + } + + let source = opts.source; + if (!source && opts.sourceUrl) { + const res = await fetch(opts.sourceUrl); + if (!res.ok) { + const err = `failed to load ${opts.sourceUrl} (${res.status})`; + onError(err); + throw new Error(err); + } + source = await res.text(); + } + if (!source) { + const err = "mount: need source, sourceUrl, or playground"; + onError(err); + throw new Error(err); + } + + const result = boot(exports, source); + if (!result.ok) { + onError(result.error || "boot failed"); + throw new Error(result.error || "boot failed"); + } + + // If boot value is a map with effects alongside wire, apply them. + if (result.value && !Array.isArray(result.value)) { + await applyEffects(exports, result.value, { onError }); + } + + const n = wireEvents(exports, result.value, { onError }); + const srcLabel = opts.sourceUrl || "(inline)"; + markReady(opts, `marqdo-wasm ${ver} · wired ${n} handler(s)\nsource: ${srcLabel}`); + return { exports, boot: result, wired: n }; +} + +/** Auto-mount from DOM configs (route D). */ +export async function autoMount(doc) { + const configs = collectMountConfigs(doc); + const results = []; + for (const cfg of configs) { + if (cfg.noBoot) continue; + results.push(await mount(cfg)); + } + return results; +} + +const g = typeof globalThis !== "undefined" ? globalThis : undefined; +if (g && g.document) { + const start = () => { + autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e)); + }; + if (g.document.readyState === "loading") { + g.document.addEventListener("DOMContentLoaded", start); + } else { + queueMicrotask(start); + } +} diff --git a/doc/README.md b/doc/README.md index d9897f7..26658b0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -59,7 +59,10 @@ | [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) | | [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) | | [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) | -| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) | +| [roadmap/browser-wasm.md](roadmap/browser-wasm.md) | **浏览器 WASM 路线 C(C0–C5 Completed)** | +| [roadmap/browser-wasm-d.md](roadmap/browser-wasm-d.md) | **路线 D:作者零 JS 前端(Completed)** | +| [roadmap/browser-wasm-e.md](roadmap/browser-wasm-e.md) | **路线 E:前端能力补齐(Planned)** | +| [design/browser-marqdo-wasm.md](design/browser-marqdo-wasm.md) | **浏览器 Marqdo(WASM)设计** | | [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) | | [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 | | [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 | diff --git a/doc/design/browser-marqdo-wasm.md b/doc/design/browser-marqdo-wasm.md index 16d1f0e..70b8f49 100644 --- a/doc/design/browser-marqdo-wasm.md +++ b/doc/design/browser-marqdo-wasm.md @@ -299,6 +299,74 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js --- +## 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 | 通用 VDOM / 客户端路由框架 | +| D-N3 | 开放无前缀的 `set_html` | + +--- + +## 17. 路线 E — 前端能力补齐(Planned) + +路线图:[browser-wasm-e.md](../roadmap/browser-wasm-e.md)。 + +**审视结论:** C+D 胜任中小型交互(挂载、wire、表单、单次 fetch);**不能**替代大部分前端 JS,直到 E 波补齐路由、存储、列表片段、WebSocket、更细 DOM/定时。 + +| 波 | 要点 | +|----|------| +| E1 | `set_style` / `focus` / 委托事件 / 键盘 | +| E2 | 受信列表/片段装配 L1 | +| E3 | `navigate` + `popstate` | +| E4 | `storage` 效应 | +| E5 | 浏览器 `ws` 效应 | +| E6 | 并行 fetch / interval / FormData | + +--- + ## 15. 决策摘要 | 问题 | 答案 | diff --git a/doc/roadmap/browser-wasm-d.md b/doc/roadmap/browser-wasm-d.md new file mode 100644 index 0000000..2f022f5 --- /dev/null +++ b/doc/roadmap/browser-wasm-d.md @@ -0,0 +1,35 @@ +# 路线图:浏览器 Marqdo 路线 D(作者零 JS) + +| | | +|---|---| +| 状态 | **Completed**(D0–D4 已落地;续作见 [browser-wasm-e.md](browser-wasm-e.md)) | +| 日期 | 2026-09-03 | +| 前置 | [browser-wasm.md](browser-wasm.md)(C0–C5 **Completed**) | +| ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) | +| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16 | + +## 一句话 + +作者侧**零业务 JS**:页面逻辑与交互只写 `.mq.md`;官方 `marqdo-bridge.js` 仍作不透明宿主胶(加载 WASM / DOM / fetch),由 `mount` + `client_embed` 自动启动。 + +## 阶段 + +| 阶段 | 内容 | 状态 | +|------|------|------| +| **D0** | 路线图 + 设计增补 | **done** | +| **D1** | bridge `mount` + data-mq / `#marqdo-boot` 自启;hello 去掉 loader/interact/fetch.js | **done** | +| **D2** | `client_embed` / `客户端挂载`:`wasm` / `source` / `boot` | **done** | +| **D3** | DOM/表单效应 + wire 传 `value`;`dom_patch` L1 | **done** | +| **D4** | `examples/web-client-site` + skill / README | **done** | + +## 非目标 + +- 消灭官方 bridge 文件本身(宿主胶必须存在) +- 任意 `eval(JS)` / React 式 VDOM +- 把 axum / SQLite 搬进浏览器(仍属 C 非目标) + +## 验收 + +- 示例无作者业务 `.js`(允许构建拷贝的 `marqdo-bridge.js`) +- `ext/web` 一行挂载即可 boot + wire +- 点击、表单 input、`fetch` 效应可演示 diff --git a/doc/roadmap/browser-wasm-e.md b/doc/roadmap/browser-wasm-e.md new file mode 100644 index 0000000..21d0792 --- /dev/null +++ b/doc/roadmap/browser-wasm-e.md @@ -0,0 +1,55 @@ +# 路线图:浏览器 Marqdo 路线 E(前端能力补齐) + +| | | +|---|---| +| 状态 | **Planned** | +| 日期 | 2026-09-04 | +| 前置 | [browser-wasm-d.md](browser-wasm-d.md)(D0–D4 **Completed**) | +| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16–§17 | + +## 结论(能力审视) + +路线 C+D 已能覆盖**中小型交互站**的常见路径:挂载会话、wire 事件、文本/表单回写、`fetch`/`after`、作者零业务 JS。 + +**尚不能**宣称「替代大部分 / 全部前端 JS」。缺口集中在:列表级 UI 装配、客户端路由与历史、本地持久化、实时通道、媒体/画布、以及更细的 DOM 读写与委托事件。 + +| 类别 | 今日 | 典型 JS 任务 | 路线 E | +|------|------|--------------|--------| +| 启动 / 会话 | `mount` / `client_embed` | 手写 loader | 已够用 | +| 点击 / 表单 | wire + `value`/`fields` | addEventListener | 扩委托 / 更多事件 | +| DOM 补丁 | `set_text`/`value`/`attr`/`class` | jQuery 式改节点 | `set_style`、`focus`、`scroll`、列表 diff | +| 网络 | 单次 `fetch` 效应 | axios / 多并行 | 并行 `fetch_all`、上传进度 | +| 定时 | `after` | setInterval | `interval` / `cancel` | +| 路由 | 无 | history / SPA | `navigate` / `popstate` wire | +| 存储 | 无 | localStorage / IDB | `storage` 效应 | +| 实时 | 服务端有 `ws`;浏览器无 | WebSocket | 浏览器 `ws` 效应 | +| 组件列表 | SSR 为主 | 客户端 render list | `set_html(#trusted*)` + 模板装配 L1 | +| 媒体 / 画布 | 无 | Audio / Canvas / WebGL | 后置(非 E 核心) | +| 原生插件 | 浏览器无 `.so` | wasm 插件 | 明确非目标 | + +原则不变:官方 bridge 仍是宿主胶;业务只写 `.mq.md`;不引入通用 VDOM / 任意 `eval(JS)`。 + +## 阶段 + +| 阶段 | 内容 | 状态 | +|------|------|------| +| **E0** | 本文 + 设计 §17 能力矩阵 | **done**(文档) | +| **E1** | DOM 补齐:`set_style`、`focus`/`blur`、`scroll_into`;wire `keydown`/`keyup`;事件委托(可选 `委托` 列) | planned | +| **E2** | 列表 / 片段:`replace_children` 或受信 `#trusted*` 模板 L1(`web.client_list`);避免手写巨段 HTML | planned | +| **E3** | 客户端路由:`navigate` / `replace` 效应 + `popstate` wire;与 `ext/web` SSR 深链共存约定 | planned | +| **E4** | 持久化:`storage.get/set/remove`(local/session);可选简单 cookie 读写白名单 | planned | +| **E5** | 实时:浏览器 `ws` 效应(open / send / on_message → `mq_call`);对齐服务端 `ws` 语义 | planned | +| **E6** | 异步增强:`fetch` 并行表、`interval`+`clear`、上传 `FormData` 字段表 | planned | + +## 验收(E 收口时) + +- 无作者业务 JS 的情况下,可做:多页客户端导航、表单草稿存 localStorage、列表增删改、同源 WebSocket 回显。 +- 冒烟 / 示例覆盖 E1–E5 各至少一例。 +- 体积与安全:效应仍白名单;`set_html` 维持 `#trusted*` 前缀。 + +## 明确非目标(E) + +- React/Vue 式 VDOM 与虚拟列表框架 +- 浏览器内 SQLite / 完整 ORM +- Service Worker / PWA 全套(可另开路线) +- 用 Marqdo 重写 bridge 自身 diff --git a/doc/roadmap/browser-wasm.md b/doc/roadmap/browser-wasm.md index 7124896..1caf137 100644 --- a/doc/roadmap/browser-wasm.md +++ b/doc/roadmap/browser-wasm.md @@ -2,7 +2,7 @@ | | | |---|---| -| 状态 | **Completed**(路线 C 首版功能完备) | +| 状态 | **Completed**(路线 C 首版功能完备;续作见 [browser-wasm-d.md](browser-wasm-d.md)) | | 日期 | 2026-09-01 | | ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) | | 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) | diff --git a/examples/browser-hello/README.md b/examples/browser-hello/README.md index a4339c0..efa19f2 100644 --- a/examples/browser-hello/README.md +++ b/examples/browser-hello/README.md @@ -1,6 +1,6 @@ -# browser-hello(WASM C1–C3) +# browser-hello(WASM C1–C4 / 路线 D) -浏览器内跑 Marqdo(路线 C)。 +浏览器内跑 Marqdo。**无作者业务 JS**——只保留官方 `marqdo-bridge.js`(`marqdo wasm build` 拷贝)。 ```bash # 仓库根目录 @@ -13,9 +13,9 @@ python3 -m http.server 8765 | 页 | 说明 | |----|------| -| [/](http://127.0.0.1:8765/) | C1:编辑源码 → `mq_run` 打印 | -| [/interact.html](http://127.0.0.1:8765/interact.html) | C3:`counter.mq.md` 交互表 → 点击改 DOM | -| [/fetch.html](http://127.0.0.1:8765/fetch.html) | C4:`fetch` / `after` 效应续体 | +| [/](http://127.0.0.1:8765/) | playground:`data-mq-playground` + textarea → `mq_run` | +| [/interact.html](http://127.0.0.1:8765/interact.html) | `counter.mq.md` wire → 点击改 DOM | +| [/fetch.html](http://127.0.0.1:8765/fetch.html) | `fetch` / `after` 效应 | +| [/form.html](http://127.0.0.1:8765/form.html) | `input` + `value` / `set_class`(D3) | -- `marqdo-bridge.js`:官方宿主桥(`boot` / `call` / `wireEvents` / `applyEffects`) -- 业务源码只有 `.mq.md`;异步见 [ADR 0003](../../doc/adr/0003-browser-async-effects.md) +自启方式:脚本上的 `data-mq-source-url` / `data-mq-playground`,或 `#marqdo-boot` JSON。详见 [browser-wasm-d.md](../../doc/roadmap/browser-wasm-d.md)。 diff --git a/examples/browser-hello/fetch.html b/examples/browser-hello/fetch.html index a37acdf..8de701e 100644 --- a/examples/browser-hello/fetch.html +++ b/examples/browser-hello/fetch.html @@ -69,11 +69,18 @@
C4:返回 fetch / after 效应,由官方 bridge 续体回调(ADR 0003)。业务只在 fetch.mq.md。计数器 · 打印
C4/D:返回 fetch / after 效应;bridge 自启(ADR 0003)。业务只在 fetch.mq.md。计数器 · 表单 · 打印
loading…- +