blume 1.5.0 → 1.5.2

package/dist/types/ai/ask-context.d.ts

@@ -0,0 +1,78 @@
+import type { OramaDoc } from "../search/orama-index.ts";
+/** A chat message as posted by the Ask AI island (`{ role, content }`). */
+export interface AskMessage {
+    content: string;
+    role: string;
+}
+/** The current-page hint the island forwards so the endpoint can prioritize it. */
+export interface AskPage {
+    path?: string;
+}
+/**
+ * The self-contained snapshot the grounded Ask AI endpoint imports. Bundles the
+ * search documents so retrieval works regardless of the configured search
+ * provider and needs no filesystem access at request time. Serialized to
+ * `generated/ask-data.json` and built by {@link buildAskData}.
+ */
+export interface AskData {
+    /**
+     * The site's `i18n.defaultLocale`, when i18n is configured. Selects a
+     * word-segmenting Orama tokenizer for every non-Latin script, so retrieval
+     * can match CJK, Cyrillic, Greek, Hebrew, or Devanagari content.
+     */
+    defaultLocale?: string;
+    documents: OramaDoc[];
+    site: string | null;
+}
+/**
+ * How much retrieved documentation a question carries (the `ai.ask.retrieval`
+ * config). Every field falls back to the built-in default, so a partial object
+ * only changes what it names. Injected characters dominate time-to-first-token
+ * on a self-hosted backend, and the three knobs aren't interchangeable: the
+ * budget caps the total, `excerptChars` decides how deep into one long page the
+ * excerpt reaches, and `maxResults` decides how many pages retrieval adds (the
+ * page the reader is viewing is injected on top of them).
+ */
+export interface AskRetrievalOptions {
+    /** Overall cap on injected documentation characters. Defaults to `10000`. */
+    contextBudget?: number;
+    /** Characters kept per injected excerpt. Defaults to `2000`. */
+    excerptChars?: number;
+    /**
+     * Documents retrieved per question. Defaults to `6`. The current page is
+     * injected in addition when it isn't among the hits.
+     */
+    maxResults?: number;
+}
+/**
+ * Excerpt the region of `content` most relevant to `query`, not just its head.
+ *
+ * Pages are indexed whole (one document each), so a naive head slice of a long
+ * page returns its intro and misses sections below the fold — the exact failure
+ * where "How does Ask AI work?" retrieves the right page but only sees its
+ * opening paragraph. This centers the window on the densest cluster of query
+ * terms so the injected text is the part that actually answers the question.
+ * Exported for testing; {@link createAskContext} is the runtime entry point.
+ */
+export declare const relevantExcerpt: (content: string, query: string, max: number) => string;
+/**
+ * Build the request-time grounding function for the Ask AI endpoint.
+ *
+ * Lexical retrieval over Orama (the same index/ranking the search dialog and MCP
+ * server use). The index is built once and memoized across requests. Returns a
+ * grounded system prompt — the retrieved excerpts plus the page the user is
+ * viewing — or `undefined` when there is nothing to ground on, so the endpoint
+ * can fall back to its plain prompt.
+ *
+ * `options.instructions` (the `ai.ask.instructions` config) is appended after
+ * the base instruction rather than replacing it: the base carries the
+ * functional contract (answer only from the excerpts, cite pages as Markdown
+ * links) that the panel's citation rendering depends on.
+ *
+ * `options.retrieval` (the `ai.ask.retrieval` config) sizes how much
+ * documentation each question carries; omitted fields keep today's defaults.
+ */
+export declare const createAskContext: (data: AskData, options?: {
+    instructions?: string;
+    retrieval?: AskRetrievalOptions;
+}) => ((messages: AskMessage[], page?: AskPage) => Promise<string | undefined>);

package/dist/types/core/config-input.d.ts

