An Elixir implementation of the browser DOM. A document is a GenServer that owns a private ETS table of per-type node records; you manipulate it through immutable handles (%DOM.Node{server, node_id, type}) rather than live objects. It exists to test DOM interactions from Elixir — the tree, CSS selectors, events, and the WHATWG event loop — without a browser, with behavior verified against real Chromium and Firefox.

doc = DOM.new("<ul id='list'><li class='item'>a</li><li class='item'>b</li></ul>")

DOM.query_selector_all(doc, "#list > .item")   # [%DOM.Node{}, %DOM.Node{}]
item = DOM.query_selector(doc, "li.item")
DOM.Element.get_attribute(item, "class")       # "item"

DOM.Node.add_event_listener(item, "click", fn _event -> IO.puts("clicked") end)
DOM.Node.dispatch_event(item, DOM.Event.new("click", bubbles: true))

DOM.new/0,1 starts an unsupervised document and returns its handle — convenient for scripts, tests, and the REPL. For a long-lived document, use DOM.start_link/1 under a supervisor (it takes the same options; you mint the %DOM.Node{type: :document} handle from the returned server):

{:ok, server} = DOM.start_link(parse: DOM.HTML.tokens(html), document_id: id)
document = %DOM.Node{server: server, node_id: id, type: :document}

• Two struct layers. DOM.Node is the one user-facing handle — a struct carrying {server, node_id, type}, never a live object. Internally, six per-type DOM.NodeData.* records live in the server's ETS tuple space. Operations are type-guarded function clauses on the handle, never a protocol over the handle.
• Scoped dispatch. Generic node operations → DOM.Node; element-intrinsic ones (attributes, local_name) → DOM.Element; whole-document / query operations → DOM (which is also the GenServer). querySelector is scoped per ParentNode kind (DOM, Element, DocumentFragment, ShadowRoot).
• Nested-set tree. Child order and containment are encoded in binary extent keys in an :ordered_set index, so querySelectorAll, ancestor/containment tests, and compareDocumentPosition are index range scans, not tree walks.

• Tree & attributes — the everyday node/element surface, the attribute API (including namespaced attributes and live Attr nodes), cloneNode, cross-document adoption.
• CSS selectors — the full CSS Level-4 grammar parses and matches for everything derivable from the tree (type/id/class/attribute, all combinators, selector lists, :not/:is/:where/:has, the structural and *-of-type families, and the derivable UI/form-state pseudo-classes). The combinator engine is index-fused (no per-candidate re-query).
• Shadow DOM — shadow roots, maintained slot assignment, shadow-scoped CSS.
• Events & the event loop — full capture→target→bubble dispatch with shadow retargeting; microtasks, MutationObserver, slotchange, timers (setTimeout/setInterval); custom elements with synchronous reactions; AbortController/AbortSignal; focus and other interaction state.
• Ranges & traversal — Range, TreeWalker, NodeIterator.

Everything browser-observable is checked against a Chromium+Firefox oracle via Playwright, and every document verifies an internal consistency invariant on teardown.

Dominique aims to be a faithful, thorough implementation of the DOM core — the parts of the WHATWG DOM (and the DOM-facing slices of HTML and CSS Selectors) that are derivable from the tree, its attributes, and the event loop. That surface is broad and browser-verified: tree mutation and traversal, the full attribute model, CSS Level-4 selector matching, Shadow DOM, events with shadow retargeting, the microtask/task event loop, custom elements, ranges, and traversal objects all behave as Chromium and Firefox do.

What it does not implement is anything that requires a subsystem a pure DOM library doesn't have. These are deliberate omissions, not bugs:

• No layout or rendering. getBoundingClientRect, scrollIntoView, innerText (needs layout), and the rendering/presentation pseudo-classes (:modal, :fullscreen, :picture-in-picture, :popover-open) are out of scope.
• No navigation, history, or live URL. :visited, :target-by-navigation, :local-link, link-follows-on-click, and form submission are not modeled (the :target fragment and click activations that are derivable — checkbox/radio toggle, <summary>→<details>— are implemented).
• No media, autofill, or live-editing engine. HTMLMediaElement playback state (:playing/:paused/…), :autofill, :user-valid/:user-invalid, and the finer constraint-validation edges (step, minlength under live editing) are absent.
• No Window. Timers and queueMicrotask live on DOM as a documented convenience (the document server owns the event loop), but there is no Window, Location, or Selection/XPath subsystem.

Where a selector references something unmodelable (:playing, :visited, …) it matches nothing rather than erroring — mirroring how a browser querySelector returns no elements. And a few browser divergences are intentional design choices for a testing library (a listener/microtask that raises crashes the document server; handles go stale after cross-document adoption) — see the notes below.

Dominique does not put every DOM method on one module; each WHATWG interface maps to a scope module, and members are partitioned by which interface they belong to. This index maps the JS member to its Elixir equivalent. All functions take a %DOM.Node{} handle (or another handle struct) as their first argument.

Interaction state that a browser drives from real input (:hover/:active/:target, fragment navigation) is set through convenience functions on DOM (set_hover/1, set_active/1, set_fragment/2, set_indeterminate/2, …), since Dominique has no pointer/URL layer.

Node structs are immutable handles into a DOM GenServer, not live JavaScript objects. Like structs returned from a GenServer or database, a node handle may become stale after ownership changes.

Appending a node owned by another DOM transfers its entire subtree from the source DOM server to the destination DOM server. DOM.Node.append_child/2 returns a current handle owned by the destination server. Callers must use that returned handle after a cross-document transfer:

child = DOM.Node.append_child(destination_parent, child)

Handles retained from before the transfer still point at the source server and must be considered stale. This intentionally differs from JavaScript, where object identity remains live across document adoption.

DOM operations that defer work — slotchange, and later MutationObserver and custom-element reactions — enqueue microtasks that run at a checkpoint after the current operation, matching the WHATWG event loop. The checkpoint drains the queue inside the document server.

A microtask that raises crashes the document server. This is deliberate and differs from a browser, which reports the error and continues to the next microtask. WHATWG does not require isolation here, and Dominique's purpose is to test DOM interactions from Elixir — so a lambda that raises is a bug in your code, and letting it take down the document is a correct forcing function for correctness (and idiomatic OTP "let it crash"). Do not wrap microtask execution in a try to swallow this: a supervised document that silently survives a broken listener would hide exactly the defects this library exists to surface.

This package is NOT available on hex and can be installed by adding dominique to your list of dependencies in mix.exs:

def deps do
  [
    {:dominique, "~> 0.1.0", git: "https://github.com/ityonemo/dominique"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/dominique.