blume 0.5.1 → 0.5.3

package/dist/types/core/package-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Derive a valid npm package name from a directory name, falling back to
+ * `docs` when nothing usable remains.
+ */
+export declare const toPackageName: (raw: string) => string;
+/**
+ * A minimal, runnable `package.json` body for a Blume project: the `blume`
+ * dependency pinned to the installed version plus `dev`/`build`/`doctor`
+ * scripts, so `npm install && npm run dev` works immediately. Shared by
+ * `blume init` and the migrators, which scaffold one when a project has none.
+ */
+export declare const blumePackageJson: (name: string) => string;

package/dist/types/migrate/shared.d.ts

@@ -0,0 +1,153 @@
+import type { BlumeConfig } from "../core/schema.ts";
+/**
+ * Whether `candidate` resolves to a path inside `root` (or is `root` itself).
+ * Guards migrators against `../` traversal in author-controlled source paths
+ * (`pages` entries, `<include>` targets) that would otherwise read or move
+ * files outside the docs tree.
+ */
+export declare const isInsideRoot: (root: string, candidate: string) => boolean;
+/**
+ * Framework-agnostic helpers shared by more than one migrator. Each piece here
+ * was generalized from a migrator-specific implementation so Mintlify, Nextra,
+ * and future migrators converge on a single copy.
+ */
+/** Serialize a `BlumeConfig` to a `blume.config.ts` at the project root. */
+export declare const writeBlumeConfig: (root: string, config: BlumeConfig) => Promise<void>;
+/**
+ * Rewrite a migrated project's npm scripts off the old framework's CLI. A
+ * `dev`/`build`/`start` script whose command invokes `cli` (e.g. `/\bnext\b/`)
+ * is repointed at the matching Blume command (`start` -> `blume preview`); a
+ * script whose command matches `remove` (e.g. a `fumadocs-mdx` postinstall) is
+ * dropped. Scripts that don't match either are left untouched, so custom tasks
+ * survive. Returns true when `package.json` changed.
+ */
+export declare const rewriteFrameworkScripts: (root: string, cli: RegExp, remove?: RegExp) => Promise<boolean>;
+/** Of the candidate project-relative paths, the ones that still exist — the old
+ * framework files a migration leaves behind for the user to remove by hand. */
+export declare const leftoverFiles: (root: string, candidates: string[]) => string[];
+/**
+ * Scaffold a minimal, runnable `package.json` when the migrated project has
+ * none. Config-only sources (e.g. a Mintlify `docs.json`) ship no npm manifest,
+ * so a fresh migration has nothing to run `blume dev` with; this writes a stub
+ * with `blume` as a dependency and `dev`/`build`/`doctor` scripts, making
+ * `npm install && npm run dev` work immediately. A pre-existing `package.json`
+ * is left untouched — {@link rewriteFrameworkScripts} repoints those instead.
+ * Returns true when a file was created.
+ */
+export declare const ensurePackageJson: (root: string) => Promise<boolean>;
+/**
+ * Remove every match of an import pattern, collapsing the blank gap each
+ * removal leaves behind — without touching blank runs elsewhere in the
+ * document (double blank lines inside code fences are real content that a
+ * whole-document `\n{3,}` collapse used to corrupt).
+ */
+export declare const stripImports: (source: string, pattern: RegExp) => string;
+export interface CalloutRewriteOptions {
+    /** Directive for a type-bearing tag with no `type` attribute (e.g. bare `<Callout>`). */
+    defaultDirective: string;
+    /** Tag names whose directive is fixed by the tag itself (e.g. `<Warning>`). */
+    tagDirectives: Record<string, string>;
+    /** Component tag names to convert. */
+    tags: string[];
+    /** `type="…"` values mapped to Blume directive names. */
+    typeDirectives: Record<string, string>;
+}
+/** Read a quoted string attribute (`name="…"` or `name='…'`) from a tag. */
+export declare const attribute: (attrs: string, name: string) => string | undefined;
+/**
+ * Find the `>` that closes an opening JSX tag, honoring quotes and `{…}`
+ * expression attributes (so a `>` inside `icon={"<svg…>"}` is not mistaken for
+ * the tag end). Returns -1 if unterminated.
+ */
+export declare const findOpenTagEnd: (source: string, from: number) => number;
+/**
+ * Convert callout-style JSX components into Blume `:::` directives. Uses a
+ * quote/brace-aware tag scanner so callouts carrying JSX-expression attributes
+ * (e.g. inline-SVG icons) convert cleanly; non-convertible attributes (icons,
+ * colors, emoji) are dropped. A tag whose resolved directive is unknown is left
+ * untouched.
+ */
+export declare const rewriteCallouts: (source: string, options: CalloutRewriteOptions) => string;
+/**
+ * Remove frontmatter keys Blume's strict page schema would reject (e.g. stray
+ * `og:*`/`twitter:*` metatags) so the migrated page validates, reporting what
+ * was dropped. Validation errors other than stray keys are left for `blume dev`
+ * to surface.
+ */
+export declare const stripUnknownPageMeta: (data: Record<string, unknown>) => {
+    data: Record<string, unknown>;
+    removed: string[];
+};
+/**
+ * Rename a JSX tag (open and close) while preserving its attributes. The
+ * trailing lookahead means a longer tag (e.g. `CardGrid`) is never matched by a
+ * rule for its shorter prefix (`Card`), so prefix-sharing renames can be chained
+ * — run the item-level rename before the container rename.
+ */
+export declare const renameTag: (source: string, from: string, to: string) => string;
+/**
+ * Static readers for JS/TS config files (Nextra `_meta`, Starlight
+ * `astro.config`). Config is parsed by walking the source as text — quote-,
+ * comment-, and bracket-aware — rather than executing user code, matching the
+ * other migrators (which never eval). Values that aren't pure literals (an
+ * identifier, call, JSX, or interpolated template) are reported as `UNPARSEABLE`
+ * so the caller can drop the field and warn.
+ */
+/** Index of a string within a JS source: the close quote matching `s[open]`. */
+export declare const findStringEnd: (s: string, open: number) => number;
+export declare const unescapeString: (inner: string) => string;
+export interface ObjectScanResult {
+    end: number;
+    entries: string[];
+}
+/**
+ * Walk a `{…}` object literal starting at `openIndex`, returning the matching
+ * close-brace index and the raw `key: value` text of each top-level entry.
+ * Quote-, comment-, and bracket-aware so commas/braces nested in strings,
+ * arrays, or child objects don't split entries. Returns null if unterminated.
+ */
+export declare const scanObject: (source: string, openIndex: number) => ObjectScanResult | null;
+export interface ArrayScanResult {
+    elements: string[];
+    end: number;
+}
+/**
+ * Walk a `[…]` array literal starting at `openIndex`, returning the matching
+ * close-bracket index and the raw text of each top-level element. The sibling of
+ * {@link scanObject}; a trailing comma yields no empty element.
+ */
+export declare const scanArray: (source: string, openIndex: number) => ArrayScanResult | null;
+/**
+ * Strip `//` and block comments so they don't leak into entry text (the scanner
+ * splits on slices, so an inter-entry comment would otherwise attach to the next
+ * entry). String literals are preserved verbatim.
+ */
+export declare const stripJsComments: (source: string) => string;
+export interface KeyValue {
+    key: string;
+    value: string;
+}
+/** Split a raw `key: value` entry at its top-level colon. */
+export declare const splitKeyValue: (entry: string) => KeyValue | null;
+/** Read an object key, unquoting it when it is a string literal. */
+export declare const parseKey: (key: string) => string;
+/** Read a clean string literal value, or null if it's an expression. */
+export declare const readString: (value: string) => string | null;
+/** A value that isn't a pure literal (identifier, call, JSX, computed, …). */
+export declare const UNPARSEABLE: unique symbol;
+export type LiteralValue = LiteralValue[] | boolean | null | number | string | typeof UNPARSEABLE | {
+    [key: string]: LiteralValue;
+};
+/**
+ * Evaluate a JS literal expression (string / number / boolean / null / array /
+ * object) into its value without executing it. Anything else resolves to
+ * {@link UNPARSEABLE}; inside arrays the sentinel keeps the element's position,
+ * inside objects it stays as the field's value so the caller can warn and drop.
+ */
+export declare const parseLiteral: (source: string) => LiteralValue;
+/** Narrow a parsed literal to a string. */
+export declare const asLiteralString: (value: LiteralValue | undefined) => string | undefined;
+/** Narrow a parsed literal to a plain object (not an array or `UNPARSEABLE`). */
+export declare const isLiteralObject: (value: LiteralValue | undefined) => value is Record<string, LiteralValue>;
+/** Narrow a parsed literal to an array. */
+export declare const asLiteralArray: (value: LiteralValue | undefined) => LiteralValue[] | undefined;

