@describe-me/vitest 0.3.0 → 0.4.0

package/dist/asset-store.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Content-addressed store for the project files snapshots point at (images,
+ * fonts, `url()` targets of stylesheets), living in `<outDir>/assets`.
+ *
+ * rrweb makes most URLs absolute against the test page, whose server is gone
+ * once the tests finish; a few stay root-relative, which the viewer would
+ * resolve against itself. `rewrite()` copies each file it finds in the project
+ * and swaps its URL for `ASSET_URL_PREFIX` plus the stored name, which the
+ * viewer resolves against its own data directory.
+ */
+export declare class AssetStore {
+    private readonly outDir;
+    private readonly dir;
+    private readonly root;
+    /** Stored name per URL pathname in this run, or null when it is not a project file. */
+    private readonly names;
+    private readonly notFound;
+    /** Asset names per snapshot file. Snapshots are content-addressed, so an entry never goes stale. */
+    private readonly referencesBySnapshot;
+    constructor(outDir: string, root: string);
+    /** Forget what the previous run found: files may have changed or appeared since. */
+    startRun(): void;
+    /**
+     * Replace every URL in a serialized snapshot that points at a project file
+     * with an asset URL. rrweb has made most of them absolute against `origin`:
+     * `src`, `href`, `srcset`, `xlink:href`, `style` attributes and, in a real
+     * browser, `url()` inside stylesheets. The two it leaves root-relative are
+     * handled on their own. A `#fragment` is kept, for SVG sprites.
+     */
+    rewrite(json: string, origin: string | undefined): string;
+    /** Root-relative paths that snapshots in this run pointed at but that do not exist. */
+    missing(): string[];
+    /**
+     * Drop the assets no kept snapshot refers to. Paths are relative to the
+     * output directory, as the manifest stores them. Every kept file is scanned,
+     * not only the ones written now: snapshots of modules that were not re-run
+     * were rewritten by an earlier run.
+     */
+    collectGarbage(snapshotFiles: Iterable<string>): void;
+    private referencesIn;
+    /** The asset URL for a root-relative URL path, or null when it is not a project file. */
+    private assetUrl;
+    /** The stored name for a URL pathname, copying the file on first sight in this run. */
+    private nameFor;
+    private copyIntoStore;
+    /** Where Vite serves a URL pathname from: `/@fs/`, the project root, or its `public/` folder. */
+    private fileFor;
+}

package/dist/asset-store.js

