blume 1.1.1 → 1.1.3

package/src/core/schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
+import type { CodeTheme } from "../markdown/themes.ts";
 import { normalizeRoute } from "../openapi/references.ts";
 import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
@@ -950,9 +951,38 @@ const githubConfigSchema = z.strictObject({
   repo: z.string(),
 });
 
+const codeThemeSchema = z.custom<CodeTheme>((value) => {
+  if (typeof value === "string") {
+    return true;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  // Token rules live in `settings` (Shiki's canonical field, also the TextMate
+  // form themes like createCssVariablesTheme() produce) or `tokenColors` (the
+  // VS Code spelling Shiki falls back to). A colors-only theme (editor fg/bg,
+  // no token rules) is also valid — Shiki renders it from `colors` alone. Each
+  // field present must have the right shape, and at least one must be present.
+  const theme = value as Record<string, unknown>;
+  const settingsValid =
+    theme.settings === undefined || Array.isArray(theme.settings);
+  const tokenColorsValid =
+    theme.tokenColors === undefined || Array.isArray(theme.tokenColors);
+  const colorsValid =
+    theme.colors === undefined ||
+    (typeof theme.colors === "object" &&
+      theme.colors !== null &&
+      !Array.isArray(theme.colors));
+  const hasContent =
+    theme.settings !== undefined ||
+    theme.tokenColors !== undefined ||
+    theme.colors !== undefined;
+  return settingsValid && tokenColorsValid && colorsValid && hasContent;
+}, "Expected a Shiki theme name or custom theme object");
+
 const codeBlockThemeSchema = z.strictObject({
-  dark: z.string().default("github-dark"),
-  light: z.string().default("github-light"),
+  dark: codeThemeSchema.default("github-dark"),
+  light: codeThemeSchema.default("github-light"),
 });
 
 const codeBlocksConfigSchema = z.strictObject({
@@ -998,6 +1028,49 @@ const lastModifiedConfigSchema = z.union([
   z.strictObject({ type: z.enum(["git", "frontmatter"]).default("git") }),
 ]);
 
+/**
+ * How the "last updated" stamp and the changelog timeline render their dates —
+ * a curated pass-through to `Intl.DateTimeFormat`, shared by both surfaces so
+ * they read alike. Defaults to `{ dateStyle: "long" }`. Both stamps format in
+ * UTC unless a `timeZone` is given, so a date reads the same regardless of the
+ * build machine's zone. `dateStyle` is a preset that can't be combined with the
+ * individual component fields (`year`, `month`, …), matching `Intl`'s own rule.
+ */
+const dateFormatConfigSchema = z
+  .strictObject({
+    /** Calendar system (e.g. `japanese`, `buddhist`). */
+    calendar: z.string().optional(),
+    /** Preset date length; mutually exclusive with the component fields. */
+    dateStyle: z.enum(["full", "long", "medium", "short"]).optional(),
+    /** Day representation. */
+    day: z.enum(["numeric", "2-digit"]).optional(),
+    /** Era representation (e.g. the Japanese imperial era). */
+    era: z.enum(["long", "short", "narrow"]).optional(),
+    /** Month representation. */
+    month: z.enum(["numeric", "2-digit", "long", "short", "narrow"]).optional(),
+    /** Numbering system (e.g. `latn`, `arab`). */
+    numberingSystem: z.string().optional(),
+    /** IANA time zone (e.g. `Asia/Tokyo`). Defaults to `UTC`. */
+    timeZone: z.string().optional(),
+    /** Weekday representation. */
+    weekday: z.enum(["long", "short", "narrow"]).optional(),
+    /** Year representation. */
+    year: z.enum(["numeric", "2-digit"]).optional(),
+  })
+  .refine(
+    (value) =>
+      value.dateStyle === undefined ||
+      (value.weekday === undefined &&
+        value.era === undefined &&
+        value.year === undefined &&
+        value.month === undefined &&
+        value.day === undefined),
+    {
+      message:
+        "dateFormat.dateStyle can't be combined with weekday/era/year/month/day; use one or the other.",
+    }
+  );
+
 /** Code-block rendering options (`markdown.code`). */
 const codeConfigSchema = z.strictObject({
   /**
@@ -1055,6 +1128,16 @@ const openapiSourceSchema = z.strictObject({
 
 export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
 
+/**
+ * Arbitrary Scalar API-reference options forwarded verbatim to the generated
+ * `<ScalarComponent>` (Scalar renderer only). A passthrough map — Blume doesn't
+ * mirror Scalar's full config surface — so keys like `localization`, `agent`,
+ * `hideTestRequestButton`, or `orderSchemaPropertiesBy` all flow through. These
+ * take precedence over Blume's own derived config (spec, theme), so this is a
+ * full escape hatch; the dedicated `theme` field is the ergonomic shorthand.
+ */
+const scalarConfigSchema = z.record(z.string(), z.unknown()).optional();
+
 /**
  * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
  * Scalar's parser and renders its own UI: one real page per operation, grouped
@@ -1072,6 +1155,8 @@ const openapiConfigSchema = z.strictObject({
   renderer: z.enum(["blume", "scalar"]).default("blume"),
   /** Where the reference mounts. */
   route: z.string().default("/reference"),
+  /** Extra Scalar config forwarded to `<ScalarComponent>` (Scalar renderer only). */
+  scalar: scalarConfigSchema,
   /** One or more specs; each renders on its own route by default. */
   sources: z.array(openapiSourceSchema).default([]),
   /** Shorthand for a single source: `sources: [{ spec }]`. */
@@ -1087,6 +1172,8 @@ const openapiConfigSchema = z.strictObject({
 const asyncapiConfigSchema = z.strictObject({
   enabled: z.boolean().default(false),
   route: z.string().default("/events"),
+  /** Extra Scalar config forwarded to `<ScalarComponent>`. */
+  scalar: scalarConfigSchema,
   sources: z.array(openapiSourceSchema).default([]),
   spec: z.string().optional(),
   theme: z.string().optional(),
@@ -1175,6 +1262,11 @@ export const blumeConfigSchema = z.strictObject({
     .optional()
     .transform((value) => normalizeBasePath(value)),
   content: contentConfigSchema.default({}),
+  /**
+   * Date presentation for the "last updated" stamp and the changelog timeline.
+   * Pass-through `Intl.DateTimeFormat` options; defaults to `{ dateStyle: "long" }`.
+   */
+  dateFormat: dateFormatConfigSchema.default({ dateStyle: "long" }),
   deployment: deploymentConfigSchema.default({}),
   description: z.string().optional(),
   /**
@@ -1207,6 +1299,8 @@ export const blumeConfigSchema = z.strictObject({
 
 /** Resolved config: every field present after defaults are applied. */
 export type ResolvedConfig = z.infer<typeof blumeConfigSchema>;
+/** Resolved `dateFormat`: the `Intl.DateTimeFormat` options both date stamps share. */
+export type ResolvedDateFormat = z.infer<typeof dateFormatConfigSchema>;
 /** Resolved `frontmatter.extend`: custom key → user-supplied schema. */
 export type FrontmatterExtend = Record<string, StandardSchema>;
 /** Resolved i18n block (present only when the project opts into i18n). */

package/src/core/types.ts

@@ -31,6 +31,22 @@ export interface Diagnostic {
   docsUrl?: string;
 }
 
+/** One discovered `examples/` file reduced to what Markdown downleveling needs. */
+export interface ExampleMarkdownEntry {
+  /** Shiki language for the fenced block — the file's extension. */
+  lang: string;
+  /** Raw example source, shown verbatim in the agent-facing code fence. */
+  source: string;
+}
+
+/**
+ * Discovered examples keyed by their `<Component path>` (the file's location
+ * under `examples/`, sans extension). Lets the agent-facing Markdown downlevel
+ * `<Component path="…" />` to the example's source, since the live preview
+ * can't survive the trip to plain Markdown.
+ */
+export type ExampleLookup = Record<string, ExampleMarkdownEntry>;
+
 /** A heading extracted from page content, used for the TOC and search. */
 export interface Heading {
   depth: number;
@@ -227,6 +243,13 @@ export interface Navigation {
   tabs: NavTab[];
   selectors: NavSelector[];
   sidebar: NavNode[];
+  /**
+   * The tree root in final path space — localized and based (`/`, `/en`,
+   * `/docs`). Tab paths arrive in the same space, so the tab sitting at this
+   * path spans the whole tree and must be scoped as the root tab, not as a
+   * section tab. Absent on older serialized graphs; treat as `/`.
+   */
+  root?: string;
   /** Pinned links shown above the sidebar sections, unscoped by tab. */
   featured: FeaturedLink[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */

package/src/markdown/index.ts

@@ -21,6 +21,8 @@ import { tableWrapPlugin } from "./table-wrap.ts";
 import { DEFAULT_CODE_THEMES } from "./themes.ts";
 import type { CodeThemes } from "./themes.ts";
 
+export type { CodeTheme, CodeThemes } from "./themes.ts";
+
 /** A Shiki transformer, derived from the upstream factories' return type. */
 type ShikiTransformer = ReturnType<typeof transformerNotationDiff>;
 

package/src/markdown/inline-code.ts

@@ -64,7 +64,7 @@ type InlineHighlighter = (
     defaultColor: false;
     lang: string;
     structure: "inline";
-    themes: { dark: string; light: string };
+    themes: CodeThemes;
   }
 ) => Promise<{ children: HastNode[] }>;
 

package/src/markdown/themes.ts

@@ -6,6 +6,11 @@
  * single home for the github fallback used when nothing is configured.
  */
 
+import type { ThemeRegistrationAny } from "shiki";
+
+/** A bundled Shiki theme name or an inline custom Shiki theme definition. */
+export type CodeTheme = string | ThemeRegistrationAny;
+
 /**
  * A light/dark Shiki theme pair (`markdown.codeBlocks.theme`). A `type` (not an
  * `interface`) so it keeps the implicit index signature Shiki's `themes`
@@ -13,8 +18,8 @@
  */
 // oxlint-disable-next-line typescript/consistent-type-definitions -- interface loses the implicit index signature Shiki's `themes` param needs
 export type CodeThemes = {
-  dark: string;
-  light: string;
+  dark: CodeTheme;
+  light: CodeTheme;
 };
 
 /** The default pair, used when `markdown.codeBlocks.theme` is unset. */

package/src/openapi/references.ts

@@ -42,6 +42,11 @@ export interface ReferenceSource {
   spec: string;
   /** Per-block Scalar theme name override, if any (Scalar renderer only). */
   theme?: string;
+  /**
+   * Arbitrary Scalar config forwarded to `<ScalarComponent>` (Scalar renderer
+   * only). Takes precedence over Blume's derived spec/theme config.
+   */
+  scalar?: Record<string, unknown>;
   /** Display options carried through to the Blume renderer. */
   display: ReferenceDisplay;
   /**
@@ -117,6 +122,7 @@ const referencesFor = (
       label,
       renderer,
       route,
+      scalar: block.scalar,
       slug: routeSlug(route),
       spec: source.spec,
       theme: block.theme,

package/src/openapi/scalar.ts

@@ -161,6 +161,10 @@ export const buildReferenceFiles = async (options: {
         configuration: {
           ...spec.config,
           ...themeConfiguration(config, ref.theme),
+          // Author-supplied Scalar options win outright — a full escape hatch
+          // over Blume's derived spec/theme config (localization, agent,
+          // hideTestRequestButton, orderSchemaPropertiesBy, and the rest).
+          ...ref.scalar,
         },
         dataImport: `${"../".repeat(depth + 1)}generated/data.json`,
         route: ref.route,

package/src/registry/eject.ts

@@ -9,7 +9,7 @@ import { buildRawMarkdown } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
 import { planComponentSlots } from "../astro/component-slots.ts";
-import { discoverExamples } from "../astro/examples.ts";
+import { discoverExamples, exampleMarkdownLookup } from "../astro/examples.ts";
 import {
   buildRuntimeData,
   collectStaged,
@@ -292,6 +292,11 @@ export const eject = async (
   const exportPdf = config.export.pdf;
   const exportEpub = config.export.epub;
 
+  // Discover examples first and expose them on the project, so the agent-facing
+  // Markdown built below (raw `.md`, MCP) downlevels `<Component>` to its source.
+  const examples = await discoverExamples(root, config.examples.source);
+  project.examples = exampleMarkdownLookup(examples.examples);
+
   const [
     pages,
     needsReactRaw,
@@ -300,7 +305,6 @@ export const eject = async (
     userExamplesCss,
     rawMarkdown,
     islands,
-    examples,
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
@@ -311,7 +315,6 @@ export const eject = async (
     readExamplesCss(root, config.examples.css),
     buildRawMarkdown(project),
     discoverIslands(root),
-    discoverExamples(root, config.examples.source),
   ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.

package/src/theme/entry.ts

@@ -247,6 +247,13 @@ ${THEME_MAPPING}
   letter-spacing: 0;
 }
 
+/* A heading can carry one long unbreakable token — an OpenAPI operation's title
+   is \`METHOD /very/long/{path}\` when the spec sets no summary — which would run
+   off the content column. Break it across lines instead of overflowing. */
+.prose :where(h1, h2, h3, h4, h5, h6) {
+  overflow-wrap: break-word;
+}
+
 .prose :where(h1) {
   font-size: 3rem;
   line-height: 1.1;

package/src/theme/twoslash.ts

@@ -43,6 +43,16 @@ const OVERRIDES = `
   padding-right: 1.25rem;
 }
 
+/* Twoslash blocks keep \`overflow: visible\` so popups can escape, which means
+   long lines can't scroll — they'd push past the viewport on narrow screens.
+   Wrap them on mobile instead; hover popups still position against the token. */
+@media (max-width: 640px) {
+  .prose pre.twoslash code {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+}
+
 /* The rich renderer renders each popup's type signature as a nested Shiki
    pre. Strip the code-block chrome (border, radius, padding, background) so it
    sits flush inside the popup, which owns the frame. */