Files
marqdo/examples/browser-app/static/app.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

28 KiB
Executable File
Raw Blame History

markup, title, description, import
markup title description import
occlusion Browser effects — native records and explicit completion list CRUD, storage, navigate, interval, fetch_all, ws — GFM + lib/browser
browser table text
lib/browser.mq.md lib/table.mq.md lib/text.mq.md

main

返回 类型 说明
result any Initial browser view/state record

This entry prepares browser instructions; it does not itself fetch a URL or manipulate a server filesystem. The host page must supply the selectors listed below. List state uses native records with stable ids, keeping duplicate text and literal newlines independent. The wire table maps each UI event to one actual callback, including delegated item buttons, history navigation, timer controls, parallel fetches and a named WebSocket connection.

Event declarations contain no user values interpolated into code. Input values flow through callback parameters while the server page remains a separate document.

The returned boot record combines event registration and a storage lookup, without pushing an initial history entry. The browser bridge applies those instructions and dispatches later events into the callbacks. Draft text, tick count, route and socket identifier belong to that browser instance. Storage callbacks complete asynchronously; the initial return is not proof that a saved draft was found.

We ticks = 0 as the retained count before the first real timer event. We items = Start native list state and next_id = 1 for independent record identities. We route_path = "/" as this browser instance’s panel state. We ws_id = "echo" as the one named local connection.

wire =

@ 选择器 事件 调用 委托 值选择器
1 "#add" click add "#draft"
2 "#save" click save_draft "#draft"
3 "#load" click load_draft
4 "#start-tick" click start_tick
5 "#stop-tick" click stop_tick
6 "#nav-home" click go_home
7 "#nav-about" click go_about
8 "#nav-net" click go_net
9 "window" popstate on_pop
10 "#items" click on_item "button[data-id]"
11 "#fetch-all" click do_fetch_all
12 "#ws-open" click ws_open
13 "#ws-send" click ws_send "#ws-msg"
14 "#ws-close" click ws_close
15 "#copy-log" click copy_log
16 "#dl-list" click dl_list

st =

op key then
get mq-draft on_draft

boot =

wire storage
wire st

After these steps, return boot.

add

参数 类型 默认 说明
value text "" Exact draft text supplied by the add control
返回 类型 说明
result any Native list refresh, input clear and focus; None for empty text

Use value="" from the input. Retain each nonempty value exactly as one record, including quotes, angle brackets or a literal newline. A monotonically assigned id separates duplicate titles; deleting one must not erase its siblings. This direct callback updates entry state, then passes those records explicitly to the pure renderer. No business value is interpolated into HTML.

The input clears and regains focus after a real local addition. An empty string returns None without changing records or consuming an id. This list is session memory; only the separately saved draft uses browser storage.

  1. value == "" Return None because there is no new item. We id = Assign an independent stable identity and next_id = next_id + 1.

record =

id text
id value

We items = [Retain the actual text record](table.append(list=items, item=record)) and view = Render typed labels and delete controls and clear = [Clear the completed input](browser.set_value(sel="#draft", value="")) and focus = Return to the draft control. We view = [Keep the independent list and value effects](browser.merge(a=view, b=clear)). Return [Keep focus with the completed list update](browser.merge(a=view, b=focus)).

on_item

参数 类型 默认 说明
data_id text "" Stable id supplied by the delegated delete button
返回 类型 说明
result any Remaining native records and removal feedback, or None for an unknown id

Use data_id="" from button[data-id]. Compare identities rather than text, so duplicate values and values containing newlines stay independent. Preserve remaining order and do nothing for an empty or unknown id. The renderer receives retained records explicitly; it does not infer client state inside a normal helper call.

A deletion rebuilds the same list through typed controls and reports the removed id as text. It neither modifies a saved draft nor changes timer, transport or route state. Ids are not recycled after deletion, avoiding a stale event selecting a different later item.

  1. data_id == "" Return None for an absent selection. We remaining = Start the retained row order.
  • [Keep every record except the selected identity](for items as item)
    1. access(item, "id") != data_id We remaining = [Keep this independent record](table.append(list=remaining, item=item)).
  1. len(remaining) == len(items) Return None because no selected identity exists. We items = remaining and view = Render the actual retained rows and message = "removed " + data_id and status = [Describe the observed local removal](browser.set_text(sel="#log", text=message)). Return [Keep list and feedback together](browser.merge(a=view, b=status)).

