# @variance-authority/dom
> Extract a Variance Authority capture from a mounted element, under jsdom or a browser, with CSS applicability pruning.
Part of [Variance Authority](https://variance-authority.dev).
Point your coding agent at [`llms.txt`](https://variance-authority.dev/llms.txt).
Point this package at an element that is already mounted and it reads back two
things: a **capture** — the element's tree, its ARIA, and the CSS declarations
that actually apply to it, as serializable data — and a **render document**,
the same subtree as markup plus the frame it was mounted in and only the CSS
that applies to it, which another process can paint. It does not mount anything,
launch a browser, or take a screenshot; it reads a DOM you already have.
```bash
npm install --save-dev @variance-authority/dom
```
## Requirements
ESM only, Node 22 or newer. Nothing here imports a DOM implementation, so it
runs in whichever one your test already has:
| Environment | What you get |
| --- | --- |
| jsdom (`jsdom`, or Vitest's `jsdom` environment) | tree, ARIA, and declared CSS; a `::before` or `::after` whose rules give it content is in the tree with those rules and the words its declared `content` says; one whose `content` needs a counter, a quote, a `var()` or a `url()` is marked `unread` instead, because jsdom computes no generated content |
| a real browser (Chromium, via Playwright or a collector) | the above, plus computed styles, element geometry, and the computed style and text of every `::before` and `::after` that renders |
`@variance-authority/core` installs with it and defines the capture types. The
examples below also use `jsdom`:
```bash
npm install --save-dev jsdom
```
## Smallest working path
Save this as `capture.ts` and run it with `node capture.ts` (Node 24 and
newer) or `node --experimental-strip-types capture.ts` (Node 22):
```ts
import { JSDOM } from 'jsdom';
import { acquireDocument, collect } from '@variance-authority/dom';
const dom = new JSDOM(`
`);
const root = dom.window.document.getElementById('canvas')!;
// A subject is one named UI state you asked for and can ask for again — a
// story, a route, a fixture, a value. The id is yours and stays stable when
// the element that renders it changes.
const subject = { id: 'story:button--primary', kind: 'story' as const };
const viewport = {
width: 1280,
height: 720,
deviceScaleFactor: 1,
colorScheme: 'light' as const,
};
const fonts = ['Inter/400/normal/9f2c1ab4'];
const capture = collect(root, { subject, viewport, engine: 'jsdom@30.0.1', fonts });
const renderDocument = acquireDocument(root, { subject, viewport, fonts });
console.log(JSON.stringify(capture.root.children[0], null, 2));
console.log(renderDocument.css);
```
`collect` is synchronous and returns data ready for `normalize` in
`@variance-authority/core`. `acquireDocument` returns markup, frame context, and
applicable CSS, ready for a renderer in another package or on another machine —
a document acquired in a jsdom unit test can be painted by a pinned host
elsewhere.
### What you get
The first `console.log` — the captured button, one child of the captured root:
```json
{
"tag": "button",
"attributes": { "class": "btn" },
"aria": { "role": "button", "name": "Save", "state": {} },
"matchedRules": [
{
"sheet": "",
"selector": ".btn",
"specificity": [0, 1, 0],
"order": 4,
"declarations": [
{ "property": "color", "value": "var(--brand)", "important": false, "references": ["--brand"] },
{ "property": "padding-top", "value": "8px", "important": false }
]
}
],
"children": [
{ "tag": "#text", "attributes": {}, "matchedRules": [], "text": "Save", "children": [] }
]
}
```
Values leave as authored — generated ids intact, hashed class names intact,
shorthands unexpanded, cascade losers retained. `normalize` decides what to do
with them, so the rules that settle a comparison are versioned in one place.
Around that node the capture also includes `subject`, an `environment` block
(engine, viewport, fonts, resolved conditions, assets), `inheritedSeed` —
`{"--brand": "#0000ff"}` here, the custom properties in force at the root — and
`diagnostics`. The run above reports one:
```json
{
"severity": "warn",
"code": "portals-not-resolved",
"message": "no portal provider supplied; content rendered through createPortal is outside this capture, and a subject that portals will report unchanged when that content changes"
}
```
Diagnostics are never hashed. Omit `fonts` as well and you get a second one,
`unverified-fonts`: a page can see that `Inter` is in use and cannot read the
bytes it was handed, so a font substitution moves geometry with no change to
your code.
The second `console.log` — the CSS the render document ships:
```
[ ':root {--brand:#0000ff}\n.btn {color:var(--brand);padding-top:8px}' ]
```
Two of the four rules in that page are gone. `.sb-show-main` and `.u-mt-2`
cannot match anything in the subtree, so they are not in the payload and not in
the comparison.
## What applicability pruning removes
`collect` and `acquireDocument` both discard every stylesheet rule that cannot
apply to the mounted element, keeping only what could style it.
On a single-button subject mounted under Storybook chrome — a preview reset,
dead utility classes, CSS-in-JS accretion — pruning reduced 1,010 parsed rules
to the one that could style the subject. Without it, a baseline changes when a
stylesheet the subject never touched does.
An `@font-face` matches no element, so it is kept by what the subtree is set
in: the render document carries every face whose family appears in a computed
`font-family` inside the subject or in a box its frame generates, with its
`url()`s rewritten to resolve against
the page rather than the sheet that declared them, and `referencedAssets` adds
those files to the asset key. A face the subject is not set in is pruned like
any other rule. jsdom keeps a face's `font-family` and drops its `src`, so a
face read there cannot be carried; `acquireDocument` reports
`unreadable-font-face` for it, and the render paints the fallback.
## Images a page made itself
A `blob:` URL names memory in the page that minted it, and the renderer paints
in a page of its own. So `acquireDocument` reads every `blob:` URL the render
document would carry, in an attribute that names a file or in a `url()` of a
style, a `
