describe-me 0.3.0 → 0.5.0-next.0

package/README.md

@@ -14,6 +14,9 @@ writes, and replays the snapshots in a sandboxed iframe.
 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`.
+
 ## Usage
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "describe-me",
-  "version": "0.3.0",
+  "version": "0.5.0-next.0",
   "description": "Living component documentation generated from your Vitest tests: viewer and CLI",
   "keywords": [
     "vitest",
@@ -21,7 +21,7 @@
   "bugs": "https://github.com/grzehub/describe-me/issues",
   "type": "module",
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": "^20.16.0 || >=22.4.0"
   },
   "publishConfig": {
     "access": "public",
@@ -42,11 +42,14 @@
   "sideEffects": false,
   "dependencies": {
     "rrweb-snapshot": "^2.1.6",
-    "vite": "^8.3.0",
-    "@describe-me/core": "^0.3.0"
+    "@describe-me/core": "^0.5.0-next.0"
+  },
+  "peerDependencies": {
+    "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22"
+    "@types/node": "^22",
+    "vite": "^8.3.0"
   },
   "scripts": {
     "build": "rimraf dist-cli && tsc -p tsconfig.cli.json",

package/src/data.ts

@@ -1,10 +1,10 @@
-import type { rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
 import type { Manifest } from '@describe-me/core/types'
 import { allTests, currentTest, state } from './state.js'
 import { rerender } from './rerender.js'
-
-/** rrweb's serialized document node; the package does not re-export the type. */
-type SerializedNode = Parameters<typeof rebuildIntoSandboxedIframe>[0]
+import { resolveAssetUrls } from './resolve-asset-urls.js'
+import { restoreStyles } from './restore-styles.js'
+import type { SerializedNode } from './serialized-node.js'
+import { withoutEmptyTests } from './without-empty-tests.js'
 
 const snapshotCache = new Map<string, Promise<SerializedNode>>()
 
@@ -18,7 +18,7 @@ export async function loadManifest(): Promise<void> {
     throw new Error(`manifest: ${response.status}`)
   }
 
-  const next = (await response.json()) as Manifest
+  const next = withoutEmptyTests((await response.json()) as Manifest)
   if (state.manifest?.generatedAt === next.generatedAt) {
     return
   }
@@ -39,16 +39,30 @@ export async function loadManifest(): Promise<void> {
   rerender()
 }
 
-/** Fetch one serialized DOM, memoized until the next manifest load. */
+/**
+ * Fetch one serialized DOM, memoized until the next manifest load. The promise
+ * resolves with asset URLs made absolute and stored stylesheets put back, so
+ * the stage and the gallery thumbnails always rebuild complete CSS and measure
+ * styled boxes.
+ */
 export function loadSnapshot(path: string): Promise<SerializedNode> {
   let pending = snapshotCache.get(path)
   if (!pending) {
-    pending = fetch(`__data/${path}`, { cache: 'no-store' }).then(
-      (response) => response.json() as Promise<SerializedNode>,
-    )
+    pending = fetch(`__data/${path}`, { cache: 'no-store' })
+      .then((response) => response.text())
+      .then((json) => parseSnapshot(json))
+      .then(async (node) => {
+        await restoreStyles(node)
+
+        return node
+      })
 
     snapshotCache.set(path, pending)
   }
 
   return pending
 }
+
+function parseSnapshot(json: string): SerializedNode {
+  return JSON.parse(resolveAssetUrls(json)) as SerializedNode
+}

package/src/diagnostics-menu.ts

@@ -0,0 +1,102 @@
+import { manifestDiagnostics } from '@describe-me/core/diagnostics'
+import type { Manifest } from '@describe-me/core/types'
+import { el } from './el.js'
+import { select } from './state.js'
+
+/** Long lists are cut here; the rest is summed up in one line. */
+const LIST_LIMIT = 40
+
+function section(title: string, hint: string, items: HTMLElement[]): HTMLElement {
+  const shown = items.slice(0, LIST_LIMIT)
+  const rest = items.length - shown.length
+  const list = el('ul', { class: 'issues-list' }, ...shown)
+
+  if (rest > 0) {
+    list.append(el('li', { class: 'issues-more' }, `+${rest} more`))
+  }
+
+  return el(
+    'section',
+    { class: 'issues-section' },
+    el('h3', {}, title, el('span', { class: 'issues-count' }, String(items.length))),
+    el('p', { class: 'issues-hint' }, hint),
+    list,
+  )
+}
+
+/**
+ * A header chip that opens the list of what this manifest could not document:
+ * anonymous components, components without props docs and assets that will not
+ * load. Absent when there is nothing to report.
+ */
+export function renderDiagnosticsMenu(manifest: Manifest): HTMLElement | null {
+  const { anonymous, undocumented, assetsMissing } = manifestDiagnostics(manifest)
+  const count = anonymous.length + undocumented.length + assetsMissing.length
+
+  if (count === 0) {
+    return null
+  }
+
+  const sections: HTMLElement[] = []
+
+  if (anonymous.length > 0) {
+    const items = anonymous.map((test) =>
+      el(
+        'li',
+        {},
+        el('button', { class: 'issues-link', click: () => select(test.testId) }, test.fullName),
+      ),
+    )
+
+    sections.push(
+      section(
+        'Anonymous components',
+        'Export the component from a project module (it is named after its export) or give it a displayName.',
+        items,
+      ),
+    )
+  }
+
+  if (undocumented.length > 0) {
+    const items = undocumented.map((component) =>
+      el(
+        'li',
+        {},
+        el('span', { class: 'mono' }, component.name),
+        el('span', { class: 'issues-meta' }, `${component.tests} tests`),
+      ),
+    )
+
+    sections.push(
+      section(
+        'No props docs',
+        'Its props could not be read: is it exported from a TypeScript module, and is typescript installed?',
+        items,
+      ),
+    )
+  }
+
+  if (assetsMissing.length > 0) {
+    const items = assetsMissing.map((path) => el('li', { class: 'mono' }, path))
+
+    sections.push(
+      section(
+        'Assets not found',
+        'Not found under the project root or public/, so they will not load here.',
+        items,
+      ),
+    )
+  }
+
+  return el(
+    'details',
+    { class: 'issues' },
+    el(
+      'summary',
+      { class: 'stat warn' },
+      el('b', {}, String(count)),
+      count === 1 ? 'issue' : 'issues',
+    ),
+    el('div', { class: 'issues-panel' }, ...sections),
+  )
+}

package/src/header.ts

@@ -1,3 +1,4 @@
+import { renderDiagnosticsMenu } from './diagnostics-menu.js'
 import { el } from './el.js'
 import { allTests, state } from './state.js'
 
@@ -5,7 +6,7 @@ function stat(count: number, label: string, tone?: 'pass' | 'fail'): HTMLElement
   return el('span', { class: tone ? `stat ${tone}` : 'stat' }, el('b', {}, String(count)), label)
 }
 
-/** Wordmark, pass/fail counts and the time of the last run. */
+/** Wordmark, pass/fail counts, what could not be documented and the time of the last run. */
 export function renderHeader(): HTMLElement {
   const manifest = state.manifest
   const tests = manifest ? allTests(manifest) : []
@@ -26,6 +27,7 @@ export function renderHeader(): HTMLElement {
     { class: 'header' },
     wordmark,
     summary,
+    manifest && renderDiagnosticsMenu(manifest),
     el('span', { class: 'right live' }, 'updated ', el('span', { class: 'mono' }, when)),
   )
 }

package/src/load-style.ts

@@ -0,0 +1,66 @@
+import { resolveAssetUrls } from './resolve-asset-urls.js'
+
+/**
+ * Chunk texts by hash, kept as promises so parallel thumbnails share one
+ * request. Never cleared, because a hash always names the same text.
+ */
+const chunks = new Map<string, Promise<string | null>>()
+
+/** Joined sheets by reference, so every snapshot using a sheet shares one string. */
+const sheets = new Map<string, Promise<string>>()
+
+async function fetchChunk(hash: string): Promise<string | null> {
+  try {
+    // Default caching: the name is a content hash, so a cached copy is always right.
+    const response = await fetch(`__data/styles/${hash}.css`)
+
+    return response.ok ? resolveAssetUrls(await response.text()) : null
+  } catch {
+    return null
+  }
+}
+
+function loadChunk(hash: string): Promise<string | null> {
+  const memo = chunks.get(hash)
+  if (memo) {
+    return memo
+  }
+
+  const pending = fetchChunk(hash).then((css) => {
+    if (css === null) {
+      console.warn(`describe-me: style chunk styles/${hash}.css did not load`)
+      chunks.delete(hash)
+    }
+
+    return css
+  })
+
+  chunks.set(hash, pending)
+
+  return pending
+}
+
+/**
+ * The stylesheet behind a reference, the text after `STYLE_URL_PREFIX`. A chunk
+ * that fails to load leaves a gap rather than failing the frame, and is fetched
+ * again next time.
+ */
+export function loadStyle(reference: string): Promise<string> {
+  const memo = sheets.get(reference)
+  if (memo) {
+    return memo
+  }
+
+  const loads = reference.split('+').map((hash) => loadChunk(hash))
+  const pending = Promise.all(loads).then((texts) => {
+    if (texts.includes(null)) {
+      sheets.delete(reference)
+    }
+
+    return texts.map((text) => text ?? '').join('')
+  })
+
+  sheets.set(reference, pending)
+
+  return pending
+}

package/src/replay-cache.ts

@@ -0,0 +1,4 @@
+import { createCache } from 'rrweb-snapshot'
+
+/** rrweb caches its CSS adaptation per CSS text, so the stage and the gallery share one cache. */
+export const replayCache = createCache()

package/src/resolve-asset-urls.ts

@@ -0,0 +1,9 @@
+import { ASSET_URL_PREFIX } from '@describe-me/core/types'
+
+/**
+ * Make stored asset URLs absolute against the page, because a snapshot replays
+ * in a sandboxed iframe that has no base URL of its own.
+ */
+export function resolveAssetUrls(text: string): string {
+  return text.replaceAll(ASSET_URL_PREFIX, new URL('__data/assets/', location.href).href)
+}

package/src/restore-styles.ts

@@ -0,0 +1,44 @@
+import { STYLE_URL_PREFIX } from '@describe-me/core/types'
+import { loadStyle } from './load-style.js'
+import type { SerializedNode } from './serialized-node.js'
+
+/**
+ * What the walk reads. `SerializedNode` is `any` here: rrweb-snapshot's types
+ * import `@rrweb/types`, which it does not install.
+ */
+interface WalkedNode {
+  attributes?: Record<string, unknown>
+  childNodes?: WalkedNode[]
+}
+
+interface StoredSheet {
+  attributes: Record<string, unknown>
+  reference: string
+}
+
+function storedSheets(node: WalkedNode, found: StoredSheet[] = []): StoredSheet[] {
+  const cssText = node.attributes?._cssText
+  if (node.attributes && typeof cssText === 'string' && cssText.startsWith(STYLE_URL_PREFIX)) {
+    found.push({ attributes: node.attributes, reference: cssText.slice(STYLE_URL_PREFIX.length) })
+  }
+
+  for (const child of node.childNodes ?? []) {
+    storedSheets(child, found)
+  }
+
+  return found
+}
+
+/**
+ * Put every stylesheet a snapshot keeps in `styles/` back in place, before
+ * rrweb rebuilds it. Snapshots without references pass through unchanged.
+ */
+export async function restoreStyles(node: SerializedNode): Promise<void> {
+  const stored = storedSheets(node)
+
+  await Promise.all(
+    stored.map(async ({ attributes, reference }) => {
+      attributes._cssText = await loadStyle(reference)
+    }),
+  )
+}

package/src/serialized-node.ts

@@ -0,0 +1,4 @@
+import type { rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+
+/** rrweb's serialized document node, which the package does not re-export. */
+export type SerializedNode = Parameters<typeof rebuildIntoSandboxedIframe>[0]

package/src/stage.ts

@@ -1,7 +1,8 @@
-import { createCache, createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+import { createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
 import type { ManifestFrame } from '@describe-me/core/types'
 import { loadSnapshot } from './data.js'
 import { fitStage } from './fit-stage.js'
+import { replayCache } from './replay-cache.js'
 import { state } from './state.js'
 
 let paintToken = 0
@@ -18,7 +19,7 @@ export async function paintFrame(stage: HTMLElement, frame: ManifestFrame): Prom
   const { iframe } = rebuildIntoSandboxedIframe(node, {
     root: stage,
     iframeAttributes: { title: 'snapshot' },
-    cache: createCache(),
+    cache: replayCache,
     mirror: createMirror(),
     hackCss: true,
   })

package/src/states-gallery.ts

@@ -1,8 +1,9 @@
-import { createCache, createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+import { createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
 import type { ManifestFrame, ManifestTest } from '@describe-me/core/types'
 import { contentBox } from './content-box.js'
 import { loadSnapshot } from './data.js'
 import { el } from './el.js'
+import { replayCache } from './replay-cache.js'
 import { select } from './state.js'
 
 /** Bumped on every gallery render, so snapshots that arrive late are dropped. */
@@ -17,7 +18,7 @@ async function paintThumb(thumb: HTMLElement, frame: ManifestFrame, token: numbe
   const { iframe } = rebuildIntoSandboxedIframe(node, {
     root: thumb,
     iframeAttributes: { title: frame.label },
-    cache: createCache(),
+    cache: replayCache,
     mirror: createMirror(),
     hackCss: true,
   })

package/src/style.css

@@ -208,6 +208,104 @@ a {
   box-shadow: 0 0 0 3px color-mix(in srgb, var(--pass) 18%, transparent);
 }
 
+/* ---------------------------------------------------------- diagnostics -- */
+
+.issues {
+  position: relative;
+  font-size: 12px;
+}
+.issues > summary {
+  padding: 2px 9px;
+  border-radius: var(--r-pill);
+  background: color-mix(in srgb, var(--warn) 12%, transparent);
+  color: var(--warn);
+  cursor: pointer;
+  list-style: none;
+}
+.issues > summary::-webkit-details-marker {
+  display: none;
+}
+.issues > summary b {
+  color: inherit;
+}
+.issues[open] > summary {
+  box-shadow: 0 0 0 2px var(--ring);
+}
+.issues-panel {
+  position: absolute;
+  top: calc(100% + 8px);
+  left: 0;
+  z-index: 20;
+  width: 440px;
+  max-height: 70vh;
+  overflow: auto;
+  padding: 6px 0;
+  border: 1px solid var(--line);
+  border-radius: var(--r-lg);
+  background: var(--raised);
+  box-shadow: var(--shadow-md);
+}
+.issues-section {
+  padding: 10px 16px;
+}
+.issues-section + .issues-section {
+  border-top: 1px solid var(--line-soft);
+}
+.issues-section h3 {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  margin: 0;
+  color: var(--ink);
+  font-size: 12px;
+  font-weight: 600;
+}
+.issues-count {
+  color: var(--ink-3);
+  font-weight: 400;
+  font-variant-numeric: tabular-nums;
+}
+.issues-hint {
+  margin: 4px 0 8px;
+  color: var(--ink-3);
+  line-height: 1.45;
+}
+.issues-list {
+  display: grid;
+  gap: 2px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.issues-list li {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+  overflow: hidden;
+  color: var(--ink-2);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.issues-link {
+  overflow: hidden;
+  padding: 2px 0;
+  border: 0;
+  background: none;
+  color: var(--accent);
+  font: inherit;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.issues-link:hover {
+  text-decoration: underline;
+}
+.issues-meta,
+.issues-more {
+  color: var(--ink-3);
+}
+
 /* -------------------------------------------------------------- sidebar -- */
 
 .sidebar {

package/src/without-empty-tests.ts

@@ -0,0 +1,12 @@
+import type { Manifest } from '@describe-me/core/types'
+
+export function withoutEmptyTests(manifest: Manifest): Manifest {
+  const modules = manifest.modules
+    .map((mod) => ({
+      ...mod,
+      tests: mod.tests.filter((test) => test.frames.some((frame) => frame.kind !== 'end')),
+    }))
+    .filter((mod) => mod.tests.length > 0)
+
+  return { ...manifest, modules }
+}

package/vite.config.ts

@@ -1,7 +1,31 @@
 import { cpSync, existsSync, readFileSync, statSync, watch } from 'node:fs'
-import { dirname, join, resolve, sep } from 'node:path'
+import { dirname, extname, join, resolve, sep } from 'node:path'
 import { defineConfig, type Plugin } from 'vite'
 
+/** Content types of what the data directory holds: the manifest, snapshots and copied project assets. */
+const CONTENT_TYPES: Record<string, string> = {
+  '.json': 'application/json',
+  '.css': 'text/css',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+}
+
+function contentType(file: string): string {
+  return CONTENT_TYPES[extname(file).toLowerCase()] ?? 'application/octet-stream'
+}
+
 /** Where the manifest and snapshots live. The CLI sets this; the default is the example project. */
 function dataDir(): string {
   return resolve(process.env.DESCRIBE_ME_DIR ?? '../../examples/react-browser/.describe-me')
@@ -60,7 +84,7 @@ function describeMeData(): Plugin {
           return next()
         }
 
-        response.setHeader('Content-Type', 'application/json')
+        response.setHeader('Content-Type', contentType(absolute))
         response.setHeader('Cache-Control', 'no-store')
         response.end(readFileSync(absolute))
       })