@variance-authority/unit-test 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# @variance-authority/unit-test
+
+## 0.1.0
+
+### Minor Changes
+
+- 5c34e6d: Say which input moved, not just which tag did
+  
+  `partingOf(baseline, candidate)` climbs from a set of deltas to the component
+  boundary that owns them and names the input that carried the decision:
+  `Cart chose differently — useState #0 moved`, with `Summary` reported as having
+  been handed a different `expanded` and hanging under that line as a
+  manifestation rather than as a second finding. `explainParting` renders that
+  as lines. Two runs of one page that differ in a `<p>` where the other has a
+  `<span>` previously produced a structural delta and nothing to say about it;
+  the tag is now the symptom and the hook cell is the report.
+  
+  `holdingOf` from `@variance-authority/react` supplies the evidence — props,
+  context values and hook cells as digests, per boundary, including
+  `useSyncExternalStore` snapshots so a store that moved outside React is
+  distinguished from a component that decided differently on its own. Values are
+  never carried, only digests, and a holding reaches no hash: `renderHash`,
+  `structureHash`, `styleHash`, band-exact component digests and
+  `componentInstances` are all unmoved by it, the same bargain `styleProvenance`
+  makes. `collect` in `@variance-authority/dom` takes `holdingOf` as a
+  caller-supplied reader, opt in separately from `wiringOf`, and `capture` in
+  `@variance-authority/unit-test` now accepts `provenanceOf`, `wiringOf` and
+  `holdingOf` so a unit test can read one.
+  
+  A boundary whose own input could not be read is reported as `unread` and never
+  as nondeterminism: `undetermined` is reserved for a component whose every input
+  was read and agreed. A wrapper that roots a component boundary no longer
+  collapses, because collapsing it discarded the holding — the cost is that a run
+  reading holdings keeps wrappers a run without them removes, which is why both
+  sides of a comparison must be read the same way.
+  
+  A component that ran no hooks is read as having run none, rather than as
+  unreadable. React writes `_debugHookTypes = null` on every fiber and fills it on
+  the first hook call, so the property's absence is the only silence — and
+  collapsing the two reported the one shape most worth calling nondeterministic, a
+  component with no props and no hooks that renders differently twice, as
+  something nothing could be said about.
+  
+  `PartedBoundary.moved` names the properties the owned deltas named — `color`,
+  `padding-top`, `width` — and `explainParting` spends them on the delta line.
+  That is the last joint of the chain the rungs climb: a hook cell moved, a prop
+  carried it down, and this is what the prop turned into on the page. A count and
+  a band stop one link short of what somebody chasing a visual regression is
+  trying to name.
+  
+  `Parting.slice` answers the question asked before which input moved: is this
+  worth opening. Three facts are read independently — did the component tree
+  move, did any input move, did the output move — and the combinations collapse
+  to six sentences. `refactor` is the one that pays for the rest: a component
+  tree that moved while the page did not is the receipt a refactor never gets,
+  since a pixel differ can say the screenshots match and nothing about what was
+  rewritten underneath. `flake` is `settled`'s opposite number and is refused on
+  silence — a run that read no boundary reports `unread`, never `flake`.
+  
+  `explainParting` leads with that line, and stops enumerating manifestations
+  past three: one input at a fork can put a boundary on every component beneath
+  it, and nine lines carrying one decision bury the one line worth reading.
+  
+  The whole layer is documented in `docs/parting.md`: the six slices, the seven
+  rungs, what a holding carries and what it deliberately does not.
+
+### Patch Changes
+
+- Updated dependencies [f800342]
+- Updated dependencies [e8fee66]
+- Updated dependencies [5c34e6d]
+  - @variance-authority/dom@0.1.0
+  - @variance-authority/core@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/unit-test
+
+> Capture a mounted DOM subject in a browserless Jest or Vitest process, then render and observe it later.
+
+Capture a mounted DOM subject in a browserless Jest or Vitest process, then let
+`variance run` render and observe that artifact in a later process. The package
+does not export `test`, `expect`, a reporter, or a browser.
+
+A subject is the thing captured for comparison: a mounted DOM subtree here, or
+— for `snapshotValue` below — a plain value. Each one is identified by a
+`SubjectRef`: an id plus a `kind` recording what produced it (`'story'`,
+`'route'`, `'fixture'`, or `'value'`), not what it looks like.
+
+It needs a live DOM and a directory it can write artifacts to. External resources
+arrive as immutable bytes: capture closes over the document by resolving every
+resource it references into bytes the artifact carries, and refuses to write a
+capture it cannot close this way.
+
+Browserless describes this half. The capture carries markup, CSS and resources —
+not pixels — so the later `variance run` opens a browser to paint it and refuses
+the run if it cannot.
+
+Install the package and the DOM environment used by the test runner:
+
+```bash
+npm install --save-dev @variance-authority/unit-test jsdom
+```
+
+The render half is a separate process and a separate install, in the job that
+paints:
+
+```bash
+npm install --save-dev @variance-authority/cli
+npx playwright install chromium
+```
+
+Vitest needs `// @vitest-environment jsdom` (or an equivalent project setting).
+Jest needs its normal `jsdom` test environment. This package does not configure
+either runner.
+
+## Capture in the existing unit test
+
+```ts
+// @vitest-environment jsdom
+import { test, expect } from 'vitest';
+import { capture, writeCapture } from '@variance-authority/unit-test';
+
+test('save button', async () => {
+  const button = document.createElement('button');
+  button.textContent = 'Save';
+  document.body.append(button);
+
+  const artifact = await capture(button, {
+    subject: 'button/save',
+    viewport: {
+      width: 320,
+      height: 200,
+      deviceScaleFactor: 1,
+      colorScheme: 'light',
+    },
+  });
+
+  await writeCapture('.variance/captures', artifact);
+  expect(button.textContent).toBe('Save');
+});
+```
+
+This process acquires markup, applicable CSS, semantic evidence, and resources.
+It does not produce a screenshot or visual verdict.
+
+`capture(root, options)` takes:
+
+| option | default | what it decides |
+|---|---|---|
+| `subject` | required | `'button/save'`, or a full `SubjectRef`. A bare string becomes `kind: 'fixture'` |
+| `viewport` | required | width, height, scale, colour scheme. Media queries are resolved against it here, in the unit process, because the later renderer never sees this DOM |
+| `engine` | the DOM's own user agent | what painted, as it lands in the identity |
+| `fonts` | none | the font stack this capture is asserted to have, as `family/weight/style/hash` |
+| `features` | none | environment facts folded into the capture and into media-condition resolution |
+| `sourceRoot` | none | the root component paths are made relative to, so `file:line` survives the move to another machine |
+| `resolveResource` | none | `(url) => bytes`. **Required the moment the subtree references anything**: a subtree with resources and no resolver throws at capture, naming every URL it would have had to guess at, and a resolver returning `null` for one of them throws naming that one |
+| `provenanceOf` | none | `(node) => owners`. Attaches the component chain that rendered each node, so a difference can be named by component rather than by path |
+| `wiringOf` | none | `(node) => wiring`. Attaches the framework wiring a node carries — hook count, keys, boundaries — as part of the compared identity |
+| `holdingOf` | none | `(node) => holding`. Attaches what each component boundary was handed and what it retained: props, contexts, and hook cells as digests. Evidence beside the snapshot, not part of any hash |
+
+`resolveResource` is the whole of the requirement above. A capture is rendered in
+another process — possibly on another machine, possibly hours later — so a
+document that carries digests and no bytes is a document that paints holes over
+there and cannot say why.
+
+`writeCapture(directory, artifact)` writes one versioned file per subject;
+`readCapture` and `captureFiles` are the read half, and `CAPTURE_SUFFIX` is what
+they match on.
+
+## Clear the directory once per run
+
+```ts
+// vitest.config.js  →  test: { globalSetup: ['variance/reset.mjs'] }
+import { resetCaptures } from '@variance-authority/unit-test';
+
+export async function setup() {
+  await resetCaptures('.variance/captures');
+}
+```
+
+A capture is addressed by its subject id, so two tests that both call themselves
+`button/save` address one file. `writeCapture` refuses to be the second write
+rather than overwriting, because the run that reads this directory afterwards
+would otherwise be missing a subject and say nothing about it.
+
+That refusal is only correct over a directory holding one run, and nothing in a
+test runner makes a directory hold one run by itself. `resetCaptures` is what
+does. Call it from a once-per-run hook — `globalSetup` in Vitest, a setup project
+in Playwright — never from a test file, where it would race the other test files
+and delete their captures. It removes capture files and leaves everything else in
+the directory alone, and a directory that does not exist yet is not an error.
+
+Without it the second run of an unchanged suite fails, and the failure names a
+subject id collision to somebody who has only ever had one subject.
+
+## Snapshot a value
+
+Not every public surface is a page. An API response, a generated OpenAPI
+document, a GraphQL schema, a route table and a build manifest are all things a
+change can break, and none of them needs a DOM.
+
+```ts
+import { test } from 'vitest';
+import { snapshotValue } from '@variance-authority/unit-test';
+
+test('the health endpoint', async () => {
+  const response = await fetch('http://localhost:3000/health');
+
+  await snapshotValue(await response.json(), {
+    subject: 'api/health',
+    directory: '.variance/captures',
+    drop: ['/uptimeSeconds'],
+  });
+});
+```
+
+`snapshotValue(value, options)` takes:
+
+| option | default | what it decides |
+|---|---|---|
+| `subject` | required | `'api/health'`, or a full `SubjectRef`. A bare string becomes `kind: 'value'` |
+| `directory` | required | where the capture is written; one fresh directory per run, as above |
+| `dialect` | `'json'` | how the text is read later. A reader for a dialect it does not know still compares the value |
+| `drop` | none | JSON Pointers whose value is volatile. Recorded as present, never compared |
+| `replace` | none | JSON Pointers whose value becomes a token you choose, so the shape stays readable |
+| `arrayKey` | none | for an array of records, the member that identifies a row: `{ '/rows': 'id' }` |
+| `generator` | none | what emitted the value, when something did |
+
+Set `arrayKey` for any array of records. Without it, an array is compared by
+index, so a row inserted at the top reports every row after it as changed
+instead of reporting the one insertion.
+
+The value is serialized here, in the unit process, into canonical text: keys
+sorted, numbers written portably, `undefined` members omitted. That text is what
+is addressed and what a later run compares, so two processes that built the same
+response in a different order produce the same record.
+
+Like `capture`, `snapshotValue` writes and does not compare — the baseline is
+not in this process, and the verdict belongs to `variance run`. It throws only
+on a value that cannot be one: a function, a `Date`, a `bigint` or a non-finite
+number, naming the JSON Pointer where it was found. Dropping it silently would
+put a key in the baseline that a later run reads as removed.
+
+`captureCollector` accepts document captures for the normal `variance run` path.
+If its directory contains a value capture, collection
+reports that the material is a value capture while the run compares rendered
+documents; it does not turn that refusal into an unchanged result. The
+value-writing API is therefore usable independently, but the CLI/raster path
+does not compare value artifacts.
+
+## Render later
+
+Point the normal CLI collector setting at a module exporting the artifact
+collector:
+
+```ts
+import { captureCollector } from '@variance-authority/unit-test';
+
+export default captureCollector({ directory: '.variance/captures' });
+```
+
+`directory` is the only option, and duplicate subject ids inside it are an error
+rather than a last-write-wins: two tests writing `button/save` is a name
+collision, and picking one silently makes half the suite invisible.
+
+Name that module as the collector, and set `profile` to the observation tier
+the capture was taken in — `"jsdom"` here, or `"chromium"` for a
+browser-based collector:
+
+```json
+{
+  "project": "design-system",
+  "profile": "jsdom",
+  "viewport": { "width": 320, "height": 200 },
+  "retention": "durable",
+  "subjects": { "kind": "collector", "collector": "variance/collector.mjs" },
+  "baselines": { "kind": "directory", "root": "baselines" },
+  "report": "out/report.json"
+}
+```
+
+`retention` is `"durable"` (compare against a stored baseline — `baselines` is
+then required) or `"ephemeral"` (nothing is stored, and `baselines` must be
+absent). `subjects.kind` says where the run gets its subject list:
+`"collector"` (a module like the one above), `"storybook"`, or `"list"`.
+`baselines.kind` says where the stored baseline lives: `"directory"`, `"lfs"`,
+or `"remote"`.
+
+```bash
+npx variance run
+```
+
+`variance run` is the command `@variance-authority/cli` installs as `variance`.
+It reads the document captures this package wrote, renders each one with the
+configured renderer, compares it against the configured baseline, and writes
+the report.
+
+`profile: "jsdom"` says what observed the subject, not what paints it: the
+capture has no layout engine behind it, so every changed region in the report
+is reported unattributed rather than joined to a guessed node — the render
+itself is still Chromium.
+
+A run that finds nothing to review exits 0. The first run against baselines
+that don't exist yet has nothing to compare against, so it exits 1 for review
+rather than a pass. Use a fresh capture directory per run; the runner still
+owns test selection and retry lifecycle.

