blume 0.4.0 → 0.5.0

package/src/openapi/render-mdx.ts

@@ -0,0 +1,76 @@
+import type { ApiOperationRef, ApiSpecData } from "./model.ts";
+
+/**
+ * Lower a parsed spec into MDX for the staged content source. Each operation and
+ * the spec overview become a thin MDX page: the frontmatter carries the
+ * searchable `title` (so operations flow into Blume's search, OG, and llms.txt),
+ * the operation/overview **description is emitted as markdown in the body** so it
+ * renders parsed (links, formatting) and is indexed, and the structured UI is
+ * deferred to a Blume-owned component (`<Operation>` / `<ApiOverview>`). The
+ * catch-all renders the frontmatter title as the page `<h1>`, so the components
+ * omit their own top heading.
+ */
+
+// Neutralize the few characters MDX treats specially (`{` expressions, `<` JSX)
+// so an arbitrary spec description can be embedded in the body verbatim without
+// breaking compilation. They render as their literal selves.
+const MDX_UNSAFE = /[<>{}]/gu;
+const ENTITIES: Record<string, string> = {
+  "<": "&lt;",
+  ">": "&gt;",
+  "{": "&#123;",
+  "}": "&#125;",
+};
+const mdxSafe = (text: string): string =>
+  text.replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char);
+
+/** Frontmatter + body for one operation or overview page. */
+export interface RenderedPage {
+  data: Record<string, unknown>;
+  body: string;
+}
+
+/** Prepend a markdown description (if any) above a component invocation. */
+const withDescription = (description: string, component: string): string =>
+  description.trim()
+    ? `${mdxSafe(description.trim())}\n\n${component}`
+    : component;
+
+export const operationMdx = (
+  spec: ApiSpecData,
+  operation: ApiOperationRef
+): RenderedPage => {
+  const method = operation.method.toUpperCase();
+  const title = operation.summary || `${method} ${operation.path}`;
+  // Skip the body description when it only repeats the summary (the `<h1>`) —
+  // common in specs that set summary and description to the same string.
+  const description =
+    operation.description.trim() === operation.summary.trim()
+      ? ""
+      : operation.description;
+  return {
+    body: withDescription(
+      description,
+      `<Operation source="${spec.slug}" id="${operation.key}" />`
+    ),
+    data: {
+      ...(operation.deprecated ? { deprecated: true } : {}),
+      search: { tags: [operation.tag, method] },
+      sidebar: { badge: method, label: operation.summary || operation.path },
+      title,
+      // Signals the two-column API layout (request panel instead of the TOC).
+      type: "openapi-operation",
+    },
+  };
+};
+
+export const overviewMdx = (spec: ApiSpecData): RenderedPage => ({
+  body: withDescription(
+    spec.description,
+    `<ApiOverview source="${spec.slug}" />`
+  ),
+  data: {
+    sidebar: { label: "Overview" },
+    title: spec.title || spec.label,
+  },
+});

package/src/openapi/scalar.ts

@@ -4,32 +4,19 @@ import { isAbsolute, join } from "pathe";
 
 import { scalarReferenceTemplate } from "../astro/templates.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
-import type { NavTab } from "../core/types.ts";
 import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+import { resolveReferences } from "./references.ts";
+import type { ReferenceSource } from "./references.ts";
 
 /**
- * API reference support, delegated wholesale to Scalar (`@scalar/astro`). Blume
- * resolves the configured spec sources into routes, generates one self-contained
- * Scalar page per source, and adds a nav tab. OpenAPI and AsyncAPI share this
- * exact path — Scalar auto-detects the document type — so the only difference
- * between the two config blocks is their default route and nav label.
+ * The Scalar renderer: an escape hatch (`openapi.renderer: "scalar"`) and the
+ * path AsyncAPI still uses. Each Scalar-rendered spec becomes one self-contained
+ * `@scalar/astro` page loaded client-side from Scalar's CDN. Blume's own OpenAPI
+ * renderer (the default) lives in `source.ts` / the `components/openapi` set and
+ * does not pass through here.
  */
 
