blume 0.2.0 → 0.4.0

package/src/core/builtin-tags.ts

@@ -0,0 +1,40 @@
+/**
+ * The MDX component tags Blume ships (the keys of the catch-all's component map,
+ * plus composed sub-parts like `Color.Item`/`Tree.File`). Used by the
+ * missing-component diagnostic to tell an unknown `<Tag>` from a built-in. Keep
+ * in sync with the component map in `astro/templates.ts`.
+ */
+export const BUILTIN_MDX_TAGS = new Set<string>([
+  "Accordion",
+  "AccordionItem",
+  "AutoTypeTable",
+  "Badge",
+  "Callout",
+  "Card",
+  "CardGroup",
+  "CodeBlock",
+  "CodeGroup",
+  "Color",
+  "Column",
+  "Columns",
+  "Component",
+  "Diff",
+  "Expandable",
+  "FileTree",
+  "Frame",
+  "GithubInfo",
+  "Icon",
+  "Math",
+  "Panel",
+  "Prompt",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tile",
+  "Tooltip",
+  "Tree",
+  "TypeTable",
+  "Visibility",
+  "YouTube",
+]);

package/src/core/component-diagnostics.ts

@@ -0,0 +1,44 @@
+import { BUILTIN_MDX_TAGS } from "./builtin-tags.ts";
+import type { Diagnostic, PageRecord } from "./types.ts";
+
+/** `CardGroup` → `card-group`, matching registry item names. */
+const toKebab = (tag: string): string =>
+  tag
+    .replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>")
+    .toLowerCase();
+
+/**
+ * Warn when an `.mdx` page uses a `<Component>` tag that resolves to nothing —
+ * a built-in, an island, or a `components.ts` override — so a typo surfaces as a
+ * friendly diagnostic (with a `blume add` hint where one exists) instead of a raw
+ * MDX "X is not defined" build error. `extraTags` are the project's own known
+ * components (islands + overrides); `registryNames` gates the install hint.
+ */
+export const validateUsedComponents = (
+  pages: PageRecord[],
+  extraTags: Set<string>,
+  registryNames: Set<string>
+): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const seen = new Set<string>();
+  for (const page of pages) {
+    for (const tag of page.componentsUsed ?? []) {
+      if (BUILTIN_MDX_TAGS.has(tag) || extraTags.has(tag) || seen.has(tag)) {
+        continue;
+      }
+      seen.add(tag);
+      const name = toKebab(tag);
+      const suggestion = registryNames.has(name)
+        ? `Run \`blume add ${name}\` to install it, or register <${tag}> in components.ts (mdx).`
+        : `Register <${tag}> in components.ts (mdx), or add an islands/${tag}.tsx component.`;
+      diagnostics.push({
+        code: "BLUME_UNKNOWN_COMPONENT",
+        file: page.sourcePath ?? page.id,
+        message: `<${tag}> is used in ${page.route} but isn't a known component.`,
+        severity: "warning",
+        suggestion,
+      });
+    }
+  }
+  return diagnostics;
+};

package/src/core/component-overrides.ts

