describe-me 0.4.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.4.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.4.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 { ASSET_URL_PREFIX, type Manifest } from '@describe-me/core/types'
+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
   }
@@ -40,10 +40,10 @@ export async function loadManifest(): Promise<void> {
 }
 
 /**
- * Fetch one serialized DOM, memoized until the next manifest load. Asset URLs
- * are made absolute here, against the page, because the snapshot replays in a
- * sandboxed iframe that has no base URL of its own. The stage and the gallery
- * thumbnails both load through this.
+ * 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)
@@ -51,6 +51,11 @@ export function loadSnapshot(path: string): 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)
   }
@@ -59,7 +64,5 @@ export function loadSnapshot(path: string): Promise<SerializedNode> {
 }
 
 function parseSnapshot(json: string): SerializedNode {
-  const assetsUrl = new URL('__data/assets/', location.href).href
-
-  return JSON.parse(json.replaceAll(ASSET_URL_PREFIX, assetsUrl)) as SerializedNode
+  return JSON.parse(resolveAssetUrls(json)) as SerializedNode
 }

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/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 }
+}