@@ -0,0 +1,230 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, } from 'node:fs';
+import { extname, join, resolve, sep } from 'node:path';
+import { ASSET_URL_PREFIX } from '@describe-me/core/types';
+/** A URL path inside serialized JSON runs until a quote, whitespace, `)`, `\`, `<` or `>`. */
+const URL_PATH = String.raw `/[^"'\s)\\<>]*`;
+/** A root-relative path: one slash, not the two of a protocol-relative URL. */
+const ROOT_RELATIVE_PATH = String.raw `/(?!/)[^"'\s)\\<>]*`;
+/**
+ * `url(/…)` in CSS text, with the opening quote as it looks inside JSON (`\"`,
+ * `'` or none). rrweb makes stylesheet URLs absolute through the sheet's
+ * `ownerNode`, which jsdom does not implement, so in jsdom they stay as Vite
+ * wrote them.
+ */
+const CSS_ROOT_RELATIVE_URL = new RegExp(String.raw `url\((\\"|')?(${ROOT_RELATIVE_PATH})`, 'g');
+/** rrweb makes `src` and `href` absolute, but leaves a video's `poster` as authored. */
+const ROOT_RELATIVE_POSTER = new RegExp(`"poster":"(${ROOT_RELATIVE_PATH})`, 'g');
+/** A stored asset's name: a content hash and, when the file has one, its extension. */
+const ASSET_REFERENCE = new RegExp(`${escapeRegExp(ASSET_URL_PREFIX)}([0-9a-f]{16}(?:\\.[a-z0-9]+)?)`, 'g');
+/**
+ * Dev-server paths that are never project files: Vite's client and module ids,
+ * the pre-bundled dependencies, and the pages Vitest serves in browser mode.
+ */
+const SERVER_PREFIXES = [
+    '/@vite/',
+    '/@id/',
+    '/@react-refresh',
+    '/node_modules/.vite/',
+    '/__vitest__/',
+    '/__vitest_browser__/',
+    '/__vitest_test__/',
+];
+/** Scripts, not assets: they never run in the viewer, so their URLs are left as they are. */
+const MODULE_EXTENSIONS = new Set([
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.jsx',
+    '.ts',
+    '.mts',
+    '.cts',
+    '.tsx',
+    '.vue',
+    '.svelte',
+]);
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function isFile(path) {
+    return existsSync(path) && statSync(path).isFile();
+}
+function decodePath(pathname) {
+    try {
+        return decodeURIComponent(pathname);
+    }
+    catch {
+        return pathname;
+    }
+}
+/** Split `/logo.svg?v=2#icon` into its pathname and its fragment; the query is dropped. */
+function splitUrlPath(urlPath) {
+    const hashAt = urlPath.indexOf('#');
+    const beforeHash = hashAt === -1 ? urlPath : urlPath.slice(0, hashAt);
+    const fragment = hashAt === -1 ? '' : urlPath.slice(hashAt);
+    const queryAt = beforeHash.indexOf('?');
+    const pathname = queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt);
+    return { pathname, fragment };
+}
+function isServerPath(pathname) {
+    if (SERVER_PREFIXES.some((prefix) => pathname.startsWith(prefix))) {
+        return true;
+    }
+    return MODULE_EXTENSIONS.has(extname(pathname).toLowerCase());
+}
+/** Vite serves files outside the root as `/@fs/<absolute path>`; a Windows path keeps its drive letter. */
+function fsPathFromUrl(pathname) {
+    const path = pathname.slice('/@fs/'.length);
+    return /^[A-Za-z]:/.test(path) ? path : `/${path}`;
+}
+/**
+ * Content-addressed store for the project files snapshots point at (images,
+ * fonts, `url()` targets of stylesheets), living in `<outDir>/assets`.
+ *
+ * rrweb makes most URLs absolute against the test page, whose server is gone
+ * once the tests finish; a few stay root-relative, which the viewer would
+ * resolve against itself. `rewrite()` copies each file it finds in the project
+ * and swaps its URL for `ASSET_URL_PREFIX` plus the stored name, which the
+ * viewer resolves against its own data directory.
+ */
+export class AssetStore {
+    outDir;
+    dir;
+    root;
+    /** Stored name per URL pathname in this run, or null when it is not a project file. */
+    names = new Map();
+    notFound = new Set();
+    /** Asset names per snapshot file. Snapshots are content-addressed, so an entry never goes stale. */
+    referencesBySnapshot = new Map();
+    constructor(outDir, root) {
+        this.outDir = outDir;
+        this.dir = join(outDir, 'assets');
+        this.root = resolve(root);
+        mkdirSync(this.dir, { recursive: true });
+    }
+    /** Forget what the previous run found: files may have changed or appeared since. */
+    startRun() {
+        this.names.clear();
+        this.notFound.clear();
+    }
+    /**
+     * Replace every URL in a serialized snapshot that points at a project file
+     * with an asset URL. rrweb has made most of them absolute against `origin`:
+     * `src`, `href`, `srcset`, `xlink:href`, `style` attributes and, in a real
+     * browser, `url()` inside stylesheets. The two it leaves root-relative are
+     * handled on their own. A `#fragment` is kept, for SVG sprites.
+     */
+    rewrite(json, origin) {
+        let rewritten = json;
+        // An opaque origin serializes as "null", which is not a URL prefix at all.
+        if (origin !== undefined && /^https?:\/\//.test(origin)) {
+            const onOrigin = new RegExp(`${escapeRegExp(origin)}(${URL_PATH})`, 'g');
+            rewritten = rewritten.replace(onOrigin, (url, urlPath) => {
+                return this.assetUrl(urlPath) ?? url;
+            });
+        }
+        rewritten = rewritten.replace(CSS_ROOT_RELATIVE_URL, (url, quote, urlPath) => {
+            const asset = this.assetUrl(urlPath);
+            return asset === null ? url : `url(${quote ?? ''}${asset}`;
+        });
+        return rewritten.replace(ROOT_RELATIVE_POSTER, (poster, urlPath) => {
+            const asset = this.assetUrl(urlPath);
+            return asset === null ? poster : `"poster":"${asset}`;
+        });
+    }
+    /** Root-relative paths that snapshots in this run pointed at but that do not exist. */
+    missing() {
+        return Array.from(this.notFound).sort();
+    }
+    /**
+     * Drop the assets no kept snapshot refers to. Paths are relative to the
+     * output directory, as the manifest stores them. Every kept file is scanned,
+     * not only the ones written now: snapshots of modules that were not re-run
+     * were rewritten by an earlier run.
+     */
+    collectGarbage(snapshotFiles) {
+        const stored = readdirSync(this.dir);
+        if (stored.length === 0) {
+            return;
+        }
+        const keep = new Set();
+        for (const snapshotFile of snapshotFiles) {
+            for (const name of this.referencesIn(snapshotFile)) {
+                keep.add(name);
+            }
+        }
+        for (const file of stored) {
+            if (!keep.has(file)) {
+                rmSync(join(this.dir, file), { force: true });
+            }
+        }
+    }
+    referencesIn(snapshotFile) {
+        const cached = this.referencesBySnapshot.get(snapshotFile);
+        if (cached) {
+            return cached;
+        }
+        const path = join(this.outDir, snapshotFile);
+        if (!isFile(path)) {
+            return [];
+        }
+        const json = readFileSync(path, 'utf8');
+        const names = Array.from(json.matchAll(ASSET_REFERENCE), (match) => match[1]);
+        this.referencesBySnapshot.set(snapshotFile, names);
+        return names;
+    }
+    /** The asset URL for a root-relative URL path, or null when it is not a project file. */
+    assetUrl(urlPath) {
+        const { pathname, fragment } = splitUrlPath(urlPath);
+        const name = this.nameFor(pathname);
+        if (name === null) {
+            return null;
+        }
+        return `${ASSET_URL_PREFIX}${name}${fragment}`;
+    }
+    /** The stored name for a URL pathname, copying the file on first sight in this run. */
+    nameFor(pathname) {
+        const known = this.names.get(pathname);
+        if (known !== undefined) {
+            return known;
+        }
+        const name = this.copyIntoStore(decodePath(pathname));
+        this.names.set(pathname, name);
+        return name;
+    }
+    copyIntoStore(pathname) {
+        if (isServerPath(pathname)) {
+            return null;
+        }
+        const file = this.fileFor(pathname);
+        // Page links such as `/`, `/#` or `/about` resolve to nothing and are not
+        // assets either. Only a path that names a file is worth reporting.
+        if (!file) {
+            if (extname(pathname) !== '') {
+                this.notFound.add(pathname);
+            }
+            return null;
+        }
+        const hash = createHash('sha1').update(readFileSync(file)).digest('hex').slice(0, 16);
+        const extension = extname(file).toLowerCase();
+        const name = /^\.[a-z0-9]+$/.test(extension) ? `${hash}${extension}` : hash;
+        const target = join(this.dir, name);
+        if (!existsSync(target)) {
+            copyFileSync(file, target);
+        }
+        return name;
+    }
+    /** Where Vite serves a URL pathname from: `/@fs/`, the project root, or its `public/` folder. */
+    fileFor(pathname) {
+        if (pathname.startsWith('/@fs/')) {
+            const path = fsPathFromUrl(pathname);
+            return isFile(path) ? path : undefined;
+        }
+        const candidates = [
+            resolve(this.root, `.${pathname}`),
+            resolve(this.root, 'public', `.${pathname}`),
+        ];
+        // A decoded `%2F..` must not reach outside the project.
+        return candidates.find((path) => path.startsWith(this.root + sep) && isFile(path));
+    }
+}

