blume 0.1.2 → 0.1.4

package/src/astro/generate.ts

@@ -45,7 +45,7 @@ import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { customOgRoutes, discoverPages } from "./pages.ts";
+import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -61,6 +61,7 @@ import {
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
+  notFoundPageTemplate,
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
@@ -786,6 +787,25 @@ const writeMcpFiles = async (
   ]);
 };
 
+/**
+ * Write the default 404 page at Astro's reserved `src/pages/404.astro` path so
+ * static builds emit `dist/404.html`. Skipped when the project already owns
+ * `/404` (a custom `pages/404.astro` or a `404.md` content page), letting it be
+ * fully overridden without a route collision; `pruneOrphans` then removes any
+ * previously-generated copy.
+ */
+const writeNotFoundPage = async (
+  write: (path: string, content: string) => Promise<boolean>,
+  srcDir: string,
+  pages: { pattern: string }[],
+  contentPages: { route: string }[]
+): Promise<void> => {
+  if (routeIsTaken(pages, contentPages, "/404")) {
+    return;
+  }
+  await write(join(srcDir, "pages", "404.astro"), notFoundPageTemplate());
+};
+
 export interface GenerateResult {
   /** Whether any structural file changed (config/page/content config). */
   structuralChange: boolean;
@@ -985,6 +1005,9 @@ export const generateRuntime = async (
     );
   }
 
+  // The default 404 page (`/404`), unless the project already owns the route.
+  await writeNotFoundPage(write, srcDir, pages, project.graph.pages);
+
   // The provider-specific client loader behind the `blume:search-client` alias
   // is always (re)generated so the alias resolves even when search is disabled.
   await write(searchClientPath, searchClientTemplate(config));
@@ -1054,10 +1077,19 @@ export const generateRuntime = async (
     ...exampleDiscovery.warnings,
   ];
 
-  // The new provider SDKs are optional peers; warn (rather than fail opaquely in
-  // Vite) when the configured provider's package isn't installed.
+  // Provider SDKs are optional peers; warn (rather than fail opaquely in Vite)
+  // when the configured provider's package isn't installed. A dep is available
+  // if the project installed it (resolves from the root) OR Blume ships it
+  // (resolves from the Blume package — the same set the `.blume` deps link
+  // exposes to the build). Resolving from the project root alone falsely flagged
+  // a shipped SDK like Orama (the default provider) as missing whenever it
+  // wasn't hoisted into the project, e.g. under isolated linkers. We resolve
+  // from each package's real location rather than through the `.blume` junction,
+  // which can't be traversed reliably for store-symlinked deps.
   for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
