blume 0.5.3 → 0.6.0

package/src/openapi/parse.ts

@@ -1,8 +1,10 @@
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { setTimeout as sleep } from "node:timers/promises";
 
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import { isAbsolute, join } from "pathe";
 
+import { hashText } from "../core/sources/cache.ts";
 import type { ApiDocument } from "./model.ts";
 
 /**
@@ -10,39 +12,220 @@ import type { ApiDocument } from "./model.ts";
  * (`@scalar/openapi-parser`) to read a spec (YAML or JSON), then upgrade Swagger
  * 2.0 / OpenAPI 3.0 documents to 3.1 so the renderer only handles one shape.
  * Internal `$ref`s are deliberately left in place (see `model.ts`).
+ *
+ * Remote (`http(s)`) specs are fetched defensively — bounded per attempt, retried
+ * on transient failures, proxy-aware, and cached on disk — mirroring the
+ * resilience the external link checker (`core/links.ts`) and the Notion source
+ * (`core/sources/notion.ts`) already have. A bare `fetch` is the classic "curl
+ * works but the build doesn't" gap: it ignores `*_PROXY`, has no timeout, and
+ * dies on a single cold-start blip.
  */
 
 const URL_SPEC = /^https?:\/\//u;
 
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_ATTEMPTS = 3;
+const BASE_BACKOFF_MS = 500;
+const SECOND_MS = 1000;
+// Worth another try: request timeout, too-early, rate-limited, and the 5xx range.
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+const USER_AGENT = "blume (+https://github.com/haydenbleasel/blume)";
+const PROXY_ENV_VARS = [
+  "HTTP_PROXY",
+  "http_proxy",
+  "HTTPS_PROXY",
+  "https_proxy",
+  "ALL_PROXY",
+  "all_proxy",
+];
+
 export interface ParsedSpec {
   document: ApiDocument;
   warnings: string[];
 }
 
+/** Where and whether to cache a remote spec's text between runs. */
+export interface SpecFetchOptions {
+  /** Dir for a last-good on-disk copy of a remote spec (offline fallback). */
+  cacheDir?: string;
+  /**
+   * Re-fetch even when a cached copy exists. Builds/sync refresh; dev is
+   * cache-first for fast, offline-tolerant restarts (see `SourceContext`).
+   */
+  refresh?: boolean;
+}
+
+/**
+ * Route Node's global `fetch` through an HTTP(S) proxy the first time a remote
+ * spec is fetched with one configured. Node's built-in `fetch` ignores `*_PROXY`
+ * on its own; undici's env proxy agent, installed on the shared global-dispatcher
+ * symbol, wires it in without replacing `fetch` (so tests can still stub it).
+ * Best-effort and lazy: no proxy env means no undici import at all, and an
+ * unavailable undici just leaves the direct connection in place.
+ */
+let proxyInstalled = false;
+const ensureProxyDispatcher = async (): Promise<void> => {
+  // Only memoize a successful install: with no proxy configured we cheaply
+  // re-check each time, so a proxy set later in the process still takes effect.
+  if (proxyInstalled || !PROXY_ENV_VARS.some((name) => process.env[name])) {
+    return;
+  }
+  try {
+    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    setGlobalDispatcher(new EnvHttpProxyAgent());
+    proxyInstalled = true;
+  } catch {
+    // No proxy support available; fall back to a direct connection.
+  }
+};
+
+/** `Retry-After` in ms when the server sent a sane one, else undefined. */
+const retryAfterMs = (response: Response): number | undefined => {
+  const header = response.headers.get("retry-after");
+  const seconds = header ? Number(header) : Number.NaN;
+  return Number.isFinite(seconds) && seconds > 0
+    ? seconds * SECOND_MS
+    : undefined;
+};
+
+/** One fetch attempt, normalized: the body text, or a (maybe-retryable) error. */
+type Attempt =
+  | { text: string }
+  | { error: Error; retryable: boolean; retryAfter?: number };
+
+const attemptFetch = async (spec: string): Promise<Attempt> => {
+  try {
+    const response = await fetch(spec, {
+      headers: {
+        accept: "application/json, application/yaml, text/yaml, */*",
+        "user-agent": USER_AGENT,
+      },
+      redirect: "follow",
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (response.ok) {
+      return { text: await response.text() };
+    }
+    return {
+      error: new Error(`${spec} -> ${response.status} ${response.statusText}`),
+      retryAfter: retryAfterMs(response),
+      retryable: RETRYABLE_STATUS.has(response.status),
+    };
+  } catch (error) {
+    // Network error, DNS/TLS failure, or an aborted (timed-out) request — all
+    // transient by nature, so worth a retry.
+    return {
+      error: error instanceof Error ? error : new Error(String(error)),
+      retryable: true,
+    };
+  }
+};
+
+/** Fetch a remote spec's text, retrying transient failures with backoff. */
+const fetchSpecText = async (spec: string): Promise<string> => {
+  await ensureProxyDispatcher();
+  let last: Attempt = {
+    error: new Error(`Could not fetch ${spec}`),
+    retryable: false,
+  };
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1) {
+    // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
+    last = await attemptFetch(spec);
+    if ("text" in last) {
+      return last.text;
+    }
+    if (!last.retryable || attempt === MAX_ATTEMPTS - 1) {
+      throw last.error;
+    }
+    // oxlint-disable-next-line no-await-in-loop -- back off before retrying
+    await sleep(last.retryAfter ?? BASE_BACKOFF_MS * 2 ** attempt);
+  }
+  throw last.error;
+};
+
+const cacheFileFor = (cacheDir: string, spec: string): string =>
+  join(cacheDir, `spec-${hashText(spec)}.cache`);
+
+const readCache = async (file: string): Promise<string | undefined> => {
+  try {
+    return await readFile(file, "utf-8");
+  } catch {
+    return undefined;
+  }
+};
+
+const writeCache = async (
+  dir: string,
+  file: string,
+  text: string
+): Promise<void> => {
+  try {
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, text, "utf-8");
+  } catch {
+    // Best-effort cache; a write failure must not fail the load.
+  }
+};
+
 /** Read a spec's raw text from an `http(s)` URL or a local (project-relative) path. */
