blume 0.2.0 → 0.3.0

package/src/migrate/mintlify/config.ts

@@ -579,72 +579,6 @@ const mintlifySelectors = (spec: JsonObject): NavigationSelectors => {
   ].filter((selector) => selector.items.length > 0);
 };
 
-const navbarTypeLabel = (type: string | undefined): string | undefined => {
-  if (type === "github") {
-    return "GitHub";
-  }
-  if (type === "discord") {
-    return "Discord";
-  }
-  return undefined;
-};
-
-const navbarLinkType = (
-  type: string | undefined
-): "github" | "discord" | undefined =>
-  type === "github" || type === "discord" ? type : undefined;
-
-const navbarPrimaryType = (
-  type: string | undefined
-): "button" | "github" | "discord" =>
-  type === "github" || type === "discord" ? type : "button";
-
-const mintlifyNavbar = (value: unknown): NonNullable<BlumeConfig["navbar"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { links: [] };
-  }
-
-  const links = asArray(object.links).flatMap((item) => {
-    const itemObject = asObject(item);
-    const href = itemObject ? asString(itemObject.href) : undefined;
-    const type = itemObject ? asString(itemObject.type) : undefined;
-    const label = itemObject
-      ? (asString(itemObject.label) ?? navbarTypeLabel(type))
-      : undefined;
-    if (!itemObject || !href || !label) {
-      return [];
-    }
-    return [
-      withoutUndefined({
-        href,
-        icon: asString(itemObject.icon),
-        label,
-        type: navbarLinkType(type),
-      }),
-    ];
-  });
-
-  const primaryObject = asObject(object.primary);
-  const primaryHref = primaryObject ? asString(primaryObject.href) : undefined;
-  const primaryType = primaryObject
-    ? (asString(primaryObject.type) ?? "button")
-    : undefined;
-  const primaryLabel = primaryObject
-    ? (asString(primaryObject.label) ?? navbarTypeLabel(primaryType))
-    : undefined;
-  const primary =
-    primaryObject && primaryHref && primaryLabel
-      ? withoutUndefined({
-          href: primaryHref,
-          label: primaryLabel,
-          type: navbarPrimaryType(primaryType),
-        })
-      : undefined;
-
-  return withoutUndefined({ links, primary });
-};
-
 const mintignorePatterns = async (root: string): Promise<string[]> => {
   try {
     const raw = await readFile(resolve(root, ".mintignore"), "utf-8");
@@ -678,78 +612,6 @@ const mintlifyRedirects = (
     return [{ from, to }];
   });
 
-const mintlifyContextual = (
-  value: unknown
-): NonNullable<BlumeConfig["contextual"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { options: [] };
-  }
-
-  const display = object.display === "toc" ? "toc" : "header";
-  const options: NonNullable<BlumeConfig["contextual"]>["options"] = [];
-  for (const option of asArray(object.options)) {
-    if (typeof option === "string") {
-      options.push(option);
-      continue;
-    }
-
-    const optionObject = asObject(option);
-    const title = optionObject ? asString(optionObject.title) : undefined;
-    if (!optionObject || !title) {
-      continue;
-    }
-
-    options.push(
-      withoutUndefined({
-        description: asString(optionObject.description),
-        href: asString(optionObject.href),
-        icon: asString(optionObject.icon),
-        title,
-      })
-    );
-  }
-
-  return { display, options };
-};
-
-const mintlifyFooter = (value: unknown): NonNullable<BlumeConfig["footer"]> => {
-  const object = asObject(value);
-  const socials = asObject(object?.socials);
-  const links = asArray(object?.links)
-    .flatMap((group) => {
-      const groupObject = asObject(group);
-      const items = asArray(groupObject?.items).flatMap((item) => {
-        const itemObject = asObject(item);
-        const label = itemObject ? asString(itemObject.label) : undefined;
-        const href = itemObject ? asString(itemObject.href) : undefined;
-        return label && href ? [{ href, label }] : [];
-      });
-      if (!groupObject || items.length === 0) {
-        return [];
-      }
-      return [
-        withoutUndefined({
-          header: asString(groupObject.header),
-          items,
-        }),
-      ];
-    })
-    .slice(0, 4);
-
-  return {
-    links,
-    socials: socials
-      ? Object.fromEntries(
-          Object.entries(socials).flatMap(([label, href]) => {
-            const hrefValue = asString(href);
-            return hrefValue ? [[label, hrefValue]] : [];
-          })
-        )
-      : {},
-  };
-};
-
 const mintlifyLogo = (value: unknown): BlumeConfig["logo"] => {
   if (typeof value === "string") {
     return value;
@@ -826,21 +688,13 @@ const mintlifyChromeVariants = (spec: JsonObject): NavigationChromeVariants => {
     const banner = hasOwn(object, "banner")
       ? mintlifyBanner(object.banner)
       : undefined;
-    const footer = hasOwn(object, "footer")
-      ? mintlifyFooter(object.footer)
-      : undefined;
-    const navbar = hasOwn(object, "navbar")
-      ? mintlifyNavbar(object.navbar)
-      : undefined;
-    if (!banner && !footer && !navbar) {
+    if (!banner) {
       return [];
     }
 
     return [
       withoutUndefined({
         banner,
-        footer,
-        navbar,
         path,
       }),
     ];
@@ -914,19 +768,6 @@ const mintlifyMarkdown = (
   });
 };
 
-const mintlifyStyling = (
-  value: unknown
-): NonNullable<BlumeConfig["styling"]> => {
-  const object = asObject(value);
-  const eyebrows = asString(object?.eyebrows);
-  return withoutUndefined({
-    eyebrows:
-      eyebrows === "breadcrumbs" || eyebrows === "section"
-        ? eyebrows
-        : undefined,
-  });
-};
-
 const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -942,17 +783,6 @@ const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   };
 };
 
