blume 2.1.0 → 2.1.1

package/skills/blume-migrate/references/starlight.md

@@ -21,17 +21,17 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 | `logo` (`{ src }` or `{ light, dark, alt }`) | `logo` — move the referenced file into `public/` |
 | `logo.replacesTitle` | `logo: { text: "" }` (renders the mark alone) |
 | `favicon` | copy the file into `public/` (drop the config field — Blume auto-detects) |
-| `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; other socials drop (report) |
+| `social` (array of `{ label, icon, href }`; pre-0.33 legacy: `{ github: url }` object) | derive **`github: { owner, repo }`** from the GitHub entry; every other entry whose platform Blume knows → **`footer.socials`** (`{ discord: href, bluesky: href, … }`; the `x.com`/`twitter` icon → `x`; the platform list is under `footer` in `docs/configuration/index.mdx`); the rest (`mastodon`, `gitlab`, `rss`, …) drop (report) |
 | `editLink.baseUrl` (`…/edit/<branch>/<subdir?>`) | `github: { owner, repo, branch }` — **and any repo sub-path after the branch → `github.dir`** (a docs-in-subfolder repo breaks every edit link without it); **an origin other than `https://github.com` → `github.host`** (a GitHub Enterprise repo otherwise links to the public site) |
 | `sidebar` (array) | filesystem nav / `navigation.sidebar` (see below) |
 | `tableOfContents` (`false` or `{ minHeadingLevel, maxHeadingLevel }`) | `toc` — identical shape, 1:1 |
 | `markdown.headingLinks: false` | `markdown.headingAnchors: false` |
 | `expressiveCode.themes` | `markdown.code.theme: { light, dark }` — EC assigns by theme _type_, so match each theme by its darkness, not by array position |
 | `expressiveCode.styleOverrides` | drop → restyle via a root `theme.css` file |
-| `head` | **drop and report** (there is no `seo.metatags`); analytics `<script>` entries → one `script()` adapter each in the `analytics` list (from `blume/analytics`): `attrs.src` → `src`, an `async`/`defer` attr → `strategy`, every other `attrs` key → `attributes`, and an inline body (`content`) → `content` |
+| `head` | per entry: a `meta` tag → **`seo.metatags`** (`{ [attrs.name ?? attrs.property]: attrs.content }` — verification tokens, `theme-color`, and the like), minus the tags Blume writes itself (`description`, `robots`, `og:title`/`og:description`/`og:image`/`og:url`/`og:type`/`og:site_name`, `twitter:*` card tags, `article:*` dates — the build refuses them and names the setting that owns each, e.g. `og:image` → `seo.og`, `twitter:site` → `seo.x.handle`); an analytics `<script>` → one `script()` adapter each in the `analytics` list (from `blume/analytics`): `attrs.src` → `src`, an `async`/`defer` attr → `strategy`, every other `attrs` key → `attributes`, and an inline body (`content`) → `content`; anything else (`link`, `style`, other scripts) → drop and report |
 | `lastUpdated: true` | `lastModified: "git"` |
 | `customCss` | drop → move into a root **`theme.css`** file (auto-picked-up; not a config field) |
