blume 1.5.1 → 1.5.2

package/src/core/schema.ts

@@ -8,6 +8,7 @@ import { normalizeXHandle } from "../seo/x-handle.ts";
 import { FONT_SLUGS, isFontSlug } from "../theme/fonts.ts";
 import { normalizeBasePath } from "./base-path.ts";
 import { uiLocaleOverridesSchema } from "./i18n-ui.ts";
+import { openInChatProviders } from "./open-in-chat.ts";
 import type { ContentSource } from "./sources/types.ts";
 import { isStandardSchema } from "./standard-schema.ts";
 import type { StandardSchema } from "./standard-schema.ts";
@@ -813,6 +814,19 @@ const aiConfigSchema = z.strictObject({
       instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
+      // How much documentation each question carries. Injected characters are
+      // the dominant term in time-to-first-token on a self-hosted backend, so
+      // these trade recall for latency. No zod defaults here: only what the
+      // user set reaches the generated (and ejected) endpoint, so omitted
+      // fields keep tracking the installed package's built-in defaults in
+      // `ai/ask-context.ts` instead of pinning today's numbers as literals.
+      retrieval: z
+        .strictObject({
+          contextBudget: z.number().int().positive().optional(),
+          excerptChars: z.number().int().positive().optional(),
+          maxResults: z.number().int().positive().optional(),
+        })
+        .optional(),
       // Empty-state prompts shown before the first question. Each renders as a
       // clickable suggestion; `icon` is an optional Lucide name beside it.
       suggestions: z
@@ -877,6 +891,28 @@ const aiConfigSchema = z.strictObject({
     .default({}),
   /** Expose the docs as an MCP server for connecting agents. */
   mcp: mcpConfigSchema.prefault({}),
+  /**
+   * The "Open in chat" page action. `true` (the default) lists every
+   * provider, `false` hides the action entirely, and an array of provider
+   * keys shows just that subset, in the given order. Normalized to the
+   * provider list so consumers read a plain array.
+   */
+  openInChat: z
+    .union([
+      z.boolean(),
+      z
+        .array(z.enum(openInChatProviders))
+        .refine((value) => new Set(value).size === value.length, {
+          message: "ai.openInChat must not repeat a provider.",
+        }),
+    ])
+    .default(true)
+    .transform((value) => {
+      if (isBoolean(value)) {
+        return value ? [...openInChatProviders] : [];
+      }
+      return value;
+    }),
   /**
    * Publish Agent Skills for discovery: a directory (resolved against the
    * project root) whose subdirectories each hold a `SKILL.md`. The build
@@ -947,6 +983,8 @@ const navigationConfigSchema = z.strictObject({
 
 export type AskAiProvider = (typeof askAiProviders)[number];
 export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
+export { openInChatProviders } from "./open-in-chat.ts";
+export type { OpenInChatProvider } from "./open-in-chat.ts";
 
 // Reader-facing "Export" page action (PDF via print, EPUB via client-side
 // generation). Off by default. Accepts a shorthand boolean to toggle both
@@ -1553,6 +1591,27 @@ const referenceConfigSchema = (defaults: {
     enabled: z.boolean().default(false),
     /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
     expandSchemas: z.boolean().default(false),
+    /**
+     * The interactive "Try it" panel on operation pages (Blume renderer). On by
+     * default; `false` hides it. The object form keeps it on and sets `proxy`,
+     * the CORS escape hatch the OpenAPI Send button routes requests through: a
+     * proxy URL, or `true` for the built-in `/_api-proxy` endpoint (which
+     * requires `deployment.output: "server"`). Booleans normalize to the object
+     * shape so consumers read `{ enabled, proxy }` directly. `proxy` is
+     * OpenAPI-only — an event composer's WebSocket connect is direct.
+     */
+    playground: z
+      .union([
+        z.boolean(),
+        z.strictObject({
+          enabled: z.boolean().default(true),
+          proxy: z.union([z.boolean(), z.string()]).default(false),
+        }),
+      ])
+      .default(true)
+      .transform((value) =>
+        isBoolean(value) ? { enabled: value, proxy: false } : value
+      ),
     /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
     renderer: z.enum(["blume", "scalar"]).default("blume"),
     /** Where the reference mounts. */

package/src/core/server-features.ts

@@ -14,6 +14,17 @@ export const serverFeatures = (config: ResolvedConfig): string[] => {
   if (config.ai.mcp.enabled) {
     features.push("MCP server");
   }
+  // The built-in playground proxy (`openapi.playground.proxy: true`) is a
+  // live fetch endpoint at `/_api-proxy`; an external proxy URL (string) or a
+  // proxy-less playground stays fully static.
+  if (
+    config.openapi.enabled &&
+    config.openapi.renderer === "blume" &&
+    config.openapi.playground.enabled &&
+    config.openapi.playground.proxy === true
+  ) {
+    features.push("API playground proxy");
+  }
   // Mixedbread (and any future provider) that proxies queries through a secret
   // server endpoint can't run on a static build.
   if (searchProviderMeta(config.search.provider).requiresServer) {

package/src/core/sources/normalize.ts

@@ -413,11 +413,18 @@ const scanLinkLine = (
     // for its text — a label that contains the same text (e.g. `[/a/b](/a/b)`)
     // would otherwise report the column inside the label.
     const targetOffset = targetOffsetIn(match[0], target, match.groups?.title);
-    links.push({
+    const entry: PageLink = {
       column: match.index + targetOffset + 1,
       line: lineNumber,
       target,
-    });
+    };
+    // `MD_LINK` matches the `[label](target)` tail of an image embed too; the
+    // preceding `!` is what marks the target as going through the image
+    // pipeline rather than resolving as a site route.
+    if (masked[match.index - 1] === "!") {
+      entry.image = true;
+    }
+    links.push(entry);
     // An image nested in the label (`[![alt](/img.png)](/target)`) carries its
     // own target; surface it too so a missing image is still caught.
     const label = match[0].slice(0, targetOffset - "](".length);
@@ -432,6 +439,7 @@ const scanLinkLine = (
           image.index +
           targetOffsetIn(image[0], imageTarget, image.groups?.title) +
           1,
+        image: true,
         line: lineNumber,
         target: imageTarget,
       });

package/src/core/types.ts

@@ -58,6 +58,10 @@ export interface Heading {
 export interface PageLink {
   /** Raw link target as written, e.g. `./foo`, `/api#auth`, `https://x.dev`. */
   target: string;
+  /** Set when the target was written as an image embed (`![alt](target)`) —
+   * only those go through the image pipeline; a plain link to the same path
+   * resolves as a site route. */
+  image?: boolean;
   /** 1-based line number in the source file. */
   line: number;
   /** 1-based column of the target within the line. */
@@ -269,9 +273,12 @@ export interface Navigation {
   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 `/`.
+   * `/docs`), and versionized for an archived version tree (`/v1.0`). Tab
+   * paths share that space except under a version, where they stay in
+   * current-docs space — so the root tab is the tab this root sits under
+   * (`isRootTab`), not necessarily the tab at this exact path, 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. */

package/src/openapi/model.ts

@@ -98,6 +98,13 @@ export interface ApiSpecData {
   codeSamples: string[];
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
+  /**
+   * The "Try it" playground: whether operation pages render it, and the
+   * resolved proxy the Send button targets — `false` for direct requests, a
+   * URL string otherwise (the built-in `/_api-proxy` route already carries
+   * the site `basePath`).
+   */
+  playground: { enabled: boolean; proxy: string | false };
 }
 
 /** The generated `blume:openapi` module: specs keyed by {@link ApiSpecData.slug}. */

package/src/openapi/proxy.ts

@@ -0,0 +1,217 @@
+/**
+ * The playground's CORS proxy. Browsers block the "Try it" panel's `fetch`
+ * whenever the documented API doesn't allow cross-origin requests from the
+ * docs site, so `openapi.playground.proxy: true` mounts this handler at
+ * `/_api-proxy` (server output only) and the client sends its real request
+ * here as `?url=<encoded target>` instead. The handler replays the request
+ * upstream and mirrors the response back, so the browser only ever talks
+ * same-origin.
+ *
+ * Kept dependency-free and `fetch`-injectable so it unit-tests without a
+ * network and stays safe to bundle into the generated endpoint file.
+ */
+
+/**
+ * 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.
+ */
+const REQUEST_DROP = {
+  "accept-encoding": true,
+  connection: true,
+  "content-length": true,
+  cookie: true,
+  host: true,
+  origin: true,
+  referer: true,
+} satisfies Record<string, true>;
+
+/**
+ * Upstream response headers never returned to the browser: the runtime's
+ * fetch already decoded the body (so `content-encoding`/`content-length` no
+ * longer describe it), hop-by-hop headers belong to the upstream connection
+ * rather than ours, and `set-cookie` would let the documented API plant
+ * cookies on the docs origin — where they'd ride along on every later docs
+ * request, including the proxy's own.
+ */
+const RESPONSE_DROP = {
+  connection: true,
+  "content-encoding": true,
+  "content-length": true,
+  "keep-alive": true,
+  "set-cookie": true,
+  "transfer-encoding": true,
+} satisfies Record<string, true>;
+
+/** Redirect statuses the handler resolves itself; see {@link followUpstream}. */
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+
+/** Hops followed before giving up, matching fetch's own redirect limit. */
+const MAX_REDIRECTS = 20;
+
+/** A 400 the playground client can render verbatim. */
+const badRequest = (error: string): Response =>
+  Response.json({ error }, { status: 400 });
+
+/** Copy headers, skipping the given denylist (names are already lowercase). */
+const filterHeaders = (
+  source: Headers,
+  drop: Record<string, true>
+): Headers => {
+  const headers = new Headers();
+  for (const [name, value] of source) {
+    if (!drop[name]) {
+      headers.set(name, value);
+    }
+  }
+  return headers;
+};
+
+/** A 403 for a target no configured spec declares as one of its servers. */
+const forbidden = (origin: string): Response =>
+  Response.json(
+    {
+      error:
+        `${origin} is not one of the API servers this documentation declares, ` +
+        "so the docs proxy will not request it.",
+    },
+    { status: 403 }
+  );
+
+/**
+ * Follow the upstream chain by hand, re-checking every hop. Redirects are
+ * deliberately NOT delegated to fetch: `redirect: "follow"` would chase a
+ * `Location` to any host, so an allowlisted first hop could bounce the docs
+ * server onto an internal address it must never reach. The rewrite rules match
+ * fetch's own — 303 (and 301/302, as every browser does) degrade to a bodyless
+ * GET, 307/308 replay the method and body.
+ */
+const followUpstream = async (args: {
+  allowed: ReadonlySet<string>;
+  body: ArrayBuffer | undefined;
+  fetchImpl: typeof fetch;
+  headers: Headers;
+  /** Hops already followed; the chain is bounded by {@link MAX_REDIRECTS}. */
+  hop: number;
+  method: string;
+  url: URL;
+}): Promise<Response> => {
+  const response = await args.fetchImpl(args.url, {
+    body: args.body,
+    headers: args.headers,
+    method: args.method,
+    redirect: "manual",
+  });
+  const location = REDIRECT_STATUS.has(response.status)
+    ? response.headers.get("location")
+    : null;
+  if (location === null) {
+    return response;
+  }
+  if (args.hop >= MAX_REDIRECTS) {
+    throw new Error(`Too many redirects from ${args.url.href}.`);
+  }
+  let next: URL;
+  try {
+    next = new URL(location, args.url);
+  } catch {
+    throw new Error(`Upstream redirected to an invalid URL: ${location}`);
+  }
+  if (next.protocol !== "http:" && next.protocol !== "https:") {
+    throw new Error(`Upstream redirected to a non-http(s) URL: ${location}`);
+  }
+  if (!args.allowed.has(next.origin)) {
+    return forbidden(next.origin);
+  }
+  // 307/308 replay the request as-is; the rest degrade to a bodyless GET.
+  const replay = response.status === 307 || response.status === 308;
+  return followUpstream({
+    ...args,
+    body: replay ? args.body : undefined,
+    hop: args.hop + 1,
+    method: replay || args.method === "HEAD" ? args.method : "GET",
+    url: next,
+  });
+};
+
+/**
+ * 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
+ * (minus {@link RESPONSE_DROP}) with an `x-blume-proxy` marker. An unreachable
+ * upstream is a 502 with a JSON `error`.
+ *
+ * `origins` is the allowlist: the origins of the `servers` the documented specs
+ * themselves declare (derived at build time). Without it the endpoint would be
+ * an open proxy — any visitor could aim the docs deployment at cloud metadata
+ * or a service on its private network. Non-absolute and non-http(s) targets are
+ * a 400; anything outside the allowlist, including on a redirect hop, is a 403.
+ * Loopback and private addresses need no separate rule: they are reachable only
+ * when a spec documents them, which is exactly the local-API case that must
+ * keep working.
+ */
+export const createPlaygroundProxyHandler = (
+  origins: readonly string[],
+  fetchImpl: typeof fetch = fetch
+) => {
+  const allowed = new Set(origins);
+  return async (request: Request): Promise<Response> => {
+    const target = new URL(request.url).searchParams.get("url");
+    if (!target) {
+      return badRequest("Missing `url` query parameter.");
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(target);
+    } catch {
+      return badRequest(`Invalid target URL: ${target}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return badRequest("Only http(s) target URLs are allowed.");
+    }
+    if (!allowed.has(parsed.origin)) {
+      return forbidden(parsed.origin);
+    }
+
+    // Buffer the body instead of streaming it: GET/HEAD must not carry one
+    // (fetch rejects it), and a buffered body avoids the `duplex` requirement
+    // streaming request bodies have in Node.
+    const body =
+      request.method === "GET" || request.method === "HEAD"
+        ? undefined
+        : await request.arrayBuffer();
+
+    let upstream: Response;
+    try {
+      upstream = await followUpstream({
+        allowed,
+        body,
+        fetchImpl,
+        headers: filterHeaders(request.headers, REQUEST_DROP),
+        hop: 0,
+        method: request.method,
+        url: parsed,
+      });
+    } catch (error) {
+      // SAFETY: followUpstream itself only throws `new Error(...)`, and a
+      // failed fetch rejects with a TypeError per spec — both are Errors
+      // carrying `.message`.
+      return Response.json(
+        { error: (error as Error).message },
+        { status: 502 }
+      );
+    }
+
+    const headers = filterHeaders(upstream.headers, RESPONSE_DROP);
+    // Marks proxied responses so the client (and debugging humans) can tell
+    // them apart from direct responses.
+    headers.set("x-blume-proxy", "1");
+    return new Response(upstream.body, {
+      headers,
+      status: upstream.status,
+      statusText: upstream.statusText,
+    });
+  };
+};

package/src/openapi/references.ts

@@ -25,6 +25,12 @@ export interface ReferenceDisplay {
   codeSamples: string[];
   /** Whether nested schema rows start expanded. */
   expandSchemas: boolean;
+  /**
+   * The "Try it" playground: whether operation pages render it, and the CORS
+   * proxy the Send button routes through (`false` off, a URL string, or
+   * `true` for the built-in `/_api-proxy` endpoint).
+   */
+  playground: { enabled: boolean; proxy: string | boolean };
 }
 
 /** A spec source resolved to a concrete route, label, and renderer. */
@@ -190,6 +196,7 @@ export const resolveReferences = (
     {
       codeSamples: config.openapi.codeSamples,
       expandSchemas: config.openapi.expandSchemas,
+      playground: config.openapi.playground,
     },
     config.basePath
   ),
@@ -201,6 +208,7 @@ export const resolveReferences = (
     {
       codeSamples: config.asyncapi.codeSamples,
       expandSchemas: config.asyncapi.expandSchemas,
+      playground: config.asyncapi.playground,
     },
     config.basePath
   ),

package/src/openapi/source.ts

@@ -182,6 +182,18 @@ export const openApiSource = (
       const { document, warnings, operations, tags, extractWarnings } =
         await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
+      // The playground proxy resolves here, not client-side: `true` selects
+      // the built-in `/_api-proxy` route (mounted under the site `basePath`,
+      // like every served URL this module emits), a non-empty string is an
+      // external proxy used verbatim, and anything else (`false`, `""`)
+      // means the Send button fetches the API directly.
+      const { proxy: configuredProxy } = reference.display.playground;
+      let proxy: string | false = false;
+      if (configuredProxy === true) {
+        proxy = withBasePath(reference.basePath, "/_api-proxy");
+      } else if (configuredProxy !== false && configuredProxy !== "") {
+        proxy = configuredProxy;
+      }
       const spec: ApiSpecData = {
         codeSamples: reference.display.codeSamples,
         description: info.description ?? "",
@@ -202,6 +214,7 @@ export const openApiSource = (
             },
           ])
         ),
+        playground: { enabled: reference.display.playground.enabled, proxy },
         route: reference.route,
         slug: reference.slug,
         tags,

package/src/registry/eject.ts

@@ -127,11 +127,10 @@ const askFiles = async (
   const grounded = ask.provider !== "inkeep";
   const files = [
     {
-      content: askEndpointTemplate(
-        resolveAskBackend(ask),
-        grounded,
-        ask.instructions
-      ),
+      content: askEndpointTemplate(resolveAskBackend(ask), grounded, {
+        instructions: ask.instructions,
+        retrieval: ask.retrieval,
+      }),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
   ];