blume 0.5.3 → 0.5.4

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/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,

package/src/theme/icons.ts

@@ -1,16 +1,11 @@
 /**
- * Icon resolution backed by the open Iconify icon sets — Font Awesome (free),
- * Lucide, and Tabler — the three libraries Mintlify exposes. Resolution runs at
+ * Icon resolution backed by the open Iconify Lucide set. Resolution runs at
  * **build time, server-side**, and returns ready-to-inline SVG, so icons stay
- * zero-JS and fully self-contained (no runtime CDN fetch, unlike Mintlify).
+ * zero-JS and fully self-contained (no runtime CDN fetch).
  *
  * Because the Iconify set data is large, this module must only be imported from
  * server contexts (`.astro` frontmatter, the CLI). Client scripts use the tiny
  * hand-inlined set in `./chrome-icons.ts` instead.
- *
- * Coverage vs Mintlify: full parity for every Font Awesome *free* name, Lucide,
- * and Tabler. Font Awesome Pro styles (`light`/`thin`/`duotone`/`sharp-solid`)
- * aren't in the open data, so they fall back to `solid`.
  */
 import { createRequire } from "node:module";
 
@@ -25,61 +20,22 @@ const requireJson = createRequire(import.meta.url);
 const loadSet = (pkg: string): IconifyJSON => requireJson(pkg) as IconifyJSON;
 
 const SETS: Record<string, IconifyJSON> = {
-  "fa6-brands": loadSet("@iconify-json/fa6-brands/icons.json"),
-  "fa6-regular": loadSet("@iconify-json/fa6-regular/icons.json"),
-  "fa6-solid": loadSet("@iconify-json/fa6-solid/icons.json"),
   lucide: loadSet("@iconify-json/lucide/icons.json"),
-  tabler: loadSet("@iconify-json/tabler/icons.json"),
 };
 
-/** Blume's default library when a project sets no `icons.library`. */
+/** Blume's only icon library. */
 const DEFAULT_SET = "lucide";
 
-/** `icons.library` config value → Iconify set. */
-const LIBRARY_SETS: Record<string, string> = {
-  fa: "fa6-solid",
-  "font-awesome": "fa6-solid",
-  fontawesome: "fa6-solid",
-  lucide: "lucide",
-  tabler: "tabler",
-};
-
-/**
- * Mintlify Font Awesome `iconType` → Iconify set. The Pro-only styles
- * (`light`/`thin`/`duotone`/`sharp-solid`) aren't in the free data, so they map
- * to `solid` rather than render nothing.
- */
-const ICON_TYPE_SETS: Record<string, string> = {
-  brands: "fa6-brands",
-  duotone: "fa6-solid",
-  light: "fa6-solid",
-  regular: "fa6-regular",
-  "sharp-solid": "fa6-solid",
-  solid: "fa6-solid",
-  thin: "fa6-solid",
-};
-
-/** Explicit `prefix:name` prefixes (Iconify prefixes + common FA aliases). */
+/** Explicit `prefix:name` prefixes. Lucide is the only bundled set. */
 const PREFIX_SETS: Record<string, string> = {
-  ...LIBRARY_SETS,
-  fa: "fa6-solid",
-  "fa-brands": "fa6-brands",
-  "fa-regular": "fa6-regular",
-  "fa-solid": "fa6-solid",
-  "fa6-brands": "fa6-brands",
-  "fa6-regular": "fa6-regular",
-  "fa6-solid": "fa6-solid",
-  fab: "fa6-brands",
-  far: "fa6-regular",
-  fas: "fa6-solid",
-  ti: "tabler",
+  lucide: "lucide",
 };
 
 /**
- * Own-property map lookup. Icon names and library/iconType hints come from
- * content and config, so a value like `constructor:x` would otherwise resolve
- * an Object.prototype member (a function) and crash resolution deep in the
- * build with no pointer to the offending page.
+ * Own-property map lookup. Icon names come from content and config, so a value
+ * like `constructor:x` would otherwise resolve an Object.prototype member (a
+ * function) and crash resolution deep in the build with no pointer to the
+ * offending page.
  */
 const ownEntry = <T>(map: Record<string, T>, key: string): T | undefined =>
   Object.hasOwn(map, key) ? map[key] : undefined;
