@describe-me/core 0.3.0 → 0.5.0-next.0

package/README.md

@@ -25,8 +25,14 @@ import { step } from '@describe-me/core'
 await step('open the menu', () => screen.getByRole('button', { name: 'Menu' }).click())
 ```
 
+`elementLabel()` names a DOM element the way frame labels do, e.g.
+`button "Save"`, for adapters that record their own interactions.
+
 The manifest types live in `@describe-me/core/types`, for tools that want to
-read `.describe-me/manifest.json` themselves.
+read `.describe-me/manifest.json` themselves. Stored snapshots point into
+`assets/` and `styles/` through `ASSET_URL_PREFIX` and `STYLE_URL_PREFIX`
+([Output directory](https://github.com/grzehub/describe-me#output-directory) in
+the root README).
 
 See the [root README](https://github.com/grzehub/describe-me#readme) for the
 full picture.

package/dist/describe-component-type.d.ts

@@ -0,0 +1,14 @@
+import { type ComponentInfo } from './types.js';
+/** How a component type is shown and where it was defined, when that is known. */
+type ComponentIdentity = Pick<ComponentInfo, 'name' | 'file'>;
+/**
+ * Name a component type (an element's `type`) the way its author would.
+ *
+ * The export it was registered under wins, because an anonymous `forwardRef`
+ * or a styled component has no name of its own. Then an explicit
+ * `displayName`, then the function's name, then the same again for the
+ * component a `memo` or `forwardRef` wraps. Shapes are detected structurally,
+ * so no framework is imported. `Anonymous` when nothing names it.
+ */
+export declare function describeComponentType(type: unknown): ComponentIdentity;
+export {};

package/dist/describe-component-type.js

@@ -0,0 +1,72 @@
+import { ANONYMOUS_COMPONENT, EXPORT_REGISTRY_KEY, } from './types.js';
+/** `memo(forwardRef(memo(…)))` is as deep as real code goes; the bound only guards against cycles. */
+const MAX_UNWRAP_DEPTH = 5;
+/**
+ * Display names styled-components gives when none was set: `styled.p`,
+ * `Styled(Button)`. They say which element is styled, not which component it is.
+ */
+const STYLED_DEFAULT_NAMES = [/^styled\./, /^Styled\(/];
+/**
+ * Name a component type (an element's `type`) the way its author would.
+ *
+ * The export it was registered under wins, because an anonymous `forwardRef`
+ * or a styled component has no name of its own. Then an explicit
+ * `displayName`, then the function's name, then the same again for the
+ * component a `memo` or `forwardRef` wraps. Shapes are detected structurally,
+ * so no framework is imported. `Anonymous` when nothing names it.
+ */
+export function describeComponentType(type) {
+    if (typeof type === 'string') {
+        return { name: type };
+    }
+    return identify(type, 0) ?? { name: ANONYMOUS_COMPONENT };
+}
+function identify(type, depth) {
+    if (!isComponentLike(type)) {
+        return null;
+    }
+    const registered = registeredExport(type);
+    if (registered) {
+        return { name: registered.name, file: registered.file };
+    }
+    const { displayName, name } = type;
+    if (isNonEmptyString(displayName) && !isStyledDefault(displayName)) {
+        return { name: displayName };
+    }
+    if (typeof type === 'function' && isNonEmptyString(name)) {
+        return { name };
+    }
+    // An unregistered styled component: its render function is named after the
+    // library's internals (`forwardRefRender`), so `styled.p` is the best name left.
+    if (isNonEmptyString(displayName)) {
+        return { name: displayName };
+    }
+    if (depth >= MAX_UNWRAP_DEPTH) {
+        return null;
+    }
+    return identify(wrappedType(type), depth + 1);
+}
+/** The component inside `memo(…)` (`.type`) or `forwardRef(…)` (`.render`). */
+function wrappedType(type) {
+    const { type: memoized, render } = type;
+    return memoized ?? render;
+}
+/** What the plugin's appended code registered for this value, if anything. */
+function registeredExport(type) {
+    const registry = globalThis[Symbol.for(EXPORT_REGISTRY_KEY)];
+    // Duck-typed rather than `instanceof`: the map may come from another realm.
+    if (typeof registry?.get !== 'function') {
+        return undefined;
+    }
+    return registry.get(type);
+}
+/** Functions and non-null objects: everything a registry can hold and a component can be. */
+function isComponentLike(value) {
+    return typeof value === 'function' || (typeof value === 'object' && value !== null);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+function isStyledDefault(displayName) {
+    return STYLED_DEFAULT_NAMES.some((pattern) => pattern.test(displayName));
+}

package/dist/element-label.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A readable target for a frame label, e.g. `button "show details"`.
+ * Testing Library hands interactions a real `Element` rather than a Vitest
+ * locator, so the label is read off the element instead of a selector string.
+ */
+export declare function elementLabel(target: unknown): string | undefined;

package/dist/element-label.js

@@ -0,0 +1,34 @@
+/** Attributes that name an element better than its text, in order of preference. */
+const NAME_ATTRIBUTES = ['aria-label', 'name', 'placeholder', 'title'];
+function roleOf(element) {
+    const explicit = element.getAttribute('role');
+    if (explicit) {
+        return explicit;
+    }
+    const tag = element.tagName.toLowerCase();
+    if (tag === 'input') {
+        return element.getAttribute('type') ?? 'input';
+    }
+    return tag;
+}
+function nameOf(element) {
+    for (const attribute of NAME_ATTRIBUTES) {
+        const value = element.getAttribute(attribute);
+        if (value) {
+            return value;
+        }
+    }
+    return (element.textContent ?? '').trim().slice(0, 40);
+}
+/**
+ * A readable target for a frame label, e.g. `button "show details"`.
+ * Testing Library hands interactions a real `Element` rather than a Vitest
+ * locator, so the label is read off the element instead of a selector string.
+ */
+export function elementLabel(target) {
+    if (typeof Element === 'undefined' || !(target instanceof Element)) {
+        return undefined;
+    }
+    const name = nameOf(target);
+    return name ? `${roleOf(target)} "${name}"` : roleOf(target);
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 export * from './types.js';
+export { describeComponentType } from './describe-component-type.js';
+export { elementLabel } from './element-label.js';
+export { manifestDiagnostics } from './manifest-diagnostics.js';
 export { recorder } from './recorder.js';
 export { serializeValue } from './serialize-value.js';
 export { step } from './step.js';

package/dist/index.js

@@ -1,4 +1,7 @@
 export * from './types.js';
+export { describeComponentType } from './describe-component-type.js';
+export { elementLabel } from './element-label.js';
+export { manifestDiagnostics } from './manifest-diagnostics.js';
 export { recorder } from './recorder.js';
 export { serializeValue } from './serialize-value.js';
 export { step } from './step.js';

package/dist/manifest-diagnostics.d.ts

@@ -0,0 +1,7 @@
+import { type Manifest, type ManifestDiagnostics } from './types.js';
+/**
+ * List what the manifest could not document: anonymous components, named ones
+ * without props, and assets that will not load. The reporter prints it after a
+ * run and the viewer shows it in the header, so both agree on what is missing.
+ */
+export declare function manifestDiagnostics(manifest: Manifest): ManifestDiagnostics;

package/dist/manifest-diagnostics.js

@@ -0,0 +1,34 @@
+import { ANONYMOUS_COMPONENT } from './types.js';
+/** Host elements such as `div` are rendered as-is and have no props doc to miss. */
+function isHostElement(name) {
+    return /^[a-z]/.test(name);
+}
+/**
+ * List what the manifest could not document: anonymous components, named ones
+ * without props, and assets that will not load. The reporter prints it after a
+ * run and the viewer shows it in the header, so both agree on what is missing.
+ */
+export function manifestDiagnostics(manifest) {
+    const anonymous = [];
+    const undocumented = new Map();
+    for (const mod of manifest.modules) {
+        for (const test of mod.tests) {
+            const name = test.component?.name;
+            if (!name || isHostElement(name)) {
+                continue;
+            }
+            if (name === ANONYMOUS_COMPONENT) {
+                anonymous.push({ testId: test.id, fullName: test.fullName });
+                continue;
+            }
+            if (!manifest.components[name]) {
+                undocumented.set(name, (undocumented.get(name) ?? 0) + 1);
+            }
+        }
+    }
+    return {
+        anonymous,
+        undocumented: Array.from(undocumented, ([name, tests]) => ({ name, tests })).sort((left, right) => left.name.localeCompare(right.name)),
+        assetsMissing: manifest.assetsMissing ?? [],
+    };
+}

package/dist/materialize-adopted-styles.d.ts

@@ -2,6 +2,8 @@
  * Constructable stylesheets (`document.adoptedStyleSheets`, used by Lit and
  * other web-component libraries) are not part of the DOM tree, so rrweb's
  * snapshot never sees them. For the duration of `run`, mirror their rules into
- * a temporary `<style>` element so they end up in the capture.
+ * a temporary `<style>` element so they end up in the capture. Synchronous,
+ * like rrweb's snapshot, so a `settle: false` capture records its frame before
+ * `recorder.capture()` returns.
  */
-export declare function materializeAdoptedStyles<T>(run: () => T | Promise<T>): Promise<T>;
+export declare function materializeAdoptedStyles<T>(run: () => T): T;

package/dist/materialize-adopted-styles.js

@@ -2,9 +2,11 @@
  * Constructable stylesheets (`document.adoptedStyleSheets`, used by Lit and
  * other web-component libraries) are not part of the DOM tree, so rrweb's
  * snapshot never sees them. For the duration of `run`, mirror their rules into
- * a temporary `<style>` element so they end up in the capture.
+ * a temporary `<style>` element so they end up in the capture. Synchronous,
+ * like rrweb's snapshot, so a `settle: false` capture records its frame before
+ * `recorder.capture()` returns.
  */
-export async function materializeAdoptedStyles(run) {
+export function materializeAdoptedStyles(run) {
     const sheets = document.adoptedStyleSheets ?? [];
     if (sheets.length === 0) {
         return run();
@@ -16,7 +18,7 @@ export async function materializeAdoptedStyles(run) {
         .join('\n');
     document.head.append(mirror);
     try {
-        return await run();
+        return run();
     }
     finally {
         mirror.remove();

package/dist/page-has-content.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the page shows anything at all. False for what Testing Library
+ * leaves behind: an empty body after `cleanup()`, the bare container `div`
+ * after `unmount()`. Any text, any other element and any attribute count as
+ * content, so a styled box or an icon is never taken for an empty page.
+ */
+export declare function pageHasContent(): boolean;

package/dist/page-has-content.js

@@ -0,0 +1,21 @@
+/**
+ * Whether the page shows anything at all. False for what Testing Library
+ * leaves behind: an empty body after `cleanup()`, the bare container `div`
+ * after `unmount()`. Any text, any other element and any attribute count as
+ * content, so a styled box or an icon is never taken for an empty page.
+ */
+export function pageHasContent() {
+    const body = document.body;
+    if (!body) {
+        return false;
+    }
+    if ((body.textContent ?? '').trim() !== '') {
+        return true;
+    }
+    for (const element of body.querySelectorAll('*')) {
+        if (element.localName !== 'div' || element.attributes.length > 0) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/real-timers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `setTimeout` and `performance.now()` as they were before any test faked
+ * them, so `vi.useFakeTimers()` neither hangs a capture nor skews frame times.
+ */
+export declare const realTimers: {
+    setTimeout: typeof setTimeout;
+    now: () => number;
+};

package/dist/real-timers.js

@@ -0,0 +1,23 @@
+/** The global `setTimeout`, unwrapped when a setup file faked timers before this module loaded. */
+function originalSetTimeout() {
+    const current = globalThis.setTimeout;
+    return current.clock ? current.clock._setTimeout : current;
+}
+/** The global `performance`, unwrapped the same way. */
+function originalPerformance() {
+    const current = globalThis.performance;
+    return current.clock ? current.clock._performance : current;
+}
+// Bound, because browsers throw "Illegal invocation" when `setTimeout` is
+// called without its global as `this`.
+const setTimeoutAtLoad = originalSetTimeout().bind(globalThis);
+// Fake timers replace `performance` as a whole object, so this reference stays real.
+const performanceAtLoad = originalPerformance();
+/**
+ * `setTimeout` and `performance.now()` as they were before any test faked
+ * them, so `vi.useFakeTimers()` neither hangs a capture nor skews frame times.
+ */
+export const realTimers = {
+    setTimeout: setTimeoutAtLoad,
+    now: () => performanceAtLoad.now(),
+};

package/dist/recorder.d.ts

@@ -10,13 +10,16 @@ declare class Recorder {
     private component?;
     private startedAt;
     private active;
-    private lastHash;
+    private closed;
+    private lastJson;
     private seq;
     private teardowns;
     begin(): void;
     get isActive(): boolean;
     setComponent(info: ComponentInfo): void;
     capture(kind: FrameKind, label: string, meta?: Record<string, unknown>, options?: CaptureOptions): Promise<void>;
+    /** The test went on after `cleanup()`, so the closing frame it took names the state before it. */
+    private reopen;
     end(): TestRecord;
     /**
      * Register work that must run after the test's frames are handed over, such

package/dist/recorder.js

@@ -1,6 +1,6 @@
-import { snapshot, createMirror } from 'rrweb-snapshot';
-import { materializeAdoptedStyles } from './materialize-adopted-styles.js';
-import { quickHash } from './quick-hash.js';
+import { pageHasContent } from './page-has-content.js';
+import { realTimers } from './real-timers.js';
+import { serializeDocument } from './serialize-document.js';
 import { settle } from './settle.js';
 /**
  * Test-side recorder, running wherever the tests run: the browser-mode iframe
@@ -12,15 +12,18 @@ class Recorder {
     component;
     startedAt = 0;
     active = false;
-    lastHash = '';
+    // Once `cleanup()` or the setup file took the closing frame, a second one is skipped.
+    closed = false;
+    lastJson = '';
     seq = 0;
     teardowns = new Set();
     begin() {
         this.frames = [];
         this.component = undefined;
-        this.startedAt = performance.now();
+        this.startedAt = realTimers.now();
         this.active = true;
-        this.lastHash = '';
+        this.closed = false;
+        this.lastJson = '';
         this.seq = 0;
     }
     get isActive() {
@@ -35,39 +38,65 @@ class Recorder {
         if (!this.active) {
             return;
         }
+        if (kind !== 'end' && this.closed) {
+            this.reopen();
+        }
+        if (kind === 'end' && (this.frames.length === 0 || this.closed)) {
+            return;
+        }
         if (options.settle !== false) {
             await settle();
         }
-        const node = await materializeAdoptedStyles(() => snapshot(document, { mirror: createMirror(), inlineStylesheet: true }));
-        if (!node) {
+        if (kind === 'end') {
+            this.closed = true;
+            // After `cleanup()` or `unmount()` there is nothing left to show.
+            if (!pageHasContent()) {
+                return;
+            }
+        }
+        const json = serializeDocument();
+        if (json === null) {
             return;
         }
-        // rrweb numbers nodes with a global counter, so ids differ between otherwise identical captures.
-        const hash = quickHash(JSON.stringify(node, (key, value) => (key === 'id' || key === 'rootId' ? undefined : value)));
         // The closing frame is only interesting if something changed since the last one.
-        if (kind === 'end' && hash === this.lastHash) {
+        if (kind === 'end' && json === this.lastJson) {
             return;
         }
         // A step whose body already produced this exact DOM (e.g. via an action) just names that frame.
-        if (kind === 'step' && hash === this.lastHash && this.frames.length) {
+        if (kind === 'step' && json === this.lastJson && this.frames.length) {
             const last = this.frames[this.frames.length - 1];
             last.label = `${label} · ${last.label}`;
             last.kind = 'step';
             return;
         }
-        this.lastHash = hash;
+        this.lastJson = json;
         this.frames.push({
             id: `f${this.seq++}`,
             kind,
             label,
-            at: Math.round(performance.now() - this.startedAt),
+            at: Math.round(realTimers.now() - this.startedAt),
             meta,
-            snapshot: node,
+            snapshot: json,
         });
     }
+    /** The test went on after `cleanup()`, so the closing frame it took names the state before it. */
+    reopen() {
+        this.closed = false;
+        const last = this.frames[this.frames.length - 1];
+        if (last?.kind === 'end') {
+            last.kind = 'step';
+            last.label = 'before cleanup()';
+        }
+    }
     end() {
         this.active = false;
-        return { frames: this.frames, component: this.component };
+        // The reporter needs the origin rrweb resolved every URL against. Optional
+        // chaining, because a DOM environment is not guaranteed to define `location`.
+        return {
+            frames: this.frames,
+            component: this.component,
+            origin: globalThis.location?.origin,
+        };
     }
     /**
      * Register work that must run after the test's frames are handed over, such

package/dist/serialize-document.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Serialize the current document with rrweb, as JSON text, or `null` when
+ * rrweb has nothing to serialize.
+ *
+ * rrweb numbers nodes from a module-level counter that only
+ * `cleanupSnapshot()` resets. Resetting it before every capture makes ids
+ * start at 1, drops `rootId` (added whenever the document's id is not 1), and
+ * makes identical DOM serialize to identical text, so the snapshot store
+ * writes it once. Gotcha: any other rrweb user in the same realm shares that
+ * counter; none is expected inside tests.
+ */
+export declare function serializeDocument(): string | null;

package/dist/serialize-document.js

@@ -0,0 +1,20 @@
+import { cleanupSnapshot, createMirror, snapshot } from 'rrweb-snapshot';
+import { materializeAdoptedStyles } from './materialize-adopted-styles.js';
+/**
+ * Serialize the current document with rrweb, as JSON text, or `null` when
+ * rrweb has nothing to serialize.
+ *
+ * rrweb numbers nodes from a module-level counter that only
+ * `cleanupSnapshot()` resets. Resetting it before every capture makes ids
+ * start at 1, drops `rootId` (added whenever the document's id is not 1), and
+ * makes identical DOM serialize to identical text, so the snapshot store
+ * writes it once. Gotcha: any other rrweb user in the same realm shares that
+ * counter; none is expected inside tests.
+ */
+export function serializeDocument() {
+    return materializeAdoptedStyles(() => {
+        cleanupSnapshot();
+        const node = snapshot(document, { mirror: createMirror(), inlineStylesheet: true });
+        return node ? JSON.stringify(node) : null;
+    });
+}

package/dist/serialize-value.js

@@ -1,3 +1,4 @@
+import { describeComponentType } from './describe-component-type.js';
 /** Turn arbitrary props into something JSON-safe and readable. */
 export function serializeValue(value, depth = 0) {
     if (depth > 3) {
@@ -23,12 +24,7 @@ export function serializeValue(value, depth = 0) {
         const record = value;
         // React element
         if ('$$typeof' in record && 'type' in record) {
-            const type = record.type;
-            const name = typeof type === 'string'
-                ? type
-                : (type?.displayName ??
-                    type?.name ??
-                    'Anonymous');
+            const { name } = describeComponentType(record.type);
             return `<${name} />`;
         }
         const out = {};

package/dist/settle.d.ts

@@ -3,5 +3,6 @@
  * One macrotask is enough for React to commit batched updates. We deliberately
  * do not wait for requestAnimationFrame: the snapshot is DOM + stylesheets, not
  * layout, and a rAF costs a whole vsync (~16ms) per capture in headless Chromium.
+ * It uses real timers, so a test that leaves fake timers on still settles.
  */
 export declare function settle(): Promise<void>;

package/dist/settle.js

@@ -1,9 +1,11 @@
+import { realTimers } from './real-timers.js';
 /**
  * Let the framework flush pending updates before we look at the DOM.
  * One macrotask is enough for React to commit batched updates. We deliberately
  * do not wait for requestAnimationFrame: the snapshot is DOM + stylesheets, not
  * layout, and a rAF costs a whole vsync (~16ms) per capture in headless Chromium.
+ * It uses real timers, so a test that leaves fake timers on still settles.
  */
 export async function settle() {
-    await new Promise((resolve) => setTimeout(resolve, 0));
+    await new Promise((resolve) => realTimers.setTimeout(resolve, 0));
 }

package/dist/types.d.ts

@@ -3,18 +3,53 @@ export type FrameKind = 'render' | 'action' | 'step' | 'end';
 export interface ComponentInfo {
     name: string;
     props: Record<string, unknown>;
+    /**
+     * Source file that defines the component, relative to the project root, when
+     * the plugin registered its module's exports. Lets the reporter read props
+     * without guessing the file from the test's imports.
+     */
+    file?: string;
 }
+/** What the plugin registers for every top-level export of a project module. */
+export interface RegisteredExport {
+    /** The export name in the defining module, e.g. `Button`. */
+    name: string;
+    /** The defining module, relative to the project root, posix separators. */
+    file: string;
+}
+/**
+ * `Symbol.for()` key of the registry on `globalThis`: a
+ * `WeakMap<object, RegisteredExport>` filled by code the plugin appends to
+ * project modules. A global rather than an import, because a user's module
+ * cannot always resolve `@describe-me/core` (pnpm) and a bundled adapter may
+ * carry its own copy of core.
+ */
+export declare const EXPORT_REGISTRY_KEY: "describe-me.exports";
+/**
+ * Prefix of project asset URLs inside stored snapshots, e.g.
+ * `describe-me-asset:3f2a9c1d.svg`. The reporter copies the file to
+ * `<outDir>/assets/` and the viewer resolves the prefix against `__data/assets/`.
+ */
+export declare const ASSET_URL_PREFIX: "describe-me-asset:";
+/**
+ * Prefix of stylesheet references inside stored snapshots, e.g.
+ * `describe-me-style:3f2a9c1d0b7e4a55+9c1d…`. The reporter stores an rrweb
+ * `_cssText` of 256+ characters as chunks in `<outDir>/styles/<hash>.css`, and
+ * the viewer joins them back in order before replaying.
+ */
+export declare const STYLE_URL_PREFIX: "describe-me-style:";
 /** Options for `recorder.capture()`. */
 export interface CaptureOptions {
     /**
      * Wait one macrotask for the framework to flush before looking at the DOM.
      * Default: true. Pass false when the caller knows the DOM is already
      * committed (e.g. right after Testing Library's `act()`-wrapped `rerender`):
-     * the snapshot is then taken synchronously, before the caller moves on.
+     * the snapshot is then taken and the frame recorded before `capture()`
+     * returns, so the caller can move on without awaiting it.
      */
     settle?: boolean;
 }
-/** A frame as captured in the browser. `snapshot` is an rrweb serialized document. */
+/** A frame as captured by the recorder. `snapshot` is the DOM, already serialized to JSON. */
 export interface Frame {
     id: string;
     kind: FrameKind;
@@ -22,12 +57,19 @@ export interface Frame {
     /** ms since the test began */
     at: number;
     meta?: Record<string, unknown>;
-    snapshot: unknown;
+    /** rrweb serialized document, as JSON text */
+    snapshot: string;
 }
 /** What a single test hands over to the reporter via task.meta[META_KEY]. */
 export interface TestRecord {
     frames: Frame[];
     component?: ComponentInfo;
+    /**
+     * `location.origin` of the page the test ran in (`http://localhost:3000` in
+     * jsdom, the Vitest server in browser mode). rrweb makes every URL absolute
+     * against it, so the reporter uses it to find project assets.
+     */
+    origin?: string;
 }
 export declare const META_KEY: "describeMe";
 export type TestState = 'passed' | 'failed' | 'skipped' | 'pending';