package/dist/archive.d.ts

@@ -0,0 +1,40 @@
+import type { CaptureArtifact } from '@variance-authority/core';
+export declare const CAPTURE_SUFFIX = ".va-capture.json";
+/**
+ * Atomically write one capture, and refuse to be the second write for a subject.
+ *
+ * The filename is the subject id, so two tests capturing `button/save` address
+ * one file. `rename` would have taken the second one — silently, successfully,
+ * and with half the suite then invisible to the run that reads this directory.
+ * `link` is the same atomic publish with the opposite answer to an occupied
+ * name: it fails with `EEXIST` rather than overwriting, so a collision costs one
+ * failing test instead of a report that is quietly missing a subject.
+ *
+ * *What it costs.* A capture directory reused across runs fails on the second
+ * run, and the second run is the ordinary one: edit a component, re-run the
+ * tests, compare. So the run boundary this guard assumes has to be given to the
+ * writer rather than described to them — {@link resetCaptures}, once, from
+ * wherever the runner starts a run. Without it the guard is right about the
+ * directory and wrong about the cause, and it says so to somebody who changed
+ * one colour and has no second subject anywhere.
+ */
+export declare function writeCapture(directory: string, artifact: CaptureArtifact): Promise<string>;
+/**
+ * Empty a capture directory, once, at the start of a run.
+ *
+ * The other half of {@link writeCapture}'s refusal to overwrite. That guard is
+ * only correct over a directory that holds one run, and nothing in a test runner
+ * makes a directory hold one run by itself — so this is the boundary, called
+ * from wherever the runner has a once-per-run hook (`globalSetup` in Vitest, a
+ * global setup project in Playwright). Called from a test file it would race the
+ * other test files and delete their captures.
+ *
+ * It removes capture files and nothing else. The directory is named by the
+ * adopter and may be one they keep other things in; a helper that took
+ * `rm -rf` to a configured path would eventually take it to the wrong one.
+ * A directory that is not there yet is not an error — that is the first run.
+ */
+export declare function resetCaptures(directory: string): Promise<void>;
+export declare function readCapture(path: string): Promise<CaptureArtifact>;
+export declare function captureFiles(directory: string): Promise<readonly string[]>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.js