@@ -89,40 +45,16 @@ export interface ResolvedIcon {
   body: string;
   /** The resolved icon name. */
   name: string;
-  /** The icon's viewBox, which varies per library (24×24, 512-height, …). */
+  /** The icon's viewBox (Lucide is 24×24). */
   viewBox: string;
 }
 
-export interface ResolveIconOptions {
-  /** Font Awesome style selector (`solid`, `regular`, `brands`, …). */
-  iconType?: string;
-  /** Default library for a bare name (`fontawesome` | `lucide` | `tabler`). */
-  library?: string;
-}
-
 const normalize = (name: string): string =>
   name
     .trim()
     .toLowerCase()
     .replaceAll(/[\s_]+/gu, "-");
 
-/** Which set a bare name resolves against, given library/iconType hints. */
-const setFor = (options: ResolveIconOptions): string => {
-  if (options.iconType) {
-    const set = ownEntry(ICON_TYPE_SETS, normalize(options.iconType));
-    if (set) {
-      return set;
-    }
-  }
-  if (options.library) {
-    const set = ownEntry(LIBRARY_SETS, normalize(options.library));
-    if (set) {
-      return set;
-    }
-  }
-  return DEFAULT_SET;
-};
-
 const fromSet = (setName: string, iconName: string): ResolvedIcon | null => {
   const set = ownEntry(SETS, setName);
   const data = set && getIconData(set, iconName);
@@ -133,46 +65,23 @@ const fromSet = (setName: string, iconName: string): ResolvedIcon | null => {
   return { body, name: iconName, viewBox: attributes.viewBox };
 };
 
-// Font Awesome splits brands into their own set, so a bare `github` under a
-// solid/regular default still resolves.
-const fromFaSet = (setName: string, name: string): ResolvedIcon | null =>
-  fromSet(setName, name) ?? fromSet("fa6-brands", name);
-
-const resolveInSet = (setName: string, name: string): ResolvedIcon | null =>
-  setName.startsWith("fa6-")
-    ? fromFaSet(setName, name)
-    : fromSet(setName, name);
-
 /**
- * Resolve an icon name to inline SVG. Honors an explicit `prefix:name`
- * (`lucide:rocket`, `fa6-brands:github`), then `iconType`, then the configured
- * `library`, falling back to Lucide.
+ * Resolve an icon name to inline SVG. Honors an explicit `lucide:name` prefix;
+ * a bare name resolves against Lucide.
  */
-export const resolveIcon = (
-  name: string,
-  options: ResolveIconOptions = {}
-): ResolvedIcon | null => {
+export const resolveIcon = (name: string): ResolvedIcon | null => {
   const normalized = normalize(name);
   const colon = normalized.indexOf(":");
   if (colon > 0) {
     const setName = ownEntry(PREFIX_SETS, normalized.slice(0, colon));
-    if (setName) {
-      return resolveInSet(setName, normalized.slice(colon + 1));
-    }
+    return setName ? fromSet(setName, normalized.slice(colon + 1)) : null;
   }
-  return resolveInSet(setFor(options), normalized);
+  return fromSet(DEFAULT_SET, normalized);
 };
 
-/**
- * Whether a name resolves to a known icon. Without a library hint this checks
- * every bundled set, so a valid Font Awesome/Tabler name isn't flagged as a typo
- * just because the project's default library is Lucide.
- */
-export const hasIcon = (
-  name: string,
-  options: ResolveIconOptions = {}
-): boolean => {
-  if (resolveIcon(name, options)) {
+/** Whether a name resolves to a known Lucide icon. */
+export const hasIcon = (name: string): boolean => {
+  if (resolveIcon(name)) {
     return true;
   }
   const normalized = normalize(name);

package/src/theme/palette.ts

@@ -52,36 +52,11 @@ const backgroundImageCss = (image: string): string =>
 const cssToken = (name: string, value?: string | null): string[] =>
   value ? [`  ${name}: ${value};`] : [];
 
-const backgroundDecorationCss = (
-  decoration: ResolvedConfig["theme"]["backgroundDecoration"]
-): string => {
-  if (decoration === "gradient") {
-    return `  --blume-background-decoration: radial-gradient(circle at top left, color-mix(in oklab, var(--blume-accent) 18%, transparent), transparent 28rem), radial-gradient(circle at top right, color-mix(in oklab, var(--blume-action) 12%, transparent), transparent 24rem);
-  --blume-background-decoration-repeat: no-repeat, no-repeat;
-  --blume-background-decoration-size: auto, auto;
-`;
-  }
-  if (decoration === "grid") {
-    return `  --blume-background-decoration: linear-gradient(var(--blume-border) 1px, transparent 1px), linear-gradient(90deg, var(--blume-border) 1px, transparent 1px);
-  --blume-background-decoration-repeat: repeat, repeat;
-  --blume-background-decoration-size: 2rem 2rem, 2rem 2rem;
-`;
-  }
-  if (decoration === "windows") {
-    return `  --blume-background-decoration: linear-gradient(90deg, color-mix(in oklab, var(--blume-border) 70%, transparent) 1px, transparent 1px), linear-gradient(var(--blume-border) 1px, transparent 1px);
-  --blume-background-decoration-repeat: repeat, repeat;
-  --blume-background-decoration-size: 7rem 4.5rem, 7rem 4.5rem;
-`;
-  }
-  return "";
-};
-
 const themeRootCss = (
   theme: ResolvedConfig["theme"],
   options: {
     accent: string;
     action: string | null;
-    backgroundDecoration: string;
     radius: string;
   }
 ): string =>
@@ -97,7 +72,6 @@ const themeRootCss = (
       "--blume-background-image",
       theme.backgroundImage ? backgroundImageCss(theme.backgroundImage) : null
     ),
-    options.backgroundDecoration.trimEnd(),
     `  --blume-radius: ${options.radius};`,
   ]
     .filter(Boolean)
@@ -108,13 +82,12 @@ const themeDarkCss = (
   options: {
     accent: string;
     action: string | null;
-    backgroundDecoration: string;
   }
 ): string => {
-  // Mode-shared tokens (accent, action, decoration) must be re-declared here:
-  // the base stylesheet's own `:root[data-theme="dark"]` block outranks the
-  // `:root` config tokens on specificity, so without this block dark mode
-  // would silently keep its neutral defaults and ignore the config.
+  // Mode-shared tokens (accent, action) must be re-declared here: the base
+  // stylesheet's own `:root[data-theme="dark"]` block outranks the `:root`
+  // config tokens on specificity, so without this block dark mode would
+  // silently keep its neutral defaults and ignore the config.
   const tokens = [
     `  --blume-accent: ${options.accent};`,
     "  --blume-accent-foreground: oklch(1 0 0);",
@@ -130,7 +103,6 @@ const themeDarkCss = (
         ? backgroundImageCss(theme.backgroundImageDark)
         : null
     ),
-    options.backgroundDecoration.trimEnd(),
   ].filter(Boolean);
   return `:root[data-theme="dark"] {
 ${tokens.join("\n")}
@@ -159,20 +131,15 @@ export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
   const accent = presetOrColor(theme.accent);
   const accentDark = theme.accentDark ? presetOrColor(theme.accentDark) : null;
   const action = theme.action ? presetOrColor(theme.action) : null;
-  const backgroundDecoration = backgroundDecorationCss(
-    theme.backgroundDecoration
-  );
   const radius = RADII[theme.radius];
   const root = themeRootCss(theme, {
     accent,
     action,
-    backgroundDecoration,
     radius,
   });
   const dark = themeDarkCss(theme, {
     accent: accentDark ?? accent,
     action,
-    backgroundDecoration,
   });
 
   return `/* Generated by Blume from theme config. */

package/src/theme/twoslash.ts

@@ -33,9 +33,14 @@ const OVERRIDES = `
 
 /* Popups are absolutely positioned and must escape the pre's scroll container.
    The base prose pre rule (from the typography layer) wins the cascade here
-   despite lower specificity, so !important is needed to force visibility. */
+   despite lower specificity, so !important is needed to force visibility.
+   Regular code blocks scroll their inner code element and carry the horizontal
+   padding there; twoslash code opts out of that scroller (popups again), so the
+   padding is restored on the pre. */
 .prose pre.twoslash {
   overflow: visible !important;
+  padding-left: 1.25rem;
+  padding-right: 1.25rem;
 }
 
 /* The rich renderer renders each popup's type signature as a nested Shiki

package/dist/types/core/bridge.d.ts

@@ -1,24 +0,0 @@
-import type { BlumeConfig } from "./schema.ts";
-/** A detected docs-tool config that Blume can serve without a migration. */
-export interface BridgeDetection {
-    /** Which foreign docs tool was detected. */
-    tool: "mintlify";
-    /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
-    configFile: string;
-    /** A Blume config synthesized from the foreign config, ready to validate. */
-    raw: BlumeConfig;
-}
-/**
- * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
- *
- * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
- * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
- * its content block is rewired to a single `mintlify` content source, which
- * transforms each MDX page to Blume idiom at scan time. The original
- * `content.root`/`exclude` and `variables` move onto the source (Blume has no
- * runtime variable substitution, so globals are inlined into content there).
- *
- * Returns `null` when no Mintlify config is present. Only called when no
- * `blume.config.*` exists, so an explicit Blume config always takes precedence.
- */
-export declare const detectMintlifyBridge: (root: string) => Promise<BridgeDetection | null>;

package/dist/types/core/package-json.d.ts

@@ -1,12 +0,0 @@
-/**
- * Derive a valid npm package name from a directory name, falling back to
- * `docs` when nothing usable remains.
- */
-export declare const toPackageName: (raw: string) => string;
-/**
- * A minimal, runnable `package.json` body for a Blume project: the `blume`
- * dependency pinned to the installed version plus `dev`/`build`/`doctor`
- * scripts, so `npm install && npm run dev` works immediately. Shared by
- * `blume init` and the migrators, which scaffold one when a project has none.
- */
-export declare const blumePackageJson: (name: string) => string;

package/dist/types/migrate/mintlify/assets.d.ts

@@ -1,8 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-/**
- * Top-level path segments referenced as static assets by a Mintlify config
- * (the conventional `/images`, plus logo/favicon/background paths). These are
- * the root-served folders Mintlify exposes at the site root; Blume serves them
- * via `content.assets` (bridge) or relocates them under `public/` (migrator).
- */
-export declare const assetSegments: (config: BlumeConfig) => string[];

package/dist/types/migrate/mintlify/config.d.ts

@@ -1,16 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-type JsonObject = Record<string, unknown>;
-export interface MintlifyRedirectPartition {
-    /** Static redirects Blume can honor, translated to Blume's `from`/`to` shape. */
-    kept: NonNullable<BlumeConfig["redirects"]>;
-    /** Source paths of dynamic redirects dropped because Blume can't model them. */
-    dropped: string[];
-}
-/**
- * Split a spec's redirects into the static ones Blume emits and the dynamic
- * (wildcard/param) ones it drops. Keeping a dynamic redirect crashes the Astro
- * build, so the migrator surfaces the dropped sources as a warning instead.
- */
-export declare const partitionMintlifyRedirects: (spec: JsonObject) => MintlifyRedirectPartition;
-export declare const loadMintlifyConfig: (root: string, file: string) => Promise<BlumeConfig>;
-export {};

package/dist/types/migrate/mintlify/i18n.d.ts

@@ -1,7 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-/**
- * Map a Mintlify `navigation.languages[]` array to a Blume `i18n` config. The
- * entry marked `default: true` becomes `defaultLocale`; translated content
- * already lives in ISO-code directories, which match Blume's `dir` parser.
- */
-export declare const mintlifyI18n: (spec: Record<string, unknown>) => BlumeConfig["i18n"] | null;