Module dom

Expand description

An in-process mock DOM — the shared oracle that gives the DOM builtins identical semantics on the tree-walker and the register VM (they both run call_builtin), so the sacred WASM==VM==tree-walker invariant holds even though the DOM is browser-only.

A DOM-driving LOGOS program builds a node tree and mutates it; on the native tiers those operations land here (a thread-local handle table + an ordered op-log), and on the wasm tier the SAME operations land in the emitted module’s dom_* host imports — a MockDom linker in tests, the real browser DOM in production. Because DOM ops emit no Show, the existing output differential passes trivially; the DOM EFFECTS are compared via op_log/render, keyed by node creation ordinal (raw handles legitimately differ per tier), which the wasm MockDom reproduces because it creates nodes in the same order.

Modeled on logicaffeine_base::money’s AMBIENT_RATES thread-local.

Structs§

DispatchPath: Where an event dispatched at one element goes: the listeners it reaches, in order, and whether one of them cancels its default action — dispatch_path.
DomRecorder: The mock DOM: a handle table of nodes + the ordered op-log. Handle 0 is always body, the render root.
DomState: Everything a document holds: its tree, its once-per-mount declared head, and the shell it is served in. What take saves and restore puts back.
DroppedFile: A file a drop carries: its name, the type its author declared for it when they declared one, and its content. Its size is always its content’s length, as a browser’s File.size is; its type (DroppedFile::mime_type) is the declared one, and otherwise what a browser names the file from its name (browser_mime_type).
FetchRequest: One recorded fetch request — the tw≡VM parity surface for the request side (what was asked for, with what method/body/headers, and its control state).
HeadTag: One element of a document’s <head>: its tag, its attributes, and the text it holds — a <title>’s, a <style>’s or <script>’s raw content, nothing for a void element.
Link: A link a click lands on: the nearest <a href> that is the clicked element or holds it, as a browser’s activation behaviour finds it.
Validity: Why a form control is invalid, flag for flag as a browser’s ValidityState reports it. The constraints modelled are required, type="email"/url"/number", minlength/maxlength, pattern and a number’s min/max/step; min/max/step on the date and time types are not modelled.

Enums§

DomOp: One recorded DOM mutation. Nodes are referenced by their creation ordinal (the handle, assigned sequentially from 0 = body), so op-logs compare equal across tiers regardless of how each tier numbers its handles internally.
RouteOp: One recorded navigation — the router’s history op-log entry: a pushState (replace: false, a new history entry) or replaceState (replace: true, swap the current one) within the page, or a document load. Compares equal across tiers; the wasm MockDom records the same shape.
ToggleControl: A control whose CHECKED state a click moves. See DomRecorder::toggle_control.

Constants§

CSRF_META_NAME: The <meta name=…> a document carries its CSRF token in — written by the server that composes a page under a ## Session, and read by every tier’s host when the page makes a request.
FETCH_ALLOWED_REQUEST_HEADERS: The request headers fetchSend allows (lowercase). A header outside this list fails the request immediately with "network: header not allowed: <name>" — the browser would silently strip or reject forbidden headers per-engine; the contract makes the denial explicit and identical on every tier.
FETCH_REQUEST_BODY_CAP: The largest request body fetchSend will put on the wire — exceeding it fails the request immediately with the "toolarge" transport error (never a silent truncation). Shared by every tier (native recorder, MockDom, browser host) so behavior cannot drift.
FETCH_RESPONSE_BODY_CAP: The largest response body a fetch will deliver — a larger body is dropped and the request fails with "toolarge" (the callback still runs and can read the error).
LISTEN_CAPTURE
LISTEN_ONCE
LISTEN_PASSIVE
LISTEN_PREVENT: Event-modifier bits a listener registration carries (listenFlags, DomOp::Listen) — .prevent / .stop / .once / .capture / .passive, one bit each, in that order. Every host dispatches by them as a browser does (dispatch_path), except .once, which the lowering keeps itself: a host never retires a listener on its own.
LISTEN_STOP
NON_BUBBLING_EVENTS: The events a browser dispatches WITHOUT a bubbling phase — the ones a listener on an ancestor hears only by capturing. Every other event bubbles.
STREAM_ID_BASE: The first id of the range a patch stream’s emitter names (vdom.lg’s vdWire); every id below it is a creation ordinal this recorder minted itself, so the two never collide.
STUB_CONTENT_TYPE: Every request the run registered, in id order — the tw≡VM parity surface for the REQUEST side (method, url, body, headers, timeout, abort state). The content type an answer a test arranged (stub_fetch) is served with, on every tier.

