blume 0.3.0 → 0.5.0

package/src/components/openapi/panel.ts

@@ -0,0 +1,59 @@
+/**
+ * Client behaviour for the OpenAPI request/response panels. `<blume-panel-tabs>`
+ * switches the visible `[data-panel="key"]` region when a `[data-panel-tab="key"]`
+ * button is clicked, and an optional `[data-panel-copy]` button copies the active
+ * panel's text. Vanilla custom element — no framework, in keeping with the core
+ * theme.
+ */
+
+class BlumePanelTabs extends HTMLElement {
+  connectedCallback() {
+    const tabs = [
+      ...this.querySelectorAll<HTMLButtonElement>("[data-panel-tab]"),
+    ];
+    const panels = [...this.querySelectorAll<HTMLElement>("[data-panel]")];
+    const copy = this.querySelector<HTMLButtonElement>("[data-panel-copy]");
+
+    const activate = (key: string): void => {
+      for (const tab of tabs) {
+        tab.setAttribute(
+          "aria-selected",
+          tab.dataset.panelTab === key ? "true" : "false"
+        );
+      }
+      for (const panel of panels) {
+        panel.classList.toggle("hidden", panel.dataset.panel !== key);
+      }
+    };
+
+    for (const tab of tabs) {
+      tab.addEventListener("click", () => {
+        const key = tab.dataset.panelTab;
+        if (key) {
+          activate(key);
+        }
+      });
+    }
+
+    if (copy) {
+      copy.addEventListener("click", async () => {
+        const active = panels.find(
+          (panel) => !panel.classList.contains("hidden")
+        );
+        try {
+          await navigator.clipboard.writeText(active?.textContent ?? "");
+          copy.dataset.copied = "true";
+          setTimeout(() => {
+            delete copy.dataset.copied;
+          }, 1500);
+        } catch {
+          // Clipboard unavailable (insecure context); silently ignore.
+        }
+      });
+    }
+  }
+}
+
+if (!customElements.get("blume-panel-tabs")) {
+  customElements.define("blume-panel-tabs", BlumePanelTabs);
+}

package/src/components/openapi/snippets.ts

