Files
marqdo/ext/web/web.mq.md

20 KiB

markup, title, description, import
markup title description import
occlusion ext/web/web 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).
cap page_mod route_mod dom_mod client_mod table
ext/web/_capability/index.mq.md ext/web/page/index.mq.md ext/web/route/index.mq.md ext/web/dom/index.mq.md ext/web/client/index.mq.md lib/table.mq.md

Web facade — start at the root handbook, 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.

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.

  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)).

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. 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. 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. 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. 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. Return Build image descriptors from a readable table of sources and alts. Keep media declarations in Markdown tables beside the Document that uses them..

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. Return Build head resource rows (link, script, icon) from a table. Prefer declaring head needs as data rather than injecting opaque HTML head strings..

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. 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. Return Serve the prepared site with its bound resources.

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. 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..

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)).