blume 2.0.0 → 2.0.2

package/src/components/openapi/schema-tree.ts

@@ -0,0 +1,203 @@
+import {
+  objectProperties,
+  refName,
+  resolveSchema,
+  typeLabel,
+} from "./helpers.ts";
+import type { SchemaLike, SpecValue } from "./helpers.ts";
+
+/**
+ * The expansion plan behind the schema tables (`SchemaTable.astro` and
+ * `SchemaProperty.astro`). Every nested object is server-rendered in full
+ * inside a collapsed `<details>`, so the plan is the page's weight: expanding
+ * each named schema wherever it appears — stopping only at a model nested in
+ * itself — grows exponentially with cross-references (twelve schemas that
+ * each reference four others render tens of thousands of nested tables for
+ * one request body).
+ *
+ * So a named schema expands wherever it appears in the first
+ * {@link REPEAT_DEPTH} named levels, and deeper than that only where it
+ * appears first in the tree, breadth-first; a later mention shows its name
+ * alone. Beyond the first levels each named schema expands at most once, so
+ * the tree stays proportional to the spec instead of to the number of paths
+ * through it, while the shallow nesting typical specs use — `billing` and
+ * `shipping` both an `Address` — renders exactly as before.
+ */
+
+/**
+ * Named-schema nesting depth (the root being 0) up to which a named schema
+ * expands at every mention, even one already expanded elsewhere in the tree.
+ */
+export const REPEAT_DEPTH = 2;
+
+/** A place in the tree a node is planned into; filled in breadth-first. */
+export interface SchemaSlot {
+  node: SchemaNode;
+}
+
+/** One property row of an object table. */
+export interface SchemaRow {
+  name: string;
+  required: boolean;
+  schema: SchemaLike;
+  /** The row's disclosure contents; absent when the row has nothing to show. */
+  children?: SchemaSlot;
+}
+
+/** What one schema table renders. */
+export type SchemaNode =
+  /** A named schema nested inside itself. */
+  | { kind: "circular"; name: string }
+  /** A named schema expanded elsewhere in this tree: its name only. */
+  | { kind: "named"; name: string }
+  | { kind: "array"; itemsLabel: string; items?: SchemaSlot }
+  | {
+      kind: "branches";
+      label: "One of" | "Any of";
+      branches: { label: string; slot: SchemaSlot }[];
+    }
+  | { kind: "properties"; rows: SchemaRow[] }
+  | { kind: "type"; label: string };
+
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const typesOf = (schema: SchemaLike): (string | undefined)[] =>
+  Array.isArray(schema.type) ? schema.type : [schema.type];
+
+/** Whether a schema has nested fields a row can disclose. */
+const hasNestedFields = (candidate: SchemaLike): boolean =>
+  Boolean(
+    candidate.properties ||
+    candidate.allOf ||
+    candidate.oneOf ||
+    candidate.anyOf ||
+    isString(candidate.$ref)
+  );
+
+/** A named schema waiting for its breadth-first turn. */
+interface PendingRef {
+  ancestors: string[];
+  name: string;
+  schema: SchemaLike;
+  slot: SchemaSlot;
+}
+
+/** Plan the table tree for one schema (a request body, a response, a payload). */
+export const schemaTree = (
+  root: SchemaLike,
+  schemas: Record<string, SchemaLike>
+): SchemaNode => {
+  const queue: PendingRef[] = [];
+  const expanded = new Set<string>();
+
+  /**
+   * A table for `schema`, where `ancestors` are the named schemas already
+   * open above it. A `$ref` waits in the queue, so every mention at one depth
+   * is planned before any deeper one; `resolved` plans a dequeued schema's
+   * own body instead.
+   */
+  const table = (
+    schema: SchemaLike,
+    ancestors: string[],
+    resolved = false
+  ): SchemaSlot => {
+    if (!resolved && isString(schema.$ref)) {
+      const name = refName(schema.$ref);
+      if (ancestors.includes(name)) {
+        return { node: { kind: "circular", name } };
+      }
+      const slot: SchemaSlot = { node: { kind: "named", name } };
+      queue.push({ ancestors, name, schema, slot });
+      return slot;
+    }
+    if (typesOf(schema).includes("array")) {
+      // Items stay unresolved, so a self-referential item `$ref` is still
+      // recognized as the circle it is.
+      const { items } = schema;
+      return {
+        node: items
+          ? {
+              items: table(items, ancestors),
+              itemsLabel: typeLabel(items),
+              kind: "array",
+            }
+          : { itemsLabel: typeLabel({}), kind: "array" },
+      };
+    }
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (branches) {
+      return {
+        node: {
+          branches: branches.map((branch, index) => ({
+            label: typeLabel(branch) || `Option ${index + 1}`,
+            slot: table(branch, ancestors),
+          })),
+          kind: "branches",
+          label: schema.oneOf ? "One of" : "Any of",
+        },
+      };
+    }
+    // A row discloses nested structure — never a model inside itself.
+    const rowChildren = (property: SchemaLike): SchemaSlot | undefined => {
+      if (
+        isString(property.$ref) &&
+        ancestors.includes(refName(property.$ref))
+      ) {
+        return undefined;
+      }
+      const target = resolveSchema(schemas, property);
+      const items = typesOf(target).includes("array")
+        ? resolveSchema(schemas, target.items)
+        : null;
+      return hasNestedFields(target) || (items && hasNestedFields(items))
+        ? table(property, ancestors)
+        : undefined;
+    };
+    const { properties, required } = objectProperties(schema, schemas);
+    if (properties.length > 0) {
+      return {
+        node: {
+          kind: "properties",
+          rows: properties.map(([name, property]) => ({
+            children: rowChildren(property),
+            name,
+            required: required.has(name),
+            schema: property,
+          })),
+        },
+      };
+    }
+    return { node: { kind: "type", label: typeLabel(schema) } };
+  };
+
+  const tree = table(root, []);
+  // The queue grows while it drains, in depth order: every mention at one
+  // named depth is queued before the first one at the next.
+  for (const pending of queue) {
+    const depth = pending.ancestors.length;
+    if (depth > REPEAT_DEPTH && expanded.has(pending.name)) {
+      continue;
+    }
+    expanded.add(pending.name);
+    pending.slot.node = table(
+      resolveSchema(schemas, pending.schema),
+      [...pending.ancestors, pending.name],
+      true
+    ).node;
+  }
+  return tree.node;
+};
+
+/**
+ * Whether a row gets a disclosure: it has nested structure, and that structure
+ * isn't just the name of a schema expanded elsewhere (directly, or as the
+ * items of an array).
+ */
+export const rowExpands = (row: SchemaRow): boolean => {
+  const node = row.children?.node;
+  if (!node || node.kind === "named") {
+    return false;
+  }
+  return !(node.kind === "array" && node.items?.node.kind === "named");
+};