package/dist/collect-component-docs.d.ts

@@ -3,10 +3,15 @@ import type { ComponentDoc } from '@describe-me/core/types';
 export interface ComponentEntry {
     testFile: string;
     componentName: string;
+    /**
+     * The module that defines the component, relative to the root, when the
+     * plugin registered its exports. Otherwise the test's imports are searched.
+     */
+    componentFile?: string;
 }
 /**
- * Document every component the tests rendered: find its source file through the
- * test's imports, then read its props from TypeScript. One program covers all of
- * them; a component that cannot be found or read is left out of the result.
+ * Document every component the tests rendered: find its source file, then read
+ * its props from TypeScript. One program covers all of them; a component that
+ * cannot be found or read is left out of the result.
  */
 export declare function collectComponentDocs(root: string, entries: Iterable<ComponentEntry>): Record<string, ComponentDoc>;

package/dist/collect-component-docs.js

@@ -1,16 +1,16 @@
-import { relative, sep } from 'node:path';
+import { relative, resolve, sep } from 'node:path';
 import ts from 'typescript';
 import { extractProps } from './extract-props.js';
 import { loadCompilerOptions } from './load-compiler-options.js';
 import { resolveComponentFile } from './resolve-component-file.js';
 /**
- * Document every component the tests rendered: find its source file through the
- * test's imports, then read its props from TypeScript. One program covers all of
- * them; a component that cannot be found or read is left out of the result.
+ * Document every component the tests rendered: find its source file, then read
+ * its props from TypeScript. One program covers all of them; a component that
+ * cannot be found or read is left out of the result.
  */
 export function collectComponentDocs(root, entries) {
     const options = loadCompilerOptions(root);
-    const resolved = resolveAll(entries, options);
+    const resolved = resolveAll(root, Array.from(entries), options);
     if (resolved.size === 0) {
         return {};
     }
@@ -28,9 +28,13 @@ export function collectComponentDocs(root, entries) {
     }
     return docs;
 }
