blume 0.6.7 → 0.7.0

package/src/astro/markdown-negotiation.ts

@@ -18,7 +18,7 @@ const parseAccept = (accept: string): AcceptEntry[] =>
       .slice(1)
       .map((segment) => segment.trim())
       .find((segment) => segment.startsWith("q="));
-    const q = qSegment ? Number.parseFloat(qSegment.slice(2)) : 1;
+    const q = qSegment ? Number(qSegment.slice(2)) : 1;
     return { q: Number.isNaN(q) ? 1 : q, type };
   });
 

package/src/astro/pages.ts

@@ -80,20 +80,25 @@ export const customOgRoutes = (
 ): OgCustomRoute[] => {
   const seen = new Set<string>();
   const routes: OgCustomRoute[] = [];
-  for (const { pattern } of pages) {
+  // Extracted so the skip paths become early `return`s (one `continue` budget
+  // per loop under the lint rule) instead of `continue` statements.
+  const collectRoute = (pattern: string): void => {
     const segments = pattern.split("/").filter(Boolean);
     if (
       segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))
     ) {
-      continue;
+      return;
     }
     const slug = segments.length === 0 ? "index" : segments.join("/");
     if (seen.has(slug)) {
-      continue;
+      return;
     }
     seen.add(slug);
     const last = segments.at(-1);
     routes.push({ slug, title: last ? humanizeSegment(last) : siteTitle });
+  };
+  for (const { pattern } of pages) {
+    collectRoute(pattern);
   }
   return routes;
 };

package/src/astro/templates.ts

@@ -1,12 +1,15 @@
 import { existsSync, readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 
 import { dirname, isAbsolute, join, relative } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { applyBaseToRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
@@ -184,6 +187,19 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * The `react()` integration call. When `compilerPath` is set (the resolved
+ * absolute path to `babel-plugin-react-compiler`), react() carries the compiler
+ * as the first babel plugin — an absolute path, because @vitejs/plugin-react
+ * resolves babel plugins from the *project* root, not `.blume/`, so a bare
+ * specifier wouldn't resolve in a user project. `target: "19"` matches Blume's
+ * React pin. `null`/`undefined` (compiler off or unresolvable) emits bare react().
+ */
+const reactIntegration = (compilerPath: string | null | undefined): string =>
+  compilerPath
+    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] } })`
+    : "react()";
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -194,9 +210,17 @@ export const astroConfigTemplate = (options: {
   contentRoutes: string[];
   dataPath: string;
   examplesPath: string;
+  /** The example-preview Tailwind entry (`blume:examples-theme`). */
+  examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
   openapiPath: string;
+  /**
+   * Absolute path to `babel-plugin-react-compiler` when the React Compiler is
+   * enabled (resolved from Blume's package root by the caller); null/absent
+   * disables the compiler and emits a bare `react()`.
+   */
+  reactCompilerPath?: string | null;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
 }): string => {
@@ -204,6 +228,7 @@ export const astroConfigTemplate = (options: {
   const {
     contentRoutes,
     examplesPath,
+    examplesThemePath,
     needsSvelte,
     needsVue,
     openapiPath,
@@ -248,11 +273,17 @@ export const astroConfigTemplate = (options: {
       })},`
     : "";
 
+  // Base the redirect paths the same way routes are based, so a redirect lands
+  // under `basePath` too. Astro layers its own `base` (deployment.base) on top.
+  const basedRedirects = applyBaseToRedirects(
+    config.redirects,
+    config.basePath
+  );
   const redirectsOption =