@@ -0,0 +1,96 @@
+import { link, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { captureArtifactFrom } from './shape.js';
+export const CAPTURE_SUFFIX = '.va-capture.json';
+/**
+ * Atomically write one capture, and refuse to be the second write for a subject.
+ *
+ * The filename is the subject id, so two tests capturing `button/save` address
+ * one file. `rename` would have taken the second one — silently, successfully,
+ * and with half the suite then invisible to the run that reads this directory.
+ * `link` is the same atomic publish with the opposite answer to an occupied
+ * name: it fails with `EEXIST` rather than overwriting, so a collision costs one
+ * failing test instead of a report that is quietly missing a subject.
+ *
+ * *What it costs.* A capture directory reused across runs fails on the second
+ * run, and the second run is the ordinary one: edit a component, re-run the
+ * tests, compare. So the run boundary this guard assumes has to be given to the
+ * writer rather than described to them — {@link resetCaptures}, once, from
+ * wherever the runner starts a run. Without it the guard is right about the
+ * directory and wrong about the cause, and it says so to somebody who changed
+ * one colour and has no second subject anywhere.
+ */
+export async function writeCapture(directory, artifact) {
+    await mkdir(directory, { recursive: true });
+    const path = join(directory, `${encodeURIComponent(artifact.subject.id)}${CAPTURE_SUFFIX}`);
+    const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    try {
+        await link(temporary, path);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        throw new Error(`${artifact.subject.id} already has a capture at ${path}. Two subjects with one id ` +
+            'is a name collision, and taking the later write makes the earlier subject invisible ' +
+            'to the run. Give them distinct ids — or, if this is a second run over the same ' +
+            'directory, call `resetCaptures` once when the run starts.', { cause: error });
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return path;
+}
+/**
+ * Empty a capture directory, once, at the start of a run.
+ *
+ * The other half of {@link writeCapture}'s refusal to overwrite. That guard is
+ * only correct over a directory that holds one run, and nothing in a test runner
+ * makes a directory hold one run by itself — so this is the boundary, called
+ * from wherever the runner has a once-per-run hook (`globalSetup` in Vitest, a
+ * global setup project in Playwright). Called from a test file it would race the
+ * other test files and delete their captures.
+ *
+ * It removes capture files and nothing else. The directory is named by the
+ * adopter and may be one they keep other things in; a helper that took
+ * `rm -rf` to a configured path would eventually take it to the wrong one.
+ * A directory that is not there yet is not an error — that is the first run.
+ */
+export async function resetCaptures(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    await Promise.all(entries
+        .filter((entry) => entry.endsWith(CAPTURE_SUFFIX))
+        .map((entry) => rm(join(directory, entry), { force: true })));
+}
+export async function readCapture(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`cannot read capture artifact ${path}`, { cause: error });
+    }
+    return captureArtifactFrom(value, path);
+}
+export async function captureFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        throw new Error(`cannot read capture directory ${directory}`, { cause: error });
+    }
+    return entries
+        .filter((entry) => entry.endsWith(CAPTURE_SUFFIX))
+        .sort()
+        .map((entry) => join(directory, entry));
+}
+//# sourceMappingURL=archive.js.map

package/dist/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"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","sourcesContent":["import { link, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport type { CaptureArtifact } from '@variance-authority/core';\nimport { captureArtifactFrom } from './shape.js';\n\nexport const CAPTURE_SUFFIX = '.va-capture.json';\n\n/**\n * Atomically write one capture, and refuse to be the second write for a subject.\n *\n * The filename is the subject id, so two tests capturing `button/save` address\n * one file. `rename` would have taken the second one — silently, successfully,\n * and with half the suite then invisible to the run that reads this directory.\n * `link` is the same atomic publish with the opposite answer to an occupied\n * name: it fails with `EEXIST` rather than overwriting, so a collision costs one\n * failing test instead of a report that is quietly missing a subject.\n *\n * *What it costs.* A capture directory reused across runs fails on the second\n * run, and the second run is the ordinary one: edit a component, re-run the\n * tests, compare. So the run boundary this guard assumes has to be given to the\n * writer rather than described to them — {@link resetCaptures}, once, from\n * wherever the runner starts a run. Without it the guard is right about the\n * directory and wrong about the cause, and it says so to somebody who changed\n * one colour and has no second subject anywhere.\n */\nexport async function writeCapture(\n  directory: string,\n  artifact: CaptureArtifact,\n): Promise<string> {\n  await mkdir(directory, { recursive: true });\n  const path = join(directory, `${encodeURIComponent(artifact.subject.id)}${CAPTURE_SUFFIX}`);\n  const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;\n  await writeFile(temporary, `${JSON.stringify(artifact, null, 2)}\\n`, 'utf8');\n  try {\n    await link(temporary, path);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;\n    throw new Error(\n      `${artifact.subject.id} already has a capture at ${path}. Two subjects with one id ` +\n        'is a name collision, and taking the later write makes the earlier subject invisible ' +\n        'to the run. Give them distinct ids — or, if this is a second run over the same ' +\n        'directory, call `resetCaptures` once when the run starts.',\n      { cause: error },\n    );\n  } finally {\n    await rm(temporary, { force: true });\n  }\n  return path;\n}\n\n/**\n * Empty a capture directory, once, at the start of a run.\n *\n * The other half of {@link writeCapture}'s refusal to overwrite. That guard is\n * only correct over a directory that holds one run, and nothing in a test runner\n * makes a directory hold one run by itself — so this is the boundary, called\n * from wherever the runner has a once-per-run hook (`globalSetup` in Vitest, a\n * global setup project in Playwright). Called from a test file it would race the\n * other test files and delete their captures.\n *\n * It removes capture files and nothing else. The directory is named by the\n * adopter and may be one they keep other things in; a helper that took\n * `rm -rf` to a configured path would eventually take it to the wrong one.\n * A directory that is not there yet is not an error — that is the first run.\n */\nexport async function resetCaptures(directory: string): Promise<void> {\n  let entries: readonly string[];\n  try {\n    entries = await readdir(directory);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;\n    throw error;\n  }\n  await Promise.all(\n    entries\n      .filter((entry) => entry.endsWith(CAPTURE_SUFFIX))\n      .map((entry) => rm(join(directory, entry), { force: true })),\n  );\n}\n\nexport async function readCapture(path: string): Promise<CaptureArtifact> {\n  let value: unknown;\n  try {\n    value = JSON.parse(await readFile(path, 'utf8'));\n  } catch (error) {\n    throw new Error(`cannot read capture artifact ${path}`, { cause: error });\n  }\n\n  return captureArtifactFrom(value, path);\n}\n\nexport async function captureFiles(directory: string): Promise<readonly string[]> {\n  let entries: readonly string[];\n  try {\n    entries = await readdir(directory);\n  } catch (error) {\n    throw new Error(`cannot read capture directory ${directory}`, { cause: error });\n  }\n  return entries\n    .filter((entry) => entry.endsWith(CAPTURE_SUFFIX))\n    .sort()\n    .map((entry) => join(directory, entry));\n}\n"]}

