@describe-me/vitest 0.4.0 → 0.5.0-next.1

package/dist/mirror-react-act-environment.js

@@ -0,0 +1,27 @@
+import { afterAll, beforeAll } from 'vitest';
+/** Testing Library's own test: its auto-cleanup block runs unless the variable is set. */
+function testingLibrarySkippedItsSetup() {
+    return typeof process !== 'undefined' && Boolean(process.env?.RTL_SKIP_AUTO_CLEANUP);
+}
+/**
+ * Set React's `IS_REACT_ACT_ENVIRONMENT` flag for each test file, the way
+ * Testing Library does. `RTL_SKIP_AUTO_CLEANUP` skips its whole setup block,
+ * the flag included, which silences React's act warnings. The flag is set
+ * only under Testing Library's own condition (Vitest globals), so the
+ * warnings match a run without describe-me.
+ */
+export function mirrorReactActEnvironment() {
+    const host = globalThis;
+    const hasGlobalHooks = typeof host.beforeAll === 'function' && typeof host.afterAll === 'function';
+    if (!testingLibrarySkippedItsSetup() || !hasGlobalHooks) {
+        return;
+    }
+    let previous;
+    beforeAll(() => {
+        previous = host.IS_REACT_ACT_ENVIRONMENT;
+        host.IS_REACT_ACT_ENVIRONMENT = true;
+    });
+    afterAll(() => {
+        host.IS_REACT_ACT_ENVIRONMENT = previous;
+    });
+}

package/dist/patch-testing-library-user-event.d.ts

@@ -3,6 +3,7 @@
  * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
  * instance from `userEvent.setup()`, and the first delegates to the second,
  * so both are patched and `recordAction`'s depth guard keeps one gesture to
- * one frame. Safe to call more than once.
+ * one frame. When the optional peer is not installed, there is nothing to
+ * patch. Safe to call more than once.
  */
-export declare function patchTestingLibraryUserEvent(): void;
+export declare function patchTestingLibraryUserEvent(): Promise<void>;

package/dist/patch-testing-library-user-event.js

@@ -1,6 +1,5 @@
-import userEvent from '@testing-library/user-event';
+import { elementLabel } from '@describe-me/core';
 import { describeArg } from './describe-arg.js';
