blume 1.4.3 → 1.5.1

package/src/astro/generate.ts

@@ -61,7 +61,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
-import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
+import { buildFontsCss, configuredFonts } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
@@ -489,12 +489,14 @@ export const ensureDepsLink = async (
  * (`<build.server>/.prerender/`) output — so it fires for exactly that build.
  * Inert in dev, where there is no build and `writeBundle` never runs.
  */
-export const prerenderDepsPlugin = (
-  pkgDir: string = packageRoot()
-): {
+export interface PrerenderDepsPlugin {
   name: string;
   writeBundle: (options: { dir?: string }) => Promise<void>;
-} => ({
+}
+
+export const prerenderDepsPlugin = (
+  pkgDir: string = packageRoot()
+): PrerenderDepsPlugin => ({
   name: "blume:prerender-deps",
   writeBundle: async (options) => {
     if (!options.dir || basename(options.dir) !== ".prerender") {
@@ -528,14 +530,16 @@ interface ServerAppResolveContext {
  * Stripping the spurious `.js` and delegating back to Astro's resolver lets the
  * reload complete cleanly, so the renamed route resolves without a restart.
  */
-export const serverAppResolvePlugin = (): {
+export interface ServerAppResolvePlugin {
   enforce: "pre";
   name: string;
   resolveId: (
     this: ServerAppResolveContext,
     id: string
   ) => Promise<string | null>;
-} => ({
+}
+
+export const serverAppResolvePlugin = (): ServerAppResolvePlugin => ({
   enforce: "pre",
   name: "blume:server-app-resolve",
   async resolveId(id) {
@@ -548,20 +552,20 @@ export const serverAppResolvePlugin = (): {
 });
 
 /** Astro integration package each non-React island framework needs installed. */
-const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
-  svelte: "@astrojs/svelte",
-  vue: "@astrojs/vue",
-};
+const ISLAND_FRAMEWORK_DEPS = new Map([
+  ["svelte", "@astrojs/svelte"],
+  ["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",
-};
+const DEPLOYMENT_ADAPTER_DEPS = new Map([
+  ["cloudflare", "@astrojs/cloudflare"],
+  ["netlify", "@astrojs/netlify"],
+]);
 
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
@@ -574,7 +578,7 @@ const islandFrameworkWarnings = (
 ): string[] => {
   const warnings: string[] = [];
   for (const framework of frameworks) {
-    const dep = ISLAND_FRAMEWORK_DEPS[framework];
+    const dep = ISLAND_FRAMEWORK_DEPS.get(framework);
     if (dep && !canResolveFrom(root, dep)) {
       warnings.push(
         `Islands use ${framework}, which needs "${dep}". Install it (e.g. \`npm install ${dep} ${framework}\`).`
@@ -599,7 +603,7 @@ const deploymentAdapterWarnings = (
 ): string[] => {
   const dep =
     deployment.output === "server" && deployment.adapter
-      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter)
       : undefined;
   if (
     dep &&
@@ -906,6 +910,10 @@ const readLogoSvg = (
   return file ? readFileSync(file, "utf-8") : undefined;
 };
 
+/** Narrows a config union's string shorthand from its object form. */
+const isStringShorthand = <T>(value: T | string): value is string =>
+  typeof value === "string";
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -916,12 +924,12 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { image: logo } : logo;
+  const config = isStringShorthand(logo) ? { image: logo } : logo;
   // `text` is passed through verbatim: `undefined` lets the brand fall back to
   // the site title, `""` renders the mark alone (a logo with the wordmark baked
   // in).
   const { href, image: source, text } = config;
-  const image = typeof source === "string" ? { light: source } : source;
+  const image = isStringShorthand(source) ? { light: source } : source;
   const light = image?.light ?? image?.dark;
   const dark = image?.dark ?? image?.light;
   const alt = image?.alt ?? "";
@@ -957,18 +965,18 @@ const FAVICON_CANDIDATES = [
 ];
 
 /** `<link type>` MIME for the favicon extensions we recognize. */
-const FAVICON_TYPES: Record<string, string> = {
-  ico: "image/x-icon",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-};
+const FAVICON_TYPES = new Map([
+  ["ico", "image/x-icon"],
+  ["jpeg", "image/jpeg"],
+  ["jpg", "image/jpeg"],
+  ["png", "image/png"],
+  ["svg", "image/svg+xml"],
+]);
 
 /** Infer the `<link type>` MIME from a filename, when we recognize the extension. */
 const faviconType = (name: string): string | undefined => {
   const ext = name.split(".").pop()?.toLowerCase();
-  return ext ? FAVICON_TYPES[ext] : undefined;
+  return ext ? FAVICON_TYPES.get(ext) : undefined;
 };
 
 /** Read a file and encode it as a `data:` URI of the given MIME type. */
@@ -1041,7 +1049,7 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   if (!banner) {
     return null;
   }
-  if (typeof banner === "string") {
+  if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
   return {
@@ -1234,6 +1242,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      versions: config.versions ?? null,
       webmcp: {
         enabled: config.ai.webmcp,
         llms: config.ai.llmsTxt.enabled,
@@ -1246,10 +1255,23 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     })),
     // CSS variables for Astro's <Font> component; matches the astro.config
     // `fonts:` entries derived from the same theme.fonts config.
-    fontCssVars: configuredCssVars(config.theme.fonts),
+    fontCssVars: configuredFonts(config.theme.fonts),
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
+    // Per-archived-version navigation; the catch-all selects by the route's
+    // version, then locale.
+    navigationByVersion: Object.fromEntries(
+      Object.entries(graph.navigationByVersion).map(([id, byLocale]) => [
+        id,
+        Object.fromEntries(
+          Object.entries(byLocale).map(([code, nav]) => [
+            code,
+            withRepoUrl(nav),
+          ])
+        ),
+      ])
+    ),
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
@@ -1264,6 +1286,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       locale: route.locale,
       path: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     })),
     // Default-locale chrome strings (English baseline when not under i18n).
     ui: defaultUi,
@@ -1600,6 +1624,11 @@ export const generateRuntime = async (
   // private and filtered out anyway, but the intent is the user's pages.
   const ogRoutes = customOgRoutes(pages, config.title, config.seo.og.titles);
 
+  // Whether the generated `/changelog` index exists — shared by the OG endpoint
+  // (which adds the index's own card) and the page write below. Computed here,
+  // before the MCP discovery pages are appended, on the user's own pages.
+  const changelogIndex = hasGeneratedChangelog(project, pages);
+
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
   // normal (server-rendered) page written by `writeMcpFiles`.
@@ -1756,12 +1785,12 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes, projectOgFonts(project))
+      ogEndpointTemplate(ogRoutes, projectOgFonts(project), changelogIndex)
     );
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1861,8 +1890,9 @@ export const generateRuntime = async (
     ]);
   }
 
-  // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
-  // mounted on its configured route and regenerated each run.
+  // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
+  // self-contained page per source, mounted on its configured route and
+  // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
@@ -1881,7 +1911,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceRoutes(config),
   ]);
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     navTargetRoutes.add("/changelog");
   }
   // Curated `search.popular` icons live outside the navigation model, so they

package/src/astro/integration.ts

@@ -6,9 +6,20 @@ import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
 
+/** The `{ type: "error" }` payload Vite's browser overlay renders. */
+interface OverlayErrorPayload {
+  err: {
+    id?: string;
+    message: string;
+    plugin: string;
+    stack: string;
+  };
+  type: "error";
+}
+
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
-  send: (payload: unknown) => void;
+  send: (payload: OverlayErrorPayload) => void;
 }
 interface OverlayServer {
   hot?: OverlayChannel;
@@ -164,7 +175,7 @@ export const blumeIntegration = (
     "astro:server:setup": ({ server }) => {
       // Keep a handle on the dev server so Blume diagnostics can be pushed to
       // its browser error overlay (see `showBlumeErrorOverlay`).
-      overlayServer = server as unknown as OverlayServer;
+      overlayServer = server;
       // Prepend so the rewrite happens before Astro's own request handler,
       // letting the rewritten URL resolve to the `.md` endpoint.
       server.middlewares.stack.unshift({

package/src/astro/islands.ts

@@ -40,13 +40,20 @@ const VALID_MODES = new Set<IslandClientMode>([
   "visible",
 ]);
 
+/** Whether a declared client mode is one Astro's directives support. */
+const isClientMode = (mode: string): mode is IslandClientMode =>
+  // SAFETY: `Set.has` only compares identity at runtime; the assertion widens
+  // the lookup key so the narrower-typed set accepts it, and the `has` result
+  // is exactly the predicate being claimed.
+  VALID_MODES.has(mode as IslandClientMode);
+
 /** Island extensions mapped to the Astro renderer that handles them. */
-const FRAMEWORK_BY_EXT: Record<string, IslandFramework> = {
-  jsx: "react",
-  svelte: "svelte",
-  tsx: "react",
-  vue: "vue",
-};
+const FRAMEWORK_BY_EXT = new Map<string, IslandFramework>([
+  ["jsx", "react"],
+  ["svelte", "svelte"],
+  ["tsx", "react"],
+  ["vue", "vue"],
+]);
 
 // Captures the extension so we can both strip it from the name and pick the
 // framework. Kept in sync with the glob below.
@@ -66,13 +73,13 @@ export const readClientMode = (
   if (!mode) {
     return DEFAULT_CLIENT;
   }
-  if (!VALID_MODES.has(mode as IslandClientMode)) {
+  if (!isClientMode(mode)) {
     warnings.push(
       `Island "${file}" declares an unknown client mode "${mode}"; defaulting to "${DEFAULT_CLIENT}". Use "load", "idle", "visible", or "only".`
     );
     return DEFAULT_CLIENT;
   }
-  return mode as IslandClientMode;
+  return mode;
 };
 
 /**
@@ -109,7 +116,7 @@ export const discoverIslands = async (
   const collectIsland = (file: string, source: string): void => {
     const base = basename(file);
     const ext = base.match(ISLAND_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT.get(ext) : undefined;
     if (!framework) {
       return;
     }