package/dist/capture.d.ts

@@ -0,0 +1,33 @@
+import { type CaptureArtifact, type Holding, type Provenance, type Wiring, type SubjectRef, type Viewport } from '@variance-authority/core';
+export interface ResolvedResource {
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+}
+export interface UnitCaptureOptions {
+    readonly subject: string | SubjectRef;
+    readonly viewport: Viewport;
+    readonly engine?: string;
+    readonly fonts?: readonly string[];
+    readonly features?: Readonly<Record<string, string>>;
+    readonly sourceRoot?: string;
+    readonly resolveResource?: (url: string) => Promise<ResolvedResource | null>;
+    /**
+     * Framework readers, passed straight through to `collect`.
+     *
+     * Three callbacks rather than one adapter object, mirroring `CollectOptions`
+     * exactly, because they are opted into separately and cost differently: an
+     * owner chain is a name, and a holding is a digest of every hook cell and
+     * every prop in the tree. A caller reading a subject twice to ask whether it
+     * is stable wants all three; a caller archiving a fixture for a pixel diff
+     * wants none, and neither should be inferred from the other.
+     *
+     * Absent by default. This package does not import React, and a capture taken
+     * without them carries no component names — not empty ones.
+     */
+    readonly provenanceOf?: (element: Element) => Provenance | undefined;
+    readonly wiringOf?: (element: Element) => Wiring | undefined;
+    readonly holdingOf?: (element: Element) => Holding | undefined;
+}
+/** Capture a mounted DOM tree without importing or launching a browser. */
+export declare function capture(root: Element, options: UnitCaptureOptions): Promise<CaptureArtifact>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/capture.js

