blume 2.0.2 → 2.0.3

package/src/og/derive.ts

@@ -2,9 +2,9 @@
  * Bridges `theme.fonts` into the OG card renderer. A site that explicitly
  * picks its typefaces gets matching cards (and non-Latin coverage) without
  * configuring `seo.og.fonts`; untouched defaults derive nothing, so plain
- * sites keep Takumi's built-in font and gain no build-time font fetch. Locales
- * in scripts that font can't draw (Japanese, Hindi, Russian, …) add a Noto
- * fallback for their script either way.
+ * sites keep Takumi's built-in font. Either way every card gets a Noto
+ * fallback stack for the scripts that font can't draw (Japanese, Hindi,
+ * Russian, …), which it fetches only when its text needs one.
  */
 
 import { existsSync } from "node:fs";
@@ -19,9 +19,10 @@ import type {
 import { GOOGLE_FONTS, isFontSlug, localeFontSubsets } from "../theme/fonts.ts";
 import type { OgFont, OgFontFamilies, OgLocalFont } from "./card.ts";
 
-/** Fonts plus per-role families for the generated OG endpoint. */
+/** Fonts, script fallbacks, and per-role families for the OG endpoint. */
 export interface DerivedOgFonts {
   families?: OgFontFamilies;
+  fallbacks?: OgFallbackFont[];
   fonts: OgFont[];
 }
 
@@ -165,17 +166,17 @@ export const deriveOgFonts = (
 /**
  * The family Takumi renders a card in when no font is loaded: its embedded
  * Geist, which covers Latin only. Naming it keeps a card's Latin text in that
- * face once locale fallbacks are loaded, since Takumi otherwise tries loaded
- * fonts first; a glyph Geist lacks still falls back to them. Were Takumi to
- * rename it, the name would resolve to nothing and cards would fall back to
- * the loaded fonts, never to tofu.
+ * face once fallbacks are loaded, since Takumi otherwise tries loaded fonts
+ * first; a glyph Geist lacks still falls back to them. Were Takumi to rename
+ * it, the name would resolve to nothing and cards would fall back to the
+ * loaded fonts, never to tofu.
  */
 const BUILT_IN_FAMILY = "Geist";
 
 /**
  * The Google Noto family that draws each language's script, keyed by BCP 47
  * language subtag, for scripts beyond the Latin, Cyrillic, Greek, and
- * Vietnamese that `Noto Sans` covers (see {@link localeOgFonts}). Keep keys
+ * Vietnamese that `Noto Sans` covers (see {@link localeFamily}). Keep keys
  * alphabetical.
  */
 const SCRIPT_FAMILIES = {
@@ -219,8 +220,8 @@ const isScriptLanguage = (
 ): language is keyof typeof SCRIPT_FAMILIES =>
   Object.hasOwn(SCRIPT_FAMILIES, language);
 
-/** A locale fallback: a Google family at the weights the card renders. */
-export interface LocaleOgFont {
+/** A script fallback: a Google family at the weights the card renders. */
+export interface OgFallbackFont {
   name: string;
   weight: number[];
 }
@@ -246,16 +247,28 @@ const localeFamily = (locale: string): string | null => {
 };
 
 /**
- * The fallback card fonts the configured locales' scripts need, at the card's
- * weights. Takumi's built-in font covers only basic Latin, so without these a
- * Japanese or Hindi page's card renders every glyph as tofu. The renderer
- * fetches only the glyph subsets a card's text uses, so an English card on
- * the same site pulls nothing extra.
+ * Every script's fallback, in the order a card tries them: `Noto Sans` for
+ * extended Latin, Cyrillic, Greek, and Vietnamese, then a family per script.
+ * The CJK families all draw Han ideographs, so the first one wins them —
+ * Japanese forms, unless a configured locale moves its own family ahead.
  */
-export const localeOgFonts = (locales: string[]): LocaleOgFont[] => {
+const DEFAULT_FALLBACKS = [
+  "Noto Sans",
+  ...new Set(Object.values(SCRIPT_FAMILIES)),
+  "Noto Sans TC",
+];
+
+/**
+ * The card's script fallbacks, at the card's weights: each configured
+ * locale's family first, so a Chinese site draws Han in Chinese forms, then
+ * every other script's, so a page in a language the site never configured
+ * still renders instead of tofu. Takumi's built-in font covers only basic
+ * Latin; the card fetches these only when its text needs a glyph beyond it,
+ * and then only the families and subsets that glyph needs.
+ */
+export const ogFallbackFonts = (locales: string[]): OgFallbackFont[] => {
   const names = new Set<string>();
-  for (const locale of locales) {
-    const family = localeFamily(locale);
+  for (const family of [...locales.map(localeFamily), ...DEFAULT_FALLBACKS]) {
     if (family) {
       names.add(family);
     }
@@ -272,27 +285,24 @@ const ogFontName = (font: OgFont): string =>
   isGoogleFamilyName(font) ? font : font.name;
 
 /**
- * `derived` plus the locale fallbacks it doesn't already load. A card that
+ * `derived` plus the script fallbacks it doesn't already load. A card that
  * names no family is pinned to {@link BUILT_IN_FAMILY}, so its Latin text
  * keeps the face it had before any fallback was loaded.
  */
-const withLocaleFonts = (
+const withFallbacks = (
   derived: DerivedOgFonts,
   locales: string[]
 ): DerivedOgFonts => {
   const loaded = new Set(derived.fonts.map(ogFontName));
-  const fallbacks = localeOgFonts(locales).filter(
-    (font) => !loaded.has(ogFontName(font))
-  );
-  if (fallbacks.length === 0) {
-    return derived;
-  }
   return {
+    fallbacks: ogFallbackFonts(locales).filter(
+      (font) => !loaded.has(font.name)
+    ),
     families: derived.families ?? {
       body: BUILT_IN_FAMILY,
       title: BUILT_IN_FAMILY,
     },
-    fonts: [...derived.fonts, ...fallbacks],
+    fonts: derived.fonts,
   };
 };
 
@@ -307,8 +317,8 @@ export const resolveOgFontSources = (fonts: OgFont[], root: string): OgFont[] =>
  * always wins (including `[]` to opt out, keeping the card's role styling
  * untouched); otherwise a site that explicitly set `theme.fonts` gets its
  * display/body fonts derived so cards match the site without extra config,
- * and either way the configured locales add a fallback for each script the
- * built-in font can't draw.
+ * and either way every card gets the script fallbacks, the configured
+ * locales' first.
  */
 export const resolveOgFonts = (
   options: {
@@ -328,7 +338,7 @@ export const resolveOgFonts = (
   const derived = options.themeFontsConfigured
     ? deriveOgFonts(options.themeFonts, root)
     : { fonts: [] };
-  return withLocaleFonts(derived, options.locales ?? []);
+  return withFallbacks(derived, options.locales ?? []);
 };
 
 /**

package/src/og/index.ts

@@ -11,4 +11,5 @@ export type {
   OgCardPalette,
   OgFont,
   OgFontFamilies,
+  OgGoogleFont,
 } from "./card.ts";

package/src/openapi/asyncapi.ts

@@ -46,7 +46,8 @@ export interface AsyncApiChannelObject {
   messages?: Record<string, AsyncApiRefLike>;
   parameters?: Record<string, AsyncApiRefLike>;
   servers?: AsyncApiRefLike[];
-  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+  bindings?: Record<string, AsyncApiSpecValue>;
   [key: string]: AsyncApiSpecValue;
 }
 
@@ -61,7 +62,8 @@ export interface AsyncApiOperationObject {
   tags?: { name?: string; description?: string }[];
   security?: AsyncApiRefLike[];
   messages?: AsyncApiRefLike[];
-  bindings?: Record<string, Record<string, AsyncApiSpecValue>>;
+  /** Protocol-keyed binding objects, or a `$ref` to a components entry. */
+  bindings?: Record<string, AsyncApiSpecValue>;
   [key: string]: AsyncApiSpecValue;
 }
 

package/src/openapi/model.ts

@@ -260,9 +260,18 @@ const isOperation = (
   value: OperationObject | undefined
 ): value is OperationObject => typeof value === "object" && value !== null;
 
-/** A declared tag whose `name` really is a string at runtime, type aside. */
-const hasTagName = (tag: SpecTag): tag is SpecTag =>
-  typeof tag.name === "string";
+/** Whether a spec value is text YAML may have read as a number. */
+const isText = <Value>(value: Value): value is Value & (string | number) =>
+  typeof value === "string" || typeof value === "number";
+
+/**
+ * A spec field that names something, as a string. YAML reads an unquoted
+ * `operationId: 404` or `tags: [2024]` as a number, which still names the
+ * operation or tag; anything else a hand-written spec puts there counts as
+ * absent.
+ */
+const specText = <Value>(value: Value): string | undefined =>
+  isText(value) ? String(value) : undefined;
 
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
@@ -295,9 +304,6 @@ export const tagSlugger = (): ((name: string) => string) => {
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
 
-/** A document's declared tag entry (`tags[n]`). */
-type SpecTag = NonNullable<ApiDocument["tags"]>[number];
-
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
   operations: ApiOperationRef[];
@@ -391,9 +397,10 @@ export const extractOperations = (
 ): ExtractedOperations => {
   const warnings: string[] = [];
   const tagMeta = new Map(
-    (document.tags ?? [])
-      .filter(hasTagName)
-      .map((tag) => [tag.name, tag.description ?? ""])
+    (document.tags ?? []).flatMap((tag): [string, string][] => {
+      const name = specText(tag.name);
+      return name === undefined ? [] : [[name, tag.description ?? ""]];
+    })
   );
   const collector = operationCollector(baseRoute, tagMeta);
 
@@ -413,15 +420,16 @@ export const extractOperations = (
       if (!isOperation(operation)) {
         continue;
       }
+      const operationId = specText(operation.operationId);
       collector.add({
         deprecated: operation.deprecated ?? false,
-        description: operation.description ?? "",
-        key: operationKey(method, path, operation.operationId),
+        description: specText(operation.description) ?? "",
+        key: operationKey(method, path, operationId),
         method,
-        operationId: operation.operationId,
+        operationId,
         path,
-        summary: operation.summary ?? "",
-        tag: operation.tags?.[0] ?? UNTAGGED,
+        summary: specText(operation.summary) ?? "",
+        tag: specText(operation.tags?.[0]) ?? UNTAGGED,
       });
     }
   }

package/src/openapi/proxy.ts

@@ -12,25 +12,52 @@
  * network and stays safe to bundle into the generated endpoint file.
  */
 
+import { PROXY_HEADERS_HEADER } from "../components/openapi/request.ts";
 import { readCappedBody } from "../core/request-body.ts";
 
 /**
- * Request headers never forwarded upstream: hop-by-hop headers describe this
- * connection (not the upstream one), `host`/`origin`/`referer` would leak or
- * misattribute the docs site, and `cookie` would forward reader credentials
- * to an arbitrary target. `accept-encoding`/`content-length` are recomputed
- * by the runtime's own fetch.
+ * Request headers never forwarded upstream, even when the playground names
+ * them: hop-by-hop headers describe this connection (not the upstream one),
+ * `host`/`origin`/`referer` would leak or misattribute the docs site, `cookie`
+ * would forward reader credentials to an arbitrary target, and the rest are
+ * set or rewritten by the platform in front of the docs server — the
+ * reader's address, the edge's own identity — whatever the browser sent.
+ * `accept-encoding`/`content-length` are recomputed by the runtime's own
+ * fetch.
  */
 const REQUEST_DROP = {
   "accept-encoding": true,
+  "cdn-loop": true,
   connection: true,
   "content-length": true,
   cookie: true,
+  forwarded: true,
   host: true,
+  "keep-alive": true,
   origin: true,
+  "proxy-authorization": true,
   referer: true,
+  te: true,
+  trailer: true,
+  "transfer-encoding": true,
+  "true-client-ip": true,
+  upgrade: true,
+  via: true,
+  "x-client-ip": true,
+  "x-real-ip": true,
 } satisfies Record<string, true>;
 
+/**
+ * Platform header families, dropped like {@link REQUEST_DROP}: Cloudflare's
+ * (`cf-connecting-ip`, the Access `cf-access-jwt-assertion`), the
+ * `x-forwarded-*` set, Vercel's (`x-vercel-oidc-token`), Netlify's, Fly's,
+ * and AWS load balancers' (`x-amzn-oidc-data`).
+ */
+const PLATFORM_HEADER = /^(?:cf-|x-forwarded-|x-vercel-|x-nf-|fly-|x-amzn-)/u;
+
+/** The {@link PROXY_HEADERS_HEADER} name as `Headers` iterates it. */
+const DECLARED = PROXY_HEADERS_HEADER.toLowerCase();
+
 /**
  * Upstream response headers never returned to the browser: the runtime's
  * fetch already decoded the body (so `content-encoding`/`content-length` no
@@ -99,20 +126,45 @@ const DOCUMENT_TYPE =
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
 
-/** Copy headers, skipping the given denylist (names are already lowercase). */
+/**
+ * Copy headers, skipping the given denylist and any name `keep` rejects
+ * (names are already lowercase).
+ */
 const filterHeaders = (
   source: Headers,
-  drop: Record<string, true>
+  drop: Record<string, true>,
+  keep: (name: string) => boolean = () => true
 ): Headers => {
   const headers = new Headers();
   for (const [name, value] of source) {
-    if (!drop[name]) {
+    if (!drop[name] && keep(name)) {
       headers.set(name, value);
     }
   }
   return headers;
 };
 
+/**
+ * The headers to send upstream: only those the playground set itself, which
+ * it names in {@link PROXY_HEADERS_HEADER}. Forwarding everything else minus
+ * a denylist would hand the documented API whatever the browser and the
+ * platform attach on their own — the HTTP Basic credentials of a docs site
+ * behind a password (a same-origin fetch with no `Authorization` of its own
+ * carries them), a Cloudflare Access assertion, a Vercel OIDC token.
+ */
+const forwardedHeaders = (source: Headers): Headers => {
+  const named = new Set(
+    (source.get(DECLARED) ?? "")
+      .split(",")
+      .map((name) => name.trim().toLowerCase())
+  );
+  return filterHeaders(
+    source,
+    REQUEST_DROP,
+    (name) => named.has(name) && !PLATFORM_HEADER.test(name)
+  );
+};
+
 /** A 403 for a target no configured spec declares as one of its servers. */
 const forbidden = (origin: string): Response =>
   Response.json(
@@ -186,7 +238,8 @@ const followUpstream = async (args: {
 /**
  * Build the `/_api-proxy` fetch handler. The client sends its REAL method,
  * headers, and body to `?url=<encodeURIComponent(target)>`; the handler
- * forwards them (minus {@link REQUEST_DROP}) and mirrors the upstream response
+ * forwards the method, the body, and the headers the client names (see
+ * {@link forwardedHeaders}), and mirrors the upstream response
  * (minus {@link RESPONSE_DROP}) with an `x-blume-proxy` marker. An unreachable
  * upstream is a 502 with a JSON `error`.
  *
@@ -252,7 +305,7 @@ export const createPlaygroundProxyHandler = (
         allowed,
         body,
         fetchImpl,
-        headers: filterHeaders(request.headers, REQUEST_DROP),
+        headers: forwardedHeaders(request.headers),
         hop: 0,
         method: request.method,
         signal: AbortSignal.timeout(timeoutMs),

package/src/openapi/render-mdx.ts

@@ -126,6 +126,45 @@ const mdxSafe = (text: string): string => {
   return out + escapeProse(text.slice(cursor));
 };
 
+// A fence opener: up to three columns of indentation, then a run of three or
+// more backticks or tildes.
+const FENCE_OPEN = /^ {0,3}(?<fence>`{3,}|~{3,})/u;
+
+/**
+ * Close a fenced code block the text leaves open. An unclosed fence runs to
+ * the end of the document, so the component appended after a description
+ * would render as code, and the page would lose its parameters, responses,
+ * and playground. Only the last top-level block can run that far — a fence in
+ * a quote or list closes with its container — and it's read from the same
+ * `<`-masked parse as `mdxSafe`, since the emitted MDX has no HTML blocks to
+ * hide a fence in.
+ */
+const closeOpenFence = (text: string): string => {
+  const last = fromMarkdown(text.replaceAll("<", HTML_MASK)).children.at(-1);
+  if (last?.type !== "code") {
+    return text;
+  }
+  // fromMarkdown always stamps positions; 0 is an unreachable guard.
+  const block = text.slice(last.position?.start.offset ?? 0);
+  const fence = FENCE_OPEN.exec(block)?.groups?.fence;
+  // No fence: indented code, which MDX reads as a paragraph.
+  if (!fence) {
+    return text;
+  }
+  const lines = block.split("\n");
+  const closer = new RegExp(
+    `^ {0,3}${fence[0]}{${fence.length},}[ \\t\\r]*$`,
+    "u"
+  );
+  return lines.length > 1 && closer.test(lines.at(-1) ?? "")
+    ? text
+    : `${text}\n${fence}`;
+};
+
+/** Spec prose as MDX that is safe to follow with a component. */
+const descriptionMdx = (text: string): string =>
+  mdxSafe(closeOpenFence(text.trim()));
+
 /**
  * Frontmatter emitted for one operation or overview page. Boolean flags are
  * assigned only when set, so absent keys stay absent in the staged MDX.
@@ -249,7 +288,7 @@ const operationDescription = (
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
-    ? `${mdxSafe(description.trim())}\n\n${component}`
+    ? `${descriptionMdx(description)}\n\n${component}`
     : component;
 
 export const operationMdx = (
@@ -365,7 +404,7 @@ export const overviewMdx = (
       continue;
     }
     const description = tag.description.trim()
-      ? [mdxSafe(tag.description.trim())]
+      ? [descriptionMdx(tag.description)]
       : [];
     tagSections.push(
       [