package/src/components/openapi/snippets.ts

@@ -22,26 +22,42 @@ const headerLines = (
 ): string[] =>
   Object.entries(headers).map(([key, value]) => format(key, value));
 
+/**
+ * A single-quoted POSIX shell word. Nothing expands inside single quotes — no
+ * `$`, backtick, `!`, or `\` — so a value reaches curl byte for byte; a
+ * literal `'` closes the quote, adds an escaped one, and reopens it.
+ */
+const shellQuote = (value: string): string =>
+  `'${value.replaceAll("'", String.raw`'\''`)}'`;
+
+/**
+ * A double-quoted string literal for the JavaScript and Python samples. JSON's
+ * string escapes are a subset of both languages' — a quote in a header value
+ * (`If-Match: "33a64df5"`) or a backslash becomes an escape rather than
+ * ending the literal early.
+ */
+const stringLiteral = (value: string): string => JSON.stringify(value);
+
 const curlSnippet = (sample: RequestSample): string => {
   const lines = [
-    `curl -X ${sample.method} "${sample.url}"`,
-    ...headerLines(sample.headers, (key, value) => `  -H "${key}: ${value}"`),
+    `curl -X ${sample.method} ${shellQuote(sample.url)}`,
+    ...headerLines(
+      sample.headers,
+      (key, value) => `  -H ${shellQuote(`${key}: ${value}`)}`
+    ),
   ];
   if (sample.body) {
-    // Close-quote/escaped-quote/reopen: the POSIX way to put a literal ' in a
-    // single-quoted string, so an example like "it's" doesn't break the shell.
-    const escapedBody = sample.body.replaceAll("'", String.raw`'\''`);
-    lines.push(`  -d '${escapedBody}'`);
+    lines.push(`  -d ${shellQuote(sample.body)}`);
   }
   return lines.join(" \\\n");
 };
 
 const fetchSnippet = (sample: RequestSample): string => {
-  const options = [`  method: "${sample.method}"`];
+  const options = [`  method: ${stringLiteral(sample.method)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `    "${key}": "${value}"`
+      (key, value) => `    ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     options.push(`  headers: {\n${headers}\n  }`);
   }
@@ -53,28 +69,27 @@ const fetchSnippet = (sample: RequestSample): string => {
     // and an id past 2^53 loses digits through a JS number. The string
     // literal also stays syntactically valid while the editor holds mid-edit
     // text that isn't JSON yet.
-    options.push(`  body: ${JSON.stringify(sample.body)}`);
+    options.push(`  body: ${stringLiteral(sample.body)}`);
   }
-  return `const response = await fetch("${sample.url}", {\n${options.join(
+  return `const response = await fetch(${stringLiteral(sample.url)}, {\n${options.join(
     ",\n"
   )}\n});`;
 };
 
 const pythonSnippet = (sample: RequestSample): string => {
-  const args = [`    "${sample.url}"`];
+  const args = [`    ${stringLiteral(sample.url)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
       sample.headers,
-      (key, value) => `        "${key}": "${value}"`
+      (key, value) => `        ${stringLiteral(key)}: ${stringLiteral(value)}`
     ).join(",\n");
     args.push(`    headers={\n${headers}\n    }`);
   }
   if (sample.body) {
     // Same rule as the fetch snippet: the raw text travels as a string via
-    // `data=` (JSON string escapes are a subset of Python's, so the literal is
-    // valid) rather than a `json=` dict — a Python literal re-serializes
+    // `data=` rather than a `json=` dict — a Python literal re-serializes
     // `1e400` as `Infinity` and would otherwise diverge from the live send.
-    args.push(`    data=${JSON.stringify(sample.body)}`);
+    args.push(`    data=${stringLiteral(sample.body)}`);
   }
   return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
     ",\n"

