blume 0.1.0 → 0.1.2

package/src/astro/generate.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import {
+  lstat,
   mkdir,
   readFile,
   rename,
@@ -10,18 +11,25 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
-import { dirname, join, normalize, relative } from "pathe";
+import { basename, dirname, join, normalize, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
+import type {
+  BlumeBanner,
+  BlumeData,
+  BlumeFavicon,
+  BlumeLogo,
+} from "../core/data.ts";
 import { EN_UI, resolveUIStrings } from "../core/i18n-ui.ts";
 import { resolveFallbackLocale } from "../core/i18n.ts";
 import { packageRoot } from "../core/package-root.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { resolveTsconfigAliases } from "../core/tsconfig-aliases.ts";
 import type { Navigation } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import {
@@ -35,8 +43,9 @@ import { tailwindEntryTemplate } from "../theme/entry.ts";
 import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
+import { discoverExamples } from "./examples.ts";
 import { discoverIslands } from "./islands.ts";
-import { discoverPages } from "./pages.ts";
+import { customOgRoutes, discoverPages } from "./pages.ts";
 import {
   askEndpointTemplate,
   astroConfigTemplate,
@@ -44,6 +53,9 @@ import {
   changelogIndexTemplate,
   contentConfigTemplate,
   envTemplate,
+  exampleMapTemplate,
+  exampleWrapperTemplate,
+  exampleSlug,
   islandMapTemplate,
   islandWrapperTemplate,
   mcpEndpointTemplate,
@@ -64,8 +76,6 @@ import {
 
 /** Absolute path to the Blume package `src` directory. */
 const BLUME_SRC = join(packageRoot(), "src");
-/** The Blume package's own `node_modules` (where Astro and friends live). */
-const BLUME_NODE_MODULES = join(packageRoot(), "node_modules");
 
 /** Whether a module specifier resolves from a directory via node resolution. */
 const canResolveFrom = (fromDir: string, spec: string): boolean => {
@@ -77,31 +87,195 @@ const canResolveFrom = (fromDir: string, spec: string): boolean => {
   }
 };
 
-/** Whether Astro resolves from a directory via normal node resolution. */
-const canResolveAstro = (fromDir: string): boolean =>
-  canResolveFrom(fromDir, "astro/package.json");
+/**
+ * Realpath of the `astro` package node resolves from a directory, or null when
+ * none resolves. Comparing this for `.blume/` against Blume's own deps tells
+ * whether the runtime would bind to the *same* astro Blume uses or a different
+ * one shadowing it (the hoisted-conflict failure mode).
+ */
+const resolvedAstroPath = (fromDir: string): string | null => {
+  try {
+    const pkg = createRequire(
+      pathToFileURL(join(fromDir, "_.js")).href
+    ).resolve("astro/package.json");
+    return realpathSync(pkg);
+  } catch {
+    return null;
+  }
+};
 
 /**
- * Make the generated runtime resolve Astro and its integrations. When they are
- * hoisted into the project (the usual case for published installs), resolution
- * already works. When they are nested and unreachable (workspaces, strict
- * package managers), symlink Blume's own dependencies into `.blume`.
+ * Locate the directory that holds Blume's installed dependencies (Astro and its
+ * integrations).
+ *
+ * With a clean hoisted install this is moot — the deps sit in a `node_modules`
+ * the generated `.blume/` already walks up into, and {@link ensureDepsLink}
+ * short-circuits before we need it. But under isolated linkers (Bun's
+ * `isolated` mode, pnpm) Blume's deps are NOT hoisted into the project; they
+ * live beside the Blume package in a virtual store, invisible to the upward
+ * walk from `.blume/`. Two layouts are possible, so probe for `astro`:
+ *   - `<blume>/node_modules` — deps nested under the package (workspace source)
+ *   - `dirname(<blume>)`     — deps as siblings in the store (isolated/pnpm)
+ *
+ * `packageRoot()` resolves to Blume's real on-disk path (Node follows the
+ * install symlink), so its parent is the store's package directory where the
+ * isolated linker places the siblings. The previous fixed
+ * `packageRoot()/node_modules` assumption missed the sibling layout entirely,
+ * which is why isolated-linker projects had to redeclare Blume's deps by hand.
  */
-const ensureDepsLink = async (outDir: string): Promise<void> => {
-  if (canResolveAstro(outDir)) {
-    return;
+export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
+  const candidates = [join(pkgDir, "node_modules"), dirname(pkgDir)];
+  return candidates.find((dir) => existsSync(join(dir, "astro"))) ?? 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.
+ *
+ * `lstat`, not `existsSync`, so a broken junction (target since moved) is still
+ * detected — `existsSync` follows the link and reports a dangling one as absent.
+ */
+const linkDepsJunction = async (
+  link: string,
+  depsDir: string
+): Promise<void> => {
+  const existing = await lstat(link).catch(() => null);
+  if (existing) {
+    if (!existing.isSymbolicLink()) {
+      return;
+    }
+    await rm(link, { force: true });
   }
-  if (!existsSync(join(BLUME_NODE_MODULES, "astro"))) {
-    return;
+  await mkdir(dirname(link), { recursive: true });
+  await symlink(depsDir, link, "junction");
+};
+
+/** Read the `version` field of a `package.json`, or null when unreadable. */
+const readPkgVersion = (pkgJsonPath: string | null): string | null => {
+  if (!pkgJsonPath) {
+    return null;
   }
-  const link = join(outDir, "node_modules");
-  if (existsSync(link)) {
-    return;
+  try {
+    return JSON.parse(readFileSync(pkgJsonPath, "utf-8")).version ?? null;
+  } catch {
+    return null;
   }
-  await mkdir(outDir, { recursive: true });
-  await symlink(BLUME_NODE_MODULES, link, "junction");
 };
 
+/**
+ * Build the diagnostic for a split-layout Astro conflict that a symlink can't
+ * repair: a different Astro is hoisted to the project root, shadowing Blume's,
+ * and `@astrojs/mdx` binds to the wrong copy. `blumeAstroPkg`/`shadowAstroPkg`
+ * are the resolved `astro/package.json` paths for Blume's set and the one the
+ * runtime actually resolves.
+ */
+const astroConflictWarning = (
+  blumeAstroPkg: string | null,
+  shadowAstroPkg: string | null
+): string => {
+  const blume = readPkgVersion(blumeAstroPkg);
+  const shadow = readPkgVersion(shadowAstroPkg);
+  const versions =
+    blume && shadow
+      ? `astro@${shadow} shadowing Blume's astro@${blume}`
+      : "a second copy of Astro shadowing Blume's";
+  const pin = blume ?? "<Blume's astro version>";
+  return `Astro version conflict: another dependency hoisted ${versions} to the project root, so @astrojs/mdx binds to the wrong copy and the build fails on a missing export (e.g. "chunkToString"). A single symlink can't reconcile a split install — pin Blume's Astro by adding a package.json "overrides" (npm/bun/pnpm) or "resolutions" (yarn) entry { "astro": "${pin}" }, then reinstall. Run \`npm ls astro\` to find the dependency pulling the older copy.`;
+};
+
+/**
+ * Make the generated runtime resolve Astro and its integrations against Blume's
+ * own dependency set. Two failure modes this repairs:
+ *
+ *   - Astro is *unreachable* from `.blume/` (workspaces under isolated linkers,
+ *     pnpm) — the deps live in a store the upward walk can't see.
+ *   - Astro *resolves to the wrong copy* — a hoisted sibling pinned an older
+ *     major (e.g. `astro@6` for a type-only import) that shadows Blume's
+ *     `astro@7`, so `@astrojs/mdx@7` binds to it and crashes the build on a
+ *     missing export. Resolving merely *an* astro isn't enough; it must be the
+ *     same one Blume uses.
+ *
+ * In both cases we symlink Blume's dependency directory in as
+ * `.blume/node_modules` so the generated config's bare specifiers (`astro`,
+ * `@astrojs/mdx`, …) bind to the matching set. We only do this when those deps
+ * are a *co-located, consistent* set (astro beside the `@astrojs/mdx` that binds
+ * to it). A split layout — an integration hoisted away from a conflicting astro
+ * — can't be made consistent by a single symlink and needs a root `overrides`/
+ * `resolutions` pin instead. We can't fix that from `.blume/`, so we return a
+ * diagnostic naming the conflict rather than silently shipping a runtime that
+ * crashes downstream. Returns the warning, or null when nothing needs saying.
+ */
+export const ensureDepsLink = async (
+  outDir: string,
+  pkgDir: string = packageRoot()
+): Promise<string | null> => {
+  const depsDir = blumeDepsDir(pkgDir);
+  if (!depsDir) {
+    return null;
+  }
+  // Already correct when `.blume/` resolves the very same astro Blume's deps
+  // provide — the clean hoisted case, nothing to do.
+  const blumeAstro = resolvedAstroPath(depsDir);
+  const outDirAstro = resolvedAstroPath(outDir);
+  if (blumeAstro && outDirAstro === blumeAstro) {
+    return null;
+  }
+  // A co-located, consistent set (astro beside the @astrojs/mdx that binds to
+  // it) can be linked in wholesale; this repairs the unreachable and the
+  // repairable-conflict cases. Any existing link here is stale and gets
+  // replaced.
+  if (existsSync(join(depsDir, "@astrojs", "mdx"))) {
+    await linkDepsJunction(join(outDir, "node_modules"), depsDir);
+    return null;
+  }
+  // Split layout: Blume's astro is nested (a conflicting astro took the root
+  // spot) but @astrojs/mdx hoisted away from it, binding to the shadow. Only a
+  // root pin fixes this — surface it.
+  return astroConflictWarning(blumeAstro, outDirAstro);
+};
+
+/**
+ * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
+ * `@takumi-rs/core`, …) resolvable when Astro executes the static prerender
+ * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
+ *
+ * Astro's static build emits a self-contained SSR bundle to
+ * `<outDir>/.prerender/` and `import()`s it in-process to generate the HTML.
+ * That bundle externalizes Blume's render-time deps, so Node resolves them at
+ * prerender time by walking up from `.prerender/chunks/*.mjs`. {@link
+ * ensureDepsLink} only repairs resolution rooted at `.blume/`; `.prerender/`
+ * lives under `dist/`, a separate tree an isolated linker never hoists Blume's
+ * deps into — so the import dies with `Cannot find package 'zod'`. We drop the
+ * same `node_modules` junction into the prerender root, mirroring
+ * `.blume/node_modules`, so every externalized specifier — native bindings
+ * included, which can't be bundled — resolves. Astro deletes `.prerender/` once
+ * generation finishes (and the junction with it: `fs.rm` unlinks symlinks, it
+ * never follows them), so nothing leaks into the published `dist/`.
+ *
+ * Keyed off the output dir's basename (`.prerender`) — the name Astro 7 gives
+ * the prerender build for both static (`<outDir>/.prerender/`) and server
+ * (`<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()
+): {
+  name: string;
+  writeBundle: (options: { dir?: string }) => Promise<void>;
+} => ({
+  name: "blume:prerender-deps",
+  writeBundle: async (options) => {
+    if (!options.dir || basename(options.dir) !== ".prerender") {
+      return;
+    }
+    const depsDir = blumeDepsDir(pkgDir);
+    if (!depsDir) {
+      return;
+    }
+    await linkDepsJunction(join(options.dir, "node_modules"), depsDir);
+  },
+});
+
 /** Astro integration package each non-React island framework needs installed. */
 const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
   svelte: "@astrojs/svelte",
@@ -243,20 +417,12 @@ const writeStagedContent = async (
 };
 
 /** The logo shape the runtime consumes: an inline SVG or image URL(s). */
-interface ResolvedLogo {
-  svg?: string;
-  light?: string;
-  dark?: string;
-  alt: string;
-  href: 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
  * `<img>`. The file is looked up under `public/` and the project root.
  */
-const resolveLogo = (project: BlumeProject): ResolvedLogo | null => {
+const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   const { logo } = project.config;
   if (!logo) {
     return null;
@@ -280,12 +446,6 @@ const resolveLogo = (project: BlumeProject): ResolvedLogo | null => {
   return { alt, dark, href, light };
 };
 
-/** The favicon shape the runtime consumes: a link href plus optional MIME type. */
-interface ResolvedFavicon {
-  href: string;
-  type?: string;
-}
-
 /**
  * Favicon filenames Blume auto-detects, in priority order. Mirrors the Next.js
  * convention: an `icon.*` or `favicon.*` file in `public/` or the project root
@@ -303,6 +463,8 @@ 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",
 };
@@ -318,45 +480,67 @@ const inlineDataUri = (file: string, type: string): string =>
   `data:${type};base64,${readFileSync(file).toString("base64")}`;
 
 /** The bundled Blume favicon, inlined as a data URI so it needs no public file. */
-const defaultFavicon = (): ResolvedFavicon => ({
+const defaultFavicon = (): BlumeFavicon => ({
   href: inlineDataUri(join(BLUME_SRC, "assets", "icon.png"), "image/png"),
   type: "image/png",
 });
 
 /**
- * Resolve the site favicon by convention. An `icon.*`/`favicon.*` file in
- * `public/` is served as-is and referenced by URL; one at the project root is
- * inlined as a data URI (the root isn't a served directory). Falls back to the
- * bundled Blume mark when the project ships no icon.
+ * Apple touch icon filenames Blume auto-detects, in priority order. Mirrors the
+ * Next.js `apple-icon.*` convention (plus the `apple-touch-icon.png` most favicon
+ * generators emit): a match in `public/` or the project root becomes the iOS
+ * home-screen icon, no config required.
+ */
+const APPLE_ICON_CANDIDATES = [
+  "apple-icon.png",
+  "apple-icon.jpg",
+  "apple-icon.jpeg",
+  "apple-touch-icon.png",
+];
+
+/**
+ * Resolve an icon file by convention. A candidate in `public/` is served as-is
+ * and referenced by URL; one at the project root is inlined as a data URI (the
+ * root isn't a served directory). Returns null when the project ships none.
  */
-const resolveFavicon = (project: BlumeProject): ResolvedFavicon => {
+const resolveIconFile = (
+  project: BlumeProject,
+  candidates: string[]
+): BlumeFavicon | null => {
   const { root } = project.context;
-  for (const name of FAVICON_CANDIDATES) {
+  for (const name of candidates) {
     if (existsSync(join(root, "public", name))) {
       return { href: `/${name}`, type: faviconType(name) };
     }
   }
-  for (const name of FAVICON_CANDIDATES) {
+  for (const name of candidates) {
     const file = join(root, name);
     if (existsSync(file)) {
       const type = faviconType(name);
       return { href: inlineDataUri(file, type ?? "image/x-icon"), type };
     }
   }
-  return defaultFavicon();
+  return null;
 };
 
-/** The announcement banner shape the runtime consumes. */
-interface ResolvedBanner {
-  content: string;
-  link?: { href: string; text: string };
-  dismissible: boolean;
-  /** Dismissal key: the configured id, else the content itself. */
-  key: string;
-}
+/**
+ * Resolve the site favicon by convention, falling back to the bundled Blume mark
+ * when the project ships no `icon.*`/`favicon.*` file.
+ */
+const resolveFavicon = (project: BlumeProject): BlumeFavicon =>
+  resolveIconFile(project, FAVICON_CANDIDATES) ?? defaultFavicon();
+
+/**
+ * Resolve the Apple touch icon by convention, or null when the project ships
+ * none (unlike the favicon, there's no bundled default). Note: iOS ignores
+ * `data:`-URI apple-touch-icons, so a `public/` file (served by URL) is the
+ * reliable path; a root-level file is still inlined for symmetry with favicons.
+ */
+const resolveAppleIcon = (project: BlumeProject): BlumeFavicon | null =>
+  resolveIconFile(project, APPLE_ICON_CANDIDATES);
 
 /** Normalize the banner config (string shorthand or object) for the runtime. */
-const resolveBanner = (config: ResolvedConfig): ResolvedBanner | null => {
+const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   const { banner } = config;
   if (!banner) {
     return null;
@@ -436,9 +620,10 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       )
     : {};
 
-  const data = {
+  const data: BlumeData = {
     config: {
       analytics: config.analytics ?? null,
+      appleIcon: resolveAppleIcon(project),
       banner: resolveBanner(config),
       codeWrap: config.markdown.code.wrap,
       description: config.description,
@@ -463,7 +648,9 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       mcp: config.mcp.enabled
         ? { name: config.mcp.name ?? config.title, route: config.mcp.route }
         : null,
-      og: { enabled: config.seo.og.enabled },
+      // `og.enabled` is resolved to a definite boolean in `loadConfig`; coerce
+      // the optional schema type so the serialized shape stays `boolean`.
+      og: { enabled: config.seo.og.enabled ?? false },
       repoUrl,
       search: {
         enabled: config.search.provider !== "none",
@@ -619,6 +806,7 @@ export const generateRuntime = async (
   const dataPath = join(srcDir, "generated", "data.json");
   const themePath = join(srcDir, "generated", "app.css");
   const searchClientPath = join(srcDir, "generated", "search-client.ts");
+  const examplesPath = join(srcDir, "generated", "examples.ts");
 
   // Record every file this pass writes so orphans (from a now-disabled feature)
   // can be pruned afterwards. `write` wraps the atomic writer and tracks paths.
@@ -628,26 +816,36 @@ export const generateRuntime = async (
     return writeIfChanged(path, content);
   };
 
-  await ensureDepsLink(out);
+  const depsLinkWarning = await ensureDepsLink(out);
 
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
-  const [pages, detectedReact, userTheme, islandDiscovery] = await Promise.all([
-    context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
-    detectNeedsReact(context.root),
-    readOptional(context.themeFile),
-    discoverIslands(context.root),
+  const [pages, detectedReact, userTheme, islandDiscovery, exampleDiscovery] =
+    await Promise.all([
+      context.pagesRoot
+        ? discoverPages(context.pagesRoot)
+        : Promise.resolve([]),
+      detectNeedsReact(context.root),
+      readOptional(context.themeFile),
+      discoverIslands(context.root),
+      discoverExamples(context.root, config.examples),
+    ]);
+  // Each island/example framework enables its Astro renderer. React also
+  // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
+  // island/example-driven. `.astro` examples need no renderer.
+  const frameworks = new Set<string>([
+    ...islandDiscovery.islands.map((island) => island.framework),
+    ...exampleDiscovery.examples.map((example) => example.framework),
   ]);
-  // Each island's framework enables its Astro renderer. React also switches on
-  // for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are island-driven.
-  const islandFrameworks = new Set(
-    islandDiscovery.islands.map((island) => island.framework)
-  );
-  const needsReact =
-    detectedReact || askEnabled || islandFrameworks.has("react");
-  const needsVue = islandFrameworks.has("vue");
-  const needsSvelte = islandFrameworks.has("svelte");
+  const needsReact = detectedReact || askEnabled || frameworks.has("react");
+  const needsVue = frameworks.has("vue");
+  const needsSvelte = frameworks.has("svelte");
+
+  // 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
+  // private and filtered out anyway, but the intent is the user's pages.
+  const ogRoutes = customOgRoutes(pages, config.title, config.description);
 
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
@@ -664,10 +862,12 @@ export const generateRuntime = async (
     write(
       join(out, "astro.config.mjs"),
       astroConfigTemplate({
+        aliases: resolveTsconfigAliases(context.root),
         config,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context,
         dataPath,
+        examplesPath,
         needsReact,
         needsSvelte,
         needsVue,
@@ -705,6 +905,10 @@ export const generateRuntime = async (
       join(srcDir, "generated", "islands.ts"),
       islandMapTemplate(islandDiscovery.islands)
     ),
+    write(
+      join(srcDir, "generated", "examples.ts"),
+      exampleMapTemplate(exampleDiscovery.examples)
+    ),
     write(
       themePath,
       tailwindEntryTemplate({
@@ -731,6 +935,22 @@ export const generateRuntime = async (
     )
   );
 
+  // Per-example live wrappers for the `examples/` convention, resolved by
+  // `<Component path>` through the `examples.ts` map (written above, always).
+  await Promise.all(
+    exampleDiscovery.examples.map((example) =>
+      write(
+        join(
+          srcDir,
+          "generated",
+          "examples",
+          `${exampleSlug(example.path)}.astro`
+        ),
+        exampleWrapperTemplate(example)
+      )
+    )
+  );
+
   if (askEnabled) {
     await write(
       join(srcDir, "pages", "api", "ask.ts"),
@@ -743,7 +963,7 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate()
+      ogEndpointTemplate(ogRoutes)
     );
   }
 
@@ -827,7 +1047,12 @@ export const generateRuntime = async (
 
   // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
   // mounted on its configured route and regenerated each run.
-  const warnings: string[] = [...mcp.warnings, ...islandDiscovery.warnings];
+  const warnings: string[] = [
+    ...(depsLinkWarning ? [depsLinkWarning] : []),
+    ...mcp.warnings,
+    ...islandDiscovery.warnings,
+    ...exampleDiscovery.warnings,
+  ];
 
   // The new provider SDKs are optional peers; warn (rather than fail opaquely in
   // Vite) when the configured provider's package isn't installed.
@@ -841,7 +1066,7 @@ export const generateRuntime = async (
 
   // React ships with Blume; Vue/Svelte islands need their Astro integration
   // installed by the project. Warn early rather than let Vite fail to resolve it.
-  warnings.push(...islandFrameworkWarnings(islandFrameworks, context.root));
+  warnings.push(...islandFrameworkWarnings(frameworks, context.root));
   if (hasReferences(config)) {
     const references = await buildReferenceFiles({
       config,

package/src/astro/index.ts

@@ -1,4 +1,4 @@
-export { generateRuntime } from "./generate.ts";
+export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
 export type { GenerateResult } from "./generate.ts";
 export { blumeIntegration } from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";

package/src/astro/islands.ts

@@ -53,7 +53,7 @@ const ISLAND_FILE = /\.(?<ext>jsx|svelte|tsx|vue)$/u;
 const CLIENT_EXPORT =
   /export\s+const\s+client\s*(?::[^=]+)?=\s*["'](?<mode>\w+)["']/u;
 
-const readClientMode = (
+export const readClientMode = (
   source: string,
   file: string,
   warnings: string[]

package/src/astro/pages.ts

@@ -26,3 +26,62 @@ export const discoverPages = async (
     return { entrypoint: file, pattern };
   });
 };
+
+/** A custom-page route that should get a generated OG card. */
+export interface OgCustomRoute {
+  /** `og/<slug>.png` path segment; `index` for the site root. */
+  slug: string;
+  /** Card title. */
+  title: string;
+  /** Small eyebrow line above the title. */
+  eyebrow?: string;
+}
+
+/** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
+const PRIVATE_SEGMENT = /^[._]/u;
+
+const humanizeSegment = (segment: string): string =>
+  segment
+    .split(/[-_]/u)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+/**
+ * Pick the custom-page routes that should get a generated Open Graph card, with
+ * the card's slug and text. OG is otherwise content-route only, so a custom page
+ * — most importantly the landing `/`, the most-shared URL — would have no card.
+ *
+ * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
+ * are skipped: they aren't shareable pages. The home is titled with the site
+ * title (eyebrow: the site description); a deeper page is titled from its last
+ * path segment.
+ */
+export const customOgRoutes = (
+  pages: BlumePageRoute[],
+  siteTitle: string,
+  siteDescription?: string
+): OgCustomRoute[] => {
+  const seen = new Set<string>();
+  const routes: OgCustomRoute[] = [];
+  for (const { pattern } of pages) {
+    const segments = pattern.split("/").filter(Boolean);
+    if (
+      segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))
+    ) {
+      continue;
+    }
+    const slug = segments.length === 0 ? "index" : segments.join("/");
+    if (seen.has(slug)) {
+      continue;
+    }
+    seen.add(slug);
+    const last = segments.at(-1);
+    routes.push(
+      last
+        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
+        : { eyebrow: siteDescription, slug, title: siteTitle }
+    );
+  }
+  return routes;
+};