-/** One source file per component name; the same component is looked up once. */
-function resolveAll(entries, options) {
-    const resolved = new Map();
+/**
+ * One source file per component name. Files the plugin registered come first,
+ * because the test's imports are only a guess; among them the first one seen
+ * for a name wins. The remaining names are looked up through the imports.
+ */
+function resolveAll(root, entries, options) {
+    const resolved = registeredComponents(root, entries);
     for (const entry of entries) {
         if (resolved.has(entry.componentName)) {
             continue;
@@ -42,6 +46,31 @@ function resolveAll(entries, options) {
     }
     return resolved;
 }
+/**
+ * The components whose file the adapter reported. Docs are keyed by name, so
+ * two components exported under the same name from different files cannot
+ * both be documented: the first stays, and the clash is reported once.
+ */
+function registeredComponents(root, entries) {
+    const resolved = new Map();
+    const clashes = new Set();
+    for (const { componentName, componentFile } of entries) {
+        if (componentFile === undefined) {
+            continue;
+        }
+        const file = resolve(root, componentFile);
+        const known = resolved.get(componentName);
+        if (!known) {
+            resolved.set(componentName, { file, exportName: componentName });
+            continue;
+        }
+        if (known.file !== file && !clashes.has(componentName)) {
+            clashes.add(componentName);
+            console.warn(`[describe-me] two components are named ${componentName}: ${toPosix(relative(root, known.file))} and ${componentFile}. Only the first is documented.`);
+        }
+    }
+    return resolved;
+}
 /** The manifest is read in a browser, where paths are posix whatever wrote them. */
 function toPosix(path) {
     return path.split(sep).join('/');

package/dist/component-entries.js

@@ -5,7 +5,11 @@ export function componentEntries(modules, root) {
     for (const mod of modules) {
         for (const test of mod.tests) {
             if (test.component) {
-                entries.push({ testFile: resolve(root, mod.id), componentName: test.component.name });
+                entries.push({
+                    testFile: resolve(root, mod.id),
+                    componentName: test.component.name,
+                    componentFile: test.component.file,
+                });
             }
         }
     }

package/dist/extract-props.js

@@ -1,6 +1,8 @@
 import ts from 'typescript';
 /** Type names that mean "renderable children" once TypeScript has printed them. */
 const NODE_TYPE_NAMES = ['ReactNode', 'ReactElement', 'Element'];
+/** Calls that wrap a component function without changing its props. */
+const COMPONENT_WRAPPERS = ['forwardRef', 'memo'];
 /**
  * Read a component's props from its TypeScript type: one PropDoc per own prop,
  * with the literal choices and the default from the destructuring pattern.
@@ -33,23 +35,46 @@ export function extractProps(program, file, exportName) {
         .filter(isDeclaredInProject)
         .map((prop) => toPropDoc(checker, prop, declaration, defaults));
 }
-/** The exported symbol behind `exportName`, with `export { X } from` aliases followed. */
+/**
+ * The exported symbol behind `exportName`, with `export { X } from` aliases
+ * followed. A default export also answers to its local name, which is the name
+ * the plugin registers it under: `export default function Button` is `Button`.
+ */
 function exportedSymbol(checker, sourceFile, exportName) {
     const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
     if (!moduleSymbol) {
         return undefined;
     }
-    const exported = checker.getExportsOfModule(moduleSymbol).find((sym) => sym.name === exportName);
-    if (exported && exported.flags & ts.SymbolFlags.Alias) {
-        return checker.getAliasedSymbol(exported);
+    const exports = checker.getExportsOfModule(moduleSymbol);
+    const exported = exports.find((sym) => sym.name === exportName) ??
+        exports.find((sym) => {
+            return sym.name === 'default' && localNameOf(followAlias(checker, sym)) === exportName;
+        });
+    return exported && followAlias(checker, exported);
+}
+function followAlias(checker, symbol) {
+    if (symbol.flags & ts.SymbolFlags.Alias) {
+        return checker.getAliasedSymbol(symbol);
     }
-    return exported;
+    return symbol;
+}
+/** The name a symbol is declared under, which differs from its export name for `default`. */
+function localNameOf(symbol) {
+    const declaration = symbol.declarations?.[0];
+    const name = declaration && ts.getNameOfDeclaration(declaration);
+    return name && ts.isIdentifier(name) ? name.text : undefined;
 }
-/** The first call signature of the export, or null when it is not callable (not a component). */
+/**
+ * The call signature props are read from, or null when the export is not
+ * callable (not a component). A plain signature beats a generic one:
+ * styled-components 6 puts a generic `as`-aware signature first, whose props
+ * TypeScript cannot list until `as` is known, and inherits a plain one.
+ */
 function componentSignature(checker, component, declaration) {
     const type = checker.getTypeOfSymbolAtLocation(component, declaration);
-    const [signature] = type.getCallSignatures();
-    return signature ?? null;
+    const signatures = type.getCallSignatures();
+    const plain = signatures.find((signature) => !signature.typeParameters?.length);
+    return plain ?? signatures[0] ?? null;
 }
 /**
  * Drop props inherited from a library type. `Omit<ButtonHTMLAttributes<…>, …>`
@@ -61,14 +86,12 @@ function isDeclaredInProject(prop) {
     });
 }
 function toPropDoc(checker, prop, location, defaults) {
-    // An optional prop carries `| undefined`, which says nothing the `required`
-    // flag does not already say and makes every printed type noisier.
-    const type = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(prop, location));
+    const type = propType(checker, prop, location);
     const description = ts.displayPartsToString(prop.getDocumentationComment(checker));
     const shape = classify(checker, type);
     return {
         name: prop.name,
-        type: declaredTypeText(prop) ??
+        type: declaredTypeNode(prop)?.getText() ??
             checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation),
         required: !(prop.flags & ts.SymbolFlags.Optional),
         defaultValue: defaults.get(prop.name),
@@ -77,15 +100,42 @@ function toPropDoc(checker, prop, location, defaults) {
         description: description || undefined,
     };
 }
+/**
+ * The type a prop is classified by. An optional prop carries `| undefined`,
+ * which says nothing the `required` flag does not already say and makes every
+ * printed type noisier, so it is dropped.
+ *
+ * A generic component (`<T extends ElementType>(props: Props<T>)`) leaves prop
+ * types that still depend on `T`, such as `Props<T>['variant']`, which cannot
+ * be classified. The type the prop was declared with (`'primary' | …`) usually
+ * does not depend on `T`, and is used instead. One that does, such as
+ * `component?: T`, stays generic and is classified as `other`.
+ */
+function propType(checker, prop, location) {
+    const atLocation = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(prop, location));
+    const node = declaredTypeNode(prop);
+    if (!isGeneric(atLocation) || !node) {
+        return atLocation;
+    }
+    const declared = checker.getTypeFromTypeNode(node);
+    return isGeneric(declared) ? atLocation : checker.getNonNullableType(declared);
+}
+/** Whether a type still depends on a type parameter: `T`, `Props<T>['size']`, `T & {}`. */
+function isGeneric(type) {
+    if (type.flags & ts.TypeFlags.Instantiable) {
+        return true;
+    }
+    return type.isUnionOrIntersection() && type.types.some(isGeneric);
+}
 /**
  * The type as the author wrote it (`ReactNode`), when the prop has an
  * annotation. The checker would otherwise print the expanded alias, which for
  * ReactNode is a union longer than the table column.
  */
-function declaredTypeText(prop) {
+function declaredTypeNode(prop) {
     for (const declaration of prop.declarations ?? []) {
         if (ts.isPropertySignature(declaration) && declaration.type) {
-            return declaration.type.getText();
+            return declaration.type;
         }
     }
     return undefined;
@@ -160,9 +210,31 @@ function functionOf(declaration) {
     }
     return undefined;
 }
+/**
+ * The function an expression evaluates to, seen through the wrappers a
+ * component is commonly written with: `forwardRef(fn)`, `React.memo(fn)`,
+ * `memo(forwardRef<A, B>(fn))`, and `as` / `satisfies` / parentheses.
+ */
 function asFunction(expression) {
     if (ts.isArrowFunction(expression) || ts.isFunctionExpression(expression)) {
         return expression;
     }
-    return undefined;
+    if (ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isTypeAssertionExpression(expression) ||
+        ts.isNonNullExpression(expression)) {
+        return asFunction(expression.expression);
+    }
+    const [wrapped] = isComponentWrapperCall(expression) ? expression.arguments : [];
+    return wrapped ? asFunction(wrapped) : undefined;
+}
+/** `forwardRef(…)` or `memo(…)`, called bare or on a namespace such as `React`. */
+function isComponentWrapperCall(expression) {
+    if (!ts.isCallExpression(expression)) {
+        return false;
+    }
+    const callee = expression.expression;
+    const name = ts.isPropertyAccessExpression(callee) ? callee.name : callee;
+    return ts.isIdentifier(name) && COMPONENT_WRAPPERS.includes(name.text);
 }

package/dist/plugin.d.ts

@@ -13,6 +13,20 @@ export interface DescribeMeOptions {
     environment?: DescribeMeEnvironment;
     /** Output directory, relative to the Vitest root. Default: `.describe-me`. */
     outDir?: string;
+    /**
+     * Register the top-level exports of project modules, so a component is named
+     * after its export (`Button`) even when it is an anonymous `forwardRef`,
+     * `memo` or styled component, and its props are read from the right file.
+     * Default: true.
+     */
+    registerExports?: boolean;
+    /**
+     * DOM environments only. Load the browser build of styled-components (v5+)
+     * instead of the Node one, whose `createGlobalStyle` never inserts its CSS on
+     * the client: global resets and fonts would be missing from every snapshot.
+     * Applied when styled-components is installed. Default: true.
+     */
+    styledComponentsBrowserBuild?: boolean;
 }
 type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];
 /**

package/dist/plugin.js

@@ -1,4 +1,7 @@
+import { projectModulePath } from './project-module-path.js';
+import { registerExports } from './register-exports.js';
 import DescribeMeReporter from './reporter.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 = {
     react: {
@@ -26,7 +29,8 @@ function browserConfig(renderModule) {
         },
     };
 }
-function domConfig(userTest) {
+function domConfig(userConfig, options) {
+    const userTest = userConfig.test;
     const test = {
         setupFiles: ['@describe-me/vitest/setup-dom'],
         // Testing Library would otherwise unmount in its own afterEach, before the
@@ -41,7 +45,14 @@ function domConfig(userTest) {
     else if (userTest.css === false) {
         console.warn('describe-me: `test.css` is false, so imported stylesheets are stubbed and will be missing from the snapshots.');
     }
-    return { test };
+    const styledComponents = options.styledComponentsBrowserBuild === false
+        ? undefined
+        : styledComponentsBrowserBuild(userConfig.root ?? process.cwd());
+    if (!styledComponents) {
+        return { test };
+    }
+    console.info('describe-me: using the browser build of styled-components, for createGlobalStyle');
+    return { resolve: styledComponents.resolve, test: { ...test, ...styledComponents.test } };
 }
 /**
  * One-line integration: `plugins: [describeMe()]`.
@@ -55,6 +66,10 @@ function domConfig(userTest) {
 export function describeMe(options = {}) {
     const { enabled = true, framework = 'react', outDir } = options;
     let renderModule = RENDER_MODULES[framework].browser;
+    // Known once Vite has resolved its config. Vitest always serves; a production
+    // build that shares the config must not carry the export registration.
+    let root = '';
+    let serving = false;
     return {
         name: 'describe-me',
         enforce: 'pre',
@@ -68,7 +83,7 @@ export function describeMe(options = {}) {
             // 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.test);
+            const config = environment === 'browser' ? browserConfig(renderModule) : domConfig(userConfig, options);
             return { ...config, test: { ...config.test, reporters } };
         },
         async resolveId(source, importer) {
@@ -90,5 +105,41 @@ export function describeMe(options = {}) {
             }
             return resolved;
         },
+        configResolved(config) {
+            root = config.root;
+            serving = config.command === 'serve';
+        },
+        // Names components after their export (see registerExports). `order: 'post'`
+        // runs it after the TypeScript and JSX transforms, so it parses plain
+        // JavaScript, while the plugin as a whole stays `enforce: 'pre'` for the
+        // render redirect above.
+        transform: {
+            order: 'post',
+            handler(code, id) {
+                if (!enabled || options.registerExports === false || !serving) {
+                    return null;
+                }
+                const file = projectModulePath(id, root);
+                // Without the word `export` there is nothing to register: skip the parse.
+                if (file === null || !code.includes('export')) {
+                    return null;
+                }
+                let snippet;
+                // Parse errors are for the user's own tooling to report, and an older
+                // Vite may lack `this.parse`. This transform must never be the reason a
+                // module fails, so it steps aside instead.
+                try {
+                    snippet = registerExports(this.parse(code), file);
+                }
+                catch {
+                    return null;
+                }
+                if (snippet === null) {
+                    return null;
+                }
+                // Appending moves no code, so the source maps of earlier transforms stay valid.
+                return { code: code + snippet, map: null };
+            },
+        },
     };
 }

package/dist/print-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import type { Manifest } from '@describe-me/core/types';
+/**
+ * Warn, one line per kind, about what the manifest could not document. Prints
+ * nothing when everything is named, documented and loadable. The viewer shows
+ * the same list in its header.
+ */
+export declare function printDiagnostics(manifest: Manifest): void;

package/dist/print-diagnostics.js

@@ -0,0 +1,31 @@
+import { manifestDiagnostics } from '@describe-me/core/diagnostics';
+/** How many names or paths a warning line spells out before summing up the rest. */
+const SHOWN = 5;
+function listed(items) {
+    const shown = items.slice(0, SHOWN).join(', ');
+    const rest = items.length - SHOWN;
+    if (rest > 0) {
+        return `${shown} (+${rest} more)`;
+    }
+    return shown;
+}
+function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}
+/**
+ * Warn, one line per kind, about what the manifest could not document. Prints
+ * nothing when everything is named, documented and loadable. The viewer shows
+ * the same list in its header.
+ */
+export function printDiagnostics(manifest) {
+    const { anonymous, undocumented, assetsMissing } = manifestDiagnostics(manifest);
+    if (anonymous.length > 0) {
+        console.warn(`describe-me: ${plural(anonymous.length, 'test renders', 'tests render')} an anonymous component; export it from a project module or give it a displayName`);
+    }
+    if (undocumented.length > 0) {
+        console.warn(`describe-me: ${plural(undocumented.length, 'component has', 'components have')} no props docs: ${listed(undocumented.map((component) => component.name))}`);
+    }
+    if (assetsMissing.length > 0) {
+        console.warn(`describe-me: ${plural(assetsMissing.length, 'asset was', 'assets were')} not found in the project and will not load in the viewer: ${listed(assetsMissing)}`);
+    }
+}

package/dist/project-module-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The path of a Vite module id relative to the project root, with posix
+ * separators, or null when the module is not the project's own source: a
+ * virtual module (`\0…`), a request with a query (`?raw`, `?worker`), anything
+ * outside the root or in node_modules, a non-script file, or a test file.
+ */
+export declare function projectModulePath(id: string, root: string): string | null;

package/dist/project-module-path.js

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/** Modules that can export a component: JavaScript and TypeScript, with or without JSX. */
+const SCRIPT_MODULE = /\.[cm]?[jt]sx?$/;
+const TEST_MODULE = /\.(test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * The path of a Vite module id relative to the project root, with posix
+ * separators, or null when the module is not the project's own source: a
+ * virtual module (`\0…`), a request with a query (`?raw`, `?worker`), anything
+ * outside the root or in node_modules, a non-script file, or a test file.
+ */
+export function projectModulePath(id, root) {
+    if (root === '' || id.startsWith('\0') || id.includes('?')) {
+        return null;
+    }
+    if (id.includes('/node_modules/') || !SCRIPT_MODULE.test(id) || TEST_MODULE.test(id)) {
+        return null;
+    }
+    const path = relative(root, id);
+    if (path === '' || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+        return null;
+    }
+    return path.split(sep).join('/');
+}

package/dist/register-exports.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The part of an ESTree node every node has. Rollup (Vite 6 and 7) and
+ * Rolldown (Vite 8) both parse to ESTree, so structural types fit either
+ * without depending on their AST packages.
+ */
+export interface EstreeNode {
+    type: string;
+}
+/** A parsed module, as `this.parse(code)` returns it in a Vite plugin. */
+export interface EstreeProgram {
+    body: readonly EstreeNode[];
+}
+/**
+ * The code to append to a project module so that each value it exports is
+ * registered under its export name, or null when it exports nothing to
+ * register. A component is then named `Button` even when it is an anonymous
+ * `forwardRef` or a styled component.
+ *
+ * The appended code imports nothing: a user's module cannot always resolve
+ * `@describe-me/core`, and a bundled adapter may carry its own copy of it. It
+ * writes to a `WeakMap` on `globalThis` instead, and the first registration of
+ * a value wins, so the defining module beats a barrel that re-exports it.
+ *
+ * Only local bindings are referenced. Re-exports with `from` are skipped (the
+ * defining module registers the value itself), and so are anonymous default
+ * exports, which have no binding to point at.
+ */
+export declare function registerExports(program: EstreeProgram, file: string): string | null;

package/dist/register-exports.js

@@ -0,0 +1,118 @@
+import { EXPORT_REGISTRY_KEY } from '@describe-me/core/types';
+/**
+ * The code to append to a project module so that each value it exports is
+ * registered under its export name, or null when it exports nothing to
+ * register. A component is then named `Button` even when it is an anonymous
+ * `forwardRef` or a styled component.
+ *
+ * The appended code imports nothing: a user's module cannot always resolve
+ * `@describe-me/core`, and a bundled adapter may carry its own copy of it. It
+ * writes to a `WeakMap` on `globalThis` instead, and the first registration of
+ * a value wins, so the defining module beats a barrel that re-exports it.
+ *
+ * Only local bindings are referenced. Re-exports with `from` are skipped (the
+ * defining module registers the value itself), and so are anonymous default
+ * exports, which have no binding to point at.
+ */
+export function registerExports(program, file) {
+    const registrations = program.body.flatMap(registrationsOf);
+    if (registrations.length === 0) {
+        return null;
+    }
+    return snippetFor(registrations, file);
+}
+function registrationsOf(node) {
+    if (node.type === 'ExportNamedDeclaration') {
+        return namedExports(node);
+    }
+    if (node.type === 'ExportDefaultDeclaration') {
+        return defaultExport(node);
+    }
+    return [];
+}
+/** `export const A = …`, `export function A`, `export class A`, `export { a as A }`. */
+function namedExports(node) {
+    if (node.source) {
+        return [];
+    }
+    if (node.declaration) {
+        return declaredNames(node.declaration).map((name) => ({ name, local: name }));
+    }
+    return (node.specifiers ?? []).flatMap(specifierExport);
+}
+/** Identifiers only: a destructuring pattern would need its own walk for little gain. */
+function declaredNames(declaration) {
+    let ids = [];
+    if (declaration.type === 'VariableDeclaration') {
+        ids = declaration.declarations.map((declarator) => declarator.id);
+    }
+    else if (isFunctionOrClass(declaration)) {
+        ids = [declaration.id];
+    }
+    return ids.map(identifierName).filter((name) => name !== null);
+}
+function specifierExport(specifier) {
+    const local = identifierName(specifier.local);
+    const exported = exportedName(specifier.exported);
+    if (local === null || exported === null) {
+        return [];
+    }
+    // `export { Button as default }` is a default export: its local name says more.
+    const name = exported === 'default' ? local : exported;
+    return [{ name, local }];
+}
+/**
+ * `export default Button` and `export default function Button`, under the local
+ * name. A function or class expression (`export default (function A() {})`)
+ * binds nothing in the module scope, so it is left out like any anonymous one.
+ */
+function defaultExport(node) {
+    const { declaration } = node;
+    const local = identifierName(isFunctionOrClass(declaration) ? declaration.id : declaration);
+    if (local === null) {
+        return [];
+    }
+    return [{ name: local, local }];
+}
+function isFunctionOrClass(node) {
+    return node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration';
+}
+function identifierName(node) {
+    if (node?.type !== 'Identifier') {
+        return null;
+    }
+    return node.name;
+}
+/** `export { a as A }` or, since ES2022, `export { a as 'A' }`. */
+function exportedName(node) {
+    if (node.type === 'Literal') {
+        const { value } = node;
+        return typeof value === 'string' ? value : null;
+    }
+    return identifierName(node);
+}
+/**
+ * Appended after the module's last line, so no existing code moves and the
+ * source maps from earlier transforms stay valid. Starts on a new line and
+ * with a semicolon, in case the module ends in a comment or an unterminated
+ * expression.
+ */
+function snippetFor(registrations, file) {
+    const entries = registrations
+        .map(({ name, local }) => `[${JSON.stringify(name)}, ${local}]`)
+        .join(', ');
+    return [
+        '',
+        '// describe-me: name components after their export (registerExports option)',
+        ';((key, file, entries) => {',
+        '  const registry = globalThis[key] || (globalThis[key] = new WeakMap())',
+        '  for (const [name, value] of entries) {',
+        "    const isObject = typeof value === 'function' || (typeof value === 'object' && value !== null)",
+        '    if (isObject && !registry.has(value)) {',
+        '      registry.set(value, { name, file })',
+        '    }',
+        '  }',
+        `})(Symbol.for(${JSON.stringify(EXPORT_REGISTRY_KEY)}), ${JSON.stringify(file)}, [${entries}])`,
+        '',
+    ].join('\n');
+}

package/dist/reporter.d.ts

@@ -8,9 +8,11 @@ export default class DescribeMeReporter implements Reporter {
     private root;
     private outDir;
     private snapshots;
+    private assets;
     private modules;
     constructor(options?: DescribeMeReporterOptions);
     onInit(vitest: Vitest): void;
+    onTestRunStart(): void;
     /**
      * 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.
@@ -20,4 +22,6 @@ export default class DescribeMeReporter implements Reporter {
     onTestModuleEnd(module: TestModule): void;
     onTestRunEnd(): Promise<void>;
     private toManifestTest;
+    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    private writeSnapshot;
 }

package/dist/reporter.js

@@ -5,8 +5,10 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } 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 { componentEntries } from './component-entries.js';
+import { printDiagnostics } from './print-diagnostics.js';
 import { SnapshotStore } from './snapshot-store.js';
 import { testPath } from './test-path.js';
 export default class DescribeMeReporter {
@@ -14,6 +16,7 @@ export default class DescribeMeReporter {
     root = process.cwd();
     outDir = '';
     snapshots;
+    assets;
     modules = new Map();
     constructor(options = {}) {
         this.outDirOption = options.outDir ?? '.describe-me';
@@ -22,8 +25,12 @@ export default class DescribeMeReporter {
         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.seedFromPreviousRun();
     }
+    onTestRunStart() {
+        this.assets.startRun();
+    }
     /**
      * 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.
@@ -54,15 +61,22 @@ export default class DescribeMeReporter {
     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));
+        // 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();
         const manifest = {
             version: 1,
             generatedAt: new Date().toISOString(),
             root: this.root,
             modules,
             components,
+            assetsMissing,
         };
-        this.snapshots.collectGarbage(manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot))));
+        const snapshotFiles = manifest.modules.flatMap((mod) => mod.tests.flatMap((test) => test.frames.map((frame) => frame.snapshot)));
+        this.snapshots.collectGarbage(snapshotFiles);
+        this.assets.collectGarbage(snapshotFiles);
         writeFileSync(join(this.outDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        printDiagnostics(manifest);
     }
     toManifestTest(tc) {
         const record = tc.meta()[META_KEY];
@@ -73,7 +87,7 @@ export default class DescribeMeReporter {
             label: frame.label,
             at: frame.at,
             meta: frame.meta,
-            snapshot: this.snapshots.write(frame.snapshot),
+            snapshot: this.writeSnapshot(frame.snapshot, record?.origin),
         }));
         return {
             id: tc.id,
@@ -87,4 +101,8 @@ export default class DescribeMeReporter {
             frames,
         };
     }
+    /** Store one frame's DOM, with its project asset URLs pointing into the asset store. */
+    writeSnapshot(snapshot, origin) {
+        return this.snapshots.write(this.assets.rewrite(JSON.stringify(snapshot), origin));
+    }
 }

package/dist/snapshot-store.d.ts

@@ -5,8 +5,8 @@
 export declare class SnapshotStore {
     private readonly dir;
     constructor(outDir: string);
-    /** Write one snapshot and return its path relative to the manifest. */
-    write(snapshot: unknown): string;
+    /** Write one serialized snapshot and return its path relative to the manifest. */
+    write(json: string): string;
     /** Drop the files no manifest frame points at any more. */
     collectGarbage(referenced: Iterable<string>): void;
 }

package/dist/snapshot-store.js

@@ -11,9 +11,8 @@ export class SnapshotStore {
         this.dir = join(outDir, 'snapshots');
         mkdirSync(this.dir, { recursive: true });
     }
-    /** Write one snapshot and return its path relative to the manifest. */
-    write(snapshot) {
-        const json = JSON.stringify(snapshot);
+    /** Write one serialized snapshot and return its path relative to the manifest. */
+    write(json) {
         const hash = createHash('sha1').update(json).digest('hex').slice(0, 16);
         const file = `${hash}.json`;
         const abs = join(this.dir, file);

package/dist/styled-components-browser-build.d.ts

@@ -0,0 +1,15 @@
+import type { ViteUserConfig } from 'vitest/config';
+/**
+ * The Vite and Vitest config that makes a DOM environment load the browser
+ * build of styled-components, or undefined when the project does not use
+ * styled-components 5 or later.
+ *
+ * Vitest resolves the Node build, whose `createGlobalStyle` never inserts its
+ * CSS on the client, so global resets and fonts would be missing from every
+ * snapshot. The alias points `styled-components` at the browser ESM file. The
+ * optimizer is needed as well: jest-styled-components `require`s
+ * styled-components through Node, which ignores the alias, and would get a
+ * second instance whose styles its serializer cannot see. Bundling both
+ * together gives them one.
+ */
+export declare function styledComponentsBrowserBuild(root: string): ViteUserConfig | undefined;

package/dist/styled-components-browser-build.js

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+function resolverFor(root) {
+    // createRequire wants an absolute file inside the directory; it does not have to exist.
+    const requireFromRoot = createRequire(join(resolve(root), 'package.json'));
+    return (id) => {
+        try {
+            return requireFromRoot.resolve(id);
+        }
+        catch {
+            return undefined;
+        }
+    };
+}
+function withoutDotSlash(path) {
+    return path.replace(/^\.\//, '');
+}
+/** The file the package's `browser` map swaps its `module` entry for, relative to the package. */
+function browserModule(pkg) {
+    if (!pkg.module || !pkg.browser || typeof pkg.browser === 'string') {
+        return undefined;
+    }
+    const moduleEntry = withoutDotSlash(pkg.module);
+    for (const [from, to] of Object.entries(pkg.browser)) {
+        if (withoutDotSlash(from) === moduleEntry && typeof to === 'string') {
+            return to;
+        }
+    }
+    return undefined;
+}
+/**
+ * The Vite and Vitest config that makes a DOM environment load the browser
+ * build of styled-components, or undefined when the project does not use
+ * styled-components 5 or later.
+ *
+ * Vitest resolves the Node build, whose `createGlobalStyle` never inserts its
+ * CSS on the client, so global resets and fonts would be missing from every
+ * snapshot. The alias points `styled-components` at the browser ESM file. The
+ * optimizer is needed as well: jest-styled-components `require`s
+ * styled-components through Node, which ignores the alias, and would get a
+ * second instance whose styles its serializer cannot see. Bundling both
+ * together gives them one.
+ */
+export function styledComponentsBrowserBuild(root) {
+    const resolveFromRoot = resolverFor(root);
+    const manifest = resolveFromRoot('styled-components/package.json');
+    if (!manifest) {
+        return undefined;
+    }
+    const pkg = JSON.parse(readFileSync(manifest, 'utf8'));
+    const major = Number.parseInt(pkg.version ?? '', 10);
+    const browserFile = browserModule(pkg);
+    if (Number.isNaN(major) || major < 5 || !browserFile) {
+        return undefined;
+    }
+    const replacement = join(dirname(manifest), browserFile);
+    if (!existsSync(replacement)) {
+        return undefined;
+    }
+    const include = ['styled-components'];
+    if (resolveFromRoot('jest-styled-components')) {
+        include.push('jest-styled-components');
+    }
+    return {
+        resolve: { alias: [{ find: /^styled-components$/, replacement }] },
+        test: { deps: { optimizer: { client: { enabled: true, include } } } },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/vitest",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Vitest integration for describe-me: plugin, setup file and reporter",
   "keywords": [
     "vitest",
@@ -58,7 +58,7 @@
     "./dist/setup-dom.js"
   ],
   "dependencies": {
-    "@describe-me/core": "^0.3.0"
+    "@describe-me/core": "^0.4.0"
   },
   "peerDependencies": {
     "vitest": ">=4",