blume 0.7.0 → 0.8.0

package/src/astro/generate.ts

@@ -54,7 +54,12 @@ import { planComponentSlots } from "./component-slots.ts";
 import type { ComponentSlotPlan } from "./component-slots.ts";
 import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { customOgRoutes, discoverPages, routeIsTaken } from "./pages.ts";
+import {
+  customOgRoutes,
+  discoverPages,
+  hasGeneratedChangelog,
+  routeIsTaken,
+} from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -377,6 +382,16 @@ const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
   vue: "@astrojs/vue",
 };
 
+/**
+ * Adapter package the project must install itself for each deployment
+ * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
+ * so they never need this.
+ */
+const DEPLOYMENT_ADAPTER_DEPS: Record<string, string> = {
+  cloudflare: "@astrojs/cloudflare",
+  netlify: "@astrojs/netlify",
+};
+
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
  * installed — Vite would otherwise fail opaquely on the generated config import.
@@ -398,6 +413,34 @@ const islandFrameworkWarnings = (
   return warnings;
 };
 
+/**
+ * Warn when the resolved server-output adapter is one the project must install
+ * itself (Netlify/Cloudflare; Node and Vercel ship with Blume). The generated
+ * astro.config.mjs imports the adapter package directly — and on those
+ * platforms the adapter is even auto-selected from env vars — so warn early
+ * rather than let the build die with an opaque ERR_MODULE_NOT_FOUND from the
+ * hidden generated config. Availability mirrors the search-provider check: a
+ * dep resolves from the project root or from the Blume package itself.
+ */
+const deploymentAdapterWarnings = (
+  deployment: ResolvedConfig["deployment"],
+  root: string
+): string[] => {
+  const dep =
+    deployment.output === "server" && deployment.adapter
+      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      : undefined;
+  if (
+    dep &&
+    !(canResolveFrom(root, dep) || canResolveFrom(packageRoot(), dep))
+  ) {
+    return [
+      `Deployment adapter "${deployment.adapter}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
+    ];
+  }
+  return [];
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (root: string, config: ResolvedConfig): string | null =>
   config.examples.css ? join(root, config.examples.css) : null;
@@ -461,16 +504,24 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
   return matches.length > 0;
 };
 
+/** Block math (`$$…$$`) or an explicitly authored `<Math …>` component. */
+const containsMath = (content: string): boolean =>
+  content.includes("$$") || content.includes("<Math");
+
 /**
- * Detect whether the project authors block math (`$$…$$`) in any `.mdx`. Drives
- * whether the generated runtime imports the `<Math>` component and KaTeX's
- * stylesheet, so a math-free site ships no KaTeX CSS. Math parsing itself is
- * always on but block-only, so a literal `$$` in source is a necessary
- * condition — no false negatives. A stray `$$` (e.g. inside a code fence) merely
- * over-includes the idempotent import, which is harmless.
+ * Detect whether the project can render math: block math (`$$…$$`) or an
+ * explicit `<Math>` tag in any local `.md`/`.mdx`, or in staged (non-filesystem)
+ * source bodies. Drives whether the generated runtime imports the `<Math>`
+ * component and KaTeX's stylesheet, so a math-free site ships no KaTeX CSS.
+ * Math parsing itself is always on but block-only, so one of those literals is
+ * a necessary condition — no false negatives. A stray `$$` (e.g. inside a code
+ * fence) merely over-includes the idempotent import, which is harmless.
  */
-export const detectUsesMath = async (root: string): Promise<boolean> => {
-  const files = await glob(["**/*.mdx"], {
+export const detectUsesMath = async (
+  root: string,
+  staged: Iterable<string> = []
+): Promise<boolean> => {
+  const files = await glob(["**/*.{md,mdx}"], {
     cwd: root,
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
@@ -478,7 +529,7 @@ export const detectUsesMath = async (root: string): Promise<boolean> => {
   const contents = await Promise.all(
     files.map((file) => readOptional(join(root, file)))
   );
-  return contents.some((content) => content.includes("$$"));
+  return [...contents, ...staged].some(containsMath);
 };
 
 const writeIfChanged = async (
@@ -792,6 +843,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
         ? { suggestions: config.ai.ask.suggestions }
         : null,
       banner: resolveBanner(config),
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -934,6 +986,7 @@ const writeMcpFiles = async (
   }
   const data = await buildMcpData(project);
   const discoveryInput = {
+    base: data.base,
     name: data.name,
     route: plan.route,
     site: data.site,
@@ -1012,32 +1065,6 @@ export interface GenerateResult {
   warnings: string[];
 }
 
-/**
- * Whether to generate the default `/changelog` index. Written when there are
- * `type: changelog` entries — or when a release-backed changelog source is
- * configured, so its route (and any nav tab pointing at it) still resolves to an
- * empty timeline on a build where the source could not be fetched (e.g. CI
- * without a token). Skipped when a user content page or a custom `.astro` page
- * already owns `/changelog`.
- */
-const shouldGenerateChangelog = (
-  project: BlumeProject,
-  userPages: { pattern: string }[]
-): boolean => {
-  const hasChangelog = project.graph.pages.some(
-    (page) =>
-      page.contentType === "changelog" &&
-      !(page.meta.draft || page.meta.sidebar.hidden)
-  );
-  const hasChangelogSource = (project.config.content.sources ?? []).some(
-    (source) => source.type === "github-releases"
-  );
-  return (
-    (hasChangelog || hasChangelogSource) &&
-    !routeIsTaken(userPages, project.graph.pages, "/changelog")
-  );
-};
-
 /**
  * Statically analyze the user's `components.ts` (never executing it) and plan the
  * generated `components.ts` module plus any hydration wrappers. Returns the plan
@@ -1097,6 +1124,10 @@ export const generateRuntime = async (
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
+  // entryId so i18n duplicates of one entry write a single file. Collected here
+  // so math detection also sees staged bodies (they never live under root).
+  const staged = collectStaged(project);
   // Statically analyze `components.ts` overrides (never executed): drives the
   // `islands` group, hydration on layout/mdx overrides, string-path resolution,
   // and the "framework component with no client mode" diagnostic. Independent of
@@ -1113,7 +1144,7 @@ export const generateRuntime = async (
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(context.root),
-    detectUsesMath(context.root),
+    detectUsesMath(context.root, staged.values()),
     readOptional(context.themeFile),
     readOptional(examplesCssFile(context.root, config)),
     discoverIslands(context.root),
@@ -1156,9 +1187,6 @@ export const generateRuntime = async (
   const mcp = planMcp(project, srcDir, pages);
   pages.push(...mcp.discoveryPages);
 
-  // Staged (non-filesystem) sources materialize into `.blume/content`; keyed by
-  // 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. An all-staged project (openapi/notion/…) has only staged
@@ -1303,7 +1331,7 @@ export const generateRuntime = async (
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1363,11 +1391,11 @@ export const generateRuntime = async (
     ),
     write(
       join(srcDir, "pages", "[...slug].md.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("md")
     ),
     write(
       join(srcDir, "pages", "[...slug].mdx.ts"),
-      rawMarkdownEndpointTemplate()
+      rawMarkdownEndpointTemplate("mdx")
     ),
   ]);
 
@@ -1410,7 +1438,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceTabs(config).map((tab) => tab.path),
   ]);
-  if (shouldGenerateChangelog(project, pages)) {
+  if (hasGeneratedChangelog(project, pages)) {
     navTargetRoutes.add("/changelog");
   }
   warnings.push(
@@ -1461,7 +1489,10 @@ export const generateRuntime = async (
 
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
+  warnings.push(
+    ...deploymentAdapterWarnings(config.deployment, context.root),
+    ...islandFrameworkWarnings(frameworks, context.root)
+  );
   if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/astro/integration.ts

@@ -108,7 +108,7 @@ const negotiateMarkdown =
  * Blume's Astro integration. Mounts user-authored pages from `pages/` into the
  * generated runtime via `injectRoute`, keeping each file in its original
  * location so relative imports and `getStaticPaths` keep working, and teaches
- * the dev server to honour `Accept: text/markdown`.
+ * the dev server to honor `Accept: text/markdown`.
  */
 export const blumeIntegration = (
   options: BlumeIntegrationOptions

package/src/astro/markdown-negotiation.ts

@@ -1,7 +1,7 @@
 /**
  * HTTP content negotiation for the raw-Markdown variants. The `<route>.md`
  * endpoints already serve a page's source verbatim; these helpers let the dev
- * server honour `Accept: text/markdown` by transparently rewriting a page
+ * server honor `Accept: text/markdown` by transparently rewriting a page
  * request to its `.md` variant.
  */
 

package/src/astro/pages.ts

@@ -1,23 +1,14 @@
 import { extname, relative } from "pathe";
-import { glob } from "tinyglobby";
+import { glob, globSync } from "tinyglobby";
 
+import type { BlumeProject } from "../core/project-graph.ts";
 import type { BlumePageRoute } from "./integration.ts";
 
-/**
- * Discover user `.astro` pages and map them to route patterns. Files keep their
- * original location; only the route pattern is derived (index -> parent,
- * dynamic `[param]` segments preserved).
- */
-export const discoverPages = async (
-  pagesRoot: string
-): Promise<BlumePageRoute[]> => {
-  const files = await glob(["**/*.astro"], {
-    absolute: true,
-    cwd: pagesRoot,
-    onlyFiles: true,
-  });
-  files.sort();
+const PAGE_GLOB = ["**/*.astro"];
 
+/** 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 rel = relative(pagesRoot, file);
     const withoutExt = rel.slice(0, rel.length - extname(rel).length);
@@ -32,6 +23,26 @@ export const discoverPages = async (
   });
 };
 
+/**
+ * Discover user `.astro` pages and map them to route patterns. Files keep their
+ * original location; only the route pattern is derived (index -> parent,
+ * dynamic `[param]` segments preserved).
+ */
+export const discoverPages = async (
+  pagesRoot: string
+): Promise<BlumePageRoute[]> =>
+  toPageRoutes(
+    pagesRoot,
+    await glob(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true })
+  );
+
+/** {@link discoverPages} for synchronous callers (e.g. the sitemap builder). */
+export const discoverPagesSync = (pagesRoot: string): BlumePageRoute[] =>
+  toPageRoutes(
+    pagesRoot,
+    globSync(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true })
+  );
+
 /**
  * Whether the project already owns `route` — through a custom `.astro` page
  * (injected, so matched on `pattern`) or a content page (matched on `route`).
@@ -57,6 +68,59 @@ export interface OgCustomRoute {
 /** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
 const PRIVATE_SEGMENT = /^[._]/u;
 
+/** Segments of a static, shareable page pattern; null for dynamic/private ones. */
+const staticSegments = (pattern: string): string[] | null => {
+  const segments = pattern.split("/").filter(Boolean);
+  return segments.some(
+    (part) => PRIVATE_SEGMENT.test(part) || part.includes("[")
+  )
+    ? null
+    : segments;
+};
+
+/**
+ * The static routes served by custom `.astro` pages — the same filtering as
+ * {@link customOgRoutes}, but yielding the routes themselves. Feeds the route
+ * sets that must know every servable page beyond the content graph (the link
+ * checker, the sitemap); dynamic (`[param]`) and private segments are skipped
+ * because their concrete URLs can't be enumerated statically.
+ */
+export const customStaticRoutes = (pages: { pattern: string }[]): string[] => {
+  const routes = new Set<string>();
+  for (const { pattern } of pages) {
+    const segments = staticSegments(pattern);
+    if (segments !== null) {
+      routes.add(segments.length === 0 ? "/" : `/${segments.join("/")}`);
+    }
+  }
+  return [...routes];
+};
+
+/**
+ * Whether the generated `/changelog` index route exists for this project —
+ * `generate.ts` (which writes the page) and the sitemap/link validator all
+ * share this check: there are visible `type: changelog` entries — or a
+ * release-backed changelog source, whose route must resolve even when a fetch
+ * fails — and no user content or custom page already owns `/changelog`.
+ */
+export const hasGeneratedChangelog = (
+  project: BlumeProject,
+  userPages: { pattern: string }[]
+): boolean => {
+  const hasChangelog = project.graph.pages.some(
+    (page) =>
+      page.contentType === "changelog" &&
+      !(page.meta.draft || page.meta.sidebar.hidden)
+  );
+  const hasChangelogSource = (project.config.content.sources ?? []).some(
+    (source) => source.type === "github-releases"
+  );
+  return (
+    (hasChangelog || hasChangelogSource) &&
+    !routeIsTaken(userPages, project.graph.pages, "/changelog")
+  );
+};
+
 const humanizeSegment = (segment: string): string =>
   segment
     .split(/[-_]/u)
@@ -83,10 +147,8 @@ export const customOgRoutes = (
   // 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("["))
-    ) {
+    const segments = staticSegments(pattern);
+    if (segments === null) {
       return;
     }
     const slug = segments.length === 0 ? "index" : segments.join("/");

package/src/astro/templates.ts

@@ -329,15 +329,18 @@ export const astroConfigTemplate = (options: {
     "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;
+  // subdirectory (Astro doesn't rewrite `<a href>`) layered over the site-wide
+  // `basePath` baked into routes. The layers are passed separately so a
+  // hand-written `basePath` link (`/docs/x`) isn't double-prefixed (see
+  // `withComposedBasePath`). The link checker validates the base-less authored
+  // path against `basePath` routes separately.
+  const deployBase = normalizeBasePath(deployment.base);
 
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
-      basePath: contentLinkBase,
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}) })`,
   ];
@@ -371,8 +374,9 @@ export default defineConfig({
   integrations: [${integrations.join(", ")}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
-      basePath: contentLinkBase,
+      basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}),
     shikiConfig: {
@@ -615,6 +619,31 @@ export const askEndpointTemplate = (
     content: m.content,
     role: m.role,
   }));`;
+  // `streamText` returns synchronously and defers provider/auth/network errors
+  // to stream consumption, so the handler's try/catch never sees them: without
+  // these the client gets a 200 whose stream aborts mid-flight and nothing is
+  // logged server-side. A missing credential is rejected up front as a real
+  // 500; everything else is at least logged via `onError`.
+  const keyCheck =
+    backend.kind === "gateway"
+      ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
+  if (!(process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN)) {
+    return new Response(
+      "Ask AI is not configured: set AI_GATEWAY_API_KEY (or deploy on Vercel with OIDC).",
+      { status: 500 }
+    );
+  }`
+      : `  if (!process.env[${JSON.stringify(backend.apiKeyEnv)}]) {
+    return new Response(
+      ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
+      { status: 500 }
+    );
+  }`;
+  // Provider errors surface mid-stream, after the 200 is committed; this is
+  // the only place they can be observed server-side.
+  const onError = `      onError({ error }) {
+        console.error("Ask AI provider error:", error);
+      },`;
   const stream = grounded
     ? `    const system =
       (await ground(messages, body.page)) ??
@@ -623,15 +652,18 @@ export const askEndpointTemplate = (
       model: ${modelExpr},
       system,
       messages,
+${onError}
     });`
     : `    const result = streamText({
       model: ${modelExpr},
       system:
         "You are a helpful documentation assistant. Answer using the project's documentation.",
       messages,
+${onError}
     });`;
   const handler = `export const POST: APIRoute = async ({ request }) => {
 ${validate}
+${keyCheck}
   try {
 ${stream}
     return result.toTextStreamResponse();
@@ -804,9 +836,13 @@ export const POST: APIRoute = async ({ request }) => {
 
 /**
  * Generate the raw-Markdown endpoints (`[...slug].md.ts` and `[...slug].mdx.ts`).
- * Each route's source is served verbatim so `/<route>.md` returns plain Markdown.
+ * Both read `raw-markdown.json`, whose entries hold the verbatim source (`mdx`)
+ * plus a component-downleveled variant (`md`) when the page uses components:
+ * `/<route>.mdx` serves the source exactly as written, `/<route>.md` serves
+ * plain Markdown with `<TypeTable>`-style components converted for consumers
+ * that can't interpret JSX.
  */
-export const rawMarkdownEndpointTemplate = (): string =>
+export const rawMarkdownEndpointTemplate = (kind: "md" | "mdx"): string =>
   `// Generated by Blume. Do not edit.
 import raw from "../generated/raw-markdown.json";
 
@@ -820,7 +856,10 @@ export function getStaticPaths() {
 }
 
 export function GET({ props }) {
-  return new Response(raw[props.route] ?? "", {
+  const entry = raw[props.route];
+  return new Response(entry ? ${
+    kind === "md" ? "(entry.md ?? entry.mdx)" : "entry.mdx"
+  } : "", {
     headers: { "Content-Type": "text/markdown; charset=utf-8" },
   });
 }
@@ -999,6 +1038,7 @@ const configuration = ${JSON.stringify(options.configuration, null, 2)};
   searchEnabled={data.config.search.enabled}
   site={{ title: data.config.title, description: data.config.description }}
   themeMode={data.config.theme.mode}
+  ui={data.ui}
 >
   <ScalarComponent configuration={configuration} renderMode="client" />
 </ReferenceLayout>
@@ -1314,6 +1354,7 @@ export const changelogIndexTemplate = (options: {
 import { getCollection, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
 ${askImport}import data from "../generated/data.json";
@@ -1394,6 +1435,20 @@ const items = await Promise.all(
   })
 );
 
+// Repeated labels slug to the same id (e.g. two entries with neither a title
+// nor a version both falling back to "update"); suffix the later ones -2, -3,
+// ... so every heading deep-links to its own entry. The first keeps the plain
+// slug, and the rendered ids stay in lockstep with the \`headings\` list below.
+const seenIds = new Set();
+for (const item of items) {
+  let uniqueId = item.id;
+  for (let n = 2; seenIds.has(uniqueId); n += 1) {
+    uniqueId = item.id + "-" + n;
+  }
+  seenIds.add(uniqueId);
+  item.id = uniqueId;
+}
+
 // A changelog is semver-paginated only when every visible release parses as
 // semver and they span more than one major line. Older majors then collapse
 // into groups the reader reveals one at a time; otherwise the timeline is flat.
@@ -1414,7 +1469,20 @@ const headings = items.map((item) => ({
 }));
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
-const canonical = base ? base + "/changelog" : null;
+// The canonical URL carries the deployment base (the page is served under it),
+// matching how the catch-all canonicalizes via \`withBase(route)\`.
+const basedRoute = withBase("/changelog");
+const canonical = base ? base + basedRoute : null;
+
+// The changelog is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -1431,6 +1499,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   imageZoom={data.config.imageZoom}
   codeWrap={data.config.codeWrap}
   navigation={data.navigation}
+  locale={htmlLang}
+  dir={dir}
+  ui={data.ui}
   page={{
     title: data.config.title + " changelog",
     description: "Product updates and release notes.",
@@ -1458,7 +1529,10 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
     ) : paginate ? (
-      <blume-changelog class="not-prose mt-8 block">
+      <blume-changelog
+        class="not-prose mt-8 block"
+        data-i18n-more={data.ui.changelog?.showReleases}
+      >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
             <Content />
@@ -1517,11 +1591,22 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 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 { withBase } from "blume/components/islands/base-path.ts";
 import data from "../generated/data.json";
 
 export const prerender = true;
 
 const nf = data.ui.notFound;
+
+// The 404 page is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 ---
 
 <PageLayout
@@ -1536,6 +1621,8 @@ const nf = data.ui.notFound;
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
+  locale={htmlLang}
+  dir={dir}
   ui={data.ui}
   noindex={true}
 >
@@ -1547,7 +1634,7 @@ const nf = data.ui.notFound;
     <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
+      href={withBase("/")}>{nf.home}</a
     >
   </div>
 </PageLayout>

package/src/blume-modules.d.ts

@@ -15,6 +15,14 @@ declare module "blume:search-client" {
   export const createSearch: () => Fn | Promise<Fn>;
 }
 
+declare module "blume:data" {
+  /** The generated per-project data snapshot (see `core/data.ts`). */
+  // biome-ignore lint/style/useImportType: ambient module must stay a global script
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const data: import("./core/data.ts").BlumeData;
+  export default data;
+}
+
 // Package-only shim so `components/props.ts` can extract `.astro` prop types with
 // `ComponentProps<typeof import("./X.astro").default>` under the package's own
 // `tsc` (where the Astro TS plugin isn't active). Not shipped in `dist/types`, so