-import { elementLabel } from './element-label.js';
 import { recordAction } from './record-action.js';
 /** Every interaction of user-event 14 that can change what the page shows. */
 const METHODS = [
@@ -42,9 +41,17 @@ function patchMethods(target) {
  * It comes in two shapes, the direct API (`userEvent.click(el)`) and an
  * instance from `userEvent.setup()`, and the first delegates to the second,
  * so both are patched and `recordAction`'s depth guard keeps one gesture to
- * one frame. Safe to call more than once.
+ * one frame. When the optional peer is not installed, there is nothing to
+ * patch. Safe to call more than once.
  */
-export function patchTestingLibraryUserEvent() {
+export async function patchTestingLibraryUserEvent() {
+    let userEvent;
+    try {
+        userEvent = (await import('@testing-library/user-event')).default;
+    }
+    catch {
+        return;
+    }
     const direct = userEvent;
     patchMethods(direct);
     const originalSetup = direct.setup;

package/dist/plugin.d.ts

@@ -27,6 +27,20 @@ export interface DescribeMeOptions {
      * Applied when styled-components is installed. Default: true.
      */
     styledComponentsBrowserBuild?: boolean;
+    /**
+     * Test files to record, as globs relative to the Vitest root, matched with
+     * picomatch, dotfiles included. Tests in other files still run, but record
+     * nothing and leave the manifest. Default: every test file.
+     */
+    include?: string | string[];
+    /** Test files never to record, as globs like `include`. Wins over `include`. Default: none. */
+    exclude?: string | string[];
+    /**
+     * HTML the viewer adds to the start of the `<head>` of every replayed frame,
+     * like Storybook's `preview-head.html`. It never reaches the test page.
+     * Project files it links are copied into the output directory. Default: none.
+     */
+    previewHead?: string;
 }
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 /**

package/dist/plugin.js

@@ -1,6 +1,9 @@
+import { adapterPackageRoot } from './adapter-package-root.js';
+import { compileGlobs } from './compile-globs.js';
 import { projectModulePath } from './project-module-path.js';
 import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.js';
+import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
 import { styledComponentsBrowserBuild } from './styled-components-browser-build.js';
 /** For each framework and environment: the render module tests import, and our adapter that wraps it. */
 const RENDER_MODULES = {
@@ -9,8 +12,24 @@ const RENDER_MODULES = {
         dom: { original: '@testing-library/react', adapter: '@describe-me/react/testing-library' },
     },
 };
-/** Paths an adapter's own files live under, published or in this workspace. */
-const ADAPTER_PATHS = ['/@describe-me/react/', '/packages/react/'];
+/**
+ * The package an adapter entry point belongs to, e.g.
+ * `@describe-me/react/testing-library` → `@describe-me/react`.
+ */
+function packageNameOf(specifier) {
+    return specifier.split('/').slice(0, 2).join('/');
+}
+/**
+ * Whether a module is one of the adapter's own files, whose imports of the
+ * original module must stay unredirected. `/node_modules/<package>/` is the
+ * fallback for when the project root could not resolve the package.
+ */
+function isAdapterModule(id, adapterRoot, adapterPackage) {
+    if (adapterRoot !== null && id.startsWith(adapterRoot)) {
+        return true;
+    }
+    return id.includes(`/node_modules/${adapterPackage}/`);
+}
 function detectEnvironment(userConfig) {
     return userConfig.test?.browser?.enabled ? 'browser' : 'dom';
 }
@@ -70,6 +89,9 @@ export function describeMe(options = {}) {
     // build that shares the config must not carry the export registration.
     let root = '';
     let serving = false;
+    // Where the installed adapter lives, so a user path that merely looks like
+    // it (`packages/react/` in a monorepo) is still redirected.
+    let adapterRoot = null;
     return {
         name: 'describe-me',
         enforce: 'pre',
@@ -79,20 +101,31 @@ export function describeMe(options = {}) {
             }
             const environment = options.environment ?? detectEnvironment(userConfig);
             renderModule = RENDER_MODULES[framework][environment];
-            const reporter = new DescribeMeReporter({ outDir });
+            // Compiled here, so invalid globs fail before any test runs. Vite
+            // deep-merges `provide`, so the user's own keys survive.
+            const runtimeOptions = {
+                include: compileGlobs(options.include),
+                exclude: compileGlobs(options.exclude),
+            };
+            const provide = { [RUNTIME_OPTIONS_KEY]: runtimeOptions };
+            const reporter = new DescribeMeReporter({
+                outDir,
+                include: options.include,
+                exclude: options.exclude,
+                previewHead: options.previewHead,
+            });
             // Vite concatenates arrays when merging, so only add `default` when the
             // user has not chosen their own reporters; otherwise they would lose it.
             const reporters = userConfig.test?.reporters ? [reporter] : ['default', reporter];
             const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig, options);
-            return { ...config, test: { ...config.test, reporters } };
+            return { ...config, test: { ...config.test, reporters, provide } };
         },
         async resolveId(source, importer) {
             if (!enabled || source !== renderModule.original) {
                 return null;
             }
             const fromAdapter = importer !== undefined &&
-                (importer.includes(renderModule.adapter) ||
-                    ADAPTER_PATHS.some((path) => importer.includes(path)));
+                isAdapterModule(importer, adapterRoot, packageNameOf(renderModule.adapter));
             if (fromAdapter) {
                 return null;
             }
@@ -101,13 +134,14 @@ export function describeMe(options = {}) {
             // recording nothing, and in a DOM environment it would also leave every
             // test mounted, because Testing Library's auto-cleanup is switched off.
             if (!resolved) {
-                throw new Error(`describe-me: cannot resolve ${renderModule.adapter} (the recording replacement for ${renderModule.original}). Install ${renderModule.adapter.split('/').slice(0, 2).join('/')}.`);
+                throw new Error(`describe-me: cannot resolve ${renderModule.adapter} (the recording replacement for ${renderModule.original}). Install ${packageNameOf(renderModule.adapter)}.`);
             }
             return resolved;
         },
         configResolved(config) {
             root = config.root;
             serving = config.command === 'serve';
+            adapterRoot = adapterPackageRoot(config.root, packageNameOf(renderModule.adapter));
         },
         // Names components after their export (see registerExports). `order: 'post'`
         // runs it after the TypeScript and JSX transforms, so it parses plain

package/dist/read-runtime-options.d.ts

@@ -0,0 +1,3 @@
+import { type RuntimeOptions } from './runtime-options.js';
+/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+export declare function readRuntimeOptions(): RuntimeOptions;

package/dist/read-runtime-options.js

@@ -0,0 +1,6 @@
+import { inject } from 'vitest';
+import { RUNTIME_OPTIONS_KEY } from './runtime-options.js';
+/** Without the plugin nothing is provided, so a hand-wired setup keeps recording every test. */
+export function readRuntimeOptions() {
+    return inject(RUNTIME_OPTIONS_KEY) ?? { include: [], exclude: [] };
+}

package/dist/register-recording-hooks.d.ts

@@ -1,6 +1,9 @@
+import type { RuntimeOptions } from './runtime-options.js';
 /**
- * The per-test lifecycle shared by every environment: begin a recording
- * before each test, then take the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount.
+ * The per-test lifecycle shared by every environment: begin a recording, take
+ * the closing frame, hand the frames to the reporter via task.meta, and only
+ * then let adapters unmount. Teardown runs for unrecorded tests too, because
+ * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
+ * the one recorder, so they are not recorded.
  */
-export declare function registerRecordingHooks(): void;
+export declare function registerRecordingHooks(options: RuntimeOptions): void;

package/dist/register-recording-hooks.js

@@ -1,17 +1,41 @@
 import { afterEach, beforeEach } from 'vitest';
 import { META_KEY, recorder } from '@describe-me/core';
+import { fileFilter } from './file-filter.js';
 /**
- * The per-test lifecycle shared by every environment: begin a recording
- * before each test, then take the closing frame, hand the frames to the
- * reporter via task.meta, and only then let adapters unmount.
+ * The per-test lifecycle shared by every environment: begin a recording, take
+ * the closing frame, hand the frames to the reporter via task.meta, and only
+ * then let adapters unmount. Teardown runs for unrecorded tests too, because
+ * Testing Library's auto-cleanup is off in jsdom. Concurrent tests would share
+ * the one recorder, so they are not recorded.
  */
-export function registerRecordingHooks() {
-    beforeEach(() => {
-        recorder.begin();
+export function registerRecordingHooks(options) {
+    const isRecordedFile = fileFilter(options);
+    let warnedConcurrent = false;
+    beforeEach((context) => {
+        if (context.task.concurrent) {
+            if (!warnedConcurrent) {
+                warnedConcurrent = true;
+                console.warn(`describe-me: concurrent tests are not recorded (${context.task.file.name})`);
+            }
+            return;
+        }
+        if (isRecordedFile(context.task.file.name)) {
+            recorder.begin();
+        }
     });
     afterEach(async (context) => {
-        await recorder.capture('end', 'end of test');
-        context.task.meta[META_KEY] = recorder.end();
-        recorder.teardown();
+        try {
+            if (recorder.isActive) {
+                await recorder.capture('end', 'end of test');
+                const record = recorder.end();
+                if (record.frames.length > 0) {
+                    ;
+                    context.task.meta[META_KEY] = record;
+                }
+            }
+        }
+        finally {
+            recorder.teardown();
+        }
     });
 }

package/dist/reporter.d.ts

@@ -2,13 +2,32 @@ import type { Reporter, TestModule, Vitest } from 'vitest/node';
 export interface DescribeMeReporterOptions {
     /** Output directory, relative to the Vitest root. Default: `.describe-me` */
     outDir?: string;
+    /**
+     * Which test files appear in the manifest: globs relative to the Vitest
+     * root, matched with picomatch, dotfiles included. Default: every test file.
+     */
+    include?: string | string[];
+    /**
+     * Test files to leave out of the manifest, as globs like `include`. Wins over
+     * `include`. Default: none.
+     */
+    exclude?: string | string[];
+    /**
+     * HTML the viewer adds to the start of the `<head>` of every replayed frame,
+     * like Storybook's `preview-head.html`. It never reaches the test page.
+     * Project files it links are copied into the output directory. Default: none.
+     */
+    previewHead?: string;
 }
 export default class DescribeMeReporter implements Reporter {
     private readonly outDirOption;
+    private readonly isRecordedFile;
+    private readonly previewHead;
     private root;
     private outDir;
     private snapshots;
     private assets;
+    private styles;
     private modules;
     constructor(options?: DescribeMeReporterOptions);
     onInit(vitest: Vitest): void;
@@ -16,12 +35,25 @@ export default class DescribeMeReporter implements Reporter {
     /**
      * A filtered run (`vitest run Button.test.tsx`) must not wipe the other
      * modules from the manifest, so start from whatever the last run wrote.
-     * Modules whose file no longer exists are dropped.
+     * Modules whose file is gone or no longer selected by `include` / `exclude`
+     * are dropped, and so are the empty tests that 0.4 still wrote.
      */
     private seedFromPreviousRun;
+    /**
+     * A test skipped in this run keeps its previous entry, so a filtered run does
+     * not erase documentation.
+     */
     onTestModuleEnd(module: TestModule): void;
     onTestRunEnd(): Promise<void>;
+    /** Module ids use the platform's separators. Globs expect posix ones. */
+    private isRecordedModule;
+    /** Decided before any snapshot is written, so a dropped test writes no file. */
+    private manifestTestOf;
     private toManifestTest;
-    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    /**
+     * Store one frame's DOM, with asset URLs pointing into the asset store and
+     * long stylesheets moved to the style store. Assets go first, so stored CSS
+     * carries asset URLs too.
+     */
     private writeSnapshot;
 }

package/dist/reporter.js

@@ -1,32 +1,52 @@
 /**
  * Node-side Vitest reporter. Collects frames from task.meta and writes
- * `.describe-me/manifest.json` plus one file per snapshot.
+ * `.describe-me/`: `manifest.json`, `snapshots/`, `styles/` and `assets/`.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, relative, resolve } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { META_KEY, } from '@describe-me/core/types';
 import { AssetStore } from './asset-store.js';
 import { collectComponentDocsSafely } from './collect-component-docs-safely.js';
+import { compileGlobs } from './compile-globs.js';
 import { componentEntries } from './component-entries.js';
+import { fileFilter } from './file-filter.js';
+import { isRecordedTest } from './is-recorded-test.js';
 import { printDiagnostics } from './print-diagnostics.js';
 import { SnapshotStore } from './snapshot-store.js';
+import { StyleStore } from './style-store.js';
 import { testPath } from './test-path.js';
+function recordOf(tc) {
+    return tc.meta()[META_KEY];
+}
 export default class DescribeMeReporter {
     outDirOption;
+    isRecordedFile;
+    previewHead;
     root = process.cwd();
     outDir = '';
     snapshots;
     assets;
+    styles;
     modules = new Map();
     constructor(options = {}) {
         this.outDirOption = options.outDir ?? '.describe-me';
+        this.isRecordedFile = fileFilter({
+            include: compileGlobs(options.include),
+            exclude: compileGlobs(options.exclude),
+        });
+        // A blank head, such as an empty preview-head.html, is the same as none.
+        this.previewHead = options.previewHead?.trim() ? options.previewHead : undefined;
     }
     onInit(vitest) {
         this.root = vitest.config.root;
         this.outDir = resolve(this.root, this.outDirOption);
         this.snapshots = new SnapshotStore(this.outDir);
         this.assets = new AssetStore(this.outDir, this.root);
+        this.styles = new StyleStore(this.outDir);
         this.seedFromPreviousRun();
+        if (this.previewHead !== undefined && /<script\b/i.test(this.previewHead)) {
+            console.warn('describe-me: previewHead contains a <script>, which the viewer never runs.');
+        }
     }
     onTestRunStart() {
         this.assets.startRun();
@@ -34,7 +54,8 @@ export default class DescribeMeReporter {
     /**
      * A filtered run (`vitest run Button.test.tsx`) must not wipe the other
      * modules from the manifest, so start from whatever the last run wrote.
-     * Modules whose file no longer exists are dropped.
+     * Modules whose file is gone or no longer selected by `include` / `exclude`
+     * are dropped, and so are the empty tests that 0.4 still wrote.
      */
     seedFromPreviousRun() {
         const file = join(this.outDir, 'manifest.json');
@@ -44,8 +65,11 @@ export default class DescribeMeReporter {
         try {
             const previous = JSON.parse(readFileSync(file, 'utf8'));
             for (const mod of previous.modules ?? []) {
-                if (existsSync(resolve(this.root, mod.id))) {
-                    this.modules.set(mod.id, mod);
+                const tests = mod.tests.filter((test) => isRecordedTest(test));
+                if (tests.length > 0 &&
+                    this.isRecordedModule(mod.id) &&
+                    existsSync(resolve(this.root, mod.id))) {
+                    this.modules.set(mod.id, { ...mod, tests });
                 }
             }
         }
@@ -53,14 +77,35 @@ export default class DescribeMeReporter {
             // corrupt or incompatible manifest: start fresh
         }
     }
+    /**
+     * A test skipped in this run keeps its previous entry, so a filtered run does
+     * not erase documentation.
+     */
     onTestModuleEnd(module) {
         const id = relative(this.root, module.moduleId);
-        const tests = Array.from(module.children.allTests()).map((tc) => this.toManifestTest(tc));
+        if (!this.isRecordedModule(id)) {
+            this.modules.delete(id);
+            return;
+        }
+        const previous = this.modules.get(id);
+        const tests = [];
+        for (const tc of module.children.allTests()) {
+            const test = this.manifestTestOf(tc, previous);
+            if (test) {
+                tests.push(test);
+            }
+        }
+        if (tests.length === 0) {
+            this.modules.delete(id);
+            return;
+        }
         this.modules.set(id, { id, tests });
     }
     async onTestRunEnd() {
         const modules = Array.from(this.modules.values()).sort((left, right) => left.id.localeCompare(right.id));
         const components = await collectComponentDocsSafely(this.root, componentEntries(modules, this.root));
+        // Before `missing()`, so the files the head links that do not exist are listed too.
+        const head = this.previewHead === undefined ? undefined : this.assets.rewriteHead(this.previewHead);
         // Only what this run found: a filtered run does not know which of the
         // previous run's missing assets belonged to the modules it skipped.
         const assetsMissing = this.assets.missing();
@@ -72,22 +117,40 @@ export default class DescribeMeReporter {
             components,
             assetsMissing,
         };
+        if (head !== undefined) {
+            manifest.head = head;
+        }
         const snapshotFiles = manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot)));
         this.snapshots.collectGarbage(snapshotFiles);
-        this.assets.collectGarbage(snapshotFiles);
+        const styleFiles = this.styles.collectGarbage(snapshotFiles);
+        this.assets.collectGarbage([...snapshotFiles, ...styleFiles], head === undefined ? [] : [head]);
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
         printDiagnostics(manifest);
     }
-    toManifestTest(tc) {
-        const record = tc.meta()[META_KEY];
+    /** Module ids use the platform's separators. Globs expect posix ones. */
+    isRecordedModule(id) {
+        return this.isRecordedFile(id.split(sep).join('/'));
+    }
+    /** Decided before any snapshot is written, so a dropped test writes no file. */
+    manifestTestOf(tc, previous) {
+        const record = recordOf(tc);
+        if (record && isRecordedTest(record)) {
+            return this.toManifestTest(tc, record);
+        }
+        if (tc.result().state !== 'skipped') {
+            return undefined;
+        }
+        return previous?.tests.find((test) => test.id === tc.id && test.fullName === tc.fullName && isRecordedTest(test));
+    }
+    toManifestTest(tc, record) {
         const result = tc.result();
-        const frames = (record?.frames ?? []).map((frame) => ({
+        const frames = record.frames.map((frame) => ({
             id: frame.id,
             kind: frame.kind,
             label: frame.label,
             at: frame.at,
             meta: frame.meta,
-            snapshot: this.writeSnapshot(frame.snapshot, record?.origin),
+            snapshot: this.writeSnapshot(frame.snapshot, record.origin),
         }));
         return {
             id: tc.id,
@@ -97,12 +160,18 @@ export default class DescribeMeReporter {
             state: result.state ?? 'pending',
             duration: tc.diagnostic()?.duration,
             errors: result.errors?.map((error) => ({ message: error.message, stack: error.stack })),
-            component: record?.component,
+            component: record.component,
             frames,
         };
     }
-    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    /**
+     * Store one frame's DOM, with asset URLs pointing into the asset store and
+     * long stylesheets moved to the style store. Assets go first, so stored CSS
+     * carries asset URLs too.
+     */
     writeSnapshot(snapshot, origin) {
-        return this.snapshots.write(this.assets.rewrite(JSON.stringify(snapshot), origin));
+        // A mixed install, where an older core created the global recorder, still hands over objects.
+        const json = typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot);
+        return this.snapshots.write(this.styles.extract(this.assets.rewrite(json, origin)));
     }
 }

package/dist/rewrite-css-references.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Replace each `url()` and `@import` target in CSS text for which `resolve`
+ * returns a string. Quotes and everything else stay as written.
+ */
+export declare function rewriteCssReferences(css: string, resolve: (url: string) => string | null): string;

package/dist/rewrite-css-references.js

@@ -0,0 +1,18 @@
+import { cssReferences } from '@describe-me/core/css-references';
+/**
+ * Replace each `url()` and `@import` target in CSS text for which `resolve`
+ * returns a string. Quotes and everything else stay as written.
+ */
+export function rewriteCssReferences(css, resolve) {
+    let rewritten = '';
+    let copied = 0;
+    for (const reference of cssReferences(css)) {
+        const replacement = resolve(reference.url);
+        if (replacement === null) {
+            continue;
+        }
+        rewritten += css.slice(copied, reference.start) + replacement;
+        copied = reference.end;
+    }
+    return rewritten + css.slice(copied);
+}

package/dist/rewrite-head-references.d.ts

@@ -0,0 +1,8 @@
+type Resolve = (url: string) => string | null;
+/**
+ * Replace the URLs in HTML meant for a document's `<head>`: `href` and `src`
+ * values, and the `url()` and `@import` targets of `<style>` elements and
+ * `style` attributes, wherever `resolve` returns a string.
+ */
+export declare function rewriteHeadReferences(html: string, resolve: Resolve): string;
+export {};

package/dist/rewrite-head-references.js

@@ -0,0 +1,49 @@
+import { rewriteCssReferences } from './rewrite-css-references.js';
+/**
+ * Comments and `<script>` elements, which stay as written, and `<style>`
+ * elements, whose CSS is rewritten. Tags between them are rewritten attribute
+ * by attribute. End tags and comment ends are matched as loosely as browsers
+ * read them: `</script foo>` and `--!>` count too.
+ */
+const RAW_TEXT = /<!--[\s\S]*?--!?>|<script\b[\s\S]*?<\/script\b[^>]*>|(<style\b[^>]*>)([\s\S]*?)(<\/style\b[^>]*>)/gi;
+/** A start tag, split after its name. Quoted attribute values may contain `>`. */
+const START_TAG = /(<[a-z][^\s/>]*)((?:[^>"']|"[^"]*"|'[^']*')*>)/gi;
+/**
+ * One attribute: its whole name, so `data-src` is never `src`, and its value,
+ * double-quoted, single-quoted or bare.
+ */
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:(\s*=\s*)("[^"]*"|'[^']*'|[^\s"'=<>`]+))?/g;
+/** Attributes whose value is a URL, and `style`, whose value is CSS. */
+const REWRITTEN_ATTRIBUTES = new Set(['href', 'src', 'style']);
+function rewriteAttribute(attribute, name, equals, value, resolve) {
+    const kind = name.toLowerCase();
+    if (equals === undefined || value === undefined || !REWRITTEN_ATTRIBUTES.has(kind)) {
+        return attribute;
+    }
+    const quote = value.startsWith('"') || value.startsWith("'") ? value[0] : '';
+    const text = quote === '' ? value : value.slice(1, -1);
+    const rewritten = kind === 'style' ? rewriteCssReferences(text, resolve) : (resolve(text) ?? text);
+    return `${name}${equals}${quote}${rewritten}${quote}`;
+}
+function rewriteTags(html, resolve) {
+    return html.replace(START_TAG, (_tag, name, attributes) => {
+        const rewritten = attributes.replace(ATTRIBUTE, (attribute, attributeName, equals, value) => rewriteAttribute(attribute, attributeName, equals, value, resolve));
+        return name + rewritten;
+    });
+}
+/**
+ * Replace the URLs in HTML meant for a document's `<head>`: `href` and `src`
+ * values, and the `url()` and `@import` targets of `<style>` elements and
+ * `style` attributes, wherever `resolve` returns a string.
+ */
+export function rewriteHeadReferences(html, resolve) {
+    let rewritten = '';
+    let copied = 0;
+    for (const match of html.matchAll(RAW_TEXT)) {
+        const [text, styleStart, css, styleEnd] = match;
+        const kept = styleStart === undefined ? text : styleStart + rewriteCssReferences(css, resolve) + styleEnd;
+        rewritten += rewriteTags(html.slice(copied, match.index), resolve) + kept;
+        copied = match.index + text.length;
+    }
+    return rewritten + rewriteTags(html.slice(copied), resolve);
+}

package/dist/runtime-options.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Travels from the plugin to the setup files through Vitest's `provide` /
+ * `inject`. Keep it plain JSON: the browser receives it serialized, so a
+ * RegExp would not survive. The test runtime imports this file, so it imports
+ * nothing itself.
+ */
+export interface CompiledGlob {
+    source: string;
+    flags: string;
+}
+export interface RuntimeOptions {
+    /** Empty means every test file. */
+    include: CompiledGlob[];
+    /** Wins over `include`. */
+    exclude: CompiledGlob[];
+}
+export declare const RUNTIME_OPTIONS_KEY: "describe-me";
+declare module 'vitest' {
+    interface ProvidedContext {
+        'describe-me': RuntimeOptions;
+    }
+}

package/dist/runtime-options.js

@@ -0,0 +1,7 @@
+/**
+ * Travels from the plugin to the setup files through Vitest's `provide` /
+ * `inject`. Keep it plain JSON: the browser receives it serialized, so a
+ * RegExp would not survive. The test runtime imports this file, so it imports
+ * nothing itself.
+ */
+export const RUNTIME_OPTIONS_KEY = 'describe-me';

package/dist/setup-dom.js

@@ -1,11 +1,15 @@
 /**
  * Vitest setup file for DOM environments such as jsdom:
  * `setupFiles: ['@describe-me/vitest/setup-dom']`. Patches Testing Library's
- * userEvent so every interaction records a frame, and registers the
- * recording hooks. Never imports `vitest/browser`, which only exists in
- * browser mode.
+ * userEvent, when it is installed, so every interaction records a frame, sets
+ * React's act flag where Testing Library would, and registers the recording
+ * hooks. Which test files are recorded (`include` / `exclude`) comes from the
+ * plugin. Never imports `vitest/browser`, which only exists in browser mode.
  */
+import { mirrorReactActEnvironment } from './mirror-react-act-environment.js';
 import { patchTestingLibraryUserEvent } from './patch-testing-library-user-event.js';
+import { readRuntimeOptions } from './read-runtime-options.js';
 import { registerRecordingHooks } from './register-recording-hooks.js';
-patchTestingLibraryUserEvent();
-registerRecordingHooks();
+await patchTestingLibraryUserEvent();
+mirrorReactActEnvironment();
+registerRecordingHooks(readRuntimeOptions());