blume 0.1.5 → 0.3.0

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"),
     });
   }

package/src/registry/registry.ts

@@ -62,6 +62,165 @@ 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",
+  },
+];
+
 /** The built-in, Blume-owned source registry. */
 export const registry: RegistryItem[] = [
   layoutComponent({
@@ -94,6 +253,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/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));
+};

package/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+// Ambient types for the Vite `import.meta.env` fields Blume's client islands read
+// (`.astro` files aren't typechecked, so only real `.ts`/`.tsx` sources need this).
+interface ImportMetaEnv {
+  /** Deployment base path, always with a trailing slash (e.g. `/` or `/docs/`). */
+  readonly BASE_URL: string;
+  readonly DEV: boolean;
+  readonly MODE: string;
+  readonly PROD: boolean;
+  readonly SSR: boolean;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/docs/changelog/v0-1-0.mdx

@@ -1,12 +0,0 @@
----
-title: v0.1.0
-type: changelog
-date: 2026-06-01
-changelog:
-  version: 0.1.0
-  category: Release
----
-
-The first public release of Blume — a markdown-first docs framework on Astro and
-Vite. Drop in Markdown or MDX, run `blume dev`, and ship a production-grade docs
-site with search, theming, and AI-ready output.

package/docs/changelog/v0-2-0.mdx

@@ -1,16 +0,0 @@
----
-title: v0.2.0
-type: changelog
-date: 2026-06-24
-changelog:
-  version: 0.2.0
-  category: Features
----
-
-A big batch of built-in components landed: **columns**, **frames**, **trees**,
-**tooltips**, **code groups**, **panels**, **tiles**, and **fields**. Code groups
-now render as proper language tabs, and the changelog gets this timeline.
-
-- New `Accordion` / `AccordionItem`, `Expandable`, `Tooltip`, `Frame`, `Color`
-- `CodeGroup` tabs with flush code blocks
-- Redesigned `Prompt` with a copy-to-clipboard button