@@ -0,0 +1,201 @@
+import { exampleValue, toJson } from "./helpers.ts";
+import type { SchemaLike } from "./helpers.ts";
+
+/**
+ * Request example + code-sample generation for an operation. Kept separate from
+ * `helpers.ts` so the schema renderers don't pull in the sample builders. Output
+ * is intentionally simple, copy-pasteable starter code — not an exhaustive SDK.
+ */
+
+interface ParamLike {
+  name?: string;
+  in?: string;
+  required?: boolean;
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+export interface OperationLike {
+  parameters?: ParamLike[];
+  requestBody?: { content?: Record<string, MediaTypeLike> };
+}
+
+export interface RequestSample {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  /** JSON-stringified request body, when the operation takes one. */
+  body?: string;
+  bodyValue?: unknown;
+}
+
+const TRAILING_SLASH = /\/+$/u;
+
+const jsonContentType = (
+  content: Record<string, MediaTypeLike> | undefined
+): [string, MediaTypeLike] | undefined => {
+  const entries = Object.entries(content ?? {});
+  return entries.find(([type]) => type.includes("json")) ?? entries[0];
+};
+
+/** Assemble a representative request from an operation and the spec servers. */
+export const buildRequestSample = (
+  operation: OperationLike,
+  method: string,
+  path: string,
+  servers: { url?: string }[],
+  schemas: Record<string, SchemaLike>
+): RequestSample => {
+  const base = (servers[0]?.url ?? "").replace(TRAILING_SLASH, "");
+  const params = operation.parameters ?? [];
+
+  let resolvedPath = path;
+  for (const param of params) {
+    if (param.in === "path" && param.name) {
+      const value = param.example ?? exampleValue(param.schema, schemas);
+      resolvedPath = resolvedPath.replace(
+        `{${param.name}}`,
+        encodeURIComponent(String(value ?? param.name))
+      );
+    }
+  }
+
+  const query = params
+    .filter((param) => param.in === "query" && param.required && param.name)
+    .map((param) => {
+      const value = param.example ?? exampleValue(param.schema, schemas);
+      return `${encodeURIComponent(param.name ?? "")}=${encodeURIComponent(
+        String(value ?? "")
+      )}`;
+    });
+  const search = query.length > 0 ? `?${query.join("&")}` : "";
+
+  const headers: Record<string, string> = {};
+  for (const param of params) {
+    if (param.in === "header" && param.required && param.name) {
+      headers[param.name] = String(
+        param.example ?? exampleValue(param.schema, schemas) ?? ""
+      );
+    }
+  }
+
+  const media = jsonContentType(operation.requestBody?.content);
+  let body: string | undefined;
+  let bodyValue: unknown;
+  if (media) {
+    const [type, mediaType] = media;
+    headers["Content-Type"] = type;
+    bodyValue = mediaType.example ?? exampleValue(mediaType.schema, schemas);
+    body = toJson(bodyValue);
+  }
+
+  return {
+    body,
+    bodyValue,
+    headers,
+    method: method.toUpperCase(),
+    url: `${base}${resolvedPath}${search}`,
+  };
+};
+
+const headerLines = (
+  headers: Record<string, string>,
+  format: (key: string, value: string) => string
+): string[] =>
+  Object.entries(headers).map(([key, value]) => format(key, value));
+
+const curlSnippet = (sample: RequestSample): string => {
+  const lines = [
+    `curl -X ${sample.method} "${sample.url}"`,
+    ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
+  ];
+  if (sample.body) {
+    lines.push(`  -d '${sample.body}'`);
+  }
+  return lines.join(" \\\n");
+};
+
+const fetchSnippet = (sample: RequestSample): string => {
+  const options = [`  method: "${sample.method}"`];
+  if (Object.keys(sample.headers).length > 0) {
+    const headers = headerLines(
+      sample.headers,
+      (key, value) => `    "${key}": "${value}"`
+    ).join(",\n");
+    options.push(`  headers: {\n${headers}\n  }`);
+  }
+  if (sample.body) {
+    options.push(`  body: JSON.stringify(${sample.body})`);
+  }
+  return `const response = await fetch("${sample.url}", {\n${options.join(
+    ",\n"
+  )}\n});`;
+};
+
+/** Turn a JSON literal into an equivalent Python literal (`true` -> `True`). */
+const toPython = (json: string): string =>
+  json
+    .replaceAll(/\btrue\b/gu, "True")
+    .replaceAll(/\bfalse\b/gu, "False")
+    .replaceAll(/\bnull\b/gu, "None");
+
+const pythonSnippet = (sample: RequestSample): string => {
+  const args = [`    "${sample.url}"`];
+  if (Object.keys(sample.headers).length > 0) {
+    const headers = headerLines(
+      sample.headers,
+      (key, value) => `        "${key}": "${value}"`
+    ).join(",\n");
+    args.push(`    headers={\n${headers}\n    }`);
+  }
+  if (sample.body) {
+    args.push(`    json=${toPython(sample.body)}`);
+  }
+  return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
+    ",\n"
+  )},\n)`;
+};
+
+/** A code-sample language: config id -> label, Shiki lang, and builder. */
+export interface SampleLanguage {
+  id: string;
+  label: string;
+  lang: string;
+  build: (sample: RequestSample) => string;
+}
+
+const LANGUAGES: SampleLanguage[] = [
+  { build: curlSnippet, id: "curl", label: "cURL", lang: "bash" },
+  { build: fetchSnippet, id: "js", label: "JavaScript", lang: "js" },
+  { build: pythonSnippet, id: "python", label: "Python", lang: "python" },
+];
+
+const ALIASES: Record<string, string> = {
+  bash: "curl",
+  javascript: "js",
+  node: "js",
+  py: "python",
+  shell: "curl",
+  typescript: "js",
+};
+
+/** The sample languages to render, resolved from config ids (unknown ids dropped). */
+export const sampleLanguages = (ids: string[]): SampleLanguage[] => {
+  const wanted = ids.length > 0 ? ids : ["curl", "js", "python"];
+  const out: SampleLanguage[] = [];
+  const seen = new Set<string>();
+  for (const raw of wanted) {
+    const id = ALIASES[raw.toLowerCase()] ?? raw.toLowerCase();
+    const language = LANGUAGES.find((entry) => entry.id === id);
+    if (language && !seen.has(id)) {
+      seen.add(id);
+      out.push(language);
+    }
+  }
+  return out;
+};

package/src/components/props.ts

@@ -65,4 +65,7 @@ export type TileProps = ComponentProps<
 export type TooltipProps = ComponentProps<
   typeof import("./content/Tooltip.astro").default
 >;
+export type YouTubeProps = ComponentProps<
+  typeof import("./content/YouTube.astro").default
+>;
 export type IconProps = ComponentProps<typeof import("./Icon.astro").default>;

package/src/core/assets.ts

@@ -0,0 +1,31 @@
+import { join } from "pathe";
+
+/** A static directory served at a URL prefix, in addition to `public/`. */
+export interface AssetMount {
+  /** Absolute filesystem path to the source directory (or file). */
+  dir: string;
+  /** URL path prefix the source is served at, e.g. `/images`. */
+  url: string;
+}
+
+/**
+ * Resolve `content.assets` entries (top-level dirs served at the site root,
+ * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
+ * runtime (dev middleware + build copy) and by link validation, so all three
+ * agree on where a `/images/foo.png` reference resolves on disk.
+ *
+ * Each entry is normalized to a leading-slash URL and joined to the project
+ * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
+ * escape the root or collide with the site's own routing prefix.
+ */
+export const resolveAssetMounts = (
+  root: string,
+  assets: string[]
+): AssetMount[] =>
+  assets.map((entry) => {
+    const rel = entry
+      .replace(/^[./]+/u, "")
+      .replaceAll(/\.\.\/?/gu, "")
+      .replace(/\/+$/u, "");
+    return { dir: join(root, rel), url: `/${rel}` };
+  });

package/src/core/bridge.ts

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 
 import { join } from "pathe";
 
+import { assetSegments } from "../migrate/mintlify/assets.ts";
 import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
 import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
 import type { BlumeConfig } from "./schema.ts";
@@ -64,11 +65,20 @@ export const detectMintlifyBridge = async (
   const root_ = config.content?.root ?? ".";
   const exclude = config.content?.exclude ?? [];
 
+  // Mintlify serves assets from the project root; the bridge never moves files,
+  // so referenced root-level asset folders (e.g. `images/`) are served in place
+  // via `content.assets` instead. This is the read-only twin of the migrator's
+  // relocation — same referenced segments, just no `public/` move.
+  const assets = assetSegments(config).filter(
+    (segment) => segment !== "public" && existsSync(join(root, segment))
+  );
+
   return {
     configFile,
     raw: {
       ...config,
       content: {
+        assets,
         // Mirror the excludes onto `content.exclude` too: the generated Astro
         // `docs` collection globs `content.root` (here the project root) and
         // must skip node_modules/snippets just like the source does.

package/src/core/builtin-tags.ts

@@ -7,6 +7,7 @@
 export const BUILTIN_MDX_TAGS = new Set<string>([
   "Accordion",
   "AccordionItem",
+  "ApiOverview",
   "AutoTypeTable",
   "Badge",
   "Callout",
@@ -25,8 +26,12 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "GithubInfo",
   "Icon",
   "Math",
+  "Operation",
   "Panel",
+  "ParamField",
   "Prompt",
+  "RequestField",
+  "ResponseField",
   "Step",
   "Steps",
   "Tab",
@@ -36,4 +41,5 @@ export const BUILTIN_MDX_TAGS = new Set<string>([
   "Tree",
   "TypeTable",
   "Visibility",
+  "YouTube",
 ]);

package/src/core/data.ts

@@ -93,6 +93,8 @@ export interface BlumeDataConfig {
   favicon: BlumeFavicon;
   feedback: boolean;
   i18n: BlumeDataI18n | null;
+  /** Default icon library for bare `icon` names. */
+  icons: ResolvedConfig["icons"];
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;

package/src/core/diagnostics.ts

@@ -84,7 +84,12 @@ const locatePath = (
     if (typeof segment !== "string") {
       continue;
     }
-    const matcher = new RegExp(`${escapeRegExp(segment)}\\s*[:=]`, "gu");
+    // The negative lookbehind keeps a segment like `title` from matching the
+    // tail of an unrelated key such as `subtitle:`.
+    const matcher = new RegExp(
+      `(?<![\\w$])${escapeRegExp(segment)}\\s*[:=]`,
+      "gu"
+    );
     matcher.lastIndex = cursor;
     const match = matcher.exec(source);
     if (!match) {

package/src/core/gitignore.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+
+import { join } from "pathe";
+
+/** A `.gitignore` line, normalized for comparison (trailing slashes dropped). */
+const gitignoreKey = (line: string): string => line.trim().replace(/\/+$/u, "");
+
+/**
+ * Ensure `.gitignore` ignores each of `entries`, appending any that are missing
+ * (creating the file when absent). Trailing-slash differences (`dist` vs
+ * `dist/`) count as already present. Returns the entries actually added.
+ */
+export const ensureGitignore = async (
+  root: string,
+  entries: string[]
+): Promise<string[]> => {
+  const path = join(root, ".gitignore");
+  const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
+  const present = new Set(
+    existing.split("\n").map(gitignoreKey).filter(Boolean)
+  );
+  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
+  if (added.length === 0) {
+    return [];
+  }
+  const gap = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  await writeFile(path, `${existing}${gap}${added.join("\n")}\n`, "utf-8");
+  return added;
+};

package/src/core/links.ts

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 
-import { join } from "pathe";
+import { basename, join } from "pathe";
 
+import type { AssetMount } from "./assets.ts";
 import type {
   ContentGraph,
   Diagnostic,
@@ -37,20 +38,52 @@ interface ExternalRef extends LinkSite {
 /** Lookups derived once from the content graph. */
 interface LinkContext {
   anchors: Map<string, Set<string>>;
+  /** `content.assets` mounts served alongside `public/` (checked in place). */
+  assetMounts: AssetMount[];
   publicDir: string | null;
   /** Normalized `redirect.from` paths — valid targets that resolve at runtime. */
   redirects: Set<string>;
   routes: Set<string>;
 }
 
+/** Whether a resolved asset path exists under `public/` or an asset mount. */
+const assetIsPresent = (resolved: string, ctx: LinkContext): boolean => {
+  if (ctx.publicDir && existsSync(join(ctx.publicDir, resolved))) {
+    return true;
+  }
+  return ctx.assetMounts.some(
+    (mount) =>
+      (resolved === mount.url || resolved.startsWith(`${mount.url}/`)) &&
+      existsSync(join(mount.dir, resolved.slice(mount.url.length)))
+  );
+};
+
 /** Outcome of classifying one link target. */
 type LinkResult = Diagnostic | "asset-unchecked" | null;
 
+/**
+ * Whether a page is a directory index (`…/index.md(x)`). Its route already *is*
+ * its directory, so a relative link must resolve against the route itself, not
+ * its parent — otherwise `./sibling` from `guides/index.mdx` (route `/guides`)
+ * would resolve to `/sibling` and be falsely flagged as broken.
+ */
+const isIndexPage = (page: PageRecord): boolean => {
+  const ref = page.source?.ref ?? page.sourcePath ?? "";
+  return /^index\.(?:md|mdx)$/iu.test(basename(ref));
+};
+
 /** Resolve a relative link target against the directory of a page route. */
-const resolveRelative = (pageRoute: string, target: string): string => {
+const resolveRelative = (
+  pageRoute: string,
+  target: string,
+  isIndex: boolean
+): string => {
   const segments = pageRoute.split("/").filter(Boolean);
-  // Drop the page's own segment so links resolve against its parent directory.
-  segments.pop();
+  // Drop a leaf page's own segment so links resolve against its parent
+  // directory. An index page's route already is its directory, so keep it.
+  if (!isIndex) {
+    segments.pop();
+  }
   for (const part of target.split("/")) {
     if (part === "" || part === ".") {
       continue;
@@ -114,13 +147,28 @@ const checkPathLink = (
   site: LinkSite,
   ctx: LinkContext
 ): LinkResult => {
+  // A real route always wins over the asset-extension heuristic, so a path
+  // whose last segment merely contains a dot (e.g. a page at `/releases/v1.0`)
+  // isn't misread as a missing asset.
+  const route = toRoute(resolved);
+  if (ctx.routes.has(route)) {
+    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
+  }
+  // A configured `redirect.from` resolves at runtime, so it's a valid target.
+  // Its destination (and any anchor there) is validated on its own page, so we
+  // don't follow the redirect to check the fragment here.
+  if (ctx.redirects.has(route)) {
+    return null;
+  }
+
   if (FILE_EXT.test(resolved) && !DOC_EXT.test(resolved)) {
-    if (ctx.publicDir === null) {
-      return "asset-unchecked";
-    }
-    if (existsSync(join(ctx.publicDir, resolved))) {
+    if (assetIsPresent(resolved, ctx)) {
       return null;
     }
+    // Nowhere to look: no `public/` and no asset mounts configured.
+    if (ctx.publicDir === null && ctx.assetMounts.length === 0) {
+      return "asset-unchecked";
+    }
     return {
       ...site,
       code: "BLUME_BROKEN_ASSET",
@@ -130,16 +178,6 @@ const checkPathLink = (
     };
   }
 
-  const route = toRoute(resolved);
-  if (ctx.routes.has(route)) {
-    return fragment ? checkAnchor(route, fragment, site, ctx) : null;
-  }
-  // A configured `redirect.from` resolves at runtime, so it's a valid target.
-  // Its destination (and any anchor there) is validated on its own page, so we
-  // don't follow the redirect to check the fragment here.
-  if (ctx.redirects.has(route)) {
-    return null;
-  }
   return {
     ...site,
     code: "BLUME_BROKEN_LINK",
@@ -295,7 +333,7 @@ const classifyLink = (
 
   const resolved = rawPath.startsWith("/")
     ? rawPath
-    : resolveRelative(page.route, rawPath);
+    : resolveRelative(page.route, rawPath, isIndexPage(page));
   return checkPathLink(resolved, fragment, target, site, ctx);
 };
 
@@ -309,12 +347,15 @@ export const validateLinks = async (
   options: {
     publicDir: string | null;
     checkExternal?: boolean;
+    /** `content.assets` mounts served alongside `public/`. */
+    assetMounts?: AssetMount[];
     /** Configured redirects; their `from` paths count as valid link targets. */
     redirects?: { from: string }[];
   }
 ): Promise<Diagnostic[]> => {
   const ctx: LinkContext = {
     anchors: buildAnchorIndex(graph.pages),
+    assetMounts: options.assetMounts ?? [],
     publicDir: options.publicDir,
     redirects: new Set(
       (options.redirects ?? []).map((redirect) => toRoute(redirect.from))

package/src/core/project-graph.ts

@@ -88,6 +88,8 @@ export const scanProject = async (
     refresh?: boolean;
     /** CLI overrides applied over the loaded config (e.g. `--output`). */
     overrides?: ConfigOverrides;
+    /** Relocate the generated runtime (e.g. `.blume-verify` for isolation). */
+    runtimeDir?: string;
   } = {}
 ): Promise<BlumeProject> => {
   const mode = options.mode ?? "dev";
@@ -97,7 +99,9 @@ export const scanProject = async (
   });
   const { bridge } = configResult;
   const config = applyConfigOverrides(configResult.config, options.overrides);
-  const context = resolveProjectContext(root, config);
+  const context = resolveProjectContext(root, config, {
+    runtimeDir: options.runtimeDir,
+  });
 
   // Each source validates itself (e.g. the filesystem source checks its root
   // exists), replacing the single hard `contentRoot` check.

package/src/core/project.ts

@@ -28,13 +28,27 @@ const firstExisting = (root: string, names: string[]): string | null => {
 export const findConfigFile = (root: string): string | null =>
   firstExisting(root, CONFIG_FILENAMES);
 
+/**
+ * Resolve the generated runtime directory for a project. Defaults to
+ * `<root>/.blume`; an override (e.g. `.blume-verify` for an isolated build that
+ * runs alongside a live `blume dev`) may be relative to the root or absolute.
+ */
+export const resolveRuntimeDir = (
+  root: string,
+  runtimeDir = ".blume"
+): string =>
+  isAbsolute(runtimeDir) ? runtimeDir : join(resolve(root), runtimeDir);
+
 /**
  * Resolve every path Blume needs from a project root and its resolved config.
- * Paths are absolute and normalized.
+ * Paths are absolute and normalized. `options.runtimeDir` relocates the whole
+ * generated runtime (and its build output) so a verify build/check can run
+ * without touching a live dev server's `.blume/` or the real `dist/`.
  */
 export const resolveProjectContext = (
   root: string,
-  config: ResolvedConfig
+  config: ResolvedConfig,
+  options?: { runtimeDir?: string }
 ): ProjectContext => {
   const absoluteRoot = resolve(root);
   const contentRoot = isAbsolute(config.content.root)
@@ -44,11 +58,19 @@ export const resolveProjectContext = (
   const pagesPath = join(absoluteRoot, config.content.pages);
   const pagesRoot = existsSync(pagesPath) ? pagesPath : null;
 
+  const outDir = resolveRuntimeDir(absoluteRoot, options?.runtimeDir);
+  // A relocated runtime keeps its build output self-contained under itself, so a
+  // verify build never empties the user's real `<root>/dist`.
+  const distDir = options?.runtimeDir
+    ? join(outDir, "dist")
+    : join(absoluteRoot, "dist");
+
   return {
     componentsFile: firstExisting(absoluteRoot, COMPONENTS_FILENAMES),
     configFile: findConfigFile(absoluteRoot),
     contentRoot,
-    outDir: join(absoluteRoot, ".blume"),
+    distDir,
+    outDir,
     pagesRoot,
     root: absoluteRoot,
     themeFile: firstExisting(absoluteRoot, THEME_FILENAMES),