Make Web an executable handbook with recursive Markdown layouts
This commit is contained in:
1 parent
cc5277d2b5
commit
5080136d65
84 files changed
+3394
-957
No files matched your search
@@ -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`
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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 试点归纳的整包开发范式与验收清单 |
|
||||
@@ -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。
|
||||
|
||||
---
|
||||
|
||||
@@ -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 手册回归通过。本轮没有把这些既有策略/回放失败混入布局修复。
|
||||
@@ -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)。
|
||||
@@ -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" 端口=`监听端口`
|
||||
@@ -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"*
|
||||
@@ -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`
|
||||
@@ -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
@@ -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.
|
||||
@@ -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
|
||||
****
|
||||
@@ -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
|
||||
****
|
||||
@@ -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*
|
||||
@@ -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*
|
||||
@@ -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`*
|
||||
@@ -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*
|
||||
@@ -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
@@ -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
@@ -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*
|
||||
@@ -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`*
|
||||
@@ -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`*
|
||||
@@ -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*
|
||||
@@ -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
@@ -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
@@ -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
@@ -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 | 挂载描述 |
|
||||
|
||||
@@ -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`*
|
||||
@@ -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 的装配使用同一渲染器,能检查双栏是否确实保留了层级。
|
||||
|
||||
*> 网页.渲染 节点=`节点` 标题=`标题`*
|
||||
@@ -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=`样式`*
|
||||
@@ -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*
|
||||
@@ -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=`中间件`*
|
||||
@@ -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
@@ -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 {
|
||||
|
||||
@@ -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(),
|
||||
}
|
||||
|
||||
@@ -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"},
|
||||
|
||||
@@ -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{}
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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());
|
||||
|
||||
@@ -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
@@ -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");
|
||||
|
||||
@@ -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);});
|
||||
@@ -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]);
|
||||
}
|
||||
Reference in new issue
Block a user