package/docs/advanced/migrate.mdx

@@ -59,6 +59,7 @@ Reads `docs.json` (or legacy `mint.json`) and rewrites every page **in place**
 - Snippets under `/snippets` are inlined as includes; component snippets (e.g. `.jsx`) are kept and their imports rewritten to relative paths.
 - A Mintlify `openapi` spec — declared top-level or on a nav group (a path, URL, or `{ source, directory }`) — maps to Blume's [native OpenAPI reference](/docs/advanced/api-reference) (`openapi.sources`), which renders one real page per operation. A group's `directory` becomes the reference's route; endpoint refs like `GET /users` are dropped since Blume generates them from the spec.
 - `docs.json` `variables` are inlined into content — Blume has no runtime `{{variable}}` substitution.
+- The source `docs.json`/`mint.json` is removed once `blume.config.ts` is safely written. Leaving it around would keep the project a [Bridge mode](/docs/advanced/bridge) candidate — a later run without a Blume config would silently serve the un-migrated Mintlify site.
 - Multi-language projects map to [`i18n.locales`](/docs/content/i18n); the language nav selector is dropped in favor of Blume's locale switching.
 - Icons resolve against the real bundled libraries — Font Awesome (free), Lucide, and Tabler. The migrator sets [`icons.library: fontawesome`](/docs/content/components#default-library) (Mintlify's default), so Font Awesome names (`shield-halved`, `gauge-high`, `layer-group`, …) and `iconType` styles render unchanged. Pro-only FA styles (`light`/`thin`/`duotone`/`sharp-solid`) fall back to solid.
 - Fonts map to [`theme.fonts`](/docs/configuration/theming) when the family is one of Blume's curated Google Fonts (`fonts.family`, or a `heading`/`body` split); a family outside that set is warned about, not guessed. Header links (`navbar.links`/`navbar.primary`) and footer socials (`footer.socials`) have no `blume.config` equivalent yet, so they're reported as warnings rather than dropped silently — re-add them with [`navigation.tabs`](/docs/content/navigation) or a Header/Footer [layout override](/docs/advanced/custom-pages). The contextual page menu and last-updated timestamp are already Blume defaults.

package/docs/configuration/ai.mdx

@@ -133,7 +133,7 @@ Keys are read with `process.env`, which covers the Node, Vercel, and Netlify ada
 
 ### Rate limiting
 
-The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request (rejecting malformed bodies and capping it to 1–40 messages) to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.
+The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request — rejecting malformed bodies, capping it to 1–40 messages, and accepting only `user`/`assistant` roles so a caller can't inject their own system prompt and repurpose the route as a general LLM proxy — to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.
 
 ## MCP server
 

package/docs/configuration/theming.mdx

@@ -146,7 +146,7 @@ Drop a `theme.css` in your project root to override any design token. It's the l
 }
 ```
 
-Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode.
+Set a token under `:root` for light mode and under `:root[data-theme="dark"]` for dark mode. Color tokens have distinct built-in dark values declared at the dark selector's higher specificity, so a `:root`-only override of `--blume-accent`, `--blume-background`, and friends applies to light mode only — declare the dark block too when both modes should change.
 
 ### Design tokens
 

package/docs/content/i18n.mdx

@@ -85,7 +85,7 @@ i18n: {
 
 ## Per-locale navigation
 
-Each language gets its own sidebar, built from that locale's files — so translations can diverge in structure, ordering, or labels. Folder [`meta.ts`](/docs/content/meta) files resolve per locale, too: put a `meta.ts` under `fr/guides/` to order the French group independently. Everything else about [navigation](/docs/content/navigation) works the same, per language.
+Each language gets its own sidebar, built from that locale's files — so translations can diverge in structure, ordering, or labels. Folder [`meta.ts`](/docs/content/meta) files resolve per locale, too: under the default `dir` parser, put a `meta.ts` under `fr/guides/` to order the French group independently. Under the `dot` parser translations sit next to the originals, so a folder's `meta.ts` applies to every locale. Everything else about [navigation](/docs/content/navigation) works the same, per language.
 
 ## Fallbacks
 

package/docs/content/sources.mdx

@@ -56,7 +56,7 @@ The built-in `mdx-remote` source fetches raw `.md`/`.mdx` over HTTP. Enumerate f
 }
 ```
 
