Files
marqdo/lib/browser.mq.md
T

705 lines
23 KiB
Markdown

---
markup: occlusion
title: lib/browser
description: >-
Readable browser effect helpers for WASM clients. Prefer GFM tables + these
helpers; do not build effects with json.set chains.
import:
table: lib/table.mq.md
---
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](../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:
```sh
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`))**.
1. `src` != ""
We retain **`spec` = [Set the src field in the new record](table.put(in=`spec`, at="src", value=`src`))**.
1. `freq` != None
We retain **`spec` = [Set the freq field in the new record](table.put(in=`spec`, at="freq", value=`freq`))**.
1. `ms` != None
We retain **`spec` = [Set the ms field in the new record](table.put(in=`spec`, at="ms", value=`ms`))**.
1. `sel` != ""
We retain **`spec` = [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` |
1. `then` != ""
We retain **`spec` = [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`))*.