@@ -2,7 +2,7 @@ import type { AstroIntegration } from "astro";
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { CodeTheme } from "../markdown/themes.ts";
 import type { FontSlug } from "../theme/fonts.ts";
-import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
+import type { OpenApiSource, OpenInChatProvider, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
 import type { StandardSchema } from "./standard-schema.ts";
 /**
@@ -438,7 +438,7 @@ export type FontInput = LiteralUnion<FontSlug> | RemoteFontInput | LocalFontInpu
 export interface FontsConfig {
     /** Body / prose font. Defaults to `inter`. */
     body?: FontInput;
-    /** Display / heading font. Defaults to `inter-tight`. */
+    /** Display / heading font. Defaults to `inter` (shared with the body). */
     display?: FontInput;
     /** Monospace / code font. Defaults to `ibm-plex-mono`. */
     mono?: FontInput;
@@ -548,6 +548,27 @@ export interface AskSuggestion {
 /** Backends that can route an Ask AI request. */
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+/** How much retrieved documentation each Ask AI question carries. */
+export interface AskRetrievalConfig {
+    /**
+     * Total injected documentation characters, across all excerpts. Defaults to
+     * `10000`. The single biggest lever on time-to-first-token — the model reads
+     * every injected character before it emits a token.
+     */
+    contextBudget?: number;
+    /**
+     * Characters kept per excerpt. Defaults to `2000`. Raise it when one long
+     * page holds the whole answer (a table the excerpt cuts in half); the
+     * `contextBudget` still caps the total.
+     */
+    excerptChars?: number;
+    /**
+     * Documents retrieved per question. Defaults to `6`. The page the reader is
+     * viewing is injected on top of the retrieved ones, so an answer can cite up
+     * to one page more than this.
+     */
+    maxResults?: number;
+}
 export interface AskConfig {
     /**
      * Name of the env var holding the provider API key. Each provider has a
@@ -577,6 +598,12 @@ export interface AskConfig {
     model?: string;
     /** Which backend routes the request. Defaults to `gateway`. */
     provider?: AskProvider;
+    /**
+     * How much documentation each question carries into the model's prompt.
+     * Lower values cut time-to-first-token — which dominates on a self-hosted
+     * backend — at the cost of recall. Defaults keep the built-in behavior.
+     */
+    retrieval?: AskRetrievalConfig;
     /** Starter prompts shown before the first question. */
     suggestions?: AskSuggestion[];
 }
@@ -637,6 +664,19 @@ export interface AiConfig {
     markdownComponents?: Record<string, ComponentMarkdown>;
     /** Expose the docs as an MCP server for agents. */
     mcp?: McpConfig;
+    /**
+     * The "Open in chat" page action, which opens the current page in an AI
+     * assistant pre-filled with a prompt pointing at its raw Markdown.
+     * Defaults to `true` (every provider). Set `false` to hide the action, or
+     * list a subset of providers to show, in order.
+     *
+     * ```ts
+     * ai: {
+     *   openInChat: ["claude", "chatgpt", "cursor"],
+     * }
+     * ```
+     */
+    openInChat?: boolean | OpenInChatProvider[];
     /**
      * Publish Agent Skills for discovery: a directory (resolved against the
      * project root) whose subdirectories each hold a `SKILL.md`. Skills are
@@ -1022,6 +1062,18 @@ interface ReferenceConfig {
     enabled?: boolean;
     /** Start nested schema rows expanded (Blume renderer). Defaults to `false`. */
     expandSchemas?: boolean;
+    /**
+     * The interactive "Try it" panel on operation pages (Blume renderer). On by
+     * default; `false` hides it. `proxy` is 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"`). `proxy` is OpenAPI-only — an event
+     * composer's WebSocket connect is direct.
+     */
+    playground?: boolean | {
+        enabled?: boolean;
+        proxy?: boolean | string;
+    };
     /** Who renders the reference. Defaults to `blume`. */
     renderer?: "blume" | "scalar";
     /**

package/dist/types/core/data.d.ts

@@ -1,3 +1,4 @@
+import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
@@ -32,6 +33,17 @@ export interface BlumeLogo {
 export interface BlumeFavicon {
     href: string;
     type?: string;
+    /**
+     * Dark-scheme variant: the `-dark` sibling of the resolved icon file (e.g.
+     * `icon.svg` → `icon-dark.svg`), or the bundled default pair. When set, the
+     * layout emits an unconditional light link plus both icons behind
+     * `media="(prefers-color-scheme: …)"` so a dark mark doesn't vanish against
+     * dark browser chrome.
+     */
+    dark?: {
+        href: string;
+        type?: string;
+    };
 }
 /** Announcement banner, normalized from its config (string shorthand or object). */
 export interface BlumeBanner {
@@ -156,6 +168,11 @@ export interface BlumeDataConfig {
          */
         site?: string;
     };
+    /**
+     * "Open in chat" page-action providers (`ai.openInChat`), in display order;
+     * empty hides the action.
+     */
+    openInChat: ResolvedConfig["ai"]["openInChat"];
     /** Repository URL for header/edit links, or `null`. */
     repoUrl: string | null;
     search: {
@@ -209,8 +226,8 @@ export interface BlumeClientData {
 export interface BlumeData {
     config: BlumeDataConfig;
     feeds: BlumeFeed[];
-    /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
-    fontCssVars: string[];
+    /** Configured fonts for the head: CSS variable + preload weights per family. */
+    fontCssVars: FontHead[];
     /** Sidebar + tab tree for the default locale. */
     navigation: Navigation;
     /** Per-locale navigation trees, keyed by locale code (empty without i18n). */

package/dist/types/core/open-in-chat.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Providers for the "Open in chat" page action, in display order. Shared by
+ * the config schema (`ai.openInChat` subsets validate against this list) and
+ * the PageActions menu (which renders the full list when the config is `true`).
+ * Lives outside `schema.ts` so the component can import the list without
+ * pulling the whole config schema into the layout module graph.
+ */
+export declare const openInChatProviders: readonly ["v0", "chatgpt", "claude", "t3", "scira", "cursor"];
+export type OpenInChatProvider = (typeof openInChatProviders)[number];

package/dist/types/core/schema.d.ts

@@ -269,6 +269,11 @@ declare const aiConfigSchema: z.ZodObject<{
             inkeep: "inkeep";
             "openai-compatible": "openai-compatible";
         }>>;
+        retrieval: z.ZodOptional<z.ZodObject<{
+            contextBudget: z.ZodOptional<z.ZodNumber>;
+            excerptChars: z.ZodOptional<z.ZodNumber>;
+            maxResults: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
         suggestions: z.ZodDefault<z.ZodArray<z.ZodObject<{
             icon: z.ZodOptional<z.ZodString>;
             label: z.ZodString;
@@ -291,6 +296,14 @@ declare const aiConfigSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodString>;
         route: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
     }, z.core.$strict>>;
+    openInChat: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
+        v0: "v0";
+        chatgpt: "chatgpt";
+        claude: "claude";
+        t3: "t3";
+        scira: "scira";
+        cursor: "cursor";
+    }>>]>>, z.ZodTransform<("v0" | "chatgpt" | "claude" | "t3" | "scira" | "cursor")[], boolean | ("v0" | "chatgpt" | "claude" | "t3" | "scira" | "cursor")[]>>;
     skills: z.ZodOptional<z.ZodString>;
     webBotAuth: z.ZodPrefault<z.ZodObject<{
         keys: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -299,6 +312,8 @@ declare const aiConfigSchema: z.ZodObject<{
 }, z.core.$strict>;
 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";
 /** A configured locale: ISO-ish code plus display metadata for the switcher. */
 declare const localeSchema: z.ZodObject<{
     code: z.ZodString;
@@ -473,6 +488,11 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 inkeep: "inkeep";
                 "openai-compatible": "openai-compatible";
             }>>;
+            retrieval: z.ZodOptional<z.ZodObject<{
+                contextBudget: z.ZodOptional<z.ZodNumber>;
+                excerptChars: z.ZodOptional<z.ZodNumber>;
+                maxResults: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
             suggestions: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 icon: z.ZodOptional<z.ZodString>;
                 label: z.ZodString;
@@ -495,6 +515,14 @@ export declare const blumeConfigSchema: z.ZodObject<{
             name: z.ZodOptional<z.ZodString>;
             route: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
         }, z.core.$strict>>;
+        openInChat: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodArray<z.ZodEnum<{
+            v0: "v0";
+            chatgpt: "chatgpt";
+            claude: "claude";
+            t3: "t3";
+            scira: "scira";
+            cursor: "cursor";
+        }>>]>>, z.ZodTransform<("v0" | "chatgpt" | "claude" | "t3" | "scira" | "cursor")[], boolean | ("v0" | "chatgpt" | "claude" | "t3" | "scira" | "cursor")[]>>;
         skills: z.ZodOptional<z.ZodString>;
         webBotAuth: z.ZodPrefault<z.ZodObject<{
             keys: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -521,6 +549,16 @@ export declare const blumeConfigSchema: z.ZodObject<{
         codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            proxy: string | boolean;
+        }, boolean | {
+            enabled: boolean;
+            proxy: string | boolean;
+        }>>;
         renderer: z.ZodDefault<z.ZodEnum<{
             blume: "blume";
             scalar: "scalar";
@@ -814,6 +852,16 @@ export declare const blumeConfigSchema: z.ZodObject<{
         codeSamples: z.ZodDefault<z.ZodArray<z.ZodString>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         expandSchemas: z.ZodDefault<z.ZodBoolean>;
+        playground: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            proxy: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        }, z.core.$strict>]>>, z.ZodTransform<{
+            enabled: boolean;
+            proxy: string | boolean;
+        }, boolean | {
+            enabled: boolean;
+            proxy: string | boolean;
+        }>>;
         renderer: z.ZodDefault<z.ZodEnum<{
             blume: "blume";
             scalar: "scalar";
@@ -1149,4 +1197,3 @@ export type SearchProvider = (typeof searchProviders)[number];
 export type ContentSignals = z.infer<typeof contentSignalsSchema>;
 /** The resolved per-signal policy object (present when signals are enabled). */
 export type ContentSignalPolicy = NonNullable<ContentSignals>;
-export {};

package/dist/types/core/types.d.ts

@@ -47,6 +47,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. */
@@ -252,9 +256,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/dist/types/openapi/references.d.ts

@@ -16,6 +16,15 @@ 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. */
 export interface ReferenceSource {

package/dist/types/search/orama-index.d.ts

@@ -0,0 +1,70 @@
+import type { AnyOrama } from "@orama/orama";
+/**
+ * The minimal document shape both the client-side search dialog and the
+ * server-side MCP `search_docs` tool index. Mirrors the `blume-search.json`
+ * entries built by `buildSearchDocuments`.
+ */
+export interface OramaDoc {
+    content: string;
+    description: string;
+    route: string;
+    title: string;
+    /** Locale code; indexed as an enum so queries can filter to one language. */
+    locale?: string;
+    /**
+     * Docs version; indexed as an enum so queries can filter to one version.
+     * The current docs carry `""`, which the enum stores and matches exactly.
+     */
+    version?: string;
+    /** Resolved page `type`; indexed as an enum so queries can filter by type. */
+    contentType?: string;
+    /** Declared facet values (`content.types.<type>.facets`), key → value. */
+    facets?: Record<string, string>;
+    /** Carried through for the search dialog's breadcrumb + filter pills. Stored
+     * but not indexed, so they ride along on the returned document untouched. */
+    breadcrumb?: string[];
+    section?: string;
+}
+/**
+ * Build an in-memory Orama full-text index from search documents. Shared by the
+ * Orama client loader (browser), the MCP server, and Ask AI grounding (Node),
+ * so ranking is identical wherever docs are queried. `locale` — the site's
+ * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for every
+ * non-Latin script, all of which Orama's default tokenizer reduces to zero
+ * tokens; the tokenizer belongs to the database, so on a mixed-locale site it
+ * applies to every document. That is safe in one direction only: Latin words
+ * survive segmentation intact, so English pages on a segmented index stay
+ * searchable, but non-Latin translations on a Latin-default index still
+ * collapse to zero tokens.
+ */
+export declare const buildOramaIndex: (documents: OramaDoc[], locale?: string) => Promise<AnyOrama>;
+/** Optional exact-match filters applied to a query via Orama's `where`. */
+export interface OramaQueryFilters {
+    /** Keep only documents whose `contentType` is in this list. */
+    contentTypes?: string[];
+    /**
+     * Keep only documents matching every facet, key → required value. Facet
+     * keys and values come from the `facets` field on the indexed documents.
+     */
+    facets?: Record<string, string>;
+    /** Keep only documents in this locale. */
+    locale?: string;
+    /**
+     * Keep only documents of this docs version (`""` is the current docs — a
+     * meaningful filter value, so absence alone disables version filtering).
+     */
+    version?: string;
+}
+/**
+ * Query the index, returning the matching documents (highest-ranked first).
+ * `filters` narrows results by exact `where` matches on the enum fields:
+ * `locale` to one language, `contentTypes` to a set of page types, `facets`
+ * to documents carrying every requested `key:value` term.
+ *
+ * On a bigrammed index the strict pass runs first: a term is only meant to
+ * match where its bigrams sit together, and scoring them independently lets a
+ * page sharing a couple of windows outrank the page the term is about. Terms
+ * spanning several words rarely appear in full on one page, so an empty strict
+ * result falls back to the default pass rather than reporting no matches.
+ */
+export declare const queryOramaIndex: (db: AnyOrama, term: string, limit: number, filters?: OramaQueryFilters) => Promise<OramaDoc[]>;

package/dist/types/theme/fonts.d.ts

@@ -203,5 +203,14 @@ export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
  * config tokens; empty when no fonts are set so defaults stay the system stacks.
  */
 export declare const buildFontsCss: (fonts: FontsConfig) => string;
-/** The CSS variables to feed Astro's `<Font>` component in the document head. */
-export declare const configuredCssVars: (fonts: FontsConfig) => string[];
+/** One `<Font>` render in the head: its CSS variable + weights to preload. */
+export interface FontHead {
+    cssVariable: string;
+    preloadWeights: number[];
+}
+/**
+ * The fonts to feed Astro's `<Font>` component in the document head, deduped
+ * by CSS variable with preload weights unioned across the roles that share a
+ * family (so `display` and `body` both set to Inter preload 400/500/600 once).
+ */
+export declare const configuredFonts: (fonts: FontsConfig) => FontHead[];

package/docs/advanced/api-reference.mdx

@@ -3,7 +3,7 @@ title: OpenAPI / AsyncAPI
 description: Drop in an OpenAPI or AsyncAPI spec and get a native API reference — one real page per operation, in your sidebar and search.
 ---
 
-Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, and generated code samples. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. Event-driven APIs get the [same treatment from an AsyncAPI spec](#asyncapi). The config below points Blume at the public Petstore spec as an example.
+Point Blume at an OpenAPI spec and it generates a native API reference: one **real page per operation**, grouped by tag in a tab-scoped sidebar, with schema tables, request/response examples, generated code samples, and an interactive [Try it](#try-it-playground) panel. Because each operation is a genuine Blume page, it gets its own URL, shows up in **site search** and `llms.txt`, and gets an Open Graph image — the same as any hand-written doc. The config below points Blume at the public Petstore spec as an example.
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -62,6 +62,42 @@ openapi: {
 }
 ```
 
+## Try it playground
+
+Operation pages rendered natively ship an interactive **Try it** panel by default. Blume generates the form from the operation itself: an input per path, query, and header parameter, a body editor built from the request-body schema, everything prefilled from the spec's examples. A server picker lists the spec's `servers`, with a free-text field for any other base URL, and auth inputs match the operation's [resolved security](#authorization) — bearer token, API key, and basic credentials, with OAuth2 as a token paste field (bring an access token; Blume doesn't run the flow).
+
+The panel and the code samples stay in lockstep: values typed into the form update the generated samples live, so a copied curl command always matches exactly what **Send** would do. And it stays out of the way — the panel is server-rendered collapsed, and its JavaScript loads only when a reader first opens it. Readers who never touch it download none of it.
+
+`playground: false` is the entire off switch:
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+  playground: false,
+}
+```
+
+### Credentials
+
+Credentials typed into the auth inputs stay in memory and vanish on reload. Checking **Remember on this device** persists them in `localStorage`, scoped to the docs origin — they're never sent anywhere except the API being called. Code samples keep showing placeholders (`YOUR_TOKEN` and friends) whatever's typed, unless the reader toggles **Include my values in samples**.
+
+### CORS and the proxy
+
+As with the [Scalar renderer](#the-scalar-renderer), requests go **directly from the browser** to the target API, so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). For APIs that can't, set `playground.proxy`: a URL routes requests through a proxy you host, and `true` enables the built-in `/_api-proxy` route — which needs a server build, so it requires [`deployment.output: "server"`](/docs/deployment#server-rendering):
+
+```ts blume.config.ts lineNumbers
+openapi: {
+  enabled: true,
+  spec: "./openapi.yaml",
+  playground: {
+    proxy: true,   // or a URL of your own
+  },
+}
+```
+
+The built-in proxy only forwards requests to the origins your specs declare in `servers` — including across redirects — so a public docs deployment can't be aimed at other hosts on its network. A **Custom base URL** typed into the panel isn't a documented server: with the proxy enabled, requests to it are refused with a 403.
+
 ## Multiple specs
 
 Use `sources` to publish more than one spec. Each source gets its own overview route, operation pages, and header tab. Give each a `label` (used for the tab and to derive its route), or set an explicit `route`:
@@ -118,7 +154,7 @@ The OpenAPI semantics carry over as written:
 
 ## The Scalar renderer
 
-The native renderer is the default. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference — its own sidebar, search, theme, and "Try it" playground on a single route — set `renderer: "scalar"`:
+The native renderer is the default — operation pages, search integration, and the [Try it playground](#try-it-playground) above are all its work. If you'd rather embed [Scalar](https://scalar.com)'s self-contained API reference UI — its own sidebar, search, theme, and request client on a single route — set `renderer: "scalar"`:
 
 ```ts blume.config.ts lineNumbers
 openapi: {
@@ -129,7 +165,7 @@ openapi: {
 }
 ```
 
-A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`. Its "Try it" playground calls your **target API directly from the browser** (Blume doesn't proxy), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` and the playground apply to the Scalar renderer only.
+A Scalar-rendered reference is a self-contained embed on its own route — it doesn't weave into Blume's sidebar, search, or `llms.txt`, and Blume's [`playground`](#try-it-playground) config doesn't apply to it. Scalar brings its own request client, which calls your **target API directly from the browser** (the `playground.proxy` route isn't available here), so the API must allow cross-origin requests from the docs site (`Access-Control-Allow-Origin`). `theme` applies to the Scalar renderer only.
 
 ### Passing Scalar options
 
@@ -153,7 +189,7 @@ Blume's own [`i18n`](/docs/content/i18n) translates the docs chrome, but Scalar
 
 ## AsyncAPI
 
-Event-driven APIs use a sibling `asyncapi` block with the same shape — and the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, and an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups). Only the default route differs (`/events`):
+Event-driven APIs use a sibling `asyncapi` block with the same shape — and the same native renderer. Each `send`/`receive` operation becomes a real page with message payload and header schema tables, channel parameters, protocol bindings, an Authorization section derived from the spec's `securitySchemes` (server-level and operation-level, alternatives as "or" groups), and a [Try it](#try-it-for-events) message composer. Only the default route differs (`/events`):
 
 ```ts blume.config.ts lineNumbers
 asyncapi: {
@@ -166,4 +202,30 @@ AsyncAPI **2.x specs are normalized to 3.x automatically** with the official Asy
 
 Code samples are **protocol-aware**, keyed off the operation's binding (or its servers' protocol): `wscat` and a browser `WebSocket` snippet for WebSockets, `kcat` for Kafka, `mosquitto_pub`/`mosquitto_sub` for MQTT. `codeSamples` filters that set, the same way it picks languages on the `openapi` block; a protocol without a supported tool renders the message payload example alone rather than a fabricated client.
 
-Everything documented above carries over unchanged: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag. Setting `renderer: "scalar"` opts back into the embedded Scalar SPA — Scalar auto-detects the document type and renders channels, operations, messages, and a Models section (no interactive playground for events) — where, as with OpenAPI, only `noindex` applies.
+Everything documented above carries over, [`playground`](#try-it-for-events) included: `route`, `sources` with `label`/`route`, `expandSchemas`, the [per-source indexing](#per-source-indexing) flags, and search indexing by operation summary and tag.
+
+Setting `renderer: "scalar"` opts back into the embedded Scalar SPA, where — as with OpenAPI — only `noindex` applies. Scalar has no AsyncAPI playground of its own; its embed auto-detects the document type and renders channels, operations, messages, and a Models section, so that swap trades the composer away.
+
+### Try it for events
+
+Operation pages rendered natively ship a **Try it** panel here too, on the same terms as the [OpenAPI panel](#try-it-playground): server-rendered collapsed, with its JavaScript loaded only when a reader first opens it.
+
+Whatever the protocol, the panel opens with a payload editor prefilled from the message's `examples` — or, when the message declares none, from a value sampled out of the payload schema — validated against the message payload schema as you type. Under it sit an input per channel parameter and a server picker fed by the channel's `servers`, with a free-text field for any other URL. The protocol-aware code samples stay in lockstep with the form exactly as curl, js, and python do on an HTTP operation: the channel address template is filled in with the parameter values you type, so a copied `wscat`, `WebSocket`, `kcat`, or `mosquitto_pub` snippet matches what the form says.
+
+Live connect is WebSocket-only. On a `ws` or `wss` binding the panel connects to the resolved channel URL, shows the connection state, and logs every frame with a timestamp. AsyncAPI 3 states an action from the API's side, and the panel follows it: a `receive` operation is one the API receives from you, so it gets a **Send** button that publishes the composed payload; a `send` operation only streams messages at you, so it connects and logs. There's no reconnect logic — once a socket closes, it stays closed until you connect again. Kafka, MQTT, AMQP, and every other protocol get the composer and the copyable CLI samples, and the panel says as much on the page: Blume doesn't fake broker connectivity from a browser tab.
+
+`asyncapi.playground` mirrors `openapi.playground` — on by default with the native renderer, and `false` is the entire off switch:
+
+```ts blume.config.ts lineNumbers
+asyncapi: {
+  enabled: true,
+  spec: "./asyncapi.yaml",
+  playground: false,
+}
+```
+
+:::note
+`playground.proxy` is OpenAPI-only. It forwards HTTP requests, and a WebSocket connect goes straight from the browser to the server named in the URL, so there's nothing for a proxy to sit in front of.
+:::
+
+The event composer collects no broker credentials. Each operation page's **Authorization** section documents what the broker expects, and a WebSocket connect carries only what's already in the URL. Nothing is persisted for event operations.

package/docs/advanced/custom-pages.mdx

@@ -231,13 +231,17 @@ Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generat
   siteUrl={config.site}
   ogEnabled={config.og.enabled}
   ogImage="/opengraph-image.png"
+  ogImageAlt="Acme — the fastest docs"
+  ogImageSize={{ width: 1200, height: 630 }}
   page={{ title: config.title }}
 >
   <!-- page content -->
 </PageLayout>
 ```
 
-Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image.
+Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image. The generated card declares its size and alt text to crawlers on its own; for your own `ogImage`, pass `ogImageAlt` and `ogImageSize` alongside so the share card gets the same treatment.
+
+The page also emits schema.org JSON-LD — the same `WebSite` graph the docs pages carry, so the home page (usually a custom page) isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with the [`structuredData`](/docs/configuration/seo) config, or `structuredDataEnabled={false}` to turn it off for one page.
 
 `page.title` is used verbatim as the document title (no `- siteTitle` suffix), since marketing pages usually set their own. To give a custom page the full docs chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the generated pages use. Pull the required props straight from `blume:data`:
 

package/docs/configuration/ai.mdx

@@ -101,6 +101,14 @@ The **Open in chat** action opens the current page in an AI assistant — v0, Ch
 
 Like Copy as Markdown, it needs no setup. The assistant fetches the page over its public URL, so it works as soon as the page is deployed.
 
+To tailor the action, set `ai.openInChat`. `false` hides it entirely, and an array of provider keys — `"v0"`, `"chatgpt"`, `"claude"`, `"t3"`, `"scira"`, `"cursor"` — shows just those providers, in the order you list them:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  openInChat: ["claude", "chatgpt", "cursor"],
+}
+```
+
 To embed a ready-to-copy prompt inline in your content — rather than a whole-page action — use the [Prompt component](/docs/content/components#prompt), which renders a labeled row with a **Copy prompt** button and an optional open-in-Cursor link.
 
 ## Ask AI
@@ -160,6 +168,33 @@ The page the reader is currently on is added to the context first and used to sc
 
 Grounding is on for every backend except **[Inkeep](#backends)**, which runs its own retrieval over the content you've indexed in its dashboard.
 
+### Retrieval size
+
+How much documentation a question carries is the biggest lever on how long the reader waits for the first word: the model reads every injected character before it emits a token. On a hosted frontier model that's invisible, but on a self-hosted backend it dominates. `retrieval` sizes it:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    retrieval: {
+      maxResults: 3, // fewer pages retrieved per question
+      excerptChars: 1200, // shorter excerpt from each one
+      contextBudget: 3000, // smaller total injection
+    },
+  },
+}
+```
+
+| Option          | Default | Description                                     |
+| --------------- | ------- | ----------------------------------------------- |
+| `maxResults`    | `6`     | Documents retrieved per question.               |
+| `excerptChars`  | `2000`  | Characters kept from each retrieved page.       |
+| `contextBudget` | `10000` | Total injected characters, across all excerpts. |
+
+The three aren't interchangeable. `contextBudget` caps the whole injection, `excerptChars` decides how deep into a single long page its excerpt reaches — raise it when one page holds the whole answer and the excerpt cuts it off — and `maxResults` caps how many pages retrieval adds. The page the reader is viewing is injected on top of the retrieved ones, so an answer can cite up to one page more than `maxResults`.
+
+The defaults suit a hosted model. Lower them when you're serving from your own hardware and time-to-first-token matters more than recall; answers stay grounded either way, and the assistant is told to say when something isn't covered rather than fill the gap.
+
 ### External endpoint
 
 Already have an API backend for AI? Point the panel at it and keep the docs build static: