blume 1.1.2 → 1.1.4

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/render-mdx.ts

@@ -11,13 +11,14 @@ import type { ApiOperationRef, ApiSpecData } from "./model.ts";
  * omit their own top heading.
  */
 
-// Neutralize the few characters MDX treats specially (`{` expressions, `<` JSX)
-// so an arbitrary spec description can be embedded in the body verbatim without
-// breaking compilation. They render as their literal selves.
-const MDX_UNSAFE = /[<>{}]/gu;
+// Neutralize the few characters MDX treats specially (`{` expressions, `<`
+// JSX) so an arbitrary spec description can be embedded in the body verbatim
+// without breaking compilation. They render as their literal selves. `>` is
+// deliberately not escaped: it isn't MDX-special on its own, and escaping it
+// turns a `> Note:` blockquote into literal "&gt; Note:" text.
+const MDX_UNSAFE = /[<{}]/gu;
 const ENTITIES: Record<string, string> = {
   "<": "&lt;",
-  ">": "&gt;",
   "{": "&#123;",
   "}": "&#125;",
 };
@@ -28,8 +29,12 @@ const MDX_ESM_KEYWORD = /^(?<keyword>import|export)\b/gmu;
 // Backtick code — inline spans and fences alike — is already literal in MDX,
 // and entities are NOT decoded inside it, so escaping there would render the
 // entity text verbatim (`/pets/&#123;petId&#125;`). Matching any balanced
-// backtick run covers `code`, ``code``, and ```fences``` in one shot.
-const BACKTICK_CODE = /(?<bt>`+)[\s\S]*?\k<bt>/gu;
+// backtick run covers `code`, ``code``, and ```fences``` in one shot. Both
+// runs are pinned by the backtick lookarounds: CommonMark pairs a span only
+// with an *equal-length* run, so without them a lone backtick would "close" on
+// the first backtick of a longer fence run — leaving `{` in the real prose
+// unescaped (a compile error) and escaping entities into the fence body.
+const BACKTICK_CODE = /(?<!`)(?<bt>`+)(?!`)[\s\S]*?(?<!`)\k<bt>(?!`)/gu;
 
 const escapeProse = (text: string): string =>
   text

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