blume 0.7.0 → 1.0.0

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

@@ -187,18 +187,31 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * Excludes Vite's pre-bundled dep cache from @vitejs/plugin-react. Astro's
+ * react() replaces the plugin's default `/node_modules/` exclude with just
+ * `/\.astro$/`, so without this Babel re-parses every optimized dep chunk
+ * served from `.vite/deps` — a 500KB+ vendor bundle per chunk, re-done on each
+ * re-optimization. A blanket `/node_modules/` exclude would instead switch the
+ * React Compiler off for Blume's own components in published installs (they
+ * resolve under `node_modules/blume/src`, and exclude beats include in the
+ * plugin's filter), so only the pre-bundle cache is excluded.
+ */
+const REACT_EXCLUDE = String.raw`exclude: [/\/node_modules\/\.vite\//]`;
+
 /**
  * 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().
+ * React pin. `null`/`undefined` (compiler off or unresolvable) omits the babel
+ * block. Both variants carry the pre-bundle exclude above.
  */
 const reactIntegration = (compilerPath: string | null | undefined): string =>
   compilerPath
-    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] } })`
-    : "react()";
+    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })`
+    : `react({ ${REACT_EXCLUDE} })`;
 
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
@@ -329,15 +342,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 +387,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 +632,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 +665,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 +849,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 +869,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" },
   });
 }
@@ -984,12 +1036,24 @@ import data from ${JSON.stringify(options.dataImport)};
 export const prerender = true;
 
 const configuration = ${JSON.stringify(options.configuration, null, 2)};
+
+// The reference is an unlocalized route, so its chrome renders in the default
+// locale's language and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the changelog index'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";
 ---
 
 <ReferenceLayout
   analytics={data.config.analytics}
   banner={data.config.banner}
+  dir={dir}
   fontCssVars={data.fontCssVars}
+  locale={htmlLang}
   logo={data.config.logo}
   favicon={data.config.favicon}
   appleIcon={data.config.appleIcon}
@@ -999,6 +1063,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>
@@ -1162,6 +1227,13 @@ const ogRel = seo.image ?? ogPath;
 // an external URL, which passes through verbatim (mirrors PageLayout).
 const ogImage =
   ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
+// Blume's generated card has known dimensions the layout can declare; a user's
+// \`seo.image\` could be any size or format, so it gets none.
+const ogGenerated = !seo.image && Boolean(ogPath);
+
+// X attribution: the site's account, plus a creator the page can claim for
+// itself (a guest post crediting its own author) over the configured default.
+const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } : {}) };
 
 const basedRoute = withBase(route);
 const canonical =
@@ -1258,6 +1330,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={indexable}
   ogImage={ogImage}
+  ogGenerated={ogGenerated}
+  x={x}
   canonical={canonical}
   editUrl={editUrl}
   feedback={data.config.feedback}
@@ -1301,7 +1375,7 @@ export const changelogIndexTemplate = (options: {
     ? '\n  <AskAI slot="ask" strings={data.ui.ask} suggestions={data.config.ask?.suggestions ?? []} />'
     : "";
   const clientData = options.needsReact
-    ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: data.config.title + " changelog" } }}'
+    ? '\n  clientData={{ config: data.config, navigation: data.navigation, page: { route: "/changelog", title: pageTitle } }}'
     : "";
   // Staged sources (e.g. GitHub Releases) render through a parallel collection,
   // so fold them in alongside filesystem entries when one exists.
@@ -1314,6 +1388,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 +1469,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 +1503,29 @@ 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";
+
+// The page chrome (h1, title, description) comes from the same translatable
+// \`changelog\` group as the reveal button; optional chaining tolerates a
+// not-yet-regenerated data snapshot from before these keys existed.
+const changelogTitle = data.ui.changelog?.title ?? "Changelog";
+const changelogDescription =
+  data.ui.changelog?.description ??
+  "Product updates, new features, and fixes from every release.";
+const pageTitle = data.config.title + " " + changelogTitle;
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -1431,9 +1542,12 @@ 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.",
+    title: pageTitle,
+    description: changelogDescription,
     route: "/changelog",
   }}
   headings={headings}
@@ -1444,6 +1558,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={true}
   ogImage={null}
+  x={data.config.x}
   canonical={canonical}
   askEnabled={${options.askEnabled}}
   exportPdf={${options.exportPdf}}
@@ -1453,12 +1568,15 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   noindex={false}
   structuredDataEnabled={data.config.structuredData}
 >${askSlot}
-  <h1>Changelog</h1>
+  <h1>{changelogTitle}</h1>
   {
     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 +1635,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 +1665,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 +1678,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