@describe-me/core 0.5.3 → 0.6.0

package/README.md

@@ -1,47 +1,69 @@
 # @describe-me/core
 
-The framework-agnostic heart of [describe-me](https://github.com/grzehub/describe-me):
-the recorder that captures the DOM, the `step()` helper, and the JSON manifest
-types the viewer reads. Snapshots are serialized DOM via `rrweb-snapshot`, so
-nothing here knows about React.
+**Your tests are your stories.** The recorder and the manifest types of
+describe-me: living component documentation generated from the Vitest tests
+you already have.
 
-Most people never install this package directly — `@describe-me/react` and
-`@describe-me/vitest` depend on it, and both re-export `step()`.
+**[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.
 
-```sh
-pnpm add -D @describe-me/core
-```
+Status: prototype. React 18 and 19, Vitest 4 and 5 in browser mode or jsdom,
+recorded frames and Live in the viewer.
 
-All describe-me packages must be on the same version
-([One version for all packages](https://grzehub.github.io/describe-me/installation.html#lockstep)).
+## Which package do I need
 
-## Usage
+| Package               | What it is                                  | Install it              |
+| --------------------- | ------------------------------------------- | ----------------------- |
+| `describe-me`         | the viewer and the `describe-me` CLI        | 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 (this)  | no, the others bring it |
 
-`step()` names a phase of a test. The DOM is captured after the body resolves,
-and the label becomes the frame's caption in the viewer.
+## Quick start
+
+```sh
+pnpm add -D describe-me @describe-me/vitest @describe-me/react
+```
 
 ```ts
-import { step } from '@describe-me/core'
+// vitest.config.ts
+import { describeMe } from '@describe-me/vitest/plugin'
 
-await step('open the menu', () => screen.getByRole('button', { name: 'Menu' }).click())
+export default defineConfig({
+  plugins: [react(), describeMe()],
+  test: { environment: 'jsdom' }, // or your browser-mode settings
+})
 ```
 
-`elementLabel()` names a DOM element the way frame labels do, e.g.
-`button "Save"`, for adapters that record their own interactions.
+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)).
+
+## This package
+
+The framework-agnostic heart of describe-me. Snapshots are serialized DOM via
+`rrweb-snapshot`, so nothing here knows about React. You need it directly only
+to write an adapter for another framework or to read the output yourself.
+
+| Entry point                                                                                                    | What it holds                                                              |
+| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [`@describe-me/core`](https://grzehub.github.io/describe-me/api.html#entry-core)                               | `step()`, `recorder` and `elementLabel()`, for adapters                    |
+| [`@describe-me/core/types`](https://grzehub.github.io/describe-me/api.html#entry-core-types)                   | the types of `.describe-me/manifest.json`                                  |
+| [`@describe-me/core/diagnostics`](https://grzehub.github.io/describe-me/api.html#entry-core-diagnostics)       | what a manifest could not document                                         |
+| [`@describe-me/core/css-references`](https://grzehub.github.io/describe-me/api.html#entry-core-css-references) | the `url()` and `@import` references in CSS text                           |
+| [`@describe-me/core/live`](https://grzehub.github.io/describe-me/api.html#entry-core-live)                     | the live page's state and its messages to the viewer, for the live preview |
 
-Such adapters call `recorder.beforeInteraction()` before they change the page,
-so a deferred render frame is taken first. As the capture's `generation`, they
-pass `recorder.generation`, read when the interaction began, so a capture that
-outlives its test is dropped. `recorder.flush()` waits for the captures in
-flight and takes a deferred render frame.
+[How it works](https://grzehub.github.io/describe-me/how-it-works.html) explains
+the recorder and the output directory.
 
-The manifest types live in `@describe-me/core/types`, for tools that want to
-read `.describe-me/manifest.json` themselves. Stored snapshots point into
-`assets/` and `styles/` through `ASSET_URL_PREFIX` and `STYLE_URL_PREFIX`
-([The output directory](https://grzehub.github.io/describe-me/how-it-works.html#storage) in
-the docs). `@describe-me/core/css-references` lists the `url()` and
-`@import` references in CSS text.
+## License
 
-See the [docs](https://grzehub.github.io/describe-me/) for the full picture.
+MIT

package/dist/is-live-stop.d.ts

@@ -0,0 +1,2 @@
+/** Whether a thrown value is the live page's stop signal rather than a failure. */
+export declare function isLiveStop(value: unknown): boolean;

package/dist/is-live-stop.js

@@ -0,0 +1,5 @@
+import { liveState } from './live-state.js';
+/** Whether a thrown value is the live page's stop signal rather than a failure. */
+export function isLiveStop(value) {
+    return value === liveState().stop;
+}

package/dist/live-inert.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A value that takes any property access, call or `new` and gives back an
+ * inert value again. Test code after the first render never runs, but it must
+ * import, and hooks may call it. `await` ends on it, because it has no `then`.
+ */
+export declare function liveInert(): unknown;

package/dist/live-inert.js

@@ -0,0 +1,34 @@
+let inert;
+function createInert() {
+    // A plain function, so the value can be called and constructed.
+    const value = new Proxy(function inertTarget() { }, {
+        get(_target, key) {
+            if (key === 'then') {
+                return undefined;
+            }
+            if (key === Symbol.toPrimitive) {
+                return () => '';
+            }
+            if (key === Symbol.iterator) {
+                return () => [][Symbol.iterator]();
+            }
+            return value;
+        },
+        apply() {
+            return value;
+        },
+        construct() {
+            return value;
+        },
+    });
+    return value;
+}
+/**
+ * A value that takes any property access, call or `new` and gives back an
+ * inert value again. Test code after the first render never runs, but it must
+ * import, and hooks may call it. `await` ends on it, because it has no `then`.
+ */
+export function liveInert() {
+    inert ??= createInert();
+    return inert;
+}

package/dist/live-state.d.ts

@@ -0,0 +1,20 @@
+import type { LiveStatus } from './types.js';
+/** What the height observer keeps between animation frames. */
+interface LiveHeightState {
+    observing: boolean;
+    queued: boolean;
+    reported: number | null;
+}
+/** Everything one live page shares, whichever copy of core reads it. */
+export interface LiveState {
+    status: LiveStatus | null;
+    stop: Error;
+    height: LiveHeightState;
+}
+/**
+ * The state of the live page. Vite can serve two copies of core, one bundled
+ * with an adapter and one from source, so the state lives on `globalThis`,
+ * like the recorder.
+ */
+export declare function liveState(): LiveState;
+export {};

package/dist/live-state.js

@@ -0,0 +1,20 @@
+const LIVE_KEY = Symbol.for('describe-me.live');
+function createStop() {
+    const stop = new Error('describe-me: the live preview stops the test at its first render');
+    stop.name = 'LiveStop';
+    return stop;
+}
+/**
+ * The state of the live page. Vite can serve two copies of core, one bundled
+ * with an adapter and one from source, so the state lives on `globalThis`,
+ * like the recorder.
+ */
+export function liveState() {
+    const scope = globalThis;
+    scope[LIVE_KEY] ??= {
+        status: null,
+        stop: createStop(),
+        height: { observing: false, queued: false, reported: null },
+    };
+    return scope[LIVE_KEY];
+}

package/dist/live-status.d.ts

@@ -0,0 +1,3 @@
+import type { LiveStatus } from './types.js';
+/** The status the live page reported so far, or null before the first one. */
+export declare function liveStatus(): LiveStatus | null;

package/dist/live-status.js

@@ -0,0 +1,5 @@
+import { liveState } from './live-state.js';
+/** The status the live page reported so far, or null before the first one. */
+export function liveStatus() {
+    return liveState().status;
+}

package/dist/live-stop.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The page's one stop signal. The live render throws it to end the test at
+ * its first render, and the runner tells it apart from a failure.
+ */
+export declare function liveStop(): Error;

package/dist/live-stop.js

@@ -0,0 +1,8 @@
+import { liveState } from './live-state.js';
+/**
+ * The page's one stop signal. The live render throws it to end the test at
+ * its first render, and the runner tells it apart from a failure.
+ */
+export function liveStop() {
+    return liveState().stop;
+}

package/dist/live.d.ts

@@ -0,0 +1,7 @@
+export { isLiveStop } from './is-live-stop.js';
+export { liveInert } from './live-inert.js';
+export { liveStatus } from './live-status.js';
+export { liveStop } from './live-stop.js';
+export { observeLiveHeight } from './observe-live-height.js';
+export { postLiveMessage } from './post-live-message.js';
+export { reportLiveStatus } from './report-live-status.js';

package/dist/live.js

@@ -0,0 +1,8 @@
+// For the live preview page, not for tests: its status, messages, stop signal and height.
+export { isLiveStop } from './is-live-stop.js';
+export { liveInert } from './live-inert.js';
+export { liveStatus } from './live-status.js';
+export { liveStop } from './live-stop.js';
+export { observeLiveHeight } from './observe-live-height.js';
+export { postLiveMessage } from './post-live-message.js';
+export { reportLiveStatus } from './report-live-status.js';

package/dist/observe-live-height.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reports the height of the page's content now and whenever it changes, so
+ * the viewer can fit its frame. `scrollHeight` would never drop below the
+ * height of the frame itself. Runs once per page.
+ */
+export declare function observeLiveHeight(): void;

package/dist/observe-live-height.js

@@ -0,0 +1,83 @@
+import { liveState } from './live-state.js';
+import { postLiveMessage } from './post-live-message.js';
+/** Room under the lowest box, as the viewer leaves under a recorded frame. */
+const BOTTOM_MARGIN = 20;
+const SKIPPED_TAGS = new Set(['SCRIPT', 'NOSCRIPT', 'STYLE', 'LINK', 'META', 'TITLE', 'TEMPLATE']);
+function hasOwnText(element) {
+    return Array.from(element.childNodes).some((node) => node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '');
+}
+/**
+ * Whether an element draws something itself. Layout wrappers can stretch to
+ * the height of the frame, and would keep the height from ever shrinking.
+ */
+function paints(element) {
+    if (element.children.length === 0 || hasOwnText(element)) {
+        return true;
+    }
+    const style = getComputedStyle(element);
+    const hasBackground = style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
+    const hasBorder = parseFloat(style.borderTopWidth) > 0 || parseFloat(style.borderBottomWidth) > 0;
+    return hasBackground || hasBorder || style.boxShadow !== 'none';
+}
+function* elementsIn(root) {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        yield node;
+    }
+}
+/** The bottom of the lowest painted element in page pixels, plus the margin, or 0 for none. */
+function contentHeight() {
+    let bottom = 0;
+    for (const element of elementsIn(document.body)) {
+        if (SKIPPED_TAGS.has(element.tagName) || !paints(element)) {
+            continue;
+        }
+        const rect = element.getBoundingClientRect();
+        if (rect.width > 0 && rect.height > 0) {
+            bottom = Math.max(bottom, rect.bottom + window.scrollY);
+        }
+    }
+    return bottom > 0 ? Math.ceil(bottom + BOTTOM_MARGIN) : 0;
+}
+function postHeight() {
+    const height = liveState().height;
+    const measured = contentHeight();
+    if (measured === height.reported) {
+        return;
+    }
+    height.reported = measured;
+    postLiveMessage({ type: 'size', height: measured });
+}
+function schedule() {
+    const height = liveState().height;
+    if (height.queued) {
+        return;
+    }
+    height.queued = true;
+    requestAnimationFrame(() => {
+        height.queued = false;
+        postHeight();
+    });
+}
+/**
+ * Reports the height of the page's content now and whenever it changes, so
+ * the viewer can fit its frame. `scrollHeight` would never drop below the
+ * height of the frame itself. Runs once per page.
+ */
+export function observeLiveHeight() {
+    const height = liveState().height;
+    if (height.observing) {
+        return;
+    }
+    height.observing = true;
+    new ResizeObserver(schedule).observe(document.body);
+    new MutationObserver(schedule).observe(document.body, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        characterData: true,
+    });
+    window.addEventListener('resize', schedule);
+    void document.fonts.ready.then(schedule);
+    postHeight();
+}

package/dist/post-live-message.d.ts

@@ -0,0 +1,7 @@
+import { type LiveReport } from './types.js';
+/**
+ * Posts a report to the viewer that frames the live page. It goes only to the
+ * origin the page URL names, so another site that frames the page learns
+ * nothing.
+ */
+export declare function postLiveMessage(report: LiveReport): void;

package/dist/post-live-message.js

@@ -0,0 +1,32 @@
+import { LIVE_MESSAGE_SOURCE } from './types.js';
+/** The viewer's origin from the page URL, when it is exactly the origin of an http(s) URL. */
+function viewerOrigin() {
+    const origin = new URLSearchParams(window.location.search).get('origin');
+    if (origin === null) {
+        return null;
+    }
+    try {
+        const url = new URL(origin);
+        const web = url.protocol === 'http:' || url.protocol === 'https:';
+        return web && url.origin === origin ? origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Posts a report to the viewer that frames the live page. It goes only to the
+ * origin the page URL names, so another site that frames the page learns
+ * nothing.
+ */
+export function postLiveMessage(report) {
+    if (window.parent === window) {
+        return;
+    }
+    const origin = viewerOrigin();
+    if (origin === null) {
+        return;
+    }
+    const message = { source: LIVE_MESSAGE_SOURCE, ...report };
+    window.parent.postMessage(message, origin);
+}

package/dist/report-live-status.d.ts

@@ -0,0 +1,6 @@
+import type { LiveStatus } from './types.js';
+/**
+ * Reports how the live page ended up, on `<html data-describe-me-live>` and to
+ * the viewer. The first status of a page is final, so later calls do nothing.
+ */
+export declare function reportLiveStatus(status: LiveStatus, detail?: string): void;

package/dist/report-live-status.js

@@ -0,0 +1,28 @@
+import { liveState } from './live-state.js';
+import { observeLiveHeight } from './observe-live-height.js';
+import { postLiveMessage } from './post-live-message.js';
+/** Writes the status on the page itself, so the page is never blank and the viewer can fit it. */
+function showStatus(status, detail) {
+    const note = document.createElement('p');
+    note.textContent = detail === undefined ? status : `${status}: ${detail}`;
+    note.style.whiteSpace = 'pre-wrap';
+    document.body.append(note);
+}
+/**
+ * Reports how the live page ended up, on `<html data-describe-me-live>` and to
+ * the viewer. The first status of a page is final, so later calls do nothing.
+ */
+export function reportLiveStatus(status, detail) {
+    const state = liveState();
+    if (state.status !== null) {
+        return;
+    }
+    state.status = status;
+    document.documentElement.dataset.describeMeLive = status;
+    const report = detail === undefined ? { type: 'status', status } : { type: 'status', status, detail };
+    postLiveMessage(report);
+    if (status !== 'mounted') {
+        showStatus(status, detail);
+    }
+    observeLiveHeight();
+}

package/dist/types.d.ts

@@ -178,6 +178,11 @@ export interface Manifest {
     generator?: ManifestGenerator;
     generatedAt: string;
     root: string;
+    /**
+     * The Vitest config file of the run, relative to `root`, with `/` separators.
+     * Absent when the run had no config file, and in manifests written before 0.6.
+     */
+    configFile?: string;
     modules: ManifestModule[];
     /** Keyed by component name, as reported by the framework adapter. */
     components: Record<string, ComponentDoc>;
@@ -249,3 +254,32 @@ export interface ManifestDiagnostics {
     /** Problems in the project's setup that can make tests fail. */
     setupWarnings: string[];
 }
+/** How the live preview page ended up. */
+export type LiveStatus = 'mounted' | 'no-render' | 'not-found' | 'import-failed' | 'setup-failed' | 'failed';
+/** The `source` of every message the live preview page posts. */
+export declare const LIVE_MESSAGE_SOURCE: "describe-me-live";
+/** The version of the contract between the viewer, the plugin's live mode and the live page. */
+export declare const LIVE_PROTOCOL: 1;
+/** What the live page reports, without the `source` field. */
+export type LiveReport = {
+    type: 'status';
+    status: LiveStatus;
+    detail?: string;
+} | {
+    type: 'size';
+    height: number;
+} | {
+    type: 'action';
+    name: string;
+    args: string[];
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'notice';
+    message: string;
+};
+/** A message the live page posts to the viewer around it. */
+export type LiveMessage = LiveReport & {
+    source: typeof LIVE_MESSAGE_SOURCE;
+};

package/dist/types.js

@@ -23,3 +23,7 @@ export const STYLE_URL_PREFIX = 'describe-me-style:';
 export const META_KEY = 'describeMe';
 /** The name adapters fall back to when a component has no usable name. */
 export const ANONYMOUS_COMPONENT = 'Anonymous';
+/** The `source` of every message the live preview page posts. */
+export const LIVE_MESSAGE_SOURCE = 'describe-me-live';
+/** The version of the contract between the viewer, the plugin's live mode and the live page. */
+export const LIVE_PROTOCOL = 1;

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@describe-me/core",
-  "version": "0.5.3",
-  "description": "Recorder and manifest types for describe-me: living component docs from your tests",
+  "version": "0.6.0",
+  "description": "Living component documentation from your Vitest tests: the recorder and manifest types of describe-me",
   "keywords": [
     "vitest",
+    "react",
     "storybook",
+    "storybook alternative",
     "component documentation",
-    "visual testing",
+    "living documentation",
+    "jsdom",
     "testing"
   ],
   "license": "MIT",
@@ -42,6 +45,10 @@
     "./css-references": {
       "types": "./dist/css-references.d.ts",
       "default": "./dist/css-references.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
     }
   },
   "files": [