describe-me 0.5.3 → 0.6.0

package/README.md

@@ -1,59 +1,73 @@
 # describe-me
 
-The viewer and CLI of [describe-me](https://github.com/grzehub/describe-me):
-living component documentation generated from the Vitest tests you already have.
-`describe` blocks become the sidebar, each `it` is a story, each step is a frame
-you can scrub through.
+**Your tests are your stories.** The viewer and the `describe-me` CLI of
+describe-me: living component documentation generated from the Vitest tests
+you already have.
 
-It reads the `.describe-me/` directory that `@describe-me/vitest`'s reporter
-writes, and replays the snapshots in a sandboxed iframe.
+**[Read the docs](https://grzehub.github.io/describe-me/)** · open the viewer
+of the [browser-mode example](https://grzehub.github.io/describe-me/examples/react-browser/)
+or the [jsdom example](https://grzehub.github.io/describe-me/examples/react-jsdom/)
+· [Limitations](https://grzehub.github.io/describe-me/limitations.html)
 
-## Install
+describe-me captures the DOM after each step of a test and shows the result as
+a browsable catalog. `describe` blocks become the sidebar, each `it` is a
+story, and each step is a frame you can scrub through. Stories cannot rot,
+because they are tests. If one drifts from the component, CI goes red.
+
+Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
+recorded frames and Live in the viewer.
+
+## Which package do I need
+
+| Package               | What it is                                  | Install it              |
+| --------------------- | ------------------------------------------- | ----------------------- |
+| `describe-me`         | the viewer and the `describe-me` CLI (this) | yes                     |
+| `@describe-me/vitest` | the Vitest plugin, setup files and reporter | yes                     |
+| `@describe-me/react`  | `render` functions that record frames       | yes                     |
+| `@describe-me/core`   | the recorder and the manifest types         | no, the others bring it |
+
+## Quick start
 
 ```sh
 pnpm add -D describe-me @describe-me/vitest @describe-me/react
 ```
 
-`vite` is a peer dependency (Vitest requires it anyway): pnpm and npm install
-it automatically; with yarn, add `vite` to your `devDependencies`.
+```ts
+// vitest.config.ts
+import { describeMe } from '@describe-me/vitest/plugin'
+
+export default defineConfig({
+  plugins: [react(), describeMe()],
+  test: { environment: 'jsdom' }, // or your browser-mode settings
+})
+```
 
-All describe-me packages must be on the same version
-([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
+Run your tests, then `describe-me dev` opens the viewer.
+[Getting started](https://grzehub.github.io/describe-me/getting-started.html)
+walks through both environments. Keep all describe-me packages on one version
+([why](https://grzehub.github.io/describe-me/installation.html#lockstep)).
 
-## Usage
+## This package
 
 ```sh
-describe-me dev                  # viewer on http://localhost:6006, live while vitest --watch runs
-describe-me build --out docs     # self-contained static site: viewer + __data/
+describe-me dev                  # the viewer, repainted while vitest --watch runs
+describe-me build --out docs     # a static site: the viewer and its data
 ```
 
-| Flag                | Default              | Meaning                               |
-| ------------------- | -------------------- | ------------------------------------- |
-| `--data`            | `.describe-me`       | The directory the reporter wrote.     |
-| `--out`             | `describe-me-dist`   | Output directory for `build`.         |
-| `--port`            | `6006`               | Port for `dev`.                       |
-| `--no-vendor-fonts` | fonts are downloaded | `build`: keep web fonts on their CDN. |
-
-The viewer has search, collapsible suites, keyboard navigation, custom
-viewport sizes and shareable links
-([Viewer and CLI](https://grzehub.github.io/describe-me/viewer.html)).
-
-`build` downloads the web fonts that the preview head and the snapshots load
-from Google Fonts, Bunny Fonts and Fontsource on jsDelivr into the site, so
-the docs show them offline. Adobe Fonts stay remote, because their license
-does not allow self-hosting, and so do fonts on any other host. The build
-lists both.
-
-This needs the network. By default `build` connects to Google Fonts, Bunny
-Fonts and jsDelivr when the data loads fonts from them and the cache has no
-fresh copy. Downloads are cached in `node_modules/.cache/describe-me/fonts`,
-so after one online build later builds run offline. An unreachable host costs
-up to about 10 s once, then it is skipped. A font that does not download keeps
-loading from the network, and the build never fails because of it.
-`--no-vendor-fonts` keeps the build off the network, for CI without network
-access or with privacy rules.
-
-The static site uses relative URLs, so it works from a sub-path such as
-GitHub Pages.
-
-See the [docs](https://grzehub.github.io/describe-me/) for the full picture.
+`describe-me build --live` adds Live to the site. Read
+[what such a site contains](https://grzehub.github.io/describe-me/viewer.html#flag-live)
+before you publish it.
+
+`build` writes a site with relative URLs, so it works under a sub-path such as
+GitHub Pages. It needs a web server and does not open from disk. It also
+downloads web fonts from Google Fonts, Bunny Fonts and Fontsource into the
+site, so it shows them offline.
+[Viewer and CLI](https://grzehub.github.io/describe-me/viewer.html) lists every
+flag and what the viewer can do.
+
+`vite` is a peer dependency, which pnpm and npm install on their own. With
+yarn, add it to your `devDependencies`.
+
+## License
+
+MIT

package/dist-cli/build-live-preview.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Builds the live preview of the manifest's tests into `<out>/__live/` and
+ * writes `__live.json` next to the viewer, so the static site shows Live.
+ * On failure it leaves neither behind and throws the reason.
+ */
+export declare function buildLivePreview(data: string, out: string, root: string | undefined): Promise<void>;

package/dist-cli/build-live-preview.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { LIVE_PROTOCOL } from '@describe-me/core/types';
+import { codeOf } from './code-of.js';
+import { importBuildLive } from './import-build-live.js';
+import { LIVE_CONSEQUENCES } from './live-consequences.js';
+import { liveProject } from './live-project.js';
+import { reasonOf } from './reason-of.js';
+const STOPPED = LIVE_CONSEQUENCES.build;
+// The code `buildLive()` rejects with when the project's config sets `live: false`.
+const LIVE_OFF = 'DESCRIBE_ME_LIVE_OFF';
+const READY = { status: 'ready', base: '__live/' };
+/** The module ids of the manifest. Even with `--root` the build needs them, as its list of tests. */
+function manifestTestFiles(data) {
+    const file = join(resolve(data), 'manifest.json');
+    if (!existsSync(file)) {
+        throw new Error(`${file} is missing, ${STOPPED}. Run the tests first, because the manifest lists the tests to build.`);
+    }
+    try {
+        const manifest = JSON.parse(readFileSync(file, 'utf8'));
+        return manifest.modules.map((module) => module.id);
+    }
+    catch (error) {
+        throw new Error(`cannot read ${file} (${reasonOf(error)}), ${STOPPED}.`);
+    }
+}
+/** The reason for an error of `buildLive()`, which knows nothing of the CLI. */
+function buildFailure(error) {
+    if (codeOf(error) === LIVE_OFF) {
+        return new Error(`${reasonOf(error)}, but --live asks for it, ${STOPPED}. Remove one of the two.`);
+    }
+    return new Error(`the live build failed: ${reasonOf(error)}`);
+}
+async function buildProject(project, outDir, testFiles) {
+    const buildLive = await importBuildLive(project.root);
+    const built = await buildLive({ ...project, outDir, testFiles }).catch((error) => {
+        throw buildFailure(error);
+    });
+    if (built.protocol !== LIVE_PROTOCOL) {
+        throw new Error(`all describe-me packages must be on the same version. The live build in ${project.root} speaks protocol ${built.protocol}, this viewer ${LIVE_PROTOCOL}, ${STOPPED}.`);
+    }
+}
+/**
+ * Builds the live preview of the manifest's tests into `<out>/__live/` and
+ * writes `__live.json` next to the viewer, so the static site shows Live.
+ * On failure it leaves neither behind and throws the reason.
+ */
+export async function buildLivePreview(data, out, root) {
+    const outDir = join(resolve(out), '__live');
+    let testFiles;
+    try {
+        testFiles = manifestTestFiles(data);
+        await buildProject(liveProject(data, root, STOPPED), outDir, testFiles);
+    }
+    catch (error) {
+        rmSync(outDir, { recursive: true, force: true });
+        throw new Error(reasonOf(error), { cause: error });
+    }
+    const files = testFiles.length === 1 ? '1 test file' : `${testFiles.length} test files`;
+    writeFileSync(join(resolve(out), '__live.json'), JSON.stringify(READY));
+    process.stdout.write(`  ➜  Live preview: ${join(out, '__live')}/ (${files})\n`);
+}

package/dist-cli/code-of.d.ts

@@ -0,0 +1,2 @@
+/** The `code` of an error, such as `ERR_PACKAGE_PATH_NOT_EXPORTED`, or undefined. */
+export declare function codeOf(error: unknown): unknown;

package/dist-cli/code-of.js

@@ -0,0 +1,4 @@
+/** The `code` of an error, such as `ERR_PACKAGE_PATH_NOT_EXPORTED`, or undefined. */
+export function codeOf(error) {
+    return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+}

package/dist-cli/import-build-live.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What the CLI passes to `buildLive()` from `@describe-me/vitest/live`.
+ * Declared here, because `describe-me` does not depend on `@describe-me/vitest`.
+ */
+export interface LivePreviewBuildOptions {
+    /** The project root. */
+    root: string;
+    /** The Vitest config file, relative to `root`. Absent: the one Vitest picks there. */
+    configFile?: string;
+    /** Where the live page goes. */
+    outDir: string;
+    /** The module ids of the manifest. */
+    testFiles: string[];
+}
+/** The part of a finished live build that the CLI uses. */
+export interface LivePreviewBuild {
+    /** The live protocol of the project's describeMe() plugin. */
+    protocol: number;
+}
+/** `buildLive()` as the CLI calls it. */
+export type BuildLive = (options: LivePreviewBuildOptions) => Promise<LivePreviewBuild>;
+/**
+ * `buildLive()` from the project's own `@describe-me/vitest/live`, so the
+ * build runs the plugin the tests ran with. Throws the reason when the
+ * project has none.
+ */
+export declare function importBuildLive(root: string): Promise<BuildLive>;

package/dist-cli/import-build-live.js

@@ -0,0 +1,20 @@
+import { pathToFileURL } from 'node:url';
+import { LIVE_CONSEQUENCES } from './live-consequences.js';
+import { livePredates } from './live-predates.js';
+import { resolveLiveEntry } from './resolve-live-entry.js';
+/**
+ * `buildLive()` from the project's own `@describe-me/vitest/live`, so the
+ * build runs the plugin the tests ran with. Throws the reason when the
+ * project has none.
+ */
+export async function importBuildLive(root) {
+    const entry = resolveLiveEntry(root, LIVE_CONSEQUENCES.build);
+    const exported = await import(pathToFileURL(entry).href);
+    const build = typeof exported === 'object' && exported !== null && 'buildLive' in exported
+        ? exported.buildLive
+        : undefined;
+    if (typeof build !== 'function') {
+        throw livePredates(root, 'buildLive()', LIVE_CONSEQUENCES.build);
+    }
+    return build;
+}

package/dist-cli/import-create-live-server.d.ts

@@ -0,0 +1,20 @@
+import type { LiveProject } from './live-project.js';
+/**
+ * The part of the server from `@describe-me/vitest/live` that the CLI uses.
+ * Declared here, because `describe-me` does not depend on `@describe-me/vitest`.
+ */
+export interface LivePreviewServer {
+    /** The URL the live page is under. */
+    base: string;
+    /** The live protocol of the project's describeMe() plugin. */
+    protocol: number;
+    close(): Promise<void>;
+}
+/** `createLiveServer()` as the CLI calls it. */
+export type CreateLiveServer = (project: LiveProject) => Promise<LivePreviewServer>;
+/**
+ * `createLiveServer()` from the project's own `@describe-me/vitest/live`, so
+ * the preview runs the plugin the tests ran with. Throws the reason when the
+ * project has none.
+ */
+export declare function importCreateLiveServer(root: string): Promise<CreateLiveServer>;

package/dist-cli/import-create-live-server.js

@@ -0,0 +1,20 @@
+import { pathToFileURL } from 'node:url';
+import { LIVE_CONSEQUENCES } from './live-consequences.js';
+import { livePredates } from './live-predates.js';
+import { resolveLiveEntry } from './resolve-live-entry.js';
+/**
+ * `createLiveServer()` from the project's own `@describe-me/vitest/live`, so
+ * the preview runs the plugin the tests ran with. Throws the reason when the
+ * project has none.
+ */
+export async function importCreateLiveServer(root) {
+    const entry = resolveLiveEntry(root, LIVE_CONSEQUENCES.dev);
+    const exported = await import(pathToFileURL(entry).href);
+    const create = typeof exported === 'object' && exported !== null && 'createLiveServer' in exported
+        ? exported.createLiveServer
+        : undefined;
+    if (typeof create !== 'function') {
+        throw livePredates(root, 'the live preview', LIVE_CONSEQUENCES.dev);
+    }
+    return create;
+}

package/dist-cli/live-consequences.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How a reason goes on when the live preview cannot start or build: what
+ * that means for the command, so the same reason fits `dev` and `build --live`.
+ */
+export declare const LIVE_CONSEQUENCES: {
+    readonly dev: "so the viewer runs without Live";
+    readonly build: "so describe-me build --live stopped";
+};

package/dist-cli/live-consequences.js

@@ -0,0 +1,8 @@
+/**
+ * How a reason goes on when the live preview cannot start or build: what
+ * that means for the command, so the same reason fits `dev` and `build --live`.
+ */
+export const LIVE_CONSEQUENCES = {
+    dev: 'so the viewer runs without Live',
+    build: 'so describe-me build --live stopped',
+};

package/dist-cli/live-predates.d.ts

@@ -0,0 +1,2 @@
+/** The error for a project whose `@describe-me/vitest` is older than `feature`. */
+export declare function livePredates(root: string, feature: string, consequence: string): Error;

package/dist-cli/live-predates.js

@@ -0,0 +1,4 @@
+/** The error for a project whose `@describe-me/vitest` is older than `feature`. */
+export function livePredates(root, feature, consequence) {
+    return new Error(`the @describe-me/vitest in ${root} predates ${feature}, ${consequence}.`);
+}

package/dist-cli/live-preview-endpoint.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from 'vite';
+import type { LivePreviewInfo } from './live-preview-info.js';
+/**
+ * Answers `GET` and `HEAD /__live.json` on the viewer's dev server with what
+ * `info()` says at that moment. It is an inline plugin of the CLI, because
+ * the viewer's `vite.config.ts` cannot see the CLI's state.
+ */
+export declare function livePreviewEndpoint(info: () => LivePreviewInfo): Plugin;

package/dist-cli/live-preview-endpoint.js

@@ -0,0 +1,26 @@
+const PATH = '/__live.json';
+/**
+ * Answers `GET` and `HEAD /__live.json` on the viewer's dev server with what
+ * `info()` says at that moment. It is an inline plugin of the CLI, because
+ * the viewer's `vite.config.ts` cannot see the CLI's state.
+ */
+export function livePreviewEndpoint(info) {
+    return {
+        name: 'describe-me:live-preview',
+        configureServer(server) {
+            server.middlewares.use((request, response, next) => {
+                const path = (request.url ?? '').split('?')[0];
+                const readable = request.method === 'GET' || request.method === 'HEAD';
+                if (path !== PATH || !readable) {
+                    next();
+                    return;
+                }
+                const body = JSON.stringify(info());
+                response.setHeader('Content-Type', 'application/json');
+                response.setHeader('Cache-Control', 'no-store');
+                response.setHeader('Content-Length', Buffer.byteLength(body));
+                response.end(request.method === 'HEAD' ? undefined : body);
+            });
+        },
+    };
+}

package/dist-cli/live-preview-info.d.ts

@@ -0,0 +1,12 @@
+/** What `__live.json` next to the viewer says about the live preview. */
+export interface LivePreviewInfo {
+    status: 'starting' | 'ready' | 'off' | 'error';
+    /**
+     * The URL `live.html` is under, relative to `__live.json` or absolute:
+     * `__live/` on a static site, `http://localhost:5173/__describe-me/` under
+     * `describe-me dev`. Only with `ready`.
+     */
+    base?: string;
+    /** Why the live preview did not start. Only with `error`. */
+    error?: string;
+}

package/dist-cli/live-preview-info.js

@@ -0,0 +1 @@
+export {};

package/dist-cli/live-project.d.ts

@@ -0,0 +1,14 @@
+/** The project the live preview runs, as `createLiveServer()` and `buildLive()` take it. */
+export interface LiveProject {
+    /** The project root. */
+    root: string;
+    /** The Vitest config file, relative to `root`. Absent: the one Vitest picks there. */
+    configFile?: string;
+}
+/**
+ * The project of the live preview. `--root` replaces both the root and the
+ * config file of the manifest, so the preview uses the config Vitest picks in
+ * that directory. Throws the reason, followed by `consequence`, when there is
+ * neither.
+ */
+export declare function liveProject(data: string, root: string | undefined, consequence: string): LiveProject;

package/dist-cli/live-project.js

@@ -0,0 +1,31 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * The project of the live preview. `--root` replaces both the root and the
+ * config file of the manifest, so the preview uses the config Vitest picks in
+ * that directory. Throws the reason, followed by `consequence`, when there is
+ * neither.
+ */
+export function liveProject(data, root, consequence) {
+    if (root !== undefined) {
+        return { root: resolve(root) };
+    }
+    const dir = resolve(data);
+    const file = join(dir, 'manifest.json');
+    if (!existsSync(file)) {
+        throw new Error(`no manifest in ${dir} to find the project by, ${consequence}. Run the tests and start again, or pass --root.`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`cannot read ${file} (${message}), ${consequence}.`);
+    }
+    const { root: projectRoot, configFile } = manifest;
+    if (configFile !== undefined && !existsSync(resolve(projectRoot, configFile))) {
+        throw new Error(`the manifest names the config file ${configFile}, which is not in ${projectRoot}, ${consequence}. Run the tests again, or pass --root.`);
+    }
+    return { root: projectRoot, configFile };
+}

package/dist-cli/main.js

@@ -3,8 +3,8 @@ import { runBuild } from './run-build.js';
 import { runDev } from './run-dev.js';
 const USAGE = `describe-me — living component docs from your tests
 
-  describe-me dev   [--data .describe-me] [--port 6006]   viewer with live updates
-  describe-me build [--data .describe-me] [--out describe-me-dist] [--no-vendor-fonts]   static site
+  describe-me dev   [--data .describe-me] [--port 6006] [--no-live] [--root <dir>]   viewer that follows the test runs, and the live preview
+  describe-me build [--data .describe-me] [--out describe-me-dist] [--no-vendor-fonts] [--live] [--root <dir>]   static site
 `;
 /** Entry point of the `describe-me` binary. */
 async function main() {
@@ -14,10 +14,14 @@ async function main() {
         return;
     }
     if (options.command === 'build') {
-        await runBuild(options.data, options.out, { vendorFonts: options.vendorFonts });
+        await runBuild(options.data, options.out, {
+            vendorFonts: options.vendorFonts,
+            live: options.live,
+            root: options.root,
+        });
         return;
     }
-    await runDev(options.data, options.port);
+    await runDev(options.data, options.port, { live: options.live, root: options.root });
 }
 main().catch((error) => {
     process.stderr.write(`describe-me: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist-cli/parse-args.d.ts

@@ -9,9 +9,20 @@ export interface CliOptions {
     port: number;
     /** `build`: download web fonts from known font hosts into the site. */
     vendorFonts: boolean;
+    /**
+     * `dev`: start the live preview next to the viewer. `build`: build it into
+     * the site. On for `dev` and off for `build`, unless `--live` or `--no-live` says otherwise.
+     */
+    live: boolean;
+    /**
+     * `dev` and `build --live`: the project root of the live preview, instead of
+     * the manifest's root and config file.
+     */
+    root: string | undefined;
 }
 /**
- * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]`
- * into options with defaults.
+ * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]
+ * [--live | --no-live] [--root dir]` into options with defaults. `build` ignores
+ * `--port`, and `--root` without `--live`.
  */
 export declare function parseArgs(argv: string[]): CliOptions;

package/dist-cli/parse-args.js

@@ -9,8 +9,9 @@ function commandFrom(positional, help) {
     return 'dev';
 }
 /**
- * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]`
- * into options with defaults.
+ * Turn `describe-me <command> [--data dir] [--out dir] [--port n] [--no-vendor-fonts]
+ * [--live | --no-live] [--root dir]` into options with defaults. `build` ignores
+ * `--port`, and `--root` without `--live`.
  */
 export function parseArgs(argv) {
     const { values, positionals } = parseNodeArgs({
@@ -23,13 +24,18 @@ export function parseArgs(argv) {
             port: { type: 'string', default: '6006' },
             help: { type: 'boolean', short: 'h', default: false },
             'vendor-fonts': { type: 'boolean', default: true },
+            live: { type: 'boolean' },
+            root: { type: 'string' },
         },
     });
+    const command = commandFrom(positionals[0], values.help);
     return {
-        command: commandFrom(positionals[0], values.help),
+        command,
         data: values.data,
         out: values.out,
         port: Number(values.port),
         vendorFonts: values['vendor-fonts'],
+        live: values.live ?? command === 'dev',
+        root: values.root,
     };
 }

package/dist-cli/reason-of.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The message of an error as the CLI prints it after its own
+ * `describe-me: `: without colours, and without a prefix of its own.
+ */
+export declare function reasonOf(error: unknown): string;

package/dist-cli/reason-of.js

@@ -0,0 +1,13 @@
+const PREFIX = 'describe-me: ';
+// Vite and its bundler colour their errors for the terminal.
+const COLOURS = new RegExp(String.raw `\u001b\[[\d;]*m`, 'g');
+/**
+ * The message of an error as the CLI prints it after its own
+ * `describe-me: `: without colours, and without a prefix of its own.
+ */
+export function reasonOf(error) {
+    const message = (error instanceof Error ? error.message : String(error))
+        .replace(COLOURS, '')
+        .trim();
+    return message.startsWith(PREFIX) ? message.slice(PREFIX.length) : message;
+}

package/dist-cli/resolve-live-entry.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The file `@describe-me/vitest/live` resolves to from the project root.
+ * Throws the reason, followed by `consequence`, when the project has none.
+ */
+export declare function resolveLiveEntry(root: string, consequence: string): string;

package/dist-cli/resolve-live-entry.js

@@ -0,0 +1,42 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { codeOf } from './code-of.js';
+import { livePredates } from './live-predates.js';
+function notFound(root, consequence) {
+    return new Error(`cannot find @describe-me/vitest from ${root}, ${consequence}. Pass --root with the project directory.`);
+}
+/** Whether `node_modules/@describe-me/vitest` is in `root` or a directory above it. */
+function isInstalledFrom(root) {
+    for (let dir = root;; dir = dirname(dir)) {
+        if (existsSync(join(dir, 'node_modules', '@describe-me', 'vitest', 'package.json'))) {
+            return true;
+        }
+        if (dirname(dir) === dir) {
+            return false;
+        }
+    }
+}
+/**
+ * The file `@describe-me/vitest/live` resolves to from the project root.
+ * Throws the reason, followed by `consequence`, when the project has none.
+ */
+export function resolveLiveEntry(root, consequence) {
+    // The bin shims of package managers put their own store on NODE_PATH, which
+    // `resolve()` searches too. Only the project's own node_modules count.
+    if (!isInstalledFrom(root)) {
+        throw notFound(root, consequence);
+    }
+    try {
+        return createRequire(join(root, 'package.json')).resolve('@describe-me/vitest/live');
+    }
+    catch (error) {
+        if (codeOf(error) === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+            throw livePredates(root, 'the live preview', consequence);
+        }
+        if (codeOf(error) === 'MODULE_NOT_FOUND') {
+            throw notFound(root, consequence);
+        }
+        throw error;
+    }
+}

package/dist-cli/run-build.d.ts

@@ -2,9 +2,15 @@
 export interface RunBuildOptions {
     /** Download web fonts from known font hosts into the site. */
     vendorFonts: boolean;
+    /** Build the live preview into the site as `__live/`. */
+    live: boolean;
+    /** The project root of the live preview. Default: the manifest's `root` and `configFile`. */
+    root?: string;
 }
 /**
  * Produce a self-contained static site: the viewer plus the data directory
- * under `__data/`. Font vendoring works on that copy and never fails the build.
+ * under `__data/`, and with `live` the live preview under `__live/`. A live
+ * build that fails stops the command. Font vendoring works on the copy of the
+ * data and never fails the build.
  */
 export declare function runBuild(data: string, out: string, options: RunBuildOptions): Promise<void>;

package/dist-cli/run-build.js

@@ -1,13 +1,16 @@
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { build } from 'vite';
+import { buildLivePreview } from './build-live-preview.js';
 import { fontCacheDir } from './font-cache-dir.js';
 import { printVendorReport } from './print-vendor-report.js';
 import { vendorFonts } from './vendor-fonts.js';
 import { viewerRoot } from './viewer-root.js';
 /**
  * Produce a self-contained static site: the viewer plus the data directory
- * under `__data/`. Font vendoring works on that copy and never fails the build.
+ * under `__data/`, and with `live` the live preview under `__live/`. A live
+ * build that fails stops the command. Font vendoring works on the copy of the
+ * data and never fails the build.
  */
 export async function runBuild(data, out, options) {
     process.env.DESCRIBE_ME_DIR = resolve(data);
@@ -17,6 +20,10 @@ export async function runBuild(data, out, options) {
         configFile: resolve(root, 'vite.config.ts'),
         build: { outDir: resolve(out), emptyOutDir: true },
     });
+    // After the viewer, whose build empties `out` and so removes an old `__live/` and `__live.json`.
+    if (options.live) {
+        await buildLivePreview(data, out, options.root);
+    }
     if (!options.vendorFonts) {
         return;
     }