-| `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { Header, Search, Sidebar, TableOfContents, Footer, … } })` — a near-1:1 map; reach for `blume eject` only beyond those |
+| `components` (overrides) | Blume's layout slots via `defineComponents({ layout: { … } })` in a root `components.ts`: `Header`, `Search`, `Sidebar`, `TableOfContents`, `Pagination` keep their names; `SiteTitle` → `Logo`; **`Footer` → `PageFooter`**, not Blume's `Footer` (that slot is the site footer; Starlight's `Footer` is the page-end last-updated date, pagination, and edit link, which Blume renders itself, so keep only what the override added). Other overrides (`Banner`, `PageTitle`, `Hero`, `EditLink`, `SocialIcons`, …) have no slot — fold their additions into `PageHeader`/`PageFooter`, or `blume eject`; a Starlight name left under `layout` matches no slot and does nothing. Rewrite reads of `Astro.locals.starlightRoute` against the slot's props |
 | `plugins` | **map, don't blanket-drop** — see Plugins below |
 | `pagination: false`, `pagefind`/Pagefind options, `titleDelimiter`, `credits`, `disable404Route`, `routeMiddleware` | drop (report) |
 | `locales` / `defaultLocale` | `i18n` (see below) |
@@ -40,7 +40,7 @@ Keep content where it is — set `content.root: "src/content/docs"`.
 
 Starlight's `sidebar` array → prefer letting Blume generate from the filesystem; use `navigation.sidebar` only for shapes files can't express:
 
-- `{ label, autogenerate: { directory: "d" } }` → **structure the folder and rely on filesystem nav** (label → the folder's `meta.ts` `title`). Do **not** map it to a sidebar item with `root:` — in an explicit Blume sidebar that renders a single page link, not the directory's children.
+- `{ label, items: [{ autogenerate: { directory: "d" } }] }` (0.39 and later; before 0.39 the group held it directly, `{ label, autogenerate: { directory: "d" } }`) → **structure the folder and rely on filesystem nav** (label → the folder's `meta.ts` `title`; `autogenerate.collapsed` → `collapsed: true` in each subfolder's `meta.ts`). Do **not** map it to a sidebar item with `root:` — in an explicit Blume sidebar that renders a single page link, not the directory's children. Since 0.39 a group's `items` can mix manual entries with an `autogenerate` entry; move those manual pages into the folder (route change → `redirects`) so the folder holds the whole group.
 - string `"guides/intro"` → `"/guides/intro"`; `{ label?, slug }` → `/<slug>`.
 - `{ label, items: [...] }` → `{ label, items: [...] }` (recursive) — or better, a real folder.
 - `{ label?, link }` → `{ label, href: link }`.
@@ -59,7 +59,8 @@ Starlight's `sidebar` array → prefer letting Blume generate from the filesyste
 | `lastUpdated: false` (boolean) | **remove** (Blume's `lastModified` takes a date; a boolean is a build error) |
 | `prev: false` **and** `next: false` | `pagination: false` (hides both links) |
 | `prev` / `next` otherwise (one side, or a label/link) | **drop** (report — the links can only be hidden together, and their labels come from the linked pages) |
-| `template: splash` / `hero` | **no equivalent** — rebuild as a custom `.astro` page under `content.pages`; a `hero` on a normal page drops (report) |
+| `template: splash` | `mode: center` (no sidebar, a wider centered column — the closest layout; report) |
+| `hero` | **no key** — its tagline → a paragraph, its actions → `<Card>`s or links, its image → a Markdown image (report); for a designed landing page, rebuild it as a custom `.astro` page under `content.pages` (`pages/index.astro` on `PageLayout` wins over the content page) |
 | `banner`, `tableOfContents`, `editUrl`, `head` | drop (report) |
 
 ## Asides → directives (and the `.md` trap)
@@ -83,7 +84,8 @@ Starlight content is full of Expressive Code fence meta; Blume understands some
 - `title="file.js"` → works as-is (or use the space-title shorthand). Line ranges `{2-3}` → work as-is.
 - `ins=`/`del=` line marks → `// [!code ++]` / `// [!code --]` comments; `mark=` → `{ranges}` or `// [!code highlight]`.
 - `showLineNumbers` → `lineNumbers`.
-- **Drop:** `frame="terminal"`, `collapse=`, `wrap`, `"string"` and `/regex/` text markers (report if they carried meaning).
+- `wrap` / `wrap=true` → a bare `wrap` (that block's long lines wrap); a site-wide `expressiveCode.defaultProps.wrap: true` → `markdown.code.wrap: true`.
+- **Drop:** `frame="terminal"`, `collapse=`, `wrap=false`, `preserveIndent`/`hangingIndent`, `"string"` and `/regex/` text markers (report if they carried meaning).
 - ` ```diff lang="js" ` → a normal ` ```js ` fence with `[!code ++]`/`[!code --]` markers.
 
 ## Plugins — map, don't drop
@@ -114,4 +116,4 @@ Remove `@astrojs/starlight` (and plugin deps) from deps, delete the Starlight bi
 
 ## Dropped — report these
 
-Non-GitHub socials, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries, `routeMiddleware`, splash/hero pages (rebuild as custom pages), starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.
+Socials on a platform `footer.socials` lacks, badge variants, sidebar/item `attrs` + `translations`, `customCss` beyond `theme.css`, `head` entries other than meta tags and analytics scripts, a page's frontmatter `head`, `routeMiddleware`, splash layouts approximated with `mode: center` and hero blocks rebuilt as content, override components with no Blume slot, starlight-blog's tag and author pages, aside custom icons, EC frames/collapse/text markers, prev/next toggles, unmapped plugins, any `<Icon>` name with no Lucide equivalent.

package/src/ai/ask-context.ts

@@ -622,10 +622,37 @@ export interface ReaderScope {
   filters: { locale: string | undefined; version: string | undefined };
 }
 
+// The snapshot's locale codes, keyed lowercase, built once per snapshot.
+const localeCodes = new WeakMap<AskData, Map<string, string>>();
+
+/**
+ * The locale a path's first segment names (`/ja` or `/ja/pricing` → `ja`),
+ * when it's one the snapshot's documents carry: a page outside the docs,
+ * like a localized landing page, still says which language it's in.
+ */
+const pathLocale = (data: AskData, path: string): string | undefined => {
+  let codes = localeCodes.get(data);
+  if (!codes) {
+    codes = new Map<string, string>();
+    for (const { locale } of data.documents) {
+      if (locale) {
+        codes.set(locale.toLowerCase(), locale);
+      }
+    }
+    localeCodes.set(data, codes);
+  }
+  const [, first = ""] = normalizeRoute(path).split("/");
+  return first ? codes.get(first.toLowerCase()) : undefined;
+};
+
 /**
  * Where the reader is: their page, when it's in the snapshot, and the locale
- * and docs version retrieval keeps to. Without a page, a versioned site
- * grounds in the current docs rather than every archived copy of each page.
+ * and docs version retrieval keeps to. A page the snapshot doesn't have (the
+ * homepage, a custom page, or none at all from a cross-origin caller) keeps
+ * to the locale its path's first segment names, or the default locale, so
+ * translations of every page don't crowd each other out. Without a page, a
+ * versioned site grounds in the current docs rather than every archived copy
+ * of each page.
  */
 export const readerScope = (
   data: AskData,
@@ -635,10 +662,13 @@ export const readerScope = (
   const current = page?.path
     ? byRoute.get(normalizeRoute(page.path))
     : undefined;
+  const locale = current
+    ? current.locale
+    : (page?.path && pathLocale(data, page.path)) || data.defaultLocale;
   return {
     current,
     filters: {
-      locale: current?.locale || undefined,
+      locale: locale || undefined,
       version: data.versioned ? (current?.version ?? "") : undefined,
     },
   };

package/src/ai/ask-limits.ts

@@ -0,0 +1,13 @@
+/**
+ * What one request to the assistant's generated route (`/api/ask`) may carry.
+ * The route answers a longer conversation with a `400` (see
+ * `askEndpointTemplate`), so the panel's client (`useAssistant`) sends only
+ * the latest turns that fit. The endpoint is unauthenticated, so the limits
+ * bound what one request can spend against the model.
+ */
+
+/** The most messages, questions and answers together, one request sends. */
+export const ASK_MAX_MESSAGES = 40;
+
+/** The most characters the messages take as JSON (`JSON.stringify`). */
+export const ASK_MAX_MESSAGES_CHARS = 24_000;

package/src/ai/changelog-markdown.ts

@@ -1,4 +1,5 @@
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
+import { withChangelogIndexText } from "../core/changelog-index.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { absoluteUrl } from "../core/site-url.ts";
@@ -45,12 +46,16 @@ const rowLine = (project: BlumeProject, { date, page }: IndexRow): string => {
 
 export const buildChangelogIndexMarkdown = (project: BlumeProject): string => {
   const { i18n } = project.config;
-  const ui = i18n
-    ? resolveUIStrings(i18n.defaultLocale, {
-        defaultLocale: i18n.defaultLocale,
-        overrides: i18n.ui,
-      })
-    : EN_UI;
+  const ui = withChangelogIndexText(
+    project.config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
   const rows: IndexRow[] = project.graph.pages
     .filter(
       (page) =>

package/src/ai/component-markdown.ts

@@ -584,7 +584,7 @@ export const inlineCode = (text: string): string => {
 };
 
 /** Fence `code` so its opening/closing run outlengths any backticks inside. */
-const fencedBlock = (lang: string, code: string): string => {
+export const fencedBlock = (lang: string, code: string): string => {
   const trimmed = code.replace(/(?<!\n)\n+$/u, "");
   const runs = trimmed.match(/`+/gu);
   const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;

package/src/ai/cors.ts

@@ -66,6 +66,13 @@ interface RequestContext {
   request: Request;
 }
 
+/**
+ * The response headers a cross-origin caller may read beyond the safelisted
+ * ones: the rate limit's `Retry-After`, so a caller can tell a reader how
+ * long to wait after a `429`.
+ */
+const EXPOSED_HEADERS = "retry-after";
+
 /** Stamp the CORS headers on every response `handler` returns. */
 export const withCors =
   (
@@ -74,9 +81,8 @@ export const withCors =
   ): ((context: RequestContext) => Promise<Response>) =>
   async (context) => {
     const response = await handler(context);
-    for (const [key, value] of Object.entries(
-      corsHeaders(context.request, allowed)
-    )) {
+    const headers = corsHeaders(context.request, allowed);
+    for (const [key, value] of Object.entries(headers)) {
       // `Vary` accumulates (the handler may already vary on something), the
       // rest replace.
       if (key === "vary") {
@@ -85,5 +91,8 @@ export const withCors =
         response.headers.set(key, value);
       }
     }
+    if (headers["access-control-allow-origin"]) {
+      response.headers.set("access-control-expose-headers", EXPOSED_HEADERS);
+    }
     return response;
   };

package/src/ai/mcp/query.ts

@@ -53,20 +53,28 @@ const contentTypesField = z.preprocess((value) => {
 }, z.array(z.string()).optional().describe('Only include pages of these content types (frontmatter `type`, e.g. `["doc", "rfc"]`). `list_pages` shows each page\'s type. Omit to include every type.'));
 
 /**
- * The optional facet filter `search_docs` and `list_pages` share. Only
- * string-valued entries survive; an empty `{}` means "no filter".
+ * The optional facet filter `search_docs` and `list_pages` share. A value
+ * is read the way `pageFacets` stores one: a string as-is, a number or
+ * boolean stringified (`{"priority": 1}` matches the facet `"1"`). Entries of
+ * any other shape are dropped; an empty `{}` means "no filter".
  */
-/** Accepts any plain object, so the string-valued entries can be sifted out. */
+/** Accepts any plain object, so the usable entries can be sifted out. */
 const looseFacetObject = z.record(z.string(), z.unknown());
 
+/** A filter value a facet can hold, stringified like `pageFacets` does. */
+const facetFilterValue = z
+  .union([z.string(), z.number(), z.boolean()])
+  .transform(String);
+
 const filtersField = z.preprocess((value) => {
   const candidate = looseFacetObject.safeParse(value);
   if (!candidate.success) {
     return;
   }
-  const entries = Object.entries(candidate.data).filter(
-    (entry): entry is [string, string] => typeof entry[1] === "string"
-  );
+  const entries = Object.entries(candidate.data).flatMap(([key, entry]) => {
+    const parsed = facetFilterValue.safeParse(entry);
+    return parsed.success ? [[key, parsed.data] as const] : [];
+  });
   return entries.length > 0 ? Object.fromEntries(entries) : undefined;
 }, z.record(z.string(), z.string()).optional().describe('Only include pages matching every facet, key → required value (e.g. `{"status": "enforced"}`). Facets are metadata the site declares per content type; `list_pages` shows each page\'s facet values. Omit for no facet filtering.'));
 

package/src/ai/openapi-components.ts

@@ -1,13 +1,24 @@
+import { customCodeSamples } from "../components/openapi/code-samples.ts";
 import { mountBasePath, normalizeBasePath } from "../core/base-path.ts";
 import type { ApiOperationRef, OpenApiData } from "../openapi/model.ts";
-import { operationOf, specAddresses, specOf } from "../openapi/model.ts";
+import {
+  operationObject,
+  operationOf,
+  specAddresses,
+  specOf,
+} from "../openapi/model.ts";
 import { asSentence } from "../openapi/sentence.ts";
 import { operationSignature } from "../openapi/signature.ts";
 import type {
   ComponentMarkdown,
   EvaluatedValue,
 } from "./component-markdown.ts";
-import { inlineCode, isString, linkDestination } from "./component-markdown.ts";
+import {
+  fencedBlock,
+  inlineCode,
+  isString,
+  linkDestination,
+} from "./component-markdown.ts";
 
 /**
  * Spec-authored prose as one line of inline Markdown. Unlike the props the
@@ -62,7 +73,10 @@ const listItem = (
  * section shows. Parameters, schemas and responses are deliberately left out:
  * those are `operation-model.ts` plus each component's own preparation, and a
  * second implementation here would be free to disagree with the page. The
- * endpoint and what it does is the part that was missing altogether.
+ * endpoint and what it does is the part that was missing altogether. The
+ * spec's own `x-codeSamples` do come along, as fenced code: they're text the
+ * spec wrote out (often an SDK call no agent could derive from the
+ * endpoint), read through the same `customCodeSamples` the page renders.
  *
  * `specs` is the parsed `blume:openapi` data — empty when the project has no
  * API reference, in which case every serializer declines. `deployBase` is the
@@ -142,7 +156,17 @@ export const openapiComponentSerializers = (
           : "",
         operation.deprecated ? "**Deprecated.**" : "",
       ].filter(Boolean);
-      return [signature, ...notes].join("\n\n");
+      // The spec's own `x-codeSamples`, labeled as their tabs are.
+      const object =
+        data.kind === "openapi" ? operationObject(data, operation) : undefined;
+      const samples = customCodeSamples({
+        "x-code-samples": object?.["x-code-samples"],
+        "x-codeSamples": object?.["x-codeSamples"],
+      }).map(
+        (sample) =>
+          `**${inlineText(sample.label)}**\n\n${fencedBlock(sample.lang, sample.source)}`
+      );
+      return [signature, ...notes, ...samples].join("\n\n");
     },
   } satisfies Record<string, ComponentMarkdown>;
 };

package/src/ai/relative-links.ts

@@ -7,8 +7,6 @@ import {
   withAuthoredBasePath,
   withBasePath,
 } from "../core/base-path.ts";
-import { nextFenceState } from "../core/code-fences.ts";
-import type { FenceState } from "../core/code-fences.ts";
 import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
@@ -49,10 +47,6 @@ export interface LinkedPage {
 /** Rewrite a page's relative page links to the routes they mean. */
 export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
 
-/** A reference definition's target: `[label]: ./install` or `<./install>`. */
-const DEFINITION =
-  /^(?<lead> {0,3}\[(?:[^\]\\]|\\.)+\]:[\t ]*)(?:<(?<angled>[^>]*)>|(?<bare>\S+))/u;
-
 /**
  * Whether a text could hold a relative page link at all: an inline link, a
  * reference definition, or a component `href` whose target isn't a URL with
@@ -88,31 +82,13 @@ const spliceLine = (line: string, splices: readonly Splice[]): string => {
   return out;
 };
 
-/** One line's reference-definition splice, when it defines a routed target. */
-const definitionSplice = (
-  line: string,
-  routed: (target: string) => string | undefined
-): Splice | undefined => {
-  const groups = DEFINITION.exec(line)?.groups;
-  const lead = groups?.lead;
-  const target = groups?.angled ?? groups?.bare;
-  const route = target === undefined ? undefined : routed(target);
-  if (lead === undefined || target === undefined || route === undefined) {
-    return undefined;
-  }
-  // An angle-bracketed target starts one past its `<`.
-  const angled = groups?.angled === undefined ? 0 : 1;
-  return { column: lead.length + angled, length: target.length, text: route };
-};
-
 /**
- * Every routed splice in `text`, by 0-based line: links and images, then
- * definitions. An image target goes through `imaged`, everything else through
- * `routed`.
+ * Every routed splice in `text`, by 0-based line: links, images, and
+ * reference definitions, as `extractLinks` finds them. An image target goes
+ * through `imaged`, everything else through `routed`.
  */
 const collectSplices = (
   text: string,
-  lines: readonly string[],
   routed: (target: string) => string | undefined,
   imaged: (target: string) => string | undefined
 ): Map<number, Splice[]> => {
@@ -130,16 +106,6 @@ const collectSplices = (
       });
     }
   }
-  let fence: FenceState = null;
-  for (const [index, line] of lines.entries()) {
-    const next = nextFenceState(line, fence);
-    const inFence = fence !== null || next !== null;
-    fence = next;
-    const splice = inFence ? undefined : definitionSplice(line, routed);
-    if (splice !== undefined) {
-      add(index, splice);
-    }
-  }
   return splices;
 };
 
@@ -242,7 +208,7 @@ export const relativeLinkRewriter = (
     };
 
     const lines = text.split("\n");
-    const splices = collectSplices(text, lines, routed, imaged);
+    const splices = collectSplices(text, routed, imaged);
 
     return lines
       .map((line, index) => {

package/src/astro/generate.ts

@@ -34,7 +34,11 @@ import {
   navVariants,
 } from "../components/layout/nav-utils.ts";
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
-import { validateUsedComponents } from "../core/component-diagnostics.ts";
+import { withChangelogIndexText } from "../core/changelog-index.ts";
+import {
+  missingExampleDiagnostics,
+  validateUsedComponents,
+} from "../core/component-diagnostics.ts";
 import {
   analyzeComponentOverrides,
   emptyComponentOverrides,
@@ -93,13 +97,13 @@ import {
   builtinProxyReferences,
   hasScalarReferences,
   needsPlaygroundProxy,
-  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 { sourcePages } from "../search/source-pages.ts";
 import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
@@ -125,6 +129,7 @@ import {
   customOgRoutes,
   discoverPages,
   hasGeneratedChangelog,
+  navTargetRoutes,
   routeIsTaken,
 } from "./pages.ts";
 import { candidateHolding } from "./render-deps.ts";
@@ -180,28 +185,35 @@ export type { PrerenderDepsPlugin } from "./render-deps.ts";
 const BLUME_SRC = join(packageRoot(), "src");
 
 /**
- * Absolute path to `babel-plugin-react-compiler`, resolved from Blume's own
- * package root (Blume ships it). Returns null when React or the compiler is off.
+ * Whether the generated `react()` call turns the React Compiler on: React and
+ * `react.compiler` are both on, and `oxc-transform-react` (Blume ships it)
+ * resolves. False when React or the compiler is off.
  *
- * The path must be absolute: @vitejs/plugin-react resolves babel plugins from
- * the *project* root, not `.blume/`, so a bare specifier fails in a user project
- * that never installed the plugin directly. Resolving from `packageRoot()` binds
- * to Blume's shipped copy regardless of the user's package manager or hoisting.
+ * The compiler is loaded by `@vitejs/plugin-react` with a bare
+ * `import("oxc-transform-react")` from its own directory, which fails the
+ * build when it throws, so the check walks the same chain — Blume →
+ * `@astrojs/react` → `@vitejs/plugin-react` — rather than resolving from
+ * Blume's root, which a strict package manager may not link the plugin to.
  */
 export const resolveReactCompiler = (
   config: ResolvedConfig,
   needsReact: boolean,
   pkgDir: string = packageRoot()
-): string | null => {
+): boolean => {
   if (!(needsReact && config.react.compiler)) {
-    return null;
+    return false;
   }
   try {
-    return createRequire(pathToFileURL(join(pkgDir, "_.js")).href).resolve(
-      "babel-plugin-react-compiler"
+    const astroReact = createRequire(
+      pathToFileURL(join(pkgDir, "_.js")).href
+    ).resolve("@astrojs/react");
+    const pluginReact = createRequire(astroReact).resolve(
+      "@vitejs/plugin-react"
     );
+    createRequire(pluginReact).resolve("oxc-transform-react");
+    return true;
   } catch {
-    return null;
+    return false;
   }
 };
 
@@ -213,11 +225,11 @@ export const resolveReactCompiler = (
 export const reactCompilerWarnings = (
   config: ResolvedConfig,
   needsReact: boolean,
-  compilerPath: string | null
+  compiler: boolean
 ): string[] =>
-  needsReact && config.react.compiler && !compilerPath
+  needsReact && config.react.compiler && !compiler
     ? [
-        "React Compiler is enabled but `babel-plugin-react-compiler` could not be resolved; falling back to an uncompiled build. Reinstall Blume, or set `react: { compiler: false }` to silence this.",
+        "React Compiler is enabled but `oxc-transform-react` could not be resolved; falling back to an uncompiled build. Reinstall Blume, or set `react: { compiler: false }` to silence this.",
       ]
     : [];
 
@@ -1142,23 +1154,32 @@ export const buildRuntimeData = (project: BlumeProject): string => {
 
   // Resolved UI dictionaries: one per locale under i18n, English baseline
   // otherwise. Threaded into chrome so the catch-all can pick the active locale.
+  // The `changelog` config's title and description replace the dictionaries'.
   const uiByLocale = i18n
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
           code,
-          resolveUIStrings(code, {
-            defaultLocale: i18n.defaultLocale,
-            overrides: i18n.ui,
-          }),
+          withChangelogIndexText(
+            config,
+            resolveUIStrings(code, {
+              defaultLocale: i18n.defaultLocale,
+              overrides: i18n.ui,
+            }),
+            code
+          ),
         ])
       )
     : {};
-  const defaultUi = i18n
-    ? resolveUIStrings(i18n.defaultLocale, {
-        defaultLocale: i18n.defaultLocale,
-        overrides: i18n.ui,
-      })
-    : EN_UI;
+  const defaultUi = withChangelogIndexText(
+    config,
+    i18n
+      ? resolveUIStrings(i18n.defaultLocale, {
+          defaultLocale: i18n.defaultLocale,
+          overrides: i18n.ui,
+        })
+      : EN_UI,
+    i18n?.defaultLocale
+  );
 
   const navigationByLocale = i18n
     ? Object.fromEntries(
@@ -1255,6 +1276,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       openInChat: config.ai.openInChat,
       repoUrl,
       search: {
+        analytics: config.search.analytics,
         enabled: config.search.provider.mode !== "none",
         popular: resolveSearchPopular(config.search.popular, config.basePath),
         provider: config.search.provider.kind,
@@ -2064,11 +2086,12 @@ export const generateRuntime = async (
   const needsVue = frameworks.has("vue");
   const needsSvelte = frameworks.has("svelte");
 
-  // Absolute path to the React Compiler babel plugin (null when off). Resolved
-  // here, Node-side, so the generated config points babel straight at Blume's
-  // shipped copy — see resolveReactCompiler. Any unresolved-but-requested
-  // warning is folded into `warnings` below (declared later).
-  const reactCompilerPath = resolveReactCompiler(config, needsReact);
+  // Whether react() turns the React Compiler on (false when off). Checked here,
+  // Node-side, so an unresolvable compiler degrades to an uncompiled build
+  // instead of failing it — see resolveReactCompiler. Any
+  // unresolved-but-requested warning is folded into `warnings` below (declared
+  // later).
+  const reactCompiler = resolveReactCompiler(config, needsReact);
 
   // Custom pages that should get a generated OG card (the home most of all).
   // Computed before the MCP `.well-known` routes are appended below — those are
@@ -2146,7 +2169,7 @@ export const generateRuntime = async (
           needsSvelte,
           needsVue,
           pages,
-          reactCompilerPath,
+          reactCompiler,
           searchClientPath,
           themePath,
         })
@@ -2209,7 +2232,7 @@ export const generateRuntime = async (
           languageIcons,
           sources: [
             `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
-            `${context.root}/**/*.{astro,mdx,ts,tsx}`,
+            `${context.root}/**/*.{astro,jsx,mdx,ts,tsx}`,
           ],
           twoslashCss: twoslashCss(),
           userTheme,
@@ -2247,7 +2270,10 @@ export const generateRuntime = async (
     writeMcpFiles(mcp, write, agentData),
     writeApiFiles(project, api, write, agentData, mcp),
     playgroundProxy.enabled
-      ? write(playgroundProxy.entrypoint, playgroundProxyTemplate(proxyOrigins))
+      ? write(
+          playgroundProxy.entrypoint,
+          playgroundProxyTemplate(proxyOrigins, config.rateLimit)
+        )
       : Promise.resolve(false),
   ]);
 
@@ -2317,7 +2343,11 @@ export const generateRuntime = async (
   if (searchAdapter.kind === "mixedbread") {
     await write(
       join(srcDir, "pages", "api", "search.ts"),
-      mixedbreadSearchEndpointTemplate(searchAdapter.options)
+      mixedbreadSearchEndpointTemplate(
+        searchAdapter.options,
+        sourcePages(project),
+        config.rateLimit
+      )
     );
   }
 
@@ -2372,7 +2402,7 @@ export const generateRuntime = async (
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...proxyAllowlistWarnings(config, openApiData),
     ...apiPageProxyWarnings(project),
-    ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
+    ...reactCompilerWarnings(config, needsReact, reactCompiler),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,
@@ -2380,24 +2410,18 @@ export const generateRuntime = async (
     ...overrideWarnings,
   ];
 
-  // Missing-navigation-target check, now that every servable route is known:
-  // content routes, custom `.astro` pages, the generated changelog, and any
-  // 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),
-    ...referenceRoutes(config),
-  ]);
-  if (changelogIndex) {
-    navTargetRoutes.add("/changelog");
-  }
+  // Missing-navigation-target check, now that every servable route is known
+  // (see `navTargetRoutes`).
   // 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),
+      ...validateNavTargets(
+        project.graph.navigation,
+        navTargetRoutes(project, pages)
+      ),
       ...validateSearchPopularIcons(config.search.popular),
     ].map(diagnosticWarning)
   );
@@ -2414,6 +2438,12 @@ export const generateRuntime = async (
       knownComponentTags,
       new Set(registry.map((item) => item.name))
     ).map(diagnosticWarning),
+    ...missingExampleDiagnostics(
+      project.graph.pages,
+      exampleDiscovery,
+      context.root,
+      knownComponentTags
+    ).map(diagnosticWarning),
     ...dependencyWarnings
   );
   if (hasScalarReferences(config)) {