save_draft

参数 类型 默认 说明
value text "" Exact text selected from the draft input
返回 类型 说明
result map Storage write request; completion arrives at on_saved

Use value="" from the draft control. The storage record names the local key and its completion callback. Return the request immediately; only on_saved can announce a successful write. An intentionally empty draft is valid and differs from an absent key. Storage belongs to this browser origin, while list records stay in session memory. Returning this record does not write server files or grant process access.

request =

op key value then
set mq-draft value on_saved

Return Ask the browser to persist the exact draft.

load_draft

返回 类型 说明
result map Storage read request with an explicit completion callback

Request mq-draft from this browser origin. The callback distinguishes a missing key, an empty saved value and a failed read. No input is cleared while the read is pending, and this operation never replaces the native item list. The same read runs at boot, so a reload restores the saved draft without claiming to persist list records.

request =

op key then
get mq-draft on_draft

Return Request the stored draft and its actual outcome.

on_draft

参数 类型 默认 说明
ok bool True Actual storage-read completion
value text "" Stored draft text, including an intentionally empty value
found bool False Whether the key actually existed
返回 类型 说明
result map Restored value and feedback, or actual missing/failure feedback

Use ok=True, value="" and found=False from storage. A missing key differs from a stored empty draft, and an unsuccessful read must not be described as absence. Restore the exact value only after a successful read with found=True. This changes the draft input, not the native item list, and never interprets the stored text as code.

  1. not ok Return [Keep a failed read visible](browser.set_text(sel="#log", text="draft read failed")).
  2. not found Return [Keep an absent draft visible](browser.set_text(sel="#log", text="no draft")). We value_effect = [Restore exact stored draft text](browser.set_value(sel="#draft", value=value)) and status = [Confirm the observed read](browser.set_text(sel="#log", text="draft loaded")). Return [Keep the actual value and feedback](browser.merge(a=value_effect, b=status)).

start_tick

返回 类型 说明
result map One named repeating timer instruction

Start tick at one-second intervals. The bridge replaces a timer with the same id, so repeated Start clicks do not accumulate independent clocks. Each callback increments the session counter once. This returns an instruction; it is neither a blocking sleep nor proof that one second has passed. Stop cancels future callbacks and preserves the accumulated display.

Return [Start or replace the one named timer](browser.interval(ms=1000, then="on_tick", id="tick")).

stop_tick

返回 类型 说明
result map Cancellation of the named timer

Cancel tick through its explicit id. Calling Stop before Start is harmless, and stopping does not reset the visible count or alter other timers. A later Start resumes counting from retained state. The browser owns the timer handle; authors do not keep a JavaScript handle or generate a client program to clear it.

Return Cancel future callbacks for this timer.

on_tick

参数 类型 默认 说明
ok bool True Whether this timer callback is valid
id text "" Actual named timer id
返回 类型 说明
result any Updated count, or None for a failed/unrelated callback

Use ok=True and id="" from the timer. Count only successful events belonging to tick; unrelated callbacks must not change this counter. Retained ticks belongs to the direct browser callback, rather than being supplied by the event. A manual call to this function constructs the same text effect but does not prove that a real timer fired.

  1. not ok or id != "tick" Return None for an unrelated timer outcome. We ticks = ticks + 1 and label = Format the actual accumulated count. Return [Display that observed timer count](browser.set_text(sel="#tick", text=label)).

go_home

返回 类型 说明
result map Selected panel effects and one actual navigation request

Select / from its authored navigation control. This direct callback updates the retained panel state and requests exactly one history entry. The helper receives the path explicitly rather than assuming an ordinary call captures entry bindings. Back/Forward uses on_pop, which renders without navigation. No server request or page HTML is constructed here.

We route_path = "/". Return [Render and request this one deliberate navigation](_view(route=route_path, push=True)).

