blume 1.0.3 → 1.1.0

package/src/astro/adapter-root.ts

@@ -0,0 +1,70 @@
+import { pathToFileURL } from "node:url";
+
+import type { AstroIntegration } from "astro";
+
+/**
+ * Present a deploy adapter with `root` pointed at the real project root rather
+ * than the hidden `.blume` runtime.
+ *
+ * Astro's `root` and `outDir` normally sit together (`outDir` defaults to
+ * `<root>/dist`), and `@astrojs/vercel` leans on that: it writes its Build
+ * Output tree to `<root>/.vercel/output` and — the part that bites — traces the
+ * function's dependency closure with `@vercel/nft` using a base derived from
+ * `root`, silently dropping every traced file that falls outside it.
+ *
+ * Blume splits the two: `root` is `<project>/.blume`, so Astro resolves the
+ * runtime's own `package.json` and its `node_modules` junction, while `outDir`
+ * stays at `<project>/dist` so the build lands where users expect. That puts
+ * `build.server` (`<outDir>/server`) *outside* `root`, so nft's base excludes
+ * the server bundle entirely: the traced file list collapses to `entry.mjs`
+ * alone, and the deployed function dies on its first import with
+ * ERR_MODULE_NOT_FOUND — missing its chunks, its virtual middleware, and every
+ * npm dependency.
+ *
+ * A project inside a workspace accidentally escapes this, because nft's base
+ * search climbs past `.blume` to the workspace root, which does contain both
+ * `dist/` and `node_modules` — which is why the bug only ever surfaced in
+ * standalone projects.
+ *
+ * Handing the adapter the root its own `outDir` assumption implies restores the
+ * invariant without moving Astro's real root: the trace covers `dist/server`
+ * and `node_modules`, and the Build Output tree lands at the project root
+ * natively, where `vercel deploy --prebuilt` looks for it.
+ *
+ * `astro:config:setup` and `astro:config:done` are the only hooks handed a
+ * `config`; an adapter reads `root` from one or both and closes over it for its
+ * later build hooks, so overriding it there covers the whole adapter.
+ */
+const stripTrailingSlashes = (value: string): string => {
+  let end = value.length;
+
+  while (end > 0 && value[end - 1] === "/") {
+    end -= 1;
+  }
+
+  return value.slice(0, end);
+};
+
+export const withAdapterRoot = (
+  integration: AstroIntegration,
+  root: string
+): AstroIntegration => {
+  const rootUrl = pathToFileURL(`${stripTrailingSlashes(root)}/`);
+  const setup = integration.hooks["astro:config:setup"];
+  const done = integration.hooks["astro:config:done"];
+
+  return {
+    ...integration,
+    hooks: {
+      ...integration.hooks,
+      ...(setup && {
+        "astro:config:setup": (options) =>
+          setup({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+      ...(done && {
+        "astro:config:done": (options) =>
+          done({ ...options, config: { ...options.config, root: rootUrl } }),
+      }),
+    },
+  };
+};

package/src/astro/component-slots.ts

@@ -31,8 +31,9 @@ export interface ComponentSlotPlan {
 }
 
 const EMPTY_MODULE = `// Generated by Blume. Do not edit.
-export const mdxComponents = {};
-export const layoutOverrides = {};
+import type { ComponentOverride } from "blume/core/define-components.ts";
+export const mdxComponents: Record<string, ComponentOverride> = {};
+export const layoutOverrides: Record<string, ComponentOverride> = {};
 `;
 
 // A user-supplied attribute value interpolated into a generated .astro tag: a

package/src/astro/generate.ts

@@ -29,7 +29,10 @@ import type {
 } from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
-import { validateNavTargets } from "../core/nav-diagnostics.ts";
+import {
+  validateNavTargets,
+  validateSearchPopularIcons,
+} from "../core/nav-diagnostics.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
@@ -37,11 +40,13 @@ import { resolveDocsCollection } from "../core/sources/resolve.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
-import { hasScalarReferences, referenceTabs } from "../openapi/references.ts";
+import { resolveOgLogo } from "../og/logo.ts";
+import { hasScalarReferences, referenceRoutes } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { registry } from "../registry/registry.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import { resolveSearchPopular } from "../search/popular.ts";
 import { searchProviderMeta, servesStaticIndex } from "../search/providers.ts";
 import {
   examplesEntryTemplate,
@@ -144,23 +149,42 @@ const reactCompilerWarnings = (
       ]
     : [];
 
-/**
- * Realpath of the `astro` package node resolves from a directory, or null when
- * none resolves. Comparing this for `.blume/` against Blume's own deps tells
- * whether the runtime would bind to the *same* astro Blume uses or a different
- * one shadowing it (the hoisted-conflict failure mode).
- */
-const resolvedAstroPath = (fromDir: string): string | null => {
+/** Resolve Astro's package.json directly inside a node_modules directory. */
+const resolveAstroPackageJson = (modulesDir: string): string | null => {
   try {
-    const pkg = createRequire(
-      pathToFileURL(join(fromDir, "_.js")).href
-    ).resolve("astro/package.json");
-    return realpathSync(pkg);
+    return realpathSync(join(modulesDir, "astro", "package.json"));
   } catch {
     return null;
   }
 };
 
+/**
+ * Realpath of the `astro` package reachable through the normal node_modules
+ * ancestor walk from a generated runtime, or null when none resolves.
+ *
+ * This deliberately does not use `createRequire().resolve()`. pnpm's generated
+ * bin shim adds Blume's virtual-store dependencies to `NODE_PATH`, which
+ * CommonJS resolution honors but ESM package resolution ignores. The generated
+ * Astro config uses ESM imports, so treating a NODE_PATH-only result as
+ * reachable skips the dependency link and makes `import "astro/config"` fail.
+ * Walking the physical node_modules ancestors mirrors the lookup that config
+ * actually gets.
+ */
+const resolvedAstroPath = (fromDir: string): string | null => {
+  let dir = normalize(fromDir);
+  while (true) {
+    const resolved = resolveAstroPackageJson(join(dir, "node_modules"));
+    if (resolved) {
+      return resolved;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+
 /**
  * Locate the directory that holds Blume's installed dependencies (Astro and its
  * integrations).
@@ -277,7 +301,7 @@ export const ensureDepsLink = async (
   }
   // Already correct when `.blume/` resolves the very same astro Blume's deps
   // provide — the clean hoisted case, nothing to do.
-  const blumeAstro = resolvedAstroPath(depsDir);
+  const blumeAstro = resolveAstroPackageJson(depsDir);
   const outDirAstro = resolvedAstroPath(outDir);
   if (blumeAstro && outDirAstro === blumeAstro) {
     return null;
@@ -298,7 +322,7 @@ export const ensureDepsLink = async (
 
 /**
  * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
- * `@takumi-rs/core`, …) resolvable when Astro executes the static prerender
+ * `takumi-js`, …) resolvable when Astro executes the static prerender
  * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
  *
  * Astro's static build emits a self-contained SSR bundle to
@@ -626,7 +650,56 @@ const writeStagedContent = async (
   }
 };
 
-/** The logo shape the runtime consumes: an inline SVG or image URL(s). */
+interface LogoDimensions {
+  height: number;
+  width: number;
+}
+
+const SVG_ROOT = /<svg\b(?<attributes>[^>]*)>/u;
+const SVG_WIDTH = /\bwidth\s*=\s*["'](?<value>[^"']+)["']/u;
+const SVG_HEIGHT = /\bheight\s*=\s*["'](?<value>[^"']+)["']/u;
+const SVG_LENGTH = /^\s*(?<value>[\d.]+)(?:px)?\s*$/u;
+const SVG_VIEW_BOX =
+  /\bviewBox\s*=\s*["'][\d.-]+[\s,]+[\d.-]+[\s,]+(?<width>[\d.]+)[\s,]+(?<height>[\d.]+)["']/u;
+
+const parseSvgLength = (value: string | undefined): number | undefined => {
+  const length = Number(value?.match(SVG_LENGTH)?.groups?.value);
+  return length > 0 ? length : undefined;
+};
+
+/** Read dimensions from an SVG's explicit size or its view box. */
+const svgDimensions = (svg: string | undefined): LogoDimensions | undefined => {
+  const attributes = svg?.match(SVG_ROOT)?.groups?.attributes;
+  const width = parseSvgLength(attributes?.match(SVG_WIDTH)?.groups?.value);
+  const height = parseSvgLength(attributes?.match(SVG_HEIGHT)?.groups?.value);
+  if (width && height) {
+    return { height, width };
+  }
+
+  const viewBox = attributes?.match(SVG_VIEW_BOX);
+  const viewBoxWidth = Number(viewBox?.groups?.width);
+  const viewBoxHeight = Number(viewBox?.groups?.height);
+  return viewBoxWidth > 0 && viewBoxHeight > 0
+    ? { height: viewBoxHeight, width: viewBoxWidth }
+    : undefined;
+};
+
+/** Read a local SVG logo from the project root or public directory. */
+const readLogoSvg = (
+  project: BlumeProject,
+  source: string | undefined
+): string | undefined => {
+  if (!source?.toLowerCase().endsWith(".svg")) {
+    return;
+  }
+  const rel = source.replace(/^\//u, "");
+  const file = [
+    join(project.context.root, "public", rel),
+    join(project.context.root, rel),
+  ].find((path) => existsSync(path));
+  return file ? readFileSync(file, "utf-8") : undefined;
+};
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -647,18 +720,20 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   const dark = image?.dark ?? image?.light;
   const alt = image?.alt ?? "";
   const brandHref = href ?? "/";
+  const lightSvg = readLogoSvg(project, light);
+  const darkSvg = dark === light ? lightSvg : readLogoSvg(project, dark);
 
-  if (light && light === dark && light.toLowerCase().endsWith(".svg")) {
-    const rel = light.replace(/^\//u, "");
-    const file = [
-      join(project.context.root, "public", rel),
-      join(project.context.root, rel),
-    ].find((path) => existsSync(path));
-    if (file) {
-      return { alt, href: brandHref, svg: readFileSync(file, "utf-8"), text };
-    }
+  if (light && light === dark && lightSvg) {
+    return { alt, href: brandHref, svg: lightSvg, text };
   }
-  return { alt, dark, href: brandHref, light, text };
+
+  const lightDimensions = svgDimensions(lightSvg);
+  const darkDimensions = svgDimensions(darkSvg);
+  const dimensions =
+    lightDimensions || darkDimensions
+      ? { dark: darkDimensions, light: lightDimensions }
+      : undefined;
+  return { alt, dark, dimensions, href: brandHref, light, text };
 };
 
 /**
@@ -779,6 +854,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     ? `https://github.com/${github.owner}/${github.repo}`
     : null;
   const editBase = github ? `${repoUrl}/edit/${github.branch}` : null;
+  const logo = resolveLogo(project);
+  const ogLogo = config.seo.og.logo
+    ? resolveOgLogo(project, config.seo.og.logo)
+    : logo?.svg;
 
   const editUrlFor = (sourcePath?: string): string | null => {
     if (!(editBase && sourcePath)) {
@@ -791,13 +870,12 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   const { i18n } = config;
 
-  // API reference routes surface as header tabs alongside the content-derived
-  // ones (Blume-rendered references also own a tab-scoped sidebar of operations),
-  // so the reference stays discoverable in every locale.
-  const withReferenceTabs = (nav: Navigation): Navigation => ({
+  // Resolve the header repo link per locale. API references no longer add a tab
+  // automatically — authors point a `navigation.tabs` entry at the reference
+  // route to surface it (see `referenceRoutes`).
+  const withRepoUrl = (nav: Navigation): Navigation => ({
     ...nav,
     repoUrl: config.navigation.repo && repoUrl ? repoUrl : null,
-    tabs: [...nav.tabs, ...referenceTabs(config)],
   });
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
@@ -824,7 +902,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
           code,
-          withReferenceTabs(
+          withRepoUrl(
             graph.navigationByLocale[code] ?? {
               featured: [],
               selectors: [],
@@ -865,7 +943,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
           }
         : null,
       imageZoom: config.markdown.imageZoom,
-      logo: resolveLogo(project),
+      logo,
       mcp: config.ai.mcp.enabled
         ? {
             name: config.ai.mcp.name ?? config.title,
@@ -874,10 +952,16 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         : null,
       // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
       // the optional schema type so the serialized shape stays `boolean`.
-      og: { enabled: config.seo.og.enabled ?? false },
+      og: {
+        enabled: config.seo.og.enabled ?? false,
+        fonts: config.seo.og.fonts ?? [],
+        logo: ogLogo,
+        palette: config.seo.og.palette,
+      },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
+        popular: resolveSearchPopular(config.search.popular, config.basePath),
         provider: config.search.provider,
       },
       site: config.deployment.site ?? null,
@@ -894,7 +978,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     // CSS variables for Astro's <Font> component; matches the astro.config
     // `fonts:` entries derived from the same theme.fonts config.
     fontCssVars: configuredCssVars(config.theme.fonts),
-    navigation: withReferenceTabs(graph.navigation),
+    navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
     routes: manifest.routes.map((route) => ({
@@ -1441,21 +1525,27 @@ export const generateRuntime = async (
 
   // Missing-navigation-target check, now that every servable route is known:
   // content routes, custom `.astro` pages, the generated changelog, and any
-  // OpenAPI reference tabs.
+  // OpenAPI reference routes (so a tab an author points at one still validates).
   const navTargetRoutes = new Set<string>([
     ...project.graph.routes.keys(),
     ...pages.map((page) => page.pattern),
-    ...referenceTabs(config).map((tab) => tab.path),
+    ...referenceRoutes(config),
   ]);
   if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
+  // Curated `search.popular` icons live outside the navigation model, so they
+  // miss `validateNavIcons` in the graph build — they're checked here too,
+  // where the search config is known. A typo otherwise just renders the
+  // default glyph.
   warnings.push(
-    ...validateNavTargets(project.graph.navigation, navTargetRoutes).map(
-      (diagnostic) =>
-        diagnostic.suggestion
-          ? `${diagnostic.message} ${diagnostic.suggestion}`
-          : diagnostic.message
+    ...[
+      ...validateNavTargets(project.graph.navigation, navTargetRoutes),
+      ...validateSearchPopularIcons(config.search.popular),
+    ].map((diagnostic) =>
+      diagnostic.suggestion
+        ? `${diagnostic.message} ${diagnostic.suggestion}`
+        : diagnostic.message
     )
   );
 

package/src/astro/index.ts

@@ -1,3 +1,4 @@
+export { withAdapterRoot } from "./adapter-root.ts";
 export {
   generateRuntime,
   prerenderDepsPlugin,

package/src/astro/pages.ts

@@ -6,11 +6,25 @@ import type { BlumePageRoute } from "./integration.ts";
 
 const PAGE_GLOB = ["**/*.astro"];
 
+/**
+ * Astro's routing convention: a file or folder whose name starts with `_` is a
+ * private partial — importable (shared layouts, home-page sections), but never
+ * built into a route. Blume injects pages itself, so it must reproduce the same
+ * exclusion or every `pages/_home/Hero.astro`-style component ships as an HTML
+ * page.
+ */
+const isPrivatePage = (rel: string): boolean =>
+  rel.split("/").some((segment) => segment.startsWith("_"));
+
 /** Map discovered page files to routes; shared by the async/sync discoverers. */
 const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
   files.sort();
-  return files.map((file) => {
+  const routes: BlumePageRoute[] = [];
+  for (const file of files) {
     const rel = relative(pagesRoot, file);
+    if (isPrivatePage(rel)) {
+      continue;
+    }
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
     const parts = withoutExt.split("/");
     // Only a trailing `index` maps to its parent dir; a folder literally named
@@ -19,8 +33,9 @@ const toPageRoutes = (pagesRoot: string, files: string[]): BlumePageRoute[] => {
       parts.pop();
     }
     const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
-    return { entrypoint: file, pattern };
-  });
+    routes.push({ entrypoint: file, pattern });
+  }
+  return routes;
 };
 
 /**