describe-me 0.5.0 → 0.5.2

package/dist-cli/vendor-fonts.js

@@ -1,18 +1,24 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { ASSET_URL_PREFIX } from '@describe-me/core/types';
 import { CHROME_USER_AGENT } from './chrome-user-agent.js';
+import { fileNamesIn } from './file-names-in.js';
 import { findRemoteUrls } from './find-remote-urls.js';
 import { FontCache } from './font-cache.js';
 import { fontProvider } from './font-provider.js';
 import { mapWithConcurrency } from './map-with-concurrency.js';
+import { remoteStylesheets } from './remote-stylesheets.js';
+import { replaceAssetNames } from './replace-asset-names.js';
+import { replaceRemoteUrls } from './replace-remote-urls.js';
+import { rewriteStoredFiles } from './rewrite-stored-files.js';
 import { storeVendoredFile } from './store-vendored-file.js';
 import { vendorFontFile } from './vendor-font-file.js';
 import { vendorStylesheet } from './vendor-stylesheet.js';
 const TEXT_DIRECTORIES = [
-    { dir: 'snapshots', extension: '.json', syntax: 'json', prefix: ASSET_URL_PREFIX },
-    { dir: 'styles', extension: '.css', syntax: 'css', prefix: ASSET_URL_PREFIX },
-    { dir: 'assets', extension: '.css', syntax: 'css', prefix: '' },
+    { dir: 'snapshots', extension: '.json', syntax: 'json' },
+    { dir: 'styles', extension: '.css', syntax: 'css' },
+    { dir: 'assets', extension: '.css', syntax: 'css' },
 ];
 /** The test server of the run, gone by now. The reporter lists what it could not copy. */
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
@@ -39,16 +45,9 @@ function planFor(url) {
     return { action: 'remote', host: parsed.hostname, reason: NOT_ALLOWED };
 }
 function textFilesIn(dataDir) {
-    return TEXT_DIRECTORIES.flatMap(({ dir, extension, syntax, prefix }) => {
+    return TEXT_DIRECTORIES.flatMap(({ dir, extension, syntax }) => {
         const abs = join(dataDir, dir);
-        if (!existsSync(abs)) {
-            return [];
-        }
-        return readdirSync(abs, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.endsWith(extension))
-            .map((entry) => entry.name)
-            .sort()
-            .map((name) => ({ path: join(abs, name), syntax, prefix }));
+        return fileNamesIn(abs, extension).map((name) => ({ path: join(abs, name), syntax }));
     });
 }
 function readManifest(dataDir) {
@@ -74,11 +73,16 @@ function scan(dataDir) {
         }
         return vendorable;
     };
-    const files = textFilesIn(dataDir).filter((file) => {
-        return needsVendoring(readFileSync(file.path, 'utf8'), file.syntax);
-    });
+    const kept = textFilesIn(dataDir)
+        .filter((file) => needsVendoring(readFileSync(file.path, 'utf8'), file.syntax))
+        .map((file) => file.path);
     const head = headOf(readManifest(dataDir));
-    return { files, head: head !== null && needsVendoring(head, 'html'), plans };
+    return {
+        kept: new Set(kept),
+        head: head !== null && needsVendoring(head, 'html'),
+        plans,
+        cssAssets: fileNamesIn(join(dataDir, 'assets'), '.css'),
+    };
 }
 /** The failure of a nested file names that file, so the reason is not lost. */
 function failureOf(url, result) {
@@ -104,43 +108,55 @@ function store(target, files) {
         }
     }
 }
