blume 0.5.2 → 0.5.3

package/src/components/content/mermaid-element.ts

@@ -24,6 +24,9 @@ const prefersDark = () => document.documentElement.dataset.theme === "dark";
 let counter = 0;
 
 class BlumeMermaid extends HTMLElement {
+  #observer: MutationObserver | null = null;
+  #renderToken = 0;
+
   connectedCallback() {
     const source = this.dataset.source ?? "";
     if (!source.trim()) {
@@ -35,6 +38,8 @@ class BlumeMermaid extends HTMLElement {
     this.replaceChildren(output);
 
     const render = async () => {
+      this.#renderToken += 1;
+      const token = this.#renderToken;
       const mermaid = await loadMermaid();
       mermaid.initialize({
         securityLevel: "strict",
@@ -47,7 +52,11 @@ class BlumeMermaid extends HTMLElement {
           `blume-mermaid-${counter}`,
           source
         );
-        output.innerHTML = svg;
+        // A newer render (rapid theme toggles) superseded this one — dropping
+        // the stale result keeps the diagram in the latest theme.
+        if (token === this.#renderToken) {
+          output.innerHTML = svg;
+        }
       } catch {
         output.textContent = "Could not render this diagram.";
       }
@@ -57,10 +66,19 @@ class BlumeMermaid extends HTMLElement {
     render();
 
     // Re-render on color-theme changes so the diagram tracks light and dark.
-    new MutationObserver(() => render()).observe(document.documentElement, {
+    // One observer per connection, disconnected on removal — otherwise every
+    // DOM move stacks another observer that renders into detached DOM forever.
+    this.#observer?.disconnect();
+    this.#observer = new MutationObserver(() => render());
+    this.#observer.observe(document.documentElement, {
       attributeFilter: ["data-theme"],
     });
   }
+
+  disconnectedCallback() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+  }
 }
 
 if (!customElements.get("blume-mermaid")) {

package/src/components/islands/ask-ai.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import type { FormEvent } from "react";
 
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { joinBase, stripBase } from "./base-path.ts";
 
 interface ChatMessage {
   id: number;
@@ -27,16 +28,11 @@ const nextId = (): number => {
 
 // The endpoint and page path both honor the deployment `base` so grounding works
 // under a non-root base path (the server matches base-less document routes).
-const ASK_ENDPOINT = `${import.meta.env.BASE_URL}api/ask`.replace("//", "/");
+const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
 /** The current route with the deployment base stripped, for page-context lookup. */
-const currentPath = (): string => {
-  const base = import.meta.env.BASE_URL;
-  const path = window.location.pathname;
-  return base.length > 1 && path.startsWith(base)
-    ? `/${path.slice(base.length)}`
-    : path;
-};
+const currentPath = (): string =>
+  stripBase(import.meta.env.BASE_URL, window.location.pathname);
 
 const BUTTON_CLASS =
   "inline-flex h-9 cursor-pointer items-center gap-2 rounded-blume border border-border bg-muted px-2.5 text-muted-foreground text-sm hover:border-accent disabled:opacity-50";

package/src/components/islands/base-path.ts

@@ -0,0 +1,30 @@
+/**
+ * Base-path helpers for client islands. Astro's default `trailingSlash:
+ * "ignore"` passes `deployment.base` through as-is, so `BASE_URL` may arrive
+ * with or without a trailing slash (`/docs` or `/docs/`); every consumer must
+ * treat both forms the same or endpoints/grounding break under a base path.
+ */
+
+/** The base with a guaranteed trailing slash (`/docs` -> `/docs/`). */
+export const withTrailingSlash = (base: string): string =>
+  base.endsWith("/") ? base : `${base}/`;
+
+/** Join a base-relative path (`api/ask`) onto the deployment base. */
+export const joinBase = (base: string, path: string): string =>
+  `${withTrailingSlash(base)}${path}`;
+
+/**
+ * A pathname with the deployment base stripped (`/docs/guide` -> `/guide`),
+ * for page-context lookups against base-less document routes.
+ */
+export const stripBase = (base: string, pathname: string): string => {
+  const slashed = withTrailingSlash(base);
+  if (slashed === "/") {
+    return pathname;
+  }
+  if (pathname.startsWith(slashed)) {
+    return `/${pathname.slice(slashed.length)}`;
+  }
+  // The bare base itself ("/docs") is the base-less root.
+  return `${pathname}/` === slashed ? "/" : pathname;
+};

package/src/components/islands/hooks.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { BlumeClientData } from "../../core/data.ts";
 import type { SearchFn, SearchResult } from "../layout/search/types.ts";
+import { joinBase, stripBase } from "./base-path.ts";
 
 /**
  * React hooks for Blume islands.
@@ -117,16 +118,11 @@ export interface UseAskAI {
   reset: () => void;
 }
 
-const ASK_ENDPOINT = `${import.meta.env.BASE_URL}api/ask`.replace("//", "/");
+const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
 /** The current route with the deployment base stripped, for page grounding. */
-const currentPath = (): string => {
-  const base = import.meta.env.BASE_URL;
-  const path = window.location.pathname;
-  return base.length > 1 && path.startsWith(base)
-    ? `/${path.slice(base.length)}`
-    : path;
-};
+const currentPath = (): string =>
+  stripBase(import.meta.env.BASE_URL, window.location.pathname);
 
 /**
  * Stream answers from the Ask AI endpoint. Mirrors the built-in Ask AI island so
@@ -158,6 +154,14 @@ export const useAskAI = (): UseAskAI => {
           headers: { "content-type": "application/json" },
           method: "POST",
         });
+        if (!response.ok) {
+          // An error body (JSON, HTML error page) must not stream in as the
+          // assistant's answer.
+          assistant.content =
+            "Something went wrong answering that. Please try again.";
+          setMessages([...history, { ...assistant }]);
+          return;
+        }
         const reader = response.body?.getReader();
         const decoder = new TextDecoder();
         if (reader) {

package/src/components/layout/PageActions.astro

@@ -311,7 +311,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           .replace(/[^a-z0-9]+/gu, "-")
           .replace(/^-+|-+$/gu, "") || "docs";
 
-      const cursorConfig = btoa(JSON.stringify({ url: mcpUrl }));
+      // Base64 output can contain `+`/`=`, which a query string mangles
+      // (`+` decodes as a space) — it must be URL-encoded like any other value.
+      const cursorConfig = encodeURIComponent(btoa(JSON.stringify({ url: mcpUrl })));
       root
         .querySelector("[data-mcp-cursor]")
         ?.setAttribute(
@@ -325,20 +327,22 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
           `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: id, type: "http", url: mcpUrl }))}`
         );
 
-      const flash = (el: Element | null, text: string, reset: string) => {
-        if (el) {
-          el.textContent = text;
-          setTimeout(() => {
-            el.textContent = reset;
-          }, 1500);
+      const flash = (el: Element | null, text: string) => {
+        if (!(el instanceof HTMLElement)) {
+          return;
         }
+        // Remember the element's own (localized) label once — capturing it at
+        // click time would capture "Copied!" on a double-click and stick.
+        el.dataset.blumeLabel ??= el.textContent ?? "";
+        el.textContent = text;
+        setTimeout(() => {
+          el.textContent = el.dataset.blumeLabel ?? "";
+        }, 1500);
       };
       const copy = async (value: string, el: Element | null) => {
-        // Restore the element's own label, so localized text round-trips.
-        const reset = el?.textContent ?? "";
         try {
           await navigator.clipboard.writeText(value);
-          flash(el, copiedLabel, reset);
+          flash(el, copiedLabel);
         } catch {
           // Clipboard unavailable; nothing to do.
         }
@@ -359,10 +363,12 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     }
 
     const label = root.querySelector("[data-blume-copy-label]");
+    // Captured once — inside the handler a double-click would capture and
+    // permanently restore "Copied!".
+    const original = label?.textContent ?? "";
     root
       .querySelector("[data-blume-copy-page]")
       ?.addEventListener("click", async () => {
-        const original = label?.textContent ?? "";
         try {
           const response = await fetch(md);
           await navigator.clipboard.writeText(await response.text());

package/src/components/layout/Search.astro

@@ -296,10 +296,13 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.input.focus();
         this.input.select();
         if (!this.loaded) {
-          this.loaded = true;
           try {
             const { createSearch } = await import("blume:search-client");
             this.searchFn = await createSearch();
+            // Only latch on success — a transient failure (flaky network
+            // fetching the index) must retry on the next open, not disable
+            // search until a full page reload.
+            this.loaded = true;
           } catch {
             this.searchFn = null;
           }

package/src/components/layout/search/types.ts

@@ -74,15 +74,26 @@ const queryTokens = (query: string): string[] =>
     .filter(Boolean)
     .map((token) => token.replaceAll(REGEXP_SPECIAL, String.raw`\$&`));
 
-/** Wrap query matches in `<mark>`, after HTML-escaping the source text. */
+/**
+ * Wrap query matches in `<mark>`, HTML-escaping the source text. Matching runs
+ * on the *raw* text and escaping on each segment — matching after escaping
+ * would let a query like "amp" or "lt" mark the inside of an entity produced
+ * from the source (`&amp;` in "a & b"), corrupting the rendered excerpt.
+ */
 export const highlight = (text: string, query: string): string => {
-  const escaped = escapeHtml(text);
   const tokens = queryTokens(query);
   if (tokens.length === 0) {
-    return escaped;
+    return escapeHtml(text);
   }
-  const pattern = new RegExp(`(?<match>${tokens.join("|")})`, "giu");
-  return escaped.replaceAll(pattern, "<mark>$<match></mark>");
+  const pattern = new RegExp(`(${tokens.join("|")})`, "giu");
+  return text
+    .split(pattern)
+    .map((segment, index) =>
+      index % 2 === 1
+        ? `<mark>${escapeHtml(segment)}</mark>`
+        : escapeHtml(segment)
+    )
+    .join("");
 };
 
 /** First index in `text` where any query token matches (case-insensitive). */

package/src/components/openapi/ParametersTable.astro

@@ -48,7 +48,7 @@ const groups = SECTIONS.map((section) => ({
       <div class="not-prose rounded-blume border border-border px-4">
         {group.items.map((param) => {
           const resolved = resolveSchema(schemas, param.schema ?? {});
-          const type = param.schema ? typeLabel(param.schema, schemas) : "string";
+          const type = param.schema ? typeLabel(param.schema) : "string";
           const limits = constraints(resolved);
           const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
           return (

package/src/components/openapi/SchemaProperty.astro

@@ -31,7 +31,7 @@ const refLabel = typeof schema.$ref === "string" ? refName(schema.$ref) : null;
 const circular = refLabel !== null && seen.includes(refLabel);
 const resolved = resolveSchema(schemas, schema);
 
-const type = typeLabel(schema, schemas);
+const type = typeLabel(schema);
 const description = resolved.description ?? schema.description ?? "";
 const deprecated = resolved.deprecated === true;
 const nullable = isNullable(resolved);

package/src/components/openapi/SchemaTable.astro

@@ -45,7 +45,7 @@ const { properties, required } = circular
   ) : isArray ? (
     <div>
       <div class="mb-2 text-muted-foreground text-xs">
-        Array of <code class="text-foreground">{typeLabel(items ?? {}, schemas)}</code>
+        Array of <code class="text-foreground">{typeLabel(items ?? {})}</code>
       </div>
       {items && (
         <Astro.self schema={items} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
@@ -59,7 +59,7 @@ const { properties, required } = circular
       {branches.map((branch, index) => (
         <div class="rounded-blume border border-border p-3">
           <div class="mb-2 font-medium text-foreground text-xs">
-            {typeLabel(branch, schemas) || `Option ${index + 1}`}
+            {typeLabel(branch) || `Option ${index + 1}`}
           </div>
           <Astro.self schema={branch} schemas={schemas} seen={nextSeen} expandAll={expandAll} />
         </div>
@@ -80,7 +80,7 @@ const { properties, required } = circular
     </div>
   ) : (
     <div class="text-muted-foreground text-sm">
-      <code class="text-foreground">{typeLabel(resolved, schemas)}</code>
+      <code class="text-foreground">{typeLabel(resolved)}</code>
     </div>
   )
 }

package/src/components/openapi/helpers.ts

@@ -69,17 +69,18 @@ const nonNullTypes = (type: string | string[] | undefined): string[] => {
   return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
 };
 
-/** A short, human-readable type label for a schema row. */
-export const typeLabel = (
-  schema: SchemaLike,
-  schemas: Record<string, SchemaLike>
-): string => {
+/**
+ * A short, human-readable type label for a schema row. `$ref`s label by name
+ * (`Pet`, `Pet[]`) without resolving — which also means circular refs through
+ * array items can't recurse forever.
+ */
+export const typeLabel = (schema: SchemaLike): string => {
   if (typeof schema.$ref === "string") {
     return refName(schema.$ref);
   }
   if (schema.oneOf || schema.anyOf) {
     const branches = schema.oneOf ?? schema.anyOf ?? [];
-    const labels = branches.map((branch) => typeLabel(branch, schemas));
+    const labels = branches.map((branch) => typeLabel(branch));
     return [...new Set(labels)].join(" | ") || "any";
   }
   if (schema.allOf) {
@@ -87,8 +88,7 @@ export const typeLabel = (
   }
   const types = nonNullTypes(schema.type);
   if (types.includes("array")) {
-    const item = resolveSchema(schemas, schema.items);
-    return `${typeLabel(item, schemas)}[]`;
+    return `${typeLabel(schema.items ?? {})}[]`;
   }
   const base = types[0] ?? (schema.properties ? "object" : "any");
   return schema.format ? `${base}<${schema.format}>` : base;
@@ -136,8 +136,17 @@ export const objectProperties = (
 ): { properties: [string, SchemaLike][]; required: Set<string> } => {
   const properties = new Map<string, SchemaLike>();
   const required = new Set<string>();
+  // Cycles can only enter through `$ref`s (inline JSON can't self-nest), so
+  // tracking visited refs is enough to stop circular allOf chains recursing.
+  const seen = new Set<string>();
 
   const collect = (node: SchemaLike): void => {
+    if (typeof node.$ref === "string") {
+      if (seen.has(node.$ref)) {
+        return;
+      }
+      seen.add(node.$ref);
+    }
     const resolved = resolveSchema(schemas, node);
     for (const name of resolved.required ?? []) {
       required.add(name);

package/src/components/openapi/snippets.ts

@@ -115,7 +115,9 @@ const curlSnippet = (sample: RequestSample): string => {
     ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
   ];
   if (sample.body) {
-    lines.push(`  -d '${sample.body}'`);
+    // Close-quote/escaped-quote/reopen: the POSIX way to put a literal ' in a
+    // single-quoted string, so an example like "it's" doesn't break the shell.
+    lines.push(`  -d '${sample.body.replaceAll("'", String.raw`'\''`)}'`);
   }
   return lines.join(" \\\n");
 };
@@ -137,12 +139,23 @@ const fetchSnippet = (sample: RequestSample): string => {
   )}\n});`;
 };
 
+// Split-with-capture: odd segments are JSON string literals, kept verbatim so
+// a string *value* containing the words true/false/null isn't rewritten.
+const JSON_STRING = /(?<literal>"(?:\\.|[^"\\])*")/gu;
+
 /** Turn a JSON literal into an equivalent Python literal (`true` -> `True`). */
 const toPython = (json: string): string =>
   json
-    .replaceAll(/\btrue\b/gu, "True")
-    .replaceAll(/\bfalse\b/gu, "False")
-    .replaceAll(/\bnull\b/gu, "None");
+    .split(JSON_STRING)
+    .map((part, index) =>
+      index % 2 === 1
+        ? part
+        : part
+            .replaceAll(/\btrue\b/gu, "True")
+            .replaceAll(/\bfalse\b/gu, "False")
+            .replaceAll(/\bnull\b/gu, "None")
+    )
+    .join("");
 
 const pythonSnippet = (sample: RequestSample): string => {
   const args = [`    "${sample.url}"`];

package/src/core/config.ts

@@ -85,13 +85,22 @@ export const loadConfig = async (
       file: sourceFile ?? undefined,
       source,
     });
+    const [first, ...rest] = diagnostics;
+    const primary = first ?? {
+      code: "BLUME_CONFIG_INVALID",
+      file: sourceFile ?? undefined,
+      message: "Invalid Blume config.",
+      severity: "error" as const,
+    };
+    // Surface every issue in one failing run — reporting only the first turns
+    // a three-mistake config into three fix-rerun-fail loops.
     throw new BlumeError(
-      diagnostics[0] ?? {
-        code: "BLUME_CONFIG_INVALID",
-        file: sourceFile ?? undefined,
-        message: "Invalid Blume config.",
-        severity: "error",
-      }
+      rest.length > 0
+        ? {
+            ...primary,
+            message: `${primary.message}\n${rest.length} more config issue(s):\n${rest.map((d) => `  - ${d.message}`).join("\n")}`,
+          }
+        : primary
     );
   }
 

package/src/core/graph.ts

@@ -91,7 +91,12 @@ export const buildContentGraph = (
       navigationByLocale[code] = buildNavigation(localePages, {
         chromeVariants: options.navigation.chromeVariants,
         folderMeta: options.folderMeta,
-        metaPrefix: code === i18n.defaultLocale ? "" : code,
+        // Meta files live in locale directories only under the `dir` parser
+        // (`fr/guides/meta.ts` -> key `fr/guides`). Under `dot`, translations
+        // sit next to the originals and `guides/meta.ts` applies to every
+        // locale — prefixing would look up keys that can never exist.
+        metaPrefix:
+          i18n.parser === "dir" && code !== i18n.defaultLocale ? code : "",
         refByLogical: true,
         selectors: options.navigation.selectors,
         sharedFolderMeta: options.sharedFolderMeta,

package/src/core/navigation.ts

@@ -255,7 +255,11 @@ const normalizeRef = (ref: string): string => {
     return "/";
   }
   const withSlash = ref.startsWith("/") ? ref : `/${ref}`;
-  return withSlash.endsWith("/index") ? withSlash.slice(0, -6) : withSlash;
+  const trimmed = withSlash.endsWith("/index")
+    ? withSlash.slice(0, -"/index".length)
+    : withSlash;
+  // "/index" trims to "" — that's the root, not an empty route.
+  return trimmed === "" ? "/" : trimmed;
 };
 
 const routeForRef = (

package/src/core/sources/filesystem.ts

@@ -7,6 +7,11 @@ import { glob } from "tinyglobby";
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
+import {
+  BLUME_WATCH_IGNORE_DIRS,
+  excludeDirSegments,
+  ignoringWatchListener,
+} from "./watch.ts";
 
 /** Options for the built-in filesystem source. */
 export interface FilesystemSourceOptions {
@@ -75,13 +80,26 @@ export const filesystemSource = (
     }
   };
 
+  // When `content.root` is the project root (a migrated `.`-rooted project),
+  // the recursive dev watcher would otherwise see Blume's own `.blume/` output
+  // and loop; skip it, VCS/dependency trees, and every excluded dir so the
+  // watcher stays in sync with what `load()` globs. See {@link ignoringWatchListener}.
+  const watchIgnoreDirs = new Set([
+    ...BLUME_WATCH_IGNORE_DIRS,
+    ...excludeDirSegments(options.exclude),
+  ]);
+
   const watch = (onChange: () => void): (() => void) => {
     if (!existsSync(contentRoot)) {
       return () => {
         // Nothing to dispose when the root doesn't exist yet.
       };
     }
-    const watcher = fsWatch(contentRoot, { recursive: true }, onChange);
+    const watcher = fsWatch(
+      contentRoot,
+      { recursive: true },
+      ignoringWatchListener(onChange, watchIgnoreDirs)
+    );
     return () => watcher.close();
   };
 

package/src/core/sources/mdx-remote.ts

@@ -91,9 +91,23 @@ interface RemoteRef {
   editUrl?: string;
 }
 
-const githubHeaders = (): Record<string, string> => {
+// Hosts the GITHUB_TOKEN may be sent to. A configured `url` base can point at
+// any server, and leaking the token there would hand a repo credential to an
+// arbitrary third party.
+const GITHUB_HOSTS = new Set(["api.github.com", "raw.githubusercontent.com"]);
+
+const githubHeaders = (url: string): Record<string, string> => {
   const token = process.env.GITHUB_TOKEN;
-  return token ? { authorization: `Bearer ${token}` } : {};
+  if (!token) {
+    return {};
+  }
+  let host = "";
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    return {};
+  }
+  return GITHUB_HOSTS.has(host) ? { authorization: `Bearer ${token}` } : {};
 };
 
 interface GithubTreeEntry {
@@ -110,7 +124,7 @@ const enumerateGithub = async (
   const { owner, repo, ref } = github;
   const base = github.path.replaceAll(/^\/|\/$/gu, "");
   const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
-  const res = await doFetch(treeUrl, { headers: githubHeaders() });
+  const res = await doFetch(treeUrl, { headers: githubHeaders(treeUrl) });
   if (!res.ok) {
     throw new Error(`${treeUrl} -> ${res.status}`);
   }
@@ -172,7 +186,9 @@ export const mdxRemoteSource = (
   };
 
   const fetchEntry = async (item: RemoteRef): Promise<SourceEntry> => {
-    const res = await doFetch(item.fetchUrl, { headers: githubHeaders() });
+    const res = await doFetch(item.fetchUrl, {
+      headers: githubHeaders(item.fetchUrl),
+    });
     if (!res.ok) {
       throw new Error(`${item.fetchUrl} -> ${res.status}`);
     }

package/src/core/sources/mintlify.ts

@@ -10,6 +10,7 @@ import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
 import type { Diagnostic } from "../types.ts";
 import type { ContentSource, SourceEntry, SourceLoadResult } from "./types.ts";
+import { BLUME_WATCH_IGNORE_DIRS, ignoringWatchListener } from "./watch.ts";
 
 /** Options for the Mintlify bridge content source. */
 export interface MintlifySourceOptions {
@@ -44,39 +45,24 @@ const MINTLIFY_SOURCE_IGNORES = [
 ];
 
 /**
- * Directory names the recursive dev watcher must ignore. In bridge mode the
- * content root is the project root, so a naive recursive `fs.watch` also sees
- * Blume's own `.blume/` output — which the dev server rewrites on every request
- * (`.blume/.astro/data-store.json`). Left unfiltered, each such write re-triggers
- * a full rescan + runtime regeneration, whose writes land back under `.blume/`
- * and fire the watcher again: a self-sustaining storm that stalls page renders
- * and floods the console. `fs.watch` has no ignore option, so we filter by the
- * changed path in the callback. Derived from {@link MINTLIFY_SOURCE_IGNORES}
- * (dir prefixes) plus VCS metadata.
+ * Directory names the recursive dev watcher must ignore, on top of the shared
+ * {@link BLUME_WATCH_IGNORE_DIRS} (Blume's own `.blume/` output, VCS,
+ * dependencies). Derived from {@link MINTLIFY_SOURCE_IGNORES} so bridge mode's
+ * watcher stays in sync with what its scan skips (snippets, build output, …).
  */
-const WATCH_IGNORE_DIRS = new Set([
+const WATCH_IGNORE_DIRS = [
+  ...BLUME_WATCH_IGNORE_DIRS,
   ...MINTLIFY_SOURCE_IGNORES.map((pattern) => pattern.replace(/\/\*\*$/u, "")),
-  ".git",
-]);
+];
 
 /**
- * Build the recursive-watch listener: fire `onChange` for content changes but
- * ignore events whose path crosses a {@link WATCH_IGNORE_DIRS} segment (Blume's
- * own `.blume/` output, `node_modules`, VCS metadata, …). A missing `filename`
- * — rare; the platform couldn't name the changed path — falls through to
- * regenerate rather than silently dropping a real edit. Exported for testing.
+ * Build the recursive-watch listener for the bridge source: ignore events under
+ * {@link WATCH_IGNORE_DIRS} so the dev server's `.blume/` writes don't feed a
+ * regeneration loop. Exported for testing.
  */
-export const mintlifyWatchListener =
-  (onChange: () => void): WatchListener<string> =>
-  (_event, filename) => {
-    if (
-      typeof filename === "string" &&
-      filename.split(/[/\\]/u).some((segment) => WATCH_IGNORE_DIRS.has(segment))
-    ) {
-      return;
-    }
-    onChange();
-  };
+export const mintlifyWatchListener = (
+  onChange: () => void
+): WatchListener<string> => ignoringWatchListener(onChange, WATCH_IGNORE_DIRS);
 
 /**
  * The Mintlify bridge content source. Reads an unconverted Mintlify project in