go_about

返回 类型 说明
result map Selected panel effects and one actual navigation request

Select /about from its authored navigation control. This direct callback updates the retained panel state and requests exactly one history entry. The helper receives the path explicitly rather than assuming an ordinary call captures entry bindings. Back/Forward uses on_pop, which renders without navigation. No server request or page HTML is constructed here.

We route_path = "/about". Return [Render and request this one deliberate navigation](_view(route=route_path, push=True)).

go_net

返回 类型 说明
result map Selected panel effects and one actual navigation request

Select /net from its authored navigation control. This direct callback updates the retained panel state and requests exactly one history entry. The helper receives the path explicitly rather than assuming an ordinary call captures entry bindings. Back/Forward uses on_pop, which renders without navigation. No server request or page HTML is constructed here.

We route_path = "/net". Return [Render and request this one deliberate navigation](_view(route=route_path, push=True)).

on_pop

参数 类型 默认 说明
path text "" Actual browser pathname, including optional query string
返回 类型 说明
result map History-selected panel effects without pushing history again

Use path="" from the real popstate callback. Keep its normalized panel route in the differently named entry state, avoiding accidental shadowing of a callback parameter. The browser has already selected this history entry, so returning navigate would add an incorrect new entry. Query text does not choose a different panel; only the known pathname is used.

We parts = [Separate the pathname from query text](text.str_split(s=path, sep="?")) and route_path = Keep the actual panel path. Return Reflect the actual history position.

show_path

返回 类型 说明
result map Current panel visibility and label without history mutation

This direct browser callback reads retained route_path and delegates pure rendering with explicit input. It never pushes another history entry, so a repaint cannot trap Back/Forward. Call the navigation callbacks to request a new route. Server routing and page structure remain separate responsibilities; unknown browser paths select the home panel.

Return Refresh the retained panel without navigating.

do_fetch_all

返回 类型 说明
result any The value explicitly returned below; conditional returns follow the selected branch

Queue two independent browser fetches and return an immediate loading message together with the request instruction. Results arrive through on_fetch_all; this initial return does not contain either HTTP response. The request table keeps both URLs visible and avoids generating JavaScript to construct the batch.

The example endpoint is external and may fail or be unavailable. Consumers must inspect the actual callback records rather than count request declarations as successful responses. Browser network policy still applies; no backend file or shell operation is authorized by this instruction.

reqs =

@ url
1 "https://httpbin.org/uuid"
2 "https://httpbin.org/uuid"

We msg = [Describe the pending batch](browser.set_text(sel="#net-out", text="fetch_all…")) and requests = [Request both actual HTTP outcomes](browser.fetch_all(requests=reqs, then="on_fetch_all")). Return [Keep pending feedback with its asynchronous requests](browser.merge(a=msg, b=requests)).

on_fetch_all

参数 类型 默认 说明
ok bool True Whether the batch callback itself completed
results any None Ordered per-request ok/status/body/error records
返回 类型 说明
result map Actual per-request outcomes shown as plain text

Use ok=True and results=None from the bridge. A completed batch can still contain failed HTTP or network operations; the outer callback flag does not make each record successful. Show the real ordered records, including status, body and errors, rather than a fixed completion message. Text output cannot become HTML or a browser command.

A missing result list stays visibly unavailable. Public endpoints remain demonstration dependencies; local tests supply controlled responses and a failure. This callback does not retry a request or replace its body with a predetermined answer.

  1. not ok Return [Keep batch failure visible](browser.set_text(sel="#net-out", text="fetch_all failed")).
  2. results == None Return [Keep absent results distinct](browser.set_text(sel="#net-out", text="fetch_all returned no results")). We message = Retain actual request outcomes. Return [Display observed successes and failures literally](browser.set_text(sel="#net-out", text=message)).

ws_open

返回 类型 说明
result map Named local WebSocket request and lifecycle callbacks

Open the site’s /live echo resource under the explicit echo id. A relative URL uses the current origin and its transport security, allowing the example to run without a public echo provider. The server separately binds this native network resource. Returning the record only requests a connection; open, message, error and close callbacks describe actual transport outcomes. Subsequent send and close instructions reuse the same id.