-    if (!canResolveFrom(context.root, dep)) {
+    if (
+      !(canResolveFrom(context.root, dep) || canResolveFrom(packageRoot(), dep))
+    ) {
       warnings.push(
         `Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
       );

package/src/astro/pages.ts

@@ -27,6 +27,20 @@ export const discoverPages = async (
   });
 };
 
+/**
+ * Whether the project already owns `route` — through a custom `.astro` page
+ * (injected, so matched on `pattern`) or a content page (matched on `route`).
+ * Used to skip a generated default page (e.g. `/404`, `/changelog`) so a
+ * user-authored page overrides it without a route collision.
+ */
+export const routeIsTaken = (
+  pages: { pattern: string }[],
+  contentPages: { route: string }[],
+  route: string
+): boolean =>
+  pages.some((page) => page.pattern === route) ||
+  contentPages.some((page) => page.route === route);
+
 /** A custom-page route that should get a generated OG card. */
 export interface OgCustomRoute {
   /** `og/<slug>.png` path segment; `index` for the site root. */

package/src/astro/templates.ts

@@ -1188,6 +1188,54 @@ const canonical = base ? base + "/changelog" : null;
 `;
 };
 
+/**
+ * Generate `.blume/src/pages/404.astro`: the default not-found page. Rendered
+ * through `PageLayout` (header + search, no sidebar) so it stays consistent with
+ * the rest of the site, with copy pulled from the translatable `notFound` UI
+ * strings. Written at Astro's reserved `src/pages/404.astro` path so static
+ * builds emit `dist/404.html` and the dev server serves it for unmatched routes.
+ * Skipped by the generator when a user `pages/404.astro` already occupies the
+ * `/404` route, so projects can fully override it.
+ */
+export const notFoundPageTemplate = (): string => `---
+// Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import PageLayout from "blume/components/layout/PageLayout.astro";
+import data from "../generated/data.json";
+
+export const prerender = true;
+
+const nf = data.ui.notFound;
+---
+
+<PageLayout
+  site={{ title: data.config.title, description: data.config.description }}
+  logo={data.config.logo}
+  favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
+  banner={data.config.banner}
+  analytics={data.config.analytics}
+  navigation={data.navigation}
+  page={{ title: nf.title, route: "/404" }}
+  themeMode={data.config.theme.mode}
+  fontCssVars={data.fontCssVars}
+  searchEnabled={data.config.search.enabled}
+  ui={data.ui}
+  noindex={true}
+>
+  <div
+    class="mx-auto flex min-h-[60vh] max-w-2xl flex-col items-center justify-center gap-4 px-6 py-24 text-center"
+  >
+    <p class="text-6xl font-bold text-muted-foreground">404</p>
+    <h1 class="text-2xl font-semibold text-foreground">{nf.title}</h1>
+    <p class="text-muted-foreground">{nf.description}</p>
+    <a
+      class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
+      href="/">{nf.home}</a
+    >
+  </div>
+</PageLayout>
+`;
+
 /**
  * Generate `.blume/src/generated/components.ts`, which re-exports the user's
  * component overrides (or empty maps when no `components.ts` exists). Importing

package/src/components/content/Component.astro

@@ -46,7 +46,11 @@ const paneStyle = `height:${paneHeight}px`;
     // CodeGroup, switching one Component must not switch the others.
     <Tabs hash={false} sync={false}>
       <Tab
-        class="flex items-center justify-center overflow-auto"
+        // `not-prose`: the preview lives inside the page's `.prose` wrapper, so
+        // without this the typography styles bleed into the live component
+        // (headings, links, lists, spacing). The Code pane below keeps prose on
+        // purpose — that's what styles the highlighted source.
+        class="not-prose flex items-center justify-center overflow-auto"
         style={paneStyle}
         title="Preview"
       >

package/src/components/layout/RootLayout.astro

@@ -16,7 +16,12 @@ import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
 import Header from "./Header.astro";
-import { findBreadcrumbs, flattenPages, getPagination } from "./nav-utils.ts";
+import {
+  findBreadcrumbs,
+  flattenPages,
+  getPagination,
+  sidebarForRoute,
+} from "./nav-utils.ts";
 import NavTree from "./NavTree.astro";
 import { resolveSlot } from "./overrides.ts";
 import PageActions from "./PageActions.astro";
@@ -179,11 +184,12 @@ const formattedLastModified =
 // Needs a configured site to be useful, so the menu is hidden without one.
 const mcpUrl = mcp && siteUrl ? new URL(mcp.route, siteUrl).href : null;
 
-const crumbs = findBreadcrumbs(navigation.sidebar, page.route);
-const { prev, next } = getPagination(
-  flattenPages(navigation.sidebar),
-  page.route
-);
+// Scope the sidebar (and the breadcrumbs/pagination derived from it) to the
+// active tab's section, so a multi-section site drills each tab into its own
+// pages. Without tabs — or on a route under none — this is the full sidebar.
+const sidebar = sidebarForRoute(navigation.sidebar, navigation.tabs, page.route);
+const crumbs = findBreadcrumbs(sidebar, page.route);
+const { prev, next } = getPagination(flattenPages(sidebar), page.route);
 
 // Structured data is skipped when disabled or for pages we ask crawlers not to
 // index. Escape `<` so a title/description containing `</script>` can't break
@@ -294,7 +300,7 @@ const bannerScript = banner?.dismissible
         class="fixed top-16 start-0 z-[35] h-[calc(100dvh-4rem)] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:z-auto lg:w-auto lg:max-w-none lg:translate-x-0! lg:border-e-0 lg:bg-transparent lg:px-4"
       >
         <nav>
-          <SidebarSlot currentRoute={page.route} items={navigation.sidebar} />
+          <SidebarSlot currentRoute={page.route} items={sidebar} />
         </nav>
       </aside>
       <main class="min-w-0 px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">

package/src/components/layout/nav-utils.ts

@@ -1,4 +1,4 @@
-import type { NavNode } from "../../core/types.ts";
+import type { NavNode, NavTab } from "../../core/types.ts";
 
 /** A flat, ordered page reference used for previous/next pagination. */
 export interface FlatPage {
@@ -71,6 +71,69 @@ export const findBreadcrumbs = (nodes: NavNode[], route: string): Crumb[] => {
   return search(nodes, []) ?? [];
 };
 
+/** Whether `route` is the section root `base` or nested beneath it. */
+const isUnderPath = (route: string, base: string): boolean =>
+  route === base || route.startsWith(`${base}/`);
+
+/**
+ * The tab whose `path` is the longest prefix of `route`, mirroring the header's
+ * active-tab highlight. The root tab (`/`) is skipped — it spans everything and
+ * so never scopes the sidebar.
+ */
+const activeTab = (tabs: NavTab[], route: string): NavTab | null => {
+  let match: NavTab | null = null;
+  for (const tab of tabs) {
+    if (tab.path === "/" || !isUnderPath(route, tab.path)) {
+      continue;
+    }
+    if (!match || tab.path.length > match.path.length) {
+      match = tab;
+    }
+  }
+  return match;
+};
+
+/**
+ * The children of the group whose path is `base`, searched at any depth — so a
+ * content tree wrapped in a top-level container group still resolves to the
+ * right section. Returns null when no group sits exactly at `base`.
+ */
+const sectionChildren = (nodes: NavNode[], base: string): NavNode[] | null => {
+  for (const node of nodes) {
+    if (node.kind !== "group") {
+      continue;
+    }
+    if (node.path === base || node.route === base) {
+      return node.children;
+    }
+    const deeper = sectionChildren(node.children, base);
+    if (deeper) {
+      return deeper;
+    }
+  }
+  return null;
+};
+
+/**
+ * Scope the sidebar to the active tab's section. With tabs configured, a route
+ * under one tab shows only that tab's group — so a multi-section site (e.g.
+ * Adapters / API / AI tabs) drills each tab into its own pages instead of one
+ * global tree, the way Fumadocs' root folders do. Falls back to the full
+ * sidebar when no tab matches (or the tab maps to no group), so a route is
+ * never left with a blank sidebar.
+ */
+export const sidebarForRoute = (
+  sidebar: NavNode[],
+  tabs: NavTab[],
+  route: string
+): NavNode[] => {
+  const tab = activeTab(tabs, route);
+  if (!tab) {
+    return sidebar;
+  }
+  return sectionChildren(sidebar, tab.path) ?? sidebar;
+};
+
 /** Resolve previous/next pages around the current route. */
 export const getPagination = (
   flat: FlatPage[],

package/src/core/i18n-ui.ts

@@ -50,6 +50,15 @@ const uiStringsObject = z.object({
       untranslated: z.string().default("Not translated"),
     })
     .default({}),
+  notFound: z
+    .object({
+      description: z
+        .string()
+        .default("We couldn't find the page you're looking for."),
+      home: z.string().default("Back to home"),
+      title: z.string().default("Page not found"),
+    })
+    .default({}),
   page: z
     .object({
       lastUpdated: z.string().default("Last updated on"),

package/src/core/navigation.ts

@@ -55,6 +55,8 @@ interface MutableGroup {
   kind: "group";
   key: string;
   path: string;
+  /** The group's URL path (folder route prefix); set as pages are inserted. */
+  routePath?: string;
   label: string;
   icon?: string;
   collapsed?: boolean;
@@ -194,6 +196,7 @@ const toNavNode = (node: MutableNode): NavNode => {
     icon: node.icon,
     kind: "group",
     label: node.label,
+    path: node.routePath,
   };
 };
 
@@ -215,9 +218,18 @@ const buildFileSystemSidebar = (
     const filename = parts.at(-1) ?? page.navPath;
     const dirs = parts.slice(0, -1);
 
+    // Each group's URL path is the matching prefix of the page's route. navPath
+    // is locale-stripped while the route may carry a locale/base prefix, so
+    // align the folder segments from the right (the extra leading segments are
+    // that prefix). Under such a prefix the path won't match a logical tab path,
+    // so tab-scoping simply no-ops — same as the header's active-tab logic.
+    const folderParts = page.route.split("/").filter(Boolean).slice(0, -1);
+    const offset = Math.max(0, folderParts.length - dirs.length);
+
     let parent = root;
-    for (const dir of dirs) {
+    for (const [index, dir] of dirs.entries()) {
       parent = ensureGroup(parent, dir);
+      parent.routePath ??= `/${folderParts.slice(0, offset + index + 1).join("/")}`;
     }
 
     parent.children.push({

package/src/core/schema.ts

@@ -1022,11 +1022,17 @@ export const blumeConfigSchema = z
     deployment: deploymentConfigSchema.default({}),
     description: z.string().optional(),
     /**
-     * Directory (relative to the project root) that `<Component path>` resolves
-     * live previews and their source against. Defaults to `examples`; point it
-     * elsewhere when examples live outside a top-level `examples/` — e.g. a
-     * registry layout like `registry/<pkg>`, where a `<Component path>` key is
-     * then relative to that directory.
+     * Where `<Component path>` resolves live previews and their source from,
+     * relative to the project root. Defaults to the `examples` directory; point
+     * it elsewhere when examples live outside a top-level `examples/`.
+     *
+     * May be a glob (anything with `*`/`?`/`[]`/`{}`/`!`), in which case only
+     * matching files are discovered and a `<Component path>` key is relative to
+     * the glob's static prefix. Use this for a registry layout that colocates
+     * component sources with their examples — `registry/<pkg>/**\/examples/*`
+     * targets just the examples, leaving the sources (which have no default
+     * export to wrap) out, so the registry needn't be forked into its own
+     * examples directory.
      */
     examples: z.string().default("examples"),
     export: exportConfigSchema.default(false),

package/src/core/types.ts

@@ -137,6 +137,12 @@ export type NavNode =
       display?: SidebarDisplay;
       icon?: string;
       route?: string;
+      /**
+       * The group's URL path (its folder route prefix), even when the folder
+       * has no index page to link. Used to scope the sidebar to a tab's section;
+       * not a clickable link (that's `route`).
+       */
+      path?: string;
       collapsed?: boolean;
       children: NavNode[];
     };

package/src/registry/eject.ts

@@ -12,7 +12,7 @@ import {
   detectNeedsReact,
 } from "../astro/generate.ts";
 import { discoverIslands } from "../astro/islands.ts";
-import { customOgRoutes, discoverPages } from "../astro/pages.ts";
+import { customOgRoutes, discoverPages, routeIsTaken } from "../astro/pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -25,6 +25,7 @@ import {
   islandMapTemplate,
   islandWrapperTemplate,
   mixedbreadSearchEndpointTemplate,
+  notFoundPageTemplate,
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
@@ -73,7 +74,7 @@ export const eject = async (root: string): Promise<string[]> => {
         : Promise.resolve(""),
       buildRawMarkdown(project),
       discoverIslands(root),
-      discoverExamples(root),
+      discoverExamples(root, config.examples),
     ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
@@ -206,6 +207,16 @@ export const eject = async (root: string): Promise<string[]> => {
     });
   }
 
+  // Default 404 page, unless the project already owns `/404` (a custom
+  // `pages/404.astro` or a `404.md` content page). The ejected project owns the
+  // file afterwards and can edit or remove it.
+  if (!routeIsTaken(pages, project.graph.pages, "/404")) {
+    files.push({
+      content: notFoundPageTemplate(),
+      path: join(srcDir, "pages", "404.astro"),
+    });
+  }
+
   // The provider-specific client loader behind the `blume:search-client` alias.
   files.push({
     content: searchClientTemplate(config),