From c5bb08022acee5f195957c1e581d182b1370a748 Mon Sep 17 00:00:00 2001 From: cflmy Date: Thu, 17 Sep 2026 21:00:10 +0800 Subject: [PATCH] feat(web): collaborative notepad MVP over WS rooms Add LWW text sync demo (DOC\\t protocol + presence) on route_ws rooms, with design note and bag smoke. Co-authored-by: Cursor --- doc/design/ext-web-collab.md | 19 +++++ doc/design/ext-web.md | 1 + examples/web-collab-doc/README.md | 12 +++ examples/web-collab-doc/index.mq.md | 24 ++++++ examples/web-collab-doc/static/client.mq.md | 85 +++++++++++++++++++++ tests/ext/web-collab-bag-smoke.mq.md | 26 +++++++ 6 files changed, 167 insertions(+) create mode 100644 doc/design/ext-web-collab.md create mode 100644 examples/web-collab-doc/README.md create mode 100644 examples/web-collab-doc/index.mq.md create mode 100644 examples/web-collab-doc/static/client.mq.md create mode 100644 tests/ext/web-collab-bag-smoke.mq.md diff --git a/doc/design/ext-web-collab.md b/doc/design/ext-web-collab.md new file mode 100644 index 0000000..a8e4de8 --- /dev/null +++ b/doc/design/ext-web-collab.md @@ -0,0 +1,19 @@ +# Collaborative document MVP + +| | | +|---|---| +| 状态 | **Accepted · MVP (LWW)** | +| 日期 | 2026-09-17 | + +## Approach + +Not a full CRDT. Peers sync plain text over `route_ws mode=room` with: + +- Client → server: `DOC\\t` +- Server fan-out (existing G-WS1/2) +- Apply remote if body ≠ local; `applying` flag suppresses echo +- Presence JSON on `room.presence` (`presence=True`) + +## Demo + +`examples/web-collab-doc/` — open two browsers on the same room. diff --git a/doc/design/ext-web.md b/doc/design/ext-web.md index e693255..60ae4fa 100644 --- a/doc/design/ext-web.md +++ b/doc/design/ext-web.md @@ -582,6 +582,7 @@ submit → action=insert → db.insert;action=update → db.update - Postgres / Redis / S3 驱动细节(SQLite 已落地); - ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`); - ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory); +- ~~实时协同编辑~~ → **Collab MVP** 见 [ext-web-collab.md](ext-web-collab.md)(WS room LWW 文本 + presence); - 子页路由糖的更多约定(`# 应用.route` 已够用)。 --- diff --git a/examples/web-collab-doc/README.md b/examples/web-collab-doc/README.md new file mode 100644 index 0000000..dafce54 --- /dev/null +++ b/examples/web-collab-doc/README.md @@ -0,0 +1,12 @@ +# web-collab-doc + +Two-browser collaborative notepad over WebSocket room (last-write-wins text). + +```bash +marqdo wasm build -o examples/web-collab-doc/static +cd examples/web-collab-doc +marqdo run index.mq.md +# open http://127.0.0.1:18094 twice +``` + +Design: [ext-web-collab.md](../../doc/design/ext-web-collab.md). diff --git a/examples/web-collab-doc/index.mq.md b/examples/web-collab-doc/index.mq.md new file mode 100644 index 0000000..b377757 --- /dev/null +++ b/examples/web-collab-doc/index.mq.md @@ -0,0 +1,24 @@ +--- +title: web-collab-doc +description: Two-browser collaborative plain-text editor over WS room (LWW snapshot sync) +import web:ext/web/web.mq.md +--- + +# main + +Collaborative notepad: open the page in two browsers; edits fan out via +`/live/{room}` WebSocket (mode=room + presence). Build WASM first: + +``` +marqdo wasm build -o examples/web-collab-doc/static +``` + +**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True** + +**`intro` = "

Room demo · open twice to co-edit.

presence: —