-type ReferenceKind = "openapi" | "asyncapi";
-
-/** A spec source resolved to a concrete route and nav label. */
-export interface ReferenceSource {
-  kind: ReferenceKind;
-  /** Normalized route the reference mounts at, e.g. `/reference`. */
-  route: string;
-  label: string;
-  /** Local path or `http(s)` URL, verbatim from config. */
-  spec: string;
-  /** Per-block Scalar theme name override, if any. */
-  theme?: string;
-}
-
-/** A generated reference page, ready to write under `src/pages`. */
+/** A generated Scalar reference page, ready to write under `src/pages`. */
 export interface ReferenceFile {
   /** Path relative to `src/pages`, e.g. `reference.astro`, `api/events.astro`. */
   pagePath: string;
@@ -37,21 +24,7 @@ export interface ReferenceFile {
 }
 
 const URL_SPEC = /^https?:\/\//u;
-const NON_SLUG = /[^a-z0-9]+/gu;
-const SLUG_EDGES = /^-+|-+$/gu;
 const ROUTE_EDGES = /^\/+|\/+$/gu;
-const TRAILING_SLASH = /\/+$/u;
-
-const slugify = (text: string): string =>
-  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
-
-/** Normalize a configured route to a single leading slash, no trailing slash. */
-const normalizeRoute = (route: string): string => {
-  const trimmed = route.trim();
-  const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
-  return noTrailing === "" ? "/" : noTrailing;
-};
 
 /** The `src/pages`-relative file path for a reference route. */
 const referencePagePath = (route: string): string => {
@@ -59,71 +32,6 @@ const referencePagePath = (route: string): string => {
   return `${segments === "" ? "index" : segments}.astro`;
 };
 
-/** A spec is a single source (`spec` shorthand prepended to any `sources`). */
-type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];
-
-const sourcesOf = (
-  block: Block
-): { label?: string; route?: string; spec: string }[] => {
-  const sources = [...block.sources];
-  if (block.spec) {
-    sources.unshift({ spec: block.spec });
-  }
-  return sources;
-};
-
-const referencesFor = (
-  kind: ReferenceKind,
-  block: Block,
-  defaultLabel: string
-): ReferenceSource[] => {
-  if (!block.enabled) {
-    return [];
-  }
-  const sources = sourcesOf(block);
-  const base = normalizeRoute(block.route);
-
-  return sources.map((source, index) => {
-    const label =
-      source.label ??
-      (sources.length > 1 ? `${defaultLabel} ${index + 1}` : defaultLabel);
-
-    let route: string;
-    if (source.route) {
-      route = normalizeRoute(source.route);
-    } else if (sources.length === 1) {
-      route = base;
-    } else {
-      const suffix = source.label ? slugify(source.label) : "";
-      route = normalizeRoute(`${base}/${suffix || index + 1}`);
-    }
-
-    return { kind, label, route, spec: source.spec, theme: block.theme };
-  });
-};
-
-/**
- * Resolve every enabled reference source into its route and label. Pure (no file
- * IO), so the nav and the page generator stay in sync from one source of truth.
- */
-export const resolveReferences = (
-  config: ResolvedConfig
-): ReferenceSource[] => [
-  ...referencesFor("openapi", config.openapi, "API Reference"),
-  ...referencesFor("asyncapi", config.asyncapi, "Events"),
-];
-
-/** Nav tabs (header links) for the configured references. */
-export const referenceTabs = (config: ResolvedConfig): NavTab[] =>
-  resolveReferences(config).map((ref) => ({
-    label: ref.label,
-    path: ref.route,
-  }));
-
-/** Whether any reference block is enabled (gates dependency + page wiring). */
-export const hasReferences = (config: ResolvedConfig): boolean =>
-  config.openapi.enabled || config.asyncapi.enabled;
-
 const darkModeConfig = (
   mode: ResolvedConfig["theme"]["mode"]
 ): Record<string, boolean> => {
@@ -180,9 +88,10 @@ const specConfiguration = async (
 };
 
 /**
- * Build the Scalar reference page(s) for the project. Reads local specs, maps
- * the theme, and skips routes that collide with a content page or another
- * source. Returns the files to write under `src/pages` plus any warnings.
+ * Build the Scalar reference page(s) for the project. Only Scalar-rendered
+ * references are emitted here (Blume-rendered OpenAPI is staged content). Reads
+ * local specs, maps the theme, and skips routes that collide with a content page
+ * or another source. Returns the files to write under `src/pages` plus warnings.
  */
 export const buildReferenceFiles = async (options: {
   config: ResolvedConfig;
@@ -196,6 +105,9 @@ export const buildReferenceFiles = async (options: {
   const seen = new Set<string>();
   const accepted: ReferenceSource[] = [];
   for (const ref of resolveReferences(config)) {
+    if (ref.renderer !== "scalar") {
+      continue;
+    }
     if (seen.has(ref.route)) {
       warnings.push(
         `Two API reference sources resolve to ${ref.route}; keeping the first.`

package/src/openapi/source.ts

@@ -0,0 +1,140 @@
+import matter from "../core/frontmatter.ts";
+import { hashText } from "../core/sources/cache.ts";
+import type {
+  ContentSource,
+  SourceContext,
+  SourceEntry,
+  SourceLoadResult,
+} from "../core/sources/types.ts";
+import type { Diagnostic } from "../core/types.ts";
+import { extractOperations } from "./model.ts";
+import type { ApiOperationRef, ApiSpecData, OpenApiData } from "./model.ts";
+import { parseSpec } from "./parse.ts";
+import type { ReferenceSource } from "./references.ts";
+import { operationMdx, overviewMdx } from "./render-mdx.ts";
+import type { RenderedPage } from "./render-mdx.ts";
+
+/**
+ * The staged content source behind Blume's own OpenAPI renderer. Each configured
+ * spec is parsed once here, then lowered into one MDX page per operation plus an
+ * overview page — so operations become first-class Blume pages (real routes,
+ * sidebar, search, i18n, OG) and the parsed documents are handed to the
+ * generated `blume:openapi` module for the UI components to render.
+ */
+
+/** A content source that also exposes the specs it parsed during `load()`. */
+export interface OpenApiContentSource extends ContentSource {
+  readonly kind: "openapi-source";
+  /** Parsed spec data, populated by `load()`; `{}` before the first load. */
+  openApiData: () => OpenApiData;
+}
+
+/** Narrow a content source to the OpenAPI source (to read its parsed specs). */
+export const isOpenApiSource = (
+  source: ContentSource
+): source is OpenApiContentSource =>
+  (source as Partial<OpenApiContentSource>).kind === "openapi-source";
+
+/** Route (`/reference/pet/add-pet`) to a staged content ref, without extension. */
+const routeToRef = (route: string): string => route.replace(/^\/+/u, "");
+
+const toEntry = (rendered: RenderedPage, ref: string): SourceEntry => {
+  const raw = matter.stringify(`${rendered.body}\n`, rendered.data);
+  return {
+    body: { format: "mdx", text: rendered.body },
+    data: rendered.data,
+    hash: hashText(raw),
+    raw,
+    ref,
+  };
+};
+
+/** All staged entries for one spec: operations first, overview last. */
+const specEntries = (
+  spec: ApiSpecData,
+  operations: ApiOperationRef[]
+): SourceEntry[] => {
+  const entries = operations.map((operation) =>
+    toEntry(operationMdx(spec, operation), `${routeToRef(operation.route)}.mdx`)
+  );
+  // Overview last so an operation sets the section's routePath before the index
+  // page is inserted (the group's routePath is derived from its first child).
+  entries.push(
+    toEntry(overviewMdx(spec), `${routeToRef(spec.route)}/index.mdx`)
+  );
+  return entries;
+};
+
+interface LoadedSpec {
+  slug: string;
+  spec: ApiSpecData;
+  entries: SourceEntry[];
+}
+
+export const openApiSource = (
+  references: ReferenceSource[],
+  ctx: SourceContext
+): OpenApiContentSource => {
+  let parsed: OpenApiData = {};
+
+  const loadReference = async (
+    reference: ReferenceSource
+  ): Promise<LoadedSpec | Diagnostic> => {
+    try {
+      const { document } = await parseSpec(reference.spec, ctx.projectRoot);
+      const { operations, tags } = extractOperations(document, reference.route);
+      const info = document.info ?? { title: reference.label, version: "" };
+      const spec: ApiSpecData = {
+        codeSamples: reference.display.codeSamples,
+        description: info.description ?? "",
+        document,
+        expandSchemas: reference.display.expandSchemas,
+        label: reference.label,
+        operations: Object.fromEntries(
+          operations.map((operation) => [operation.key, operation])
+        ),
+        route: reference.route,
+        slug: reference.slug,
+        tags,
+        title: info.title ?? reference.label,
+        version: info.version ?? "",
+      };
+      return {
+        entries: specEntries(spec, operations),
+        slug: reference.slug,
+        spec,
+      };
+    } catch (error) {
+      return {
+        code: "BLUME_OPENAPI_UNAVAILABLE",
+        message: `Could not load OpenAPI spec "${reference.spec}" for ${reference.route} (${(error as Error).message}); its reference pages were skipped.`,
+        severity: "warning",
+      };
+    }
+  };
+
+  const load = async (): Promise<SourceLoadResult> => {
+    const results = await Promise.all(references.map(loadReference));
+    const entries: SourceEntry[] = [];
+    const diagnostics: Diagnostic[] = [];
+    const data: OpenApiData = {};
+    for (const result of results) {
+      if ("severity" in result) {
+        diagnostics.push(result);
+        continue;
+      }
+      data[result.slug] = result.spec;
+      entries.push(...result.entries);
+    }
+    parsed = data;
+    return { diagnostics, entries };
+  };
+
+  return {
+    kind: "openapi-source",
+    load,
+    name: "openapi",
+    openApiData: () => parsed,
+    staged: true,
+  };
+};

package/src/registry/eject.ts

@@ -39,7 +39,9 @@ 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";
+import { hasScalarReferences } from "../openapi/references.ts";
+import { buildReferenceFiles } from "../openapi/scalar.ts";
+import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
 import { servesStaticIndex } from "../search/providers.ts";
 import { tailwindEntryTemplate } from "../theme/entry.ts";
@@ -48,6 +50,12 @@ import { twoslashCss } from "../theme/twoslash.ts";
 
 const POSIX = (path: string): string => path.split("\\").join("/");
 
+/** The `blume:openapi` payload for the ejected app (`{}` when none). */
+const ejectOpenApiData = (project: BlumeProject): unknown => {
+  const source = project.sources.find(isOpenApiSource);
+  return source ? source.openApiData() : {};
+};
+
 /**
  * The Ask AI endpoint plus, unless the backend runs its own retrieval (Inkeep),
  * its grounding snapshot. Empty when Ask AI is disabled.
@@ -156,6 +164,7 @@ export const eject = async (root: string): Promise<string[]> => {
         needsReact,
         needsSvelte,
         needsVue,
+        openapiPath: "./src/generated/openapi.json",
         pages: relPages,
         searchClientPath: "./src/generated/search-client.ts",
         themePath: "./src/generated/app.css",
@@ -219,6 +228,10 @@ export const eject = async (root: string): Promise<string[]> => {
       path: join(genDir, "app.css"),
     },
     { content: buildRuntimeData(project), path: join(genDir, "data.json") },
+    {
+      content: `${JSON.stringify(ejectOpenApiData(project))}\n`,
+      path: join(genDir, "openapi.json"),
+    },
     {
       content: `${JSON.stringify(rawMarkdown)}\n`,
       path: join(genDir, "raw-markdown.json"),
@@ -302,7 +315,7 @@ export const eject = async (root: string): Promise<string[]> => {
 
   // Scalar API/AsyncAPI reference pages, mirrored from the generated runtime so
   // the ejected app keeps its reference routes.
-  if (hasReferences(config)) {
+  if (hasScalarReferences(config)) {
     const references = await buildReferenceFiles({
       config,
       contentRoutes: new Set(project.graph.pages.map((page) => page.route)),

package/src/theme/chrome-icons.ts

@@ -0,0 +1,22 @@
+/**
+ * The handful of built-in glyphs Blume's own chrome renders from **client-side**
+ * scripts (copy/check buttons, search result rows). These stay hand-inlined and
+ * dependency-free so they can be bundled into client JS — the full icon
+ * resolver (`./icons.ts`) pulls in library data far too large to ship to the
+ * browser, so it must never be imported from a client script.
+ *
+ * Author-facing content icons (Cards, Steps, sidebar, `icon:` frontmatter) do
+ * NOT come from here — they resolve from the bundled icon libraries at build
+ * time via `resolveIcon` and inline as zero-JS SVG.
+ *
+ * Values are Lucide inner-SVG markup; the client `svg()` helpers wrap them in an
+ * `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" …>`.
+ */
+export const chromeIcons: Record<string, string> = {
+  check: '<path d="M20 6 9 17l-5-5"/>',
+  copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
+  file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
+  search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',
+  sparkles:
+    '<path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3Z"/><path d="M5 3v4"/><path d="M3 5h4"/><path d="M19 17v4"/><path d="M17 19h4"/>',
+};