request =

op id url then_open then_message then_error then_close
open ws_id "/live" on_ws_open on_ws_msg on_ws_err on_ws_close

Return Request the local echo connection.

on_ws_open

参数 类型 默认 说明
ok bool True Actual connection completion
id text "" Connected socket id
返回 类型 说明
result any Confirmed connection text, or None for a failed/unrelated callback

Use ok=True and id="" from the real transport. Accept only the named echo socket; a different resource cannot announce this widget ready. This callback confirms the handshake, while sending still requires a separate user action. It neither invents a received message nor marks a requested connection successful before the bridge reports it.

  1. not ok or id != ws_id Return None for an unrelated connection. Return [Confirm the observed handshake](browser.set_text(sel="#net-out", text="ws open")).

on_ws_msg

参数 类型 默认 说明
ok bool True Actual message completion
data text "" Exact received text
id text "" Receiving socket id
返回 类型 说明
result any Literal received message, or None for a failed/unrelated callback

Use ok=True, data="" and id="" from the echo connection. Preserve the complete received text, including quotes and angle brackets. Display it through set_text so a message is data rather than page markup. Receipt is independent of the send click: the remote resource may respond later or close without replying.

  1. not ok or id != ws_id Return None for an unrelated message. We message = "ws ← " + data. Return [Display the actual echo as plain text](browser.set_text(sel="#net-out", text=message)).

on_ws_err

参数 类型 默认 说明
ok bool False Failure flag supplied by the bridge
error text "" Actual transport failure text
返回 类型 说明
result map Visible transport failure

Use ok=False and error="" from the transport callback. Keep the actual error text in the output rather than substituting a success message. The callback performs no automatic reconnect and sends no pending message. Reopening is an explicit user operation; failures remain inspectable while the rest of the page can continue operating.

We message = "ws error: " + error. Return [Expose the actual connection failure](browser.set_text(sel="#net-out", text=message)).

on_ws_close

参数 类型 默认 说明
ok bool True Actual close callback flag
id text "" Closed socket id
返回 类型 说明
result any Observed close text, or None for an unrelated socket

Use ok=True and id="" after the bridge observes closure. The named socket may close because of the user’s request or the server. This is a lifecycle observation and does not itself initiate another close or reopen. Leave list state, draft and timer untouched so transport changes remain independent of local page work.

  1. id != ws_id Return None for an unrelated socket. Return [Report the observed connection closure](browser.set_text(sel="#net-out", text="ws closed")).

ws_send

参数 类型 默认 说明
value text "" Exact text selected from the message input
返回 类型 说明
result map Send request for the existing named socket

Use value="" as the message payload. Sending preserves literal text and addresses the existing echo socket; it does not create a second hidden connection. Open first and wait for the real connection callback. The request is not an echo result: only on_ws_msg displays a received response, and transport failures remain visible through the bridge.

request =

op id data
send ws_id value

Return Send exact text through the named connection.

ws_close

返回 类型 说明
result map Close request for the named socket

Ask the bridge to close echo, reusing the same identity as open and send. The close callback supplies the observed lifecycle result. Returning this instruction does not delete page records or cancel the independent timer. Closing an absent connection is harmless; opening a later connection remains an explicit user action.

request =

op id
close ws_id

Return Request closure of this connection.

copy_log

返回 类型 说明
result map Clipboard request and truthful queued feedback

Export the retained item texts in their current order, including duplicate values and literal newlines. The native records remain unchanged. This browser capability is a request: policy, user activation or the destination environment may prevent completion. The bridge exposes errors, and the immediate feedback says queued because no completion callback confirms a final clipboard write or saved file.

We plain = Read the current literal list export and request = Request clipboard delivery and status = [Describe only the requested operation](browser.set_text(sel="#log", text="clipboard request queued")). Return [Keep the request and its truthful feedback](browser.merge(a=request, b=status)).

dl_list

返回 类型 说明
result map Download request and truthful queued feedback