" + embed**
+
+**page = > web.page title="Collab doc" intro=intro layout="bare"**
+**app = > web.app page=page host="127.0.0.1" port=18094**
+**app = > app.static dir="static" mount="/static"**
+**app = > `app`.route_ws path="/live/{id}" mode="room" room_key="doc.{id}" presence=True**
+> `app`.listen
diff --git a/examples/web-collab-doc/static/client.mq.md b/examples/web-collab-doc/static/client.mq.md
new file mode 100644
index 0000000..b530b74
--- /dev/null
+++ b/examples/web-collab-doc/static/client.mq.md
@@ -0,0 +1,85 @@
+---
+title: collab client
+description: LWW text sync over WS room + presence (DOC\\t protocol)
+import browser:lib/browser.mq.md
+import table:lib/table.mq.md
+import text:lib/text.mq.md
+---
+
+# main
+
+**`ws_id` = "doc"**
+**`applying` = False**
+**`doc` = ""**
+
+`wire` =
+
+| @ | 选择器 | 事件 | 调用 | 值选择器 |
+|---|--------|------|------|----------|
+| 1 | "#doc" | input | on_edit | "#doc" |
+
+`open` =
+
+| op | id | url | then_open | then_message | then_error | then_close |
+|----|----|-----|-----------|--------------|------------|------------|
+| open | `ws_id` | "ws://127.0.0.1:18094/live/demo" | on_open | on_msg | on_err | on_close |
+
+**`w` = > table.put in=None at="wire" value=wire**
+**`ws` = > browser.ws spec=open**
+**`boot` = > browser.merge a=w b=ws**
+**`ready` = > browser.set_text sel="#log" text="connecting…"**
+*> browser.merge a=boot b=ready*
+
+## on_open
+    + `ok`=True
+
+*> browser.set_text sel="#log" text="ws open · room demo"*
+
+## on_err
+    + `error`=""
+
+**`msg` = "ws error: " + error**
+*> browser.set_text sel="#log" text=msg*
+
+## on_close
+*> browser.set_text sel="#log" text="ws closed"*
+
+## on_edit
+    + `value`=""
+
+1. `applying`
+    **`applying` = False**
+    ****
+2. *
+    **`doc` = value**
+    **`payload` = "DOC\t" + value**
+    `send` =
+
+    | op | id | data |
+    |----|----|------|
+    | send | `ws_id` | `payload` |
+
+    *> browser.ws spec=send*
+
+## on_msg
+    + `data`=""
+
+1. `data` != ""
+    **`is_pres` = > text.starts_with text=data prefix="{"**
+    1. `is_pres`
+        **`msg` = "presence: " + data**
+        *> browser.set_text sel="#presence" text=msg*
+    2. *
+        **`is_doc` = > text.starts_with text=data prefix="DOC\t"**
+        1. `is_doc`
+            **`remote` = > text.replace text=data old="DOC\t" new="" count=1**
+            1. `remote` != `doc`
+                **`doc` = remote**
+                **`applying` = True**
+                *> browser.set_value sel="#doc" value=remote*
+            2. *
+                ****
+        2. *
+            ****
+2. *
+    ****
diff --git a/tests/ext/web-collab-bag-smoke.mq.md b/tests/ext/web-collab-bag-smoke.mq.md
new file mode 100644
index 0000000..80d5739
--- /dev/null
+++ b/tests/ext/web-collab-bag-smoke.mq.md
@@ -0,0 +1,26 @@
+---
+title: web collab bag smoke
+description: route_ws room+presence for collab doc
+import web:ext/web/web.mq.md
+import json:lib/json.mq.md
+import sys:lib/sys.mq.md
+---
+
+# main
+
+**首页 = > web.page title="c"**
+**应用 = > web.app page=`首页` admin=False**
+**应用 = > `应用`.route_ws path="/live/{id}" mode="room" room_key="doc.{id}" presence=True**
+**routes = > json.get value=`应用` key="ws_routes"**
+**spec = > json.get value=`routes` key="/live/{id}"**
+**mode = > json.get value=`spec` key="mode"**
+**pr = > json.get value=`spec` key="presence"**
+1. `mode` == "room"
+  1. `pr` == True
+    > print text=collab-ws-bag-ok
+  2. *
+    > print text=presence-fail
+    > sys.exit code=1
+2. *
+  > print text=mode-fail
+  > sys.exit code=1