-/** Each stored name written in place of every URL it replaces, left to right. */
-function rewrite(text, file, names) {
-    const parts = [];
-    let last = 0;
-    for (const match of findRemoteUrls(text, file.syntax)) {
-        const name = names.get(match.url);
-        if (name !== undefined) {
-            parts.push(text.slice(last, match.start), `${file.prefix}${name}`);
-            last = match.end;
-        }
+function nextHead(manifest, found, names, rewritten) {
+    const head = headOf(manifest);
+    if (head === null || (!found.head && rewritten.assetRenames.size === 0)) {
+        return manifest.head;
+    }
+    const vendored = replaceRemoteUrls(head, 'html', ASSET_URL_PREFIX, names);
+    return replaceAssetNames(vendored, rewritten.assetRenames);
+}
+/**
+ * The hosts that frames still load stylesheets from, counted again only when a
+ * snapshot, chunk or CSS asset changed. An empty or absent list stays as it is.
+ */
+function nextRemoteStylesheets(dataDir, manifest, rewritten) {
+    const listed = manifest.remoteStylesheets;
+    if (!rewritten.changed || !Array.isArray(listed) || listed.length === 0) {
+        return listed;
+    }
+    try {
+        return remoteStylesheets(dataDir, manifest);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`describe-me: remote stylesheet hosts were not counted again (${message}). The issues menu keeps the list from the test run.`);
+        return listed;
     }
-    parts.push(text.slice(last));
-    return parts.join('');
 }
-function rewriteHead(dataDir, names) {
+/**
+ * Write the head and the remote stylesheet hosts in one go, and only when one
+ * of them changed. Every other field keeps its value and its place.
+ */
+function updateManifest(dataDir, found, names, rewritten) {
     const manifest = readManifest(dataDir);
-    const head = headOf(manifest);
-    if (manifest === null || head === null) {
+    if (manifest === null) {
         return;
     }
-    const rewritten = rewrite(head, { syntax: 'html', prefix: ASSET_URL_PREFIX }, names);
-    if (rewritten !== head) {
-        manifest.head = rewritten;
-        writeFileSync(join(dataDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+    const head = nextHead(manifest, found, names, rewritten);
+    const hosts = nextRemoteStylesheets(dataDir, manifest, rewritten);
+    const headChanged = head !== manifest.head;
+    const hostsChanged = !isDeepStrictEqual(hosts, manifest.remoteStylesheets);
+    if (!headChanged && !hostsChanged) {
+        return;
     }
-}
-function rewriteTexts(dataDir, found, names) {
-    for (const file of found.files) {
-        const text = readFileSync(file.path, 'utf8');
-        const rewritten = rewrite(text, file, names);
-        if (rewritten !== text) {
-            writeFileSync(file.path, rewritten);
-        }
+    if (headChanged) {
+        manifest.head = head;
     }
-    if (found.head) {
-        rewriteHead(dataDir, names);
+    if (hostsChanged) {
+        manifest.remoteStylesheets = hosts;
     }
+    writeFileSync(join(dataDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
 }
 /** Code-unit order, the same on every machine. */
 function byText(left, right) {
@@ -183,8 +199,11 @@ function contextFor(options) {
 /**
  * Download the web fonts that a data directory loads from known font hosts
  * into its `assets/`, and point the manifest head, snapshots, style chunks and
- * CSS assets at the copies. Meant for the copy inside a built site. Every file
- * is stored before any text changes, so a crash leaves only valid references.
+ * CSS assets at the copies. Meant for the copy inside a built site. A style
+ * chunk or CSS asset whose text changes moves to the hash of its new text, and
+ * the manifest's `remoteStylesheets` is counted again. Every file is stored
+ * before any text that names it changes, and replaced files are removed last,
+ * so a crash leaves only valid references.
  */
 export async function vendorFonts(dataDir, options) {
     const found = scan(dataDir);
@@ -213,7 +232,16 @@ export async function vendorFonts(dataDir, options) {
             vendoredStylesheets.push(url);
         }
     });
-    rewriteTexts(dataDir, found, names);
+    const rewritten = rewriteStoredFiles(dataDir, {
+        names,
+        cssAssets: found.cssAssets,
+        kept: found.kept,
+        vendored: new Set(target.files.keys()),
+    });
+    updateManifest(dataDir, found, names, rewritten);
+    for (const path of rewritten.replaced) {
+        rmSync(path, { force: true });
+    }
     const fonts = [...target.files.values()].filter((file) => file.extension !== '.css');
     return {
         stylesheets: stylesheetsPerHost(vendoredStylesheets),

package/dist-cli/vendored-name.d.ts

@@ -1,2 +1,2 @@
-/** The name a vendored file gets in `assets/`: the sha1-16 of its bytes plus its extension. */
+/** The name a vendored or rewritten file gets: the sha1-16 of its bytes plus its extension. */
 export declare function vendoredName(bytes: Uint8Array, extension: string): string;

package/dist-cli/vendored-name.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-/** The name a vendored file gets in `assets/`: the sha1-16 of its bytes plus its extension. */
+/** The name a vendored or rewritten file gets: the sha1-16 of its bytes plus its extension. */
 export function vendoredName(bytes, extension) {
     return `${createHash('sha1').update(bytes).digest('hex').slice(0, 16)}${extension}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "describe-me",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Living component documentation generated from your Vitest tests: viewer and CLI",
   "keywords": [
     "vitest",
@@ -42,7 +42,7 @@
   "sideEffects": false,
   "dependencies": {
     "rrweb-snapshot": "^2.1.6",
-    "@describe-me/core": "^0.5.0"
+    "@describe-me/core": "^0.5.2"
   },
   "peerDependencies": {
     "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"

package/src/apply-viewport.ts

@@ -21,10 +21,14 @@ export function applyViewport(
 
   const width = state.viewport.width ?? available
   const scale = Math.min(1, available / width)
+  const visibleHeight =
+    stage.clientHeight - parseFloat(padding.paddingTop) - parseFloat(padding.paddingBottom)
 
   iframe.style.width = `${width}px`
 
-  const height = state.viewport.height ?? naturalHeight(iframe) ?? iframe.offsetHeight
+  const height =
+    state.viewport.height ?? naturalHeight(iframe, visibleHeight / scale) ?? iframe.offsetHeight
+
   iframe.style.height = `${height}px`
 
   if (scale < 1) {

package/src/data.ts

@@ -34,26 +34,45 @@ export async function loadManifest(): Promise<void> {
  * 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.
+ * styled boxes. A snapshot that failed or came back with missing styles is not
+ * kept, so its next paint loads it again.
  */
 export function loadSnapshot(path: string): Promise<SerializedNode> {
-  let pending = snapshotCache.get(path)
-  if (!pending) {
-    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)
+  const memo = snapshotCache.get(path)
+  if (memo) {
+    return memo
   }
 
+  // A new manifest may have replaced the entry by the time this one settles.
+  const forget = (): void => {
+    if (snapshotCache.get(path) === pending) {
+      snapshotCache.delete(path)
+    }
+  }
+
+  const pending = fetchSnapshot(path).then(async (node) => {
+    if (!(await restoreStyles(node))) {
+      forget()
+    }
+
+    return node
+  })
+
+  pending.catch(forget)
+  snapshotCache.set(path, pending)
+
   return pending
 }
 
+async function fetchSnapshot(path: string): Promise<SerializedNode> {
+  const response = await fetch(`__data/${path}`, { cache: 'no-store' })
+  if (!response.ok) {
+    throw new Error(`snapshot ${path}: ${response.status}`)
+  }
+
+  return parseSnapshot(await response.text())
+}
+
 function parseSnapshot(json: string): SerializedNode {
   return JSON.parse(resolveAssetUrls(json)) as SerializedNode
 }

package/src/diagnostics-menu.ts

@@ -32,15 +32,16 @@ function pick(testId: string): void {
 
 /**
  * A header chip that opens the list of what this manifest could not document:
- * anonymous components, components without props docs, assets that will not
- * load, font families that nothing loads and hosts that frames load
- * stylesheets from. Absent when there is nothing to report.
+ * problems in the test setup, anonymous components, components without props
+ * docs, assets that will not load, font families that nothing loads and hosts
+ * that frames load stylesheets from. Absent when there is nothing to report.
  */
 export function renderDiagnosticsMenu(manifest: Manifest): HTMLElement | null {
-  const { anonymous, undocumented, assetsMissing, fontsMissing, remoteStylesheets } =
+  const { setupWarnings, anonymous, undocumented, assetsMissing, fontsMissing, remoteStylesheets } =
     manifestDiagnostics(manifest)
 
   const count =
+    setupWarnings.length +
     anonymous.length +
     undocumented.length +
     assetsMissing.length +
@@ -53,6 +54,18 @@ export function renderDiagnosticsMenu(manifest: Manifest): HTMLElement | null {
 
   const sections: HTMLElement[] = []
 
+  if (setupWarnings.length > 0) {
+    const items = setupWarnings.map((warning) => el('li', {}, warning))
+
+    sections.push(
+      section(
+        'Setup',
+        'The plugin found a problem in the test setup that can make tests fail.',
+        items,
+      ),
+    )
+  }
+
   if (anonymous.length > 0) {
     const items = anonymous.map((test) =>
       el(

package/src/fonts-settled.ts

@@ -1,3 +1,9 @@
+/** What failed to load in a replayed frame, each list deduplicated and in document order. */
+export interface FontFailures {
+  families: string[]
+  stylesheets: string[]
+}
+
 /**
  * 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
@@ -9,22 +15,62 @@ function nextFrame(): Promise<void> {
   })
 }
 
+/**
+ * A failed link by its host when it comes from elsewhere, by its file name
+ * otherwise. Parsed URLs are compared, never substrings of them.
+ */
+function stylesheetName(link: HTMLLinkElement): string | null {
+  let url: URL
+  try {
+    url = new URL(link.href)
+  } catch {
+    return null
+  }
+
+  if (url.origin !== location.origin) {
+    return url.host
+  }
+
+  return url.pathname.split('/').pop() || url.pathname
+}
+
 /** A link that already has its sheet counts as loaded, a failed one as settled. */
-function stylesheetSettled(link: HTMLLinkElement): Promise<void> {
+function stylesheetSettled(link: HTMLLinkElement, failed: Set<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 })
+    link.addEventListener(
+      'error',
+      () => {
+        failed.add(link)
+        resolve()
+      },
+      { once: true },
+    )
   })
 }
 
-function stylesheetsSettled(doc: Document): Promise<unknown> {
+function stylesheetsSettled(doc: Document, failed: Set<HTMLLinkElement>): Promise<unknown> {
   const links = Array.from(doc.querySelectorAll<HTMLLinkElement>('link[rel~=stylesheet]'))
 
-  return Promise.all(links.map((link) => stylesheetSettled(link)))
+  return Promise.all(links.map((link) => stylesheetSettled(link, failed)))
+}
+
+function failures(doc: Document, failed: Set<HTMLLinkElement>): FontFailures {
+  const links = Array.from(doc.querySelectorAll<HTMLLinkElement>('link[rel~=stylesheet]'))
+  const stylesheets = links
+    .filter((link) => failed.has(link))
+    .map((link) => stylesheetName(link))
+    .filter((name) => name !== null)
+
+  const families = Array.from(doc.fonts)
+    .filter((face) => face.status === 'error')
+    .map((face) => face.family.replace(/^(["'])(.*)\1$/, '$2'))
+
+  return { families: [...new Set(families)], stylesheets: [...new Set(stylesheets)] }
 }
 
 function loadingFacesSettled(doc: Document): Promise<unknown> {
@@ -40,8 +86,8 @@ async function facesSettled(doc: Document): Promise<void> {
   await loadingFacesSettled(doc)
 }
 
-async function settle(doc: Document): Promise<void> {
-  await stylesheetsSettled(doc)
+async function settle(doc: Document, failed: Set<HTMLLinkElement>): Promise<void> {
+  await stylesheetsSettled(doc, failed)
   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
@@ -51,23 +97,26 @@ async function settle(doc: Document): Promise<void> {
 
 /**
  * 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.
+ * or failed, or after `timeoutMs`, with what failed so far. Never rejects.
+ * Call it right after the rebuild, before any `await`, so no stylesheet's
+ * `load` or `error` event is missed.
  */
-export function fontsSettled(iframe: HTMLIFrameElement, timeoutMs = 3000): Promise<void> {
+export function fontsSettled(iframe: HTMLIFrameElement, timeoutMs = 3000): Promise<FontFailures> {
   const doc = iframe.contentDocument
   if (!doc) {
-    return Promise.resolve()
+    return Promise.resolve({ families: [], stylesheets: [] })
   }
 
+  const failed = new Set<HTMLLinkElement>()
+
   return new Promise((resolve) => {
-    const timer = setTimeout(resolve, timeoutMs)
+    const timer = setTimeout(() => resolve(failures(doc, failed)), timeoutMs)
 
-    settle(doc)
+    settle(doc, failed)
       .catch(() => undefined)
       .finally(() => {
         clearTimeout(timer)
-        resolve()
+        resolve(failures(doc, failed))
       })
   })
 }

package/src/keyboard.ts

@@ -2,6 +2,7 @@ import type { ManifestTest } from '@describe-me/core/types'
 import { regions } from './regions.js'
 import { rerender } from './rerender.js'
 import { testsInScope } from './scope.js'
+import { sidebarOrder } from './sidebar-order.js'
 import { currentTest, select, state, writeHash } from './state.js'
 import { visibleTests } from './visible-tests.js'
 
@@ -20,14 +21,33 @@ function onSuiteKey(event: KeyboardEvent, key: string): void {
   event.preventDefault()
 }
 
-/** The next or previous test in the list. From outside it, ↓ enters at the top and ↑ at the bottom. */
-function neighbour(tests: ManifestTest[], id: string, step: 1 | -1): ManifestTest | undefined {
+/** The first test after `id` in sidebar order, going by `step`, that the sidebar shows. */
+function nearestShown(shown: ManifestTest[], id: string, step: 1 | -1): ManifestTest | undefined {
+  const shownIds = new Set(shown.map((test) => test.id))
+  const order = sidebarOrder()
+  const start = order.findIndex((candidate) => candidate.id === id)
+  const ahead = step === 1 ? order.slice(start + 1) : order.slice(0, Math.max(0, start)).reverse()
+
+  return ahead.find((candidate) => shownIds.has(candidate.id))
+}
+
+/**
+ * The next or previous test the sidebar shows. From a test hidden in a
+ * collapsed suite, that is the nearest shown row in sidebar order. From a test
+ * the search does not match, ↓ enters at the first match and ↑ at the last.
+ */
+function neighbour(id: string, step: 1 | -1): ManifestTest | undefined {
+  const tests = visibleTests()
   const index = tests.findIndex((candidate) => candidate.id === id)
-  if (index < 0) {
-    return step === 1 ? tests[0] : tests[tests.length - 1]
+  if (index >= 0) {
+    return tests[index + step]
+  }
+
+  if (state.query.trim() === '') {
+    return nearestShown(tests, id, step)
   }
 
-  return tests[index + step]
+  return step === 1 ? tests[0] : tests[tests.length - 1]
 }
 
 /** Arrow keys move the caret or the value in a field, so shortcuts stay out of the way there. */
@@ -81,9 +101,9 @@ export function onKey(event: KeyboardEvent): void {
   }
 
   if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-    const next = neighbour(visibleTests(), test.id, event.key === 'ArrowDown' ? 1 : -1)
+    const next = neighbour(test.id, event.key === 'ArrowDown' ? 1 : -1)
     if (next) {
-      select(next.id)
+      select(next.id, 0, 'replace')
     }
 
     event.preventDefault()

package/src/load-style.ts

@@ -1,5 +1,14 @@
 import { resolveAssetUrls } from './resolve-asset-urls.js'
 
+/** How long a failed chunk waits before its one retry. */
+const RETRY_DELAY_MS = 500
+
+/** A stylesheet put back together, and whether every chunk of it arrived. */
+export interface LoadedStyle {
+  css: string
+  complete: boolean
+}
+
 /**
  * Chunk texts by hash, kept as promises so parallel thumbnails share one
  * request. Never cleared, because a hash always names the same text.
@@ -7,12 +16,17 @@ import { resolveAssetUrls } from './resolve-asset-urls.js'
 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>>()
+const sheets = new Map<string, Promise<LoadedStyle>>()
 
-async function fetchChunk(hash: string): Promise<string | null> {
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+async function fetchOnce(hash: string, init?: RequestInit): 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`)
+    const response = await fetch(`__data/styles/${hash}.css`, init)
 
     return response.ok ? resolveAssetUrls(await response.text()) : null
   } catch {
@@ -20,6 +34,20 @@ async function fetchChunk(hash: string): Promise<string | null> {
   }
 }
 
+async function fetchChunk(hash: string): Promise<string | null> {
+  // Default caching: the name is a content hash, so a cached copy is always right.
+  const first = await fetchOnce(hash)
+  if (first !== null) {
+    return first
+  }
+
+  // A chunk may be missing for a moment while a site redeploys. The retry
+  // bypasses the HTTP cache, which may have kept the 404.
+  await delay(RETRY_DELAY_MS)
+
+  return fetchOnce(hash, { cache: 'reload' })
+}
+
 function loadChunk(hash: string): Promise<string | null> {
   const memo = chunks.get(hash)
   if (memo) {
@@ -42,10 +70,10 @@ function loadChunk(hash: string): Promise<string | null> {
 
 /**
  * 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.
+ * that fails to load leaves a gap rather than failing the frame, marks the
+ * sheet incomplete and is fetched again next time.
  */
-export function loadStyle(reference: string): Promise<string> {
+export function loadStyle(reference: string): Promise<LoadedStyle> {
   const memo = sheets.get(reference)
   if (memo) {
     return memo
@@ -53,11 +81,12 @@ export function loadStyle(reference: string): Promise<string> {
 
   const loads = reference.split('+').map((hash) => loadChunk(hash))
   const pending = Promise.all(loads).then((texts) => {
-    if (texts.includes(null)) {
+    const complete = !texts.includes(null)
+    if (!complete) {
       sheets.delete(reference)
     }
 
-    return texts.map((text) => text ?? '').join('')
+    return { css: texts.map((text) => text ?? '').join(''), complete }
   })
 
   sheets.set(reference, pending)

package/src/min-frame-height.ts

@@ -0,0 +1,2 @@
+/** The shortest stage frame in CSS pixels, for auto height and for a fixed `h` alike. */
+export const MIN_FRAME_HEIGHT = 120