Export the retained item texts in their current order, including duplicate values and literal newlines. The native records remain unchanged. This browser capability is a request: policy, user activation or the destination environment may prevent completion. The bridge exposes errors, and the immediate feedback says queued because no completion callback confirms a final clipboard write or saved file.

We plain = Read the current literal list export and request = [Request the plain-text download](browser.download(body=plain, filename="items.txt")) and status = [Describe only the requested operation](browser.set_text(sel="#log", text="download request queued")). Return [Keep the request and its truthful feedback](browser.merge(a=request, b=status)).

_list

参数 类型 默认 说明
records list required Native id/text records in visible order
返回 类型 说明
result map Structured list effect with literal labels and native delete buttons

Use records from the direct callback's retained state. Each row contains a span label and button as typed children. The button's data-id carries the independent record identity; visible business text stays in text, never html. The official bridge escapes it and preserves delegation without rebuilding the parent page.

This helper is pure and receives records explicitly. It does not read hidden entry state, delete anything or assume that a returned effect has already reached the DOM. The existing host list and event wiring own those later steps.

We rows = Start the native visible row records.

  • [Describe one label and native delete action](for records as record) We id = Retain the exact row identity) and value = Retain literal business text).

    label =

    tag text
    span value

    attributes =

    type data-id
    button id

    button =

    tag text attrs
    button 删 attributes

    children =

    node
    label
    button

    row =

    tag children
    li children

    We rows = [Retain this typed row](table.append(list=rows, item=row)). Return [Update only the existing list](browser.render_list(sel="#items", items=rows)).

_view

参数 类型 默认 说明
route text required Selected panel pathname
push bool False Explicit navigation callback requests one history entry
返回 类型 说明
result map Actual boolean panel visibility, path label and optional deliberate navigation

Use route and push=False. Only /about and /net select secondary panels; other paths render Home. Hidden attributes are actual booleans, while False removes the attribute. The pure helper receives its path explicitly and does not pretend to capture the browser entry state.

History observations use the default without navigation; authored link callbacks opt in once. Keep all three targets inside a single set_attr record because effect merging is shallow and otherwise one target map could overwrite another. This function performs no fetch, storage write or socket operation.

We selected = "/".

  1. route == "/about" or route == "/net" We selected = route. We home = [Describe Home visibility](table.put(in=None, at="hidden", value=(selected != "/"))) and about = [Describe About visibility](table.put(in=None, at="hidden", value=(selected != "/about"))) and network = [Describe Network visibility](table.put(in=None, at="hidden", value=(selected != "/net"))).

targets =

#panel-home #panel-about #panel-net
home about network

We visibility = [Keep every panel target together](browser.wrap(key="set_attr", value=targets)) and message = "path: " + selected and label = [Display the selected path](browser.set_text(sel="#path", text=message)) and effects = [Keep independent visibility and text effects](browser.merge(a=visibility, b=label)).

  1. push We navigation = Request one intentional history entry and effects = [Keep navigation with its actual panel effects](browser.merge(a=effects, b=navigation)). Return effects after describing the real selected panel.

_plain

参数 类型 默认 说明
records list required Native text records in retained order
返回 类型 说明
result text Literal newline-joined values for copy or download

Use records to retain the original plain-text export purpose without turning the client state into a newline-encoded database. Each item's text remains a single native value; newlines are introduced only in this human-readable export. This pure transformation neither writes the clipboard nor starts a download, and it does not encode HTML.

We values = [Select actual text fields in order](table.pluck(list=records, key="text")). Return [Form the intended text export](text.str_join(xs=values, sep="\n")).

on_saved

参数 类型 默认 说明
ok bool True Actual storage-write completion
返回 类型 说明
result map Feedback for the completed write

Use ok=True from the storage callback. Confirm saving after the browser reports completion, rather than when the user merely clicks Save. A failed callback remains a failure message. Host storage exceptions also appear through the official bridge error channel; this function cannot turn an unavailable storage service into a successful write.

  1. not ok Return [Expose the failed write](browser.set_text(sel="#log", text="draft save failed")). Return [Confirm the completed write](browser.set_text(sel="#log", text="draft saved")).