-A private repo's token is read from the `GITHUB_TOKEN` environment variable — it is never inlined into your config or generated output.
+A private repo's token is read from the `GITHUB_TOKEN` environment variable — it is never inlined into your config or generated output, and it is only ever sent to GitHub's own hosts (`api.github.com`, `raw.githubusercontent.com`), never to a custom `url` base.
 
 Remote pages are rendered with full MDX-plus-component fidelity: their bodies are materialized into a hidden staging directory and rendered through Astro alongside your local docs, so callouts, tabs, and every other Blume component keep working.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/mcp/discovery.ts

@@ -10,7 +10,9 @@ export interface McpDiscoveryInput {
 
 /** The MCP server's address — absolute when a site is configured. */
 const serverUrl = (input: McpDiscoveryInput): string =>
-  input.site ? new URL(input.route, input.site).href : input.route;
+  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+  // would drop the base path of a subpath deployment (`acme.com/docs`).
+  input.site ? `${input.site.replace(/\/+$/u, "")}${input.route}` : input.route;
 
 /**
  * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use

package/src/ai/mcp/server.ts

@@ -90,7 +90,9 @@ const normalizeRoute = (input: string): string => {
 
 /** Build the absolute (or root-relative) URL for a route. */
 const urlFor = (route: string, site: string | null): string =>
-  site ? new URL(route, site).href : route;
+  // Concatenate rather than `new URL(route, site)` — a root-absolute route
+  // would drop the base path of a subpath deployment (`acme.com/docs`).
+  site ? `${site.replace(/\/+$/u, "")}${route}` : route;
 
 const text = (value: string, isError = false) => ({
   content: [{ text: value, type: "text" as const }],

package/src/astro/component-slots.ts

@@ -35,6 +35,12 @@ export const mdxComponents = {};
 export const layoutOverrides = {};
 `;
 
+// A user-supplied attribute value interpolated into a generated .astro tag: a
+// stray quote or newline would produce a malformed component and an opaque
+// Astro parse error pointing at the generated file, not the user's config.
+const attributeValue = (value: string): string =>
+  value.replaceAll(/["\n\r]/gu, " ").trim();
+
 /** Astro client directive for a hydrated override. */
 const directiveFor = (override: NormalizedOverride): string => {
   const framework = override.source?.framework;
@@ -47,11 +53,13 @@ const directiveFor = (override: NormalizedOverride): string => {
     }
     case "media": {
       return override.media
-        ? `client:media="${override.media}"`
+        ? `client:media="${attributeValue(override.media)}"`
         : "client:load";
     }
     case "only": {
-      return framework ? `client:only="${framework}"` : "client:load";
+      return framework
+        ? `client:only="${attributeValue(framework)}"`
+        : "client:load";
     }
     default: {
       return "client:load";

package/src/astro/generate.ts

@@ -973,6 +973,11 @@ export const generateRuntime = async (
   // entryId so i18n duplicates of one entry write a single file.
   const staged = collectStaged(project);
   const hasStaged = staged.size > 0;
+  // Only emit a project-scanning `docs` collection when a filesystem source
+  // actually feeds it. Bridge mode has just the staged Mintlify source, so the
+  // `docs` glob would otherwise scan (and watch) the whole project root for
+  // nothing — see contentConfigTemplate.
+  const hasFilesystemSource = project.sources.some((source) => !source.staged);
 
   const structural = await Promise.all([
     write(
@@ -1003,7 +1008,12 @@ export const generateRuntime = async (
     write(join(srcDir, "env.d.ts"), envTemplate()),
     write(
       join(srcDir, "content.config.ts"),
-      contentConfigTemplate({ config, context, staged: hasStaged })
+      contentConfigTemplate({
+        config,
+        context,
+        filesystem: hasFilesystemSource,
+        staged: hasStaged,
+      })
     ),
     write(
       join(srcDir, "pages", "[...slug].astro"),

package/src/astro/static-assets.ts

@@ -41,9 +41,16 @@ const isContained = (parent: string, child: string): boolean => {
 
 /** Resolve a request URL to an on-disk file within one of the mounts, if any. */
 const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
-  const pathname = decodeURIComponent(
-    (url.split("?")[0] ?? "").split("#")[0] ?? ""
-  );
+  let pathname: string;
+  try {
+    pathname = decodeURIComponent(
+      (url.split("?")[0] ?? "").split("#")[0] ?? ""
+    );
+  } catch {
+    // Malformed percent-encoding (`/images/%zz`) throws URIError; treat it as
+    // a plain miss (404) rather than a middleware exception.
+    return null;
+  }
   for (const mount of mounts) {
     if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
       continue;

package/src/astro/templates.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 
-import { dirname, join } from "pathe";
+import { dirname, isAbsolute, join, relative } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
@@ -374,6 +374,15 @@ export default defineConfig({
       fs: {
         allow: ${JSON.stringify(fsAllow)},
       },
+      // Keep the file watcher out of Astro's own cache dir. In a migrated
+      // (root-rooted) project the docs collection is rooted at the project dir,
+      // so its glob-loader watcher would otherwise fire on every write Astro
+      // makes under .blume/.astro (data-store.json, content module manifests,
+      // self-hosted fonts) -- pure noise the loader logs as "No entry type
+      // found". Vite appends this to its default ignores.
+      watch: {
+        ignored: ${JSON.stringify([join(context.outDir, ".astro", "**")])},
+      },
     },
   },
 });
@@ -392,18 +401,44 @@ export const contentConfigTemplate = (options: {
   staged?: boolean;
   /** Base dir for the staged collection; defaults to `<outDir>/content`. */
   stagedBase?: string;
+  /**
+   * Whether any filesystem (non-staged) source feeds the `docs` collection.
+   * When false (e.g. Mintlify bridge mode, where every page is staged), the
+   * collection globs nothing — see below.
+   */
+  filesystem?: boolean;
 }): string => {
   const { context, config } = options;
   const stagedBase = options.stagedBase ?? stagedContentDir(context.outDir);
 
   // Fold the content excludes into the glob as negative patterns so the `docs`
-  // collection never walks into ignored trees. This matters when `content.root`
-  // is the project root (Mintlify bridge mode, or a migrated `.`-rooted project):
-  // without it the collection would scan `node_modules`, `snippets`, etc.
-  const docsPattern = [
-    ...config.content.include,
-    ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
-  ];
+  // collection doesn't ingest ignored trees (`node_modules`, `snippets`, the
+  // staged bodies under `.blume/content`, …) as entries. This matters when
+  // `content.root` is the project root (a migrated `.`-rooted project).
+  const outDirRel = relative(context.contentRoot, context.outDir);
+  const outDirIgnore =
+    outDirRel && !outDirRel.startsWith("..") && !isAbsolute(outDirRel)
+      ? [`!${outDirRel}/**`]
+      : [];
+
+  // With no filesystem source, no route renders through `docs`, so glob nothing.
+  // Beyond skipping wasted work, this is the only thing that keeps Astro's
+  // content-layer *watcher* out of `.blume/`: bridge mode roots the collection
+  // at the project dir (which contains `.blume/.astro/fonts`, rewritten on every
+  // request), and the watcher's match test is `picomatch.isMatch(path, pattern)`
+  // — with array-OR semantics, any `!ignored/**` negation *matches* unrelated
+  // files, so negative patterns can't exclude a subtree there. An empty pattern
+  // matches nothing, so the watcher stays silent. The collection is still
+  // declared below so `getCollection("docs")` / `getEntry` resolve (to empty).
+  const filesystem = options.filesystem ?? true;
+  const docsPattern = filesystem
+    ? [
+        ...config.content.include,
+        ...(config.content.exclude ?? []).map((pattern) => `!${pattern}`),
+        "!**/node_modules/**",
+        ...outDirIgnore,
+      ]
+    : [];
 
   // Non-filesystem sources render through a parallel `staged` collection backed
   // by materialized MDX, so the filesystem `docs` collection stays untouched.
@@ -477,20 +512,35 @@ export const askEndpointTemplate = (
   }
   // Validate the client-supplied body and cap its size. The endpoint is
   // unauthenticated, so bounding message count/length limits how much a caller
-  // can spend against the model per request; front it with a rate limiter (or
-  // your provider's limits) for stronger protection.
+  // can spend against the model per request, and restricting roles to
+  // user/assistant keeps callers from injecting their own system prompt and
+  // repurposing the endpoint as a general LLM proxy; front it with a rate
+  // limiter (or your provider's limits) for stronger protection.
   const validate = `  const body = await request.json().catch(() => null);
-  const messages = body?.messages;
-  if (
-    !Array.isArray(messages) ||
-    messages.length === 0 ||
-    messages.length > 40 ||
-    JSON.stringify(messages).length > 24_000
-  ) {
-    return new Response("Invalid request: send 1-40 messages.", {
-      status: 400,
-    });
-  }`;
+  const raw = body?.messages;
+  const valid =
+    Array.isArray(raw) &&
+    raw.length > 0 &&
+    raw.length <= 40 &&
+    raw.every(
+      (m: unknown) =>
+        typeof m === "object" &&
+        m !== null &&
+        ("role" in m && (m.role === "user" || m.role === "assistant")) &&
+        ("content" in m && typeof m.content === "string")
+    ) &&
+    JSON.stringify(raw).length <= 24_000;
+  if (!valid) {
+    return new Response(
+      "Invalid request: send 1-40 user/assistant messages with string content.",
+      { status: 400 }
+    );
+  }
+  // Re-build the array so only role/content ever reach the model.
+  const messages = raw.map((m: { role: "user" | "assistant"; content: string }) => ({
+    content: m.content,
+    role: m.role,
+  }));`;
   const stream = grounded
     ? `    const system =
       (await ground(messages, body.page)) ??
@@ -544,10 +594,16 @@ const SEARCH_CLIENT_HEADER = "// Generated by Blume. Do not edit.\n";
 const searchClientImport = (module: string): string =>
   `import { createSearch as create } from "blume/components/layout/search/${module}.ts";\n`;
 
+// Joins a base-relative path onto BASE_URL, which arrives with or without a
+// trailing slash (Astro's default trailingSlash: "ignore" passes `/docs`
+// through bare — naive concatenation would yield `/docsblume-search.json`).
+const SEARCH_BASE_IMPORT =
+  'import { joinBase } from "blume/components/islands/base-path.ts";\n';
+
 /** A client that loads a static `blume-search.json` index (Orama, FlexSearch). */
 const staticSearchClient = (module: string): string =>
-  `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}
-const indexUrl = \`\${import.meta.env.BASE_URL}blume-search.json\`.replace("//", "/");
+  `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}${SEARCH_BASE_IMPORT}
+const indexUrl = joinBase(import.meta.env.BASE_URL, "blume-search.json");
 
 export const createSearch = () => create({ indexUrl });
 `;
@@ -607,16 +663,16 @@ export const searchClientTemplate = (config: ResolvedConfig): string => {
   }
 
   if (search.provider === "mixedbread") {
-    return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}
-const api = \`\${import.meta.env.BASE_URL}api/search\`.replace("//", "/");
+    return `${SEARCH_CLIENT_HEADER}${searchClientImport("endpoint")}${SEARCH_BASE_IMPORT}
+const api = joinBase(import.meta.env.BASE_URL, "api/search");
 
 export const createSearch = () => create({ api });
 `;
   }
 
   if (search.provider === "pagefind") {
-    return `${SEARCH_CLIENT_HEADER}${searchClientImport("pagefind")}
-const url = \`\${import.meta.env.BASE_URL}pagefind/pagefind.js\`.replace("//", "/");
+    return `${SEARCH_CLIENT_HEADER}${searchClientImport("pagefind")}${SEARCH_BASE_IMPORT}
+const url = joinBase(import.meta.env.BASE_URL, "pagefind/pagefind.js");
 
 export const createSearch = () => create({ url });
 `;
@@ -645,8 +701,10 @@ const client = new Mixedbread({ apiKey: process.env.MIXEDBREAD_API_KEY ?? "" });
 const STORE_ID = ${JSON.stringify(storeId)};
 
 export const POST: APIRoute = async ({ request }) => {
-  const { query } = await request.json();
-  if (!query) {
+  // The endpoint is public: a malformed body must 200-empty, not 500.
+  const body = await request.json().catch(() => null);
+  const query = body?.query;
+  if (!query || typeof query !== "string") {
     return new Response("[]", {
       headers: { "Content-Type": "application/json" },
     });

package/src/cli/coalesce.ts

@@ -0,0 +1,43 @@
+/**
+ * Wrap an async task so it never runs concurrently with itself. Triggering the
+ * returned function while a run is in flight coalesces into a single trailing
+ * run after the current one settles.
+ *
+ * Dev regeneration (`scanProject` + `generateRuntime`) is expensive on a large
+ * project — a full content re-scan that allocates big strings. A plain debounce
+ * still lets a fast burst of watch events (or, before it was fixed, a `.blume/`
+ * watch storm) start a new scan before the previous finished, piling up
+ * overlapping scans until the heap is exhausted (observed as an OOM after
+ * minutes of looping). Single-flighting bounds it to one scan at a time while
+ * still guaranteeing a final run reflects the latest change.
+ *
+ * The task must not reject: a rejection would surface as an unhandled promise
+ * rejection, so callers handle their own errors and always resolve.
+ */
+export const coalescedRunner = (task: () => Promise<void>): (() => void) => {
+  let inFlight: Promise<void> | null = null;
+  let pending = false;
+
+  // Drain any run requested during the current run, then release the lock. The
+  // `inFlight` promise is assigned synchronously by the caller below, so a
+  // re-entrant trigger sees the lock immediately and only sets `pending`.
+  const cycle = async (): Promise<void> => {
+    try {
+      do {
+        pending = false;
+        // oxlint-disable-next-line no-await-in-loop -- serialized by design
+        await task();
+      } while (pending);
+    } finally {
+      inFlight = null;
+    }
+  };
+
+  return () => {
+    if (inFlight) {
+      pending = true;
+      return;
+    }
+    inFlight = cycle();
+  };
+};

package/src/cli/commands/dev.ts

@@ -7,7 +7,8 @@ import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { parsePort } from "../args.ts";
-import { acquireDevLock } from "../dev-lock.ts";
+import { coalescedRunner } from "../coalesce.ts";
+import { acquireDevLock, isDevLocked } from "../dev-lock.ts";
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
@@ -62,7 +63,15 @@ export const devCommand = defineCommand({
     }
 
     // Claim the shared `.blume` dir so a concurrent build/eject/sync refuses
-    // rather than regenerating or deleting it out from under this server.
+    // rather than regenerating or deleting it out from under this server. A
+    // second dev server would fight over the same generated tree the same
+    // way, so it must refuse too instead of silently clobbering the lock.
+    if (isDevLocked(project.context.outDir)) {
+      logger.error(
+        "Another `blume dev` is already running in this project; two dev servers would corrupt the shared .blume dir. Stop the other one first (or delete .blume/dev.lock if it crashed)."
+      );
+      process.exit(1);
+    }
     const releaseLock = acquireDevLock(project.context.outDir);
     process.on("exit", releaseLock);
 
@@ -82,26 +91,31 @@ export const devCommand = defineCommand({
 
     // Watch user inputs and regenerate the runtime data on change. Astro/Vite
     // hot-reloads the generated data module so nav and routes stay in sync.
+    // `coalescedRunner` single-flights the scan so a burst of watch events can
+    // never stack overlapping regenerations (a large project's scan can outlast
+    // the debounce; piled-up scans exhaust the heap).
+    const runRegenerate = coalescedRunner(async () => {
+      try {
+        const next = await scanProject(root, {
+          devServerUrl,
+          mode: "dev",
+          overrides,
+          preview,
+        });
+        await generateRuntime(next);
+        // Surface any content/config errors in the browser overlay too.
+        showBlumeErrorOverlay(next.diagnostics);
+      } catch (error) {
+        logger.error(`Regeneration failed: ${(error as Error).message}`);
+      }
+    });
+
     let timer: ReturnType<typeof setTimeout> | null = null;
     const regenerate = () => {
       if (timer) {
         clearTimeout(timer);
       }
-      timer = setTimeout(async () => {
-        try {
-          const next = await scanProject(root, {
-            devServerUrl,
-            mode: "dev",
-            overrides,
-            preview,
-          });
-          await generateRuntime(next);
-          // Surface any content/config errors in the browser overlay too.
-          showBlumeErrorOverlay(next.diagnostics);
-        } catch (error) {
-          logger.error(`Regeneration failed: ${(error as Error).message}`);
-        }
-      }, 80);
+      timer = setTimeout(runRegenerate, 80);
     };
 
     // Content is watched per source (filesystem uses fs.watch; remote sources