-const mintlifyIcons = (value: unknown): NonNullable<BlumeConfig["icons"]> => {
-  const object = asObject(value);
-  const library = object?.library;
-  return withoutUndefined({
-    library:
-      library === "fontawesome" || library === "lucide" || library === "tabler"
-        ? library
-        : undefined,
-  });
-};
-
 export const loadMintlifyConfig = async (
   root: string,
   file: string
@@ -993,14 +823,10 @@ export const loadMintlifyConfig = async (
       ],
       root: ".",
     },
-    contextual: mintlifyContextual(spec.contextual),
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
-    footer: mintlifyFooter(spec.footer),
-    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
-    navbar: mintlifyNavbar(spec.navbar),
     navigation: {
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
@@ -1016,7 +842,6 @@ export const loadMintlifyConfig = async (
       prompt: asString(search.prompt),
     },
     seo: mintlifySeo(seo),
-    styling: mintlifyStyling(styling),
     theme: {
       accent: asString(colors.primary) ?? "blue",
       accentDark: asString(colors.light),

package/src/migrate/starlight/config.ts

@@ -425,10 +425,6 @@ export const mapStarlightConfig = (
   }
 
   const social = mapSocial(options.social);
-  if (Object.keys(social.socials).length > 0) {
-    config.footer = { socials: social.socials };
-  }
-
   const github = mapEditLink(options.editLink) ?? social.github;
   if (github) {
     config.github = github;

package/src/og/card.ts

@@ -1,5 +1,6 @@
 import { Renderer } from "@takumi-rs/core";
-import { container, text } from "@takumi-rs/helpers";
+import { container, image, text } from "@takumi-rs/helpers";
+import type { Node } from "@takumi-rs/helpers";
 
 // Reuse one renderer (and its loaded default fonts) across all images.
 let renderer: Renderer | null = null;
@@ -24,62 +25,186 @@ const resolveAccent = (accent: string): string =>
   ACCENT_HEX[accent] ?? (accent.startsWith("#") ? accent : "#3b82f6");
 
 export interface OgCardOptions {
+  /** Large headline — the page title. */
   title: string;
-  eyebrow?: string;
+  /** Accent color (named preset or hex) for the fallback brand mark. */
   accent?: string;
+  /** Brand/site name shown in the top-left lockup. */
+  brand?: string;
+  /** Muted subtitle under the headline (usually the site description). */
+  description?: string;
+  /**
+   * Inlined SVG markup of the configured logo (`config.logo.svg`), painted into
+   * the brand lockup. Falls back to an accent mark when absent.
+   */
+  logo?: string;
+  /** Footer-left repository slug, e.g. `owner/repo`. */
+  repo?: string;
+  /** Footer-right site host, e.g. `docs.acme.com`. */
+  site?: string;
 }
 
 const WIDTH = 1200;
 const HEIGHT = 630;
 
+// Light neutral scale mirrored from the docs homepage theme tokens:
+// FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,
+// BORDER = --border.
+const BG = "#fafafa";
+const FOREGROUND = "#0a0a0a";
+const MUTED = "#737373";
+const FAINT = "#a3a3a3";
+const BORDER = "#e5e5e5";
+
+const truncate = (value: string, max: number): string =>
+  value.length > max ? `${value.slice(0, max - 1).trimEnd()}…` : value;
+
+// Brand mark sizing: target this height, but scale down so a wide wordmark logo
+// stays within the lockup.
+const MARK_HEIGHT = 32;
+const MARK_MAX_WIDTH = 100;
+const VIEW_BOX = /viewBox="0 0 (?<w>[\d.]+) (?<h>[\d.]+)"/u;
+
+// Render the configured logo as the brand mark. A `currentColor` logo carries
+// no intrinsic color, so it is painted in the foreground to read on the light
+// card, then handed to Takumi as a data URI sized from the SVG's aspect ratio.
+const logoMark = (svg: string): Node => {
+  const painted = svg.replaceAll("currentColor", FOREGROUND);
+  const box = painted.match(VIEW_BOX);
+  const w = Number(box?.groups?.w);
+  const h = Number(box?.groups?.h);
+  let height = MARK_HEIGHT;
+  let width = w && h ? (MARK_HEIGHT * w) / h : MARK_HEIGHT;
+  if (width > MARK_MAX_WIDTH) {
+    height = w && h ? (MARK_MAX_WIDTH * h) / w : MARK_HEIGHT;
+    width = MARK_MAX_WIDTH;
+  }
+  return image({
+    height: Math.round(height),
+    src: `data:image/svg+xml;base64,${Buffer.from(painted).toString("base64")}`,
+    width: Math.round(width),
+  });
+};
+
+// Fallback mark when no SVG logo is configured: an accent tile with the brand's
+// initial, matching the docs favicon aesthetic.
+const initialMark = (accent: string, initial: string): Node =>
+  container({
+    children: initial
+      ? [text(initial, { color: "#ffffff", fontSize: 32, fontWeight: 600 })]
+      : [],
+    style: {
+      alignItems: "center",
+      backgroundColor: accent,
+      borderRadius: 14,
+      display: "flex",
+      height: 60,
+      justifyContent: "center",
+      width: 60,
+    },
+  });
+
+// The headline shrinks as the title grows so it never spills past a couple of
+// lines within the card's content width.
+const titleSize = (title: string): number => {
+  if (title.length > 60) {
+    return 52;
+  }
+  if (title.length > 40) {
+    return 64;
+  }
+  return 76;
+};
+
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const accent = resolveAccent(options.accent ?? "blue");
+  const brand = options.brand?.trim();
+  const logo = options.logo?.trim();
+  const initial = brand ? brand.charAt(0).toUpperCase() : "";
+  const description = options.description?.trim();
+  const repo = options.repo?.trim();
+  const site = options.site?.trim();
 
-  const node = container({
+  const header = container({
     children: [
-      container({
-        children: [
-          container({
-            style: {
-              backgroundColor: accent,
-              borderRadius: 6,
-              height: 32,
-              width: 32,
-            },
-          }),
-          options.eyebrow
-            ? text(options.eyebrow, {
-                color: "#94a3b8",
-                fontSize: 30,
-              })
-            : container({}),
-        ],
-        style: { alignItems: "center", display: "flex", gap: 16 },
-      }),
-      text(options.title, {
-        color: "#f8fafc",
-        fontSize: 76,
-        fontWeight: 700,
-        lineHeight: 1.1,
-      }),
-      container({
-        style: {
-          backgroundColor: accent,
-          borderRadius: 4,
-          height: 8,
-          width: 120,
-        },
+      logo ? logoMark(logo) : initialMark(accent, initial),
+      brand
+        ? text(brand, {
+            color: FOREGROUND,
+            fontSize: 30,
+            fontWeight: 500,
+            letterSpacing: "-0.01em",
+          })
+        : container({}),
+    ],
+    style: { alignItems: "center", display: "flex", gap: 18 },
+  });
+
+  const body = container({
+    children: [
+      text(truncate(options.title, 64), {
+        color: FOREGROUND,
+        fontSize: titleSize(options.title),
+        fontWeight: 600,
+        letterSpacing: "-0.03em",
+        lineHeight: 1.05,
+        maxWidth: 1010,
+        textWrap: "balance",
       }),
+      description
+        ? text(truncate(description, 140), {
+            color: MUTED,
+            fontSize: 30,
+            lineHeight: 1.4,
+            marginTop: 28,
+            maxWidth: 900,
+            textWrap: "balance",
+          })
+        : container({}),
     ],
+    style: { display: "flex", flexDirection: "column" },
+  });
+
+  const footer =
+    repo || site
+      ? container({
+          children: [
+            container({
+              style: { backgroundColor: BORDER, height: 1, width: "100%" },
+            }),
+            container({
+              children: [
+                repo
+                  ? text(repo, { color: MUTED, fontSize: 22 })
+                  : container({}),
+                site
+                  ? text(site, { color: FAINT, fontSize: 22 })
+                  : container({}),
+              ],
+              style: {
+                alignItems: "center",
+                display: "flex",
+                justifyContent: "space-between",
+                marginTop: 28,
+                width: "100%",
+              },
+            }),
+          ],
+          style: { display: "flex", flexDirection: "column", width: "100%" },
+        })
+      : container({});
+
+  const node = container({
+    children: [header, body, footer],
     style: {
-      backgroundColor: "#0b1020",
-      color: "#ffffff",
+      backgroundColor: BG,
+      color: FOREGROUND,
       display: "flex",
       flexDirection: "column",
       height: HEIGHT,
       justifyContent: "space-between",
-      padding: 80,
+      padding: 72,
       width: WIDTH,
     },
   });

package/src/registry/eject.ts

@@ -3,8 +3,10 @@ import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 
 import { join, relative } from "pathe";
 
+import { buildAskData } from "../ai/ask-data.ts";
 import { resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown } from "../ai/markdown.ts";
+import { planComponentSlots } from "../astro/component-slots.ts";
 import { discoverExamples } from "../astro/examples.ts";
 import {
   buildRuntimeData,
@@ -32,9 +34,9 @@ import {
   runtimeTsconfigTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
-  userComponentsTemplate,
 } from "../astro/templates.ts";
 import { scanProject } from "../core/project-graph.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import { buildReferenceFiles, hasReferences } from "../openapi/scalar.ts";
@@ -46,6 +48,35 @@ import { twoslashCss } from "../theme/twoslash.ts";
 
 const POSIX = (path: string): string => path.split("\\").join("/");
 
+/**
+ * The Ask AI endpoint plus, unless the backend runs its own retrieval (Inkeep),
+ * its grounding snapshot. Empty when Ask AI is disabled.
+ */
+const askFiles = async (
+  project: BlumeProject,
+  srcDir: string,
+  genDir: string
+): Promise<{ content: string; path: string }[]> => {
+  const { ask } = project.config.ai;
+  if (!ask?.enabled) {
+    return [];
+  }
+  const grounded = ask.provider !== "inkeep";
+  const files = [
+    {
+      content: askEndpointTemplate(resolveAskBackend(ask), grounded),
+      path: join(srcDir, "pages", "api", "ask.ts"),
+    },
+  ];
+  if (grounded) {
+    files.push({
+      content: `${JSON.stringify(await buildAskData(project))}\n`,
+      path: join(genDir, "ask-data.json"),
+    });
+  }
+  return files;
+};
+
 /**
  * Promote the generated runtime into the project as an owned Astro app. After
  * eject the project has a normal `astro.config.mjs` and `src/`, the `blume` CLI
@@ -146,11 +177,15 @@ export const eject = async (root: string): Promise<string[]> => {
         exportEpub,
         exportPdf,
         mathEnabled: config.markdown.math,
+        needsReact,
       }),
       path: join(srcDir, "pages", "[...slug].astro"),
     },
     {
-      content: userComponentsTemplate(componentsImport),
+      // Eject keeps the portable re-export form (relative import to the user's
+      // components file); hydration/island wrappers would need machine-specific
+      // absolute paths, so the ejected app owns and wires those itself.
+      content: planComponentSlots(componentsImport, null).module,
       path: join(genDir, "components.ts"),
     },
     // Island/example maps the catch-all imports; written even when empty so the
@@ -192,17 +227,12 @@ export const eject = async (root: string): Promise<string[]> => {
   ];
 
   if (askEnabled) {
-    files.push({
-      content: askEndpointTemplate(resolveAskBackend(config.ai.ask)),
-      path: join(srcDir, "pages", "api", "ask.ts"),
-    });
+    files.push(...(await askFiles(project, srcDir, genDir)));
   }
 
   if (config.seo.og.enabled) {
     files.push({
-      content: ogEndpointTemplate(
-        customOgRoutes(pages, config.title, config.description)
-      ),
+      content: ogEndpointTemplate(customOgRoutes(pages, config.title)),
       path: join(srcDir, "pages", "og", "[...slug].png.ts"),
     });
   }