-const readSpecText = async (spec: string, root: string): Promise<string> => {
-  if (URL_SPEC.test(spec)) {
-    const response = await fetch(spec);
-    if (!response.ok) {
-      throw new Error(`${spec} -> ${response.status} ${response.statusText}`);
+const readSpecText = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions
+): Promise<{ text: string; warnings: string[] }> => {
+  if (!URL_SPEC.test(spec)) {
+    const absolute = isAbsolute(spec) ? spec : join(root, spec);
+    return { text: await readFile(absolute, "utf-8"), warnings: [] };
+  }
+
+  const cacheFile = options.cacheDir
+    ? cacheFileFor(options.cacheDir, spec)
+    : undefined;
+
+  // Cache-first in dev: serve the last-good snapshot without touching the network.
+  if (cacheFile && options.refresh === false) {
+    const cached = await readCache(cacheFile);
+    if (cached !== undefined) {
+      return { text: cached, warnings: [] };
+    }
+  }
+
+  try {
+    const text = await fetchSpecText(spec);
+    if (options.cacheDir && cacheFile) {
+      await writeCache(options.cacheDir, cacheFile, text);
+    }
+    return { text, warnings: [] };
+  } catch (error) {
+    // A transient outage falls back to the last good fetch, with a warning.
+    if (cacheFile) {
+      const cached = await readCache(cacheFile);
+      if (cached !== undefined) {
+        return {
+          text: cached,
+          warnings: [
+            `Could not fetch ${spec} (${(error as Error).message}); using the last cached copy.`,
+          ],
+        };
+      }
     }
-    return await response.text();
+    throw error;
   }
-  const absolute = isAbsolute(spec) ? spec : join(root, spec);
-  return await readFile(absolute, "utf-8");
 };
 
 /**
  * Read, normalize, and upgrade a spec to an OpenAPI 3.1 document. Throws when the
- * spec can't be read; callers turn that into a source diagnostic rather than a
- * hard failure so a broken spec doesn't take down the whole build.
+ * spec can't be read and no cache is available; callers turn that into a source
+ * diagnostic (an error in build, a warning in dev) rather than a hard failure so
+ * a broken spec doesn't take down the whole build.
  */
 export const parseSpec = async (
   spec: string,
-  root: string
+  root: string,
+  options: SpecFetchOptions = {}
 ): Promise<ParsedSpec> => {
-  const text = await readSpecText(spec, root);
+  const { text, warnings } = await readSpecText(spec, root, options);
   const normalized = normalize(text);
   const { specification } = upgrade(normalized);
-  return { document: specification as ApiDocument, warnings: [] };
+  return { document: specification as ApiDocument, warnings };
 };

package/src/openapi/render-mdx.ts

@@ -73,13 +73,47 @@ export const operationMdx = (
   };
 };
 
-export const overviewMdx = (spec: ApiSpecData): RenderedPage => ({
-  body: withDescription(
-    spec.description,
-    `<ApiOverview source="${spec.slug}" />`
-  ),
-  data: {
-    sidebar: { label: "Overview" },
-    title: spec.title || spec.label,
-  },
-});
+export const overviewMdx = (spec: ApiSpecData): RenderedPage => {
+  // Tag sections: declared tags in spec order, then any tag an operation
+  // references that isn't declared under `tags`. The section headings are
+  // emitted as real markdown `##` (not markup inside a component) so the
+  // markdown pipeline gives them ids, permalink anchors, and table-of-contents
+  // entries; only the operation-link list defers to a component.
+  const operations = Object.values(spec.operations);
+  const sections = [...spec.tags];
+  const known = new Set(spec.tags.map((tag) => tag.slug));
+  for (const operation of operations) {
+    if (!known.has(operation.tagSlug)) {
+      known.add(operation.tagSlug);
+      sections.push({
+        description: "",
+        name: operation.tag,
+        slug: operation.tagSlug,
+      });
+    }
+  }
+  const tagSections = sections
+    .filter((tag) =>
+      operations.some((operation) => operation.tagSlug === tag.slug)
+    )
+    .map((tag) =>
+      [
+        `## ${mdxSafe(tag.name)}`,
+        ...(tag.description.trim() ? [mdxSafe(tag.description.trim())] : []),
+        `<ApiTagOperations source="${spec.slug}" tag="${tag.slug}" />`,
+      ].join("\n\n")
+    );
+  return {
+    body: [
+      withDescription(
+        spec.description,
+        `<ApiOverview source="${spec.slug}" />`
+      ),
+      ...tagSections,
+    ].join("\n\n"),
+    data: {
+      sidebar: { label: "Overview" },
+      title: spec.title || spec.label,
+    },
+  };
+};

package/src/openapi/scalar.ts

@@ -61,7 +61,7 @@ const themeConfiguration = (
   const accent = resolveAccent(config.theme);
   const radius = resolveRadius(config.theme);
   return {
-    customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent};--scalar-radius:${radius};}`,
+    customCss: `:root,.light-mode,.dark-mode{--scalar-color-accent:${accent.light};--scalar-radius:${radius};}.dark-mode{--scalar-color-accent:${accent.dark};}`,
     ...darkModeConfig(config.theme.mode),
   };
 };

package/src/openapi/source.ts

@@ -69,6 +69,8 @@ interface LoadedSpec {
   slug: string;
   spec: ApiSpecData;
   entries: SourceEntry[];
+  /** Non-fatal notes from the load (e.g. an offline cache fallback). */
+  diagnostics: Diagnostic[];
 }
 
 export const openApiSource = (
@@ -81,7 +83,11 @@ export const openApiSource = (
     reference: ReferenceSource
   ): Promise<LoadedSpec | Diagnostic> => {
     try {
-      const { document } = await parseSpec(reference.spec, ctx.projectRoot);
+      const { document, warnings } = await parseSpec(
+        reference.spec,
+        ctx.projectRoot,
+        { cacheDir: ctx.cacheDir, refresh: ctx.refresh }
+      );
       const { operations, tags } = extractOperations(document, reference.route);
       const info = document.info ?? { title: reference.label, version: "" };
       const spec: ApiSpecData = {
@@ -100,6 +106,11 @@ export const openApiSource = (
         version: info.version ?? "",
       };
       return {
+        diagnostics: warnings.map((message) => ({
+          code: "BLUME_OPENAPI_STALE",
+          message,
+          severity: "warning" as const,
+        })),
         entries: specEntries(spec, operations),
         slug: reference.slug,
         spec,
@@ -108,7 +119,12 @@ export const openApiSource = (
       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",
+        // A configured-but-unloadable spec ships a dead nav tab (a 404 route),
+        // so fail loudly in build (blocks under --strict) while staying a warning
+        // in dev so offline work still runs.
+        severity: ctx.mode === "build" ? "error" : "warning",
+        suggestion:
+          "Check the spec URL/path is reachable from the build environment; behind a proxy, set HTTP(S)_PROXY.",
       };
     }
   };
@@ -125,6 +141,7 @@ export const openApiSource = (
       }
       data[result.slug] = result.spec;
       entries.push(...result.entries);
+      diagnostics.push(...result.diagnostics);
     }
     parsed = data;
     return { diagnostics, entries };

package/src/search/documents.ts

@@ -114,10 +114,15 @@ const buildCrumbIndex = (sidebar: NavNode[]): Map<string, Crumbs> => {
  * Pass `includeWhenDisabled` to index pages on their content merits even when
  * the search provider is `none` — used by the MCP server, which is a separate
  * feature from on-page search.
+ *
+ * `content` selects the extraction: `"plain"` (default) strips Markdown to bare
+ * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
+ * headings — for Ask AI grounding, where fenced examples are often the answer
+ * and stripping them makes the model unable to cite content the docs do contain.
  */
 export const buildSearchDocuments = async (
   project: BlumeProject,
-  options?: { includeWhenDisabled?: boolean }
+  options?: { includeWhenDisabled?: boolean; content?: "markdown" | "plain" }
 ): Promise<SearchDocument[]> => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
 
@@ -148,7 +153,9 @@ export const buildSearchDocuments = async (
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
       const raw = page ? await readEntryText(project, page) : "";
-      const body = raw ? toPlainText(matter(raw).content) : "";
+      const source = raw ? matter(raw).content : "";
+      const body =
+        options?.content === "markdown" ? source.trim() : toPlainText(source);
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       return {

package/src/theme/entry.ts

@@ -32,9 +32,6 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 
 :root {
   --blume-background: oklch(1 0 0);
-  --blume-background-decoration: none;
-  --blume-background-decoration-repeat: no-repeat;
-  --blume-background-decoration-size: auto;
   --blume-background-image: none;
   --blume-background-image-repeat: no-repeat;
   --blume-background-image-size: cover;
@@ -90,9 +87,6 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 
 :root[data-theme="dark"] {
   --blume-background: oklch(0.085 0 0);
-  --blume-background-decoration: none;
-  --blume-background-decoration-repeat: no-repeat;
-  --blume-background-decoration-size: auto;
   --blume-background-image: none;
   --blume-background-image-repeat: no-repeat;
   --blume-background-image-size: cover;
@@ -134,9 +128,22 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
 }
 
 @layer base {
+  /* Nothing refuses to shrink below its intrinsic content width. This global
+     min-width reset defuses the classic flex/grid overflow — a long or
+     truncating child forcing its container (and the page) past the viewport
+     edge — so components don't need per-element min-w-0 overrides. */
+  * {
+    min-width: 0;
+  }
+  /* Interactive controls get a pointer cursor unless disabled. */
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
   html {
     scroll-behavior: smooth;
     scroll-padding-top: 4.5rem;
+    text-rendering: optimizeLegibility;
   }
   /* Headings use the display font (defaults to the body font when unset). */
   h1,
@@ -153,16 +160,11 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
     border-radius: 2px;
   }
   body {
-    background-attachment: fixed, fixed;
-    background-image:
-      var(--blume-background-image), var(--blume-background-decoration);
-    background-position: center top, top center;
-    background-repeat:
-      var(--blume-background-image-repeat),
-      var(--blume-background-decoration-repeat);
-    background-size:
-      var(--blume-background-image-size),
-      var(--blume-background-decoration-size);
+    background-attachment: fixed;
+    background-image: var(--blume-background-image);
+    background-position: center top;
+    background-repeat: var(--blume-background-image-repeat);
+    background-size: var(--blume-background-image-size);
   }
   @media (prefers-reduced-motion: reduce) {
     html {
@@ -298,7 +300,7 @@ ${options.sources.map((source) => `@source "${source}";`).join("\n")}
   line-height: 1.55;
   margin: 1.5rem 0;
   overflow-x: auto;
-  padding: 1rem 1.25rem;
+  padding: 1rem 0;
   position: relative;
 }
 
@@ -395,6 +397,32 @@ blume-diff {
   padding: 0;
 }
 
+/* Long lines scroll inside the code element, not the pre: the pre stays static
+   so its absolute header bar (::before) and copy button don't drift with the
+   scroll. The pre's horizontal padding lives here so content still scrolls
+   edge-to-edge past it. Two contexts opt out: twoslash blocks (popups must
+   escape any scroll container — see theme/twoslash.ts), and the API request
+   panel, which owns its code layout and keeps the copy control in the panel
+   header. Every other component that hosts a code block — Tabs, CodeGroup,
+   Steps, Callout, Card, Accordion — is real prose content and keeps the inset,
+   even though its chrome wrapper is not-prose. */
+.prose :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code) {
+  display: block;
+  overflow-x: auto;
+  padding: 0 1.25rem;
+  /* The scroller is only as tall as the code, so an overlay scrollbar would
+     draw on top of the last line; hide it (wheel/trackpad/keyboard scrolling
+     still works). */
+  scrollbar-width: none;
+}
+
+.prose
+  :where(
+    pre:not(.twoslash, .twoslash pre, blume-panel-tabs *) > code
+  )::-webkit-scrollbar {
+  display: none;
+}
+
 /* Word wrap (markdown.code.wrap): long lines wrap instead of scrolling. The
    attribute is set on <body> from config; default code keeps \`white-space: pre\`. */
 [data-blume-code-wrap] pre,