@@ -0,0 +1,478 @@
+import { existsSync } from "node:fs";
+
+import { dirname, extname, isAbsolute, resolve } from "pathe";
+import ts from "typescript";
+
+import type { HydrationMode } from "./schema.ts";
+
+/**
+ * Static analysis of a user `components.ts`/`.tsx`.
+ *
+ * Astro can only hydrate a component it imports *statically by path*, so to honor
+ * hydration on overrides (the `islands` group and `client:*` layout/mdx
+ * descriptors) Blume needs each override's source path and client mode at
+ * generate time — before Vite compiles anything. We read that here by parsing the
+ * file with the TypeScript compiler API (never executing it, so `.astro`/React
+ * imports don't need a Node loader).
+ *
+ * Only statically-analyzable authoring is understood: a default export that is an
+ * object literal or a `defineComponents({ ... })` call, with entries that are
+ * imported identifiers, path strings, or `{ component, client, media }` object
+ * literals. Anything else falls back to the runtime overrides object (which can
+ * still render a static component, just not hydrate it).
+ */
+
+export type OverrideFramework = "react" | "svelte" | "vue";
+
+/** How a wrapper should import an override's component. */
+export interface OverrideImport {
+  /** Framework inferred from the file extension, or null (e.g. `.astro`). */
+  framework: OverrideFramework | null;
+  /** Exported name to import: `"default"` or a named export. */
+  name: string;
+  /** Absolute path (for relative/absolute specifiers) or a bare specifier. */
+  path: string;
+}
+
+/** A normalized override entry, keyed by its MDX tag / layout-slot name. */
+export interface NormalizedOverride {
+  /** Present when the override should hydrate; drives the `client:*` directive. */
+  client?: HydrationMode;
+  /**
+   * True when the value is a bare imported identifier, so the runtime overrides
+   * object already holds a usable component (no generated import needed for a
+   * non-hydrated entry). False for path strings and `{ component }` descriptors.
+   */
+  identifier: boolean;
+  key: string;
+  /** Media query for `client: "media"`. */
+  media?: string;
+  /**
+   * How to obtain the component. `null` means it couldn't be resolved to a file,
+   * so the runtime overrides object is used (static render only).
+   */
+  source: OverrideImport | null;
+}
+
+export interface ComponentOverrideAnalysis {
+  islands: NormalizedOverride[];
+  layout: NormalizedOverride[];
+  mdx: NormalizedOverride[];
+  warnings: string[];
+}
+
+const GROUPS = ["mdx", "layout", "islands"] as const;
+type Group = (typeof GROUPS)[number];
+
+const FRAMEWORK_BY_EXT: Record<string, OverrideFramework> = {
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue",
+};
+
+const FRAMEWORK_LABEL: Record<OverrideFramework, string> = {
+  react: "React",
+  svelte: "Svelte",
+  vue: "Vue",
+};
+
+/** Extensions probed (in order) when a specifier omits one. */
+const COMPONENT_EXTS = [
+  "astro",
+  "tsx",
+  "ts",
+  "jsx",
+  "js",
+  "mjs",
+  "vue",
+  "svelte",
+];
+
+const HYDRATION_MODES = new Set<HydrationMode>([
+  "idle",
+  "load",
+  "media",
+  "only",
+  "visible",
+]);
+
+interface ImportBinding {
+  /** Exported name: `"default"` or a named export. */
+  imported: string;
+  specifier: string;
+}
+
+/** An override's declared component before framework/path resolution. */
+interface RawDescriptor {
+  client?: HydrationMode;
+  hadComponent: boolean;
+  media?: string;
+  source: OverrideImport | null;
+}
+
+const emptyAnalysis = (): ComponentOverrideAnalysis => ({
+  islands: [],
+  layout: [],
+  mdx: [],
+  warnings: [],
+});
+
+const propName = (name: ts.PropertyName): string | undefined =>
+  ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+
+/** Map each local binding name to the module + exported name it came from. */
+const collectImports = (
+  sourceFile: ts.SourceFile
+): Map<string, ImportBinding> => {
+  const map = new Map<string, ImportBinding>();
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier)
+    ) {
+      continue;
+    }
+    const specifier = statement.moduleSpecifier.text;
+    const clause = statement.importClause;
+    if (!clause) {
+      continue;
+    }
+    if (clause.name) {
+      map.set(clause.name.text, { imported: "default", specifier });
+    }
+    const named = clause.namedBindings;
+    if (named && ts.isNamedImports(named)) {
+      for (const element of named.elements) {
+        map.set(element.name.text, {
+          imported: (element.propertyName ?? element.name).text,
+          specifier,
+        });
+      }
+    }
+  }
+  return map;
+};
+
+/** Unwrap `defineComponents({...})`, `({...})`, or `{...} as T` to the object. */
+const unwrapObject = (
+  expression: ts.Expression
+): ts.ObjectLiteralExpression | undefined => {
+  if (ts.isObjectLiteralExpression(expression)) {
+    return expression;
+  }
+  if (ts.isCallExpression(expression)) {
+    const [arg] = expression.arguments;
+    return arg && ts.isObjectLiteralExpression(arg) ? arg : undefined;
+  }
+  if (
+    ts.isAsExpression(expression) ||
+    ts.isParenthesizedExpression(expression)
+  ) {
+    return unwrapObject(expression.expression);
+  }
+  return undefined;
+};
+
+const findDefaultExportObject = (
+  sourceFile: ts.SourceFile
+): ts.ObjectLiteralExpression | undefined => {
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      return unwrapObject(statement.expression);
+    }
+  }
+  return undefined;
+};
+
+const probeExtension = (base: string): string | null => {
+  for (const extension of COMPONENT_EXTS) {
+    const candidate = `${base}.${extension}`;
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+
+/** Resolve a module specifier to a wrapper-importable path + framework. */
+const toImport = (
+  specifier: string,
+  imported: string,
+  dir: string
+): OverrideImport => {
+  const relative = specifier.startsWith(".") || isAbsolute(specifier);
+  let path = specifier;
+  let extension = extname(specifier).slice(1).toLowerCase();
+  if (relative) {
+    const absolute = isAbsolute(specifier)
+      ? specifier
+      : resolve(dir, specifier);
+    if (extension) {
+      path = absolute;
+    } else {
+      const probed = probeExtension(absolute);
+      path = probed ?? absolute;
+      extension = probed ? extname(probed).slice(1).toLowerCase() : "";
+    }
+  }
+  return {
+    framework: FRAMEWORK_BY_EXT[extension] ?? null,
+    name: imported,
+    path,
+  };
+};
+
+const resolveIdentifier = (
+  name: string,
+  imports: Map<string, ImportBinding>,
+  dir: string
+): OverrideImport | null => {
+  const binding = imports.get(name);
+  return binding ? toImport(binding.specifier, binding.imported, dir) : null;
+};
+
+const readDescriptor = (
+  object: ts.ObjectLiteralExpression,
+  imports: Map<string, ImportBinding>,
+  dir: string
+): RawDescriptor => {
+  const descriptor: RawDescriptor = { hadComponent: false, source: null };
+  for (const property of object.properties) {
+    if (ts.isShorthandPropertyAssignment(property)) {
+      if (property.name.text === "component") {
+        descriptor.hadComponent = true;
+        descriptor.source = resolveIdentifier(property.name.text, imports, dir);
+      }
+      continue;
+    }
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const name = propName(property.name);
+    const init = property.initializer;
+    if (name === "component") {
+      descriptor.hadComponent = true;
+      if (ts.isStringLiteral(init)) {
+        descriptor.source = toImport(init.text, "default", dir);
+      } else if (ts.isIdentifier(init)) {
+        descriptor.source = resolveIdentifier(init.text, imports, dir);
+      }
+    } else if (
+      name === "client" &&
+      ts.isStringLiteral(init) &&
+      HYDRATION_MODES.has(init.text as HydrationMode)
+    ) {
+      descriptor.client = init.text as HydrationMode;
+    } else if (name === "media" && ts.isStringLiteral(init)) {
+      descriptor.media = init.text;
+    }
+  }
+  return descriptor;
+};
+
+/** Apply cross-cutting validation and produce the final normalized override. */
+const finalize = (
+  key: string,
+  group: Group,
+  descriptor: RawDescriptor,
+  label: string,
+  identifier: boolean,
+  warnings: string[]
+): NormalizedOverride | null => {
+  const { client, media, source } = descriptor;
+
+  if (group === "islands") {
+    if (!source) {
+      warnings.push(
+        `Island override "${key}" couldn't be resolved to a file. Reference it by an imported component or a path string with an extension.`
+      );
+      return null;
+    }
+    if (!source.framework) {
+      warnings.push(
+        `Island override "${key}" (${label}) is not a React, Vue, or Svelte component; only framework components can be islands.`
+      );
+      return null;
+    }
+  }
+
+  if (client === "media" && !media) {
+    warnings.push(
+      `Override "${key}" uses client: "media" but no \`media\` query was given; it will hydrate as if \`client: "load"\`.`
+    );
+  }
+
+  if (client === "only" && source && !source.framework) {
+    warnings.push(
+      `Override "${key}" uses client: "only" but its framework couldn't be inferred; reference a .tsx/.jsx/.vue/.svelte file.`
+    );
+  }
+
+  if (client && !source) {
+    warnings.push(
+      `Override "${key}" declares client: "${client}" but its component couldn't be resolved to a file, so it can't hydrate. Reference it by an imported component or a path string.`
+    );
+    return { identifier, key, source: null };
+  }
+
+  if (!client && source?.framework) {
+    warnings.push(
+      `Override "${key}" points to a ${FRAMEWORK_LABEL[source.framework]} component (${label}) but has no hydration mode, so it renders as static HTML with no interactivity. Add one, e.g. \`${key}: { component: ${JSON.stringify(label)}, client: "load" }\`.`
+    );
+  }
+
+  return {
+    identifier,
+    key,
+    ...(client ? { client } : {}),
+    ...(media ? { media } : {}),
+    source,
+  };
+};
+
+const normalizeEntry = (
+  entry: ts.ObjectLiteralElementLike,
+  group: Group,
+  imports: Map<string, ImportBinding>,
+  dir: string,
+  warnings: string[]
+): NormalizedOverride | null => {
+  const defaultClient: HydrationMode | undefined =
+    group === "islands" ? "visible" : undefined;
+
+  if (ts.isShorthandPropertyAssignment(entry)) {
+    const name = entry.name.text;
+    return finalize(
+      name,
+      group,
+      {
+        client: defaultClient,
+        hadComponent: true,
+        source: resolveIdentifier(name, imports, dir),
+      },
+      name,
+      true,
+      warnings
+    );
+  }
+
+  if (!ts.isPropertyAssignment(entry)) {
+    return null;
+  }
+  const key = propName(entry.name);
+  if (!key) {
+    return null;
+  }
+  const value = entry.initializer;
+
+  if (ts.isIdentifier(value)) {
+    return finalize(
+      key,
+      group,
+      {
+        client: defaultClient,
+        hadComponent: true,
+        source: resolveIdentifier(value.text, imports, dir),
+      },
+      value.text,
+      true,
+      warnings
+    );
+  }
+  if (ts.isStringLiteral(value)) {
+    return finalize(
+      key,
+      group,
+      {
+        client: defaultClient,
+        hadComponent: true,
+        source: toImport(value.text, "default", dir),
+      },
+      value.text,
+      false,
+      warnings
+    );
+  }
+  if (ts.isObjectLiteralExpression(value)) {
+    const descriptor = readDescriptor(value, imports, dir);
+    if (!descriptor.hadComponent) {
+      warnings.push(
+        `Override "${key}" is an object without a \`component\` field; expected \`{ component, client }\`.`
+      );
+      return null;
+    }
+    if (!descriptor.source) {
+      warnings.push(
+        `Override "${key}"'s \`component\` couldn't be resolved to a file. Reference an imported component or a path string with an extension.`
+      );
+      return null;
+    }
+    return finalize(
+      key,
+      group,
+      { ...descriptor, client: descriptor.client ?? defaultClient },
+      key,
+      false,
+      warnings
+    );
+  }
+
+  // An inline function/expression: keep it on the runtime object (static only).
+  return { identifier: false, key, source: null };
+};
+
+/**
+ * Parse a user `components.ts`/`.tsx` and return its normalized overrides. Never
+ * executes the file. On a parse failure or unrecognized shape, returns empty
+ * groups so generation falls back to the plain runtime overrides object.
+ */
+export const analyzeComponentOverrides = (
+  source: string,
+  filePath: string
+): ComponentOverrideAnalysis => {
+  const result = emptyAnalysis();
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    filePath.endsWith("tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+  );
+
+  const object = findDefaultExportObject(sourceFile);
+  if (!object) {
+    return result;
+  }
+
+  const imports = collectImports(sourceFile);
+  const dir = dirname(filePath);
+
+  for (const property of object.properties) {
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    const name = propName(property.name);
+    if (
+      !(name && (GROUPS as readonly string[]).includes(name)) ||
+      !ts.isObjectLiteralExpression(property.initializer)
+    ) {
+      continue;
+    }
+    const group = name as Group;
+    for (const entry of property.initializer.properties) {
+      const normalized = normalizeEntry(
+        entry,
+        group,
+        imports,
+        dir,
+        result.warnings
+      );
+      if (normalized) {
+        result[group].push(normalized);
+      }
+    }
+  }
+
+  return result;
+};

package/src/core/config.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import { detectMintlifyBridge } from "./bridge.ts";
 import type { BridgeDetection } from "./bridge.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
@@ -73,9 +75,15 @@ export const loadConfig = async (
   const sourceFile = bridge?.configFile ?? configFile;
   const parsed = blumeConfigSchema.safeParse(raw ?? {});
   if (!parsed.success) {
+    // Read the raw config text (when on disk) so errors carry a line/column.
+    const source =
+      sourceFile && existsSync(sourceFile)
+        ? readFileSync(sourceFile, "utf-8")
+        : undefined;
     const diagnostics = diagnosticsFromZod(parsed.error, {
       code: "BLUME_CONFIG_INVALID",
       file: sourceFile ?? undefined,
+      source,
     });
     throw new BlumeError(
       diagnostics[0] ?? {

package/src/core/data.ts

@@ -108,6 +108,20 @@ export interface BlumeDataConfig {
   structuredData: boolean;
   theme: ResolvedConfig["theme"];
   title: string;
+  /** Table-of-contents settings: whether to show it and the heading range. */
+  toc: ResolvedConfig["toc"];
+}
+
+/**
+ * The compact snapshot the layout serializes into the page for React island
+ * hooks (`blume/hooks`). Islands hydrate independently, so this is read from a
+ * `<script type="application/json" id="blume-client-data">` tag rather than
+ * React context.
+ */
+export interface BlumeClientData {
+  config: BlumeDataConfig;
+  navigation: Navigation;
+  page: { route: string; title: string };
 }
 
 /** The `blume:data` module a Blume site's custom pages import. */

package/src/core/define-components.ts

@@ -19,10 +19,17 @@ export type ComponentOverride = ComponentReference | IslandDescriptor;
 
 /** User-authored component overrides, grouped by surface. */
 export interface ComponentOverrides {
+  /**
+   * Interactive framework components made available in every `.mdx` page. Like
+   * `mdx`, but hydrated: entries default to `client: "visible"`. Shorthand for
+   * an `mdx` descriptor with a client mode, and the config-file equivalent of
+   * dropping a component in the `islands/` folder.
+   */
+  islands?: Record<string, ComponentOverride>;
+  /** Layout slot overrides (`Header`, `Sidebar`, `Footer`, ...). */
+  layout?: Record<string, ComponentOverride>;
   /** MDX component map overrides (`Callout`, `Card`, ...). */
   mdx?: Record<string, ComponentOverride>;
-  /** Layout slot overrides (`Header`, `Sidebar`, `Search`, ...). */
-  layout?: Record<string, ComponentOverride>;
 }
 
 /**