@describe-me/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Łotysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @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.
+
+Most people never install this package directly — `@describe-me/react` and
+`@describe-me/vitest` depend on it, and both re-export `step()`.
+
+## Install
+
+```sh
+pnpm add -D @describe-me/core
+```
+
+## Usage
+
+`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.
+
+```ts
+import { step } from '@describe-me/core'
+
+await step('open the menu', () => screen.getByRole('button', { name: 'Menu' }).click())
+```
+
+The manifest types live in `@describe-me/core/types`, for tools that want to
+read `.describe-me/manifest.json` themselves.
+
+See the [root README](https://github.com/grzehub/describe-me#readme) for the
+full picture.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { recorder } from './recorder.js';
+export { serializeValue } from './serialize-value.js';
+export { step } from './step.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export { recorder } from './recorder.js';
+export { serializeValue } from './serialize-value.js';
+export { step } from './step.js';

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

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function materializeAdoptedStyles<T>(run: () => T | Promise<T>): Promise<T>;

package/dist/materialize-adopted-styles.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export async function materializeAdoptedStyles(run) {
+    const sheets = document.adoptedStyleSheets ?? [];
+    if (sheets.length === 0) {
+        return run();
+    }
+    const mirror = document.createElement('style');
+    mirror.setAttribute('data-describe-me', 'adopted-styles');
+    mirror.textContent = sheets
+        .flatMap((sheet) => Array.from(sheet.cssRules, (rule) => rule.cssText))
+        .join('\n');
+    document.head.append(mirror);
+    try {
+        return await run();
+    }
+    finally {
+        mirror.remove();
+    }
+}

package/dist/quick-hash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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

@@ -0,0 +1,19 @@
+/**
+ * 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}`;
+}

package/dist/recorder.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentInfo, FrameKind, TestRecord } from './types.js';
+/**
+ * Browser-side recorder. One instance per test iframe; `begin()` in beforeEach,
+ * `end()` in afterEach. Framework adapters call `capture()` and `setComponent()`.
+ */
+declare class Recorder {
+    private frames;
+    private component?;
+    private startedAt;
+    private active;
+    private lastHash;
+    private seq;
+    begin(): void;
+    get isActive(): boolean;
+    setComponent(info: ComponentInfo): void;
+    capture(kind: FrameKind, label: string, meta?: Record<string, unknown>): Promise<void>;
+    end(): TestRecord;
+}
+export declare const recorder: Recorder;
+export {};

package/dist/recorder.js

@@ -0,0 +1,69 @@
+import { snapshot, createMirror } from 'rrweb-snapshot';
+import { materializeAdoptedStyles } from './materialize-adopted-styles.js';
+import { quickHash } from './quick-hash.js';
+import { settle } from './settle.js';
+/**
+ * Browser-side recorder. One instance per test iframe; `begin()` in beforeEach,
+ * `end()` in afterEach. Framework adapters call `capture()` and `setComponent()`.
+ */
+class Recorder {
+    frames = [];
+    component;
+    startedAt = 0;
+    active = false;
+    lastHash = '';
+    seq = 0;
+    begin() {
+        this.frames = [];
+        this.component = undefined;
+        this.startedAt = performance.now();
+        this.active = true;
+        this.lastHash = '';
+        this.seq = 0;
+    }
+    get isActive() {
+        return this.active;
+    }
+    setComponent(info) {
+        if (!this.component) {
+            this.component = info;
+        }
+    }
+    async capture(kind, label, meta) {
+        if (!this.active) {
+            return;
+        }
+        await settle();
+        const node = await materializeAdoptedStyles(() => snapshot(document, { mirror: createMirror(), inlineStylesheet: true }));
+        if (!node) {
+            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) {
+            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) {
+            const last = this.frames[this.frames.length - 1];
+            last.label = `${label} · ${last.label}`;
+            last.kind = 'step';
+            return;
+        }
+        this.lastHash = hash;
+        this.frames.push({
+            id: `f${this.seq++}`,
+            kind,
+            label,
+            at: Math.round(performance.now() - this.startedAt),
+            meta,
+            snapshot: node,
+        });
+    }
+    end() {
+        this.active = false;
+        return { frames: this.frames, component: this.component };
+    }
+}
+export const recorder = new Recorder();

package/dist/serialize-value.d.ts

@@ -0,0 +1,2 @@
+/** Turn arbitrary props into something JSON-safe and readable. */
+export declare function serializeValue(value: unknown, depth?: number): unknown;

package/dist/serialize-value.js

