blume 0.5.2 → 0.5.4

package/src/core/types.ts

@@ -173,24 +173,17 @@ export interface NavSelectorItem {
   tag?: string;
 }
 
-/** Top-level Mintlify-style partition selectors. */
+/** Top-level partition selectors (products, versions, languages). */
 export interface NavSelector {
   label: string;
   kind: "dropdown" | "language" | "product" | "version";
   items: NavSelectorItem[];
 }
 
-/** Chrome overrides used when the current route belongs to a nav partition. */
-export interface NavChromeVariant {
-  path: string;
-  banner?: ResolvedConfig["banner"];
-}
-
 /** The complete navigation model derived from the content graph. */
 export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
-  chromeVariants: NavChromeVariant[];
   sidebar: NavNode[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
   repoUrl?: string | null;

package/src/markdown/code-title.ts

@@ -25,7 +25,9 @@ export interface CodeTitleTransformer {
   pre: (this: CodeMetaContext, node: PreNode) => void;
 }
 
-const TITLE_ATTR = /title=(?<quote>["'])(?<title>[^"']*)\k<quote>/u;
+// The body excludes only the delimiting quote, so `title="foo's file.ts"`
+// (an apostrophe inside double quotes) still matches.
+const TITLE_ATTR = /title=(?:"(?<dq>[^"]*)"|'(?<sq>[^']*)')/u;
 const LINE_NUMBERS = /(?:^|\s)lineNumbers(?=\s|$)/u;
 
 const parseTitle = (raw: string | undefined): string | undefined => {
@@ -33,8 +35,9 @@ const parseTitle = (raw: string | undefined): string | undefined => {
     return undefined;
   }
   const explicit = raw.match(TITLE_ATTR);
-  if (explicit?.groups?.title) {
-    return explicit.groups.title;
+  const attrTitle = explicit?.groups?.dq ?? explicit?.groups?.sq;
+  if (attrTitle) {
+    return attrTitle;
   }
   // The first bare token is the title (```ts blume.config.ts), skipping Shiki
   // line ranges (`{1,3-5}`), `key=value` attrs, and the reserved `lineNumbers`

package/src/markdown/package-install.ts

@@ -31,7 +31,9 @@ export const packageInstallPlugin = () => ({
       node,
       jsxFlowElement(
         "Tabs",
-        [],
+        // hash off: clicking "pnpm" in an install block must not rewrite the
+        // page hash (clobbering the heading anchor the reader arrived with).
+        [jsxAttribute("hash", "false")],
         PACKAGE_MANAGERS.map((manager) => tabNode(manager, commands[manager]))
       )
     );

package/src/og/card.ts

@@ -19,10 +19,19 @@ const ACCENT_HEX: Record<string, string> = {
   teal: "#14b8a6",
 };
 
+const HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/iu;
+
 // OG rendering uses hex (Takumi's color parser does not accept oklch); named
-// presets map to hex, raw hex passes through, anything else falls back.
-const resolveAccent = (accent: string): string =>
-  ACCENT_HEX[accent] ?? (accent.startsWith("#") ? accent : "#3b82f6");
+// presets map to hex, well-formed hex passes through, anything else falls
+// back — a malformed hex (`#12345` typo) would throw inside Takumi and fail
+// the build at OG prerender with an opaque native error. `hasOwn` keeps a
+// preset name like "constructor" from resolving up the prototype chain.
+const resolveAccent = (accent: string): string => {
+  if (Object.hasOwn(ACCENT_HEX, accent)) {
+    return ACCENT_HEX[accent] as string;
+  }
+  return HEX_COLOR.test(accent) ? accent : "#3b82f6";
+};
 
 export interface OgCardOptions {
   /** Large headline — the page title. */
@@ -75,7 +84,10 @@ export const truncate = (value: string, max: number): string => {
 // stays within the lockup.
 const MARK_HEIGHT = 32;
 const MARK_MAX_WIDTH = 100;
-const VIEW_BOX = /viewBox="0 0 (?<w>[\d.]+) (?<h>[\d.]+)"/u;
+// Accept either quote style and a non-zero min-x/min-y; only width/height
+// matter for the aspect ratio. A miss falls back to a square mark.
+const VIEW_BOX =
+  /viewBox=(?<q>["'])[\d.-]+[\s,]+[\d.-]+[\s,]+(?<w>[\d.]+)[\s,]+(?<h>[\d.]+)\k<q>/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

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

@@ -21,8 +21,17 @@ const ENTITIES: Record<string, string> = {
   "{": "&#123;",
   "}": "&#125;",
 };
+// MDX also parses lines starting with `import`/`export` as ESM ("import the
+// SDK…" is common spec prose). Entity-escape the keyword's first letter so the
+// construct can't match; it still renders as the literal word.
+const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
 const mdxSafe = (text: string): string =>
-  text.replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char);
+  text
+    .replace(MDX_UNSAFE, (char) => ENTITIES[char] ?? char)
+    .replace(
+      MDX_ESM_KEYWORD,
+      (keyword) => `&#${keyword.codePointAt(0)};${keyword.slice(1)}`
+    );
 
 /** Frontmatter + body for one operation or overview page. */
 export interface RenderedPage {
@@ -64,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/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/sync/orama-cloud.ts

@@ -31,6 +31,8 @@ export const syncOramaCloud = async (
       content: record.content,
       description: record.description,
       id: record._id,
+      // Carried so an i18n site can filter hosted results per language.
+      locale: record.locale,
       tag: record.tag,
       title: record.title,
       url: record.url,

package/src/search/sync/typesense.ts

@@ -54,6 +54,9 @@ export const syncTypesense = async (
       { name: "content", type: "string" },
       { name: "url", type: "string" },
       { facet: true, name: "tag", optional: true, type: "string" },
+      // Carried as a facet so an i18n site can filter hosted results per
+      // language (the SearchRecord contract).
+      { facet: true, name: "locale", optional: true, type: "string" },
     ],
     name: config.collection,
   });
@@ -62,6 +65,7 @@ export const syncTypesense = async (
     content: record.content,
     description: record.description,
     id: record._id,
+    locale: record.locale,
     tag: record.tag,
     title: record.title,
     url: record.url,

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,