@kenjura/ursa 0.96.0 → 0.97.0

package/src/helper/fullTextIndex.js

@@ -113,49 +113,61 @@ function extractWords(text) {
  * @returns {Object} - Inverted index: { word: [{ path, score }] }
  */
 export function buildFullTextIndex(documents) {
+  return mergeWordCounts(
+    documents
+      .filter((doc) => doc.content || doc.title)
+      .map((doc) => ({ path: doc.path, counts: documentWordCounts(doc) }))
+  );
+}
+
+/**
+ * Word → weighted count for one document: title words weigh 10, content
+ * words 1. This is the per-document half of the index, so the build graph can
+ * cache it per document and re-tokenize only what was edited.
+ * @param {{title: string, content: string}} doc
+ * @returns {Record<string, number>}
+ */
+export function documentWordCounts(doc) {
+  const wordCounts = {};
+  for (const word of extractWords(doc.title)) {
+    wordCounts[word] = (wordCounts[word] || 0) + 10;
+  }
+  for (const word of extractWords(doc.content)) {
+    wordCounts[word] = (wordCounts[word] || 0) + 1;
+  }
+  return wordCounts;
+}
+
+/**
+ * Merge per-document word counts into the inverted index.
+ * Deterministic: ties in score are broken by path, so the index is a pure
+ * function of its inputs regardless of the order documents arrive in.
+ * @param {Array<{path: string, counts: Record<string, number>}>} docs
+ * @returns {Object} - Inverted index: { word: [{ p: path, s: score }] }
+ */
+export function mergeWordCounts(docs) {
   const index = {};
-  
-  for (const doc of documents) {
-    if (!doc.content && !doc.title) continue;
-    
-    // Extract words from title (higher weight) and content
-    const titleWords = extractWords(doc.title);
-    const contentWords = extractWords(doc.content);
-    
-    // Count word frequencies in this document
-    const wordCounts = {};
-    
-    // Title words get weight of 10
-    for (const word of titleWords) {
-      wordCounts[word] = (wordCounts[word] || 0) + 10;
-    }
-    
-    // Content words get weight of 1
-    for (const word of contentWords) {
-      wordCounts[word] = (wordCounts[word] || 0) + 1;
-    }
-    
-    // Add to inverted index
-    for (const [word, count] of Object.entries(wordCounts)) {
+  for (const { path, counts } of docs) {
+    for (const [word, count] of Object.entries(counts)) {
       if (!index[word]) {
         index[word] = [];
       }
       index[word].push({
-        p: doc.path, // path (shortened key for smaller JSON)
-        s: count,    // score (shortened key)
+        p: path,  // path (shortened key for smaller JSON)
+        s: count, // score (shortened key)
       });
     }
   }
-  
-  // Sort each word's document list by score (descending)
+
+  // Sort each word's document list by score (descending), then path
   for (const word of Object.keys(index)) {
-    index[word].sort((a, b) => b.s - a.s);
+    index[word].sort((a, b) => b.s - a.s || (a.p < b.p ? -1 : a.p > b.p ? 1 : 0));
     // Limit to top 100 documents per word to keep index size reasonable
     if (index[word].length > 100) {
       index[word] = index[word].slice(0, 100);
     }
   }
-  
+
   return index;
 }
 

package/src/helper/imageProcessor.js

@@ -122,6 +122,51 @@ async function isImageSmallEnough(sourcePath) {
   }
 }
 
+/**
+ * Whether ursa handles this extension as an image at all.
+ */
+export function isImageExtension(ext) {
+  const e = ext.toLowerCase();
+  return PROCESSABLE_EXTENSIONS.includes(e) || COPY_ONLY_EXTENSIONS.includes(e);
+}
+
+/**
+ * Decide whether an image gets a WebP preview, without rendering one.
+ * SVG/ICO and unknown formats never do; neither does an image already within
+ * the preview bounds, nor anything when sharp is unavailable. Cheap: reads the
+ * header only. This is what a page needs to know to write its markup; the
+ * expensive encode (`renderPreview`) can then run after the page is served.
+ * @param {string} sourcePath - Absolute path to the image
+ * @returns {Promise<boolean>}
+ */
+export async function willHavePreview(sourcePath) {
+  const ext = extname(sourcePath).toLowerCase();
+  if (!PROCESSABLE_EXTENSIONS.includes(ext)) return false;
+  if (!(await ensureSharp())) return false;
+  return !(await isImageSmallEnough(sourcePath));
+}
+
+/**
+ * Encode the WebP preview of an image and return it.
+ * @param {string} sourcePath - Absolute path to the image
+ * @returns {Promise<Buffer|null>} The WebP bytes, or null when no preview can be made
+ */
+export async function renderPreview(sourcePath) {
+  if (!(await ensureSharp())) return null;
+  try {
+    return await sharp(sourcePath)
+      .resize(PREVIEW_MAX_WIDTH, PREVIEW_MAX_HEIGHT, {
+        fit: 'inside',
+        withoutEnlargement: true, // Don't upscale small images
+      })
+      .webp({ quality: PREVIEW_QUALITY })
+      .toBuffer();
+  } catch (e) {
+    console.warn(`⚠️  Failed to generate preview for ${basename(sourcePath)}: ${e.message}`);
+    return null;
+  }
+}
+
 /**
  * Generate preview filename from original filename
  * e.g., "photo.jpg" -> "photo.preview.webp"

package/src/helper/linkValidator.js

@@ -1,97 +1,70 @@
 import { extname, dirname, join, normalize, posix, basename } from "path";
 
 /**
- * Build a set of valid internal paths from the list of source files and directories.
- * Returns a Map where keys are normalized paths (with/without extension) and values
- * are the canonical resolved paths (always with .html extension).
- * @param {string[]} sourceFiles - Array of source file paths
- * @param {string} source - Source directory path
- * @param {string[]} [directories] - Optional array of directory paths (for auto-index support)
+ * Build the canonical-URL map used for link resolution: normalized (lowercased,
+ * extensionless or .html) paths → the `.html` output they name.
+ *
+ * Rules (docs/PATH_LOGIC.md, README "Link logic", docs/SERVE.md §8.3):
+ *  - `/foo` names `foo.html` when a document `foo.*` exists — the file wins over
+ *    a folder of the same name. With no such document it names the folder's
+ *    index, `foo/index.html`.
+ *  - `/foo/` and `/foo/index.html` name the folder's index page, which exists
+ *    (as a document, a promoted alternate or the auto-index) for every folder
+ *    that has documents somewhere beneath it.
+ *
+ * Which source owns an output is decided elsewhere (`outputOwner`); the map
+ * only says which output a URL means.
+ *
+ * @param {string[]} sourceFiles - Article source paths (absolute, or relative when `source` is "")
+ * @param {string} source - Source directory path (prefix stripped from every path)
+ * @param {string[]} [directories] - Directory paths in the same form
+ * @param {{dirsWithDocuments?: Set<string>}} [opts] - Relative dir paths (no leading slash)
+ *   that hold documents; when omitted every directory is assumed to.
  * @returns {Map<string, string>} Map of normalized paths to canonical resolved paths
  */
-export function buildValidPaths(sourceFiles, source, directories = []) {
+export function buildValidPaths(sourceFiles, source, directories = [], { dirsWithDocuments = null } = {}) {
   const validPaths = new Map();
-  
-  for (const file of sourceFiles) {
-    // Get the path relative to source, without extension
-    const ext = extname(file);
-    let relativePath = file.replace(source, "").replace(ext, "");
-    
-    // Normalize: ensure leading slash, lowercase for comparison
-    if (!relativePath.startsWith("/")) {
-      relativePath = "/" + relativePath;
-    }
-    
-    // Decode URI components for paths with special characters (spaces, etc.)
+
+  const toRelative = (path) => {
+    let rel = source ? path.replace(source, "") : path;
+    if (!rel.startsWith("/")) rel = "/" + rel;
     try {
-      relativePath = decodeURIComponent(relativePath);
+      rel = decodeURIComponent(rel);
     } catch (e) {
       // Ignore decode errors
     }
-    
-    // The canonical resolved path (always .html)
+    return rel;
+  };
+
+  // Documents: the direct mapping is authoritative
+  for (const file of sourceFiles) {
+    const ext = extname(file);
+    const relativePath = toRelative(file.slice(0, file.length - ext.length));
     const resolvedPath = relativePath + ".html";
-    
-    // Add mappings: extensionless and with .html both resolve to the .html version
     validPaths.set(relativePath.toLowerCase(), resolvedPath);
     validPaths.set(resolvedPath.toLowerCase(), resolvedPath);
-    
-    // Also add /index.html variant for directory indexes
-    if (relativePath.endsWith("/index")) {
-      const dirPath = relativePath.replace(/\/index$/, "");
-      const dirResolvedPath = dirPath + "/index.html";
-      validPaths.set(dirPath.toLowerCase(), dirResolvedPath);
-      validPaths.set((dirPath + "/").toLowerCase(), dirResolvedPath);
-      validPaths.set(dirResolvedPath.toLowerCase(), dirResolvedPath);
-    }
-    
-    // Handle (foldername).md files - they get promoted to index.html by auto-index
-    // e.g., /foo/bar/bar.md becomes /foo/bar/index.html (bar.html promoted to index.html)
-    const fileName = basename(relativePath); // e.g., "bar" from "/foo/bar/bar"
-    const parentDir = dirname(relativePath); // e.g., "/foo/bar" from "/foo/bar/bar"
-    const parentDirName = basename(parentDir); // e.g., "bar" from "/foo/bar"
-    
-    if (fileName === parentDirName) {
-      // This file has same name as its parent folder - it will be promoted to index.html
-      const promotedPath = parentDir + "/index.html";
-      validPaths.set(parentDir.toLowerCase(), promotedPath);
-      validPaths.set((parentDir + "/").toLowerCase(), promotedPath);
-      validPaths.set(promotedPath.toLowerCase(), promotedPath);
-    }
   }
-  
-  // Add all directories as valid paths (they get auto-generated index.html)
+
+  // Folders
   for (const dir of directories) {
-    let relativePath = dir.replace(source, "");
-    
-    // Normalize: ensure leading slash
-    if (!relativePath.startsWith("/")) {
-      relativePath = "/" + relativePath;
-    }
-    
-    // Remove trailing slash for consistency
-    if (relativePath.endsWith("/")) {
-      relativePath = relativePath.slice(0, -1);
-    }
-    
-    // Decode URI components
-    try {
-      relativePath = decodeURIComponent(relativePath);
-    } catch (e) {
-      // Ignore decode errors
+    let relativePath = toRelative(dir);
+    if (relativePath.endsWith("/")) relativePath = relativePath.slice(0, -1);
+    if (relativePath === "") continue; // the root is handled below
+    const key = relativePath.toLowerCase();
+    const hasDocs = !dirsWithDocuments || dirsWithDocuments.has(relativePath.replace(/^\//, ""));
+    if (hasDocs) {
+      const indexPath = relativePath + "/index.html";
+      // `/foo` → the folder index, unless a document foo.* already claimed it
+      if (!validPaths.has(key)) validPaths.set(key, indexPath);
+      validPaths.set(key + "/", indexPath);
+      validPaths.set(indexPath.toLowerCase(), indexPath);
     }
-    
-    // All folders resolve to /folder/index.html
-    const resolvedPath = relativePath + "/index.html";
-    validPaths.set(relativePath.toLowerCase(), resolvedPath);
-    validPaths.set((relativePath + "/").toLowerCase(), resolvedPath);
-    validPaths.set(resolvedPath.toLowerCase(), resolvedPath);
   }
-  
+
   // Add root
   validPaths.set("/", "/index.html");
   validPaths.set("/index.html", "/index.html");
-  
+
   return validPaths;
 }
 
@@ -148,7 +121,7 @@ function resolveRelativePath(href, currentDocPath) {
  * @param {string} currentDocPath - The current document's URL path (for relative link resolution)
  * @returns {string} Normalized path
  */
-function normalizeHref(href, currentDocPath = null) {
+export function normalizeHref(href, currentDocPath = null) {
   // Remove hash fragments
   let normalized = href.split("#")[0];
   
@@ -189,6 +162,7 @@ function normalizeHref(href, currentDocPath = null) {
  */
 function resolveHref(href, validPaths, currentDocPath = null) {
   const debugTries = [];
+  const lookup = toLookup(validPaths);
   
   // Get hash fragment if present (to preserve it)
   const hashIndex = href.indexOf('#');
@@ -204,68 +178,84 @@ function resolveHref(href, validPaths, currentDocPath = null) {
     ? resolveRelativePath(hrefWithoutHash, currentDocPath)
     : hrefWithoutHash;
   
-  // Check if path exists in validPaths map - the value is the canonical resolved path
-  if (validPaths.has(normalized)) {
-    const canonicalPath = validPaths.get(normalized);
+  const canonicalPath = lookup(normalized);
+  if (canonicalPath) {
     debugTries.push(`${normalized} → ${canonicalPath} ✓`);
     return { resolvedHref: canonicalPath + hash, inactive: false, debug: debugTries.join(' | ') };
   }
-  
-  // Check if the href already has an extension
+
+  // A .md/.mdx link to a document that does not exist (yet) is still
+  // converted to .html optimistically: the target may be created later.
   const ext = extname(hrefWithoutHash);
+  if (ext && (ext.toLowerCase() === '.md' || ext.toLowerCase() === '.mdx')) {
+    const resolvedHtmlPath = absoluteHref.replace(/\.(md|mdx)$/i, '.html');
+    debugTries.push(`${normalized} (${ext} → .html optimistic) → ${resolvedHtmlPath}`);
+    return { resolvedHref: resolvedHtmlPath + hash, inactive: false, debug: debugTries.join(' | ') };
+  }
+
+  // Nothing owns it - mark as inactive, keep absolute href
+  debugTries.push(`${normalized} → ✗`);
+  return { resolvedHref: absoluteHref + hash, inactive: true, debug: debugTries.join(' | ') };
+}
+
+/**
+ * Resolve one normalized href (lowercased, absolute, no hash or query — see
+ * `normalizeHref`) to the canonical `.html` output it names, or null.
+ *
+ * This is the whole of link resolution's dependence on the site's path set,
+ * isolated so the build graph can hold one `linkResolution` node per distinct
+ * href: adding a document then rewrites only the pages whose links resolve
+ * differently, not every page.
+ *
+ * @param {string} normalized
+ * @param {Map<string, string>} validPaths
+ * @returns {string|null}
+ */
+export function resolveNormalizedHref(normalized, validPaths) {
+  if (validPaths.has(normalized)) return validPaths.get(normalized);
+
+  const ext = extname(normalized);
   if (ext) {
-    // Special handling for .md/.mdx links - always convert to .html
-    // This ensures links work even if the target file is created after serve starts
-    if (ext.toLowerCase() === '.md' || ext.toLowerCase() === '.mdx') {
-      // Remove source extension and convert to .html
+    if (ext === '.md' || ext === '.mdx') {
       const pathWithoutExt = normalized.slice(0, -ext.length);
       const htmlPath = pathWithoutExt + '.html';
-      
-      // Check if .html version exists in validPaths for canonical path
-      if (validPaths.has(htmlPath.toLowerCase())) {
-        const canonicalPath = validPaths.get(htmlPath.toLowerCase());
-        debugTries.push(`${normalized} (${ext} → .html) → ${canonicalPath} ✓`);
-        return { resolvedHref: canonicalPath + hash, inactive: false, debug: debugTries.join(' | ') };
-      }
-      // Also check without extension
-      if (validPaths.has(pathWithoutExt.toLowerCase())) {
-        const canonicalPath = validPaths.get(pathWithoutExt.toLowerCase());
-        debugTries.push(`${normalized} (${ext} → resolved) → ${canonicalPath} ✓`);
-        return { resolvedHref: canonicalPath + hash, inactive: false, debug: debugTries.join(' | ') };
-      }
-      // File doesn't exist yet, but still convert to .html optimistically
-      // (the target file may be created later during serve)
-      const resolvedHtmlPath = absoluteHref.replace(/\.(md|mdx)$/i, '.html');
-      debugTries.push(`${normalized} (${ext} → .html optimistic) → ${resolvedHtmlPath}`);
-      return { resolvedHref: resolvedHtmlPath + hash, inactive: false, debug: debugTries.join(' | ') };
+      if (validPaths.has(htmlPath)) return validPaths.get(htmlPath);
+      if (validPaths.has(pathWithoutExt)) return validPaths.get(pathWithoutExt);
     }
-    // Has extension but doesn't exist (or is not .md)
-    debugTries.push(`${normalized} → ✗`);
-    return { resolvedHref: absoluteHref + hash, inactive: true, debug: debugTries.join(' | ') };
+    return null;
   }
-  
-  // No extension - try .html first
+
+  // No extension - try .html first, then /index.html
   const htmlPath = normalized + '.html';
-  if (validPaths.has(htmlPath.toLowerCase())) {
-    const canonicalPath = validPaths.get(htmlPath.toLowerCase());
-    debugTries.push(`${htmlPath} → ${canonicalPath} ✓`);
-    return { resolvedHref: canonicalPath + hash, inactive: false, debug: debugTries.join(' | ') };
-  }
-  debugTries.push(`${htmlPath} → ✗`);
-  
-  // Try /index.html
-  const indexPath = normalized.endsWith('/') 
-    ? normalized + 'index.html' 
-    : normalized + '/index.html';
-  if (validPaths.has(indexPath.toLowerCase())) {
-    const canonicalPath = validPaths.get(indexPath.toLowerCase());
-    debugTries.push(`${indexPath} → ${canonicalPath} ✓`);
-    return { resolvedHref: canonicalPath + hash, inactive: false, debug: debugTries.join(' | ') };
+  if (validPaths.has(htmlPath)) return validPaths.get(htmlPath);
+  const indexPath = normalized.endsWith('/') ? normalized + 'index.html' : normalized + '/index.html';
+  if (validPaths.has(indexPath)) return validPaths.get(indexPath);
+  return null;
+}
+
+/** Accept either a validPaths Map or a `(normalized) => canonical|null` function. */
+function toLookup(validPathsOrResolver) {
+  if (typeof validPathsOrResolver === 'function') return validPathsOrResolver;
+  return (normalized) => resolveNormalizedHref(normalized, validPathsOrResolver);
+}
+
+/**
+ * Every internal link target in the HTML, normalized the way resolution sees
+ * it. Lets a page ask the build graph for each target before rewriting.
+ * @param {string} html
+ * @param {string} currentDocPath - The current document's URL path
+ * @returns {string[]} Distinct normalized hrefs
+ */
+export function collectInternalHrefs(html, currentDocPath = '/') {
+  const out = new Set();
+  const re = /<a\s+[^>]*?href=["']([^"']+)["'][^>]*>/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    const href = m[1];
+    if (!isInternalLink(href)) continue;
+    out.add(normalizeHref(href.split('#')[0], currentDocPath));
   }
-  debugTries.push(`${indexPath} → ✗`);
-  
-  // Neither exists - mark as inactive, keep absolute href
-  return { resolvedHref: absoluteHref + hash, inactive: true, debug: debugTries.join(' | ') };
+  return [...out];
 }
 
 /**
@@ -276,7 +266,8 @@ function resolveHref(href, validPaths, currentDocPath = null) {
  * 3. Marks broken links with the "inactive" class
  * 
  * @param {string} html - The HTML content
- * @param {Map<string, string>} validPaths - Map of normalized paths to canonical resolved paths
+ * @param {Map<string, string>|((normalized: string) => string|null)} validPaths - Map of
+ *   normalized paths to canonical resolved paths, or a resolver over normalized hrefs
  * @param {string} currentDocPath - The current document's URL path (e.g., "/character/index.html")
  * @param {boolean} includeDebug - Whether to include debug info in link text
  * @returns {string} Processed HTML with resolved links and inactive class on broken links

package/src/helper/mdxRenderer.js

@@ -4,7 +4,7 @@ import React from "react";
 import { renderToString } from "react-dom/server";
 import * as esbuild from "esbuild";
 import { dirname, extname, join, resolve, sep } from "path";
-import { existsSync } from "fs";
+import { existsSync } from "./build/tracedFs.js";
 import { readFile, writeFile, mkdir } from "fs/promises";
 import remarkDirective from "remark-directive";
 import { remarkDefinitionList, defListHastHandlers } from "remark-definition-list";
@@ -245,11 +245,29 @@ function findComponentDirs(startDir, sourceRoot) {
  * @param {string} options.filePath - Absolute path to the MDX file (used for import resolution)
  * @param {string} [options.sourceRoot] - Root directory of the source files (for absolute imports)
  * @param {boolean} [options.hydrate=false] - If true, includes client bundle for hydration
- * @returns {Promise<{ html: string, frontmatter: Record<string, any>, clientCode?: string }>}
+ * @returns {Promise<{ html: string, frontmatter: Record<string, any>, clientCode?: string, inputs: string[] }>}
+ *   `inputs` is every file esbuild loaded while bundling (components, their
+ *   imports, anything under `_components`), excluding node_modules — the
+ *   document's real dependency set, so the build can re-render exactly the
+ *   pages that import an edited component.
  */
 export async function renderMDX({ source, filePath, sourceRoot, hydrate = false }) {
   const cwd = dirname(filePath);
   const componentDirs = findComponentDirs(cwd, sourceRoot);
+  const inputs = new Set();
+
+  /** Records every file esbuild loads; returns nothing so the real loaders still run. */
+  const inputRecorderPlugin = {
+    name: "ursa-input-recorder",
+    setup(build) {
+      build.onLoad({ filter: /.*/ }, (args) => {
+        if (args.namespace === "file" && !args.path.includes(`${sep}node_modules${sep}`)) {
+          inputs.add(args.path);
+        }
+        return undefined;
+      });
+    },
+  };
 
   /**
    * Create esbuild options for the given platform
@@ -277,7 +295,7 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
     }
 
     // Island plugin goes first so it sees component imports before mdx-bundler's resolvers
-    options.plugins = [islandPlugin(platform), ...(options.plugins || [])];
+    options.plugins = [inputRecorderPlugin, islandPlugin(platform), ...(options.plugins || [])];
 
     return options;
   };
@@ -331,7 +349,7 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
 
     // If hydration is not requested, return without client code
     if (!hydrate) {
-      return { html, frontmatter: frontmatter || {} };
+      return { html, frontmatter: frontmatter || {}, inputs: [...inputs].sort() };
     }
 
     // Client-side bundle (for hydration)
@@ -348,9 +366,13 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
       html, 
       frontmatter: frontmatter || {},
       clientCode: clientResult.code,
+      inputs: [...inputs].sort(),
     };
   } catch (error) {
-    throw formatMDXError(error, filePath);
+    const formatted = formatMDXError(error, filePath);
+    formatted.inputs = [...inputs].sort();
+    formatted.componentDirs = componentDirs;
+    throw formatted;
   }
 }
 

package/src/helper/menuLabels.js

@@ -7,9 +7,9 @@
  * resolution rules here is what makes `menu-label: 'BNW - Brave New World'`
  * show up in both places instead of only in the sidebar.
  */
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, currentRecorder } from "./build/tracedFs.js";
 import { basename, extname, join } from "path";
-import { extractMetadata } from "./metadataExtractor.js";
+import { extractMetadata, isMetadataOnly } from "./metadataExtractor.js";
 import { stripHtml } from "./stripHtml.js";
 
 // Index file extensions to check for folder metadata
@@ -29,6 +29,32 @@ export function toDisplayName(filename) {
     .replace(/\b\w/g, c => c.toUpperCase());  // Capitalize first letter of each word
 }
 
+/**
+ * A document's frontmatter and whether it is metadata-only, or null when the
+ * file does not exist.
+ *
+ * When a build-graph node is computing, it may have pre-loaded this from the
+ * document's `docMeta` node into the active recorder's `frontmatter` map. A
+ * hit there records nothing further — the edge to `docMeta` already exists,
+ * and it is a projection that a body edit leaves unchanged. That is what
+ * keeps a paragraph edit from reaching the menu, the auto-indices and every
+ * breadcrumb beneath the folder. A miss reads the file (and records it).
+ *
+ * @param {string} filePath - Path to the source file
+ * @returns {{meta: object|null, isMetadataOnly: boolean}|null}
+ */
+export function readFrontmatterInfo(filePath) {
+  const cached = currentRecorder()?.frontmatter?.get(filePath);
+  if (cached !== undefined) return cached;
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf8');
+    return { meta: extractMetadata(content), isMetadataOnly: isMetadataOnly(content) };
+  } catch (e) {
+    return null;
+  }
+}
+
 /**
  * Read a single frontmatter key from a file, with HTML stripped.
  * @param {string} filePath - Path to the source file
@@ -37,9 +63,8 @@ export function toDisplayName(filename) {
  */
 function getFrontmatterString(filePath, key) {
   try {
-    if (!existsSync(filePath)) return null;
-    const content = readFileSync(filePath, 'utf8');
-    const metadata = extractMetadata(content);
+    const info = readFrontmatterInfo(filePath);
+    const metadata = info?.meta;
     if (metadata && metadata[key]) {
       return stripHtml(String(metadata[key]));
     }

package/src/helper/whitelistFilter.js

@@ -1,6 +1,5 @@
-import { readFile } from 'fs/promises';
+import { readFile, existsSync } from './build/tracedFs.js';
 import { resolve, relative } from 'path';
-import { existsSync } from 'fs';
 
 /**
  * Creates a filter function based on a whitelist file