@@ -0,0 +1,84 @@
+import { digestBytes, normalize, } from '@variance-authority/core';
+import { acquireDocument, collect, conditionsFor, indexStyleSheets, referencedAssets, } from '@variance-authority/dom';
+/** Capture a mounted DOM tree without importing or launching a browser. */
+export async function capture(root, options) {
+    const subject = typeof options.subject === 'string'
+        ? { id: options.subject, kind: 'fixture' }
+        : options.subject;
+    const owner = root.ownerDocument;
+    const index = indexStyleSheets(owner, conditionsFor(owner, options.viewport, options.features));
+    const acquireOptions = {
+        subject,
+        viewport: options.viewport,
+        ...(options.fonts === undefined ? {} : { fonts: options.fonts }),
+        ...(options.features === undefined ? {} : { features: options.features }),
+        index,
+    };
+    const acquired = acquireDocument(root, acquireOptions);
+    const urls = resourceUrls(root, acquired);
+    const resources = await closeResources(urls, options.resolveResource);
+    const assets = Object.fromEntries(Object.entries(resources).map(([url, resource]) => [url, resource.digest]));
+    const raw = collect(root, {
+        ...acquireOptions,
+        engine: options.engine ?? engineOf(owner),
+        assets,
+        ...(options.provenanceOf === undefined ? {} : { provenanceOf: options.provenanceOf }),
+        ...(options.wiringOf === undefined ? {} : { wiringOf: options.wiringOf }),
+        ...(options.holdingOf === undefined ? {} : { holdingOf: options.holdingOf }),
+    });
+    const document = {
+        ...acquired,
+        assets,
+        baseUrl: owner.baseURI,
+        resources,
+    };
+    return {
+        artifactVersion: 1,
+        subject,
+        material: { kind: 'document', document },
+        snapshot: normalize(raw, options.sourceRoot === undefined ? {} : { sourceRoot: options.sourceRoot }),
+    };
+}
+function engineOf(document) {
+    return document.defaultView?.navigator.userAgent ?? 'dom/unknown';
+}
+function resourceUrls(root, document) {
+    const found = new Set(referencedAssets(root));
+    const base = root.ownerDocument.baseURI;
+    const text = [document.html, ...document.css].join('\n');
+    for (const match of text.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^\s)]*))\s*\)/g)) {
+        addReference(found, match[1] ?? match[2] ?? match[3] ?? '', base);
+    }
+    if (/\bblob:/i.test(text)) {
+        throw new Error(`capture ${document.subject.id} is not portable: blob URLs have process-local bytes`);
+    }
+    return [...found].sort();
+}
+function addReference(found, value, base) {
+    if (value === '' || /^(data|about|javascript):/i.test(value) || value.startsWith('#'))
+        return;
+    try {
+        found.add(new URL(value, base).toString());
+    }
+    catch {
+        throw new Error(`capture contains an unresolved resource reference: ${value}`);
+    }
+}
+async function closeResources(urls, resolve) {
+    if (urls.length > 0 && resolve === undefined) {
+        throw new Error(`capture is not resource-closed; supply resolveResource for: ${urls.join(', ')}`);
+    }
+    const closed = {};
+    for (const url of urls) {
+        const response = await resolve(url);
+        if (response === null)
+            throw new Error(`capture could not archive resource: ${url}`);
+        closed[url] = {
+            contentType: response.contentType,
+            bytes: Buffer.from(response.bytes).toString('base64'),
+            digest: digestBytes(response.bytes),
+        };
+    }
+    return closed;
+}
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  digestBytes,\n  normalize,\n  type CaptureArtifact,\n  type Holding,\n  type Provenance,\n  type Wiring,\n  type RenderDocument,\n  type RenderResource,\n  type SubjectRef,\n  type Viewport,\n} from '@variance-authority/core';\nimport {\n  acquireDocument,\n  collect,\n  conditionsFor,\n  indexStyleSheets,\n  referencedAssets,\n} from '@variance-authority/dom';\n\nexport interface ResolvedResource {\n  readonly contentType: string;\n  readonly bytes: Uint8Array;\n}\n\nexport interface UnitCaptureOptions {\n  readonly subject: string | SubjectRef;\n  readonly viewport: Viewport;\n  readonly engine?: string;\n  readonly fonts?: readonly string[];\n  readonly features?: Readonly<Record<string, string>>;\n  readonly sourceRoot?: string;\n  readonly resolveResource?: (url: string) => Promise<ResolvedResource | null>;\n\n  /**\n   * Framework readers, passed straight through to `collect`.\n   *\n   * Three callbacks rather than one adapter object, mirroring `CollectOptions`\n   * exactly, because they are opted into separately and cost differently: an\n   * owner chain is a name, and a holding is a digest of every hook cell and\n   * every prop in the tree. A caller reading a subject twice to ask whether it\n   * is stable wants all three; a caller archiving a fixture for a pixel diff\n   * wants none, and neither should be inferred from the other.\n   *\n   * Absent by default. This package does not import React, and a capture taken\n   * without them carries no component names — not empty ones.\n   */\n  readonly provenanceOf?: (element: Element) => Provenance | undefined;\n  readonly wiringOf?: (element: Element) => Wiring | undefined;\n  readonly holdingOf?: (element: Element) => Holding | undefined;\n}\n\n/** Capture a mounted DOM tree without importing or launching a browser. */\nexport async function capture(\n  root: Element,\n  options: UnitCaptureOptions,\n): Promise<CaptureArtifact> {\n  const subject: SubjectRef =\n    typeof options.subject === 'string'\n      ? { id: options.subject, kind: 'fixture' }\n      : options.subject;\n  const owner = root.ownerDocument;\n  const index = indexStyleSheets(\n    owner,\n    conditionsFor(owner, options.viewport, options.features),\n  );\n  const acquireOptions = {\n    subject,\n    viewport: options.viewport,\n    ...(options.fonts === undefined ? {} : { fonts: options.fonts }),\n    ...(options.features === undefined ? {} : { features: options.features }),\n    index,\n  };\n  const acquired = acquireDocument(root, acquireOptions);\n  const urls = resourceUrls(root, acquired);\n  const resources = await closeResources(urls, options.resolveResource);\n  const assets = Object.fromEntries(\n    Object.entries(resources).map(([url, resource]) => [url, resource.digest]),\n  );\n  const raw = collect(root, {\n    ...acquireOptions,\n    engine: options.engine ?? engineOf(owner),\n    assets,\n    ...(options.provenanceOf === undefined ? {} : { provenanceOf: options.provenanceOf }),\n    ...(options.wiringOf === undefined ? {} : { wiringOf: options.wiringOf }),\n    ...(options.holdingOf === undefined ? {} : { holdingOf: options.holdingOf }),\n  });\n\n  const document: RenderDocument = {\n    ...acquired,\n    assets,\n    baseUrl: owner.baseURI,\n    resources,\n  };\n\n  return {\n    artifactVersion: 1,\n    subject,\n    material: { kind: 'document', document },\n    snapshot: normalize(\n      raw,\n      options.sourceRoot === undefined ? {} : { sourceRoot: options.sourceRoot },\n    ),\n  };\n}\n\nfunction engineOf(document: Document): string {\n  return document.defaultView?.navigator.userAgent ?? 'dom/unknown';\n}\n\nfunction resourceUrls(root: Element, document: RenderDocument): readonly string[] {\n  const found = new Set(referencedAssets(root));\n  const base = root.ownerDocument.baseURI;\n  const text = [document.html, ...document.css].join('\\n');\n\n  for (const match of text.matchAll(/url\\(\\s*(?:\"([^\"]*)\"|'([^']*)'|([^\\s)]*))\\s*\\)/g)) {\n    addReference(found, match[1] ?? match[2] ?? match[3] ?? '', base);\n  }\n\n  if (/\\bblob:/i.test(text)) {\n    throw new Error(\n      `capture ${document.subject.id} is not portable: blob URLs have process-local bytes`,\n    );\n  }\n\n  return [...found].sort();\n}\n\nfunction addReference(found: Set<string>, value: string, base: string): void {\n  if (value === '' || /^(data|about|javascript):/i.test(value) || value.startsWith('#')) return;\n  try {\n    found.add(new URL(value, base).toString());\n  } catch {\n    throw new Error(`capture contains an unresolved resource reference: ${value}`);\n  }\n}\n\nasync function closeResources(\n  urls: readonly string[],\n  resolve: UnitCaptureOptions['resolveResource'],\n): Promise<Readonly<Record<string, RenderResource>>> {\n  if (urls.length > 0 && resolve === undefined) {\n    throw new Error(\n      `capture is not resource-closed; supply resolveResource for: ${urls.join(', ')}`,\n    );\n  }\n\n  const closed: Record<string, RenderResource> = {};\n  for (const url of urls) {\n    const response = await resolve!(url);\n    if (response === null) throw new Error(`capture could not archive resource: ${url}`);\n    closed[url] = {\n      contentType: response.contentType,\n      bytes: Buffer.from(response.bytes).toString('base64'),\n      digest: digestBytes(response.bytes),\n    };\n  }\n  return closed;\n}\n"]}

package/dist/collector.d.ts

@@ -0,0 +1,7 @@
+import type { SubjectSource } from './contract.js';
+export interface CaptureCollectorOptions {
+    readonly directory: string;
+}
+/** Read browserless unit-test captures in a later `variance run` process. */
+export declare function captureCollector(options: CaptureCollectorOptions): SubjectSource;
+//# sourceMappingURL=collector.d.ts.map