blume 0.5.1 → 0.5.3

package/src/migrate/mintlify/snippets.ts

@@ -3,6 +3,7 @@ import { readFile as readFileFromDisk } from "node:fs/promises";
 import { dirname, relative, resolve } from "pathe";
 
 import matter from "../../core/frontmatter.ts";
+import { isInsideRoot, stripImports } from "../shared.ts";
 
 const MARKDOWN_SNIPPET_IMPORT =
   /^import\s+(?<name>[$A-Z_a-z][$\w]*)\s+from\s+["'](?<source>[^"']+\.mdx?)["'];?\s*$/gmu;
@@ -37,11 +38,6 @@ interface SnippetTransformOptions {
   trail?: string[];
 }
 
-const isInsideRoot = (root: string, candidate: string): boolean => {
-  const rel = relative(root, candidate);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
-};
-
 const escapeRegExp = (value: string): string =>
   value.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 
@@ -151,7 +147,9 @@ const interpolateProps = (
   source.replaceAll(PLACEHOLDER, (value, name: string) => props[name] ?? value);
 
 const stripImport = (source: string, importText: string): string =>
-  source.replace(importText, "").replaceAll(/\n{3,}/gu, "\n\n");
+  // Seam-targeted removal: a whole-document `\n{3,}` collapse would rewrite
+  // real double blank lines inside the page's code fences.
+  stripImports(source, new RegExp(escapeRegExp(importText), "gu"));
 
 const replacePlaceholder = (
   source: string,
@@ -189,9 +187,20 @@ export const rewriteMintlifyMarkdownSnippets = async (
       );
     }
     seen.add(file);
-    const readFile = options.readFile ?? readFileFromDisk;
+    const readFile =
+      options.readFile ??
+      ((path: string): Promise<string> => readFileFromDisk(path, "utf-8"));
     try {
-      const raw = await readFile(file);
+      let raw: string;
+      try {
+        raw = await readFile(file);
+      } catch {
+        // A dangling import must fail with a message that names both ends —
+        // the caller downgrades it to a per-page warning and moves on.
+        throw new Error(
+          `snippet ${rootRelativePath(options.root, file)} (imported by ${rootRelativePath(options.root, options.filePath)}) does not exist`
+        );
+      }
       const content = matter(raw).content.trim();
       const transformed = await rewriteMintlifyMarkdownSnippets(content, {
         ...options,

package/src/migrate/nextra/index.ts

@@ -5,8 +5,9 @@ import { basename, dirname, extname, join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import matter from "../../core/frontmatter.ts";
+import { ensureGitignore } from "../../core/gitignore.ts";
 import type { BlumeConfig, FolderMeta } from "../../core/schema.ts";
-import { writeBlumeConfig } from "../shared.ts";
+import { rewriteFrameworkScripts, writeBlumeConfig } from "../shared.ts";
 import {
   rewriteNextraCallouts,
   stripNextraImports,
@@ -353,11 +354,25 @@ export const migrateNextraProject = async (
   );
   await writeBlumeConfig(root, buildConfig(plan.tabs));
 
+  // Tear down the Next scaffolding like the Fumadocs migrator does — without
+  // this, `npm run dev` still launches Next against the gutted content tree.
+  const scriptsRewritten = await rewriteFrameworkScripts(
+    root,
+    /\bnext\b/u,
+    /\bnextra\b/u
+  );
+  await ensureGitignore(root, [".blume/", "dist/"]);
+
   const warnings = [
     ...plan.warnings,
     ...pages.skipped.map((rel) => `Skipped ${rel} (target already exists)`),
     ...relocateWarnings,
   ];
+  if (scriptsRewritten) {
+    warnings.push(
+      "Repointed package.json scripts at Blume (dev/build/preview); remove the leftover Next/Nextra dependencies and next.config/theme.config by hand."
+    );
+  }
   if (pages.removedKeys.length > 0) {
     warnings.push(
       `Dropped unsupported page frontmatter keys: ${pages.removedKeys.join(", ")}.`

package/src/migrate/shared.ts

@@ -1,8 +1,9 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
-import { isAbsolute, join, relative } from "pathe";
+import { basename, isAbsolute, join, relative } from "pathe";
 
+import { blumePackageJson, toPackageName } from "../core/package-json.ts";
 import type { BlumeConfig } from "../core/schema.ts";
 import { pageMetaSchema } from "../core/schema.ts";
 
@@ -102,6 +103,49 @@ export const rewriteFrameworkScripts = async (
 export const leftoverFiles = (root: string, candidates: string[]): string[] =>
   candidates.filter((candidate) => existsSync(join(root, candidate)));
 
+/**
+ * Scaffold a minimal, runnable `package.json` when the migrated project has
+ * none. Config-only sources (e.g. a Mintlify `docs.json`) ship no npm manifest,
+ * so a fresh migration has nothing to run `blume dev` with; this writes a stub
+ * with `blume` as a dependency and `dev`/`build`/`doctor` scripts, making
+ * `npm install && npm run dev` work immediately. A pre-existing `package.json`
+ * is left untouched — {@link rewriteFrameworkScripts} repoints those instead.
+ * Returns true when a file was created.
+ */
+export const ensurePackageJson = async (root: string): Promise<boolean> => {
+  const pkgPath = join(root, "package.json");
+  if (existsSync(pkgPath)) {
+    return false;
+  }
+  await writeFile(
+    pkgPath,
+    blumePackageJson(toPackageName(basename(root))),
+    "utf-8"
+  );
+  return true;
+};
+
+// A marker no markdown document contains, planted where an import was removed
+// so the blank-gap collapse can target the seams alone.
+const IMPORT_SEAM = "\u0000blume-import-seam\u0000";
+
+/**
+ * Remove every match of an import pattern, collapsing the blank gap each
+ * removal leaves behind — without touching blank runs elsewhere in the
+ * document (double blank lines inside code fences are real content that a
+ * whole-document `\n{3,}` collapse used to corrupt).
+ */
+export const stripImports = (source: string, pattern: RegExp): string => {
+  const marked = source.replaceAll(pattern, IMPORT_SEAM);
+  if (marked === source) {
+    return source;
+  }
+  return marked
+    .replaceAll(new RegExp(String.raw`\n*(?:${IMPORT_SEAM})+\n*`, "gu"), "\n\n")
+    .replace(/^\n+/u, "")
+    .replace(/\n+$/u, "\n");
+};
+
 // ---------------------------------------------------------------------------
 // Callout components -> Blume `:::` directives
 // ---------------------------------------------------------------------------
@@ -138,14 +182,30 @@ const dedent = (value: string): string => {
   return lines.map((line) => line.slice(common)).join("\n");
 };
 
+/**
+ * A colon fence one longer than any directive fence in the body — nested
+ * container directives require the outer fence to be longer than the inner
+ * ones, or the inner `:::` closes the outer block.
+ */
+const fenceOver = (body: string): string => {
+  let max = 2;
+  for (const match of body.matchAll(/^ {0,3}(?<colons>:{3,})/gmu)) {
+    max = Math.max(max, match.groups?.colons?.length ?? 0);
+  }
+  return ":".repeat(Math.max(3, max + 1));
+};
+
 const directiveBlock = (
   directive: string,
   title: string | undefined,
   inner: string
 ): string => {
-  const head = title ? `:::${directive}[${title}]` : `:::${directive}`;
   const body = dedent(inner);
-  return `${head}\n${body}\n:::`;
+  const fence = fenceOver(body);
+  const head = title
+    ? `${fence}${directive}[${title}]`
+    : `${fence}${directive}`;
+  return `${head}\n${body}\n${fence}`;
 };
 
 /**
@@ -177,6 +237,40 @@ export const findOpenTagEnd = (source: string, from: number): number => {
   return -1;
 };
 
+/**
+ * Find the close tag matching an open tag, honoring same-tag nesting
+ * (`<Note>a<Note>b</Note>c</Note>` must close at the *outer* `</Note>`).
+ * Returns the index of the matching `</Tag>`, or -1 when unterminated.
+ */
+const findMatchingClose = (
+  source: string,
+  tag: string,
+  from: number
+): number => {
+  const scanner = new RegExp(`<(?<closing>/)?${tag}(?=[\\s/>])`, "gu");
+  scanner.lastIndex = from;
+  let depth = 0;
+  for (let match = scanner.exec(source); match; match = scanner.exec(source)) {
+    if (match.groups?.closing) {
+      if (depth === 0) {
+        return match.index;
+      }
+      depth -= 1;
+      continue;
+    }
+    // A nested open tag: skip its attributes; self-closing ones don't nest.
+    const end = findOpenTagEnd(source, match.index + tag.length + 1);
+    if (end === -1) {
+      return -1;
+    }
+    if (source[end - 1] !== "/") {
+      depth += 1;
+    }
+    scanner.lastIndex = end + 1;
+  }
+  return -1;
+};
+
 const directiveFor = (
   tag: string,
   attrs: string,
@@ -233,7 +327,7 @@ export const rewriteCallouts = (
     const selfClosing = attrs.trimEnd().endsWith("/");
     const closeIndex = selfClosing
       ? openEnd
-      : source.indexOf(closeTag, openEnd + 1);
+      : findMatchingClose(source, tag, openEnd + 1);
 
     if (!directive || (!selfClosing && closeIndex === -1)) {
       output += source.slice(cursor, openEnd + 1);
@@ -249,10 +343,12 @@ export const rewriteCallouts = (
         : `:::${directive}\n:::`;
       cursor = openEnd + 1;
     } else {
+      // Recurse so nested callouts (of any tag) convert too — they'd
+      // otherwise survive as components Blume doesn't ship.
       output += directiveBlock(
         directive,
         title,
-        source.slice(openEnd + 1, closeIndex)
+        rewriteCallouts(source.slice(openEnd + 1, closeIndex), options)
       );
       cursor = closeIndex + closeTag.length;
     }

package/src/migrate/starlight/content.ts

@@ -1,4 +1,4 @@
-import { renameTag, rewriteCallouts } from "../shared.ts";
+import { renameTag, rewriteCallouts, stripImports } from "../shared.ts";
 
 /**
  * Source-to-source rewrites that turn Starlight-only MDX into idiomatic Blume
@@ -14,11 +14,8 @@ const STARLIGHT_IMPORT =
  * Blume injects its components globally, so these imports would fail to resolve
  * once the Starlight packages are gone.
  */
-export const stripStarlightImports = (source: string): string => {
-  const stripped = source.replace(STARLIGHT_IMPORT, "");
-  // Collapse the blank gap a removed import block leaves behind.
-  return stripped === source ? source : stripped.replaceAll(/\n{3,}/gu, "\n\n");
-};
+export const stripStarlightImports = (source: string): string =>
+  stripImports(source, STARLIGHT_IMPORT);
 
 /** Starlight `<Aside type="X">` values mapped to Blume directive names. */
 const ASIDE_TYPE_DIRECTIVES: Record<string, string> = {

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

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/icons.ts

@@ -75,6 +75,15 @@ const PREFIX_SETS: Record<string, string> = {
   ti: "tabler",
 };
 
+/**
+ * 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.
+ */
+const ownEntry = <T>(map: Record<string, T>, key: string): T | undefined =>
+  Object.hasOwn(map, key) ? map[key] : undefined;
+
 export interface ResolvedIcon {
   /** Inner SVG markup (self-styled: carries its own fill/stroke). */
   body: string;
@@ -100,13 +109,13 @@ const normalize = (name: string): string =>
 /** Which set a bare name resolves against, given library/iconType hints. */
 const setFor = (options: ResolveIconOptions): string => {
   if (options.iconType) {
-    const set = ICON_TYPE_SETS[normalize(options.iconType)];
+    const set = ownEntry(ICON_TYPE_SETS, normalize(options.iconType));
     if (set) {
       return set;
     }
   }
   if (options.library) {
-    const set = LIBRARY_SETS[normalize(options.library)];
+    const set = ownEntry(LIBRARY_SETS, normalize(options.library));
     if (set) {
       return set;
     }
@@ -115,7 +124,7 @@ const setFor = (options: ResolveIconOptions): string => {
 };
 
 const fromSet = (setName: string, iconName: string): ResolvedIcon | null => {
-  const set = SETS[setName];
+  const set = ownEntry(SETS, setName);
   const data = set && getIconData(set, iconName);
   if (!data) {
     return null;
@@ -146,7 +155,7 @@ export const resolveIcon = (
   const normalized = normalize(name);
   const colon = normalized.indexOf(":");
   if (colon > 0) {
-    const setName = PREFIX_SETS[normalized.slice(0, colon)];
+    const setName = ownEntry(PREFIX_SETS, normalized.slice(0, colon));
     if (setName) {
       return resolveInSet(setName, normalized.slice(colon + 1));
     }

package/src/theme/palette.ts

@@ -22,6 +22,17 @@ const CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 const safeColor = (value: string, fallback: string): string =>
   CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
 
+/**
+ * Resolve a named preset or fall back to {@link safeColor}. `hasOwn` keeps a
+ * value like "constructor" from resolving an Object.prototype member — which
+ * would stringify a function into the generated CSS, breaking the rule (the
+ * exact breakout safeColor exists to prevent).
+ */
+const presetOrColor = (value: string): string =>
+  Object.hasOwn(ACCENTS, value)
+    ? (ACCENTS[value] as string)
+    : safeColor(value, FALLBACK_ACCENT);
+
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
   value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
@@ -94,10 +105,24 @@ const themeRootCss = (
 
 const themeDarkCss = (
   theme: ResolvedConfig["theme"],
-  accentDark: string | null
+  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.
   const tokens = [
-    ...cssToken("--blume-accent", accentDark),
+    `  --blume-accent: ${options.accent};`,
+    "  --blume-accent-foreground: oklch(1 0 0);",
+    ...cssToken("--blume-action", options.action),
+    ...cssToken(
+      "--blume-action-foreground",
+      options.action ? "oklch(1 0 0)" : null
+    ),
     ...cssToken("--blume-background", safeColorOrNull(theme.backgroundDark)),
     ...cssToken(
       "--blume-background-image",
@@ -105,10 +130,8 @@ const themeDarkCss = (
         ? backgroundImageCss(theme.backgroundImageDark)
         : null
     ),
-  ];
-  if (tokens.length === 0) {
-    return "";
-  }
+    options.backgroundDecoration.trimEnd(),
+  ].filter(Boolean);
   return `:root[data-theme="dark"] {
 ${tokens.join("\n")}
 }
@@ -121,7 +144,7 @@ ${tokens.join("\n")}
  * arbitrary colors without a config change.
  */
 export const resolveAccent = (theme: ResolvedConfig["theme"]): string =>
-  ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
+  presetOrColor(theme.accent);
 
 /** Resolve the configured radius preset to a CSS length. */
 export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
@@ -133,15 +156,9 @@ export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
  * arbitrary colors without a config change.
  */
 export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
-  const accent =
-    ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
-  const accentDark = theme.accentDark
-    ? (ACCENTS[theme.accentDark] ??
-      safeColor(theme.accentDark, FALLBACK_ACCENT))
-    : null;
-  const action = theme.action
-    ? (ACCENTS[theme.action] ?? safeColor(theme.action, FALLBACK_ACCENT))
-    : null;
+  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
   );
@@ -152,7 +169,11 @@ export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
     backgroundDecoration,
     radius,
   });
-  const dark = themeDarkCss(theme, accentDark);
+  const dark = themeDarkCss(theme, {
+    accent: accentDark ?? accent,
+    action,
+    backgroundDecoration,
+  });
 
   return `/* Generated by Blume from theme config. */
 :root {