blume 1.6.6 → 1.7.1

package/src/astro/generate.ts

@@ -30,9 +30,14 @@ 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";
@@ -68,7 +73,14 @@ 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";
@@ -148,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");
@@ -322,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.
  *
- * `lstat`, not `existsSync`, so a broken junction (target since moved) is still
+ * 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 link (target since moved) is still
  * detected — `existsSync` follows the link and reports a dangling one as absent.
  */
 const linkDepsJunction = async (
@@ -356,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. */
@@ -1894,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.
@@ -1909,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,6 +2056,14 @@ export const generateRuntime = async (
   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).
@@ -2060,6 +2187,8 @@ export const generateRuntime = async (
           context,
           examplesPath,
           examplesThemePath,
+          features: clientFeatures,
+          featuresPath,
           integrationBridge,
           needsReact,
           needsSvelte,
@@ -2093,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`.
@@ -2127,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}`,
@@ -2189,6 +2321,10 @@ export const generateRuntime = async (
         ogRoutes,
         {
           ...projectOgFonts(project),
+          cache: {
+            dir: ogCacheDir(project.context),
+            version: getBlumeVersion(),
+          },
           pageDescriptions: config.seo.og.description !== false,
         },
         changelogIndex
@@ -2203,6 +2339,7 @@ export const generateRuntime = async (
       changelogIndexTemplate({
         exportEpub,
         exportPdf,
+        mathEnabled: usesMath,
         needsReact,
         staged: hasStaged,
       })
@@ -2225,6 +2362,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.
@@ -2253,7 +2391,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

package/src/astro/integration.ts

@@ -374,8 +374,19 @@ export const blumeIntegration = (
           filename: MODULE_TYPES_FILE,
         });
       },
-      "astro:config:setup": ({ createCodegenDir, injectRoute }) => {
+      "astro:config:setup": ({
+        addMiddleware,
+        createCodegenDir,
+        injectRoute,
+      }) => {
         codegenDir = createCodegenDir();
+        // Splices each page's icon sprite in once the page has rendered (see
+        // components/icon-sprite-middleware.ts). Innermost, so a project's
+        // own middleware sees the finished HTML.
+        addMiddleware({
+          entrypoint: "blume/components/icon-sprite-middleware.ts",
+          order: "post",
+        });
         for (const page of options.pages) {
           injectRoute({
             entrypoint: page.entrypoint,

package/src/astro/module-types.ts

@@ -66,6 +66,15 @@ declare module "blume:openapi" {
   export default specs;
 }
 
+declare module "blume:features" {
+  /** Registers the <blume-mermaid> element; null when no page has a mermaid fence. */
+  export const loadMermaid: (() => Promise<unknown>) | null;
+  /** The EPUB generator's browser bundle; null when export.epub is off. */
+  export const loadEpub:
+    | (() => Promise<typeof import("epub-gen-memory/bundle")>)
+    | null;
+}
+
 declare module "blume:search-client" {
   export const createSearch: () =>
     | import("blume/components/layout/search/types.ts").SearchFn