blume 0.2.0 → 0.4.0

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,198 @@ 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";
+
+/**
+ * Truncate to `max` code points with an ellipsis. Slices by code points, not
+ * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
+ * glyph) before the ellipsis.
+ */
+export const truncate = (value: string, max: number): string => {
+  const chars = [...value];
+  return chars.length > max
+    ? `${chars
+        .slice(0, max - 1)
+        .join("")
+        .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
@@ -109,7 +140,12 @@ export const eject = async (root: string): Promise<string[]> => {
   const hasStaged = staged.size > 0;
   const stagedDir = "blume-staged";
 
-  const files: { path: string; content: string }[] = [
+  const files: {
+    path: string;
+    content: string;
+    /** Don't overwrite a file the user already owns (e.g. a tuned tsconfig). */
+    skipIfExists?: boolean;
+  }[] = [
     {
       content: astroConfigTemplate({
         config,
@@ -129,6 +165,8 @@ export const eject = async (root: string): Promise<string[]> => {
     {
       content: runtimeTsconfigTemplate(),
       path: join(root, "tsconfig.json"),
+      // Never clobber a hand-tuned tsconfig; only write ours if none exists.
+      skipIfExists: true,
     },
     { content: envTemplate(), path: join(srcDir, "env.d.ts") },
     {
@@ -146,11 +184,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 +234,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"),
     });
   }
@@ -297,8 +334,11 @@ export const eject = async (root: string): Promise<string[]> => {
     files.push({ content, path: join(root, stagedDir, entryId) });
   }
 
+  const written = files.filter(
+    (file) => !(file.skipIfExists && existsSync(file.path))
+  );
   await Promise.all(
-    files.map(async (file) => {
+    written.map(async (file) => {
       await mkdir(join(file.path, ".."), { recursive: true });
       await writeFile(file.path, file.content, "utf-8");
     })
@@ -317,5 +357,5 @@ export const eject = async (root: string): Promise<string[]> => {
   // The hidden runtime is no longer the source of truth.
   await rm(context.outDir, { force: true, recursive: true });
 
-  return files.map((file) => file.path);
+  return written.map((file) => file.path);
 };

package/src/registry/registry.ts

@@ -62,6 +62,171 @@ const layoutComponent = (config: {
   };
 };
 
+/**
+ * A built-in MDX content component offered as editable source. Like
+ * {@link layoutComponent}, but registered under the `mdx` map (the tag you write
+ * in `.mdx`) rather than a `layout` slot.
+ */
+const contentComponent = (config: {
+  name: string;
+  description: string;
+  /** Source basename under `src/components/content`. */
+  file: string;
+  /** MDX tag / component name, also the import name in the post-install hint. */
+  tag: string;
+}): RegistryItem => {
+  const target = `components/blume/${config.file}`;
+  return {
+    description: config.description,
+    files: [
+      {
+        rewrite: true,
+        source: `components/content/${config.file}`,
+        target,
+      },
+    ],
+    name: config.name,
+    postInstall: [
+      "Register it in components.ts:",
+      '  import { defineComponents } from "blume";',
+      `  import ${config.tag} from "./${target}";`,
+      "",
+      `  export default defineComponents({ mdx: { ${config.tag} } });`,
+      "",
+      "It imports the rest from `blume/*`, so it matches the built-in until you edit it.",
+    ],
+  };
+};
+
+/** Every user-facing content component, by `blume add` name → source basename. */
+const CONTENT_COMPONENTS: {
+  name: string;
+  description: string;
+  file: string;
+  tag: string;
+}[] = [
+  {
+    description: "Aside for notes, tips, and warnings.",
+    file: "Callout.astro",
+    name: "callout",
+    tag: "Callout",
+  },
+  {
+    description: "A linkable card with icon, title, and body.",
+    file: "Card.astro",
+    name: "card",
+    tag: "Card",
+  },
+  {
+    description: "A responsive grid of cards.",
+    file: "CardGroup.astro",
+    name: "card-group",
+    tag: "CardGroup",
+  },
+  {
+    description: "Tabbed code blocks for multiple languages.",
+    file: "CodeGroup.astro",
+    name: "code-group",
+    tag: "CodeGroup",
+  },
+  {
+    description: "A small status/label badge.",
+    file: "Badge.astro",
+    name: "badge",
+    tag: "Badge",
+  },
+  {
+    description: "A numbered list of steps.",
+    file: "Steps.astro",
+    name: "steps",
+    tag: "Steps",
+  },
+  {
+    description: "A single step within Steps.",
+    file: "Step.astro",
+    name: "step",
+    tag: "Step",
+  },
+  {
+    description: "A tabbed content panel.",
+    file: "Tabs.astro",
+    name: "tabs",
+    tag: "Tabs",
+  },
+  {
+    description: "A single tab within Tabs.",
+    file: "Tab.astro",
+    name: "tab",
+    tag: "Tab",
+  },
+  {
+    description: "A collapsible accordion group.",
+    file: "Accordion.astro",
+    name: "accordion",
+    tag: "Accordion",
+  },
+  {
+    description: "A single item within an Accordion.",
+    file: "AccordionItem.astro",
+    name: "accordion-item",
+    tag: "AccordionItem",
+  },
+  {
+    description: "A multi-column layout.",
+    file: "Columns.astro",
+    name: "columns",
+    tag: "Columns",
+  },
+  {
+    description: "A single column within Columns.",
+    file: "Column.astro",
+    name: "column",
+    tag: "Column",
+  },
+  {
+    description: "A bordered frame around an image or embed.",
+    file: "Frame.astro",
+    name: "frame",
+    tag: "Frame",
+  },
+  {
+    description: "An inline expand/collapse disclosure.",
+    file: "Expandable.astro",
+    name: "expandable",
+    tag: "Expandable",
+  },
+  {
+    description: "A titled content panel.",
+    file: "Panel.astro",
+    name: "panel",
+    tag: "Panel",
+  },
+  {
+    description: "A hover tooltip.",
+    file: "Tooltip.astro",
+    name: "tooltip",
+    tag: "Tooltip",
+  },
+  {
+    description: "A compact linkable tile.",
+    file: "Tile.astro",
+    name: "tile",
+    tag: "Tile",
+  },
+  {
+    description: "A styled prompt / terminal block.",
+    file: "Prompt.astro",
+    name: "prompt",
+    tag: "Prompt",
+  },
+  {
+    description: "A responsive, privacy-friendly YouTube embed.",
+    file: "YouTube.astro",
+    name: "youtube",
+    tag: "YouTube",
+  },
+];
+
 /** The built-in, Blume-owned source registry. */
 export const registry: RegistryItem[] = [
   layoutComponent({
@@ -94,6 +259,13 @@ export const registry: RegistryItem[] = [
     name: "pagination",
     slot: "Pagination",
   }),
+  layoutComponent({
+    description: 'The "Was this page helpful?" feedback rating.',
+    file: "PageFeedback.astro",
+    name: "feedback",
+    slot: "Feedback",
+  }),
+  ...CONTENT_COMPONENTS.map(contentComponent),
 ];
 
 export const findItem = (name: string): RegistryItem | undefined =>

package/src/registry/rewrite-imports.ts

@@ -1,10 +1,16 @@
 import { dirname, relative, resolve } from "pathe";
 
-// The module specifier in `... from "<spec>"` and side-effect `import "<spec>"`,
-// limited to relative specifiers (those starting with `.`). Capturing the
-// keyword, gap, and quote lets us rebuild the statement verbatim.
-const RELATIVE_IMPORT =
-  /(?<kw>\bfrom|\bimport)(?<gap>\s+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gu;
+// A relative specifier (starting with `.`) in an `import … from "…"` or
+// `export … from "…"` statement. Anchored to the start of a line (`m` flag) and
+// bounded by `[^;]` so it only matches a real statement — not a `from "./…"`
+// that happens to appear inside a string or JSX text — while still allowing a
+// multiline import body between the keyword and `from`.
+const FROM_IMPORT =
+  /(?<prefix>^[ \t]*(?:import|export)\b[^;]*?\bfrom[ \t]*)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
+
+// A side-effect `import "./…"` at the start of a line.
+const SIDE_EFFECT_IMPORT =
+  /(?<prefix>^[ \t]*import[ \t]+)(?<quote>["'])(?<spec>\.[^"']*)\k<quote>/gmu;
 
 /**
  * Rewrite a built-in component's relative imports to `blume/*` package
@@ -22,18 +28,24 @@ export const rewriteImports = (
   content: string,
   sourceFile: string,
   srcRoot: string
-): string =>
-  content.replaceAll(
-    RELATIVE_IMPORT,
-    (match, kw: string, gap: string, quote: string, spec: string) => {
-      const resolved = resolve(dirname(sourceFile), spec);
-      if (resolved === sourceFile) {
-        return match;
-      }
-      const rel = relative(srcRoot, resolved);
-      if (rel.startsWith("..")) {
-        return match;
-      }
-      return `${kw}${gap}${quote}blume/${rel}${quote}`;
+): string => {
+  const rewrite = (
+    match: string,
+    prefix: string,
+    quote: string,
+    spec: string
+  ): string => {
+    const resolved = resolve(dirname(sourceFile), spec);
+    if (resolved === sourceFile) {
+      return match;
+    }
+    const rel = relative(srcRoot, resolved);
+    if (rel.startsWith("..")) {
+      return match;
     }
-  );
+    return `${prefix}${quote}blume/${rel}${quote}`;
+  };
+  return content
+    .replaceAll(FROM_IMPORT, rewrite)
+    .replaceAll(SIDE_EFFECT_IMPORT, rewrite);
+};

package/src/runtime/index.ts

@@ -5,6 +5,14 @@
  * (config, navigation, page collections) without reaching into generated
  * runtime internals. The surface grows with the customization milestone.
  */
+import type { BlumeData, BlumeRoute } from "../core/data.ts";
+
+export type {
+  BlumeData,
+  BlumeDataConfig,
+  BlumeFeed,
+  BlumeRoute,
+} from "../core/data.ts";
 export type {
   Heading,
   NavNode,
@@ -12,3 +20,56 @@ export type {
   NavTab,
   PageRecord,
 } from "../core/types.ts";
+
+/** Query for {@link getBlumeCollection}. */
+export interface BlumeCollectionQuery {
+  /** Astro collection to read from. Defaults to `"docs"`. */
+  collection?: string;
+  /** Include drafts, hidden pages, and translation fallbacks. Default `false`. */
+  includeHidden?: boolean;
+  /** Restrict to a locale code (matches `route.locale`). */
+  locale?: string;
+  /** Restrict to routes whose path starts with this prefix, e.g. `"/blog"`. */
+  prefix?: string;
+}
+
+/**
+ * Select content routes from the `blume:data` snapshot — for building custom
+ * index pages, listings, or feeds without touching generated internals. Pass the
+ * imported `data` and an optional query; results are sorted by path.
+ *
+ * ```astro
+ * ---
+ * import data from "blume:data";
+ * import { getBlumeCollection } from "blume/runtime";
+ * const posts = getBlumeCollection(data, { prefix: "/blog" });
+ * ---
+ * <ul>{posts.map((p) => <li><a href={p.path}>{p.title}</a></li>)}</ul>
+ * ```
+ */
+export const getBlumeCollection = (
+  data: BlumeData,
+  query: BlumeCollectionQuery = {}
+): BlumeRoute[] => {
+  const collection = query.collection ?? "docs";
+  return data.routes
+    .filter((route) => {
+      if (route.collection !== collection) {
+        return false;
+      }
+      if (query.locale && route.locale !== query.locale) {
+        return false;
+      }
+      if (query.prefix && !route.path.startsWith(query.prefix)) {
+        return false;
+      }
+      if (
+        !query.includeHidden &&
+        (route.draft || route.hidden || route.fallback)
+      ) {
+        return false;
+      }
+      return true;
+    })
+    .toSorted((a, b) => a.path.localeCompare(b.path));
+};