blume 1.6.5 → 1.7.0

package/src/astro/generate.ts

@@ -12,7 +12,6 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
-import { imageSize } from "image-size";
 import pMap from "p-map";
 import {
   basename,
@@ -29,10 +28,16 @@ import { OPENAPI_PATH } from "../ai/api/paths.ts";
 import { buildApiSpec } from "../ai/api/spec.ts";
 import { buildAskData } from "../ai/ask-data.ts";
 import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
+import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
+import type { RawMarkdownEntry } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import type { McpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import {
+  hasDeferrableGroups,
+  navVariants,
+} from "../components/layout/nav-utils.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { validateUsedComponents } from "../core/component-diagnostics.ts";
 import { analyzeComponentOverrides } from "../core/component-overrides.ts";
@@ -64,10 +69,18 @@ import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { resolveDocsCollection } from "../core/sources/resolve.ts";
+import { svgDimensions } from "../core/svg-dimensions.ts";
 import { trimChar } from "../core/trim.ts";
 import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Diagnostic, Navigation } from "../core/types.ts";
+import { getBlumeVersion } from "../core/version.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import {
+  languageIconCss,
+  languageIconSlugsIn,
+} from "../markdown/language-icon.ts";
+import { hasMermaidFence } from "../markdown/mermaid.ts";
+import { ogCacheDir } from "../og/cache.ts";
 import { missingFontFiles, resolveOgFonts } from "../og/derive.ts";
 import type { DerivedOgFonts } from "../og/derive.ts";
 import { resolveOgLogo } from "../og/logo.ts";
@@ -104,6 +117,7 @@ import {
   exampleMarkdownLookup,
   exampleScanRoots,
 } from "./examples.ts";
+import { publishDevNegotiation } from "./integration.ts";
 import { discoverIslands } from "./islands.ts";
 import {
   customOgRoutes,
@@ -121,7 +135,6 @@ import {
   changelogIndexTemplate,
   contentAssetsEndpointTemplate,
   contentConfigTemplate,
-  envTemplate,
   exampleMapTemplate,
   exampleWrapperTemplate,
   examplesPageTemplate,
@@ -147,10 +160,13 @@ import {
   runtimeDependencies,
   runtimePackageTemplate,
   runtimeTsconfigTemplate,
+  featuresTemplate,
+  navFragmentTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
   stagedContentDir,
 } from "./templates.ts";
+import type { ClientFeatures } from "./templates.ts";
 
 /** Absolute path to the Blume package `src` directory. */
 const BLUME_SRC = join(packageRoot(), "src");
@@ -321,10 +337,35 @@ export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
 };
 
 /**
- * Point `link` at Blume's dependency directory via a `node_modules` junction,
- * replacing a stale junction we own and leaving a real directory untouched.
+ * Create `link` as a directory symlink to `target`, falling back to a junction.
+ *
+ * The type only matters on Windows, and there a junction is the wrong first
+ * choice: Windows can't follow a *relative* symlink reached through a
+ * junction (it resolves the relative target against the junction-side path,
+ * so it lands outside the store and every lookup is ENOENT), and Bun's
+ * isolated linker writes exactly those into Blume's dependency directory
+ * whenever it holds symlink privilege. A directory symlink traverses them
+ * fine. Without that privilege (no Developer Mode, non-admin shell) creating
+ * one fails, so fall back to a junction — and in that session the installer
+ * had no privilege either, so the deps are absolute junctions a junction can
+ * follow. Exported for testing.
+ */
+export const symlinkDir = async (
+  target: string,
+  link: string
+): Promise<void> => {
+  try {
+    await symlink(target, link, "dir");
+  } catch {
+    await symlink(target, link, "junction");
+  }
+};
+
+/**
+ * Point `link` at Blume's dependency directory via a `node_modules` link,
+ * replacing a stale link we own and leaving a real directory untouched.
  *
- * `lstat`, not `existsSync`, so a broken junction (target since moved) is still
+ * `lstat`, not `existsSync`, so a broken link (target since moved) is still
  * detected — `existsSync` follows the link and reports a dangling one as absent.
  */
 const linkDepsJunction = async (
@@ -355,7 +396,7 @@ const linkDepsJunction = async (
     await rm(link, { force: true });
   }
   await mkdir(dirname(link), { recursive: true });
-  await symlink(depsDir, link, "junction");
+  await symlinkDir(depsDir, link);
 };
 
 /** Read the `version` field of a `package.json`, or null when unreadable. */
@@ -906,24 +947,13 @@ interface LogoDimensions {
 }
 
 /**
- * Read dimensions from an SVG's explicit size or its view box. Measured with
- * image-size — the same parser og/card.ts uses for the OG brand mark, so the
- * header and the card can't disagree about one logo — which also tolerates
- * the spellings the old regex missed (unquoted values, `em`/`pt` lengths, a
- * `>` inside another attribute). An SVG with no usable size returns partial
- * dimensions or throws; both collapse to undefined.
+ * Read dimensions from an SVG's explicit size or its view box, with the same
+ * root-tag parser og/card.ts uses for the OG brand mark so the header and the
+ * card can't disagree about one logo. An SVG with no usable size collapses to
+ * undefined.
  */
-const svgDimensions = (svg: string | undefined): LogoDimensions | undefined => {
-  if (!svg) {
-    return;
-  }
-  try {
-    const { height, width } = imageSize(Buffer.from(svg));
-    return height && width ? { height, width } : undefined;
-  } catch {
-    return undefined;
-  }
-};
+const logoDimensions = (svg: string | undefined): LogoDimensions | undefined =>
+  svg ? (svgDimensions(svg) ?? undefined) : undefined;
 
 /** Read a local SVG logo from the project root or public directory. */
 const readLogoSvg = (
@@ -988,8 +1018,8 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
     return { alt, href: brandHref, svg: lightSvg, text };
   }
 
-  const lightDimensions = svgDimensions(lightSvg);
-  const darkDimensions = svgDimensions(darkSvg);
+  const lightDimensions = logoDimensions(lightSvg);
+  const darkDimensions = logoDimensions(darkSvg);
   const dimensions =
     lightDimensions || darkDimensions
       ? { dark: darkDimensions, light: lightDimensions }
@@ -1904,6 +1934,84 @@ const assertFontFilesExist = (project: BlumeProject): void => {
   }
 };
 