@@ -93,4 +135,27 @@ export interface Manifest {
     modules: ManifestModule[];
     /** Keyed by component name, as reported by the framework adapter. */
     components: Record<string, ComponentDoc>;
+    /**
+     * Asset URLs the snapshots point at on the test page's origin that could not
+     * be found in the project, as root-relative paths (`/lib/images/logo.svg`).
+     * They will not load in the viewer. Absent in manifests written before 0.4.
+     */
+    assetsMissing?: string[];
+}
+/** The name adapters fall back to when a component has no usable name. */
+export declare const ANONYMOUS_COMPONENT: "Anonymous";
+/** What keeps a manifest from documenting everything its tests rendered. */
+export interface ManifestDiagnostics {
+    /** Tests whose rendered component has no usable name. */
+    anonymous: {
+        testId: string;
+        fullName: string;
+    }[];
+    /** Named components without a props doc, with how many tests rendered each. */
+    undocumented: {
+        name: string;
+        tests: number;
+    }[];
+    /** Root-relative asset paths that will not load in the viewer. */
+    assetsMissing: string[];
 }

package/dist/types.js

@@ -1,2 +1,25 @@
 /** Shared, JSON-serializable types. Safe to import from Node (no DOM). */
+/**
+ * `Symbol.for()` key of the registry on `globalThis`: a
+ * `WeakMap<object, RegisteredExport>` filled by code the plugin appends to
+ * project modules. A global rather than an import, because a user's module
+ * cannot always resolve `@describe-me/core` (pnpm) and a bundled adapter may
+ * carry its own copy of core.
+ */
+export const EXPORT_REGISTRY_KEY = 'describe-me.exports';
+/**
+ * Prefix of project asset URLs inside stored snapshots, e.g.
+ * `describe-me-asset:3f2a9c1d.svg`. The reporter copies the file to
+ * `<outDir>/assets/` and the viewer resolves the prefix against `__data/assets/`.
+ */
+export const ASSET_URL_PREFIX = 'describe-me-asset:';
+/**
+ * Prefix of stylesheet references inside stored snapshots, e.g.
+ * `describe-me-style:3f2a9c1d0b7e4a55+9c1d…`. The reporter stores an rrweb
+ * `_cssText` of 256+ characters as chunks in `<outDir>/styles/<hash>.css`, and
+ * the viewer joins them back in order before replaying.
+ */
+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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@describe-me/core",
-  "version": "0.3.0",
+  "version": "0.5.0-next.0",
   "description": "Recorder and manifest types for describe-me: living component docs from your tests",
   "keywords": [
     "vitest",
@@ -34,6 +34,10 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "default": "./dist/types.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/manifest-diagnostics.d.ts",
+      "default": "./dist/manifest-diagnostics.js"
     }
   },
   "files": [

package/dist/quick-hash.d.ts

@@ -1,7 +0,0 @@
-/**
- * Inexpensive, non-cryptographic hash used to tell two captures apart.
- * `| 0` keeps the accumulator a 32-bit integer, so overflow wraps like a Java
- * int instead of drifting into floating point. A collision merely skips one
- * frame, which is why this is good enough here and SHA-1 is not needed.
- */
-export declare function quickHash(input: string): string;

package/dist/quick-hash.js

@@ -1,19 +0,0 @@
-/**
- * Multiplier of the polynomial rolling hash, the same one `String.hashCode()`
- * uses in Java. Odd, so no bit is lost to a plain shift on every step; prime,
- * so common inputs spread evenly; and `x * 31` is just `(x << 5) - x`.
- */
-const MULTIPLIER = 31;
-/**
- * Inexpensive, non-cryptographic hash used to tell two captures apart.
- * `| 0` keeps the accumulator a 32-bit integer, so overflow wraps like a Java
- * int instead of drifting into floating point. A collision merely skips one
- * frame, which is why this is good enough here and SHA-1 is not needed.
- */
-export function quickHash(input) {
-    let hash = 0;
-    for (let i = 0; i < input.length; i++) {
-        hash = (hash * MULTIPLIER + input.charCodeAt(i)) | 0;
-    }
-    return `${input.length}:${hash}`;
-}