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