23 KiB
markup, title, description, import
| markup | title | description | import | ||
|---|---|---|---|---|---|
| occlusion | lib/browser | Readable browser effect helpers for WASM clients. Prefer GFM tables + these helpers; do not build effects with json.set chains. |
|
Readable browser effect helpers for WASM clients. Prefer GFM tables + these helpers; do not build effects with json.set chains.
Build browser effects as ordinary structured values.
Behavior and limits: Constructing an effect is pure; the official WASM bridge performs it in a browser. Native construction does not prove a DOM update occurred. Keep business logic in Marqdo.
This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.
Implementation: crates/marqdo-wasm/js/marqdo-bridge.js
For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.
set_text
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_text effect map for the official bridge |
Use sel, text as the inputs for this operation.
Effects: pure.
Call this function directly:
marqdo call lib/browser.mq.md set_text 'sel="#status"' 'text="Ready"' --effects none --json
Build set_text effect map for the official bridge.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=text)).
Return [Set the set_text field in the new record](table.put(in=None, at="set_text", value=m)).
set_html
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| html | any | required | HTML fragment; use set_text for ordinary untrusted text |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_html effect map |
Use sel, html as the inputs for this operation.
Effects: pure.
Build set_html effect map.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=html)).
Return [Set the set_html field in the new record](table.put(in=None, at="set_html", value=m)).
set_value
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_value effect map |
Use sel, value as the inputs for this operation.
Effects: pure.
Build set_value effect map.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=value)).
Return [Set the set_value field in the new record](table.put(in=None, at="set_value", value=m)).
set_class
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| class | any | required | Space-separated CSS class names |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_class effect map |
Use sel, class as the inputs for this operation.
Effects: pure.
Build set_class effect map.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=class)).
Return [Set the set_class field in the new record](table.put(in=None, at="set_class", value=m)).
add_class
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| class | any | required | Space-separated CSS class names |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build add_class effect map (classList.add; space-separated names OK) |
Use sel, class as the inputs for this operation.
Effects: pure.
Build add_class effect map (classList.add; space-separated names OK).
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=class)).
Return [Set the add_class field in the new record](table.put(in=None, at="add_class", value=m)).
remove_class
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| class | any | required | Space-separated CSS class names |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build remove_class effect map |
Use sel, class as the inputs for this operation.
Effects: pure.
Build remove_class effect map.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=class)).
Return [Set the remove_class field in the new record](table.put(in=None, at="remove_class", value=m)).
toggle_class
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| class | any | required | Space-separated CSS class names |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build toggle_class effect map |
Use sel, class as the inputs for this operation.
Effects: pure.
Build toggle_class effect map.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=class)).
Return [Set the toggle_class field in the new record](table.put(in=None, at="toggle_class", value=m)).
set_style
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| style | any | required | CSS property/value record for the target element |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_style effect map; style is a map of CSS properties or a cssText string |
Use sel, style as the inputs for this operation.
Effects: pure.
Build set_style effect map; style is a map of CSS properties or a cssText string.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=style)).
Return [Set the set_style field in the new record](table.put(in=None, at="set_style", value=m)).
set_attr
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| attrs | any | required | HTML attribute/value record for the target element |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build set_attr effect map; attrs is usually a small map of attribute names to values |
Use sel, attrs as the inputs for this operation.
Effects: pure.
Build set_attr effect map; attrs is usually a small map of attribute names to values.
We retain m = [Return the updated structured value](table.put(in=None, at=sel, value=attrs)).
Return [Set the set_attr field in the new record](table.put(in=None, at="set_attr", value=m)).
wrap
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | text | required | Field name or key required by this operation |
| value | any | required | Value to transform or store, without mutating the input |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Single-key effect map wrapper |
Use key, value as the inputs for this operation.
Effects: pure.
Single-key effect map wrapper.
Return [Return the updated structured value](table.put(in=None, at=key, value=value)).
merge
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| a | any | required | First browser effect record |
| b | any | required | Browser effect record to merge over a |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Merge two effect maps; right-hand keys win |
Use a, b as the inputs for this operation.
Effects: pure.
Merge two effect maps; right-hand keys win.
Return [Merge](table.merge(a=a, b=b)).
canvas
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| commands | any | required | Ordered list of canvas drawing commands |
| clear | any | True | Whether the canvas is cleared before drawing commands |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build canvas effect; commands is usually an @ GFM table |
Use sel, commands, clear=True as the inputs for this operation.
Effects: pure.
Build canvas effect; commands is usually an @ GFM table.
spec =
| sel | clear | commands |
|---|---|---|
sel |
clear |
commands |
Return [Set the canvas field in the new record](table.put(in=None, at="canvas", value=spec)).
audio
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| op | any | "play" | Audio command: play, pause or stop |
| id | any | "default" | Audio channel identifier |
| src | text | "" | Audio URL, or beep for a synthesized tone |
| freq | any | None | Oscillator frequency in hertz |
| ms | any | None | Duration or delay in milliseconds |
| sel | any | "" | CSS selector of the target browser element |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build audio effect for the bridge |
Use op="play", id="default", src="", freq=None, ms=None, sel="" as the inputs for this operation.
Effects: pure.
Build audio effect for the bridge.
This function returns an effect record and plays no sound immediately. The bridge selects a source, synthesized frequency or audio element; browsers may require a prior user gesture.
We retain spec = [Set the op field in the new record](table.put(in=None, at="op", value=op)).
We retain spec = [Set the id field in the new record](table.put(in=spec, at="id", value=id)).
src!= "" We retainspec= [Set the src field in the new record](table.put(in=spec, at="src", value=src)).freq!= None We retainspec= [Set the freq field in the new record](table.put(in=spec, at="freq", value=freq)).ms!= None We retainspec= [Set the ms field in the new record](table.put(in=spec, at="ms", value=ms)).sel!= "" We retainspec= [Set the sel field in the new record](table.put(in=spec, at="sel", value=sel)). Return [Set the audio field in the new record](table.put(in=None, at="audio", value=spec)).
read_file
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| as | any | "text" | File content representation expected by the browser bridge |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build read_file effect |
Use sel, then, as="text" as the inputs for this operation.
Effects: pure.
Build read_file effect.
spec =
| sel | as | then |
|---|---|---|
sel |
as |
then |
Return [Set the read_file field in the new record](table.put(in=None, at="read_file", value=spec)).
observe
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| specs | any | required | Effect specifications; use a record or an @ row-record list |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build observe effect; specs is one map or an @ list of maps |
Use specs as the inputs for this operation.
Effects: pure.
Build observe effect; specs is one map or an @ list of maps.
Return [Set the observe field in the new record](table.put(in=None, at="observe", value=specs)).
unobserve
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| specs | any | required | Effect specifications; use a record or an @ row-record list |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build unobserve effect; specs is a map or @ list with id |
Use specs as the inputs for this operation.
Effects: pure.
Build unobserve effect; specs is a map or @ list with id.
Return [Set the unobserve field in the new record](table.put(in=None, at="unobserve", value=specs)).
focus
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| sel | any | required | CSS selector of the target browser element |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build a focus effect for the selected element; the browser bridge applies it after the handler returns |
Use sel as the inputs for this operation.
Effects: pure.
Build a focus effect for the selected element; the browser bridge applies it after the handler returns.
Build the focus effect record. The browser bridge consumes this record; this function itself does not change the page.
Return [Set the focus field in the new record](table.put(in=None, at="focus", value=sel)).
navigate
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| replace | any | False | Whether navigation replaces the current history entry |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the navigate effect record |
Use url, replace=False as the inputs for this operation.
Effects: pure.
Build the navigate effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| url | replace |
|---|---|
url |
replace |
Return [Set the navigate field in the new record](table.put(in=None, at="navigate", value=spec)).
store_set
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | text | required | Field name or key required by this operation |
| value | any | required | Value to transform or store, without mutating the input |
| scope | any | "memory" | Storage scope: memory, local or session |
| then | any | "" | Marqdo callback name for the bridge result; empty text omits callback |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | In-memory (or local/session) key write for SPA client state |
Use key, value, scope="memory", then="" as the inputs for this operation.
Effects: pure.
In-memory (or local/session) key write for SPA client state. Prefer scope=memory for tab-local app state.
Optional then is called after the write with {ok, op, key, scope}.
spec =
| op | key | value | scope |
|---|---|---|---|
| set | key |
value |
scope |
then!= "" We retainspec= [Set the then field in the new record](table.put(in=spec, at="then", value=then)). Return [Set the storage field in the new record](table.put(in=None, at="storage", value=spec)).
store_get
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| key | text | required | Field name or key required by this operation |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| scope | any | "memory" | Storage scope: memory, local or session |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Read a key then call then with {ok, value, found, key, scope} |
Use key, then, scope="memory" as the inputs for this operation.
Effects: pure.
Read a key then call then with {ok, value, found, key, scope}.
spec =
| op | key | then | scope |
|---|---|---|---|
| get | key |
then |
scope |
Return [Set the storage field in the new record](table.put(in=None, at="storage", value=spec)).
spa_goto
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| replace | any | False | Whether navigation replaces the current history entry |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | SPA navigation: history.pushState / replaceState via bridge navigate effect |
Use url, replace=False as the inputs for this operation.
Effects: pure.
SPA navigation: history.pushState / replaceState via bridge navigate effect.
spec =
| url | replace |
|---|---|
url |
replace |
Return [Set the navigate field in the new record](table.put(in=None, at="navigate", value=spec)).
storage
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| spec | any | required | Storage operation record: op, key, scope and optional value/then |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Wrap one storage specification as a browser effect; the bridge handles op, key, value, scope and then |
Use spec as the inputs for this operation.
Effects: pure.
Wrap one storage specification as a browser effect; the bridge handles op, key, value, scope and then.
Build the storage effect record. The browser bridge consumes this record; this function itself does not change the page.
Return [Set the storage field in the new record](table.put(in=None, at="storage", value=spec)).
interval
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| ms | any | required | Duration or delay in milliseconds |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| id | any | "default" | Timer identifier, later passed to clear_interval |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the interval effect record |
Use ms, then, id="default" as the inputs for this operation.
Effects: pure.
Build the interval effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| ms | then | id |
|---|---|---|
ms |
then |
id |
Return [Set the interval field in the new record](table.put(in=None, at="interval", value=spec)).
clear_interval
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | "default" | Identifier returned by the corresponding create/spawn operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build a cancellation effect using the same identifier previously supplied to interval |
Use id="default" as the inputs for this operation.
Effects: pure.
Build a cancellation effect using the same identifier previously supplied to interval.
Build the clear_interval effect record. The browser bridge consumes this record; this function itself does not change the page.
We retain spec = [Set the id field in the new record](table.put(in=None, at="id", value=id)).
Return [Set the clear_interval field in the new record](table.put(in=None, at="clear_interval", value=spec)).
fetch
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | text | required | Target URL; HTTP helpers accept http or https |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| method | text | "GET" | HTTP method, for example GET or POST |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the fetch effect record |
Use url, then, method="GET" as the inputs for this operation.
Effects: pure.
Build the fetch effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| url | then | method |
|---|---|---|
url |
then |
method |
Return [Set the fetch field in the new record](table.put(in=None, at="fetch", value=spec)).
fetch_all
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| requests | any | required | Ordered list of browser request specification records |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the fetch_all effect record |
Use requests, then as the inputs for this operation.
Effects: pure.
Build the fetch_all effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| requests | then |
|---|---|
requests |
then |
Return [Set the fetch_all field in the new record](table.put(in=None, at="fetch_all", value=spec)).
after
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| ms | any | required | Duration or delay in milliseconds |
| then | any | required | Marqdo callback name for the bridge result; empty text omits callback |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the after effect record |
Use ms, then as the inputs for this operation.
Effects: pure.
Build the after effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| ms | then |
|---|---|
ms |
then |
Return [Set the after field in the new record](table.put(in=None, at="after", value=spec)).
ws
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| spec | any | required | One bridge effect specification record |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Wrap a WebSocket operation specification for the browser bridge; this function opens no native socket |
Use spec as the inputs for this operation.
Effects: pure.
Wrap a WebSocket operation specification for the browser bridge; this function opens no native socket.
Build the ws effect record. The browser bridge consumes this record; this function itself does not change the page.
Return [Set the ws field in the new record](table.put(in=None, at="ws", value=spec)).
clipboard
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| text | text | required | Text supplied by the caller |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build a clipboard effect from the text; browser permissions and user-gesture requirements apply when consumed |
Use text as the inputs for this operation.
Effects: pure.
Build a clipboard effect from the text; browser permissions and user-gesture requirements apply when consumed.
Build the clipboard effect record. The browser bridge consumes this record; this function itself does not change the page.
We retain spec = [Set the text field in the new record](table.put(in=None, at="text", value=text)).
Return [Set the clipboard field in the new record](table.put(in=None, at="clipboard", value=spec)).
download
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| body | any | required | Request body, or replacement text for document operations |
| filename | any | "download.txt" | Suggested download filename |
| mime | any | "text/plain;charset=utf-8" | Content MIME type |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Build the download effect record |
Use body, filename="download.txt", mime="text/plain;charset=utf-8" as the inputs for this operation.
Effects: pure.
Build the download effect record. The browser bridge consumes this record; this function itself does not change the page.
spec =
| body | filename | mime |
|---|---|---|
body |
filename |
mime |
Return [Set the download field in the new record](table.put(in=None, at="download", value=spec)).