Make Web an executable handbook with recursive Markdown layouts

This commit is contained in:
cflmy committed 2026-11-08 21:50:01 +08:00
1 parent cc5277d2b5
commit 5080136d65
84 files changed
+3394 -957

No files matched your search

+3 -1
View File
@@ -186,8 +186,10 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../ext/web/网页.mq.md)
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页/索引.mq.md`](../../ext/web/网页/索引.mq.md)(作者门面仍为 `网页.mq.md`)
- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md)
- **Recursive practice:** home → nav/main/footer → footer brand/links → links docs/community; continue until a leaf is plain Markdown. Parents import children and declare one relationship. Use `component.markdown`, `component.wrap`, `layout.stack`, and `layout.columns`; merge alone gives siblings, not columns.
- **Runnable reference:** [web-layout-handbook](../../../examples/web-layout-handbook/index.mq.md) and [Chinese reference](../../../examples/web-layout-handbook-zh/index.mq.md). A composed Document declares `view: main` and returns node rows at startup; ordinary Documents keep their Markdown/data-source path. Use `inspect root=...` for disk routes, and `run` for a live server.
- EN author facade: `import web:ext/web/web.mq.md`
- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin`
+9 -1
View File
@@ -55,7 +55,7 @@ Import one file; use **that** file’s function names.
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/web/index.mq.md` · `web.mq.md` | `ext/web/网页/索引.mq.md` · `网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/index.mq.md` + modules | `ext/quantum/量子/索引.mq.md` + modules | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
@@ -64,6 +64,14 @@ Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names
Install: `marqdo ext add web` (`网页`). Native: `bash scripts/build-web-plugin.sh`.
Layout practice: split home into nav/main/footer; split footer into brand/links,
then links into docs/community until content leaves are ordinary Markdown.
Use `component.markdown|wrap`, `layout.stack|columns`, and @ record lists.
A parent value holds child rows of the same five-column View schema.
Explicit `view: main` Documents assemble once at startup; `inspect root=...`
scans disk declarations. See the Web root handbook and reference layout site.
| EN import | ZH import | Surface |
|-----------|-----------|---------|
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | facade: `page` · `route` · `serve` · `render` · `inspect` · `use` |
+2 -1
View File
@@ -210,7 +210,7 @@ Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08
## 13. 推广顺序(建议)
1. **已完成试点**:`ext/quantum/`(含 `量子/`)
2. **进行中**:`ext/web/` — 根 `index` + `layout` 布局铁律(文件划分、反 HTML 注入)已入库;facade 路径保持兼容;模块叙述与 call 金样继续补齐
2. **进行中**:`ext/web/` — 根 `index` + `layout` + 模块树 `page|route|…/index.mq.md` + 中文 `网页/`;作者门面 `web.mq.md`/`网页.mq.md` 保持兼容;call 金样与站点示例对齐继续补齐
3. **下一优先**:`linalg` 公式面、`ai` agent 面
4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade
@@ -223,4 +223,5 @@ Quantum 的完整实验、开发路线与源码示例门禁,见 [2026-11-08
| 日期 | 说明 |
|------|------|
| 2026-11-06 | web:模块树 + `网页/` 镜像 + page session call 金样推进 |
| 2026-11-06 | 初版:由 quantum 试点归纳的整包开发范式与验收清单 |
+3
View File
@@ -81,6 +81,7 @@ Welcome to the executable web.
| `type` | `类型` | `web` / `网页` |
| `route` | `路由` | 路径,可含 `{param}` |
| `method` | `方法` | 默认 `GET` |
| `view` | `视图` | 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用 |
| `title` | `标题` | 文档标题 / `<title>` |
| `data_source` | `数据源` | 表名 |
| `data_order` | `排序` | 如 `-created_at` |
@@ -97,6 +98,8 @@ Welcome to the executable web.
| title | title | Marqdo | | title |
```
2026-11-08:View 已支持 row/column 容器与 markdown 叶子,容器值保持子表;显式 `view: main` Document 通过普通函数装配。完整工程见[布局实践](ext-web-layout-paradigm.md),实现边界见[优化说明](ext-web-handbook.md)。
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
---
+71
View File
@@ -0,0 +1,71 @@
# Web:可执行手册与递归布局工程
| 项目 | 内容 |
|------|------|
| 日期 | 2026-11-08 |
| 使用与开发入口 | [英文 index](../../ext/web/index.mq.md) · [中文索引](../../ext/web/网页/索引.mq.md) |
| 工程规范 | [布局拆分](ext-web-layout-paradigm.md) |
| 参考工程 | [英文](../../examples/web-layout-handbook/index.mq.md) · [中文](../../examples/web-layout-handbook-zh/index.mq.md) |
| 自动验收 | [源手册与活站点](../../tests/web_handbook.rs) · [浏览器布局](../../tests/web/layout.browser.cjs) |
| 思想来源 | [next/010](../next/010.md) · [next/011](../next/011.md) · [next/012](../next/012.md) · [Quantum 优化](ext-quantum-handbook.md) |
## 原有规范为什么没有落实
原有 Web skill 已写「拆到简单」,但缺少可沿着文件树复现的工程。原生 `RenderNodes` 仅渲染平面 title/text/link/html;拼接两张表只产生兄弟节点,不会产生双栏。`serve` 又只把 Document 正文当 Markdown,没有执行文档里的组件装配。只加强口头禁止 HTML,无法补上这些实际缺口。
本轮以一个完整首页检验规范:导航、主体、页脚分开;页脚拆品牌与链接;链接再拆文档与社区。所有末端 content.md 都是普通 Markdown。每个父 index.mq.md 只负责其下一层排列关系。
## 使用同一份 View 表表示父与叶
沿用 `type | slot | value | attrs | style`,不新增核心语法、不建立第二套布局方言:
| 类型 | 值列 | 含义 |
|------|------|------|
| markdown / 正文 | Markdown 文本 | 内容叶子 |
| row / 横排 | 子节点列表 | 响应式分栏 |
| column / 纵排 | 子节点列表 | 上下排列 |
| nav/header/footer/section/aside | 子节点列表 | 语义区域 |
| 既有 title/text/link/html | 兼容原值 | 保留旧节点行为;html 为显式兼容边界 |
纯 `component.markdown` / `正文` 与 `component.wrap` / `包裹` 构造节点,`layout.stack` / `纵排` 和 `layout.columns` / `分栏` 声明几何。`merge` 接受 @ 记录列表,确定兄弟顺序并保留嵌套值;不再声称它会自动归一化所有列式表或把平面表变成双栏。
递归渲染保留节点类型,不把子表转成 `map[...]` 字符串。原生渲染器诊断无效子节点、列长不等和过深嵌套。运行时固定的布局样式提供基础响应式几何,样式列继续是类名引用,并非 CSS 编译器。叶子正文经过既有 Markdown 渲染器。
## 显式 Document 装配
普通 `type: web` 保留既有 Markdown/数据源路径。需要结构化页面时显式增加 `view: main`(中文 `视图: main`),普通 `# main` 返回 View 节点列表。`serve` 在启动时通过已有 `run_artifact` 回调执行装配,用与离线预览相同的渲染器生成文档,不再套入旧站点的另一份导航/页脚壳。
这是启动时装配,修改内容后重启;不声称具备自动请求期模板绑定。装配函数不再次调用渲染器或启动服务器。请求期业务仍用 Endpoint。自动 `data_source` 绑定使用普通 Document;与 `view: main` 混用会明确报错,避免静默忽略数据源。
`web.inspect root=...` / `网页.检视 根=...` 新增离线扫描入口,不启动进程也不执行组件。空应用的新进程无法读取另一个活进程的私有路由;手册不再将此作为活站点检视方法。检视结果加入 `_type: web_inspection`,使不同长度的 declared/system 列表保持对象语义,而不被 JSON 边界当作列式表。
## 手册与工具一致
另修复既有元数据型 Endpoint 在 Bytecode 没有函数时误报编译错误的问题:与 Tree 共用声明摘要路径,普通无入口程序仍然拒绝执行。
全部 Web 模块清理说明性伪函数,参数和返回契约均放在执行前;对象 API 保留。纯 DOM 构造与客户端描述不再无故加载插件。命令示例保护文本引号与会话美元引用。布尔/数字默认值与相邻标点分开,保证真正省略参数时仍符合契约。
原 `accept_component` 仅根据名称和职责就返回 ok=True,无法代表实际验收。现在返回明确的 checklist 状态,实际验收依据源码职责、渲染结构和运行结果。`site_playbook` 讲流程,`preview_markdown` / `preview_nodes` 给真实预览,不再把增加叙述字数当作完成指标。
## 验证
```bash
bash scripts/build-web-plugin.sh
cargo test --locked --test web_handbook
cargo test --locked --test call_cli web_
cargo test --locked --test gold ext_web -- --test-threads=1
```
手册门禁直接执行 18 份包内入口的双语 sh 围栏,在 Tree/Bytecode 共执行 80 次命令;同样执行根手册的作者程序。参考工程的双语双后端检查实际预览、启动服务,核对首页与预览相同、关于页仍走普通 Document、API 正常返回 JSON;不把路由声明误当作已经监听。
浏览器检查可对参考预览或活站点执行,按环境指定现有 Playwright 模块和 Chromium:
```bash
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
```
它测量 1440px 下的外层与内层双栏、390px 下的两层纵向折叠,并检查无横向溢出。无需外部资源或业务 JavaScript。Go 单元测试覆盖递归 Markdown、顺序、带类型列式表、错误形状与 Document 显式执行边界。
既有 Anlian 渲染测试已从硬编码个人数据库改为临时目录建表并注入已知数据,使完整 Go 套件无需个人站点状态。
全库 Rust 库级回归为 436 通过、25 失败,失败集中于外联内核与验证策略/回放;在隔离源码副本还原本轮三个核心文件后,失败集合完全一致,没有新增失败。Web 专项、全部 Web Go 测试、浏览器几何与 Quantum 手册回归通过。本轮没有把这些既有策略/回放失败混入布局修复。
+54 -113
View File
@@ -1,124 +1,65 @@
# Web 布局工程范式:文件划分 · 直到简单 · 禁止注入
# Web 布局工程:先拆布局,直到 Markdown 叶子
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-11-06 |
| 包内落地 | [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) |
| 上位 | [ext-web-artifact.md](ext-web-artifact.md) · ADR [0007](../adr/0007-web-document-endpoint.md) |
| 扩展范式 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) |
---
## 0. 一句话
> **页面不是一整块 HTML。页面是目录树上的若干 Document / 组件文件;每个文件只描述一层简单布局,复杂处继续拆文件,直到 View 表与 Markdown 都可读、可绑、可维护。**
值绑定、数据库绑定、样式绑定(`|type|slot|value|attrs|style|`)是默认语言。
**禁止**把「能跑」建立在 `dom.raw` / 大段 HTML 字符串 / 随意 CSS 注入上——那是逃逸舱,不是工程方法。
---
## 1. 为什么 AI 会走偏
网络扩展提供了绑定与 View 表,但代理常觉得「写 HTML/CSS 更快」,于是:
| 偏航 | 后果 |
| 项目 | 内容 |
|------|------|
| 首页一个文件塞满结构 | 无法复用导航/页脚;改一处炸全站 |
| `dom.raw` / `set_html` 拼页面 | 绕过绑定与主题;不可检视、不可 i18n 对齐 |
| 私有表方言 / `compose_*` | 与 ADR 0007 冲突;回归神对象 |
| 样式写进巨大 `<style>` | 与 `style` 列、主题表脱节 |
| 状态 | Active,2026-11-08 可执行参考工程与浏览器门禁已落地 |
| 包内手册 | [英文根入口](../../ext/web/index.mq.md) · [中文根入口](../../ext/web/网页/索引.mq.md) |
| 布局工具 | [layout](../../ext/web/layout/index.mq.md) · [布局](../../ext/web/布局/索引.mq.md) |
| 实现与边界 | [Web 手册优化](ext-web-handbook.md) · [Artifact](ext-web-artifact.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
本范式把**正确拆法写进扩展 skill 本身**,让冷启动代理先读规则再动手。
## 先建立区域树,再写内容
---
## 2. 文件划分布局(强制心智)
以站点首页为例,**先划文件,再写内容**:
首页先拆成导航、主体、页脚。页脚若有左右两栏,拆成品牌与链接;链接区若还有双栏,再拆成文档与社区。继续按内部独立布局拆分,直到叶子只剩简单 Markdown 可以直接表达的内容。
```text
site/
index.mq.md # type: web · route: / · 只编排「壳」与主区意图
pages/about.mq.md # 其它 Document
api/*.mq.md # Endpoint
components/
nav.mq.md # 顶栏(简单:品牌 + 链接表)
sidebar.mq.md # 侧栏(简单:列表或 TOC)
footer.mq.md # 底栏入口(若仍复杂 → 再拆)
footer/
brand.mq.md # 底栏左:品牌/版权
links.mq.md # 底栏右:链接双栏之一
styles/
theme.mq.md # 具名样式表(供 style 列引用)
data/ # 运行时库(gitignore)
index.mq.md → components/index.mq.md(纵排)
├─ nav/index.mq.md → content.md
├─ main/index.mq.md → content.md
└─ footer/index.mq.md(分栏)
├─ brand/index.mq.md → content.md
└─ links/index.mq.md(分栏)
├─ docs/index.mq.md → content.md
└─ community/index.mq.md → content.md
```
### 2.1 划分判据
父文件只导入子块、合并兄弟节点并声明一层排列。叶子文件只说明一种内容职责;内容较长时,使用相邻的普通 content.md,避免字符串转义。拆分终点不是行数或文件数量,更不是每句话建一个文件。
| 若出现… | 则… |
|---------|-----|
| 一个文件里同时有导航 + 主列 + 页脚 | 拆成 `components/*` + 页面正文 |
| 页脚已是「左品牌右双栏链接 + 复杂样式」 | 再拆 `footer/brand` · `footer/links`,各文件只保留一张简单 View 表或短 Markdown |
| View 表超过约一屏且多段语义 | 按槽位/区域拆文件,用 `component.merge` 或页面级 import 组合 |
| 想写 `<div class=…>` 才能对齐 | 先问能否用 `type/slot/style`;不能再考虑逃逸舱并注明原因 |
## 何时继续拆、何时停止
### 2.2 简单的定义
一个组件文件「够简单」当且仅当:
- 人一眼能说出**单一职责**(例如「仅顶栏链接」);
- 主数据是 **一张** View 表或短 Markdown,而不是嵌套 HTML;
- 样式只通过 **具名 style**(主题表)或 `style` 列引用,不内嵌大段 CSS。
---
## 3. 合法装配面(唯一主路径)
| 允许 | 禁止(默认路径) |
|------|------------------|
| Document Metadata:`type: web` · `route` · `data_source` … | 隐式用户路由;`configure` 垃圾抽屉 |
| 正文 Markdown | 把整页写成 HTML 字符串 |
| View 表 `\|type\|slot\|value\|attrs\|style\|`(ZH 别名可) | `compose_*`;`\|属性\|值\|样式\|` 等废止方言当主装配 |
| `component.nodes` / `component.merge` | `json.set` 袋胶水拼 DOM |
| `web.render` / `page.render` | 作者 `ensure_plugin` / `host_*` |
| `dom.raw` / `page.css` **仅逃逸舱**(须注释「为何不能表驱动」) | 用 raw/css 作为首页主实现 |
数据与鉴权在 `ext/data` · `ext/security`;实时在 `ext/net`——不要塞回 `ext/web` facade。
---
## 4. 智能体操作顺序
冷启动只读 [`ext/web/index.mq.md`](../../ext/web/index.mq.md):
| 若你需要 | 这样做 |
|----------|--------|
| 理解怎么拆页面 | 打开 `ext/web/layout/index.mq.md`,先 `marqdo call … rules` |
| 预览 Document HTML | `web.render` / `网页.渲染`(`--effects plugin`) |
| 起站 | 站点 `serve.mq.md` → `web.serve`;或 call facade `serve` |
| 检视路由 | `web.inspect` |
写站时循环:
1. 列出区域(导航 / 侧栏 / 主区 / 底栏…)→ 各建文件
2. 每个文件只做简单 View 或 Markdown
3. 复杂区域继续拆,直到简单
4. 页面 Document 只保留路由、数据源与主区意图;壳由组件组合
5. 绝不先写 HTML 再「补绑定」
---
## 5. 与 skill=tools 迁移
`ext/web` 按 [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) 迁移:根 `index` = SKILL,`layout` = 布局工程工具面,原有 `page`/`route`/… 补齐 For AI agents 与叙述占比。
**布局范式是 web 包特有硬约束**,与 quantum 试点并列写入扩展内,而不是只写在外部 README。
---
## 6. 修订历史
| 日期 | 说明 |
| 观察 | 决定 |
|------|------|
| 2026-11-06 | 初版:文件划分布局、反 HTML/CSS 注入、与 Artifact / skill=tools 对齐 |
| 导航、正文、页脚混在一个内容块 | 拆成父级装配和三个职责块 |
| 页脚内部仍同时负责品牌与链接排布 | 再拆左右子块 |
| 链接子块内部仍包含两个独立栏目 | 继续拆到各栏目 Markdown |
| 叶子只包含标题、段落、列表、链接、表格、图片 | 停止;已可用普通 Markdown 表达 |
| 父文件含大量正文、HTML 标签、CSS 字符串 | 职责或表达方式仍未收敛,继续拆解 |
| 结构已经简单,只为减少行数而再拆 | 不必拆;以可读职责为准 |
表单、数据源、交互各有自己的领域职责,应调用对应模块,不以“Markdown 不表达交互”为由恢复整页 HTML 壳。只有确实需要兼容宿主能力时,才在隔离边界使用已有 raw/css 接口并说明原因。
## 同一表结构贯穿所有层
公共列是 `type | slot | value | attrs | style`,中文可用 `类型 | 槽 | 值 | 属性 | 样式`。使用 @ 记录表产生节点列表。
- `component.markdown` / `组件.正文`:叶子值为普通 Markdown。
- `component.wrap` / `组件.包裹`:值中保留子节点列表,可标记 nav/footer/section 等语义区域。
- `layout.stack` / `布局.纵排`:声明上下关系。
- `layout.columns` / `布局.分栏`:声明响应式横向栏目。
- `merge`:只确定兄弟顺序,不会自动产生双栏,也不提前渲染 HTML。
原生运行时提供基本布局几何,窄屏自动折叠。style 列引用类名,不承载 CSS 源码,也不会自动定义主题。父块始终保留结构值;先渲染子块再拼 HTML 会丢失这条统一路径。
## 从文件走到真正页面
[英文参考工程](../../examples/web-layout-handbook/index.mq.md)与[中文参考工程](../../examples/web-layout-handbook-zh/index.mq.md)实现上面的整个拆分树。先运行 preview.mq.md 检查真实渲染,再进入工程目录运行 serve.mq.md。
结构化 Document 显式声明 `view: main` / `视图: main`,main 返回节点;服务启动时装配一次。普通 Markdown Document 保留既有行为,Endpoint 单独处理请求期互动。改动结构或叶子内容后重启。自动数据源绑定继续使用普通 Document,避免与启动装配混用。
验收同时检查源码和产物:叶子只含普通 Markdown,父文件只表达其一层关系;桌面页脚出现真正的两层分栏,手机两层都折叠;关于页、API 仍能工作。规则清单本身不是“已经通过”的证明。
```bash
cargo test --locked --test web_handbook
node tests/web/layout.browser.cjs /absolute/path/to/preview.html
```
详细测试方式和当前能力边界见[优化记录](ext-web-handbook.md)。
+22
View File
@@ -0,0 +1,22 @@
# Layout decomposition reference
Read [the page](index.mq.md), then follow [components](components/index.mq.md) to
navigation, main and footer. Footer splits into brand and links; links splits
again into docs and community. Every terminal content.md is plain Markdown.
Parent .mq.md files only load/compose child rows and choose one relationship.
From the repository root, preview with:
```bash
marqdo run examples/web-layout-handbook-zh/preview.mq.md
```
To serve, change into this directory, then run:
```bash
marqdo run serve.mq.md
```
Check /, /about and /api/ping. Geometry comes from the runtime's row/column
containers. No authored HTML or CSS is needed. view: main is evaluated once at
startup; restart after edits. Request-time interaction belongs in Endpoints.
@@ -0,0 +1,18 @@
---
markup: occlusion
类型: 端点
路径: /api/ping
方法: GET
请求: none
响应: json
---
# main
`result` =
| ok | ping |
|----|------|
| True | pong |
*result*
@@ -0,0 +1,3 @@
### Marqdo
代码即文档,文档即可执行。
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/brand 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/brand/content.md"**
*> 组件.正文 文本=`body` 槽="footer-brand"*
@@ -0,0 +1,24 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
brand: ./brand/index.mq.md
links: ./links/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排品牌内容与链接子树之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**brand_nodes = > brand.节点**
**links_nodes = > links.节点**
**siblings = 组件.合并 甲=`brand_nodes` 乙=`links_nodes`**
**footer_columns = 布局.分栏 子节点=`siblings` 槽="footer"**
*> 组件.包裹 子节点=`footer_columns` 种类="footer" 槽="footer"*
@@ -0,0 +1,5 @@
### 社区
[关于项目](/about)
[返回首页](/)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/links/community 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/links/community/content.md"**
*> 组件.正文 文本=`body` 槽="footer-links-community"*
@@ -0,0 +1,5 @@
### 文档
[开发手册](/about)
[服务状态](/api/ping)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责footer/links/docs 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/footer/links/docs/content.md"**
*> 组件.正文 文本=`body` 槽="footer-links-docs"*
@@ -0,0 +1,23 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
docs: ./docs/index.mq.md
community: ./community/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排文档链接与社区链接之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**docs_nodes = > docs.节点**
**community_nodes = > community.节点**
**siblings = 组件.合并 甲=`docs_nodes` 乙=`community_nodes`**
*> 布局.分栏 子节点=`siblings` 槽="footer-links"*
@@ -0,0 +1,26 @@
---
markup: occlusion
import:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
nav: ./nav/index.mq.md
content: ./main/index.mq.md
footer: ./footer/index.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
本层只安排导航、主体、页脚之间的关系,正文仍留在对应 Markdown 叶子中。
若子块仍含独立分栏,就继续沿对应目录的 index.mq.md 分解。
不要把渲染后的字符串放回值列,子节点在整个装配过程中保持结构。
**nav_nodes = > nav.节点**
**content_nodes = > content.节点**
**footer_nodes = > footer.节点**
**upper_regions = 组件.合并 甲=`nav_nodes` 乙=`content_nodes`**
**home_regions = 组件.合并 甲=`upper_regions` 乙=`footer_nodes`**
*> 布局.纵排 子节点=`home_regions` 槽="home"*
@@ -0,0 +1,3 @@
# 可执行文档站点
先拆布局,再写内容。**叶子只负责 Markdown。**
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责main 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/main/content.md"**
*> 组件.正文 文本=`body` 槽="main"*
@@ -0,0 +1 @@
[首页](/) · [关于](/about) · [状态](/api/ping)
@@ -0,0 +1,18 @@
---
markup: occlusion
import:
文件: lib/文件.mq.md
组件: ext/web/网页/组件/索引.mq.md
---
## 节点
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
此叶子只负责nav 的 Markdown 内容,父组件决定排列。修改文字只改相邻 content.md,
不添加 HTML 标签或内部分栏;出现第二种布局职责时再开子目录。
**body = 文件.读文本 路径="components/nav/content.md"**
*> 组件.正文 文本=`body` 槽="nav"*
@@ -0,0 +1,16 @@
---
markup: occlusion
类型: 网页
视图: main
标题: Marqdo 布局实践
路由: /
import:
home: ./components/index.mq.md
---
# main
页面只选择布局根,具体拆分沿 components/index.mq.md 继续。
此主程序返回结构而不是 HTML;view 元数据让服务在启动时执行它。
*> home.节点*
@@ -0,0 +1,10 @@
---
markup: occlusion
类型: 网页
标题: 关于
路由: /about
---
# 关于
这是普通 Markdown Document,不执行布局函数。
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
home: ./components/index.mq.md
网页: ext/web/网页.mq.md
---
# main
**nodes = > home.节点**
**html = 网页.渲染 节点=`nodes` 标题="Marqdo 布局实践"**
> 打印 内容=`html`
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
网页: ext/web/网页.mq.md
---
# main
端口 `端口`=18081 可通过 --bind 覆盖。启动器不包含页面布局。
**监听端口 = 整数 值=`端口`**
> 网页.服务 根="." 主机="127.0.0.1" 端口=`监听端口`
+22
View File
@@ -0,0 +1,22 @@
# Layout decomposition reference
Read [the page](index.mq.md), then follow [components](components/index.mq.md) to
navigation, main and footer. Footer splits into brand and links; links splits
again into docs and community. Every terminal content.md is plain Markdown.
Parent .mq.md files only load/compose child rows and choose one relationship.
From the repository root, preview with:
```bash
marqdo run examples/web-layout-handbook/preview.mq.md
```
To serve, change into this directory, then run:
```bash
marqdo run serve.mq.md
```
Check /, /about and /api/ping. Geometry comes from the runtime's row/column
containers. No authored HTML or CSS is needed. view: main is evaluated once at
startup; restart after edits. Request-time interaction belongs in Endpoints.
@@ -0,0 +1,18 @@
---
markup: occlusion
type: endpoint
path: /api/ping
method: GET
request: none
response: json
---
# main
`result` =
| ok | ping |
|----|------|
| True | pong |
*result*
@@ -0,0 +1,3 @@
### Marqdo
Code is documentation. Documents are executable.
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/brand Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/brand/content.md"**
*> component.markdown text=`body` slot="footer-brand"*
@@ -0,0 +1,24 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
brand: ./brand/index.mq.md
links: ./links/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges brand content and the link-region subtree. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**brand_nodes = > brand.nodes**
**links_nodes = > links.nodes**
**siblings = component.merge a=`brand_nodes` b=`links_nodes`**
**footer_columns = layout.columns children=`siblings` slot="footer"**
*> component.wrap children=`footer_columns` kind="footer" slot="footer"*
@@ -0,0 +1,5 @@
### Community
[About the project](/about)
[Return home](/)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/links/community Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/links/community/content.md"**
*> component.markdown text=`body` slot="footer-links-community"*
@@ -0,0 +1,5 @@
### Documentation
[Handbook](/about)
[Service status](/api/ping)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the footer/links/docs Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/footer/links/docs/content.md"**
*> component.markdown text=`body` slot="footer-links-docs"*
@@ -0,0 +1,23 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
docs: ./docs/index.mq.md
community: ./community/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges documentation links and community links. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**docs_nodes = > docs.nodes**
**community_nodes = > community.nodes**
**siblings = component.merge a=`docs_nodes` b=`community_nodes`**
*> layout.columns children=`siblings` slot="footer-links"*
@@ -0,0 +1,26 @@
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
nav: ./nav/index.mq.md
content: ./main/index.mq.md
footer: ./footer/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Nested child rows |
This parent arranges navigation, main content and footer. Content stays
in their Markdown leaves; this file owns their one placement relationship. Continue into each child index when another independent layout
remains. Preserve node lists rather than rendering children into HTML strings.
**nav_nodes = > nav.nodes**
**content_nodes = > content.nodes**
**footer_nodes = > footer.nodes**
**upper_regions = component.merge a=`nav_nodes` b=`content_nodes`**
**home_regions = component.merge a=`upper_regions` b=`footer_nodes`**
*> layout.stack children=`home_regions` slot="home"*
@@ -0,0 +1,3 @@
# Executable documents
Split the layout before writing content. **Leaves own Markdown only.**
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the main Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/main/content.md"**
*> component.markdown text=`body` slot="main"*
@@ -0,0 +1 @@
[Home](/) · [About](/about) · [Status](/api/ping)
@@ -0,0 +1,19 @@
---
markup: occlusion
import:
fs: lib/fs.mq.md
component: ext/web/component/index.mq.md
---
## nodes
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Markdown leaf rows |
This leaf owns only the nav Markdown content; its parent owns placement.
Edit adjacent content.md to change prose. Add a child directory when a second
layout responsibility appears instead of introducing HTML into the content.
**body = fs.read_text path="components/nav/content.md"**
*> component.markdown text=`body` slot="nav"*
+16
View File
@@ -0,0 +1,16 @@
---
markup: occlusion
type: web
view: main
title: Marqdo layout handbook
route: /
import:
home: ./components/index.mq.md
---
# main
The page selects the layout root; follow components/index.mq.md for decomposition.
This main returns rows rather than HTML; view metadata opts into startup assembly.
*> home.nodes*
@@ -0,0 +1,10 @@
---
markup: occlusion
type: web
title: About
route: /about
---
# About
An ordinary Markdown Document keeps its original rendering path.
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
home: ./components/index.mq.md
web: ext/web/web.mq.md
---
# main
**nodes = > home.nodes**
**html = web.render nodes=`nodes` title="Marqdo layout handbook"**
> print text=`html`
+12
View File
@@ -0,0 +1,12 @@
---
markup: occlusion
import:
web: ext/web/web.mq.md
---
# main
The `port`=18081 may be overridden with --bind. This launcher owns no layout.
**listen_port = int value=`port`**
> web.serve root="." host="127.0.0.1" port=`listen_port`
+18 -2
View File
@@ -10,9 +10,12 @@ Official dynamic site extension (**ADR 0007**).
| Surface | Path |
|---------|------|
| EN root skill (agents first) | `ext/web/index.mq.md` |
| EN root skill (zero-context site playbook) | `ext/web/index.mq.md` |
| EN author facade | `import web:ext/web/web.mq.md` |
| ZH root / facade | `导入 网页:ext/web/网页.mq.md` |
| ZH root skill (zero-context playbook) | `ext/web/网页/索引.mq.md` |
| ZH author facade | `导入 网页:ext/web/网页.mq.md` |
| Modules | `page/` · `route/` · `component/` · `dom/` · `client/` · `layout/` |
| ZH modules | `网页/页面/` · `网页/路由/` · `网页/组件/` · … |
| Layout tools | `ext/web/layout/index.mq.md` · `ext/web/布局/索引.mq.md` |
**Facade:** `page` · `route` · `serve` · `render` · `inspect` · `use`
@@ -25,7 +28,20 @@ Official dynamic site extension (**ADR 0007**).
bash scripts/build-web-plugin.sh
marqdo ext add web
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/index.mq.md preview_markdown 'body="# Hi"' 'title="Demo"' --effects plugin --json
marqdo run examples/marqdo-blog/serve.mq.md
```
Hard rules: no author `ensure_plugin` / `compose_*` / `configure` junk drawer; View schema only; declared vs system routes via `inspect`; no `MARQDO_EXT=repo/ext` self-install.
The [executable handbook](index.mq.md) and [Chinese handbook](网页/索引.mq.md)
now include recursive layout constructors and tested source examples. Start with
[the reference site](../../examples/web-layout-handbook/index.mq.md): parents
compose one relationship, terminal content.md files stay ordinary Markdown.
The footer splits into brand/links, and links splits again into docs/community.
See [implementation and acceptance](../../doc/design/ext-web-handbook.md).
Composed Documents explicitly declare `view: main`; main returns nested View
rows for startup assembly. Ordinary Markdown Documents keep their existing path.
Use `web.inspect root=...` to scan disk declarations; empty fresh app state cannot
inspect another process. `call` previews, while `run serve.mq.md` starts a server.
-20
View File
@@ -1,20 +0,0 @@
---
markup: occlusion
title: ext/web/_capability
description: Internal — load native web plugin once. Authors must not call this; import web = capability (ADR 0007).
import:
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
---
## load
Load ABI v2 `web` plugin if present. Fail loud when missing.
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/web: native web plugin not found (build plugins/web or marqdo ext add web)
> sys.exit code=1
****
+44
View File
@@ -0,0 +1,44 @@
---
markup: occlusion
title: ext/web/_capability
description: >-
Web ABI load skill. Prefer domain modules; call load when diagnosing plugins.
import:
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
---
This boundary loads the native Go web plugin. Domain render/server tools load
it automatically; pure layout and component constructors do not need it.
```sh
marqdo call ext/web/_capability/index.mq.md load --effects plugin --json
```
Build with bash scripts/build-web-plugin.sh, or install with marqdo ext add web.
For local development set MARQDO_WEB_PLUGIN to the built library's absolute path.
Success returns null; missing libraries also require checking process status.
Only this boundary imports lib/plugin, including through the Chinese facade.
## load
Locate the ABI v2 web shared library through plugin.native_path, then
plugin.load it. If the library is missing, print a short install hint and exit
non-zero so CI and agents fail loudly. After a successful load, later web star
names are available in this process. This is the only sanctioned place in the
package that talks to lib/plugin for web. Domain skills call load at the start
of each tool that needs the native server or renderer.
This tool takes no parameters.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | null after a successful load |
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/web: native web plugin not found (build plugins/web or marqdo ext add web)
> sys.exit code=1
****
-52
View File
@@ -1,52 +0,0 @@
---
markup: occlusion
title: ext/web/client
description: Browser Runtime helpers (WASM bridge). Prefer lib/browser for effect tables (ADR 0007).
import:
cap: ext/web/_capability.mq.md
table: lib/table.mq.md
---
## embed
+ `bridge`="/static/marqdo-bridge.js"
+ `wasm`="/static/marqdo_wasm.wasm"
+ `source`=""
+ `boot`=True
HTML snippet that loads the official browser Marqdo bridge (route C/D). With `boot` and non-empty `source`, auto-mounts. No author JS.
> cap.load
1. `boot`
1. `source` != ""
*"<script type=\"module\" src=\"" + bridge + "\" data-mq-wasm=\"" + wasm + "\" data-mq-source-url=\"" + source + "\"></script>"*
2. *
*"<script type=\"module\" src=\"" + bridge + "\"></script>"*
2. *
*"<script type=\"module\" src=\"" + bridge + "\" data-mq-no-boot=\"1\"></script>"*
## text_patch
+ `sel`
+ `text`
`set_text` effects map. Prefer `lib/browser` in client `.mq.md`.
**`m` = > table.put in=None at=sel value=text**
*> table.put in=None at="set_text" value=m*
## dom_patch
+ `sel`
+ `html`=""
+ `attrs`=None
+ `remove`=False
**`spec` = > table.put in=None at="html" value=html**
1. `attrs`
**`spec` = > table.put in=`spec` at="attrs" value=attrs**
2. *
**_ = 1**
1. `remove`
**`spec` = > table.put in=`spec` at="remove" value=True**
2. *
**_ = 1**
**`m` = > table.put in=None at=sel value=spec**
*> table.put in=None at="dom" value=m*
+94
View File
@@ -0,0 +1,94 @@
---
markup: occlusion
title: ext/web/client
description: Browser Runtime helpers (WASM bridge). Prefer lib/browser for effect tables (ADR 0007).
import:
cap: ext/web/_capability/index.mq.md
table: lib/table.mq.md
---
Browser helpers describe the official Marqdo WASM bridge and small effects.
They construct text/maps without a native server. Keep initial page layout in
[layout components](../layout/index.mq.md), and use lib/browser for client logic.
```sh
marqdo call ext/web/client/index.mq.md embed --json
marqdo call ext/web/client/index.mq.md text_patch 'sel="#status"' 'text="Ready"' --json
```
The bridge and WASM assets must actually be hosted at the chosen URLs. embed
returns a loading descriptor; it does not install assets or implement business
JavaScript. Native HTML snippets here are runtime integration, not an invitation
to put complete navigation/footer markup in authored content. Changes require
browser bridge tests and matching Chinese entry points.
## embed
| 参数 | 类型 | 说明 |
|------|------|------|
| bridge | text | bridge script URL |
| wasm | text | wasm URL |
| source | text | optional source URL |
| boot | bool | auto boot |
HTML snippet that loads the official browser Marqdo bridge (route C/D). Defaults:
`bridge`="/static/marqdo-bridge.js", `wasm`="/static/marqdo_wasm.wasm",
`source`="", `boot`=True . With boot and non-empty source, auto-mounts. No author
JS. Not a substitute for file-partitioned Document layout.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | HTML script tag |
1. `boot`
1. `source` != ""
*"<script type=\"module\" src=\"" + bridge + "\" data-mq-wasm=\"" + wasm + "\" data-mq-source-url=\"" + source + "\"></script>"*
2. *
*"<script type=\"module\" src=\"" + bridge + "\"></script>"*
2. *
*"<script type=\"module\" src=\"" + bridge + "\" data-mq-no-boot=\"1\"></script>"*
## text_patch
| 参数 | 类型 | 说明 |
|------|------|------|
| sel | text | CSS selector |
| text | text | text content |
Build a `set_text` effects map for selector `sel` with string `text`. Prefer
lib/browser in client .mq.md programs; this helper is for call-side sketches.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | effects map |
**`m` = > table.put in=None at=sel value=text**
*> table.put in=None at="set_text" value=m*
## dom_patch
| 参数 | 类型 | 说明 |
|------|------|------|
| sel | text | CSS selector |
| html | text | optional HTML |
| attrs | any | optional attrs map |
| remove | bool | remove node |
Build a `dom` effects map for selector `sel`. Optional `html`="", `attrs`=None,
`remove`=False . Prefer View/Markdown over raw html patches for page shells.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | effects map |
**`spec` = > table.put in=None at="html" value=html**
1. `attrs`
**`spec` = > table.put in=`spec` at="attrs" value=attrs**
2. *
**_ = 1**
1. `remove`
**`spec` = > table.put in=`spec` at="remove" value=True**
2. *
**_ = 1**
**`m` = > table.put in=None at=sel value=spec**
*> table.put in=None at="dom" value=m*
-57
View File
@@ -1,57 +0,0 @@
---
markup: occlusion
title: ext/web/component
description: >-
Reusable Document fragments as View node tables (ADR 0007). One file, one duty;
merge simple parts instead of writing HTML.
import:
table: lib/table.mq.md
---
Components are how file-partitioned layouts stay simple. Each component file
should expose one View table (or short Markdown consumed elsewhere). When a
footer needs two columns, use two component files and `merge` — do not embed a
mini-HTML layout in one cell.
## For AI agents
Call example (plain text):
marqdo call ext/web/layout/index.mq.md accept_component name="footer-links" duty="right link column only" --json
Prefer authoring separate tables then merge. No plugin required for nodes/merge.
*None*
## nodes
+ `table`
Identity helper — a component is a View table `|type|slot|value|attrs|style|`.
Keep the table small enough that a human sees a single region.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | View table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | same table |
*table*
## merge
+ `a`
+ `b`
Concatenate two View node lists (list-of-maps or column tables). Use after
splitting regions into files. Prefer many small tables over one private dialect.
| 参数 | 类型 | 说明 |
|------|------|------|
| a | any | first nodes |
| b | any | second nodes |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | concatenated nodes |
*> table.concat a=`a` b=`b`*
+117
View File
@@ -0,0 +1,117 @@
---
markup: occlusion
title: ext/web/component
description: Pure components: Markdown leaves and nested View rows.
import:
table: lib/table.mq.md
---
Components are ordinary functions returning View rows. A leaf contains Markdown;
a parent names its child components and one layout relationship. Stop splitting
when one file expresses one readable content responsibility. If a footer has a
brand area and a link area, split those; if links has two columns, split again.
The executable reference is [web-layout-handbook](../../../examples/web-layout-handbook/index.mq.md).
Pure construction experiment — no native plugin or session is required:
```sh
marqdo call ext/web/component/index.mq.md markdown 'text="## A readable leaf"' 'slot="intro"' --json
marqdo call ext/web/component/index.mq.md wrap 'children=[{"type":"markdown","value":"Left"},{"type":"markdown","value":"Right"}]' 'kind="row"' --json
marqdo call ext/web/component/index.mq.md merge 'a=[{"type":"text","value":"First"}]' 'b=[{"type":"text","value":"Second"}]' --json
```
Use @ record tables to return lists of node maps. merge concatenates these lists;
it does not turn a flat table into columns. wrap keeps child rows in value;
[layout](../layout/index.mq.md) supplies stack and columns helpers for the same
schema. Only [page.render](../page/index.mq.md) needs the native renderer.
Development route: add reusable content in the site's component directories;
add a new structural kind only when stack, columns and Markdown cannot express
it. Update the Go artifact renderer and its tests, then both language helpers.
Never put rendered HTML strings in parent value cells to simulate nesting.
## nodes
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | View table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Result |
Return View `table` unchanged. This preserves the existing identity helper for
column tables as well as record lists. Prefer @ record lists for reusable
components, because list composition can retain typed nested value cells.
*table*
## merge
| 参数 | 类型 | 说明 |
|------|------|------|
| a | list | First node record list |
| b | list | Second node record list |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Ordered sibling rows |
Concatenate `a` and `b` without rendering or flattening child containers.
Both inputs must be lists of View rows, normally @ record tables. To place
two components side by side, concatenate their wrapped columns then use
layout.columns; concatenation alone only establishes sibling order.
*> table.concat a=`a` b=`b`*
## markdown
| 参数 | 类型 | 说明 |
|------|------|------|
| text | text | Plain Markdown content |
| slot | text | Stable component name |
| style | text | Optional class name |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | One Markdown leaf |
Make a leaf from Markdown `text`. Default `slot`="" and `style`="" keep
content independent of placement and theme. The returned list contains one
markdown row; the runtime renders headings, links, lists and tables. No native
plugin is loaded here, and no HTML is inserted into the authored component.
`nodes` =
| @ | type | slot | value | attrs | style |
|---|------|------|-------|-------|-------|
| 1 | markdown | `slot` | `text` | "" | `style` |
*nodes*
## wrap
| 参数 | 类型 | 说明 |
|------|------|------|
| children | list | Child node records |
| kind | text | Container kind |
| slot | text | Stable region name |
| style | text | Optional class name |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | One parent containing its child rows |
Wrap `children` in one structural row. Default `kind`="column", `slot`=""
and `style`="" . Use row or column for geometry, nav/header/footer/section/aside
for a semantic region. The value cell holds the child list itself, not rendered
HTML. The native renderer diagnoses unknown child shapes at the render boundary;
this pure constructor does not claim to validate a full site.
`nodes` =
| @ | type | slot | value | attrs | style |
|---|------|------|-------|-------|-------|
| 1 | `kind` | `slot` | `children` | "" | `style` |
*nodes*
+24 -27
View File
@@ -5,73 +5,70 @@ description: >-
DOM Artifact — Markdown/body to structure; raw HTML is escape hatch only
(ADR 0007). Never use raw as the default homepage method.
import:
cap: ext/web/_capability.mq.md
cap: ext/web/_capability/index.mq.md
table: lib/table.mq.md
---
## For AI agents
DOM helpers separate Markdown content from HTML rendering. Prefer
[component.markdown](../component/index.mq.md) for layout leaves. from_markdown
and raw only construct data and need no plugin; render needs --effects plugin.
Prefer `from_markdown` and View tables from `ext/web/layout` / `component`.
`raw` is an escape hatch: if you call it for a whole page shell, you are
violating the layout law in `ext/web/index.mq.md`. Always `--effects plugin`
for render paths.
```sh
marqdo call ext/web/dom/index.mq.md from_markdown 'text="# Readable"' --session handbook --toget body --json
marqdo call ext/web/dom/index.mq.md render 'dom=$body' --effects plugin --session handbook --json
```
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
*None*
raw remains an explicit compatibility escape hatch, not a homepage layout
method. Add content behavior through Markdown/render and preserve the existing
raw path; do not use raw to compensate for missing decomposition.
## from_markdown
+ `text`
Turn Markdown text into a simple DOM map `{kind:"markdown", text}` for `page.render` / `web.render`.
This is the default body path for Document prose.
| 参数 | 类型 | 说明 |
|------|------|------|
| text | text | Markdown source |
Turn Markdown `text` into a simple DOM map `{kind:"markdown", text}` for
`page.render` / `web.render`. This is the default body path for Document prose.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM map |
> cap.load
**`out` = > table.put in=None at="kind" value="markdown"**
*> table.put in=`out` at="text" value=text*
## raw
+ `html`
Escape hatch — wrap a raw HTML string. Prefer Markdown / View nodes. Allowed only
when table-driven layout cannot express a host constraint; document the why next
to the call. Forbidden as the primary implementation of nav/sidebar/footer/home.
| 参数 | 类型 | 说明 |
|------|------|------|
| html | text | raw HTML (escape hatch) |
Escape hatch — wrap raw `html`. Prefer Markdown / View nodes. Allowed only when
table-driven layout cannot express a host constraint; document the why next to
the call. Forbidden as the primary implementation of nav/sidebar/footer/home.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM map kind=raw |
> cap.load
**`out` = > table.put in=None at="kind" value="raw"**
*> table.put in=`out` at="html" value=html*
## render
+ `dom`
Render DOM Artifact `dom` to HTML via the native plugin. When kind is markdown,
| 参数 | 类型 | 说明 |
|------|------|------|
| dom | any | DOM map from from_markdown or raw |
Render DOM Artifact `dom` (from from_markdown or raw) to HTML via the native
plugin. When kind is markdown,
the plugin turns Markdown text into HTML for Document preview. When kind is raw,
the stored HTML string is returned unchanged — that path exists only for the
escape hatch documented on raw, not for assembling a full site shell. Prefer
feeding markdown DOM produced by from_markdown, or skip this helper and use
page.render / web.render on View tables from file-partitioned components.
| 参数 | 类型 | 说明 |
|------|------|------|
| dom | any | DOM map from from_markdown or raw |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML text |
+206 -93
View File
@@ -1,134 +1,247 @@
---
markup: occlusion
title: ext/web
description: >-
Web Artifact root skill (ADR 0007). Read this first. Layout is file-partitioned;
tools run with marqdo call. No HTML/CSS injection as the default page method.
description: Executable web handbook: decompose layout down to Markdown leaves.
import:
layout: ext/web/layout/index.mq.md
page: ext/web/page.mq.md
route: ext/web/route.mq.md
component: ext/web/component.mq.md
dom: ext/web/dom.mq.md
client: ext/web/client.mq.md
web: ext/web/web.mq.md
---
This file is the root skill for the Marqdo web package. If you are an AI agent
with no other Marqdo context, follow Choose a path, then Layout law, then How to
execute any tool. Do not invent MCP wrappers, raw HTML homepages, or a second
API. The Markdown ## headings are the tools. Author programs may still
`import web:ext/web/web.mq.md` for the facade; agents should start here.
Web handbook — split page structure first, author content second, then preview,
serve and verify. Ordinary .mq.md functions are the tools; no separate Skill
compiler or manifest is needed. Install with marqdo ext add web. In this source
repo build with bash scripts/build-web-plugin.sh and optionally select its
absolute path with MARQDO_WEB_PLUGIN. Keep installation outside source ext.
## Choose a path
Start with executable evidence
Pick one row. Do not mix English and Chinese tool names or trees.
Run these from the repository root; installed users replace FILE with its actual
installed path. Preserve the inner text quotes and protect dollar references
from shell expansion. Inspect process status and ok before consuming result.
| If you need | Do this |
|-------------|---------|
| Layout rules before writing files | Call `layout.rules` on `ext/web/layout/index.mq.md` (command below). |
| Preview HTML for a Document / View table | Call `web.render` via facade path or import `web` tools with `--effects plugin`. |
| Serve a site root | Author `serve.mq.md` calling `web.serve`, or call serve with `root=` · `port=`. |
| Chinese tool names | Open `ext/web/网页.mq.md` and stay in Chinese names. |
```sh
marqdo call ext/web/index.mq.md layout_rules --json
marqdo call ext/web/index.mq.md preview_markdown 'body="# Readable page"' 'title="Preview"' --effects plugin --json
marqdo call ext/web/index.mq.md preview_nodes 'nodes=[{"type":"row","value":[{"type":"markdown","value":"## Left"},{"type":"markdown","value":"## Right"}]}]' --effects plugin --json
```
Agents use `##` tools with `marqdo call`. `# page` / `# route` / `# app` objects
are for author programs. Escape hatches `dom.raw` and `page.css` are not the
default path for building a homepage.
The engineering method: recursively decompose to Markdown leaves
*None*
Split home into navigation, main and footer. Split a two-region footer into
brand and links. If links still contains two columns, split it again into docs
and community. Continue while a block needs independent internal layout. Stop
at one simple Markdown responsibility, not at one file per paragraph.
## Layout law
```text
site/
index.mq.md Document selects the layout root
components/index.mq.md stack navigation, main, footer
nav/index.mq.md
nav/content.md ordinary Markdown links
main/index.mq.md
main/content.md ordinary Markdown prose
footer/index.mq.md columns: brand, links
brand/index.mq.md
brand/content.md brand and copyright
links/index.mq.md columns: docs, community
docs/index.mq.md
docs/content.md
community/index.mq.md
community/content.md
pages/about.mq.md another declared page
api/ping.mq.md Endpoint
preview.mq.md assemble and render offline
serve.mq.md process launcher, no page content
```
Web pages are built by file partition, not by injecting HTML. Split a homepage
into files for navigation, sidebar, main, and footer. If a region is still
complex (two-column footer, dense styles), split again until each file is
simple: one duty, one View table or short Markdown. Bind values, database
fields, and named styles through the unified View columns type, slot, value,
attrs, and style only. Forbidden as the default method: whole-page HTML
strings, CSS injection bags, restored compose fragments, and json.set DOM glue.
Escape hatch only: dom.raw / page.css, and only with a written reason.
A parent index imports children, combines their rows and declares one layout
relationship. A terminal content.md is plain Markdown. Split again if a parent
contains long content, multiple layout responsibilities or HTML tags. A leaf
does not decide its external placement. Cutting a large HTML string into files
still hides the structure in strings. Forms, data sources and interaction need
their own responsibilities; they do not justify restoring an HTML page shell.
Full text: doc/design/ext-web-layout-paradigm.md. In-package tools live at
ext/web/layout/index.mq.md.
Follow the real project
Minimal commands to load the law (no plugin required):
The [English reference](../../examples/web-layout-handbook/index.mq.md) implements
this tree. Follow its [component root](../../examples/web-layout-handbook/components/index.mq.md)
to footer grandchildren. The [Chinese reference](../../examples/web-layout-handbook-zh/index.mq.md)
uses the same representation and renderer. Preview from the repo root, then
change into the site directory to start the process:
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md view_schema --json
```text
marqdo run examples/web-layout-handbook/preview.mq.md
cd examples/web-layout-handbook
marqdo run serve.mq.md
```
*None*
Check /, /about and /api/ping. The first is a genuinely nested layout, the second
an ordinary Document, and the third JSON. Wide layouts show columns; narrow
layouts collapse without authored HTML or CSS.
## How to execute any tool
One View representation for both parents and leaves
Call example (plain text):
marqdo call FILE FUNCTION name=value name=value --effects plugin --json
Public columns remain type, slot, value, attrs, style, with Chinese aliases
类型、槽、值、属性、样式. Use @ record tables for lists of node maps. A row/column
container holds child rows in value. nav/header/footer/section/aside supply
semantic regions. A markdown value is content text. Merging defines sibling
order, not geometry: use columns to establish side-by-side placement. A style
cell references class names; it neither defines CSS nor silently compiles a theme.
Runtime defaults supply the basic responsive geometry.
FILE is under `ext/web/`, usually `index.mq.md` or a module path. FUNCTION is the
exact ## heading. Nested ### use `parent.child`. Pass `--effects plugin` for
anything that loads the native web plugin (`render`, `serve`, `inspect`, …).
Layout helpers `rules` / `view_schema` / `accept_component` are pure and may omit
plugin effects. Use `--session` / `--toget` / `$name` to chain handles. Do not
call `ensure_plugin` or `host_*`; facades load the plugin.
Short leaves can pass Markdown directly; longer leaves read a content.md as in
the reference. Parents retain structural values rather than rendering children
before composition. This small executable program demonstrates the relationship;
real sites put each responsibility into the files shown above.
Verify layout skill (no plugin):
```marqdo
---
markup: occlusion
import:
component: ext/web/component/index.mq.md
layout: ext/web/layout/index.mq.md
web: ext/web/web.mq.md
---
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
# main
*None*
**left = component.markdown text="### Brand" slot="brand"**
**right = component.markdown text="[About](/about)" slot="links"**
**siblings = component.merge a=`left` b=`right`**
**footer = layout.columns children=`siblings` slot="footer"**
**html = web.render nodes=`footer` title="Column preview"**
> print text=`html`
```
## Package layout
Document, Endpoint and lifecycle boundaries
| Path | Role |
|------|------|
| `ext/web/index.mq.md` | This root skill |
| `ext/web/layout/index.mq.md` | File-partition layout engineering tools |
| `ext/web/web.mq.md` | Author facade: page · route · serve · render · inspect · use |
| `ext/web/page.mq.md` | Document handle · render |
| `ext/web/route.mq.md` | Declared routes |
| `ext/web/component.mq.md` | View fragments · merge |
| `ext/web/dom.mq.md` | Markdown DOM; raw is escape hatch |
| `ext/web/client.mq.md` | WASM embed · patches |
| `ext/web/_capability.mq.md` | Plugin load only |
| `ext/web/网页.mq.md` | Chinese facade / skill mirror |
Ordinary Documents declare type: web, route and title around Markdown body,
retaining the existing Markdown/data-source path. A composed Document also
declares view: main: its # main returns View rows. serve executes that assembly
once at startup and uses the same renderer as offline preview. Restart after
content changes. Automatic data_source binding uses ordinary Documents and
cannot be mixed with startup assembly. Assembly returns structure; it must not render again or launch
a server. Request-time interaction belongs in Endpoints with type, path, method,
request and response metadata. Startup assembly is not an automatic request-time
template/data-binding system.
Related packages (not this facade): `ext/data`, `ext/security`, `ext/net`.
serve is a blocking lifecycle operation for a launcher run with marqdo run.
call is for pure construction, previews and inspection; --effects plugin does
not grant network or filesystem writes, so call serve is not a launch workflow.
inspect with root scans disk declarations without listening; an empty app in a
fresh process cannot inspect another process's private state.
*None*
```sh
marqdo call ext/web/web.mq.md inspect 'root="examples/web-layout-handbook"' --effects plugin --json
```
## layout module
Open the module for the next responsibility
File path: `ext/web/layout/index.mq.md`
[layout](layout/index.mq.md) supplies decomposition, stack and columns;
[component](component/index.mq.md) supplies Markdown leaves and semantic wrappers;
[page](page/index.mq.md) supplies handles and offline render;
[route](route/index.mq.md) is for explicit advanced registration, while whole
sites normally use Metadata. [dom](dom/index.mq.md) converts content, retaining
raw HTML only at a compatibility boundary. [client](client/index.mq.md) loads
the official Marqdo WASM bridge; business effects stay in lib/browser.
[_capability](_capability/index.mq.md) diagnoses loading. The [facade](web.mq.md)
keeps serve/render/inspect and the app API. Data, auth and HTTP clients belong
to ext/data, ext/security and ext/net. [Chinese handbook](网页/索引.mq.md).
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md accept_component name="nav" duty="top links only" --json
Develop and accept a change
Main ## tools: rules, view_schema, merge_nodes, accept_component.
Compose Markdown, stack and columns before inventing a primitive. Only genuinely
new structural capability needs plugins/web/internal/artifact and ABI changes;
ordinary pages need no new host primitive. Keep bilingual helpers and the five
columns aligned. Put parameter contracts after headings and return contracts
before execution. ## is a callable heading, not ordinary document sectioning.
Update src/ext_cli.rs if adding package files. Preserve ordinary Documents and
Endpoints when changing startup assembly.
*None*
```text
cargo test --locked --test web_handbook
cargo test --locked --test call_cli web_
cargo test --locked --test gold ext_web -- --test-threads=1
```
## facade module
Handbook tests execute the bilingual sh fences and author examples directly,
then preview and serve the real reference tree to check structure, routes and
API behavior. Narration ratio is a minimum, not proof of usability. A checklist
cannot truthfully accept a component without inspecting its implementation.
This package does not automatically decompose arbitrary pages or implement a
full CSS compiler through the style cell; explicit design remains the author's
responsibility, made followable and testable by these indexes.
File path: `ext/web/web.mq.md`
Author import: `web: ext/web/web.mq.md`. Agent call examples:
Call example (plain text):
marqdo call ext/web/web.mq.md inspect --effects plugin --json
Main ## tools: page, route, render, use, inspect, serve, client_embed, …
*None*
## layout_rules
Root convenience: same payload as `layout.rules` so agents who only opened this
file can still fetch the law.
## site_playbook
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | layout rule map |
| result | any | Development workflow and stopping rule |
Return the workflow and stopping rule without creating files or claiming to
accept a particular site. Define the region tree, author parents and Markdown
leaves, then start and test the declared HTTP surface.
`workflow` =
| key | value |
|-----|-------|
| goal | build a site as executable documents |
| step_A | draw region tree before content |
| step_B | recursively split components to Markdown leaves |
| step_C | declare home Document and view main for composed structure |
| step_D | declare more Documents with their own routes |
| step_E | declare Endpoint handlers for request-time work |
| step_F | run serve.mq.md from the site directory |
| step_G | compare preview and live output; test routes and browser geometry |
| stopping_rule | one Markdown responsibility and no internal layout |
*workflow*
## layout_rules
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Development workflow and stopping rule |
Reuse the layout module convention without a second rule catalog. No
parameters or plugin. Actual acceptance still inspects leaf responsibilities,
parent relationships and the running result.
*> layout.rules*
## preview_markdown
| 参数 | 类型 | 说明 |
|------|------|------|
| body | text | Markdown content |
| title | text | Document title |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | HTML document |
Render Markdown `body`="" with default `title`="Preview" .
Return HTML text without writing files or registering routes. For a complex
page split the layout first; raw HTML strings are not the content strategy.
This tool needs the native plugin.
*> web.render body=`body` title=`title`*
## preview_nodes
| 参数 | 类型 | 说明 |
|------|------|------|
| nodes | list | Nested View rows |
| title | text | Document title |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | HTML document |
Render decomposed `nodes` with default `title`="Preview" .
Parent values retain child rows, while leaf values hold Markdown. Returning
HTML starts no server. The same renderer serves composed Documents, so this
preview checks that column relationships survive assembly.
*> web.render nodes=`nodes` title=`title`*
+99 -58
View File
@@ -1,71 +1,72 @@
---
markup: occlusion
title: ext/web/layout
description: >-
Web layout engineering skill — partition pages into files until every piece is
simple. View tables only; HTML/CSS injection is escape hatch, not the method.
description: Split structure first, recursively down to simple Markdown leaves.
import:
component: ext/web/component.mq.md
component: ext/web/component/index.mq.md
---
Layout is how Marqdo web stays maintainable. A homepage is not one HTML blob. It
is a directory of Documents and component files: nav, sidebar, main, footer.
When a region is still complex (for example a two-column footer with brand and
link groups), split again until each file has one job and one simple View table
or short Markdown. Bind values, data, and named styles through
`|type|slot|value|attrs|style|`. Do not reach for `dom.raw` or giant CSS strings
to "finish faster" — that bypasses binding and becomes unreadable.
Engineering practice: draw the region tree before writing content. Home splits
into navigation, main and footer. Footer splits into brand and links; if links
has two columns, split again into docs and community. Continue while a region
needs independent internal layout. Stop at one readable Markdown responsibility,
not at an arbitrary number of files or one file per sentence.
Canonical design: `doc/design/ext-web-layout-paradigm.md`.
Follow the real [reference site](../../../examples/web-layout-handbook/index.mq.md).
Parent index.mq.md files import children and declare one layout relationship;
leaf content.md files contain ordinary Markdown. Splitting an HTML string into
several files does not make the structure document-native.
## For AI agents
```sh
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md columns 'children=[{"type":"markdown","value":"Left"},{"type":"markdown","value":"Right"}]' 'slot="footer"' --json
```
If you were given only this file, load the rules before writing any site file.
Always pass `--effects plugin` when a later step needs the native web plugin;
these tools are pure documentation helpers and need no plugin.
columns preserves child rows in value and renders a responsive grid; narrow
screens collapse automatically. stack preserves top-to-bottom region order.
The style column references class names, not raw CSS or a theme definition.
Merging alone creates siblings, not columns. Use component.markdown for content
and component.wrap for semantic regions such as nav or footer.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/layout/index.mq.md view_schema --json
When authoring: create `components/*.mq.md` (and nested folders) first, then a
thin `type: web` page that states route and main intent. Prefer
`component.merge` to concatenate View tables. Never make `dom.raw` the home
page implementation.
*None*
Development and acceptance: name each leaf by one content responsibility. If a
parent contains long prose or HTML tags, split further. Preview with page.render,
then serve and verify home, about and the API. New structural kinds belong in
plugins/web/internal/artifact with bilingual helpers and web_handbook tests.
## rules
Return the layout engineering rules as a readable map for agents and checklists.
No parameters. This tool does not load the plugin.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | rule map |
| result | any | Result |
Return the engineering convention and stopping rule. No parameters or plugin.
This is guidance rather than evidence that a particular source file passes;
acceptance also requires reading the leaves and exercising the resulting page.
`out` =
| key | value |
|-----|-------|
| paradigm | file-partitioned layout |
| partition | homepage splits into nav, sidebar, main, footer files |
| until_simple | split again when a file has multiple jobs or dense styles |
| view_schema | only type slot value attrs style columns |
| forbid_default | HTML string pages; CSS injection; compose_*; json.set DOM bags |
| escape_hatch | dom.raw / page.css only with a written why |
| data_bind | values, db, and named styles via tables |
| paradigm | recursive file-partitioned layout |
| partition | home to nav/main/footer; footer to brand/links; links to docs/community |
| until_simple | one simple Markdown responsibility with no independent internal layout |
| view_schema | type slot value attrs style; parent value holds child rows |
| parent | import child components and choose one relationship |
| leaf | ordinary Markdown content without an HTML shell |
| geometry | merge gives siblings; stack and columns give placement |
| verify | offline render; live routes; narrow and wide browser geometry |
*out*
## view_schema
Return the only allowed View table column names (English). Chinese aliases are
`类型|槽|值|属性|样式`. No parameters.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | column list |
| result | list | Public column names |
Return the five public View columns. A container value holds more rows of
the same schema; a Markdown value holds content text. This keeps recursive
layout within one representation instead of adding a private fragment dialect.
`cols` =
@@ -81,39 +82,79 @@ Return the only allowed View table column names (English). Chinese aliases are
## merge_nodes
Concatenate View node tables `a` and `b`. Use after splitting regions into files
so a page can assemble simple parts without HTML.
| 参数 | 类型 | 说明 |
|------|------|------|
| a | any | first View table |
| b | any | second View table |
| a | list | First node records |
| b | list | Second node records |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | concatenated View nodes |
| result | list | Ordered sibling nodes |
Concatenate `a` and `b` as siblings. This helper preserves structure and order
but does not imply geometry; use columns for side-by-side placement or stack
for a vertical page. The @ record lists retain nested values throughout.
*> component.merge a=`a` b=`b`*
## accept_component
Documentary gate for authors and agents. Pass component `name` (file stem) and
single-duty `duty` (one short sentence). Returns an accept map reminding that
the file must stay single-duty. Does not write disk.
## stack
| 参数 | 类型 | 说明 |
|------|------|------|
| name | text | component name, for example nav |
| duty | text | one-job description |
| children | list | Child component records |
| slot | text | Parent region name |
| style | text | Optional class name |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | accept checklist row |
| result | list | Parent container rows |
Declare one vertical relationship for `children`. Default `slot`="" and
`style`="" . The parent owns placement while each imported child owns content
or its next decomposition level. Return View rows so another parent can wrap
them without first serializing any HTML.
*> component.wrap children=`children` kind="column" slot=`slot` style=`style`*
## columns
| 参数 | 类型 | 说明 |
|------|------|------|
| children | list | Child component records |
| slot | text | Parent region name |
| style | text | Optional class name |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | Parent container rows |
Declare one responsive multi-column relationship for `children`. Default `slot`="" and
`style`="" . The parent owns placement while each imported child owns content
or its next decomposition level. Return View rows so another parent can wrap
them without first serializing any HTML.
*> component.wrap children=`children` kind="row" slot=`slot` style=`style`*
## accept_component
| 参数 | 类型 | 说明 |
|------|------|------|
| name | text | Component name |
| duty | text | One responsibility |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Result |
Return a review checklist for component `name` and stated `duty`. Two strings
cannot establish source quality or a working layout, so this tool does not
return an unconditional ok=True. Verify the actual source and rendered page
before accepting the component. It never writes or scans files.
`row` =
| ok | name | duty | must | reject_if |
|----|------|------|------|-----------|
| True | `name` | `duty` | one View table or short Markdown; named styles only | mixes nav+footer · embeds raw HTML as main body · private table dialects |
| status | name | duty | check |
|--------|------|------|-------|
| checklist | `name` | `duty` | one Markdown leaf or one parent relationship; no raw HTML shell |
*row*
-97
View File
@@ -1,97 +0,0 @@
---
markup: occlusion
title: ext/web/page
description: >-
Document → View. Sole compose path is render(nodes=) with unified View schema
(ADR 0007). File-partition layouts; no HTML injection as default.
import:
cap: ext/web/_capability.mq.md
table: lib/table.mq.md
---
## For AI agents
Build Documents with Metadata (`type: web`) and thin pages. Put chrome in
`components/*.mq.md` files. View schema is only `|type|slot|value|attrs|style|`.
Call `ext/web/layout/index.mq.md` `rules` before inventing structure. Always
`--effects plugin` for render.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md view_schema --json
*None*
# page
+ `title`=""
+ `route`="/"
+ `method`="GET"
+ `body`=""
+ `nodes`=None
+ `data_source`=""
+ `data_order`=""
+ `data_where`=""
Web Document handle. Prefer constructing from Artifact Metadata via `web.page` facade.
View tables use only `|type|slot|value|attrs|style|` (ZH `|类型|槽|值|属性|样式|`).
Do not pass a raw HTML string as the primary `body` for a full site shell.
> cap.load
`out` =
| _type | title | route | method | body | nodes | data_source | data_order | data_where |
|-------|-------|-------|--------|------|-------|-------------|------------|------------|
| page | `title` | `route` | `method` | `body` | `nodes` | `data_source` | `data_order` | `data_where` |
*out*
## render
+ `nodes`=None
+ `db`=None
Render this Document to HTML for preview or response. Optional `nodes` is the
unified View table (type/slot/value/attrs/style). When `nodes` is None, the
method uses self.nodes if present, otherwise Markdown body. Optional `db`
supplies bound rows for data_source pages. Prefer assembling `nodes` from
file-partitioned components via component.merge — do not pass a handmade HTML
string as the page shell. This is the sole compose path (ADR 0007); there is no
compose_main or fragment DSL.
| 参数 | 类型 | 说明 |
|------|------|------|
| nodes | any | View table or None |
| db | any | optional database handle |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or render payload |
> cap.load
**n = nodes**
1. `n` == None
**n = [nodes](access(self, "nodes"))**
2. *
**_ = 1**
1. `n`
*> web_render_nodes page=`self` nodes=`n` db=`db`*
2. *
**body = [body](access(self, "body"))**
*> web_render_document page=`self` body=`body` db=`db`*
## css
+ `css`
Escape hatch — append raw CSS string `css` to this page. Named style tables and
the View style column remain the default theme path. Use this only when a host
constraint cannot be expressed as a named style row, and write that reason next
to the call. Forbidden as the primary way to style nav, sidebar, or footer.
| 参数 | 类型 | 说明 |
|------|------|------|
| css | text | raw CSS (escape hatch) |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | updated page handle |
> cap.load
*> web_page_css page=`self` css=`css`*
+179
View File
@@ -0,0 +1,179 @@
---
markup: occlusion
title: ext/web/page
description: >-
Document → View. Sole compose path is render(nodes=) with unified View schema
(ADR 0007). File-partition layouts; no HTML injection as default.
import:
cap: ext/web/_capability/index.mq.md
table: lib/table.mq.md
---
Documents hold body text or nested View rows. For reusable layout follow
[layout](../layout/index.mq.md); render is the shared offline path. A complete
session begins with new, saves the handle, then reads it with a protected reference.
```sh
marqdo call ext/web/page/index.mq.md new 'title="Preview"' 'body="# Hello"' --effects plugin --session handbook --toget pg --json
marqdo call ext/web/page/index.mq.md render 'page=$pg' --effects plugin --session handbook --json
```
For a live structured Document declare view: main and return composed rows from
its main function; serve executes that assembly once at startup. Ordinary web
Documents retain their Markdown path. The reference site demonstrates both.
New behavior belongs here, in the Chinese mirror and the artifact renderer;
preserve tests/ext/web-artifact-render-smoke.mq.md and the handbook tests.
## new
| 参数 | 类型 | 说明 |
|------|------|------|
| title | text | document title |
| route | text | path |
| method | text | HTTP method |
| body | text | Markdown body |
| nodes | any | View table or None |
| data_source | text | table name |
| data_order | text | order key |
| data_where | text | filters |
Construct a Document handle with `title`="", `route`="/", `method`="GET",
`body`="", optional View `nodes`=None, and flat `data_source`="", `data_order`="",
`data_where`="" keys. Prefer Artifact discovery via serve for production pages;
use this tool for previews and stepwise agent sessions. nodes must be the
unified View schema, never a private dialect or an HTML string shell.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | page handle |
> cap.load
`out` =
| _type | title | route | method | body | nodes | data_source | data_order | data_where |
|-------|-------|-------|--------|------|-------|-------------|------------|------------|
| page | `title` | `route` | `method` | `body` | `nodes` | `data_source` | `data_order` | `data_where` |
*out*
## render
| 参数 | 类型 | 说明 |
|------|------|------|
| page | any | Document handle |
| nodes | any | View table or None |
| db | any | optional database handle |
Render Document handle `page` to HTML for preview or response. Optional
`nodes`=None is the unified View table; when None, uses the page's own nodes or
Markdown body. Optional `db`=None is retained for facade compatibility. This offline renderer
does not populate data_source; automatic row binding belongs to served ordinary
Documents, or callers can materialize their content explicitly.
Prefer assembling nodes from file-partitioned components — do not pass a
handmade HTML string as the page shell. This is the sole compose path (ADR
0007); there is no compose_main or fragment DSL. Agents should call this free
tool (not a method chain) under `--effects plugin`.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or render payload |
> cap.load
**n = nodes**
1. `n` == None
**n = [nodes](access(page, "nodes"))**
2. *
**_ = 1**
**title = [title](access(page, "title"))**
1. `n`
*> web_render_nodes page=`page` nodes=`n` db=`db` title=`title`*
2. *
**body = [body](access(page, "body"))**
*> web_render_document page=`page` body=`body` db=`db` title=`title`*
# page
| 参数 | 类型 | 说明 |
|------|------|------|
| title | any | See prose default / 见叙述默认值 |
| route | any | See prose default / 见叙述默认值 |
| method | any | See prose default / 见叙述默认值 |
| body | any | See prose default / 见叙述默认值 |
| nodes | any | See prose default / 见叙述默认值 |
| data_source | any | See prose default / 见叙述默认值 |
| data_order | any | See prose default / 见叙述默认值 |
| data_where | any | See prose default / 见叙述默认值 |
Inputs: `title`="", `route`="/", `method`="GET", `body`="", `nodes`=None, `data_source`="", `data_order`="", `data_where`=""
Web Document handle for author method chains. Prefer constructing from Artifact
Metadata via `web.page` facade or the free `new` tool above. View tables use
only `|type|slot|value|attrs|style|` (ZH `|类型|槽|值|属性|样式|`). Do not pass a
raw HTML string as the primary `body` for a full site shell.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Constructed value / 构造结果 |
> cap.load
`out` =
| _type | title | route | method | body | nodes | data_source | data_order | data_where |
|-------|-------|-------|--------|------|-------|-------------|------------|------------|
| page | `title` | `route` | `method` | `body` | `nodes` | `data_source` | `data_order` | `data_where` |
*out*
## render
| 参数 | 类型 | 说明 |
|------|------|------|
| nodes | any | View table or None |
| db | any | optional database handle |
Inputs: `nodes`=None, `db`=None
Render this Document to HTML for preview or response. Optional `nodes` is the
unified View table (type/slot/value/attrs/style). When `nodes` is None, the
method uses self.nodes if present, otherwise Markdown body. Optional `db` is retained for compatibility; automatic data_source binding
belongs to ordinary served Documents, not this offline renderer. Prefer assembling `nodes` from
file-partitioned components via component.merge — do not pass a handmade HTML
string as the page shell. This is the sole compose path (ADR 0007); there is no
compose_main or fragment DSL.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or render payload |
> cap.load
**n = nodes**
1. `n` == None
**n = [nodes](access(self, "nodes"))**
2. *
**_ = 1**
**title = [title](access(self, "title"))**
1. `n`
*> web_render_nodes page=`self` nodes=`n` db=`db` title=`title`*
2. *
**body = [body](access(self, "body"))**
*> web_render_document page=`self` body=`body` db=`db` title=`title`*
## css
| 参数 | 类型 | 说明 |
|------|------|------|
| css | text | raw CSS (escape hatch) |
Inputs: `css`
Escape hatch — append raw CSS string `css` to this page. Named style tables and
the View style column remain the default theme path. Use this only when a host
constraint cannot be expressed as a named style row, and write that reason next
to the call. Forbidden as the primary way to style nav, sidebar, or footer.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | updated page handle |
> cap.load
*> web_page_css page=`self` css=`css`*
-65
View File
@@ -1,65 +0,0 @@
---
markup: occlusion
title: ext/web/route
description: Declared Endpoint / Document route registration (ADR 0007).
import:
cap: ext/web/_capability.mq.md
table: lib/table.mq.md
---
# route
+ `app`
+ `path`
+ `method`="GET"
+ `page`=None
+ `fn`=""
+ `request`="json"
+ `response`="json"
+ `auth`=""
+ `class`=""
Declared route handle. Prefer `web.route` / Artifact `type: endpoint` discovery via `web.serve`.
Optional `class`: `execute` | `short` | `read` | `control` (empty → heuristic / `legacy_serial`).
> cap.load
`out` =
| _type | app | path | method | page | fn | request | response | auth | class |
|-------|-----|------|--------|------|----|---------|----------|------|-------|
| route | `app` | `path` | `method` | `page` | `fn` | `request` | `response` | `auth` | `class` |
*out*
## use
+ `middleware`
Attach middleware table to this route (`|header|value|` or named capability rows).
> cap.load
*> web_route_use route=`self` middleware=`middleware`*
## register
+ `app`=None
Register this declared route on an app handle.
> cap.load
**a = app**
1. `a` == None
**a = [app](access(self, "app"))**
2. *
**_ = 1**
**page = [page](access(self, "page"))**
**fn = [fn](access(self, "fn"))**
1. `page`
**path = [path](access(self, "path"))**
*> web_app_route app=`a` path=`path` page=`page`*
2. `fn`
**path = [path](access(self, "path"))**
**method = [method](access(self, "method"))**
**request = [request](access(self, "request"))**
**response = [response](access(self, "response"))**
**class = [class](access(self, "class"))**
*> web_app_invoke app=`a` path=`path` method=`method` fn=`fn` body=`request` return=`response` class=`class`*
3. *
*> table.put in=None at="ok" value=False*
+213
View File
@@ -0,0 +1,213 @@
---
markup: occlusion
title: ext/web/route
description: Declared Endpoint / Document route registration (ADR 0007).
import:
cap: ext/web/_capability/index.mq.md
table: lib/table.mq.md
---
Routes declare the HTTP surface. Prefer Document/Endpoint metadata and serve
for whole sites; use route handles only for explicit app assembly. To obtain an
app use web.app on [the facade](../../web/web.mq.md); to discover a site's routes
without a live app use web.inspect with root. A fresh call without app/root
cannot inspect the private state of another running server.
```sh
marqdo call ext/web/route/index.mq.md new 'app={}' 'path="/hello"' 'page={"title":"Hello","body":"Hi"}' --effects plugin --session handbook --toget route --json
marqdo call ext/web/route/index.mq.md register 'route=$route' --effects plugin --session handbook --json
```
The returned registration is a value, not a listening server. Middleware and
Endpoint handlers remain explicit; schema/auth resources live in their own
packages. Update both route facades and HTTP artifact tests for registration
changes; never introduce undeclared user URLs as a hidden convenience.
## new
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app handle |
| path | text | URL path |
| method | text | HTTP method |
| page | any | Document or None |
| fn | text | endpoint member |
| request | text | request kind |
| response | text | response kind |
| auth | text | auth tag |
| class | text | route class |
Build a declared route handle for `app` at `path` with `method`="GET" .
`page`=None holds a Document; `fn`="" names an Endpoint lib.member.
`request`="json", `response`="json", `auth`="", and `class`="" document the
contract. Optional class values: execute, short, read, control (empty →
heuristic / legacy_serial). This tool does not register yet — call `register`
or use the facade `web.route` which registers in one step.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | route handle |
> cap.load
`out` =
| _type | app | path | method | page | fn | request | response | auth | class |
|-------|-----|------|--------|------|----|---------|----------|------|-------|
| route | `app` | `path` | `method` | `page` | `fn` | `request` | `response` | `auth` | `class` |
*out*
## register
| 参数 | 类型 | 说明 |
|------|------|------|
| route | any | route handle |
| app | any | app or None |
Register declared route handle `route` on an app. Optional `app`=None falls back
to the app stored on the route object so stepwise agent sessions can omit it.
Page routes call web_app_route; Endpoint `fn` routes call web_app_invoke with
method and body/return contract fields pulled from the handle. User routes must
already be declared on this handle — this tool never invents paths. Prefer this
free tool under `--effects plugin` rather than a method chain when driving
registration from `marqdo call`. Soft-fails with ok=False when neither page nor
fn is present, so callers can detect incomplete declarations early.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | registration result |
> cap.load
**a = app**
1. `a` == None
**a = [app](access(route, "app"))**
2. *
**_ = 1**
**page = [page](access(route, "page"))**
**fn = [fn](access(route, "fn"))**
1. `page`
**path = [path](access(route, "path"))**
*> web_app_route app=`a` path=`path` page=`page`*
2. `fn`
**path = [path](access(route, "path"))**
**method = [method](access(route, "method"))**
**request = [request](access(route, "request"))**
**response = [response](access(route, "response"))**
**class = [class](access(route, "class"))**
*> web_app_invoke app=`a` path=`path` method=`method` fn=`fn` body=`request` return=`response` class=`class`*
3. *
*> table.put in=None at="ok" value=False*
## use
| 参数 | 类型 | 说明 |
|------|------|------|
| route | any | route handle |
| middleware | any | middleware table |
Attach middleware table `middleware` to declared route handle `route`
(`|header|value|` or named capability rows). Prefer first-class middleware tables
over configure junk drawers. Call this free tool with `--effects plugin`.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | use result |
> cap.load
*> web_route_use route=`route` middleware=`middleware`*
# route
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | See prose default / 见叙述默认值 |
| path | any | See prose default / 见叙述默认值 |
| method | any | See prose default / 见叙述默认值 |
| page | any | See prose default / 见叙述默认值 |
| fn | any | See prose default / 见叙述默认值 |
| request | any | See prose default / 见叙述默认值 |
| response | any | See prose default / 见叙述默认值 |
| auth | any | See prose default / 见叙述默认值 |
| class | any | See prose default / 见叙述默认值 |
Inputs: `app`, `path`, `method`="GET", `page`=None, `fn`="", `request`="json", `response`="json", `auth`="", `class`=""
Declared route handle for author method chains. Prefer `web.route` / Artifact
`type: endpoint` discovery via `web.serve`. Optional `class`: `execute` |
`short` | `read` | `control` (empty → heuristic / `legacy_serial`).
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Constructed value / 构造结果 |
> cap.load
`out` =
| _type | app | path | method | page | fn | request | response | auth | class |
|-------|-----|------|--------|------|----|---------|----------|------|-------|
| route | `app` | `path` | `method` | `page` | `fn` | `request` | `response` | `auth` | `class` |
*out*
## use
| 参数 | 类型 | 说明 |
|------|------|------|
| middleware | any | middleware table |
Inputs: `middleware`
Attach middleware table to this route (`|header|value|` or named capability
rows). Prefer explicit tables authors can read; do not restore a configure bag
for headers and cors.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | use result |
> cap.load
*> web_route_use route=`self` middleware=`middleware`*
## register
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app or None |
Inputs: `app`=None
Register this declared route on an app handle. When optional `app` is None, use
the app stored on this route object so author chains can omit the argument after
construction. Document pages call web_app_route with the stored path and page
handle. Endpoint members call web_app_invoke with path, method, and the
request/response/class contract fields from this route. Prefer Artifact
discovery via web.serve for whole sites; use this method when assembling routes
in memory for tests or advanced mounts. Returns a soft failure map when neither
page nor fn is set, so callers can detect an incomplete declaration without a
hard crash. Never invents an undeclared path — registration only publishes what
this handle already carries.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | registration result |
> cap.load
**a = app**
1. `a` == None
**a = [app](access(self, "app"))**
2. *
**_ = 1**
**page = [page](access(self, "page"))**
**fn = [fn](access(self, "fn"))**
1. `page`
**path = [path](access(self, "path"))**
*> web_app_route app=`a` path=`path` page=`page`*
2. `fn`
**path = [path](access(self, "path"))**
**method = [method](access(self, "method"))**
**request = [request](access(self, "request"))**
**response = [response](access(self, "response"))**
**class = [class](access(self, "class"))**
*> web_app_invoke app=`a` path=`path` method=`method` fn=`fn` body=`request` return=`response` class=`class`*
3. *
*> table.put in=None at="ok" value=False*
+111 -145
View File
@@ -6,48 +6,34 @@ description: >-
Document/Endpoint first-class. No compose_* / configure / author ensure_plugin.
Agents: read ext/web/index.mq.md first (layout file-partition law).
import:
cap: ext/web/_capability.mq.md
page_mod: ext/web/page.mq.md
route_mod: ext/web/route.mq.md
dom_mod: ext/web/dom.mq.md
client_mod: ext/web/client.mq.md
cap: ext/web/_capability/index.mq.md
page_mod: ext/web/page/index.mq.md
route_mod: ext/web/route/index.mq.md
dom_mod: ext/web/dom/index.mq.md
client_mod: ext/web/client/index.mq.md
table: lib/table.mq.md
---
Importing this module is the web capability (native plugin loads on first facade
call). Cold-start agents should open ext/web/index.mq.md before calling tools
here. Pages are file-partitioned View/Markdown assemblies — not HTML injection.
Layout skill: ext/web/layout/index.mq.md.
Web facade — [start at the root handbook](index.mq.md), then use this module
for server lifecycle and rendering. Layout assembly remains in pure component
functions; database, security and network clients stay in their own packages.
## For AI agents
```sh
marqdo call ext/web/web.mq.md render 'body="# A Document"' 'title="Preview"' --effects plugin --json
marqdo call ext/web/web.mq.md inspect 'root="examples/web-layout-handbook"' --effects plugin --json
```
Every ## below is a tool. Prefer --effects plugin. For how to split nav /
sidebar / footer into files, call layout rules first:
inspect with root scans declared metadata without starting a server. To inspect
an in-memory app, pass its actual handle; an empty fresh process cannot inspect
another process. serve is a blocking lifecycle operation: write a launcher and
use marqdo run, not call. Explicit view: main Documents assemble once at startup
through normal functions and imports. Restart after changing their content.
Call example (plain text):
marqdo call ext/web/layout/index.mq.md rules --json
marqdo call ext/web/web.mq.md inspect --effects plugin --json
Do not use dom_patch / raw HTML to build a whole Document homepage. Prefer
type: web Artifact files under a site root and web.serve.
*None*
Develop layout structure in layout/component and the Go artifact renderer;
keep this facade as orchestration. Preserve the existing app object and manual
route API. Contracts precede execution; ordinary prose titles are not functions.
## page
+ `title`=""
+ `route`="/"
+ `method`="GET"
+ `body`=""
+ `nodes`=None
+ `data_source`=""
+ `data_order`=""
+ `data_where`=""
Construct a Document handle with title, route, method, Markdown body, optional
View nodes, and flat data_source / data_order / data_where keys. Prefer
discovering type: web Artifact files via serve rather than hand-building every
page in memory. nodes must be the unified View schema, never a private dialect
or an HTML string shell.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -60,6 +46,12 @@ or an HTML string shell.
| data_order | text | order key |
| data_where | text | filters |
Construct a Document handle with `title`="", `route`="/", `method`="GET",
`body`="", optional View `nodes`=None, and flat `data_source`="", `data_order`="",
`data_where`="" keys. Prefer discovering type: web Artifact files via serve
rather than hand-building every page in memory. nodes must be the unified View
schema, never a private dialect or an HTML string shell.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | page handle |
@@ -67,21 +59,6 @@ or an HTML string shell.
*> page_mod.page title=`title` route=`route` method=`method` body=`body` nodes=`nodes` data_source=`data_source` data_order=`data_order` data_where=`data_where`*
## route
+ `app`
+ `path`
+ `method`="GET"
+ `page`=None
+ `fn`=""
+ `request`="json"
+ `response`="json"
+ `auth`=""
+ `class`=""
Register a declared Document page or Endpoint on app. path and method identify
the HTTP surface. page holds a Document; fn names an Endpoint lib.member.
request / response / auth / class document the contract. Optional class values
include execute, short, read, control. User routes must be declared — never
implicit. After building the route object this tool registers it on the app.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -95,6 +72,13 @@ implicit. After building the route object this tool registers it on the app.
| auth | text | auth tag |
| class | text | route class |
Register a declared Document page or Endpoint on `app` at `path` with
`method`="GET" . `page`=None holds a Document; `fn`="" names an Endpoint
lib.member. `request`="json", `response`="json", `auth`="", and `class`=""
document the contract. Optional class values include execute, short, read,
control. User routes must be declared — never implicit. After building the
route object this tool registers it on the app.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | registration result |
@@ -103,17 +87,6 @@ implicit. After building the route object this tool registers it on the app.
*> `r`.register app=`app`*
## render
+ `doc`=None
+ `nodes`=None
+ `body`=""
+ `title`=""
+ `db`=None
Render a Document or View nodes to HTML for offline preview. Prefer nodes from
file-partitioned components. When doc is set, delegates to page.render. When
only nodes are set, renders that View table. Otherwise renders Markdown body.
Requires the native plugin. Do not treat this as permission to paste a full HTML
homepage — keep using View tables and Markdown.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -123,6 +96,13 @@ homepage — keep using View tables and Markdown.
| title | text | title |
| db | any | optional db |
Render a Document or View nodes to HTML for offline preview. Prefer nodes from
file-partitioned components. Optional `doc`=None is a Document handle; when set,
delegates to page.render. Optional `nodes`=None is a View table; when set without
doc, renders that table. Otherwise renders Markdown `body`="" with optional
`title`="" and `db`=None . Requires the native plugin. Do not treat this as
permission to paste a full HTML homepage — keep using View tables and Markdown.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or payload |
@@ -136,18 +116,16 @@ homepage — keep using View tables and Markdown.
*> web_render_document page=`doc` body=`body` db=`db` title=`title`*
## use
+ `app`
+ `middleware`
Attach first-class middleware to app. Pass a GFM table (security headers, cors
row, and similar). This replaces the old configure(...) junk drawer with an
explicit table authors can read.
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app handle |
| middleware | any | middleware table |
Attach first-class `middleware` to `app`. Pass a GFM table (security headers,
cors row, and similar). This replaces the old configure(...) junk drawer with an
explicit table authors can read.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
@@ -156,35 +134,26 @@ explicit table authors can read.
*> web_app_use app=`app` middleware=`middleware`*
## inspect
+ `app`=None
Return declared versus system route tables for introspection. System routes such
as /_part and /_form must appear here. Use this to verify a site after serve or
manual registration. Optional app selects which application to inspect.
| 参数 | 类型 | 说明 |
|------|------|------|
| app | any | app or None |
| root | text | Site directory to inspect without listening |
Return declared versus system route tables for introspection. System routes such
as /_part and /_form must appear here. Use this to verify a site after serve or
manual registration. Optional `app`=None selects which application to inspect.
Optional `root`="" scans a site directory when supplied; it does not start a server.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | {declared, system} |
> cap.load
*> web_inspect app=`app`*
*> web_inspect app=`app` root=`root`*
## serve
+ `root`="."
+ `host`="127.0.0.1"
+ `port`=18081
+ `db`=None
+ `static_dir`=""
+ `middleware`=None
Scan root for type web or endpoint Artifacts, register declared routes, attach
system routes, and listen on host:port. The site directory should already follow
the layout law (components split until simple). Optional db and middleware bind
resources without stuffing them into this facade as author APIs.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -195,6 +164,12 @@ resources without stuffing them into this facade as author APIs.
| static_dir | text | static files |
| middleware | any | optional middleware |
Scan `root`="." for type web or endpoint Artifacts, register declared routes,
attach system routes, and listen on `host`="127.0.0.1" and `port`=18081 . The
site directory should already follow the layout law (components split until
simple). Optional `db`=None, `static_dir`="", and `middleware`=None bind
resources without stuffing them into this facade as author APIs.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | serve result |
@@ -203,14 +178,6 @@ resources without stuffing them into this facade as author APIs.
*> web_serve_root root=`root` host=`host` port=`port` db=`db` static_dir=`static_dir` middleware=`middleware`*
## client_embed
+ `bridge`="/static/marqdo-bridge.js"
+ `wasm`="/static/marqdo_wasm.wasm"
+ `source`=""
+ `boot`=True
Describe WASM bridge embed tags for a page that needs client Marqdo. This is not
a substitute for Document layout: still partition nav and main in files, then
embed the bridge where interaction needs it.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -219,6 +186,12 @@ embed the bridge where interaction needs it.
| source | text | optional source |
| boot | bool | auto boot |
Describe WASM bridge embed tags for a page that needs client Marqdo. Defaults:
`bridge`="/static/marqdo-bridge.js", `wasm`="/static/marqdo_wasm.wasm",
`source`="", `boot`=True . This is not a substitute for Document layout: still
partition nav and main in files, then embed the bridge where interaction needs
it.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | embed descriptor |
@@ -226,18 +199,16 @@ embed the bridge where interaction needs it.
*> client_mod.embed bridge=`bridge` wasm=`wasm` source=`source` boot=`boot`*
## text_patch
+ `sel`
+ `text`
Client patch: set text content for CSS selector sel. Use for small interactive
updates after a Document is already laid out with View tables — not for building
the initial homepage shell.
| 参数 | 类型 | 说明 |
|------|------|------|
| sel | text | CSS selector |
| text | text | new text |
Client patch: set text content for CSS selector `sel` to string `text`. Use for
small interactive updates after a Document is already laid out with View tables —
not for building the initial homepage shell.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
@@ -245,14 +216,6 @@ the initial homepage shell.
*> client_mod.text_patch sel=`sel` text=`text`*
## dom_patch
+ `sel`
+ `html`=""
+ `attrs`=None
+ `remove`=False
Client patch for selector sel with optional html, attrs, or remove. Treat html
here as a surgical update, never as the primary way to author nav, sidebar, or
footer. Layout law still applies to the Document that hosts the selector.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -261,6 +224,11 @@ footer. Layout law still applies to the Document that hosts the selector.
| attrs | any | optional attrs |
| remove | bool | remove node |
Client patch for selector `sel` with optional `html`="", `attrs`=None, or
`remove`=False . Treat html here as a surgical update, never as the primary way
to author nav, sidebar, or footer. Layout law still applies to the Document that
hosts the selector.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
@@ -268,13 +236,6 @@ footer. Layout law still applies to the Document that hosts the selector.
*> client_mod.dom_patch sel=`sel` html=`html` attrs=`attrs` remove=`remove`*
## make_style
+ `name`=""
+ `table`
+ `strict`=False
Compile a named style table into CSS. Styles remain data next to content; this
is not a hidden page DSL. Prefer referencing style names from View style columns
after file-partitioned components define their look.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -282,6 +243,11 @@ after file-partitioned components define their look.
| table | any | property table |
| strict | bool | strict mode |
Compile a named style `table` into CSS. Optional `name`="" and `strict`=False .
Styles remain data next to content; this is not a hidden page DSL. Prefer
referencing style names from View style columns after file-partitioned
components define their look.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | CSS / style handle |
@@ -290,15 +256,14 @@ after file-partitioned components define their look.
*> web_style name=`name` table=`table` strict=`strict`*
## make_images
+ `table`
Build image descriptors from a readable table of sources and alts. Keep media
declarations in Markdown tables beside the Document that uses them.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | images table |
Build image descriptors from a readable `table` of sources and alts. Keep media
declarations in Markdown tables beside the Document that uses them.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | images payload |
@@ -307,15 +272,14 @@ declarations in Markdown tables beside the Document that uses them.
*> web_images table=`table`*
## make_head
+ `table`
Build head resource rows (link, script, icon) from a table. Prefer declaring
head needs as data rather than injecting opaque HTML head strings.
| 参数 | 类型 | 说明 |
|------|------|------|
| table | any | head table |
Build head resource rows (link, script, icon) from a `table`. Prefer declaring
head needs as data rather than injecting opaque HTML head strings.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | head payload |
@@ -324,15 +288,20 @@ head needs as data rather than injecting opaque HTML head strings.
*> web_head table=`table`*
# app
+ `page`=None
+ `db`=None
+ `host`=127.0.0.1
+ `port`=18081
+ `admin`=False
+ `admin_prefix`=/admin
+ `shell_css`=None
+ `layout`=None
+ `asset_version`=None
| 参数 | 类型 | 说明 |
|------|------|------|
| page | any | See prose default / 见叙述默认值 |
| db | any | See prose default / 见叙述默认值 |
| host | any | See prose default / 见叙述默认值 |
| port | any | See prose default / 见叙述默认值 |
| admin | any | See prose default / 见叙述默认值 |
| admin_prefix | any | See prose default / 见叙述默认值 |
| shell_css | any | See prose default / 见叙述默认值 |
| layout | any | See prose default / 见叙述默认值 |
| asset_version | any | See prose default / 见叙述默认值 |
Inputs: `page`=None, `db`=None, `host`=127.0.0.1, `port`=18081, `admin`=False, `admin_prefix`="/admin", `shell_css`=None, `layout`=None, `asset_version`=None
Low-level app handle for advanced mounts. Prefer web.serve for Artifact sites
that already follow file-partition layout. Optional page, db, host, port, admin
@@ -342,22 +311,24 @@ discovery should stay on serve; agents should not invent HTML shells on this
object. Methods static, listen, and gate hang off the returned handle for
mounts that remain table- and Metadata-driven.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Constructed value / 构造结果 |
> cap.load
*> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=None logout_redirect=None shell_css=`shell_css` layout=`layout` asset_version=`asset_version`*
## static
+ `dir`
+ `mount`=/static
Mount static files from dir at mount path on this app. Use for bridge scripts and
assets referenced by Documents — not for dumping an HTML-only site tree that
bypasses Artifact Documents.
| 参数 | 类型 | 说明 |
|------|------|------|
| dir | text | filesystem directory |
| mount | text | URL mount |
Mount static files from `dir` at `mount`=/static on this app. Use for bridge
scripts and assets referenced by Documents — not for dumping an HTML-only site
tree that bypasses Artifact Documents.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
@@ -376,16 +347,6 @@ root scanning; listen is for advanced app handles after manual route setup.
*> web_listen app=`self`*
## gate
+ `path`
+ `roles`=admin
+ `permissions`=""
+ `match`=prefix
+ `on_deny`=forbid
+ `exclude`=None
Attach an authorization gate on path for this app. roles, permissions, match,
on_deny, and exclude document who may enter. Auth resources live in ext/security;
this method only wires the gate onto the web app surface.
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -396,6 +357,11 @@ this method only wires the gate onto the web app surface.
| on_deny | text | deny behavior |
| exclude | any | exclusions |
Attach an authorization gate on `path` for this app. Defaults: `roles`="admin",
`permissions`="", `match`="prefix", `on_deny`="forbid", `exclude`=None . Auth
resources live in ext/security; this method only wires the gate onto the web
app surface.
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
+73 -37
View File
@@ -1,82 +1,118 @@
---
markup: occlusion
title: ext/web/布局
description: >-
Web 布局工程 skill — 用文件划分布局,拆到简单为止。只用 View 表;HTML/CSS 注入是逃逸舱。
description: 先拆结构,递归到简单 Markdown 叶子。
import:
layout: ext/web/layout/index.mq.md
component: ext/web/component.mq.md
---
布局决定 Marqdo 网站是否可维护。首页不是一整块 HTML,而是目录上的 Document 与
组件文件:导航、侧栏、主区、底栏。若某一区仍复杂(例如底栏双栏品牌+链接),继续
拆文件,直到每个文件单一职责、一张 View 表或短 Markdown。值、库字段、具名样式
只通过 `|类型|槽|值|属性|样式|`(或英列名)绑定。不要用 `dom.raw` 或大段 CSS
「先做完」——那会绕过绑定,事后不可读。
工程实践:先画区域树,再建立对应目录,最后写内容。首页拆成导航、主体、页脚;
页脚拆成品牌和链接;链接如果仍有双栏,就拆成文档与社区。内部还需要独立排布就继续拆,
直到叶子只含简单 Markdown。不是把每个句子拆成文件,而是消除同一个叶子中的多种职责。
设计正文:`doc/design/ext-web-layout-paradigm.md`。
真实文件树在[参考站点](../../../examples/web-layout-handbook/index.mq.md)。
父 index.mq.md 只导入、组合子块并选择一层布局;叶子 content.md 是普通 Markdown。
不要先写 HTML 壳再拆文件,那会把结构依旧藏在字符串里。
## 给智能体
```sh
marqdo call ext/web/布局/索引.mq.md 规则 --json
marqdo call ext/web/布局/索引.mq.md 分栏 '子节点=[{"type":"markdown","value":"左栏"},{"type":"markdown","value":"右栏"}]' '槽="页脚"' --json
```
若你只拿到本文件,写站前先拉取规则。布局规则工具本身是纯函数,可不加
`--effects plugin`;后续渲染/服务必须加。
分栏会在现有五列表的值中保留子节点,渲染为可响应的 CSS 网格;窄屏自动折叠。
纵排保持区域从上到下的顺序。样式列是类名引用,不是一段 CSS 规则,也不会自动定义主题。
只用合并工具会得到相邻节点,不会得到双栏。内容叶子使用组件正文,语义包裹使用组件包裹。
调用示例(纯文本):
marqdo call ext/web/布局/索引.mq.md 规则 --json
marqdo call ext/web/布局/索引.mq.md 视图契约 --json
撰写时先建 `components/*.mq.md`(可再嵌套),再写瘦的 `类型: 网页` 页面声明路由
与主区意图。用合并节点拼接 View。禁止把 `dom.raw` 当作首页主实现。
*None*
开发与验收:每个叶子应能以内容职责命名;父文件出现大量正文或 HTML 标签时继续拆。
先用页面渲染离线检查,再运行参考站点,核对首页、关于页与 API。
新增结构需修改 plugins/web/internal/artifact 并同步双语工具与 web_handbook 测试。
## 规则
返回布局工程规则映射,供智能体与验收清单使用。无参数。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 规则表 |
| result | any | 布局实践约定 |
返回先拆布局、递归到 Markdown 叶子的工程约定。无参数;
规则是说明,不声称已静态审查某个文件。真正验收需要运行并检查站点。
*> layout.rules*
## 视图契约
返回唯一允许的 View 列名(英文)。中文别名为 `类型|槽|值|属性|样式`。无参数。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 列名列表 |
| result | list | View 列名 |
返回五个公共列名。子块通过值列继续包含同样的 View 记录;
不增加第二种布局表方言,也不把任意属性名解释为 CSS。
*> layout.view_schema*
## 合并节点
拼接 View 节点表 `甲` 与 `乙`。区域拆文件后,用本工具组装而不写 HTML。
| 参数 | 类型 | 说明 |
|------|------|------|
| 甲 | any | 第一张 View 表 |
| 乙 | any | 第二张 View 表 |
| 甲 | list | 第一组节点 |
| 乙 | list | 第二组节点 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 合并后的节点 |
| result | list | 兄弟节点 |
拼接 `甲` 与 `乙`,只保留顺序,不增加几何关系。
需要横向排列时使用分栏,需要上下分区时使用纵排。
*> layout.merge_nodes a=`甲` b=`乙`*
## 验收组件
文档门:传入组件 `名`(文件名)与单一职责 `职责`(一句话)。返回验收行,提醒
必须保持单一职责。不写磁盘。
## 纵排
| 参数 | 类型 | 说明 |
|------|------|------|
| 名 | text | 组件名,如 导航 |
| 子节点 | list | 子块列表 |
| 槽 | text | 父区域名 |
| 样式 | text | 可选类名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 父容器节点 |
为 `子节点` 声明一层上下顺序。默认 `槽`=""、`样式`=""。
父块只负责排列,内容和更深层结构留在导入的子组件。结果仍是 View 节点列表,
可以继续传给祖先组件或页面渲染,无需提前转为 HTML。
*> layout.stack children=`子节点` slot=`槽` style=`样式`*
## 分栏
| 参数 | 类型 | 说明 |
|------|------|------|
| 子节点 | list | 子块列表 |
| 槽 | text | 父区域名 |
| 样式 | text | 可选类名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 父容器节点 |
为 `子节点` 声明一层响应式多栏。默认 `槽`=""、`样式`=""。
父块只负责排列,内容和更深层结构留在导入的子组件。结果仍是 View 节点列表,
可以继续传给祖先组件或页面渲染,无需提前转为 HTML。
*> layout.columns children=`子节点` slot=`槽` style=`样式`*
## 验收组件
| 参数 | 类型 | 说明 |
|------|------|------|
| 名 | text | 组件名称 |
| 职责 | text | 单一职责描述 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 验收行 |
| result | any | 待人工或测试核对的清单 |
为 `名` 与 `职责` 返回待检查的条目。仅依据这两个文本无法证明组件合格,
所以结果明确标注为清单,调用者仍须检查文件内容与渲染结果,不自动发放通过标签。
*> layout.accept_component name=`名` duty=`职责`*
+41 -96
View File
@@ -2,58 +2,28 @@
markup: occlusion
title: ext/web/网页
description: >-
Web Artifact 中文根 skill(ADR 0007)— 文件划分布局;页面 · 路由 · 服务 · 渲染 · 检视。
禁止 compose_* / configure / 作者侧确保插件;禁止默认 HTML/CSS 注入。
Web Artifact 中文作者门面(ADR 0007)— 页面 · 路由 · 服务 · 渲染 · 检视。
智能体请先读 ext/web/网页/索引.mq.md。禁止 compose_* / configure / 默认 HTML 注入。
import:
web: ext/web/web.mq.md
布局: ext/web/布局/索引.mq.md
---
本文件是 Marqdo 网络(web)扩展的中文根 skill。若你是没有其它上下文的智能体,
请先读「选哪条路」与「布局铁律」,再按 call 形状执行。不要发明 MCP、整页 HTML
或第二套 API。`##` 标题就是工具。
门面模块:从[中文根手册](网页/索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
## 选哪条路
```sh
marqdo call ext/web/网页.mq.md 渲染 '正文="# 文档"' '标题="预览"' --effects plugin --json
marqdo call ext/web/网页.mq.md 检视 '根="examples/web-layout-handbook"' --effects plugin --json
```
只选一行。不要混用中英工具名。
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
| 若你需要 | 这样做 |
|----------|--------|
| 写站前的布局规则 | 调用本包 `布局.规则`(或 `ext/web/布局/索引.mq.md` 的 `规则`) |
| 预览 Document / View | `渲染`,加 `--effects plugin` |
| 启动站点 | 作者程序 `服务`,或 call `服务` 并传 `根=` · `端口=` |
| 英文工具名 | 改开 `ext/web/index.mq.md`,留在英文树 |
智能体默认 `##` + `marqdo call`。`# page` 等对象给作者程序。`dom.raw` /
`page.css` 不是首页默认做法。
*None*
## 布局铁律
网页靠文件划分建造,不靠注入 HTML。首页拆成导航、侧栏、主区、底栏等文件。某一
区仍复杂(双栏底栏、密样式)时再拆,直到每文件单一职责、一张 View 或短
Markdown。值、库与具名样式只走统一 View 列(类型、槽、值、属性、样式,或英列
名)。默认禁止整页 HTML 字符串、CSS 注入袋、compose 碎片与 json.set 拼 DOM。
逃逸舱仅限 dom.raw / page.css,且必须写明为何不能表驱动。
详见 doc/design/ext-web-layout-paradigm.md。包内工具:ext/web/布局/索引.mq.md。
调用示例(纯文本):
marqdo call ext/web/布局/索引.mq.md 规则 --json
marqdo call ext/web/网页.mq.md 布局规则 --json
*None*
## 如何执行任意工具
调用示例(纯文本):
marqdo call FILE FUNCTION 名=值 --effects plugin --json
FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`。布局规则类
工具可纯 call。不要调用 `确保插件` 或 `host_*`。
*None*
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 布局规则
@@ -66,17 +36,6 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> 布局.规则*
## 页面
+ `标题`=""
+ `路由`="/"
+ `方法`="GET"
+ `正文`=""
+ `节点`=None
+ `数据源`=""
+ `排序`=""
+ `条件`=""
构造 Document 句柄。站点页面优先用 `类型: 网页` Artifact,由 `服务` 发现;本工具
供预览或程序化构造。节点必须是统一 View 表,不是 HTML。
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -89,6 +48,11 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
| 排序 | text | 如 -created_at |
| 条件 | text | col=val 列表 |
构造 Document 句柄,默认 `标题`=""、`路由`="/"、`方法`="GET"、`正文`=""、
`节点`=None、`数据源`=""、`排序`=""、`条件`=""。站点页面优先用 `类型: 网页`
Artifact,由 `服务` 发现;本工具供预览或程序化构造。节点必须是统一 View 表,
不是 HTML。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 页面句柄 |
@@ -96,16 +60,6 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> web.page title=`标题` route=`路由` method=`方法` body=`正文` nodes=`节点` data_source=`数据源` data_order=`排序` data_where=`条件`*
## 路由
+ `应用`
+ `路径`
+ `方法`="GET"
+ `页面`=None
+ `函数`=""
+ `请求`="json"
+ `响应`="json"
+ `鉴权`=""
注册已声明的 Document 或 Endpoint。不要隐式注册用户路由。
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -118,6 +72,9 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
| 响应 | text | 响应类型 |
| 鉴权 | text | 鉴权标签 |
在 `应用` 上注册已声明 Document 或 Endpoint:`路径`、`方法`="GET"、`页面`=None、
`函数`=""、`请求`="json"、`响应`="json"、`鉴权`=""。不要隐式注册用户路由。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 路由结果 |
@@ -125,14 +82,6 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> web.route app=`应用` path=`路径` method=`方法` page=`页面` fn=`函数` request=`请求` response=`响应` auth=`鉴权`*
## 渲染
+ `文档`=None
+ `节点`=None
+ `正文`=""
+ `标题`=""
+ `数据库`=None
把 Document 或 View 节点渲染为 HTML(预览)。输入应来自 Markdown/View,而不是
手写 HTML 大字符串。
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -142,6 +91,10 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
| 标题 | text | 标题 |
| 数据库 | any | 可选 db |
把 Document 或 View 节点渲染为 HTML(预览)。可选 `文档`=None、`节点`=None、
`正文`=""、`标题`=""、`数据库`=None。输入应来自 Markdown/View,而不是手写 HTML
大字符串。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML 或渲染结果 |
@@ -149,16 +102,14 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> web.render doc=`文档` nodes=`节点` body=`正文` title=`标题` db=`数据库`*
## 使用
+ `应用`
+ `中间件`
一等中间件(表驱动)。禁止 `configure(...)` 垃圾抽屉。
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用句柄 |
| 中间件 | any | 中间件表 |
把 `中间件` 挂到 `应用`(表驱动)。禁止 `configure(...)` 垃圾抽屉。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 应用句柄 |
@@ -166,30 +117,23 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> web.use app=`应用` middleware=`中间件`*
## 检视
+ `应用`=None
返回 `{declared, system}` 路由表。
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用或 None |
| 根 | text | 离线扫描的站点目录 |
返回 `{declared, system}` 路由表;可选 `应用`=None。
可选 `根`="",给出时扫描站点目录,不启动服务器。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 路由检视 |
*> web.inspect app=`应用`*
*> web.inspect app=`应用` root=`根`*
## 服务
+ `根`="."
+ `主机`="127.0.0.1"
+ `端口`=18081
+ `数据库`=None
+ `静态目录`=""
+ `中间件`=None
扫描 `根/**/*.mq.md` 中 `类型: 网页|端点`,注册声明路由并监听。站点目录应已按
布局铁律拆好组件文件。
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -200,6 +144,10 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
| 静态目录 | text | 静态资源 |
| 中间件 | any | 可选中间件 |
扫描 `根`="." 下 `类型: 网页|端点` Artifact,注册声明路由并在 `主机`="127.0.0.1"
与 `端口`=18081 监听。可选 `数据库`=None、`静态目录`=""、`中间件`=None。站点
目录应已按布局铁律拆好组件文件。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 服务结果 |
@@ -207,12 +155,6 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
*> web.serve root=`根` host=`主机` port=`端口` db=`数据库` static_dir=`静态目录` middleware=`中间件`*
## 客户端挂载
+ `桥`="/static/marqdo-bridge.js"
+ `wasm`="/static/marqdo_wasm.wasm"
+ `源`=""
+ `启动`=True
嵌入 WASM 桥。不是用 HTML 字符串拼整页的借口。
| 参数 | 类型 | 说明 |
|------|------|------|
@@ -221,6 +163,9 @@ FILE 在 `ext/web/` 下。涉及原生插件的工具必须 `--effects plugin`
| 源 | text | 可选源 |
| 启动 | bool | 是否自动 boot |
嵌入 WASM 桥,默认 `桥`="/static/marqdo-bridge.js"、`wasm`="/static/marqdo_wasm.wasm"、
`源`=""、`启动`=True。不是用 HTML 字符串拼整页的借口。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 挂载描述 |
+74
View File
@@ -0,0 +1,74 @@
---
markup: occlusion
title: ext/web/网页/客户端
description: 浏览器 Runtime 辅助(WASM 桥)。效果表优先 lib/browser(ADR 0007)。
import:
client: ext/web/client/index.mq.md
---
客户端模块:从[中文根手册](../索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
```sh
marqdo call ext/web/网页/客户端/索引.mq.md 挂载 --json
marqdo call ext/web/网页/客户端/索引.mq.md 文本补丁 '选择器="#status"' '文本="就绪"' --json
```
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 挂载
| 参数 | 类型 | 说明 |
|------|------|------|
| 桥 | text | bridge 脚本 URL |
| wasm | text | wasm URL |
| 源 | text | 可选源 |
| 启动 | bool | 自动启动 |
返回加载官方浏览器桥的 HTML 片段。默认 `桥`="/static/marqdo-bridge.js"、
`wasm`="/static/marqdo_wasm.wasm"、`源`=""、`启动`=True。不是用 HTML 拼整页的
借口。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | script 标签 HTML |
*> client.embed bridge=`桥` wasm=`wasm` source=`源` boot=`启动`*
## 文本补丁
| 参数 | 类型 | 说明 |
|------|------|------|
| 选择器 | text | CSS 选择器 |
| 文本 | text | 文本内容 |
为选择器 `选择器` 构造 `set_text` 效果表,文本为 `文本`。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 效果表 |
*> client.text_patch sel=`选择器` text=`文本`*
## 节点补丁
| 参数 | 类型 | 说明 |
|------|------|------|
| 选择器 | text | CSS 选择器 |
| html | text | 可选 HTML |
| 属性 | any | 可选属性表 |
| 移除 | bool | 是否移除 |
为选择器 `选择器` 构造 `dom` 效果表。可选 `html`=""、`属性`=None、`移除`=False。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 效果表 |
*> client.dom_patch sel=`选择器` html=`html` attrs=`属性` remove=`移除`*
@@ -0,0 +1,65 @@
---
markup: occlusion
title: ext/web/网页/文档对象模型
description: DOM Artifact — Markdown 默认;raw HTML 仅逃逸舱(ADR 0007)。
import:
dom: ext/web/dom/index.mq.md
---
文档对象模型模块:从[中文根手册](../索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
```sh
marqdo call ext/web/网页/文档对象模型/索引.mq.md 自Markdown '文本="# 可读"' --session handbook --toget body --json
marqdo call ext/web/网页/文档对象模型/索引.mq.md 渲染 'dom=$body' --effects plugin --session handbook --json
```
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 自Markdown
| 参数 | 类型 | 说明 |
|------|------|------|
| 文本 | text | Markdown 源 |
把 Markdown `文本` 变成 `{kind:"markdown", text}`,供页面渲染。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM 映射 |
*> dom.from_markdown text=`文本`*
## 原始
| 参数 | 类型 | 说明 |
|------|------|------|
| html | text | 原始 HTML |
逃逸舱 — 包装原始 `html`。仅当表驱动无法表达宿主约束时使用,并写明原因。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | DOM 映射 kind=raw |
*> dom.raw html=`html`*
## 渲染
| 参数 | 类型 | 说明 |
|------|------|------|
| dom | any | 自Markdown 或 原始 的结果 |
把 DOM 映射 `dom` 渲染为 HTML(须插件)。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML 文本 |
*> dom.render dom=`dom`*
+219
View File
@@ -0,0 +1,219 @@
---
markup: occlusion
title: ext/web/网页
description: 网络库可执行开发手册;先拆布局,直到 Markdown 叶子。
import:
布局: ext/web/布局/索引.mq.md
网页: ext/web/网页.mq.md
---
网络扩展手册:先描述页面如何拆分,再写各块内容,最后预览、起站和验证。
普通 .mq.md 函数就是工具,无需另一套 Skill 编译器或工具目录。
安装用户先执行 marqdo ext add web;源码开发先用 bash scripts/build-web-plugin.sh 构建
Go 插件,必要时用 MARQDO_WEB_PLUGIN 指向其绝对路径,不能把安装根覆盖到源码 ext。
先看可执行结果
以下命令从仓库根运行;安装后把 FILE 换为安装根下对应路径。
call 的文本字面量需要保留内层双引号,会话引用必须保护美元符号。
同时检查退出码与 JSON 的 ok,再读取 result。
```sh
marqdo call ext/web/网页/索引.mq.md 布局规则 --json
marqdo call ext/web/网页/索引.mq.md 预览正文 '正文="# 可读页面"' '标题="预览"' --effects plugin --json
marqdo call ext/web/网页/索引.mq.md 预览节点 '节点=[{"type":"row","value":[{"type":"markdown","value":"## 左栏"},{"type":"markdown","value":"## 右栏"}]}]' --effects plugin --json
```
先拆布局的工程实践
首页先拆为导航、主体和页脚。页脚有左右布局,就拆成品牌栏与链接栏;链接栏若还有
双栏,再拆文档和社区。递归进行,直到内部只是简单 Markdown 能直接表示的内容。
终点是单一内容职责且不再需要内部排布,不是每段话都新建文件。
```text
site/
index.mq.md Document,选择布局根
components/index.mq.md 纵排:导航、主体、页脚
nav/index.mq.md 一个导航职责
nav/content.md 普通 Markdown 链接
main/index.mq.md
main/content.md 普通 Markdown 正文
footer/index.mq.md 分栏:品牌、链接
brand/index.mq.md
brand/content.md 品牌与版权
links/index.mq.md 分栏:文档、社区
docs/index.mq.md
docs/content.md 文档链接
community/index.mq.md
community/content.md 社区链接
pages/about.mq.md 另一条声明路由
api/ping.mq.md Endpoint
preview.mq.md 离线装配并渲染
serve.mq.md 启动进程,不放页面内容
```
每个父 index 只导入子块、组合子节点、选择一层布局;每个叶子 content.md 只写 Markdown。
父块出现大段正文、多种布局职责或 HTML 标签就继续拆;叶子不负责外部排列。
不应先写整页 HTML,再把这个字符串切成几个文件。默认也不靠内联 CSS 对齐。
复杂表格、表单、数据源和交互按各自职责再分模块,不能以此回填整页 HTML 壳。
跟着真实工程做
[中文参考站点](../../../examples/web-layout-handbook-zh/index.mq.md)实现完整目录,
沿[组件根](../../../examples/web-layout-handbook-zh/components/index.mq.md)可一直走到页脚孙级叶子。
[英文工程](../../../examples/web-layout-handbook/index.mq.md)用同一表示与渲染器。
先从仓库根生成预览,再从站点目录运行服务:
```text
marqdo run examples/web-layout-handbook-zh/preview.mq.md
cd examples/web-layout-handbook-zh
marqdo run serve.mq.md
```
检查 / 首页、/about 普通文档、/api/ping JSON。首页应真的出现父子嵌套与两个页脚区域,
不是把同一组节点平铺。宽屏横排,窄屏自动折叠,无需作者手写 HTML 或 CSS。
现有五列怎样表达树
公共 View 列仍为 type、slot、value、attrs、style,中文别名为 类型、槽、值、属性、样式。
记录表首列使用 @,让输出为节点列表。父节点类型 row/column 表示几何,值列保留子表;
nav/header/footer/section/aside 表示语义区域。markdown 的值是正文字符串。
类型和值没有变成另一种私有 DSL。合并仅生成兄弟顺序,分栏才产生几何关系。
style 是类名引用,不会凭空定义 CSS;运行时内置默认布局,主题后续按独立资源处理。
最小叶子可以直接以 Markdown 文本调用组件正文。文件较长时像参考工程一样从
content.md 读取,这样原始文件无需转义字符串。父文件不用提前渲染子组件。
```marqdo
---
markup: occlusion
导入:
组件: ext/web/网页/组件/索引.mq.md
布局: ext/web/布局/索引.mq.md
网页: ext/web/网页.mq.md
---
# main
**left = 组件.正文 文本="### 品牌" 槽="brand"**
**right = 组件.正文 文本="[关于](/about)" 槽="links"**
**siblings = 组件.合并 甲=`left` 乙=`right`**
**footer = 布局.分栏 子节点=`siblings` 槽="footer"**
**html = 网页.渲染 节点=`footer` 标题="分栏预览"**
> 打印 内容=`html`
```
Document、Endpoint 与运行边界
普通 Document 用 类型: 网页、路由、标题和 Markdown 正文,保留原来的静态/数据源路径。
组件 Document 另外声明 视图: main,其 # main 返回节点列表;服务在启动时执行装配一次,
通过同一渲染器生成 HTML。改内容后重启。自动数据源绑定使用普通 Document,不与此启动装配混用。不要在这个装配函数里再启动服务器或调用渲染;
它返回结构即可。请求期互动放在 Endpoint,声明 类型: 端点、路径、方法、请求、响应,
主程序返回响应值。不要把启动时装配误解为自动的请求期模板绑定。
serve 是长时间运行的生命周期操作,用 launcher 的 marqdo run 启动。
call 适合纯构造、离线预览与检视;--effects plugin 不授予网络或文件写入权限,
不能把 call 服务当成起站方式。网页检视给出根目录时可离线扫描声明;新进程中的空应用
不能检视另一个进程的私有路由状态。
```sh
marqdo call ext/web/网页.mq.md 检视 '根="examples/web-layout-handbook-zh"' --effects plugin --json
```
按职责打开模块
[布局](../布局/索引.mq.md)教会何时继续拆、纵排与分栏;[组件](组件/索引.mq.md)负责
Markdown 叶子与语义包裹;[页面](页面/索引.mq.md)负责句柄与离线渲染;
[路由](路由/索引.mq.md)用于高级手动声明,整站默认走 Metadata。
[文档对象模型](文档对象模型/索引.mq.md)提供内容转换,原始 HTML 仅为兼容边界。
[客户端](客户端/索引.mq.md)挂载 Marqdo WASM,业务交互继续使用 lib/browser;
[能力](能力/索引.mq.md)只诊断原生加载。[门面](../网页.mq.md)保留服务、渲染、检视和应用 API。
数据库、鉴权、HTTP 客户端分别去 ext/data、ext/security、ext/net。
开发路线与验收
先尝试组合现有 Markdown、纵排、分栏。新增原语才修改 plugins/web/internal/artifact
与 ABI 导出,普通页面不要新增宿主原语。保持双语入口与五列结构,参数契约紧跟标题,
返回契约也在首条执行语句之前。## 只能用于真正工具,普通说明保持叙述段落。
新增文件时更新 src/ext_cli.rs 安装清单。修改 Document 启动装配要保留普通文档与 API 的行为。
```text
cargo test --locked --test web_handbook
cargo test --locked --test call_cli web_
cargo test --locked --test gold ext_web -- --test-threads=1
```
手册门禁直接执行本包双语 sh 围栏与作者程序,另外预览并启动参考工程,核对路由、
嵌套结构和 API。叙述比例只作最低门槛,清单不能无条件发放“通过”。
当前没有自动把任意网页拆成组件的功能,也没有靠样式列实现完整 CSS 编译器。
布局仍是作者的显式设计决定,这些入口与运行证据帮助 AI 遵守它。
## 建站手册
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Development workflow and stopping rule |
返回建站流程与拆分终点,不执行文件操作,也不声称已经验收某个站点。
先建立区域树,再写父组件与 Markdown 叶子,最后按声明路由启动并测试。
`workflow` =
| key | value |
|-----|-------|
| goal | build a site as executable documents |
| step_A | draw region tree before content |
| step_B | recursively split components to Markdown leaves |
| step_C | declare home Document and view main for composed structure |
| step_D | declare more Documents with their own routes |
| step_E | declare Endpoint handlers for request-time work |
| step_F | run serve.mq.md from the site directory |
| step_G | compare preview and live output; test routes and browser geometry |
| stopping_rule | one Markdown responsibility and no internal layout |
*workflow*
## 布局规则
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Development workflow and stopping rule |
复用布局模块的实践约定,保持一个真相源。无参数,不需要插件。
规则描述预期做法,实际站点仍需检查叶子、父关系与运行结果。
*> 布局.规则*
## 预览正文
| 参数 | 类型 | 说明 |
|------|------|------|
| 正文 | text | Markdown content |
| 标题 | text | Document title |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | HTML document |
离线渲染 Markdown `正文`="",默认 `标题`="Preview"。
此工具只返回 HTML 文本,不写文件、不注册路由。复杂页面先拆布局,
不要用整页原生 HTML 字符串冒充正文。需要原生插件。
*> 网页.渲染 正文=`正文` 标题=`标题`*
## 预览节点
| 参数 | 类型 | 说明 |
|------|------|------|
| 节点 | list | Nested View rows |
| 标题 | text | Document title |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | text | HTML document |
渲染已经按职责拆分的 `节点`,默认 `标题`="Preview"。
父节点的值继续持有子节点,叶子值为 Markdown;返回 HTML 不会启动服务。
与真实 Document 的装配使用同一渲染器,能检查双栏是否确实保留了层级。
*> 网页.渲染 节点=`节点` 标题=`标题`*
+92
View File
@@ -0,0 +1,92 @@
---
markup: occlusion
title: ext/web/网页/组件
description: 纯组件:Markdown 叶子与嵌套 View 节点。
import:
component: ext/web/component/index.mq.md
---
组件是返回 View 记录列表的普通函数。父文件只表达子块关系,叶子只负责一段 Markdown。
页脚拆成品牌与链接,链接若仍是双栏就继续拆,直到每个文件只有一个可解释的内容职责。
完整参考见[拆分站点](../../../../examples/web-layout-handbook/index.mq.md)。
以下构造均为纯函数,无需插件或已有句柄:
```sh
marqdo call ext/web/网页/组件/索引.mq.md 正文 '文本="## 可读的叶子"' '槽="介绍"' --json
marqdo call ext/web/网页/组件/索引.mq.md 包裹 '子节点=[{"type":"markdown","value":"左"},{"type":"markdown","value":"右"}]' '种类="row"' --json
marqdo call ext/web/网页/组件/索引.mq.md 合并 '甲=[{"type":"text","value":"前"}]' '乙=[{"type":"text","value":"后"}]' --json
```
复用组件使用 @ 记录表,合并只确定兄弟顺序,不会自动产生双栏。布局请转到
[布局入口](../../布局/索引.mq.md),渲染交给[页面](../页面/索引.mq.md)。
新增内容先在站点组件目录实现;新结构类型需同步 Go 渲染器、双语入口与实际页面测试。
不要先渲染子块再拼 HTML 字符串,值单元格应保留子节点列表本身。
## 节点
| 参数 | 类型 | 说明 |
|------|------|------|
| 表 | any | View 表 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Result |
原样返回 `表`,保留已有恒等入口。可接受列式表或记录列表;
需要组合和嵌套时统一选择 @ 记录列表,让子表保持结构值而不是字符串。
*> component.nodes table=`表`*
## 合并
| 参数 | 类型 | 说明 |
|------|------|------|
| 甲 | list | 第一组节点记录 |
| 乙 | list | 第二组节点记录 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 有序兄弟节点 |
拼接 `甲` 与 `乙`,保留顺序和内部父子关系。输入均为 @ 记录列表;
本工具不把平面节点变成两栏,需要双栏时再交给布局的分栏工具。
*> component.merge a=`甲` b=`乙`*
## 正文
| 参数 | 类型 | 说明 |
|------|------|------|
| 文本 | text | 普通 Markdown |
| 槽 | text | 区域名 |
| 样式 | text | 可选类名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 单个 Markdown 叶子 |
将 Markdown `文本` 包成叶子,默认 `槽`=""、`样式`=""。
不加载原生插件,输出仍为结构数据;标题、链接、列表与表格在渲染时处理。
叶子不关心自己位于页脚左栏还是其他位置,父组件负责几何关系。
*> component.markdown text=`文本` slot=`槽` style=`样式`*
## 包裹
| 参数 | 类型 | 说明 |
|------|------|------|
| 子节点 | list | 子块记录列表 |
| 种类 | text | 容器类型 |
| 槽 | text | 区域名 |
| 样式 | text | 可选类名 |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | list | 包含子节点的父块 |
将 `子节点` 放进一层父容器,默认 `种类`="column"、`槽`=""、`样式`=""。
几何类型为 row、column;语义类型包括 nav、header、footer、section、aside。
值单元格保留子表,不承载拼好的 HTML;构造器只生成结构,实际形状由渲染器检查。
*> component.wrap children=`子节点` kind=`种类` slot=`槽` style=`样式`*
+33
View File
@@ -0,0 +1,33 @@
---
markup: occlusion
title: ext/web/网页/能力
description: Web ABI 加载 skill。日常请走领域模块;诊断插件时再 call 加载。
import:
cap: ext/web/_capability/index.mq.md
---
能力模块:从[中文根手册](../索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
```sh
marqdo call ext/web/网页/能力/索引.mq.md 加载 --effects plugin --json
```
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 加载
通过 plugin.native_path 定位 ABI v2 web 动态库并 plugin.load。缺失时打印安装提
示并以非零退出。无参数。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 加载成功后为空 |
*> cap.load*
+77
View File
@@ -0,0 +1,77 @@
---
markup: occlusion
title: ext/web/网页/路由
description: 声明式 Endpoint / Document 路由注册(ADR 0007)。
import:
route: ext/web/route/index.mq.md
---
路由模块:从[中文根手册](../索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
```sh
marqdo call ext/web/网页/路由/索引.mq.md 新建 '应用={}' '路径="/hello"' '页面={"title":"Hello","body":"Hi"}' --effects plugin --session handbook --toget route --json
marqdo call ext/web/网页/路由/索引.mq.md 注册 '路由=$route' --effects plugin --session handbook --json
```
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 新建
| 参数 | 类型 | 说明 |
|------|------|------|
| 应用 | any | 应用句柄 |
| 路径 | text | URL 路径 |
| 方法 | text | HTTP 方法 |
| 页面 | any | Document 或 None |
| 函数 | text | Endpoint 成员 |
| 请求 | text | 请求体类型 |
| 响应 | text | 响应类型 |
| 鉴权 | text | 鉴权标签 |
| 类别 | text | 路由类别 |
为 `应用` 在 `路径` 上构造路由句柄,`方法`="GET"。`页面`=None 或 `函数`="" 二
选一。`请求`="json"、`响应`="json"、`鉴权`=""、`类别`=""。本工具尚未注册——再
调 `注册`,或用门面 `路由` 一步完成。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 路由句柄 |
*> route.new app=`应用` path=`路径` method=`方法` page=`页面` fn=`函数` request=`请求` response=`响应` auth=`鉴权` class=`类别`*
## 注册
| 参数 | 类型 | 说明 |
|------|------|------|
| 路由 | any | 路由句柄 |
| 应用 | any | 应用或 None |
把路由句柄 `路由` 注册到应用;可选 `应用`=None 时用句柄内保存的应用。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 注册结果 |
*> route.register route=`路由` app=`应用`*
## 使用
| 参数 | 类型 | 说明 |
|------|------|------|
| 路由 | any | 路由句柄 |
| 中间件 | any | 中间件表 |
给路由句柄 `路由` 挂上中间件表 `中间件`。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 结果 |
*> route.use route=`路由` middleware=`中间件`*
+62
View File
@@ -0,0 +1,62 @@
---
markup: occlusion
title: ext/web/网页/页面
description: Document 句柄与渲染(ADR 0007)。文件划分布局;禁止默认 HTML 注入。
import:
page: ext/web/page/index.mq.md
---
页面模块:从[中文根手册](../索引.mq.md)选择业务路径。
布局先拆成父组件与 Markdown 叶子,默认不写整页 HTML。构造值与启动进程是两件事;
下面示例从生产者开始,所有句柄沿同一会话传递,渲染时才需要原生插件。
```sh
marqdo call ext/web/网页/页面/索引.mq.md 新建 '标题="预览"' '正文="# 你好"' --effects plugin --session handbook --toget pg --json
marqdo call ext/web/网页/页面/索引.mq.md 渲染 '页面=$pg' --effects plugin --session handbook --json
```
页面结构用五列 View 记录,父值保留子表。纯布局、DOM 构造和客户端描述无需插件。
整站服务通过 launcher 的 marqdo run 启动;检视磁盘站点请给出根目录,不能从新进程
读取另一个进程的私有应用。结构化 Document 使用 视图: main,在启动时执行布局装配。
开发时先复用组件和布局模块,再改对应领域实现;保持中英入口与真实契约一致。
验证 web_handbook 与既有 Web Artifact 金样,资源、鉴权和网络能力不要塞回门面。
## 新建
| 参数 | 类型 | 说明 |
|------|------|------|
| 标题 | text | 文档标题 |
| 路由 | text | 路径 |
| 方法 | text | HTTP 方法 |
| 正文 | text | Markdown 正文 |
| 节点 | any | View 表或 None |
| 数据源 | text | 表名 |
| 排序 | text | 排序键 |
| 条件 | text | 过滤 |
构造 Document 句柄,默认 `标题`=""、`路由`="/"、`方法`="GET"、`正文`=""、
`节点`=None、`数据源`=""、`排序`=""、`条件`=""。节点必须是统一 View 表。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | 页面句柄 |
*> page.new title=`标题` route=`路由` method=`方法` body=`正文` nodes=`节点` data_source=`数据源` data_order=`排序` data_where=`条件`*
## 渲染
| 参数 | 类型 | 说明 |
|------|------|------|
| 页面 | any | Document 句柄 |
| 节点 | any | View 表或 None |
| 数据库 | any | 可选 db |
渲染 Document 句柄 `页面`。可选 `节点`=None、`数据库`=None。不要把手写 HTML 当
作页面壳。
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML 或渲染结果 |
*> page.render page=`页面` nodes=`节点` db=`数据库`*
+32 -24
View File
@@ -26,6 +26,7 @@ import (
"github.com/marqdo/marqdo/plugins/web/internal/httpx"
"github.com/marqdo/marqdo/plugins/web/internal/middleware"
"github.com/marqdo/marqdo/plugins/web/internal/page"
"github.com/marqdo/marqdo/plugins/web/internal/plugin"
)
//export web_render_nodes
@@ -123,27 +124,32 @@ func web_serve_root(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
}
}
}
homeArgs := map[string]any{"title": "Marqdo"}
var homeMeta map[string]string
documentPage := func(f artifact.ArtifactFile) (map[string]any, error) {
title := f.Meta["title"]
if title == "" {
title = f.Meta["标题"]
}
body, structured, err := artifact.RenderFile(f, plugin.RunArtifact)
if err != nil {
return nil, err
}
pg := page.New(map[string]any{"title": title, "intro": body})
stampArtifactData(pg, f.Meta)
if structured {
pg["artifact_html"] = artifact.RenderHTMLPage(title, body)
}
return pg, nil
}
home := page.New(map[string]any{"title": "Marqdo"})
for _, f := range files {
if f.Kind == "web" && (f.Route == "/" || f.Rel == "index.mq.md") {
title := f.Meta["title"]
if title == "" {
title = f.Meta["标题"]
if f.Kind == "web" && f.Route == "/" {
home, err = documentPage(f)
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
}
if title == "" {
title = "Marqdo"
}
homeArgs = map[string]any{
"title": title,
"intro": artifact.MarkdownHTML(f.Body),
}
homeMeta = f.Meta
break
}
}
home := page.New(homeArgs)
stampArtifactData(home, homeMeta)
a := app.New(map[string]any{
"page": home,
"db": args["db"],
@@ -156,15 +162,10 @@ func web_serve_root(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
if f.Route == "/" {
continue
}
title := f.Meta["title"]
if title == "" {
title = f.Meta["标题"]
pg, err := documentPage(f)
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
}
pg := page.New(map[string]any{
"title": title,
"intro": artifact.MarkdownHTML(f.Body),
})
stampArtifactData(pg, f.Meta)
out, err := app.Route(a, f.Route, pg)
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
@@ -230,6 +231,13 @@ func web_inspect(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
}
if root, ok := argStr(args, "root"); ok && root != "" {
files, err := artifact.ScanRoot(root)
if err != nil {
return replyJSON(outJSON, errMsg, nil, err)
}
return replyJSON(outJSON, errMsg, artifact.InspectBag(nil, files), nil)
}
a := asPageMap(args["app"])
if a != nil {
if insp, ok := a["inspect"].(map[string]any); ok {
+145 -18
View File
@@ -9,7 +9,6 @@ import (
"strings"
"github.com/marqdo/marqdo/plugins/web/internal/render"
"github.com/marqdo/marqdo/plugins/web/internal/table"
)
// MetaType returns canonical kind: web | endpoint | "" from flat frontmatter map.
@@ -92,19 +91,77 @@ func ParseFrontmatter(src string) (meta map[string]string, body string) {
return meta, body
}
// RenderNodes turns a unified View table into an HTML fragment.
// Columns: type|slot|value|attrs|style (ZH: 类型|槽|值|属性|样式).
// RenderNodes renders the existing five-column View schema recursively. Container
// value cells hold more View rows; markdown leaves hold ordinary Markdown text.
func RenderNodes(nodes any) (string, error) {
raw := table.AsRows(nodes)
list, _ := raw.([]any)
var b strings.Builder
b.WriteString(`<div class="mq-view">`)
for _, item := range list {
b.WriteString(`<style>` + LayoutCSS + `</style><div class="mq-view">`)
if err := renderNodes(&b, nodes, 0); err != nil {
return "", err
}
b.WriteString(`</div>`)
return b.String(), nil
}
// Fixed runtime geometry, shared by offline previews and served Documents.
// Authors choose row/column instead of embedding CSS or HTML in content cells.
const LayoutCSS = `.mq-view{max-width:72rem;margin:auto;padding:1.5rem;line-height:1.6;font-family:system-ui,sans-serif}.mq-view *{box-sizing:border-box}.mq-view .mq-row{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,16rem),1fr));gap:1.5rem}.mq-view .mq-column{display:flex;flex-direction:column;gap:1.5rem}.mq-view .mq-node{min-width:0}.mq-view nav,.mq-view footer{padding-block:1rem}.mq-view footer{border-top:1px solid #d5dce5}.mq-view a{color:#2457a7}.mq-view img{max-width:100%;height:auto}.mq-view pre{overflow:auto}`
// Preserve typed value cells when normalizing column tables. General AsRows
// treats @ cells as text, which would stringify nested component tables.
func viewRows(nodes any) ([]any, error) {
switch v := nodes.(type) {
case nil:
return nil, nil
case []any:
return v, nil
case map[string]any:
if _, ok := v["type"].(string); ok {
return []any{v}, nil
}
if _, ok := v["类型"].(string); ok {
return []any{v}, nil
}
n := -1
for _, cell := range v {
col, ok := cell.([]any)
if !ok {
return nil, fmt.Errorf("View: expected a row or column table")
}
if n < 0 {
n = len(col)
} else if n != len(col) {
return nil, fmt.Errorf("View: column lengths differ")
}
}
rows := []any{}
for i := 0; i < n; i++ {
row := map[string]any{}
for key, cell := range v {
row[key] = cell.([]any)[i]
}
rows = append(rows, row)
}
return rows, nil
default:
return nil, fmt.Errorf("View: expected rows, got %T", nodes)
}
}
func renderNodes(b *strings.Builder, nodes any, depth int) error {
if depth > 64 {
return fmt.Errorf("View: nesting exceeds 64 levels")
}
rows, err := viewRows(nodes)
if err != nil {
return err
}
for i, item := range rows {
row, ok := item.(map[string]any)
if !ok {
continue
return fmt.Errorf("View row %d: expected a map", i+1)
}
ty := first(row, "type", "类型")
ty := strings.ToLower(first(row, "type", "类型"))
slot := first(row, "slot", "槽")
val := first(row, "value", "值")
attrs := first(row, "attrs", "属性")
@@ -116,23 +173,92 @@ func RenderNodes(nodes any) (string, error) {
if slot != "" {
class += " slot-" + html.EscapeString(slot)
}
switch strings.ToLower(ty) {
tag := ""
switch ty {
case "row", "横排":
tag = "div"
class += " mq-row"
case "column", "纵排":
tag = "div"
class += " mq-column"
case "nav", "导航":
tag = "nav"
case "header", "页头":
tag = "header"
case "footer", "页脚":
tag = "footer"
case "section", "区域":
tag = "section"
case "aside", "侧栏":
tag = "aside"
}
if tag != "" {
children := row["value"]
if children == nil {
children = row["值"]
}
if children == nil {
return fmt.Errorf("View row %d (%s): missing child rows in value", i+1, ty)
}
b.WriteString(`<` + tag + ` class="` + class + `">`)
if err := renderNodes(b, children, depth+1); err != nil {
return fmt.Errorf("View %s/%s: %w", ty, slot, err)
}
b.WriteString(`</` + tag + `>`)
continue
}
switch ty {
case "markdown", "正文":
b.WriteString(`<div class="` + class + `">` + render.MarkdownToHTML(val) + `</div>`)
case "title", "标题":
b.WriteString(`<h1 class="` + class + `">` + inline(val) + `</h1>`)
case "link", "链接":
href := attrs
if href == "" {
href = "#"
if attrs == "" {
attrs = "#"
}
b.WriteString(`<a class="` + class + `" href="` + html.EscapeString(href) + `">` + inline(val) + `</a>`)
b.WriteString(`<a class="` + class + `" href="` + html.EscapeString(attrs) + `">` + inline(val) + `</a>`)
case "html", "原文":
b.WriteString(`<div class="` + class + `">` + val + `</div>`)
default: // text
default:
value := row["value"]
if value == nil {
value = row["值"]
}
switch value.(type) {
case []any, map[string]any:
return fmt.Errorf("View row %d: unknown structural type %q", i+1, ty)
}
b.WriteString(`<p class="` + class + `">` + inline(val) + `</p>`)
}
}
b.WriteString(`</div>`)
return b.String(), nil
return nil
}
// RenderFile explicitly opts a Document into startup-time component assembly.
// Documents without view: main retain their existing Markdown/data-source path.
func RenderFile(f ArtifactFile, run func(string, map[string]any) (any, error)) (string, bool, error) {
view := metaString(f.Meta, "view", "视图")
if view == "" {
return MarkdownHTML(f.Body), false, nil
}
if view != "main" {
return "", false, fmt.Errorf("%s: view/视图 must be main", f.Rel)
}
if metaString(f.Meta, "data_source", "数据源") != "" {
return "", false, fmt.Errorf("%s: view main is startup assembly; use an ordinary Document for automatic data_source binding", f.Rel)
}
nodes, err := run(f.Path, nil)
if err != nil {
return "", false, fmt.Errorf("%s: view main: %w", f.Rel, err)
}
if nodes == nil {
return "", false, fmt.Errorf("%s: view main must return View rows", f.Rel)
}
html, err := RenderNodes(nodes)
if err != nil {
return "", false, fmt.Errorf("%s: %w", f.Rel, err)
}
return html, true, nil
}
func inline(s string) string {
@@ -159,7 +285,7 @@ func RenderHTMLPage(title, innerHTML string) string {
if t == "" {
t = "Marqdo"
}
return "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><title>" + t +
return "<!DOCTYPE html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>" + t +
"</title></head><body class=\"mq-document\"><main>" + innerHTML + "</main></body></html>"
}
@@ -313,6 +439,7 @@ func InspectBag(app map[string]any, declared []ArtifactFile) map[string]any {
}
}
return map[string]any{
"_type": "web_inspection",
"declared": dec,
"system": SystemRoutes(),
}
+90 -1
View File
@@ -1,6 +1,9 @@
package artifact
import "testing"
import (
"strings"
"testing"
)
func TestMetaType(t *testing.T) {
if MetaType(map[string]string{"type": "web"}) != "web" {
@@ -53,3 +56,89 @@ func contains(s, sub string) bool {
return false
})())
}
func TestNestedLayoutKeepsMarkdownLeavesAndSiblingOrder(t *testing.T) {
leaf := func(slot, text string) any { return map[string]any{"type": "markdown", "slot": slot, "value": text} }
nodes := []any{map[string]any{"type": "footer", "value": []any{
map[string]any{"type": "row", "slot": "footer", "value": []any{
leaf("brand", "### Marqdo\n\nReadable **documents**."),
map[string]any{"类型": "横排", "槽": "links", "值": []any{
leaf("docs", "### Docs\n\n[Guide](/guide)"),
leaf("community", "### Community\n\n[About](/about)"),
}},
}},
}}}
got, err := RenderNodes(nodes)
if err != nil {
t.Fatal(err)
}
for _, want := range []string{"<footer", "mq-row", "slot-links", "<strong>documents</strong>", `href="/guide"`, `href="/about"`} {
if !strings.Contains(got, want) {
t.Fatalf("missing %q: %s", want, got)
}
}
if strings.Index(got, "slot-brand") > strings.Index(got, "slot-docs") || strings.Index(got, "slot-docs") > strings.Index(got, "slot-community") {
t.Fatal("component order changed")
}
if strings.Contains(got, "map[") {
t.Fatal("nested data was stringified")
}
}
func TestNestedColumnTableRetainsTypedValue(t *testing.T) {
nodes := map[string]any{"@": []any{1}, "type": []any{"column"}, "value": []any{[]any{map[string]any{"type": "markdown", "value": "# Leaf"}}}}
got, err := RenderNodes(nodes)
if err != nil || !strings.Contains(got, "<h1") || !strings.Contains(got, "Leaf") {
t.Fatalf("%v: %s", err, got)
}
}
func TestInvalidChildrenAreDiagnosed(t *testing.T) {
for _, value := range []any{"<div>not child rows</div>", []any{"bad row"}} {
if _, err := RenderNodes([]any{map[string]any{"type": "row", "value": value}}); err == nil {
t.Fatalf("accepted %v", value)
}
}
var deep any = []any{map[string]any{"type": "text", "value": "end"}}
for i := 0; i < 66; i++ {
deep = []any{map[string]any{"type": "column", "value": deep}}
}
if _, err := RenderNodes(deep); err == nil {
t.Fatal("unbounded nesting")
}
}
func TestViewDocumentExecutesOnlyAnExplicitMain(t *testing.T) {
calls := 0
run := func(path string, args map[string]any) (any, error) {
calls++
return []any{map[string]any{"type": "markdown", "value": "# Composed"}}, nil
}
f := ArtifactFile{Path: "index.mq.md", Rel: "index.mq.md", Meta: map[string]string{}, Body: "# Ordinary"}
body, structured, err := RenderFile(f, run)
if err != nil || structured || calls != 0 || !strings.Contains(body, "Ordinary") {
t.Fatalf("ordinary: %v %v %d", err, structured, calls)
}
f.Meta["视图"] = "main"
body, structured, err = RenderFile(f, run)
if err != nil || !structured || calls != 1 || !strings.Contains(body, "Composed") {
t.Fatalf("view: %v %v %d", err, structured, calls)
}
f.Meta["视图"] = "typo"
if _, _, err = RenderFile(f, run); err == nil || calls != 1 {
t.Fatal("invalid view must fail before execution")
}
}
func TestViewDocumentRejectsAnEmptyAssemblyAndAutomaticDataSource(t *testing.T) {
f := ArtifactFile{Path: "index.mq.md", Rel: "index.mq.md", Meta: map[string]string{"view": "main"}}
calls := 0
run := func(string, map[string]any) (any, error) { calls++; return nil, nil }
if _, _, err := RenderFile(f, run); err == nil || !strings.Contains(err.Error(), "must return View rows") {
t.Fatalf("empty assembly: %v", err)
}
f.Meta["data_source"] = "posts"
if _, _, err := RenderFile(f, run); err == nil || calls != 1 {
t.Fatalf("data source silently ignored: %v", err)
}
}
@@ -2,6 +2,7 @@ package render
import (
"fmt"
"path/filepath"
"strings"
"testing"
@@ -11,7 +12,20 @@ import (
)
func TestAnlianPostsResolve(t *testing.T) {
url := "sqlite:/home/cflmy/work/marqdo/examples/anlian-mq/data/anlian-mq.db"
url := "sqlite:" + filepath.Join(t.TempDir(), "anlian.db")
fields := []any{
map[string]any{"name": "title", "type": "text", "nullable": false},
map[string]any{"name": "summary", "type": "text"},
map[string]any{"name": "board", "type": "text"},
map[string]any{"name": "slug", "type": "text"},
}
if _, err := db.Init(url, "posts", fields); err != nil {
t.Fatal(err)
}
rows := []any{map[string]any{"title": "欢迎", "summary": "Portable test fixture", "board": "demo", "slug": "welcome"}}
if _, err := db.Insert(url, "posts", rows); err != nil {
t.Fatal(err)
}
card := map[string]any{
"属性": []any{"title", "body", "meta", "href"},
"值": []any{"posts.title", "posts.summary", "posts.board", "posts.slug"},
+6 -1
View File
@@ -1272,7 +1272,6 @@ func resolveFormData(page map[string]any, dbURL string) map[string]any {
return nil
}
func pushIntro(buf *strings.Builder, intro string) {
pushIntroAndForm(buf, intro, nil)
}
@@ -1364,6 +1363,12 @@ func renderFragment(page map[string]any, dbURL, slot string) string {
// RenderPage builds full-page HTML (or a part fragment when partID is set).
func RenderPage(page map[string]any, dbURL string, partID string) string {
// Explicit View Documents already own their structure and document shell.
if partID == "" && page != nil {
if html, ok := page["artifact_html"].(string); ok {
return html
}
}
if page == nil {
page = map[string]any{}
}
+1 -1
View File
@@ -272,7 +272,7 @@ static int register_core(void) {
if (host_register((char *)"web_render_document", (char *)"page,body,db,title", web_render_document) != 0) return 1;
if (host_register((char *)"web_dom_markdown", (char *)"text", web_dom_markdown) != 0) return 1;
if (host_register((char *)"web_serve_root", (char *)"root,host,port,db,static_dir,middleware", web_serve_root) != 0) return 1;
if (host_register((char *)"web_inspect", (char *)"app", web_inspect) != 0) return 1;
if (host_register((char *)"web_inspect", (char *)"app,root", web_inspect) != 0) return 1;
if (host_register((char *)"web_app_use", (char *)"app,middleware", web_app_use) != 0) return 1;
if (host_register((char *)"web_route_use", (char *)"route,middleware", web_route_use) != 0) return 1;
return 0;
+3 -1
View File
@@ -186,8 +186,10 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../ext/web/网页.mq.md)
- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页/索引.mq.md`](../../ext/web/网页/索引.mq.md)(作者门面仍为 `网页.mq.md`)
- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md)
- **Recursive practice:** home → nav/main/footer → footer brand/links → links docs/community; continue until a leaf is plain Markdown. Parents import children and declare one relationship. Use `component.markdown`, `component.wrap`, `layout.stack`, and `layout.columns`; merge alone gives siblings, not columns.
- **Runnable reference:** [web-layout-handbook](../../examples/web-layout-handbook/index.mq.md) and [Chinese reference](../../examples/web-layout-handbook-zh/index.mq.md). A composed Document declares `view: main` and returns node rows at startup; ordinary Documents keep their Markdown/data-source path. Use `inspect root=...` for disk routes, and `run` for a live server.
- EN author facade: `import web:ext/web/web.mq.md`
- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin`
+9 -1
View File
@@ -55,7 +55,7 @@ Import one file; use **that** file’s function names.
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/web/index.mq.md` · `web.mq.md` | `ext/web/网页/索引.mq.md` · `网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/index.mq.md` + modules | `ext/quantum/量子/索引.mq.md` + modules | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
@@ -64,6 +64,14 @@ Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names
Install: `marqdo ext add web` (`网页`). Native: `bash scripts/build-web-plugin.sh`.
Layout practice: split home into nav/main/footer; split footer into brand/links,
then links into docs/community until content leaves are ordinary Markdown.
Use `component.markdown|wrap`, `layout.stack|columns`, and @ record lists.
A parent value holds child rows of the same five-column View schema.
Explicit `view: main` Documents assemble once at startup; `inspect root=...`
scans disk declarations. See the Web root handbook and reference layout site.
| EN import | ZH import | Surface |
|-----------|-----------|---------|
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | facade: `page` · `route` · `serve` · `render` · `inspect` · `use` |
+46
View File
@@ -84,6 +84,52 @@ fn meta_get<'a>(metadata: &'a [(String, Value)], key: &str) -> Option<&'a Value>
metadata.iter().find(|(k, _)| k == key).map(|(_, v)| v)
}
/// A Web/Endpoint declaration without a runnable local entry has no executable
/// body. Both backends return the same summary instead of inventing bytecode.
pub fn declaration_summary(module: &crate::ast::Module) -> Option<Value> {
if module.functions.iter().any(|f| f.name == "main")
|| module
.functions
.iter()
.filter(|f| f.is_object() && f.params.is_empty())
.count()
== 1
{
return None;
}
let kind = classify(&module.metadata)?;
let kind_name = match kind {
ArtifactKind::Web => "web",
ArtifactKind::Endpoint => "endpoint",
_ => return None,
};
let mut fields = vec![
("kind".into(), Value::Text(kind_name.into())),
("method".into(), Value::Text(http_method(&module.metadata))),
];
let target = if kind == ArtifactKind::Web {
web_route(&module.metadata)
} else {
endpoint_path(&module.metadata)
};
if let Some(target) = target {
fields.push((
if kind == ArtifactKind::Web {
"route"
} else {
"path"
}
.into(),
Value::Text(target),
));
}
Some(Value::Map(vec![
("ok".into(), Value::Bool(true)),
("value".into(), Value::Map(fields)),
("error".into(), Value::None),
]))
}
#[cfg(test)]
mod tests {
use super::*;
+13 -6
View File
@@ -42,14 +42,21 @@ pub const CATALOG: &[ExtPackage] = &[
"web/index.mq.md",
"web/web.mq.md",
"web/网页.mq.md",
"web/_capability.mq.md",
"web/page.mq.md",
"web/route.mq.md",
"web/component.mq.md",
"web/dom.mq.md",
"web/client.mq.md",
"web/_capability/index.mq.md",
"web/page/index.mq.md",
"web/route/index.mq.md",
"web/component/index.mq.md",
"web/dom/index.mq.md",
"web/client/index.mq.md",
"web/layout/index.mq.md",
"web/布局/索引.mq.md",
"web/网页/索引.mq.md",
"web/网页/页面/索引.mq.md",
"web/网页/路由/索引.mq.md",
"web/网页/组件/索引.mq.md",
"web/网页/文档对象模型/索引.mq.md",
"web/网页/客户端/索引.mq.md",
"web/网页/能力/索引.mq.md",
],
native_crate: Some("marqdo_plugin_web"),
},
+2 -37
View File
@@ -622,11 +622,8 @@ impl Interpreter {
}
// Web Artifact entry (ADR 0007): `type: web|endpoint` may be pure document —
// no `# main`. Return a Result-shaped summary for run/check gold paths.
if let Some(kind) = crate::artifact::classify(&module.metadata) {
use crate::artifact::ArtifactKind;
if matches!(kind, ArtifactKind::Web | ArtifactKind::Endpoint) {
return Ok(Self::artifact_run_summary(module, kind));
}
if let Some(value) = crate::artifact::declaration_summary(module) {
return Ok(value);
}
bail!("no `# main` object to run");
})();
@@ -635,38 +632,6 @@ impl Interpreter {
}
fn artifact_run_summary(module: &Module, kind: crate::artifact::ArtifactKind) -> Value {
use crate::artifact::{endpoint_path, http_method, web_route, ArtifactKind};
let kind_s = match kind {
ArtifactKind::Web => "web",
ArtifactKind::Endpoint => "endpoint",
ArtifactKind::Prompt => "prompt",
ArtifactKind::Other => "other",
};
let mut value = vec![
("kind".into(), Value::Text(kind_s.into())),
("method".into(), Value::Text(http_method(&module.metadata))),
];
match kind {
ArtifactKind::Web => {
if let Some(r) = web_route(&module.metadata) {
value.push(("route".into(), Value::Text(r)));
}
}
ArtifactKind::Endpoint => {
if let Some(r) = endpoint_path(&module.metadata) {
value.push(("path".into(), Value::Text(r)));
}
}
_ => {}
}
Value::Map(vec![
("ok".into(), Value::Bool(true)),
("value".into(), Value::Map(value)),
("error".into(), Value::None),
])
}
/// Pin `module` as site and call `lib.member` (isolated worker / CLI `--call-lib-path`).
pub fn run_site_lib_path(
&mut self,
+27
View File
@@ -235,6 +235,13 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
println!("=== marqdo: end sema ===");
}
if opts.call_lib_path.is_none() {
if let Some(value) = crate::artifact::declaration_summary(&module) {
emit_result_file(opts, &value)?;
return Ok(0);
}
}
match opts.backend {
Backend::Tree => {
let mut host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
@@ -400,6 +407,16 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
let stdin_lines = crate::input_feed::effective_stdin(&source, &opts.stdin_lines);
let bind_ctx = BindingContext::from_binds(&opts.binds, cwd_for_path(Some(path)));
let module = load_module_with_ctx(path, &bind_ctx)?;
if let Some(value) = crate::artifact::declaration_summary(&module) {
return Ok(RunCapture {
stdout: String::new(),
value,
plots: Vec::new(),
bindings: Default::default(),
view_trace: Default::default(),
});
}
match opts.backend {
Backend::Tree => {
let mut host = HostContext::for_capture(Some(path), opts.host_caps());
@@ -464,6 +481,16 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
}
let stdin_lines = crate::input_feed::effective_stdin(source, &opts.stdin_lines);
let module = load_module_from_source(source)?;
if let Some(value) = crate::artifact::declaration_summary(&module) {
return Ok(RunCapture {
stdout: String::new(),
value,
plots: Vec::new(),
bindings: Default::default(),
view_trace: Default::default(),
});
}
match opts.backend {
Backend::Tree => {
let mut host = HostContext::for_capture(None, opts.host_caps());
+1
View File
@@ -8,6 +8,7 @@
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
| [`markup-v03/`](markup-v03/) | **Markup v0.3 草案金样例**(`#[ignore]` 至旗标落地;见目录 README) |
| [`errors/`](errors/) | 期望失败(诊断文案) |
| [`web_handbook.rs`](web_handbook.rs) | 直接执行双语 Web 手册,验证递归布局参考工程的离线/在线一致性;先构建 Web 插件 |
| [`quantum_handbook.rs`](quantum_handbook.rs) | 直接执行 Quantum 双语手册围栏,校验科学期望、真实契约及双后端;先构建量子插件 |
| [`gold.rs`](gold.rs) | 集成测试:跑上述夹具并比对 stdout / stderr |
+89 -1
View File
@@ -257,15 +257,103 @@ fn web_layout_rules_via_call() {
);
}
#[test]
fn web_index_site_playbook_via_call() {
let file = root().join("ext/web/index.mq.md");
let out = run(&["call", "--json", file.to_str().unwrap(), "site_playbook"]);
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stdout));
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
assert_eq!(body["ok"], true, "{body}");
let keys = body["result"]["key"].as_array().expect("key list");
assert!(
keys.iter().any(|k| k.as_str() == Some("step_F")),
"{body}"
);
}
#[test]
fn web_zh_layout_rules_via_call() {
let file = root().join("ext/web/网页.mq.md");
let file = root().join("ext/web/网页/索引.mq.md");
let out = run(&["call", "--json", file.to_str().unwrap(), "布局规则"]);
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stdout));
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
assert_eq!(body["ok"], true, "{body}");
}
#[test]
fn web_component_merge_via_call() {
let file = root().join("ext/web/component/index.mq.md");
let a = r#"[{"type":"text","slot":"main","value":"A","attrs":"","style":""}]"#;
let b = r#"[{"type":"text","slot":"main","value":"B","attrs":"","style":""}]"#;
let out = run(&[
"call",
"--json",
file.to_str().unwrap(),
"merge",
&format!("a={a}"),
&format!("b={b}"),
]);
assert_eq!(out.status.code(), Some(0), "{}", text(&out.stdout));
let body: serde_json::Value = serde_json::from_str(&text(&out.stdout)).unwrap();
assert_eq!(body["ok"], true, "{body}");
}
#[test]
fn web_page_new_render_session_via_call() {
let dir = std::env::temp_dir().join(format!("mq-call-web-{}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let page = root().join("ext/web/page/index.mq.md");
let sess = "web-page";
let out_new = Command::new(bin())
.env("MARQDO_CALL_SESSION_DIR", &dir)
.args([
"call",
"--effects",
"plugin",
"--session",
sess,
"--toget",
"pg",
"--json",
page.to_str().unwrap(),
"new",
"title=\"Demo\"",
"body=\"# Hi\"",
])
.current_dir(root())
.output()
.unwrap();
assert_eq!(out_new.status.code(), Some(0), "{}", text(&out_new.stdout));
let body_new: serde_json::Value = serde_json::from_str(&text(&out_new.stdout)).unwrap();
assert_eq!(body_new["ok"], true, "{body_new}");
let out_render = Command::new(bin())
.env("MARQDO_CALL_SESSION_DIR", &dir)
.args([
"call",
"--effects",
"plugin",
"--session",
sess,
"--json",
page.to_str().unwrap(),
"render",
"page=$pg",
])
.current_dir(root())
.output()
.unwrap();
assert_eq!(
out_render.status.code(),
Some(0),
"{}",
text(&out_render.stdout)
);
let body_render: serde_json::Value =
serde_json::from_str(&text(&out_render.stdout)).unwrap();
assert_eq!(body_render["ok"], true, "{body_render}");
}
#[test]
fn quantum_index_bell_via_call() {
let file = root().join("ext/quantum/index.mq.md");
+34
View File
@@ -0,0 +1,34 @@
// Exercise the actual recursive reference output; no external resources required.
const assert = require('node:assert/strict');
const {pathToFileURL} = require('node:url');
const {chromium} = require(process.env.MARQDO_PLAYWRIGHT_MODULE || 'playwright');
(async () => {
const browser = await chromium.launch({headless:true, executablePath:process.env.MARQDO_CHROMIUM || undefined, args:['--no-sandbox']});
try {
const page = await browser.newPage();
const errors=[]; page.on('pageerror',e=>errors.push(e.message));
const target=process.argv[2];
await page.goto(target.startsWith('/') ? pathToFileURL(target).href : target);
const box=selector=>page.locator(selector).boundingBox();
for (const width of [1440,390]) {
await page.setViewportSize({width,height:1000});
const brand=await box('.slot-footer-brand');
const links=await box('.slot-footer-links');
const docs=await box('.slot-footer-links-docs');
const community=await box('.slot-footer-links-community');
assert(brand&&links&&docs&&community,'all footer leaves are present');
assert.equal(await page.locator('.slot-footer.mq-row > .slot-footer-links.mq-row').count(),1,'nested columns remain children');
if(width===1440) {
assert(links.x>brand.x+brand.width-1 && Math.abs(links.y-brand.y)<2,'brand and links form two columns');
assert(community.x>docs.x+docs.width-1 && Math.abs(community.y-docs.y)<2,'links decomposes into two further columns');
} else {
assert(links.y>=brand.y+brand.height,'footer collapses vertically');
assert(community.y>=docs.y+docs.height,'inner columns also collapse');
}
assert(await page.evaluate(()=>document.documentElement.scrollWidth<=innerWidth+1),'no horizontal overflow');
console.log(`layout ${width}px: outer and nested geometry passed`);
}
assert.deepEqual(errors,[]);
if(process.argv[3]) await page.screenshot({path:process.argv[3],fullPage:true});
} finally {await browser.close();}
})().catch(error=>{console.error(error);process.exit(1);});
+353
View File
@@ -0,0 +1,353 @@
//! Execute the handbook itself, then serve the actual decomposition projects.
use serde_json::Value;
use std::{
fs,
io::{Read, Write},
net::{TcpListener, TcpStream},
path::{Path, PathBuf},
process::{Child, Command, Stdio},
thread,
time::{Duration, Instant},
};
fn root() -> PathBuf {
PathBuf::from(env!("CARGO_MANIFEST_DIR"))
}
fn bin() -> &'static str {
env!("CARGO_BIN_EXE_marqdo")
}
struct Scratch(PathBuf);
impl Scratch {
fn new(label: &str) -> Self {
let p =
std::env::temp_dir().join(format!("mq-web-handbook-{label}-{}", std::process::id()));
fs::create_dir_all(&p).unwrap();
Self(p)
}
}
impl Drop for Scratch {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
fn command(session: &Path) -> Command {
let mut c = Command::new(bin());
c.current_dir(root())
.env("MARQDO_EXT", root().join("ext"))
.env("MARQDO_LIB", root().join("lib"))
.env(
"MARQDO_WEB_PLUGIN",
root()
.join("plugins/web/build")
.join(if cfg!(target_os = "macos") {
"libweb.dylib"
} else if cfg!(windows) {
"web.dll"
} else {
"libweb.so"
}),
)
.env("MARQDO_CALL_SESSION_DIR", session);
c
}
fn files(dir: &Path, out: &mut Vec<PathBuf>) {
for e in fs::read_dir(dir).unwrap() {
let p = e.unwrap().path();
if p.is_dir() {
files(&p, out)
} else if p.to_string_lossy().ends_with(".mq.md") {
out.push(p)
}
}
}
fn fences(src: &str, lang: &str) -> Vec<String> {
let mut out = Vec::new();
let mut current = None;
for l in src.lines() {
if l == format!("```{lang}") {
current = Some(String::new())
} else if l == "```" {
if let Some(b) = current.take() {
out.push(b)
}
} else if let Some(b) = current.as_mut() {
b.push_str(l);
b.push('\n')
}
}
assert!(current.is_none());
out
}
fn html_structure(html: &str) {
for marker in [
"mq-row",
"slot-footer",
"slot-footer-brand",
"slot-footer-links",
"slot-footer-links-docs",
"slot-footer-links-community",
] {
assert!(html.contains(marker), "missing {marker}: {html}")
}
assert!(!html.contains("map["), "nested nodes were stringified");
assert!(html.contains("<footer") && html.contains("<strong>"));
assert!(html.contains("viewport"));
}
#[test]
fn source_handbook_examples_and_contracts_on_both_backends() {
let scratch = Scratch::new("examples");
let mut paths = Vec::new();
files(&root().join("ext/web"), &mut paths);
paths.sort();
let mut calls = 0;
fn contracts(fs: &[marqdo::ast::Function], path: &Path) {
for f in fs {
let c = f
.contract
.as_ref()
.unwrap_or_else(|| panic!("{}: {} missing contract", path.display(), f.name));
assert!(c.returns.is_some());
assert_eq!(
c.params.len(),
f.params.len(),
"{}: {}",
path.display(),
f.name
);
contracts(&f.children, path)
}
}
for (i, p) in paths.iter().enumerate() {
let source = fs::read_to_string(p).unwrap();
let m = marqdo::load::load_module(p).unwrap();
contracts(&m.functions, p);
assert!(
marqdo::check::check_path(p).unwrap().is_empty(),
"{}",
p.display()
);
assert!(
marqdo::narrative_ratio::check_file(p).unwrap().is_empty(),
"{}",
p.display()
);
let blocks = fences(&source, "sh");
assert!(
!blocks.is_empty(),
"{} needs a runnable recipe",
p.display()
);
for backend in ["tree", "bytecode"] {
let session = scratch.0.join(format!("{i}-{backend}"));
fs::create_dir_all(&session).unwrap();
for block in &blocks {
for line in block.lines().filter(|l| !l.trim().is_empty()) {
assert!(line.starts_with("marqdo call "));
let invocation = line.replacen(
"marqdo call ",
&format!("\"{}\" call --backend {backend} ", bin()),
1,
);
let env = command(&session);
let out = Command::new("bash")
.args(["--noprofile", "--norc", "-ec", &invocation])
.current_dir(root())
.envs(env.get_envs().map(|(k, v)| (k, v.unwrap())))
.env_remove("BASH_ENV")
.output()
.unwrap();
assert!(
out.status.success(),
"{} [{backend}] {line}: {}\n{}",
p.display(),
String::from_utf8_lossy(&out.stdout),
String::from_utf8_lossy(&out.stderr)
);
let body: Value = serde_json::from_slice(&out.stdout).unwrap();
assert_eq!(body["ok"], true, "{body}");
if line.contains(" inspect ") || line.contains(" 检视 ") {
let mut routes: Vec<_> = body["result"]["declared"]
.as_array()
.unwrap()
.iter()
.map(|v| v["path"].as_str().unwrap())
.collect();
routes.sort();
assert_eq!(routes, vec!["/", "/about", "/api/ping"]);
}
if line.contains("preview_nodes") || line.contains("预览节点") {
let h = body["result"].as_str().unwrap();
assert!(h.contains("mq-row") && h.contains("<h2"));
}
calls += 1;
}
}
for (j, block) in fences(&source, "marqdo").iter().enumerate() {
let file = scratch.0.join(format!("author-{i}-{j}.mq.md"));
fs::write(&file, block).unwrap();
let out = command(&session)
.args(["run", file.to_str().unwrap(), "--backend", backend])
.output()
.unwrap();
assert!(
out.status.success(),
"{}: {}",
p.display(),
String::from_utf8_lossy(&out.stderr)
);
let html = String::from_utf8(out.stdout).unwrap();
assert!(
html.contains("slot-footer")
&& html.contains("slot-brand")
&& html.contains("mq-row")
);
}
}
}
eprintln!("Executed {calls} commands directly from bilingual Web handbooks");
}
struct Server(Child);
impl Drop for Server {
fn drop(&mut self) {
let _ = self.0.kill();
let _ = self.0.wait();
}
}
fn get(port: u16, path: &str) -> std::io::Result<String> {
let mut stream = TcpStream::connect_timeout(
&format!("127.0.0.1:{port}").parse().unwrap(),
Duration::from_millis(300),
)?;
stream.set_read_timeout(Some(Duration::from_secs(2)))?;
write!(
stream,
"GET {path} HTTP/1.0\r\nHost: localhost\r\nConnection: close\r\n\r\n"
)?;
let mut body = String::new();
stream.read_to_string(&mut body)?;
Ok(body)
}
#[test]
fn decomposition_projects_preview_and_serve_the_same_structure() {
let scratch = Scratch::new("sites");
for zh in [false, true] {
for backend in ["tree", "bytecode"] {
let site = root().join(if zh {
"examples/web-layout-handbook-zh"
} else {
"examples/web-layout-handbook"
});
let mut source_files = Vec::new();
files(&site, &mut source_files);
for p in &source_files {
let text = fs::read_to_string(p).unwrap();
for forbidden in ["<div", "<style", "dom.raw", "json.set", "compose_"] {
assert!(
!text.contains(forbidden),
"{} uses {forbidden}",
p.display()
);
}
}
for leaf in [
"nav",
"main",
"footer/brand",
"footer/links/docs",
"footer/links/community",
] {
let content = site.join("components").join(leaf).join("content.md");
assert!(content.is_file());
let markdown = fs::read_to_string(content).unwrap();
assert!(
!regex::Regex::new(r"</?[A-Za-z][^>]*>")
.unwrap()
.is_match(&markdown),
"a terminal leaf contains HTML"
);
}
let out = command(&scratch.0)
.args([
"run",
site.join("preview.mq.md").to_str().unwrap(),
"--backend",
backend,
])
.output()
.unwrap();
assert!(
out.status.success(),
"{}",
String::from_utf8_lossy(&out.stderr)
);
let preview = String::from_utf8(out.stdout).unwrap();
html_structure(&preview);
let port = TcpListener::bind("127.0.0.1:0")
.unwrap()
.local_addr()
.unwrap()
.port();
let logpath = scratch.0.join(format!("server-{zh}-{backend}.log"));
let log = fs::File::create(&logpath).unwrap();
let mut server = Server(
command(&scratch.0)
.current_dir(&site)
.args([
"run",
"serve.mq.md",
"--backend",
backend,
"--bind",
&format!("{}={port}", if zh { "端口" } else { "port" }),
])
.stdout(Stdio::from(log.try_clone().unwrap()))
.stderr(Stdio::from(log))
.spawn()
.unwrap(),
);
let deadline = Instant::now() + Duration::from_secs(8);
let response = loop {
if let Ok(h) = get(port, "/") {
break h;
}
assert!(
server.0.try_wait().unwrap().is_none() && Instant::now() < deadline,
"server failed: {}",
fs::read_to_string(&logpath).unwrap()
);
thread::sleep(Duration::from_millis(40));
};
assert!(response.starts_with("HTTP/1.0 200") || response.starts_with("HTTP/1.1 200"));
let body = response.split_once("\r\n\r\n").unwrap().1;
html_structure(body);
assert_eq!(body.trim(), preview.trim(), "preview and live layout drift");
let about = get(port, "/about").unwrap();
assert!(about.contains("200 OK") && about.contains(if zh { "关于" } else { "About" }));
let ping = get(port, "/api/ping").unwrap();
assert!(ping.contains("200 OK"));
let value: Value =
serde_json::from_str(ping.split_once("\r\n\r\n").unwrap().1).unwrap();
assert!(value.to_string().contains("pong"));
}
}
}
#[test]
fn metadata_only_endpoint_has_the_same_result_on_both_backends() {
let source = "---\nmarkup: occlusion\ntype: endpoint\npath: /api/declaration\nmethod: POST\n---\n\nHandler declaration only.\n";
let mut results = Vec::new();
for backend in [marqdo::Backend::Tree, marqdo::Backend::Bytecode] {
let options = marqdo::RunOptions {
backend,
..Default::default()
};
let output = marqdo::run_source(source, &options).unwrap();
let json = marqdo::browser_session::value_as_json(&output.value).unwrap();
assert_eq!(json["ok"], true);
assert_eq!(json["value"]["kind"], "endpoint");
assert_eq!(json["value"]["path"], "/api/declaration");
assert_eq!(json["value"]["method"], "POST");
results.push(json);
assert!(marqdo::run_source("## helper\n\n*1*\n", &options).is_err());
}
assert_eq!(results[0], results[1]);
}