Files
marqdo/ext/web/web.mq.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

441 lines
20 KiB
Markdown
Executable File

---
markup: occlusion
title: ext/web/web
description: >-
Web Artifact facade (ADR 0007) — page · route · serve · render · inspect · use.
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/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
---
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.
```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
```
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. Call it directly with explicit effects,
or compose prepare, resource bindings and listen in an ordinary callable launcher. Explicit view: main Documents assemble once at startup
through normal functions and imports. Restart after changing their content.
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 | text | "" | document title |
| route | text | "/" | path |
| method | text | "GET" | HTTP method |
| body | text | "" | Markdown body |
| nodes | any | None | View table or None |
| data_source | text | "" | table name |
| data_order | text | "" | order key |
| data_where | text | "" | filters |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | page handle |
Use `title`="", `route`="/", `method`="GET", `body`="", `nodes`=None, `data_source`="", `data_order`="", `data_where`="" as the inputs for this operation.
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.
Return *[Page](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 | any | required | app handle |
| path | text | required | URL path |
| method | text | "GET" | HTTP method |
| page | any | None | Document or None |
| fn | text | "" | endpoint member |
| request | text | "json" | request kind |
| response | text | "json" | response kind |
| auth | text | "" | auth tag |
| class | text | "" | route class |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | registration result |
Use `app`, `path`, `method`="GET", `page`=None, `fn`="", `request`="json", `response`="json", `auth`="", `class`="" as the inputs for this operation.
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.
We retain **`r` = [Route](route_mod.route(app=`app`, path=`path`, method=`method`, page=`page`, fn=`fn`, request=`request`, response=`response`, auth=`auth`, class=`class`))**.
Return *[Register](> `r`.register app=`app` )*.
## render
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| doc | any | None | Document or None |
| nodes | any | None | View table or None |
| body | text | "" | Markdown |
| title | text | "" | title supplied by the caller |
| db | any | None | optional db |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | HTML or payload |
Use `doc`=None, `nodes`=None, `body`="", `title`="", `db`=None as the inputs for this operation.
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.
We **[Load the native plugin required by this operation](cap.load())**.
1. `doc`
Return *[Render](> `doc`.render nodes=`nodes` db=`db` )*.
2. `nodes`
Return *[Render a Document or View nodes to HTML for offline preview](web_render_nodes(page=`doc`, nodes=`nodes`, db=`db`, title=`title`))*.
3. *
Return *[Render a Document or View nodes to HTML for offline preview](web_render_document(page=`doc`, body=`body`, db=`db`, title=`title`))*.
## use
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| middleware | any | required | middleware table |
| app | any | required | app handle |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
Use `middleware`, `app` as the inputs for this operation.
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.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Attach first-class middleware to app](web_app_use(app=`app`, middleware=`middleware`))*.
## inspect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| app | any | None | Current prepared application after all explicit Resource bindings |
| root | text | "" | Optional metadata-only scan directory; takes precedence over app |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | scope, declared and system; registered reports actual configured handlers, metadata reports file declarations and runtime templates |
Use `app`=None and `root`="" deliberately. After prepare and Resource bindings, pass the retained app before listen to inspect its current routes. The registrar is shared with the actual HTTP server, so later WebSocket, JSON query, form, login, administration and static bindings appear without using a stale startup snapshot. Duplicate or conflicting registrations retain their native diagnostic.
Supplying root scans Artifact metadata only. It does not execute the launcher or Documents, so it cannot observe Resource bindings performed by those functions. scope=metadata makes that limitation explicit; scope=registered reports the handler registrations of the supplied app. Neither scope proves that a server is listening, a database is available or authentication succeeds.
The operation needs plugin. It does not invoke request handlers, create sessions, reset runtime state, open a database or start a listener. Credentials and unrelated app fields are not returned. System routes include the actual configured parameterized form/part paths and session paths; declared routes retain their source identity when available.
We **[Load the maintained native inspection boundary](cap.load())**.
Return *[Observe the current declarations and registered runtime handlers](web_inspect(app=`app`, root=`root`))*.
## serve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | text | "." | site root |
| host | text | "127.0.0.1" | bind host |
| port | number | 18081 | Explicit server port |
| db | any | None | optional db |
| static_dir | text | "" | static files |
| middleware | any | None | optional middleware |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | serve result |
Use `root`=".", `host`="127.0.0.1", `port`=18081, `db`=None, `static_dir`="", `middleware`=None as the inputs for this operation.
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.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Discover the site and listen on its configured address](web_serve_root(root=`root`, host=`host`, port=`port`, db=`db`, static_dir=`static_dir`, middleware=`middleware`))*.
## client_embed
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| bridge | text | "/static/marqdo-bridge.js" | bridge script URL |
| wasm | text | "/static/marqdo_wasm.wasm" | wasm URL |
| source | text | "" | optional source |
| boot | bool | True | auto boot |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | embed descriptor |
Use `bridge`="/static/marqdo-bridge.js", `wasm`="/static/marqdo_wasm.wasm", `source`="", `boot`=True as the inputs for this operation.
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.
Return *[Embed](client_mod.embed(bridge=`bridge`, wasm=`wasm`, source=`source`, boot=`boot`))*.
## text_patch
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | text | required | CSS selector |
| text | text | required | new text |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
Use `sel`, `text` as the inputs for this operation.
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.
Return *[Text patch](client_mod.text_patch(sel=`sel`, text=`text`))*.
## dom_patch
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | text | required | CSS selector |
| html | text | "" | optional HTML fragment |
| attrs | any | None | optional attrs |
| remove | bool | False | remove node |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | patch descriptor |
Use `sel`, `html`="", `attrs`=None, `remove`=False as the inputs for this operation.
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.
Return *[Dom patch](client_mod.dom_patch(sel=`sel`, html=`html`, attrs=`attrs`, remove=`remove`))*.
## make_style
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | property table |
| name | text | "" | style name |
| strict | bool | False | strict mode |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | CSS / style handle |
Use `table`, `name`="", `strict`=False as the inputs for this operation.
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.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Compile a named style table into CSS](web_style(name=`name`, table=`table`, strict=`strict`))*.
## make_images
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | images table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | images payload |
Use `table` as the inputs for this operation.
Build image descriptors from a readable `table` of sources and alts. Keep media
declarations in Markdown tables beside the Document that uses them.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Build image descriptors from a readable table of sources and alts. Keep media declarations in Markdown tables beside the Document that uses them.](web_images(table=`table`))*.
## make_head
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| table | any | required | head table |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | head payload |
Use `table` as the inputs for this operation.
Build head resource rows (link, script, icon) from a `table`. Prefer declaring
head needs as data rather than injecting opaque HTML head strings.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Build head resource rows (link, script, icon) from a table. Prefer declaring head needs as data rather than injecting opaque HTML head strings.](web_head(table=`table`))*.
## prepare
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | text | "." | Site directory containing declared Documents and Endpoints |
| host | text | "127.0.0.1" | Explicit listen address retained for later listen |
| port | number | 18081 | Port retained for later listen |
| db | any | None | Existing database Resource or None |
| static_dir | text | "" | Optional static directory resolved under the site |
| middleware | any | None | Optional security header table |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Prepared app resource; no socket is opened |
Use `root`=".", `host`="127.0.0.1", `port`=18081, `db`=None, `static_dir`="" and `middleware`=None to discover the same Documents and Endpoints as serve. Startup View assembly runs once here. Bind additional resources to the returned app, retaining each returned app value, before calling listen. The original absolute site root travels with the app so relative endpoint callbacks and static files keep their site context. This is a lifecycle boundary, not an alternative routing language. Reading metadata or evaluating a Document can fail before any listener starts.
We **[Load the existing native web implementation](cap.load())**.
Return *[Discover routes without starting a listener](web_prepare_root(root=`root`, host=`host`, port=`port`, db=`db`, static_dir=`static_dir`, middleware=`middleware`))*.
## listen
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| app | any | required | Prepared app after explicit resource bindings |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Blocking native listener result |
Use `app` after prepare and the resource-owned binding functions. This call opens the configured host and port and blocks for the server lifetime. It works in an ordinary callable launcher reached by marqdo call; grant plugin, filesystem and network effects required by that launcher. Returning a resource description does not start the server. A separate terminal or supervised test process owns shutdown; call does not turn this listener into a background daemon. Relative paths use the site root retained by prepare.
We **[Load the existing native web implementation](cap.load())**.
Return *[Serve the prepared site with its bound resources](web_listen(app=`app`))*.
# app
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| page | any | None | Initial Document/page resource, or None for explicit later route mounts |
| db | any | None | Existing database resource used for document data and native application services |
| host | any | "127.0.0.1" | Listen address; the default binds only the local host |
| port | any | 18081 | TCP listen port selected for the application |
| admin | any | False | Whether to enable the native administration routes |
| admin_prefix | any | "/admin" | URL prefix under which native administration routes are mounted |
| shell_css | any | None | Optional native shell stylesheet configuration; None keeps the runtime default |
| layout | any | None | Optional native shell layout configuration; component geometry remains View data |
| asset_version | any | None | Optional resource version used by the native shell for asset URLs |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | Native app resource for static mounts, route registration, gates and listening |
Use `page`=None, `db`=None, `host`="127.0.0.1", `port`=18081, `admin`=False, `admin_prefix`="/admin", `shell_css`=None, `layout`=None, `asset_version`=None as the inputs for this operation.
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
flags, shell_css, layout, and asset_version configure the runtime without a
configure junk drawer of unrelated kwargs. Authors who need only Document
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.
We **[Load the native plugin required by this operation](cap.load())**.
Return *[Low-level app handle for advanced mounts](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 | text | required | filesystem directory |
| mount | text | "/static" | URL mount |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
Use `dir`, `mount`="/static" as the inputs for this operation.
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.
Return *[Mount static files from dir at mount=/static on this app](web_app_static(app=`self`, dir=`dir`, mount=`mount`))*.
## listen
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | listen result |
Start listening with the already configured app host and port. Prefer serve for
root scanning; listen is for advanced app handles after manual route setup.
Return *[Start listening with the already configured app host and port. Prefer serve for root scanning; listen is for advanced app handles after manual route setup.](web_listen(app=`self`))*.
## gate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | required | gated path |
| roles | any | "admin" | roles supplied by the caller |
| permissions | text | "" | Comma-separated permission names held by the current role or subject |
| match | text | "prefix" | match mode |
| on_deny | text | "forbid" | deny behavior |
| exclude | any | None | exclusions |
| 返回 | 类型 | 说明 |
|------|------|------|
| result | any | app handle |
Use `path`, `roles`="admin", `permissions`="", `match`="prefix", `on_deny`="forbid", `exclude`=None as the inputs for this operation.
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.
Return *[Attach an authorization gate on path for this app](web_app_gate(app=`self`, path=`path`, roles=`roles`, permissions=`permissions`, match=`match`, on_deny=`on_deny`, exclude=`exclude`))*.