Functions§

add_class: Add a class to an element’s class list, leaving the others alone.
add_event_listener
adopt: Adopt(parent, node, tag) — see DomOp::Adopt.
adopt_text: AdoptText(parent, node, text) — see DomOp::AdoptText.
answers_by_itself: Whether the browser’s own default action of verb on the element selector names changes it — typing enters text into a control that takes typed text, choosing selects an option the <select> offers — so the verb is answered whether or not the page listens: the value it entered is on the page, and the control’s validity with it. A click, a press, a submit and a hover answer only through a listener (a checkbox’s click is answered by its toggle, where the click is decided).
append_child
arrive: The page arrives, served in document — the shell HTML a browser loads it in: from now on this world’s document starts from that shell’s head, this load and every reload after it, so a page the host drives in process arrives in exactly the document a browser holds. The shell’s body is not read: the page paints its body itself.
assign_location: Another document loads at url — a link followed, or a request_load carried out. The page that asked is gone; the location and the back stack move to url; the load is the first thing the new document’s navigation log records (RouteOp::Load); and the document is empty, since what url serves is another page’s content, outside the page under test. The test’s own answers for requests survive, as they do across a reload.
atomically: Runs change against the document and keeps what it did only if it succeeds: on an Err the document is exactly as it was before, op log included.
attribute: One of node’s attribute values.
begin_dispatch: Simulate an event dispatch on the NATIVE tiers: look up the (node, event) handler, set the current event (its target + value), and hand the closure back to the caller to invoke (the interpreter owns closure invocation). Returns the closure, or None if no handler is registered.
begin_dispatch_keyed: begin_dispatch, naming the key for a keyboard event so eventKey can report it.
begin_fetch_resolve: Deliver request req with status/headers/body: record its per-request response, point the current-delivery cursor at it, and hand back its completion closure for the caller to invoke. None if the request is unknown or already FINAL (aborted/failed/delivered — the anti-double-delivery rule).
body
browser_mime_type: The type a browser gives a file named name: by the extension after its last ., from the browser’s own table; "" for a name with no extension, or with one the table does not name.
changes_state: Whether a request changes state on the server, and so must prove it came from the page the server handed out: POST, PUT, PATCH, DELETE.
clear_children
clipboard: What is on the clipboard ("" when the page has never written to it).
control_value: A control’s value as a browser reports it — see Validity.
create_element
create_element_as: A new element under the id a patch stream names for it — see STREAM_ID_BASE.
create_text_node
create_text_node_as: A new text node under the id a patch stream names for it — see STREAM_ID_BASE.
deliver_pop: Deliver a popstate (back/forward) at path: move the current path and hand back every registered handler closure, in registration order, for the caller to invoke (the interpreter owns closure invocation) — none when nothing is registered. Deterministic — never a real browser event.
dispatch_path: The walk event dispatched at target takes, as a browser dispatches it: the capture-phase listeners of the target’s ancestors from the root down, the target itself, then — when the event bubbles (event_bubbles) — the other ancestors’ listeners from the target back up. A listener registered .stop ends the walk after it. The target is always on the walk: whether anything there answers is the page’s own dispatcher’s to say.
document_head: The document’s head as it stands — the shell it arrived in with the page’s own Head: merged over it — element by element in the reference renderer’s serialization. None when the head holds no element.
downloads: Every download the page has offered, in order.
dropped_file: The file the drop being delivered carries (set_dropped_file) — no file (no name, no type, no content) when no drop has carried one.
element_blur: element.blur(): the focused element loses focus to nothing and blur is raised on it (take_raised_events); an element that does not have focus is left alone.
element_focus: element.focus(): a focusable element that does not have focus takes it, the element that had it losing it first — and the blur and focus that raises wait in take_raised_events for the host to deliver once the turn that asked has committed, as a browser delivers them. Anything else is left alone: an element that cannot take focus, or already has it.
end_dispatch
end_fetch_resolve
end_hydration: Ends the hydration a stream opened, as the stream ends; answers its mismatches (0 when the stream hydrated nothing).
enter_value: The value a visitor’s Type/Choose leaves in the control selector names before the verb raises its events — the browser’s own default action of typing (the text replaces what the field held) and of choosing (the option whose value, or else whose text, is value becomes the select’s value). Recorder state rather than an op: it is the visitor’s act on the document, not something the page asked for. Other verbs, a control the verb cannot act on (answers_by_itself), and a choice no option offers, leave it alone.
event_bubbles: Whether event bubbles in a browser — see NON_BUBBLING_EVENTS.
event_key: eventKey() -> Text — the key of the keyboard event being dispatched, "" otherwise.
event_target
event_value
fail_fetch: Deliver a structured transport failure for req (same finality rule).
fetch_abort: fetchAbort(reqId) — the request becomes FINAL with the "abort" error; a late response can never deliver.
fetch_requests
fetch_send: fetchSend(method, url, body, headers, onDone) -> Int — register a request, returning its correlation id. Contract violations (oversized body, disallowed header) fail the request immediately with a structured error.
fetch_set_timeout: fetchSetTimeout(reqId, millis) — arm (> 0) or clear (0) the timeout.
fetch_start: The fetchText(url, onDone) sugar — a GET through the correlated engine.
focus_by: The default focus action of verb on the element selector names, carried out, as the events it raises in the order a browser raises them: blur on the element that lost focus, then focus on the one that gained it — each (element, event), before the verb’s own events. Nothing when the selector names no element (the verb reports that itself) or focus stays put.
focus_for: The default focus action of verb on node, carried out: focus_target, then move_focus. What a driving verb does before it raises its own events.
focus_target: Where the default action of verb on node sends keyboard focus (crate::semantics::drive::Verb::focus_target): Some(element), Some(-1) for off every element, None when focus does not move.
focusable: Whether node can take keyboard focus, as a browser decides it: a control that is not disabled (button, select, textarea, an input other than type="hidden"), a link or image-map area with an href, an iframe, a summary, audio/video showing controls, and any element carrying a tabindex or an editable contenteditable.
focused: The focused element, or a negative handle when nothing is focused.
follow_response: A form the browser submitted itself (a POST no listener cancelled) is answered with a new document: the browser is at url, the address it posted to, and the document is the response. The document is the one a browser builds for the response’s type: a text/html response is the page it holds — its <head> and <body>, or the markup as the body when it is a fragment; a JSON response is shown in the browser’s JSON viewer, the raw text in a preformatted block; any other response is shown as plain text. The test’s answers for requests survive, as they survive a reload.
form_constraints: The controls that stop form from being submitted, in document order: none when the form says novalidate or its submitter says formnovalidate, else every control the form owns whose validity is not valid.
form_fields: The (name, value) of every named field inside node — a form’s payload, in document order.
form_of: The <form> node belongs to, if any: itself when it is one, else its form owner.
free_node
get_checked
get_text
get_value
go_back: Go back. — step one entry back and hand over the route handlers to fire, exactly as a real popstate would. None when there is nowhere to go: the first page a visitor lands on has no previous entry, and a browser’s Back button does nothing there rather than inventing one.
has_attribute: Whether node carries attribute name at all — the PRESENCE question an HTML boolean attribute is asked with ("#b" is disabled). Comparing its value against a string would call an enabled control disabled, since disabled="" is the enabled-looking spelling of disabled.
head_html: The head HTML the last mounted page declared, if it declared one. None means the page has no Head: — which is not the same as an EMPTY head, and the difference is whether the default shell’s title stands. What a server composes the page’s document from.
hydrate: Hydrate(root): the markup root holds is the page’s first paint, and the stream’s claims adopt its nodes — see DomOp::Hydrate. The root’s data-logos-prerendered mark goes with it.
init_route: Seed the initial location (a refresh / deep-link: the app boots already AT this path with this query string). Called by tests before a run.
insert_before
is_shown: Whether a visitor would SEE the first element matching selector — see Dom::shown.
link_of: The link a click on node lands on (Link), if any.
listen: listenFlags(el, event, flags): register event on node with the behavioural modifiers flags names (LISTEN_PREVENT and its siblings), replacing the flags an earlier registration gave it. dispatch_path walks by them.
move_focus: Move keyboard focus to target (-1: off every element), as a browser’s focusing steps do: (blurred, focused) — the element that lost focus and the one that gained it, -1 for none — for the caller to raise blur and then focus on; None when focus is already there.
navigate: navigate(path) — history.pushState: record the navigation, move the path.
node_address: A selector naming node by the identity a browser’s reconciler keeps it by through a repaint: #id when the element carries an id that names it, body for the page’s body, else its PLACE — its child index under each ancestor from body down, and its tag — which query_selector resolves to whatever element of that tag stands there now. The place form is not one any page can spell: it begins with a character no selector contains, and is resolved before the selector grammar is consulted. Empty for a node that is not an attached element.
note_event_listener: Record that a listener was attached, without handing the recorder a closure to fire.
notifications: Every notification the page has raised, in order.
notify: Notify "…". — a notification the page raised, (message, tone).
offer_download: Download <content> as "<name>". — a file the page offered, (name, content).
on_route: onRoute(handler) — register a popstate handler closure: a back/forward fires it, and every other handler registered before it, as a browser’s popstate reaches every listener.
op_log: The ordered op-log recorded so far — the parity assertion surface.
parse_head: Head markup — a page’s rendered Head:, or the head of the shell it is served in — as its elements, in order. What a browser’s parse keeps of it: element names and attribute names fold to lower case, the first of two same-named attributes wins, character references decode (never inside <style>/<script>), text between elements is formatting and is dropped, and an <html …> is a statement about the document element, never an element of the head.
pattern_matches: Whether value matches a control’s pattern= — an ECMAScript regular expression matched against the WHOLE value (^(?:pattern)$), with the v flag a browser compiles it with: \d, \w and \s are ASCII digits, word characters and JavaScript’s whitespace, and a class may nest classes and combine them with -- and &&. A pattern that is not a valid expression constrains nothing, as in a browser. The v flag’s strings — \q{…} and the string properties (\p{RGI_Emoji}) — are refused by name: the engine here cannot express them.
prevent_default: Record that a listener on node for event cancels the browser’s default action.
publish: Publish M on "t". — the frame the page handed to the transport, (topic, message).
published: Every frame the page has published, in order.
query_selector
query_selector_all: Every node matching selector, in document order.
reload: Reload the page. as a browser reloads it: a fresh document loaded from the SAME server at the SAME address, arriving in the same shell (DomRecorder::next_document).
remove_attribute
remove_class: Remove a class from an element’s class list, leaving the others alone.
remove_node
render
render_children: A deterministic render of the current tree rooted at body. The HTML of a node’s CHILDREN — what a view value renders as. The fragment that holds a rendered view is scaffolding, never markup, so it never appears in the output.
render_served: render as a browser must be sent it to build the same page: a control’s state is spelled the way HTML’s parser reads it back — a <select>’s value as its selected option, a <textarea>’s as its content — and content a parser would lose a leading newline of carries one more. What largo build puts in a pre-rendered page’s body.
replace_route: replaceRoute(path) — history.replaceState: record the navigation (replace), move the path.
request_load: assignLocation(url) — location.assign: ask the browser to load the document at url once the running script is done. Everything the page draws until then is drawn into the page that asked, which the browser keeps on screen until the new document replaces it; a second ask before then replaces the first.
request_reload: location.reload(): ask the browser to load the page again once the running script is done.
reset: Start a fresh DOM (call before each tier’s run so op-logs are comparable) — a fresh load of the page: its head is the shell’s again, whatever the last load merged into it.
response_body: responseBody(reqId) -> Text — the delivered body; "" while pending or failed.
response_error: responseError(reqId) -> Text — "" when none (pending or delivered OK); otherwise "timeout" | "abort" | "toolarge" | "network: <detail>".
response_header: responseHeader(reqId, name) -> Text — a delivered response header, case-insensitively; "" when absent.
response_status: responseStatus(reqId) -> Int — the delivered HTTP status; 0 while pending or on any transport failure (responseError then names the failure).
response_text: The responseText() sugar — the body of the request CURRENTLY being delivered (set by begin_fetch_resolve/fail_fetch, cleared by end_fetch_resolve).
restore: Put back a document a matching take returned.
retire_stream: A program starts: what an earlier program’s stream drew keeps its place in the document under ids this recorder mints, and the new program’s stream binds its own from the first.
route_ops: The recorded navigation op-log — the tw≡VM parity surface for the router.
route_path: routePath() -> Text — the current location pathname ("/" at boot).
route_query: routeQuery(name) -> Text — a query param by name ("" when absent).
rtc_add_ice
rtc_create_answer
rtc_create_offer
rtc_data_channel
rtc_peer_connection
rtc_send
rtc_set_local
rtc_set_remote
scroll_to: Scroll to "#card". — the element a browser would have brought into view.
scrolled_to: The element most recently scrolled to, or -1.
select_text: Select the text in "#draft". — the element whose text a browser would have selected.
selected: The element whose text was most recently selected, or -1.
set_attribute
set_attribute_value: Set an attribute from a VALUE rather than from a string — the ONE place the boolean-attribute rule lives, so no two tiers can render disabled differently.
set_checked
set_dropped_file: The file the drop being delivered carries: what eventFileName/eventFileSize/eventFileType/ eventFileBytes answer on a tier with no real transfer to read. The host that delivers a drop sets it first (page_host::Drive::DropFile), exactly as a browser’s drop event carries its file into the listener it reaches.
set_focus
set_head_html: Record the head HTML a page rendered, and merge it into the document’s head the way a browser host does (runtime.js’s mergeIntoHead): each element with an identity replaces every element of that identity already there, and joins the head at its end; one without is simply added. Called once, at mount.
set_html
set_stream
set_text
set_title: Set the title to … — document.title = …: the head’s first <title> holds the new text, or, when the head has none, a new <title> holding it joins the head.
set_value
stub_fetch: Arrange the answer to a request the page is expected to send. A later stub for the same (method, url) REPLACES an earlier one, so a test can set the scene and then change it.
stubbed_answer: The answer arranged for req, if a test arranged one.
submits_its_form: Whether activating node submits its form: a <button> of type submit (a button’s type when it names none), or an <input> of type submit or image.
tag_of: An element’s tag, lowercased — what the browser’s DEFAULT ACTION for a click turns on. A click on an <a href> follows the link and a submit on a <form> posts it, whether or not the page is listening; a runtime that only fires listeners answers neither.
take: Take the current document, leaving a fresh one in its place — reset, but the document it replaces comes back to the caller instead of being dropped. A nested run (a candidate page tier compared against the reference) takes the caller’s document before it paints its own, and restores it when it is done, so the caller’s own document survives the comparison.
take_load_request: Where the page asked the browser to go since the last look (request_load) — taken, so the host carries each request out once, by assign_location.
take_popped: Whether the browser stepped back through the history since the last look — the popstate the host then delivers to every route handler, as a browser raises it after history.back(). Taken, so each step is delivered once.
take_raised_events: The events the page’s own element commands raised (element_focus, element_blur) that the host has not delivered yet, (element, event) in the order they were raised — taken, so each is delivered once. Each element is found as the page stands NOW (it was recorded by its node_address, which survives the turn’s repaint), and an event whose element has left the page is dropped: nothing is listening there any more.
take_reload_request: Whether the page asked to be loaded again since the last look (request_reload) — taken, so the host carries each request out once.
text_content: The element’s text content: its own text plus every descendant’s, in document order.
title: the title — document.title: the text of the head’s first <title>, its ASCII whitespace stripped from both ends and collapsed to single spaces; "" when there is none.
to_own_server: Whether url goes to the page’s own server: a URL with no scheme and no host of its own. Decided on the URL as the page wrote it, identically in every host.
toggle_control
unlisten
validity: Why node is invalid (Validity) — every flag clear for an element with no constraints or barred from them. Refused only for a pattern= this tier cannot check (pattern_matches).
write_clipboard: Focus SEL. — the element the page’s keyboard input goes to. Copy "…" to the clipboard. — the text a browser would have put on the clipboard.

Module dom

Module dom Copy item path

Structs§

Enums§

Constants§

Functions§

Module dom