@@ -0,0 +1,41 @@
+/** Turn arbitrary props into something JSON-safe and readable. */
+export function serializeValue(value, depth = 0) {
+    if (depth > 3) {
+        return '…';
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const kind = typeof value;
+    if (kind === 'string' || kind === 'number' || kind === 'boolean') {
+        return value;
+    }
+    if (kind === 'function') {
+        return `ƒ ${value.name || 'anonymous'}`;
+    }
+    if (kind === 'symbol') {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => serializeValue(item, depth + 1));
+    }
+    if (kind === 'object') {
+        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');
+            return `<${name} />`;
+        }
+        const out = {};
+        for (const [key, entry] of Object.entries(record)) {
+            out[key] = serializeValue(entry, depth + 1);
+        }
+        return out;
+    }
+    return String(value);
+}

package/dist/settle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export declare function settle(): Promise<void>;

package/dist/settle.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export async function settle() {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+}

package/dist/step.d.ts

@@ -0,0 +1,2 @@
+/** Name a phase of the test. The DOM is captured after `fn` resolves. */
+export declare function step<T>(label: string, fn: () => T | Promise<T>): Promise<T>;

package/dist/step.js

@@ -0,0 +1,7 @@
+import { recorder } from './recorder.js';
+/** Name a phase of the test. The DOM is captured after `fn` resolves. */
+export async function step(label, fn) {
+    const result = await fn();
+    await recorder.capture('step', label);
+    return result;
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/** Shared, JSON-serializable types. Safe to import from Node (no DOM). */
+export type FrameKind = 'render' | 'action' | 'step' | 'end';
+export interface ComponentInfo {
+    name: string;
+    props: Record<string, unknown>;
+}
+/** A frame as captured in the browser. `snapshot` is an rrweb serialized document. */
+export interface Frame {
+    id: string;
+    kind: FrameKind;
+    label: string;
+    /** ms since the test began */
+    at: number;
+    meta?: Record<string, unknown>;
+    snapshot: unknown;
+}
+/** What a single test hands over to the reporter via task.meta[META_KEY]. */
+export interface TestRecord {
+    frames: Frame[];
+    component?: ComponentInfo;
+}
+export declare const META_KEY: "describeMe";
+export type TestState = 'passed' | 'failed' | 'skipped' | 'pending';
+export interface ManifestFrame {
+    id: string;
+    kind: FrameKind;
+    label: string;
+    at: number;
+    meta?: Record<string, unknown>;
+    /** path relative to the manifest, e.g. "snapshots/ab12.json" */
+    snapshot: string;
+}
+export interface ManifestTest {
+    id: string;
+    name: string;
+    /** suite names from outermost to innermost */
+    path: string[];
+    fullName: string;
+    state: TestState;
+    duration?: number;
+    errors?: {
+        message: string;
+        stack?: string;
+    }[];
+    component?: ComponentInfo;
+    frames: ManifestFrame[];
+}
+export interface ManifestModule {
+    /** module path relative to project root */
+    id: string;
+    tests: ManifestTest[];
+}
+/** How a prop can be covered and, later, controlled. */
+export type PropKind = 'literals' | 'boolean' | 'number' | 'string' | 'function' | 'node' | 'other';
+/** One prop of a component, as read from its TypeScript type. */
+export interface PropDoc {
+    name: string;
+    /** The type as TypeScript prints it, e.g. `'sm' | 'md' | 'lg'`. */
+    type: string;
+    required: boolean;
+    /** Default from the destructuring pattern, as source text, e.g. `'md'` or `false`. */
+    defaultValue?: string;
+    kind: PropKind;
+    /**
+     * For `literals`: every member as source text (`'sm'`, `3`), in declaration order.
+     * For `boolean`: `true` and `false`. Absent for other kinds.
+     */
+    values?: string[];
+    /** Leading JSDoc comment on the prop, if any. */
+    description?: string;
+}
+/** Everything the viewer needs to document a component beyond its tests. */
+export interface ComponentDoc {
+    name: string;
+    /** Source file relative to the project root. */
+    file: string;
+    props: PropDoc[];
+}
+export interface Manifest {
+    version: 1;
+    generatedAt: string;
+    root: string;
+    modules: ManifestModule[];
+    /** Keyed by component name, as reported by the framework adapter. */
+    components: Record<string, ComponentDoc>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Shared, JSON-serializable types. Safe to import from Node (no DOM). */
+export const META_KEY = 'describeMe';

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@describe-me/core",
+  "version": "0.1.0",
+  "description": "Recorder and manifest types for describe-me: living component docs from your tests",
+  "keywords": [
+    "vitest",
+    "storybook",
+    "component documentation",
+    "visual testing",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Grzegorz Łotysz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzehub/describe-me.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://grzehub.github.io/describe-me/",
+  "bugs": "https://github.com/grzehub/describe-me/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "rrweb-snapshot": "^2.1.6"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.json"
+  }
+}