describe-me 0.4.0 → 0.5.0-next.1

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.1",
   "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.1"
+  },
+  "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/fonts-settled.ts

@@ -0,0 +1,73 @@
+/**
+ * Wait until the next frame has been styled and laid out. A frame callback
+ * runs before that, the timeout after it, when the fonts that freshly loaded
+ * rules need have started loading.
+ */
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => setTimeout(resolve, 0))
+  })
+}
+
+/** A link that already has its sheet counts as loaded, a failed one as settled. */
+function stylesheetSettled(link: HTMLLinkElement): Promise<void> {
+  if (link.sheet) {
+    return Promise.resolve()
+  }
+
+  return new Promise((resolve) => {
+    link.addEventListener('load', () => resolve(), { once: true })
+    link.addEventListener('error', () => resolve(), { once: true })
+  })
+}
+
+function stylesheetsSettled(doc: Document): Promise<unknown> {
+  const links = Array.from(doc.querySelectorAll<HTMLLinkElement>('link[rel~=stylesheet]'))
+
+  return Promise.all(links.map((link) => stylesheetSettled(link)))
+}
+
+function loadingFacesSettled(doc: Document): Promise<unknown> {
+  const loading = Array.from(doc.fonts).filter((face) => face.status === 'loading')
+
+  return Promise.allSettled(loading.map((face) => face.loaded))
+}
+
+async function facesSettled(doc: Document): Promise<void> {
+  await loadingFacesSettled(doc)
+  // A second pass for the faces that started while the first ones loaded.
+  await nextFrame()
+  await loadingFacesSettled(doc)
+}
+
+async function settle(doc: Document): Promise<void> {
+  await stylesheetsSettled(doc)
+  await nextFrame()
+  // rrweb reopens the document and never closes it, so `fonts.ready` may never
+  // resolve. It may only end the wait early, and only from here on: raced any
+  // sooner, it may have resolved before a single font started loading.
+  await Promise.race([facesSettled(doc), doc.fonts.ready])
+}
+
+/**
+ * Resolve once the stylesheets and web fonts of a replayed frame have loaded
+ * or failed, or after `timeoutMs`. Never rejects. Call it right after the
+ * rebuild, before any `await`, so no stylesheet's `load` event is missed.
+ */
+export function fontsSettled(iframe: HTMLIFrameElement, timeoutMs = 3000): Promise<void> {
+  const doc = iframe.contentDocument
+  if (!doc) {
+    return Promise.resolve()
+  }
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, timeoutMs)
+
+    settle(doc)
+      .catch(() => undefined)
+      .finally(() => {
+        clearTimeout(timer)
+        resolve()
+      })
+  })
+}

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/preview-head.ts

@@ -0,0 +1,21 @@
+import { resolveAssetUrls } from './resolve-asset-urls.js'
+import { state } from './state.js'
+
+let memo: { generatedAt: string; html: string } | null = null
+
+/**
+ * The manifest's preview head, with asset URLs made absolute, ready to go into
+ * every replayed frame. Empty when the manifest has none.
+ */
+export function previewHeadHtml(): string {
+  const manifest = state.manifest
+  if (!manifest) {
+    return ''
+  }
+
+  if (memo?.generatedAt !== manifest.generatedAt) {
+    memo = { generatedAt: manifest.generatedAt, html: resolveAssetUrls(manifest.head ?? '') }
+  }
+
+  return memo.html
+}

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/replay-snapshot.ts

@@ -0,0 +1,33 @@
+import { createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+import { previewHeadHtml } from './preview-head.js'
+import { replayCache } from './replay-cache.js'
+import type { SerializedNode } from './serialized-node.js'
+
+/**
+ * Rebuild a snapshot into a fresh sandboxed iframe inside `root`, with the
+ * preview head at the start of its `<head>`.
+ */
+export function replaySnapshot(
+  root: HTMLElement,
+  node: SerializedNode,
+  title: string,
+): HTMLIFrameElement {
+  const { iframe } = rebuildIntoSandboxedIframe(node, {
+    root,
+    iframeAttributes: { title },
+    cache: replayCache,
+    mirror: createMirror(),
+    hackCss: true,
+  })
+
+  const html = previewHeadHtml()
+  const head = iframe.contentDocument?.head
+
+  // First, so the captured styles win ties, as in Storybook. The sandbox
+  // (`allow-same-origin` only) never runs the head's scripts.
+  if (html !== '' && head) {
+    head.insertAdjacentHTML('afterbegin', html)
+  }
+
+  return iframe
+}

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 type { ManifestFrame } from '@describe-me/core/types'
 import { loadSnapshot } from './data.js'
 import { fitStage } from './fit-stage.js'
+import { fontsSettled } from './fonts-settled.js'
+import { replaySnapshot } from './replay-snapshot.js'
 import { state } from './state.js'
 
 let paintToken = 0
@@ -15,13 +16,8 @@ export async function paintFrame(stage: HTMLElement, frame: ManifestFrame): Prom
   }
 
   stage.replaceChildren()
-  const { iframe } = rebuildIntoSandboxedIframe(node, {
-    root: stage,
-    iframeAttributes: { title: 'snapshot' },
-    cache: createCache(),
-    mirror: createMirror(),
-    hackCss: true,
-  })
+  const iframe = replaySnapshot(stage, node, 'snapshot')
+  const fonts = fontsSettled(iframe)
 
   if (state.width !== 'auto') {
     iframe.style.width = `${state.width}px`
@@ -33,4 +29,10 @@ export async function paintFrame(stage: HTMLElement, frame: ManifestFrame): Prom
       fitStage(iframe)
     }
   })
+
+  // Web fonts arrive later and change the text's size.
+  await fonts
+  if (token === paintToken) {
+    fitStage(iframe)
+  }
 }

package/src/states-gallery.ts

@@ -1,8 +1,9 @@
-import { createCache, 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 { fontsSettled } from './fonts-settled.js'
+import { replaySnapshot } from './replay-snapshot.js'
 import { select } from './state.js'
 
 /** Bumped on every gallery render, so snapshots that arrive late are dropped. */
@@ -14,16 +15,17 @@ async function paintThumb(thumb: HTMLElement, frame: ManifestFrame, token: numbe
     return
   }
 
-  const { iframe } = rebuildIntoSandboxedIframe(node, {
-    root: thumb,
-    iframeAttributes: { title: frame.label },
-    cache: createCache(),
-    mirror: createMirror(),
-    hackCss: true,
-  })
+  const iframe = replaySnapshot(thumb, node, frame.label)
+  const fonts = fontsSettled(iframe)
 
   // Styles are in place after a frame; only then do the boxes have their final size.
   requestAnimationFrame(() => fitThumb(thumb, iframe))
+
+  // Web fonts arrive later and change the text's size.
+  await fonts
+  if (token === galleryToken && thumb.isConnected) {
+    fitThumb(thumb, iframe)
+  }
 }
 
 const THUMB_PADDING = 16

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