package/src/components/openapi/validate-json.ts

@@ -74,7 +74,7 @@ const walk = (
   path: string,
   errors: string[]
 ): void => {
-  if (!schema) {
+  if (!schema || (value === null && schema.nullable === true)) {
     return;
   }
   if (schema.type !== undefined && !matchesType(value, schema.type)) {

package/src/core/base-path.ts

@@ -88,6 +88,21 @@ export const withBasePath = (basePath: string, route: string): string => {
   return route === "/" ? basePath : `${basePath}${route}`;
 };
 
+/**
+ * Mount a route Blume generates from content under `basePath`,
+ * unconditionally. {@link withBasePath} leaves a route that already starts
+ * with the base alone, which is right for a link an author based by hand but
+ * wrong for a content route: with `basePath: "/docs"`, `docs/guide.md` routes
+ * to `/docs/guide` before the base and publishes at `/docs/docs/guide`, not on
+ * top of the root `guide.md`.
+ */
+export const mountBasePath = (basePath: string, route: string): string => {
+  if (!basePath) {
+    return route;
+  }
+  return route === "/" ? basePath : `${basePath}${route}`;
+};
+
 /**
  * {@link withBasePath} for the composed `deployment.base` + `basePath` stack
  * (`/base` + `/docs` serves pages at `/base/docs/x`). The hand-written-base

package/src/core/code-fences.ts

@@ -1,6 +1,6 @@
 /**
  * Fenced-code state for line scanners. Kept free of imports so request-time
- * code (the Ask AI grounding excerpts) can share it with the build-time source
+ * code (the assistant's grounding excerpts) can share it with the build-time source
  * scanners without pulling the filesystem and schema modules along.
  *
  * CommonMark allows backtick *and* tilde fences, three or more characters

package/src/core/config-input.ts

@@ -2,7 +2,7 @@ import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { AskRetrievalOptions } from "../ai/ask-context.ts";
-import type { AskAdapter } from "../ai/ask.ts";
+import type { AssistantAdapter } from "../ai/ask.ts";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { AnalyticsAdapter } from "../analytics/schema.ts";
 import type { DeploymentInput } from "../deploy/adapters/registry.ts";
@@ -488,16 +488,16 @@ export type SearchConfig = SearchProviderConfig | SearchOptions;
 // AI
 // ---------------------------------------------------------------------------
 
-/** An empty-state prompt shown before the first Ask AI question. */
-export interface AskSuggestion {
+/** An empty-state prompt shown before the first question to the assistant. */
+export interface AssistantSuggestion {
   /** Lucide icon name shown beside the suggestion. */
   icon?: string;
   /** The clickable suggestion text. */
   label: string;
 }
 
-/** How much retrieved documentation each Ask AI question carries. */
-export interface AskRetrievalConfig {
+/** How much retrieved documentation each question to the assistant carries. */
+export interface AssistantRetrievalConfig {
   /**
    * Total injected documentation characters, across all excerpts. Defaults to
    * `10000`. The single biggest lever on time-to-first-token — the model reads
@@ -518,8 +518,8 @@ export interface AskRetrievalConfig {
   maxResults?: number;
 }
 
-/** The Ask AI chat assistant. */
-export interface AskConfig {
+/** The chat assistant. */
+export interface AssistantConfig {
   /**
    * Origins allowed to call the generated endpoint from another site — a
    * marketing page that embeds an ask box, for example — or `"*"` to allow
@@ -532,10 +532,10 @@ export interface AskConfig {
    * combined with it.
    */
   cors?: string[];
-  /** Turn Ask AI on. Defaults to `false`. */
+  /** Turn the assistant on. Defaults to `false`. */
   enabled?: boolean;
   /**
-   * Existing Ask AI endpoint to call instead of generating one. This keeps a
+   * Existing assistant endpoint to call instead of generating one. This keeps a
    * Blume site static while an API backend owns retrieval, model access, rate
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
@@ -555,15 +555,15 @@ export interface AskConfig {
    * mapping, and `providerOptions` passthrough. Defaults to
    * `gateway({ model: "openai/gpt-5.5" })`.
    */
-  provider?: AskAdapter;
+  provider?: AssistantAdapter;
   /**
    * How much documentation each question carries into the model's prompt.
    * Lower values cut time-to-first-token — which dominates on a self-hosted
    * backend — at the cost of recall. Defaults keep the built-in behavior.
    */
-  retrieval?: AskRetrievalConfig;
+  retrieval?: AssistantRetrievalConfig;
   /** Starter prompts shown before the first question. */
-  suggestions?: AskSuggestion[];
+  suggestions?: AssistantSuggestion[];
 }
 
 /** What the AI Catalog (ARD) manifest carries. */
@@ -596,14 +596,14 @@ export interface LlmsTxtConfig {
   /**
    * Markdown placed after the title and summary in `llms.txt`, before the
    * page sections — the llms.txt spec's "details" block. Use it to tell
-   * agents when to reach for the product and how to call it (a "When to use"
-   * heading, the install command, the package name). Blank values are
-   * dropped.
+   * agents when to reach for the product and how to call it (the install
+   * command, the package name). The spec allows any Markdown there but
+   * headings. Blank values are dropped.
    *
    * ```ts
    * agents: {
    *   llmsTxt: {
-   *     details: "## When to use Acme\n\nUse Acme when…",
+   *     details: "Use Acme when…",
    *   },
    * }
    * ```
@@ -631,10 +631,10 @@ export interface McpConfig {
   route?: string;
 }
 
-/** Model-facing features: the Ask AI assistant and the "Open in chat" action. */
+/** Model-facing features: the assistant and the "Open in chat" action. */
 export interface AiConfig {
-  /** The Ask AI chat assistant. */
-  ask?: AskConfig;
+  /** The chat assistant. */
+  assistant?: AssistantConfig;
   /**
    * The "Open in chat" page action, which opens the current page in an AI
    * assistant pre-filled with a prompt pointing at its raw Markdown.
@@ -833,7 +833,7 @@ export type ContentSignalsConfig =
 /**
  * The machine-readable surface agents consume: the JSON API, `llms.txt`, the
  * MCP server, published skills, discovery manifests, and the robots.txt usage
- * policy. The reader-facing model features (Ask AI, Open in chat) live under
+ * policy. The reader-facing model features (the assistant, Open in chat) live under
  * `ai`.
  */
 export interface AgentsConfig {
@@ -1331,7 +1331,7 @@ export type TocConfig =
 export interface BlumeConfig {
   /** The machine-readable surface for agents: JSON API, `llms.txt`, MCP, skills, discovery. */
   agents?: AgentsConfig;
-  /** Model-facing features: the Ask AI assistant and the "Open in chat" action. */
+  /** Model-facing features: the assistant and the "Open in chat" action. */
   ai?: AiConfig;
   /**
    * Analytics adapters from `blume/analytics`, emitted into `<head>` of every
@@ -1452,10 +1452,10 @@ type _NoExtraOrMissingKeys = AssertExtends<
 // endpoint and silently ignored at request time). `Required` makes a rename in
 // either copy a missing property, which stops compiling.
 type _AskRetrievalMatchesRuntime = AssertExtends<
-  Required<AskRetrievalConfig>,
+  Required<AssistantRetrievalConfig>,
   Required<AskRetrievalOptions>
 >;
 type _AskRuntimeMatchesRetrieval = AssertExtends<
   Required<AskRetrievalOptions>,
-  Required<AskRetrievalConfig>
+  Required<AssistantRetrievalConfig>
 >;

package/src/core/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import { basename } from "pathe";
 import { z } from "zod";
 
 import type { BlumeConfig } from "./config-input.ts";
@@ -9,7 +10,7 @@ import {
   diagnosticsFromIssues,
   diagnosticsFromZod,
 } from "./diagnostics.ts";
-import { createModuleLoader } from "./load-module.ts";
+import { createDefaultExportLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
 import type { ResolvedConfig } from "./schema.ts";
@@ -68,8 +69,8 @@ import type { Diagnostic } from "./types.ts";
  * - `theme` — `accent` color, `fonts` (curated slugs, any provider family, or
  *   local font files), `radius`,
  *   `mode` (`system`/`light`/`dark`), and `background`.
- * - `markdown` — `code` (language icons, inline highlighting, line wrap),
- *   `headingAnchors`, `imageZoom`, and opt-in KaTeX `math`.
+ * - `markdown` — `code` (language icons, light/dark Shiki `theme`, line
+ *   `wrap`), `externalLinks`, `headingAnchors`, and `imageZoom`.
  * - `toc` — on-page table of contents; `true`/`false` or a heading-level range.
  * - `lastModified` — "Last updated" stamps from `git` history or frontmatter.
  * - `feedback` — the per-page "Was this helpful?" widget (on by default).
@@ -87,7 +88,7 @@ import type { Diagnostic } from "./types.ts";
  *   `flexsearch()`, `pagefind()`, `algolia({…})`, `oramaCloud({…})`,
  *   `typesense({…})`, `mixedbread({…})`, or `false`), or `{ provider,
  *   popular, indexing }` to add curated links and indexing settings.
- * - `ai` — what faces a model at read time: `ask` (the Ask AI assistant, with
+ * - `ai` — what faces a model at read time: `assistant` (the chat assistant, with
  *   a provider adapter from `blume/ai` such as `gateway()` or `openrouter()`)
  *   and `openInChat` (the "Open in chat" page action).
  * - `agents` — the machine-readable surface: `llmsTxt`, the JSON `api`, the
@@ -146,7 +147,7 @@ import type { Diagnostic } from "./types.ts";
  * });
  * ```
  *
- * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * @example An OpenAPI reference with the assistant enabled.
  * ```ts
  * import { openapi } from "blume/reference";
  *
@@ -159,7 +160,7 @@ import type { Diagnostic } from "./types.ts";
  *     }),
  *   ],
  *   agents: { llmsTxt: true },
- *   ai: { ask: { enabled: true } },
+ *   ai: { assistant: { enabled: true } },
  * });
  * ```
  *
@@ -199,7 +200,7 @@ export interface ConfigLoadResult {
   themeFontsConfigured: boolean;
 }
 
-const importConfigModule = createModuleLoader();
+const importConfigModule = createDefaultExportLoader();
 
 /**
  * The slice of a user config module probed before schema defaults apply:
@@ -290,6 +291,19 @@ export const loadConfig = async (
         severity: "error",
       });
     }
+    // Validating whatever else the module holds would build a silent default
+    // site (a bare `defineConfig({…})` call) or reject a named `config` export
+    // as an unknown key, neither of which names the actual mistake.
+    if (raw === undefined) {
+      throw new BlumeError({
+        code: "BLUME_CONFIG_INVALID",
+        file: configFile,
+        message: `${basename(configFile)} has no default export, so Blume can't read its config.`,
+        severity: "error",
+        suggestion:
+          "Export the config as the file's default: `export default defineConfig({ … })`.",
+      });
+    }
   }
 
   // Read before parsing: schema defaults erase the set-vs-defaulted distinction.

package/src/core/data.ts

@@ -122,10 +122,10 @@ export interface BlumeDataConfig {
   analytics: ResolvedConfig["analytics"];
   /** Apple touch icon, or `null` when none is configured/detected. */
   appleIcon: BlumeFavicon | null;
-  /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
-  ask: {
+  /** The assistant's empty-state suggestions, or `null` when the assistant is off. */
+  assistant: {
     endpoint: string | null;
-    suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
+    suggestions: NonNullable<ResolvedConfig["ai"]["assistant"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
   /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */