blume 1.1.2 → 1.1.3

package/src/core/schema.ts

@@ -1028,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({
   /**
@@ -1085,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
@@ -1102,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 }]`. */
@@ -1117,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(),
@@ -1205,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(),
   /**
@@ -1237,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;

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. */