diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 44fe326..8b0f024 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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` diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index cae83c6..6481ab8 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -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` | diff --git a/doc/design/ext-skill-tools-paradigm.md b/doc/design/ext-skill-tools-paradigm.md index eae482e..e9d6482 100644 --- a/doc/design/ext-skill-tools-paradigm.md +++ b/doc/design/ext-skill-tools-paradigm.md @@ -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 试点归纳的整包开发范式与验收清单 | diff --git a/doc/design/ext-web-artifact.md b/doc/design/ext-web-artifact.md index f5a039a..01cb5f7 100644 --- a/doc/design/ext-web-artifact.md +++ b/doc/design/ext-web-artifact.md @@ -81,6 +81,7 @@ Welcome to the executable web. | `type` | `类型` | `web` / `网页` | | `route` | `路由` | 路径,可含 `{param}` | | `method` | `方法` | 默认 `GET` | +| `view` | `视图` | 可选 main:启动时执行主程序,返回递归 View 节点;不与自动 data_source 绑定混用 | | `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。 --- diff --git a/doc/design/ext-web-handbook.md b/doc/design/ext-web-handbook.md new file mode 100644 index 0000000..da7ec6c --- /dev/null +++ b/doc/design/ext-web-handbook.md @@ -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 手册回归通过。本轮没有把这些既有策略/回放失败混入布局修复。 diff --git a/doc/design/ext-web-layout-paradigm.md b/doc/design/ext-web-layout-paradigm.md index 953e9eb..27122ab 100644 --- a/doc/design/ext-web-layout-paradigm.md +++ b/doc/design/ext-web-layout-paradigm.md @@ -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)。 diff --git a/examples/web-layout-handbook-zh/README.md b/examples/web-layout-handbook-zh/README.md new file mode 100644 index 0000000..50d2254 --- /dev/null +++ b/examples/web-layout-handbook-zh/README.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. diff --git a/examples/web-layout-handbook-zh/api/ping.mq.md b/examples/web-layout-handbook-zh/api/ping.mq.md new file mode 100644 index 0000000..684ef31 --- /dev/null +++ b/examples/web-layout-handbook-zh/api/ping.mq.md @@ -0,0 +1,18 @@ +--- +markup: occlusion +类型: 端点 +路径: /api/ping +方法: GET +请求: none +响应: json +--- + +# main + +`result` = + +| ok | ping | +|----|------| +| True | pong | + +*result* diff --git a/examples/web-layout-handbook-zh/components/footer/brand/content.md b/examples/web-layout-handbook-zh/components/footer/brand/content.md new file mode 100644 index 0000000..00a8c58 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/brand/content.md @@ -0,0 +1,3 @@ +### Marqdo + +代码即文档,文档即可执行。 diff --git a/examples/web-layout-handbook-zh/components/footer/brand/index.mq.md b/examples/web-layout-handbook-zh/components/footer/brand/index.mq.md new file mode 100644 index 0000000..1222668 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/brand/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/footer/index.mq.md b/examples/web-layout-handbook-zh/components/footer/index.mq.md new file mode 100644 index 0000000..0a69fd8 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/footer/links/community/content.md b/examples/web-layout-handbook-zh/components/footer/links/community/content.md new file mode 100644 index 0000000..c27d443 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/links/community/content.md @@ -0,0 +1,5 @@ +### 社区 + +[关于项目](/about) + +[返回首页](/) diff --git a/examples/web-layout-handbook-zh/components/footer/links/community/index.mq.md b/examples/web-layout-handbook-zh/components/footer/links/community/index.mq.md new file mode 100644 index 0000000..0b6d8b0 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/links/community/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/footer/links/docs/content.md b/examples/web-layout-handbook-zh/components/footer/links/docs/content.md new file mode 100644 index 0000000..7dc424a --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/links/docs/content.md @@ -0,0 +1,5 @@ +### 文档 + +[开发手册](/about) + +[服务状态](/api/ping) diff --git a/examples/web-layout-handbook-zh/components/footer/links/docs/index.mq.md b/examples/web-layout-handbook-zh/components/footer/links/docs/index.mq.md new file mode 100644 index 0000000..7f17e65 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/links/docs/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/footer/links/index.mq.md b/examples/web-layout-handbook-zh/components/footer/links/index.mq.md new file mode 100644 index 0000000..14b2672 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/footer/links/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/index.mq.md b/examples/web-layout-handbook-zh/components/index.mq.md new file mode 100644 index 0000000..2cf4f29 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/main/content.md b/examples/web-layout-handbook-zh/components/main/content.md new file mode 100644 index 0000000..1f3fc5a --- /dev/null +++ b/examples/web-layout-handbook-zh/components/main/content.md @@ -0,0 +1,3 @@ +# 可执行文档站点 + +先拆布局,再写内容。**叶子只负责 Markdown。** diff --git a/examples/web-layout-handbook-zh/components/main/index.mq.md b/examples/web-layout-handbook-zh/components/main/index.mq.md new file mode 100644 index 0000000..59de24e --- /dev/null +++ b/examples/web-layout-handbook-zh/components/main/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/components/nav/content.md b/examples/web-layout-handbook-zh/components/nav/content.md new file mode 100644 index 0000000..0f54236 --- /dev/null +++ b/examples/web-layout-handbook-zh/components/nav/content.md @@ -0,0 +1 @@ +[首页](/) · [关于](/about) · [状态](/api/ping) diff --git a/examples/web-layout-handbook-zh/components/nav/index.mq.md b/examples/web-layout-handbook-zh/components/nav/index.mq.md new file mode 100644 index 0000000..cca0dee --- /dev/null +++ b/examples/web-layout-handbook-zh/components/nav/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook-zh/index.mq.md b/examples/web-layout-handbook-zh/index.mq.md new file mode 100644 index 0000000..d540fb5 --- /dev/null +++ b/examples/web-layout-handbook-zh/index.mq.md @@ -0,0 +1,16 @@ +--- +markup: occlusion +类型: 网页 +视图: main +标题: Marqdo 布局实践 +路由: / +import: + home: ./components/index.mq.md +--- + +# main + +页面只选择布局根,具体拆分沿 components/index.mq.md 继续。 +此主程序返回结构而不是 HTML;view 元数据让服务在启动时执行它。 + +*> home.节点* diff --git a/examples/web-layout-handbook-zh/pages/about.mq.md b/examples/web-layout-handbook-zh/pages/about.mq.md new file mode 100644 index 0000000..9d49066 --- /dev/null +++ b/examples/web-layout-handbook-zh/pages/about.mq.md @@ -0,0 +1,10 @@ +--- +markup: occlusion +类型: 网页 +标题: 关于 +路由: /about +--- + +# 关于 + +这是普通 Markdown Document,不执行布局函数。 diff --git a/examples/web-layout-handbook-zh/preview.mq.md b/examples/web-layout-handbook-zh/preview.mq.md new file mode 100644 index 0000000..9f3088e --- /dev/null +++ b/examples/web-layout-handbook-zh/preview.mq.md @@ -0,0 +1,12 @@ +--- +markup: occlusion +import: + home: ./components/index.mq.md + 网页: ext/web/网页.mq.md +--- + +# main + +**nodes = > home.节点** +**html = 网页.渲染 节点=`nodes` 标题="Marqdo 布局实践"** +> 打印 内容=`html` diff --git a/examples/web-layout-handbook-zh/serve.mq.md b/examples/web-layout-handbook-zh/serve.mq.md new file mode 100644 index 0000000..fc0d8b0 --- /dev/null +++ b/examples/web-layout-handbook-zh/serve.mq.md @@ -0,0 +1,12 @@ +--- +markup: occlusion +import: + 网页: ext/web/网页.mq.md +--- + +# main + +端口 `端口`=18081 可通过 --bind 覆盖。启动器不包含页面布局。 + +**监听端口 = 整数 值=`端口`** +> 网页.服务 根="." 主机="127.0.0.1" 端口=`监听端口` diff --git a/examples/web-layout-handbook/README.md b/examples/web-layout-handbook/README.md new file mode 100644 index 0000000..f904aac --- /dev/null +++ b/examples/web-layout-handbook/README.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/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. diff --git a/examples/web-layout-handbook/api/ping.mq.md b/examples/web-layout-handbook/api/ping.mq.md new file mode 100644 index 0000000..fa83812 --- /dev/null +++ b/examples/web-layout-handbook/api/ping.mq.md @@ -0,0 +1,18 @@ +--- +markup: occlusion +type: endpoint +path: /api/ping +method: GET +request: none +response: json +--- + +# main + +`result` = + +| ok | ping | +|----|------| +| True | pong | + +*result* diff --git a/examples/web-layout-handbook/components/footer/brand/content.md b/examples/web-layout-handbook/components/footer/brand/content.md new file mode 100644 index 0000000..43904ad --- /dev/null +++ b/examples/web-layout-handbook/components/footer/brand/content.md @@ -0,0 +1,3 @@ +### Marqdo + +Code is documentation. Documents are executable. diff --git a/examples/web-layout-handbook/components/footer/brand/index.mq.md b/examples/web-layout-handbook/components/footer/brand/index.mq.md new file mode 100644 index 0000000..4380b29 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/brand/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/footer/index.mq.md b/examples/web-layout-handbook/components/footer/index.mq.md new file mode 100644 index 0000000..85dbe69 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/footer/links/community/content.md b/examples/web-layout-handbook/components/footer/links/community/content.md new file mode 100644 index 0000000..fef6043 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/links/community/content.md @@ -0,0 +1,5 @@ +### Community + +[About the project](/about) + +[Return home](/) diff --git a/examples/web-layout-handbook/components/footer/links/community/index.mq.md b/examples/web-layout-handbook/components/footer/links/community/index.mq.md new file mode 100644 index 0000000..155fdf9 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/links/community/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/footer/links/docs/content.md b/examples/web-layout-handbook/components/footer/links/docs/content.md new file mode 100644 index 0000000..d96f030 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/links/docs/content.md @@ -0,0 +1,5 @@ +### Documentation + +[Handbook](/about) + +[Service status](/api/ping) diff --git a/examples/web-layout-handbook/components/footer/links/docs/index.mq.md b/examples/web-layout-handbook/components/footer/links/docs/index.mq.md new file mode 100644 index 0000000..8c341a2 --- /dev/null +++ b/examples/web-layout-handbook/components/footer/links/docs/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/footer/links/index.mq.md b/examples/web-layout-handbook/components/footer/links/index.mq.md new file mode 100644 index 0000000..60da42c --- /dev/null +++ b/examples/web-layout-handbook/components/footer/links/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/index.mq.md b/examples/web-layout-handbook/components/index.mq.md new file mode 100644 index 0000000..63f00d1 --- /dev/null +++ b/examples/web-layout-handbook/components/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/main/content.md b/examples/web-layout-handbook/components/main/content.md new file mode 100644 index 0000000..a8c6fa6 --- /dev/null +++ b/examples/web-layout-handbook/components/main/content.md @@ -0,0 +1,3 @@ +# Executable documents + +Split the layout before writing content. **Leaves own Markdown only.** diff --git a/examples/web-layout-handbook/components/main/index.mq.md b/examples/web-layout-handbook/components/main/index.mq.md new file mode 100644 index 0000000..708942e --- /dev/null +++ b/examples/web-layout-handbook/components/main/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/components/nav/content.md b/examples/web-layout-handbook/components/nav/content.md new file mode 100644 index 0000000..b247075 --- /dev/null +++ b/examples/web-layout-handbook/components/nav/content.md @@ -0,0 +1 @@ +[Home](/) · [About](/about) · [Status](/api/ping) diff --git a/examples/web-layout-handbook/components/nav/index.mq.md b/examples/web-layout-handbook/components/nav/index.mq.md new file mode 100644 index 0000000..16e4c57 --- /dev/null +++ b/examples/web-layout-handbook/components/nav/index.mq.md @@ -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"* diff --git a/examples/web-layout-handbook/index.mq.md b/examples/web-layout-handbook/index.mq.md new file mode 100644 index 0000000..d7681f7 --- /dev/null +++ b/examples/web-layout-handbook/index.mq.md @@ -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* diff --git a/examples/web-layout-handbook/pages/about.mq.md b/examples/web-layout-handbook/pages/about.mq.md new file mode 100644 index 0000000..630d261 --- /dev/null +++ b/examples/web-layout-handbook/pages/about.mq.md @@ -0,0 +1,10 @@ +--- +markup: occlusion +type: web +title: About +route: /about +--- + +# About + +An ordinary Markdown Document keeps its original rendering path. diff --git a/examples/web-layout-handbook/preview.mq.md b/examples/web-layout-handbook/preview.mq.md new file mode 100644 index 0000000..9c2c925 --- /dev/null +++ b/examples/web-layout-handbook/preview.mq.md @@ -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` diff --git a/examples/web-layout-handbook/serve.mq.md b/examples/web-layout-handbook/serve.mq.md new file mode 100644 index 0000000..cbd003a --- /dev/null +++ b/examples/web-layout-handbook/serve.mq.md @@ -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` diff --git a/ext/web/README.md b/ext/web/README.md index 542fbe6..28cd38a 100644 --- a/ext/web/README.md +++ b/ext/web/README.md @@ -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. diff --git a/ext/web/_capability.mq.md b/ext/web/_capability.mq.md deleted file mode 100644 index 617f2cd..0000000 --- a/ext/web/_capability.mq.md +++ /dev/null @@ -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 -**** diff --git a/ext/web/_capability/index.mq.md b/ext/web/_capability/index.mq.md new file mode 100644 index 0000000..2bc6a4d --- /dev/null +++ b/ext/web/_capability/index.mq.md @@ -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 +**** diff --git a/ext/web/client.mq.md b/ext/web/client.mq.md deleted file mode 100644 index c0245b1..0000000 --- a/ext/web/client.mq.md +++ /dev/null @@ -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* diff --git a/ext/web/client/index.mq.md b/ext/web/client/index.mq.md new file mode 100644 index 0000000..85833c5 --- /dev/null +++ b/ext/web/client/index.mq.md @@ -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* diff --git a/ext/web/component.mq.md b/ext/web/component.mq.md deleted file mode 100644 index 8668bfb..0000000 --- a/ext/web/component.mq.md +++ /dev/null @@ -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`* diff --git a/ext/web/component/index.mq.md b/ext/web/component/index.mq.md new file mode 100644 index 0000000..a85a354 --- /dev/null +++ b/ext/web/component/index.mq.md @@ -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* diff --git a/ext/web/dom.mq.md b/ext/web/dom/index.mq.md similarity index 57% rename from ext/web/dom.mq.md rename to ext/web/dom/index.mq.md index b490300..82e30d5 100644 --- a/ext/web/dom.mq.md +++ b/ext/web/dom/index.mq.md @@ -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 | diff --git a/ext/web/index.mq.md b/ext/web/index.mq.md index 038c30b..b43b9ae 100644 --- a/ext/web/index.mq.md +++ b/ext/web/index.mq.md @@ -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`* diff --git a/ext/web/layout/index.mq.md b/ext/web/layout/index.mq.md index fc8cd9c..3ae9d55 100644 --- a/ext/web/layout/index.mq.md +++ b/ext/web/layout/index.mq.md @@ -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* diff --git a/ext/web/page.mq.md b/ext/web/page.mq.md deleted file mode 100644 index 6cb74d8..0000000 --- a/ext/web/page.mq.md +++ /dev/null @@ -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`* diff --git a/ext/web/page/index.mq.md b/ext/web/page/index.mq.md new file mode 100644 index 0000000..e8e275a --- /dev/null +++ b/ext/web/page/index.mq.md @@ -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`* diff --git a/ext/web/route.mq.md b/ext/web/route.mq.md deleted file mode 100644 index 6665ffe..0000000 --- a/ext/web/route.mq.md +++ /dev/null @@ -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* diff --git a/ext/web/route/index.mq.md b/ext/web/route/index.mq.md new file mode 100644 index 0000000..3f105a4 --- /dev/null +++ b/ext/web/route/index.mq.md @@ -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* diff --git a/ext/web/web.mq.md b/ext/web/web.mq.md index 4d82a4b..2dcde36 100644 --- a/ext/web/web.mq.md +++ b/ext/web/web.mq.md @@ -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 | diff --git a/ext/web/布局/索引.mq.md b/ext/web/布局/索引.mq.md index 4533a15..4d1b814 100644 --- a/ext/web/布局/索引.mq.md +++ b/ext/web/布局/索引.mq.md @@ -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=`职责`* diff --git a/ext/web/网页.mq.md b/ext/web/网页.mq.md index 956c025..2ae72b6 100644 --- a/ext/web/网页.mq.md +++ b/ext/web/网页.mq.md @@ -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 | 挂载描述 | diff --git a/ext/web/网页/客户端/索引.mq.md b/ext/web/网页/客户端/索引.mq.md new file mode 100644 index 0000000..a87fd21 --- /dev/null +++ b/ext/web/网页/客户端/索引.mq.md @@ -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=`移除`* diff --git a/ext/web/网页/文档对象模型/索引.mq.md b/ext/web/网页/文档对象模型/索引.mq.md new file mode 100644 index 0000000..d812a3a --- /dev/null +++ b/ext/web/网页/文档对象模型/索引.mq.md @@ -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`* diff --git a/ext/web/网页/索引.mq.md b/ext/web/网页/索引.mq.md new file mode 100644 index 0000000..7434e9a --- /dev/null +++ b/ext/web/网页/索引.mq.md @@ -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 的装配使用同一渲染器,能检查双栏是否确实保留了层级。 + +*> 网页.渲染 节点=`节点` 标题=`标题`* diff --git a/ext/web/网页/组件/索引.mq.md b/ext/web/网页/组件/索引.mq.md new file mode 100644 index 0000000..1d4816f --- /dev/null +++ b/ext/web/网页/组件/索引.mq.md @@ -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=`样式`* diff --git a/ext/web/网页/能力/索引.mq.md b/ext/web/网页/能力/索引.mq.md new file mode 100644 index 0000000..df03211 --- /dev/null +++ b/ext/web/网页/能力/索引.mq.md @@ -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* diff --git a/ext/web/网页/路由/索引.mq.md b/ext/web/网页/路由/索引.mq.md new file mode 100644 index 0000000..4845155 --- /dev/null +++ b/ext/web/网页/路由/索引.mq.md @@ -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=`中间件`* diff --git a/ext/web/网页/页面/索引.mq.md b/ext/web/网页/页面/索引.mq.md new file mode 100644 index 0000000..044ec51 --- /dev/null +++ b/ext/web/网页/页面/索引.mq.md @@ -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=`数据库`* diff --git a/plugins/web/abi_artifact.go b/plugins/web/abi_artifact.go index 59bd252..9967261 100644 --- a/plugins/web/abi_artifact.go +++ b/plugins/web/abi_artifact.go @@ -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 { diff --git a/plugins/web/internal/artifact/artifact.go b/plugins/web/internal/artifact/artifact.go index 1f4f7d5..f26661d 100644 --- a/plugins/web/internal/artifact/artifact.go +++ b/plugins/web/internal/artifact/artifact.go @@ -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 + "
" + innerHTML + "
" } @@ -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(), } diff --git a/plugins/web/internal/artifact/artifact_test.go b/plugins/web/internal/artifact/artifact_test.go index ca1cf99..4a0e8d7 100644 --- a/plugins/web/internal/artifact/artifact_test.go +++ b/plugins/web/internal/artifact/artifact_test.go @@ -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{"documents", `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, "not child rows", []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) + } +} diff --git a/plugins/web/internal/render/anlian_resolve_test.go b/plugins/web/internal/render/anlian_resolve_test.go index 3bed92b..737dba9 100644 --- a/plugins/web/internal/render/anlian_resolve_test.go +++ b/plugins/web/internal/render/anlian_resolve_test.go @@ -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"}, diff --git a/plugins/web/internal/render/render.go b/plugins/web/internal/render/render.go index 84ba174..e6207ef 100644 --- a/plugins/web/internal/render/render.go +++ b/plugins/web/internal/render/render.go @@ -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{} } diff --git a/plugins/web/plugin.go b/plugins/web/plugin.go index 0c5d010..d228467 100644 --- a/plugins/web/plugin.go +++ b/plugins/web/plugin.go @@ -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; diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index 44fe326..a652b7d 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -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` diff --git a/skills/marqdo/reference.md b/skills/marqdo/reference.md index cae83c6..6481ab8 100644 --- a/skills/marqdo/reference.md +++ b/skills/marqdo/reference.md @@ -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` | diff --git a/src/artifact/mod.rs b/src/artifact/mod.rs index eda0957..45cd8a1 100644 --- a/src/artifact/mod.rs +++ b/src/artifact/mod.rs @@ -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 { + 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::*; diff --git a/src/ext_cli.rs b/src/ext_cli.rs index fd393f3..b62577c 100644 --- a/src/ext_cli.rs +++ b/src/ext_cli.rs @@ -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"), }, diff --git a/src/interp.rs b/src/interp.rs index 0e7309e..a60bfe4 100644 --- a/src/interp.rs +++ b/src/interp.rs @@ -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, diff --git a/src/lib.rs b/src/lib.rs index e82f5ae..a90972d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -235,6 +235,13 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result { 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 { 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 { } 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()); diff --git a/tests/README.md b/tests/README.md index e198d86..48de94b 100644 --- a/tests/README.md +++ b/tests/README.md @@ -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 | diff --git a/tests/call_cli.rs b/tests/call_cli.rs index 17baffc..e24092b 100644 --- a/tests/call_cli.rs +++ b/tests/call_cli.rs @@ -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"); diff --git a/tests/web/layout.browser.cjs b/tests/web/layout.browser.cjs new file mode 100644 index 0000000..f2294ac --- /dev/null +++ b/tests/web/layout.browser.cjs @@ -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);}); diff --git a/tests/web_handbook.rs b/tests/web_handbook.rs new file mode 100644 index 0000000..637866f --- /dev/null +++ b/tests/web_handbook.rs @@ -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) { + 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 { + 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("")); + 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(" std::io::Result { + 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 ["]*>") + .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]); +}