+/**
+ * The client libraries a site needs (see `featuresTemplate`): the EPUB
+ * generator when `export.epub` is on, and the Mermaid element when any page's
+ * source has a mermaid fence — read from the raw-Markdown mirrors (every
+ * route's verbatim source) and, for sources that carry their text on the
+ * page record, the record itself.
+ */
+export const clientFeaturesFrom = (
+  project: BlumeProject,
+  rawMarkdown: Record<string, RawMarkdownEntry>
+): ClientFeatures => ({
+  epub: project.config.export.epub,
+  mermaid:
+    Object.values(rawMarkdown).some((entry) =>
+      hasMermaidFence(entry.mdx ?? entry.md ?? "")
+    ) ||
+    project.graph.pages.some(
+      (page) => page.body !== undefined && hasMermaidFence(page.body.text)
+    ),
+});
+
+/**
+ * The theme's code-block icon rules for the languages the site's Markdown
+ * uses (see `languageIconCss`), read from the raw-Markdown mirrors and the
+ * page records that carry their text.
+ */
+export const languageIconCssFrom = (
+  project: BlumeProject,
+  rawMarkdown: Record<string, RawMarkdownEntry>
+): string =>
+  languageIconCss(
+    languageIconSlugsIn(
+      [
+        ...Object.values(rawMarkdown).map(
+          (entry) => entry.mdx ?? entry.md ?? ""
+        ),
+        ...project.graph.pages.map((page) => page.body?.text ?? ""),
+      ].join("\n")
+    )
+  );
+
+/** {@link languageIconCssFrom} over a fresh read of the raw Markdown (eject). */
+export const languageIconCssFor = async (
+  project: BlumeProject
+): Promise<string> =>
+  languageIconCssFrom(project, await buildRawMarkdown(project));
+
+/**
+ * The deferred sidebar fragments page, only when some group is a disclosure
+ * or a drill-in panel — a flat sidebar renders every row on every page, so
+ * there is nothing to fetch. A previous pass's page is an orphan the
+ * generator removes when the sidebar goes flat again.
+ */
+const writeNavFragments = (
+  write: (path: string, content: string) => Promise<boolean>,
+  srcDir: string,
+  navFragments: boolean
+): Promise<boolean> =>
+  navFragments
+    ? write(
+        join(
+          srcDir,
+          "pages",
+          "blume-nav",
+          "[version]",
+          "[locale]",
+          "[id].astro"
+        ),
+        navFragmentTemplate()
+      )
+    : Promise.resolve(false);
+
+/** {@link clientFeaturesFrom} over a fresh read of the raw Markdown (eject). */
+export const clientFeaturesFor = async (
+  project: BlumeProject
+): Promise<ClientFeatures> =>
+  clientFeaturesFrom(project, await buildRawMarkdown(project));
+
 /**
  * Write (or update) the generated `.blume/` Astro runtime for a project.
  * Only files whose content changed are rewritten so Vite HMR stays fast.
@@ -1919,6 +2027,7 @@ export const generateRuntime = async (
   const askPath = join(srcDir, "generated", "Ask.astro");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
+  const featuresPath = join(srcDir, "generated", "features.ts");
   const examplesPath = join(srcDir, "generated", "examples.ts");
   const examplesThemePath = join(srcDir, "generated", "examples.css");
 
@@ -1937,9 +2046,24 @@ export const generateRuntime = async (
 
   const depsLinkWarning = await ensureDepsLink(out);
 
+  // The dev negotiation inputs. Published in memory (below) rather than baked
+  // into the generated config, so a content-route change never rewrites
+  // `astro.config.mjs` — which would restart the dev server in place.
+  const contentRoutes = markdownRoutePaths(project);
+  const homeLinkHeader =
+    buildHomeLinkHeader(config, contentRoutes) ?? undefined;
+
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
+  // Every route's source Markdown: published as `blume:raw-markdown` below,
+  // and inspected here for the client features the site needs.
+  const rawMarkdown = await buildRawMarkdown(project);
+  const clientFeatures = clientFeaturesFrom(project, rawMarkdown);
+  const navFragments = navVariants(project.graph).some(({ navigation }) =>
+    hasDeferrableGroups(navigation.sidebar)
+  );
+  const languageIcons = languageIconCssFrom(project, rawMarkdown);
   // 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).
@@ -2059,10 +2183,12 @@ export const generateRuntime = async (
           askPath,
           config,
           contentRoot: docsCollection.base,
-          contentRoutes: markdownRoutePaths(project),
+          contentRoutes,
           context,
           examplesPath,
           examplesThemePath,
+          features: clientFeatures,
+          featuresPath,
           integrationBridge,
           needsReact,
           needsSvelte,
@@ -2080,7 +2206,6 @@ export const generateRuntime = async (
         )
       ),
       write(join(out, "tsconfig.json"), runtimeTsconfigTemplate()),
-      write(join(srcDir, "env.d.ts"), envTemplate()),
       write(
         join(srcDir, "content.config.ts"),
         contentConfigTemplate({
@@ -2097,9 +2222,11 @@ export const generateRuntime = async (
           exportEpub,
           exportPdf,
           mathEnabled: usesMath,
+          navFragments,
           needsReact,
         })
       ),
+      writeNavFragments(write, srcDir, navFragments),
       // The header's Ask trigger, behind the `blume:ask` alias. Always written
       // (even when Ask is off, as a component that renders nothing) so the alias
       // resolves — the same contract as `blume:search-client`.
@@ -2131,6 +2258,7 @@ export const generateRuntime = async (
         themePath,
         tailwindEntryTemplate({
           configTokens: `${buildThemeCss(config.theme)}${buildFontsCss(config.theme.fonts)}`,
+          languageIcons,
           sources: [
             `${BLUME_SRC}/**/*.{astro,ts,tsx}`,
             `${context.root}/**/*.{astro,mdx,ts,tsx}`,
@@ -2193,6 +2321,10 @@ export const generateRuntime = async (
         ogRoutes,
         {
           ...projectOgFonts(project),
+          cache: {
+            dir: ogCacheDir(project.context),
+            version: getBlumeVersion(),
+          },
           pageDescriptions: config.seo.og.description !== false,
         },
         changelogIndex
@@ -2229,6 +2361,7 @@ export const generateRuntime = async (
     }),
     writeNotFoundPage(write, srcDir, pages, project.graph.pages),
     write(searchClientPath, searchClientTemplate(config)),
+    write(featuresPath, featuresTemplate(clientFeatures)),
   ]);
 
   // Client-loaded providers (orama, flexsearch) ship a static index + endpoint.
@@ -2257,7 +2390,6 @@ export const generateRuntime = async (
     `${JSON.stringify(buildIncludeGraph(project.graph.pages))}\n`
   );
 
-  const rawMarkdown = await buildRawMarkdown(project);
   modules.set("blume:raw-markdown", JSON.stringify(rawMarkdown));
   // The originals behind the rewritten `/blume-assets/content/…` references in
   // the agent-facing Markdown, plus the endpoint that serves them (and the
@@ -2391,6 +2523,7 @@ export const generateRuntime = async (
   // Publish last, once every page that imports a module is on disk: a live
   // dev server invalidates the changed modules and reloads the browser against
   // the finished tree, never a half-written one.
+  publishDevNegotiation({ contentRoutes, homeLinkHeader });
   publishRuntimeModules(modules);
 
   return { structuralChange: structural.some(Boolean), warnings };

package/src/astro/include-hmr.ts

@@ -1,4 +1,6 @@
-import { readFile, utimes } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+
+import { refreshBlumeContent } from "./integration.ts";
 
 /**
  * Dev-server invalidation for `<include>` partials. A partial is not an Astro
@@ -54,25 +56,20 @@ export const includeHmrPlugin = (graphPath: string): IncludeHmrPlugin => ({
       return;
     }
     const { moduleGraph, ws } = ctx.server;
-    const now = new Date();
     for (const includer of includers) {
       for (const mod of moduleGraph.getModulesByFile(includer) ?? []) {
         // SAFETY: the module came out of this module graph; `never` only
         // reflects that the structural slice doesn't model the node type.
         moduleGraph.invalidateModule(mod as never);
       }
-      // Plain `.md` pages have no Vite module: their HTML lives in the
-      // content-layer store, rendered at sync time. Bump the page's mtime so
-      // Astro's content watcher re-syncs it — the include-aware digest
-      // (`withIncludeRefresh`) then forces a fresh render that re-reads the
-      // edited partial.
-      try {
-        // oxlint-disable-next-line no-await-in-loop -- ordered per-page touch
-        await utimes(includer, now, now);
-      } catch {
-        // The page may have been deleted since the graph was written.
-      }
     }
+    // Plain `.md` pages have no Vite module: their HTML lives in the
+    // content-layer store, rendered at sync time. Ask Astro to re-run the
+    // loaders — `withIncludeRefresh` then evicts the includers whose partials
+    // changed, so the glob loader renders them afresh. `false` only before
+    // the server's `astro:server:setup` has run, when there is no store to go
+    // stale yet.
+    await refreshBlumeContent();
     ws.send({ type: "full-reload" });
     // The partial itself is not a module; suppress Vite's default handling.
     return [];

package/src/astro/index.ts

@@ -3,7 +3,12 @@ export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
 export { includeHmrPlugin } from "./include-hmr.ts";
 export { withIncludeRefresh } from "./include-refresh.ts";
 export type { GenerateResult } from "./generate.ts";
-export { blumeIntegration } from "./integration.ts";
+export {
+  blumeIntegration,
+  publishBuildProject,
+  publishDevNegotiation,
+  refreshBlumeContent,
+} from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";
 export {
   publishRuntimeModules,