dom.* API reference

dom is the sandbox API for reading and changing the current page. Every asynchronous call sends an operation to the page agent. The page agent owns the real document, resolves handles, applies limits, checks writes, and returns JSON data. No dom.* call needs a manifest capability.

Security model#

Root handles#

dom.document, dom.body, and dom.head remain valid for the sandbox lifetime. dom.window supports only on and off.

Queries#

Invalid selectors reject with invalid selector.

Creating page content#

dom.create#

const handle = await dom.create(tag, {
  text,
  html,
  attrs,
  classes,
  style,
  children,
});

Creates a detached element and returns its Handle. children accepts strings and nested { tag, ...options } objects. The page agent validates the complete tree before creating any node. A tree may contain at most 1000 nodes and may be at most 32 levels deep. Text and HTML fields may contain at most 256 KB each.

The returned tree is stamped with data-rmx-owner. Refused tags, attributes, styles, or URLs reject the whole call.

dom.clone#

const handle = await dom.clone(selector, { text, strip, keepIds });

Equivalent to dom.query(selector) followed by handle.clone(options). Returns null when the selector has no match.

The clone is detached and deep. Event listeners are not copied. strip removes matches before text edits the clone. A string text replaces all content; a { selector: text } map updates the first match for each selector. keepIds preserves id and for, which are removed by default. The page agent sanitizes the clone with the same rules as dom.create and logs removed content.

dom.addStyle#

const style = await dom.addStyle(css);

Adds an owned <style> element to the page head and returns its handle. CSS may contain at most 256 KB. The page agent rejects CSS that can load a resource or execute legacy behavior. See CSS.

Page facts and scrolling#

behavior accepts auto, smooth, or instant. The runtime converts instant to auto before sending the call.

Mutation observation#

dom.observe#

const stop = dom.observe(callback, {
  root,
  childList,
  subtree,
  attributes,
  characterData,
});

Registers a page-agent observer and returns a synchronous unsubscribe function. root defaults to dom.document. All four mutation flags default to true. The callback receives { deliveries }, where deliveries is the number of raw MutationObserver deliveries folded into the notice. It does not receive mutation records.

The first notice after a quiet period arrives immediately. Later deliveries within 100 ms are coalesced. Each observer accepts at most 40 raw deliveries per second. A fast refill caused by callback writes is held to one trailing notice per second and logged as a feedback loop. Sustained page-driven changes remain coalesced and produce one informational log entry.

Handle properties#

The page agent keeps at most 20000 handles per sandbox. Call release() when a large batch is no longer needed. The sandbox permits at most 5000 unanswered DOM calls.

Handle queries and traversal#

Handle reads#

Handle content and attributes#

Handle placement and actions#

Events#

handle.on#

const stop = handle.on(type, callback, {
  selector,
  preventDefault,
  stopPropagation,
  once,
  capture,
  passive,
});

Registers an event listener and returns a synchronous unsubscribe function. selector delegates from the current handle and makes the matched descendant the event's target.

The callback receives a plain object with type, target, currentTarget, key, code, modifier keys, button, clientX, clientY, form value and checked, and defaultPrevented. target and currentTarget are handles. Fields that do not apply to the event are omitted. Events from password fields omit key and code and replace value with an empty string.

Callbacks run in the sandbox after a message round trip. To cancel the page event synchronously, set preventDefault or stopPropagation in the registration options. passive: true overrides preventDefault.

If the page removes a listened node, the page agent removes its listeners and marks the handle stale. Every later call except isConnected() and release() rejects. A listener registered during rmx.keep(...).apply() causes that keep to reapply once so it can bind to the replacement node.

dom.window.on and dom.window.off#

const stop = dom.window.on(type, callback, options);
dom.window.off(type, callback);

Supports scroll, resize, keydown, keyup, focus, blur, and visibilitychange. Re-registering the same type and callback returns the existing subscription. The sandbox's window.addEventListener and window.removeEventListener facades route to these methods.

Write security#

Ownership marks#

The page agent stamps elements created, cloned, or inserted through sanitized HTML with data-rmx-owner. Remixlet code cannot set or remove that attribute.

Owned elements accept ordinary attributes and classes. Page-owned elements accept only this remixlet's marks, written with the id slot:

The double hyphen is the slot for the remixlet id. The page agent fills it in every name, selector, attribute value, markup string, and stylesheet the remixlet hands it, the extension fills it in style.css on injection, and reads (info(), html(), class lists) show the slot form again, so a name is spelled one way everywhere. Names that spell the id in full (data-${rmx.prefix}-<name>, ${rmx.prefix}-<name>) still pass for code written before the slot.

Content writes, values, inline styles, placement, removal, and approved clicks do not use the mark rule.

Tags and attributes#

Creation rejects unlisted tags and tags that can load, execute, submit, or embed content. This includes form, iframe, frame, object, embed, script, base, meta, link, style, template, media source tags, math, and noscript.

Attribute writes reject event handlers and attributes that can load, execute, submit, or redirect. This includes on*, action, srcdoc, srcset, formaction, ping, poster, target, http-equiv, style, is, form, rel, and download. href on links and src on images use the URL policy instead.

setHTML, create({ html }), and clone parse markup in an inert document. The sanitizer removes comments, refused attributes, and refused tags with their subtrees before importing the result into the page.

URLs#

The page agent resolves link href and image src values to absolute URLs. It permits:

• the current page origin;
• a host covered by the remixlet's matches;
• a host covered by an approved fetch: capability;
• an exact URL the page already loads;
• data:image URLs.

It rejects javascript:, blob:, and hosts granted only through network:observe:. Stored attributes contain the resolved absolute URL.

click() applies the same rule to the element, an enclosing link, the control activated through a label, and a submitted form or formaction target.

CSS#

Inline styles and dom.addStyle reject CSS containing url(, image-set(, @import, src(, expression(, or behavior: in any spelling accepted by CSS.

Sandbox browser facades#

Remixlet files have no live browser globals. The sandbox provides read-only facades:

Writes to these facades reject. location.assign, location.replace, and location.reload reject. Page-shaped globals such as document, fetch, XMLHttpRequest, MutationObserver, localStorage, WebSocket, Image, Worker, alert, and open are blocked with an error that names the corresponding sandbox API where one exists.

Limits#

dom.* shares the rmx.* bridge compatibility version. The extension does not run a remixlet whose stored version falls outside its supported range. See rmx.* API compatibility.