-    config.redirects.length > 0
+    basedRedirects.length > 0
       ? `\n  redirects: ${JSON.stringify(
           Object.fromEntries(
-            config.redirects.map((redirect) => [
+            basedRedirects.map((redirect) => [
               redirect.from,
               { destination: redirect.to, status: redirect.status },
             ])
@@ -288,7 +319,7 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
-  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin } from "blume/astro";\n`;
+  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin, serverAppResolvePlugin } from "blume/astro";\n`;
 
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
@@ -297,13 +328,21 @@ export const astroConfigTemplate = (options: {
   const twoslashTransformer =
     "transformerTwoslash({ explicitTrigger: true }), ";
 
+  // Content links are rewritten to their real served URL: the `deployment.base`
+  // subdirectory (Astro doesn't rewrite `<a href>`) plus the site-wide
+  // `basePath` baked into routes. The link checker validates the base-less
+  // authored path against `basePath` routes separately.
+  const contentLinkBase = normalizeBasePath(deployment.base) + config.basePath;
+
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
+      basePath: contentLinkBase,
+      codeThemes: config.markdown.codeBlocks.theme,
       headingAnchors: config.markdown.headingAnchors,
     })}) })`,
   ];
   if (needsReact) {
-    integrations.push("react()");
+    integrations.push(reactIntegration(options.reactCompilerPath));
   }
   if (needsVue) {
     integrations.push("vue()");
@@ -332,12 +371,14 @@ export default defineConfig({
   integrations: [${integrations.join(", ")}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
+      basePath: contentLinkBase,
+      codeThemes: config.markdown.codeBlocks.theme,
       headingAnchors: config.markdown.headingAnchors,
     })}),
     shikiConfig: {
       themes: {
-        light: "github-light",
-        dark: "github-dark",
+        light: ${JSON.stringify(config.markdown.codeBlocks.theme.light)},
+        dark: ${JSON.stringify(config.markdown.codeBlocks.theme.dark)},
       },
       defaultColor: false,
       transformers: [${twoslashTransformer}...blumeShikiTransformers(${JSON.stringify(
@@ -347,7 +388,7 @@ export default defineConfig({
   },
   devToolbar: { enabled: false },
   vite: {
-    plugins: [tailwindcss(), prerenderDepsPlugin()],
+    plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
     // Blume's render-time deps are forced external on both build environments so
     // native bindings resolve at runtime and isolated linkers don't bundle
     // symlinked store copies (which would surface their children as unresolvable
@@ -368,6 +409,7 @@ export default defineConfig({
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
+        "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
         "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
         "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
@@ -396,6 +438,17 @@ export default defineConfig({
 export const stagedContentDir = (outDir: string): string =>
   join(outDir, "content");
 
+/**
+ * Astro's glob loader resolves `base` with `new URL(base, config.root)`. On
+ * Windows an absolute path like `C:\\docs\\content` makes `new URL` parse the
+ * drive letter as a URL scheme, so the result isn't a `file:` URL and Astro's
+ * subsequent `fileURLToPath` throws "The URL must be of scheme file". Emit an
+ * absolute base as a proper `file://` URL so the drive letter can't be mistaken
+ * for a scheme; relative bases resolve against `config.root` unchanged.
+ */
+const astroGlobBase = (base: string): string =>
+  isAbsolute(base) ? pathToFileURL(base).href : base;
+
 /** Generate `.blume/src/content.config.ts`. */
 export const contentConfigTemplate = (options: {
   context: ProjectContext;
@@ -454,8 +507,8 @@ export const contentConfigTemplate = (options: {
         // e.g. a prior `dist/*.mdx` render — and crash the content-module graph.
         // The runtime dir (`.blume`, or a custom distDir) is excluded precisely
         // by `outDirIgnore` instead, so it's left out of this baseline.
-        ...BLUME_IGNORE_DIRS.filter((dir) => dir !== ".blume").map(
-          (dir) => `!**/${dir}/**`
+        ...BLUME_IGNORE_DIRS.flatMap((dir) =>
+          dir === ".blume" ? [] : [`!**/${dir}/**`]
         ),
         ...outDirIgnore,
       ]
@@ -468,7 +521,7 @@ export const contentConfigTemplate = (options: {
 const staged = defineCollection({
   loader: glob({
     pattern: ["**/*.{md,mdx}"],
-    base: ${JSON.stringify(stagedBase)},
+    base: ${JSON.stringify(astroGlobBase(stagedBase))},
     generateId: ({ entry }) => entry,
   }),
 });
@@ -482,7 +535,7 @@ import { glob } from "astro/loaders";
 const docs = defineCollection({
   loader: glob({
     pattern: ${JSON.stringify(docsPattern)},
-    base: ${JSON.stringify(collectionBase)},
+    base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
   }),
 });
@@ -978,6 +1031,7 @@ export const catchAllPageTemplate = (options: {
 // Generated by Blume. Do not edit.
 import { getEntry, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${askImport}
 import Accordion from "blume/components/content/Accordion.astro";
@@ -1103,13 +1157,16 @@ const ogPath = data.config.og.enabled
   ? \`/og/\${route === "/" ? "index" : route.slice(1)}.png\`
   : null;
 const ogRel = seo.image ?? ogPath;
-// Only absolutize root-relative paths: \`seo.image\` may be an external URL,
-// which must pass through verbatim (mirrors PageLayout's absolutizeOgImage).
+// Absolute URLs also carry the deployment base (the page is served under it):
+// \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
+// an external URL, which passes through verbatim (mirrors PageLayout).
 const ogImage =
-  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${ogRel}\` : ogRel;
+  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
 
+const basedRoute = withBase(route);
 const canonical =
-  seo.canonical ?? (base ? \`\${base}\${route === "/" ? "" : route}\` : null);
+  seo.canonical ??
+  (base ? \`\${base}\${basedRoute === "/" ? "" : basedRoute}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -1142,7 +1199,10 @@ const contentLocale =
 const contentDir = i18n
   ? (i18n.locales.find((l) => l.code === contentLocale)?.dir ?? "ltr")
   : "ltr";
-const absolute = (path) => base + (path === "/" ? "" : path);
+const absolute = (path) => {
+  const p = withBase(path);
+  return base + (p === "/" ? "" : p);
+};
 
 const localeAlternates =
   i18n && base
@@ -1575,15 +1635,31 @@ import Example from ${JSON.stringify(spec.file)};
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
 `;
 
+/**
+ * The route prefix `<Component />` preview frames are served under:
+ * `{basePath}/blume-examples/<example path>`. `deployment.base` is layered on
+ * top by Astro (components apply it with `withBase`).
+ */
+export const examplesRouteBase = (basePath: string): string =>
+  `${basePath}/blume-examples`;
+
 /**
  * Generate `.blume/src/generated/examples.ts` — a map of example path to its live
- * wrapper component plus raw source and language for the code tab. Reached by the
- * shipped `Component.astro` via the `blume:examples` alias. Always written (an
+ * wrapper component plus raw source and language for the code tab, and the route
+ * base preview iframes point at. Reached by the shipped `Component.astro` and the
+ * generated preview page via the `blume:examples` alias. Always written (an
  * empty object when there are no examples) so the alias resolves.
  */
-export const exampleMapTemplate = (specs: ExampleSpec[]): string => {
+export const exampleMapTemplate = (
+  specs: ExampleSpec[],
+  basePath: string
+): string => {
+  const base = `export const examplesBase = ${JSON.stringify(
+    examplesRouteBase(basePath)
+  )};`;
   if (specs.length === 0) {
     return `// Generated by Blume. Do not edit.
+${base}
 export const examples = {};
 `;
   }
@@ -1603,12 +1679,83 @@ export const examples = {};
     .join("\n");
   return `// Generated by Blume. Do not edit.
 ${imports}
+${base}
 export const examples = {
 ${entries}
 };
 `;
 };
 
+/**
+ * Generate the `<Component />` preview page — one prerendered route per
+ * example under `{basePath}/blume-examples/`, rendered as a bare document
+ * (no layout) that an iframe in the docs page embeds. The iframe boundary is
+ * what isolates examples from the docs CSS: the only stylesheet here is the
+ * example entry (`blume:examples-theme` — Tailwind, the Blume tokens, and the
+ * user's configured examples css), so users can preview components styled by
+ * their own design system (e.g. shadcn) with no prose styles bleeding in.
+ *
+ * The inline script mirrors the docs theme before first paint — same-document
+ * reads of the parent's `data-theme` (same origin) with a MutationObserver for
+ * live toggles — and sets both `data-theme` and a `dark` class so either
+ * dark-mode convention works in user CSS. When the page is opened directly
+ * (no parent), it falls back to the stored preference, then the OS setting.
+ */
+export const examplesPageTemplate = (): string =>
+  `---
+// Generated by Blume. Do not edit.
+import { examples } from "blume:examples";
+import "blume:examples-theme";
+
+// Prerendered even in server output, like docs content.
+export const prerender = true;
+
+export const getStaticPaths = () =>
+  Object.keys(examples).map((path) => ({ params: { path } }));
+
+const { path } = Astro.params;
+const entry = examples[path];
+const Example = entry.Component;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>{path}</title>
+    <script is:inline>
+      (() => {
+        const root = document.documentElement;
+        const apply = (theme) => {
+          root.dataset.theme = theme;
+          root.classList.toggle("dark", theme === "dark");
+        };
+        const stored = () =>
+          localStorage.getItem("blume-theme") ??
+          (matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light");
+        try {
+          const host = window.parent.document.documentElement;
+          apply(host.dataset.theme ?? stored());
+          new MutationObserver(() => {
+            apply(host.dataset.theme ?? stored());
+          }).observe(host, { attributeFilter: ["data-theme"] });
+        } catch {
+          apply(stored());
+        }
+      })();
+    </script>
+  </head>
+  <!-- Flex + margin:auto centers the example and, unlike place-items, keeps
+       the top edge reachable when the example outgrows the frame. -->
+  <body style="display:flex;min-height:100svh;padding:1.5rem">
+    <div style="margin:auto"><Example /></div>
+  </body>
+</html>
+`;
+
 /** Generate `.blume/src/env.d.ts`. */
 export const envTemplate =
   (): string => `/// <reference path="../.astro/types.d.ts" />

package/src/cli/commands/build.ts

@@ -16,6 +16,7 @@ import {
   surfaceAdapterOutput,
 } from "../../deploy/adapter-output.ts";
 import {
+  applyBaseToRedirects,
   buildNetlifyRedirects,
   buildRedirectManifest,
   buildVercelConfig,
@@ -30,18 +31,27 @@ import { prepareProject } from "../prepare.ts";
 
 const ADAPTERS = ["vercel", "node", "netlify", "cloudflare"] as const;
 
+const BUDGET_JS = "budget-js";
+const BUDGET_CSS = "budget-css";
+
+interface BudgetArgs {
+  "budget-css"?: string;
+  "budget-js"?: string;
+}
+
 /**
  * Reject a non-numeric performance budget. `Number("250kb")` is `NaN` and
  * `total > NaN` is always false, so a typo'd flag would silently pass the gate;
  * fail up front instead.
  */
-const validateBudgetFlags = (args: {
-  "budget-css"?: string;
-  "budget-js"?: string;
-}): void => {
-  for (const flag of ["budget-js", "budget-css"] as const) {
+const validateBudgetFlags = (args: BudgetArgs): void => {
+  for (const flag of [BUDGET_JS, BUDGET_CSS] as const) {
     const value = args[flag];
-    if (value !== undefined && !(Number(value) > 0)) {
+    const parsed = Number(value);
+    // Equivalent to `!(parsed > 0)` but without the inverted check: this must
+    // also reject `NaN` (a typo'd flag like "250kb"), which `parsed <= 0` alone
+    // would let through since `NaN <= 0` is false.
+    if (value !== undefined && (Number.isNaN(parsed) || parsed <= 0)) {
       logger.error(
         `Invalid --${flag} "${value}" (expected a positive number of kB).`
       );
@@ -59,7 +69,7 @@ const emitRedirectFiles = async (
   config: ResolvedConfig,
   distDir: string
 ): Promise<void> => {
-  const { redirects } = config;
+  const redirects = applyBaseToRedirects(config.redirects, config.basePath);
   if (redirects.length === 0 || config.deployment.output !== "static") {
     return;
   }
@@ -82,10 +92,13 @@ const emitRedirectFiles = async (
   logger.success(`Emitted redirect files for ${redirects.length} redirect(s)`);
 };
 
-const formatBytes = (bytes: number): string =>
-  bytes < 1024
-    ? `${bytes} B`
-    : `${(bytes / 1024).toFixed(bytes < 1024 * 100 ? 1 : 0)} kB`;
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  const digits = bytes < 1024 * 100 ? 1 : 0;
+  return `${(bytes / 1024).toFixed(digits)} kB`;
+};
 
 /** Sizes of `dist/_astro/*.<ext>`, largest first (empty when none exist). */
 const astroAssets = async (
@@ -144,14 +157,14 @@ const reportBundleSizes = async (distDir: string): Promise<void> => {
  */
 const enforceBudget = async (
   distDir: string,
-  args: { "budget-css"?: string; "budget-js"?: string }
+  args: BudgetArgs
 ): Promise<"fail" | "pass" | "skip"> => {
   const checks: { ext: string; limitKb: number; name: string }[] = [
-    ...(args["budget-js"]
-      ? [{ ext: "js", limitKb: Number(args["budget-js"]), name: "JavaScript" }]
+    ...(args[BUDGET_JS]
+      ? [{ ext: "js", limitKb: Number(args[BUDGET_JS]), name: "JavaScript" }]
       : []),
-    ...(args["budget-css"]
-      ? [{ ext: "css", limitKb: Number(args["budget-css"]), name: "CSS" }]
+    ...(args[BUDGET_CSS]
+      ? [{ ext: "css", limitKb: Number(args[BUDGET_CSS]), name: "CSS" }]
       : []),
   ];
   if (checks.length === 0) {
@@ -185,7 +198,7 @@ const enforceBudget = async (
 const publishBuildArtifacts = async (
   project: BlumeProject,
   distDir: string,
-  args: { analyze?: boolean; "budget-css"?: string; "budget-js"?: string }
+  args: { analyze?: boolean } & BudgetArgs
 ): Promise<void> => {
   if (project.config.search.provider === "pagefind") {
     logger.start("Building search index");
@@ -280,11 +293,11 @@ export const buildCommand = defineCommand({
       description: "Base path the site is served under (e.g. /docs).",
       type: "string",
     },
-    "budget-css": {
+    [BUDGET_CSS]: {
       description: "Fail if total client CSS exceeds this many kB.",
       type: "string",
     },
-    "budget-js": {
+    [BUDGET_JS]: {
       description: "Fail if total client JavaScript exceeds this many kB.",
       type: "string",
     },

package/src/cli/commands/dev.ts

@@ -18,6 +18,20 @@ import {
 import { logger } from "../log.ts";
 import { prepareProject } from "../prepare.ts";
 
+/**
+ * A fingerprint of the route set: the sorted `path entryId` pairs. It changes
+ * when a page is added, removed, or renamed (a folder rename shifts many at
+ * once) but stays equal across pure body edits — so the dev loop can tell a
+ * "structural" change (needs a cold restart) from a hot-reloadable one.
+ */
+const routeSignature = (
+  routes: readonly { entryId: string; path: string }[]
+): string =>
+  routes
+    .map((route) => `${route.path} ${route.entryId}`)
+    .toSorted()
+    .join("\n");
+
 export const devCommand = defineCommand({
   args: {
     "content-dir": {
@@ -84,15 +98,18 @@ export const devCommand = defineCommand({
       strict: args.strict,
     });
 
-    const server = await dev({
-      logLevel: args.debug ? "debug" : "info",
-      root: project.context.outDir,
-      server: {
-        host: args.host ?? false,
-        open: args.open ?? false,
-        port: explicitPort,
-      },
-    });
+    // A factory so `runRegenerate` can recreate the server on a structural
+    // (route-set) change: only a cold container re-globs Astro's content store,
+    // which its in-place config restart doesn't. `open` is honoured on first
+    // boot only — a restart must not reopen the browser.
+    const createServer = (listenPort: number | undefined, open: boolean) =>
+      dev({
+        logLevel: args.debug ? "debug" : "info",
+        root: project.context.outDir,
+        server: { host: args.host ?? false, open, port: listenPort },
+      });
+
+    let server = await createServer(explicitPort, args.open ?? false);
 
     // Vite bumps to the next free port when the default is taken, so record
     // the port the server actually bound — the lock's URL is what a refused
@@ -109,11 +126,18 @@ export const devCommand = defineCommand({
     // (and its HMR channel) is up.
     showBlumeErrorOverlay(project.diagnostics);
 
-    // 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).
+    let lastSignature = routeSignature(project.manifest.routes);
+
+    // Watch user inputs and regenerate the runtime data on change. A body edit
+    // hot-reloads via Vite (fast path). A route-set change instead forces a cold
+    // server restart: Astro's in-place content sync never re-globs on a Blume
+    // route change (it strips `integrations` from its cache digest) and its glob
+    // watcher misses directory renames, so a renamed page 404s (`getEntry` reads
+    // a stale in-memory store) until the server is restarted. We restart it
+    // ourselves — stop, regenerate while down (no watcher races), then bring up
+    // a fresh container whose cold sync re-globs everything. `coalescedRunner`
+    // single-flights the scan so a burst of watch events can never stack
+    // overlapping regenerations (piled-up scans exhaust the heap).
     const runRegenerate = coalescedRunner(async () => {
       try {
         const next = await scanProject(root, {
@@ -122,7 +146,16 @@ export const devCommand = defineCommand({
           overrides,
           preview,
         });
-        await generateRuntime(next);
+        const nextSignature = routeSignature(next.manifest.routes);
+        const structural = nextSignature !== lastSignature;
+        lastSignature = nextSignature;
+        if (structural) {
+          await server.stop();
+          await generateRuntime(next);
+          server = await createServer(boundPort, false);
+        } else {
+          await generateRuntime(next);
+        }
         // Surface any content/config errors in the browser overlay too.
         showBlumeErrorOverlay(next.diagnostics);
       } catch (error) {

package/src/cli/commands/doctor.ts

@@ -34,8 +34,8 @@ const minSupportedNode = (): string => {
 };
 
 const versionBelow = (current: string, minimum: string): boolean => {
-  const a = current.split(".").map((part) => Number.parseInt(part, 10));
-  const b = minimum.split(".").map((part) => Number.parseInt(part, 10));
+  const a = current.split(".").map((part) => Math.trunc(Number(part)));
+  const b = minimum.split(".").map((part) => Math.trunc(Number(part)));
   for (let i = 0; i < 3; i += 1) {
     const delta = (a[i] ?? 0) - (b[i] ?? 0);
     if (delta !== 0) {

package/src/cli/commands/validate.ts

@@ -47,6 +47,7 @@ export const validateCommand = defineCommand({
       const publicDir = join(root, "public");
       diagnostics.push(
         ...(await validateLinks(project.graph, {
+          basePath: project.config.basePath,
           checkExternal: Boolean(args.external),
           publicDir: existsSync(publicDir) ? publicDir : null,
           redirects: project.config.redirects,

package/src/cli/dev-lock.ts

@@ -117,6 +117,30 @@ const ownsLock = (outDir: string): boolean => {
   }
 };
 
+/**
+ * One atomic claim attempt. Returns `true` when this process wins the `wx`
+ * write, `false` when the dir held a stale or our-own leftover lock (now
+ * cleared, so the caller should retry). Throws {@link DevLockHeldError} when a
+ * live foreign holder owns the dir.
+ */
+const tryClaimLock = (outDir: string, port?: number): boolean => {
+  try {
+    writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw error;
+    }
+    const existing = readDevLock(outDir);
+    if (existing && existing.pid !== process.pid) {
+      throw new DevLockHeldError(existing);
+    }
+    // Stale or our own leftover: clear it and race for the claim again.
+    rmSync(lockPath(outDir), { force: true });
+    return false;
+  }
+};
+
 /**
  * Write the current process's dev lock into `outDir` and return a release
  * function. The claim is atomic (`wx`): two `blume dev` processes racing the
@@ -128,21 +152,8 @@ const ownsLock = (outDir: string): boolean => {
  */
 export const acquireDevLock = (outDir: string, port?: number): (() => void) => {
   mkdirSync(outDir, { recursive: true });
-  for (;;) {
-    try {
-      writeFileSync(lockPath(outDir), lockPayload(port), { flag: "wx" });
-      break;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-        throw error;
-      }
-      const existing = readDevLock(outDir);
-      if (existing && existing.pid !== process.pid) {
-        throw new DevLockHeldError(existing);
-      }
-      // Stale or our own leftover: clear it and race for the claim again.
-      rmSync(lockPath(outDir), { force: true });
-    }
+  while (!tryClaimLock(outDir, port)) {
+    // Retry until we win the claim or a live holder makes us throw.
   }
   let released = false;
   return () => {