blume 2.0.2 → 2.0.3

package/src/components/openapi/request.ts

@@ -1,3 +1,14 @@
+import {
+  defaultExplode,
+  defaultStyle,
+  isJsonObject,
+  memberText,
+  parseStyledValue,
+  queryPairs,
+  styledValue,
+  templateValue,
+} from "./param-style.ts";
+import type { JsonValue } from "./param-style.ts";
 import type { RequestSample } from "./snippets.ts";
 
 /**
@@ -10,7 +21,18 @@ import type { RequestSample } from "./snippets.ts";
  * byte-for-byte what gets sent.
  */
 
-export interface PlaygroundParam {
+/**
+ * How a parameter or form-body field serializes, as far as the spec says:
+ * the request builder applies the OpenAPI defaults for what it leaves out.
+ */
+export interface ParamSerialization {
+  /** The spec's `style`; else the location's default. */
+  style?: string;
+  /** The spec's `explode`; else the style's default. */
+  explode?: boolean;
+}
+
+export interface PlaygroundParam extends ParamSerialization {
   name: string;
   in: "path" | "query" | "header";
   required: boolean;
@@ -49,9 +71,14 @@ export interface PlaygroundBody {
   contentType: string;
   /** Present when the schema is a flat object of primitives -> typed fields UI. */
   fields?: PlaygroundBodyField[];
-  /** Pretty-printed example JSON prefill for the raw editor; "" when none. */
+  /**
+   * Prefill for the raw editor: pretty-printed example JSON, or a raw media
+   * type's (`text/plain`, XML) string example verbatim; "" when none.
+   */
   example: string;
   schema?: ValidationSchema;
+  /** A form-urlencoded body's per-field `encoding` (`style`/`explode`). */
+  encoding?: Record<string, ParamSerialization>;
 }
 
 export type AuthKind = "bearer" | "basic" | "apiKey" | "oauth2";
@@ -103,6 +130,38 @@ export interface RequestValues {
 export const paramKey = (p: { in: string; name: string }): string =>
   `${p.in}:${p.name}`;
 
+/**
+ * The request header a proxied send names the headers the playground set in,
+ * comma-separated. Blume's built-in proxy forwards those and nothing else, so
+ * credentials the browser attaches on its own — HTTP Basic auth for a docs
+ * site behind a password, platform headers added in front of the docs server
+ * — never reach the documented API.
+ */
+export const PROXY_HEADERS_HEADER = "X-Blume-Proxy-Headers";
+
+/**
+ * How a body's media type is put on the wire: JSON as the editor text,
+ * `application/x-www-form-urlencoded` as `name=value` pairs, and
+ * `multipart/form-data` as form parts — both from the editor's JSON object —
+ * and any other type (`text/plain`, XML) as the raw text.
+ */
+export type BodyEncoding = "json" | "form" | "multipart" | "raw";
+
+/** A `+json` suffix or a `json` subtype: `application/json`, `application/vnd.api+json`. */
+const JSON_MEDIA_TYPE = /[+/]json$/u;
+
+/** The {@link BodyEncoding} a body's media type (parameters ignored) takes. */
+export const bodyEncoding = (contentType: string): BodyEncoding => {
+  const type = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+  if (type === "application/x-www-form-urlencoded") {
+    return "form";
+  }
+  if (type === "multipart/form-data") {
+    return "multipart";
+  }
+  return JSON_MEDIA_TYPE.test(type) ? "json" : "raw";
+};
+
 /** Values pre-filled from the model's precomputed examples; auth entries empty. */
 export const defaultValues = (model: PlaygroundModel): RequestValues => ({
   auth: Object.fromEntries(
@@ -197,48 +256,119 @@ const applyAuth = (
   }
 };
 
-/** The raw editor text to send, with a parsed mirror when it is valid JSON. */
+/**
+ * A form-urlencoded body's `name=value` pairs: each field serialized like a
+ * query parameter, under the `encoding` the spec declares for it (`form`,
+ * exploded, by default — so a list repeats its name).
+ */
+const urlencodedBody = (
+  value: { [key: string]: JsonValue },
+  encoding: PlaygroundBody["encoding"]
+): string =>
+  Object.entries(value)
+    .flatMap(([name, member]) => {
+      const style = encoding?.[name]?.style ?? "form";
+      return queryPairs(
+        name,
+        styledValue(member),
+        style,
+        encoding?.[name]?.explode ?? defaultExplode(style)
+      );
+    })
+    .join("&");
+
+/** Multipart form parts in order: a list contributes one part per item. */
+const multipartParts = (value: {
+  [key: string]: JsonValue;
+}): [string, string][] =>
+  Object.entries(value).flatMap(([name, member]) =>
+    Array.isArray(member)
+      ? member.map((item): [string, string] => [name, memberText(item)])
+      : [[name, memberText(member)]]
+  );
+
+/**
+ * The editor text serialized for the body's media type, with a parsed mirror
+ * when it is valid JSON. A form body is built from the editor's JSON object;
+ * text that isn't one (mid-edit, or a raw media type) is sent as written.
+ */
 const bodyFor = (
+  body: PlaygroundBody,
   text: string | undefined
-): Pick<RequestSample, "body" | "bodyValue"> => {
+): Pick<RequestSample, "body" | "bodyValue" | "formData"> => {
   if (text === undefined || text === "") {
     return {};
   }
+  const encoding = bodyEncoding(body.contentType);
+  if (encoding === "raw") {
+    return { body: text };
+  }
+  let value: JsonValue;
   try {
-    return { body: text, bodyValue: JSON.parse(text) };
+    value = JSON.parse(text);
   } catch {
-    // Not valid JSON (mid-edit or intentionally raw): still send it — the
-    // structured mirror is only a nicety for consumers of `bodyValue`.
+    // Not valid JSON (mid-edit): still send it — the structured mirror is
+    // only a nicety for consumers of `bodyValue`.
     return { body: text };
   }
+  if (encoding === "json" || !isJsonObject(value)) {
+    return { body: text, bodyValue: value };
+  }
+  return encoding === "form"
+    ? { body: urlencodedBody(value, body.encoding), bodyValue: value }
+    : { bodyValue: value, formData: multipartParts(value) };
 };
 
-/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
-export const buildRequest = (
-  model: PlaygroundModel,
-  values: RequestValues
-): RequestSample => {
-  const base = values.server.replace(TRAILING_SLASH, "");
+/**
+ * A path or header parameter's value under its `style`: an array or object
+ * parameter's JSON text becomes `dog,cat` (simple), `.dog.cat` (label), or
+ * `;tags=dog;tags=cat` (matrix) rather than its JSON.
+ */
+const styledParam = (
+  param: PlaygroundParam,
+  value: string,
+  encode: (text: string) => string
+): string => {
+  const style = param.style ?? defaultStyle(param.in);
+  return templateValue(
+    param.name,
+    parseStyledValue(value, param.type),
+    style,
+    param.explode ?? defaultExplode(style),
+    encode
+  );
+};
 
-  // Path params: an empty value substitutes the raw param name, so a blank
-  // form still renders a readable templated URL instead of `//`.
-  let resolvedPath = model.path;
+/**
+ * The model's path with each `{param}` filled in. An empty value substitutes
+ * the raw param name, so a blank form still renders a readable templated URL
+ * instead of `//`.
+ */
+const resolvePath = (model: PlaygroundModel, values: RequestValues): string => {
+  let resolved = model.path;
   for (const param of model.params) {
     if (param.in !== "path") {
       continue;
     }
     const value = values.params[paramKey(param)] ?? "";
-    resolvedPath = resolvedPath.replace(
+    resolved = resolved.replace(
       `{${param.name}}`,
-      value === "" ? param.name : encodeURIComponent(value)
+      value === "" ? param.name : styledParam(param, value, encodeURIComponent)
     );
   }
+  return resolved;
+};
 
-  // Query params with a value contribute in model order; a query-borne auth
-  // credential appends after — unless the spec also declares that name as an
-  // explicit query parameter, whose (better) example wins.
+/**
+ * The query parameters' `name=value` pairs in model order, each name added to
+ * `seen` so a query-borne credential can defer to it.
+ */
+const queryParams = (
+  model: PlaygroundModel,
+  values: RequestValues,
+  seen: Set<string>
+): string[] => {
   const query: string[] = [];
-  const seen = new Set<string>();
   for (const param of model.params) {
     if (param.in !== "query") {
       continue;
@@ -251,10 +381,37 @@ export const buildRequest = (
       continue;
     }
     seen.add(param.name);
+    const style = param.style ?? defaultStyle(param.in);
     query.push(
-      `${encodeURIComponent(param.name)}=${encodeURIComponent(value)}`
+      ...queryPairs(
+        param.name,
+        parseStyledValue(value, param.type),
+        style,
+        param.explode ?? defaultExplode(style)
+      )
     );
   }
+  return query;
+};
+
+/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
+export const buildRequest = (
+  model: PlaygroundModel,
+  values: RequestValues
+): RequestSample => {
+  // The server's trailing slash only goes when a path is joined onto it: a
+  // GraphQL endpoint (no path) is sent exactly as configured, and
+  // `https://host/graphql/` is not always the same route as `…/graphql`.
+  const base =
+    model.path === ""
+      ? values.server
+      : values.server.replace(TRAILING_SLASH, "");
+
+  // Query params with a value contribute in model order; a query-borne auth
+  // credential appends after — unless the spec also declares that name as an
+  // explicit query parameter, whose (better) example wins.
+  const seen = new Set<string>();
+  const query = queryParams(model, values, seen);
 
   // Auth first, so a spec that also declares the credential as an explicit
   // header parameter overrides it below with its own (better) example.
@@ -268,12 +425,18 @@ export const buildRequest = (
     // Required headers emit even when blank, mirroring the query rule above —
     // except a blank one never clobbers a credential auth already placed
     // under the same name.
-    if (value !== "" || (param.required && headers[param.name] === undefined)) {
+    if (value !== "") {
+      headers[param.name] = styledParam(param, value, (text) => text);
+    } else if (param.required && headers[param.name] === undefined) {
       headers[param.name] = value;
     }
   }
 
-  const { body, bodyValue } = model.body ? bodyFor(values.body) : {};
+  const { body, bodyValue, formData } = model.body
+    ? bodyFor(model.body, values.body)
+    : {};
+  // Multipart parts carry no Content-Type here: the client (curl, fetch,
+  // requests) writes it along with the boundary that separates the parts.
   if (body !== undefined && model.body) {
     headers["Content-Type"] = model.body.contentType;
   }
@@ -282,8 +445,9 @@ export const buildRequest = (
   return {
     body,
     bodyValue,
+    formData,
     headers,
     method: model.method.toUpperCase(),
-    url: `${base}${resolvedPath}${search}`,
+    url: `${base}${resolvePath(model, values)}${search}`,
   };
 };

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

@@ -55,6 +55,11 @@ export type SchemaNode =
       kind: "branches";
       label: "One of" | "Any of";
       branches: { label: string; slot: SchemaSlot }[];
+      /**
+       * Properties the schema declares beside its `oneOf`/`anyOf`, which
+       * every variant shares; absent when it declares none.
+       */
+      rows?: SchemaRow[];
     }
   | { kind: "properties"; rows: SchemaRow[] }
   | { kind: "type"; label: string };
@@ -125,19 +130,6 @@ export const schemaTree = (
           : { 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 (
@@ -155,18 +147,32 @@ export const schemaTree = (
         : 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,
-          })),
-        },
+    const rows: SchemaRow[] = properties.map(([name, property]) => ({
+      children: rowChildren(property),
+      name,
+      required: required.has(name),
+      schema: property,
+    }));
+    // Shared properties beside a `oneOf`/`anyOf` (`amount` and `currency`
+    // next to `Card | BankAccount`) render above the variants, planned first
+    // as they read first.
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (branches) {
+      const node: Extract<SchemaNode, { kind: "branches" }> = {
+        branches: branches.map((branch, index) => ({
+          label: typeLabel(branch) || `Option ${index + 1}`,
+          slot: table(branch, ancestors),
+        })),
+        kind: "branches",
+        label: schema.oneOf ? "One of" : "Any of",
       };
+      if (rows.length > 0) {
+        node.rows = rows;
+      }
+      return { node };
+    }
+    if (rows.length > 0) {
+      return { node: { kind: "properties", rows } };
     }
     return { node: { kind: "type", label: typeLabel(schema) } };
   };

package/src/components/openapi/snippets.ts

@@ -11,9 +11,18 @@ export interface RequestSample {
   method: string;
   url: string;
   headers: Record<string, string>;
-  /** JSON-stringified request body, when the operation takes one. */
+  /**
+   * The request body as sent, when the operation takes one: JSON text,
+   * form-urlencoded pairs, or a raw media type's text.
+   */
   body?: string;
   bodyValue?: unknown;
+  /**
+   * A `multipart/form-data` body's parts as `[name, value]` pairs, set
+   * instead of `body`. The request carries no Content-Type of its own for
+   * them: the client writes one with the parts' boundary.
+   */
+  formData?: [string, string][];
 }
 
 const headerLines = (
@@ -40,7 +49,11 @@ const stringLiteral = (value: string): string => JSON.stringify(value);
 
 const curlSnippet = (sample: RequestSample): string => {
   const lines = [
-    `curl -X ${sample.method} ${shellQuote(sample.url)}`,
+    // `-X HEAD` sends a HEAD but still waits for the body the response
+    // announces, so the command hangs; `--head` knows there is none.
+    sample.method === "HEAD"
+      ? `curl --head ${shellQuote(sample.url)}`
+      : `curl -X ${sample.method} ${shellQuote(sample.url)}`,
     ...headerLines(
       sample.headers,
       (key, value) => `  -H ${shellQuote(`${key}: ${value}`)}`
@@ -49,10 +62,37 @@ const curlSnippet = (sample: RequestSample): string => {
   if (sample.body) {
     lines.push(`  -d ${shellQuote(sample.body)}`);
   }
+  // `--form-string`, not `-F`: `-F` reads a value starting with `@` or `<` as
+  // a file to upload.
+  for (const [name, value] of sample.formData ?? []) {
+    lines.push(`  --form-string ${shellQuote(`${name}=${value}`)}`);
+  }
   return lines.join(" \\\n");
 };
 
+/**
+ * Whether fetch refuses to send `method` (an upper-case HTTP method). TRACE is
+ * one of the Fetch standard's forbidden methods, and the only one an OpenAPI
+ * spec can declare: browsers and Node's fetch alike throw a TypeError before
+ * any request goes out.
+ */
+export const fetchRefusesMethod = (method: string): boolean =>
+  method === "TRACE";
+
+/**
+ * The JavaScript sample for a method fetch refuses: a note in place of a call
+ * that could only throw.
+ */
+const FETCH_REFUSED_NOTE = [
+  "// fetch() refuses the TRACE method: browsers and Node both throw before",
+  "// sending, so there's no fetch sample for this operation. Send it with",
+  "// curl or another HTTP client instead.",
+].join("\n");
+
 const fetchSnippet = (sample: RequestSample): string => {
+  if (fetchRefusesMethod(sample.method)) {
+    return FETCH_REFUSED_NOTE;
+  }
   const options = [`  method: ${stringLiteral(sample.method)}`];
   if (Object.keys(sample.headers).length > 0) {
     const headers = headerLines(
@@ -71,11 +111,35 @@ const fetchSnippet = (sample: RequestSample): string => {
     // text that isn't JSON yet.
     options.push(`  body: ${stringLiteral(sample.body)}`);
   }
-  return `const response = await fetch(${stringLiteral(sample.url)}, {\n${options.join(
+  // A FormData body: fetch writes the multipart Content-Type and boundary.
+  let form = "";
+  if (sample.formData) {
+    form = [
+      "const form = new FormData();\n",
+      ...sample.formData.map(
+        ([name, value]) =>
+          `form.append(${stringLiteral(name)}, ${stringLiteral(value)});\n`
+      ),
+      "\n",
+    ].join("");
+    options.push("  body: form");
+  }
+  return `${form}const response = await fetch(${stringLiteral(sample.url)}, {\n${options.join(
     ",\n"
   )}\n});`;
 };
 
+/** The methods `requests` has a module-level helper for. */
+const PYTHON_METHODS = new Set([
+  "delete",
+  "get",
+  "head",
+  "options",
+  "patch",
+  "post",
+  "put",
+]);
+
 const pythonSnippet = (sample: RequestSample): string => {
   const args = [`    ${stringLiteral(sample.url)}`];
   if (Object.keys(sample.headers).length > 0) {
@@ -91,9 +155,24 @@ const pythonSnippet = (sample: RequestSample): string => {
     // `1e400` as `Infinity` and would otherwise diverge from the live send.
     args.push(`    data=${stringLiteral(sample.body)}`);
   }
-  return `import requests\n\nresponse = requests.${sample.method.toLowerCase()}(\n${args.join(
-    ",\n"
-  )},\n)`;
+  if (sample.formData) {
+    // `files=` is what makes requests encode multipart; a `(None, value)`
+    // tuple is a plain field rather than an upload.
+    const parts = sample.formData.map(
+      ([name, value]) =>
+        `        (${stringLiteral(name)}, (None, ${stringLiteral(value)})),\n`
+    );
+    args.push(`    files=[\n${parts.join("")}    ]`);
+  }
+  // requests has a helper per common method; anything else (TRACE) goes
+  // through `requests.request` with the method named.
+  const method = sample.method.toLowerCase();
+  let call = `requests.${method}`;
+  if (!PYTHON_METHODS.has(method)) {
+    call = "requests.request";
+    args.unshift(`    ${stringLiteral(sample.method)}`);
+  }
+  return `import requests\n\nresponse = ${call}(\n${args.join(",\n")},\n)`;
 };
 
 /** A code-sample language: config id -> label, Shiki lang, and builder. */

package/src/components/openapi/ws-client.ts

@@ -57,7 +57,10 @@ export interface WsClientOptions {
   /** Clock for frame timestamps; defaults to `Date.now`. */
   now?: () => number;
   onFrame: (frame: WsFrame) => void;
-  /** State transitions, with an optional human detail (close reason/code). */
+  /**
+   * State transitions, with an optional human detail: the close reason/code,
+   * or why a URL couldn't be dialed at all.
+   */
   onState: (state: WsState, detail?: string) => void;
 }
 
@@ -125,7 +128,20 @@ export const createWsClient = (options: WsClientOptions): WsClient => {
       return;
     }
     transition("connecting");
-    const next = create(url);
+    let next: SocketLike;
+    try {
+      next = create(url);
+    } catch (error) {
+      // `new WebSocket` throws synchronously on a URL it can't dial (a bad
+      // scheme, a malformed host), before any event could settle the state:
+      // left alone, the panel would say "Connecting…" forever with nothing to
+      // disconnect.
+      transition(
+        "error",
+        error instanceof Error ? error.message : String(error)
+      );
+      return;
+    }
     socket = next;
     // Every listener below is scoped to the socket it was wired for: a browser
     // can deliver a discarded socket's error/close/message after `disconnect`

package/src/core/base-path.ts

@@ -73,28 +73,46 @@ export const isInternalPath = (target: string): boolean =>
 export const isExternalUrl = (target: string): boolean =>
   /^https?:\/\//iu.test(target) || target.startsWith("//");
 
+/**
+ * The path part of a root-relative target, before any `?query` or `#fragment`
+ * (`/docs#install` -> `/docs`).
+ */
+const pathPart = (target: string): string => {
+  const at = target.search(/[#?]/u);
+  return at === -1 ? target : target.slice(0, at);
+};
+
+/**
+ * Whether `route`'s path already equals or sits under `base`. Only the path
+ * part is compared, so a fragment or query (`/docs#install`) doesn't hide a
+ * base written by hand.
+ */
+const isUnderBase = (base: string, route: string): boolean => {
+  const path = pathPart(route);
+  return path === base || path.startsWith(`${base}/`);
+};
+
 /**
  * Idempotently prepend `basePath` to a root-relative route. A route already
  * equal to or nested under the base is returned unchanged, so authors who write
- * the base by hand (`/docs/x`) aren't double-prefixed to `/docs/docs/x`.
+ * the base by hand (`/docs/x`, `/docs#install`) aren't double-prefixed to
+ * `/docs/docs/x`.
  */
 export const withBasePath = (basePath: string, route: string): string => {
-  if (!basePath || !isInternalPath(route)) {
-    return route;
-  }
-  if (route === basePath || route.startsWith(`${basePath}/`)) {
+  if (!basePath || !isInternalPath(route) || isUnderBase(basePath, route)) {
     return route;
   }
   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`.
+ * Mount a route Blume generates under a base, unconditionally: `basePath` for
+ * a content route, `deployment.base` for any generated URL (a sitemap entry,
+ * a feed item). {@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 generated 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` — and likewise under `deployment.base: "/docs"`.
  */
 export const mountBasePath = (basePath: string, route: string): string => {
   if (!basePath) {
@@ -117,16 +135,44 @@ export const withComposedBasePath = (
   route: string
 ): string => {
   const composed = `${deployBase}${basePath}`;
-  if (
-    composed &&
-    isInternalPath(route) &&
-    (route === composed || route.startsWith(`${composed}/`))
-  ) {
+  if (composed && isInternalPath(route) && isUnderBase(composed, route)) {
     return route;
   }
   return withBasePath(deployBase, withBasePath(basePath, route));
 };
 
+/**
+ * A path whose final segment carries a file extension (`/spec.pdf`,
+ * `/logo.svg`) — a public asset, unless a page is served there.
+ */
+const DOTTED_PATH = /\.[a-z0-9]+$/iu;
+
+/**
+ * Base a root-relative link an author wrote as if mounted at root — a content
+ * link (`markdown/base-links.ts`, `components/content/base-href.ts`) or a
+ * redirect target (`deploy/redirects.ts`) — by what it names. A page gains the
+ * composed stack ({@link withComposedBasePath}). A public asset — a path whose
+ * final segment carries a file extension, with no page served there (a dotted
+ * route like `/releases/v1.2` is still a page) — gains the deployment base
+ * alone: Astro serves `public/` under `deployment.base`, but never under
+ * `basePath`. `servesPage` answers whether a page is served at a
+ * `basePath`-prefixed, fragment-less path. Other targets pass through.
+ */
+export const withAuthoredBasePath = (
+  deployBase: string,
+  basePath: string,
+  target: string,
+  servesPage: (route: string) => boolean
+): string => {
+  if (!isInternalPath(target)) {
+    return target;
+  }
+  const path = pathPart(target);
+  return DOTTED_PATH.test(path) && !servesPage(withBasePath(basePath, path))
+    ? withBasePath(deployBase, target)
+    : withComposedBasePath(deployBase, basePath, target);
+};
+
 /**
  * Remove `basePath` from the front of a route (`/docs/guide` -> `/guide`,
  * `/docs` -> `/`). A route not under the base is returned unchanged. Inverse of

package/src/core/config-input.ts

@@ -958,13 +958,15 @@ export interface OgConfig {
    */
   enabled?: boolean;
   /**
-   * Fonts for the generated card, extending Takumi's Latin-only default so
-   * non-Latin titles (CJK, and so on) render instead of tofu. A bare string is
-   * a Google Fonts family fetched at build; the name-only object form pins
-   * weights (`700`, `[400, 700]`, or a `"100..900"` variable range) and
-   * styles; the `src` form reads a local font file from the project instead.
-   * When omitted and `theme.fonts` is explicitly configured, the theme's
-   * display and body fonts are used automatically — pass `[]` to opt out.
+   * Fonts for the generated card, replacing the default stack: Takumi's
+   * Latin-only built-in font plus a Noto fallback per script, which a card
+   * fetches only when its text needs one. A bare string is a Google Fonts
+   * family fetched at build; the name-only object form pins weights (`700`,
+   * `[400, 700]`, or a `"100..900"` variable range) and styles; the `src`
+   * form reads a local font file from the project instead. When omitted and
+   * `theme.fonts` is explicitly configured, the theme's display and body
+   * fonts are used automatically, ahead of the fallbacks — pass `[]` to opt
+   * out of both.
    */
   fonts?: (
     | string