blume 2.1.0 → 2.1.1

package/src/components/layout/RootLayout.astro

@@ -868,13 +868,20 @@ const localeRedirect = localeTargets
             />
           )
         }
+        {/* Below `xl`, where the rail is hidden, the page actions ride in
+            the "On this page" dropdown, so it renders wherever the rail
+            would, with or without headings. They render once, in the rail:
+            the dropdown gets an empty mount the actions script moves them
+            into (see PageActions.astro). */}
         {
-          hasToc && (
+          showToc && (
             <TableOfContentsSlot
               headings={tocHeadings}
               title={strings.toc.title}
               variant="mobile"
-            />
+            >
+              <div data-blume-page-actions-mount />
+            </TableOfContentsSlot>
           )
         }
         <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
@@ -911,6 +918,7 @@ const localeRedirect = localeTargets
                 (apiRail || modeLayout.width === "full") && "[&>*]:max-w-none",
                 modeLayout.width === "center" && "[&>*]:max-w-[54rem]",
               ]}
+              data-blume-page-end
             >
               {directoryGroup && <Directory group={directoryGroup} />}
               <RelatedPages links={relatedItems} title={strings.page.related} />

package/src/components/layout/Search.astro

@@ -4,6 +4,7 @@ import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { scopesLocales } from "../../search/adapters/locale-scope.ts";
 import { scopesVersions } from "../../search/adapters/version-scope.ts";
 import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
@@ -36,9 +37,15 @@ const {
   navigation,
   popularPages,
   strings,
-  locale,
+  locale: viewedLocale,
   version: viewedVersion = null,
 } = Astro.props;
+// Mixedbread searches every language whatever the dialog asks, so on it an
+// "All languages" toggle would change nothing: treat the site as
+// single-language for search instead.
+const locale = scopesLocales(data.config.search.provider)
+  ? viewedLocale
+  : undefined;
 // Pagefind, Orama Cloud, and Mixedbread search every version whatever the
 // dialog asks, so on those an "All versions" toggle would change nothing:
 // treat the site as unversioned for search instead.
@@ -90,6 +97,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-popular={s.popular}
   data-i18n-results={s.results}
   data-locale={locale || undefined}
+  data-redact-queries={data.config.search.analytics.queries ? undefined : ""}
   data-version={version ?? undefined}
   data-versioned={version === null ? undefined : ""}
 >
@@ -240,6 +248,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
     import { track } from "./analytics-client.ts";
     import { createSearchTracker } from "./search/analytics.ts";
+    import type { SearchTracker } from "./search/analytics.ts";
     import { highlight, matchSnippet } from "./search/types.ts";
     import type { SearchFn, SearchHit } from "./search/types.ts";
 
@@ -306,7 +315,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       searchClient ??= (async () => {
         try {
           const { createSearch } = await import("blume:search-client");
-          return await createSearch();
+          // The reader types each query, so each supersedes the last.
+          return await createSearch({ typing: true });
         } catch (error) {
           searchClient = undefined;
           throw error;
@@ -325,7 +335,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
       /** Records settled queries and picked results (search/analytics.ts). */
-      tracker = createSearchTracker(track);
+      tracker!: SearchTracker;
       loaded = false;
       loadFailed = false;
       /** First-open client/index load still in flight. */
@@ -419,6 +429,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.message = this.querySelector("[data-blume-search-message]")!;
         this.preview = this.querySelector("[data-blume-search-preview]")!;
         this.assistantEnabled = this.hasAttribute("data-ask");
+        // `search.analytics.queries: false` keeps query text off providers.
+        this.tracker = createSearchTracker(track, {
+          queries: !this.hasAttribute("data-redact-queries"),
+        });
 
         const popularScript = this.querySelector(
           "[data-blume-search-popular]"

package/src/components/layout/TableOfContents.astro

@@ -15,10 +15,14 @@ interface Props {
 }
 
 const { headings, title, variant } = Astro.props;
+// The mobile dropdown also holds what the layout passes as children (the
+// mount the page actions move into below `xl`, where the rail that renders
+// them is hidden), so a page with actions but no headings still gets it.
+const hasChildren = Astro.slots.has("default");
 ---
 
 {
-  headings.length > 0 && variant === "mobile" && (
+  (headings.length > 0 || hasChildren) && variant === "mobile" && (
     <details class="group mx-auto mb-6 max-w-content rounded-blume border border-border xl:hidden">
       <summary class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-3 font-medium text-foreground text-sm [&::-webkit-details-marker]:hidden">
         <span>{title}</span>
@@ -28,23 +32,26 @@ const { headings, title, variant } = Astro.props;
           size={16}
         />
       </summary>
-      <blume-toc class="block">
-        <ul class="m-0 list-none border-border border-t p-2">
-          {headings.map((heading) => (
-            <li
-              data-depth={heading.depth}
-              style={`padding-inline-start:${(heading.depth - 2) * 0.75}rem`}
-            >
-              <a
-                class="block rounded-md px-2 py-1.5 text-muted-foreground text-sm transition-colors hover:text-foreground aria-[current=location]:font-medium aria-[current=location]:text-foreground"
-                href={`#${heading.slug}`}
+      {headings.length > 0 && (
+        <blume-toc class="block">
+          <ul class="m-0 list-none border-border border-t p-2">
+            {headings.map((heading) => (
+              <li
+                data-depth={heading.depth}
+                style={`padding-inline-start:${(heading.depth - 2) * 0.75}rem`}
               >
-                {heading.text}
-              </a>
-            </li>
-          ))}
-        </ul>
-      </blume-toc>
+                <a
+                  class="block rounded-md px-2 py-1.5 text-muted-foreground text-sm transition-colors hover:text-foreground aria-[current=location]:font-medium aria-[current=location]:text-foreground"
+                  href={`#${heading.slug}`}
+                >
+                  {heading.text}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </blume-toc>
+      )}
+      <slot />
     </details>
   )
 }

package/src/components/layout/head-scripts.ts

@@ -44,8 +44,13 @@
  * stored preference instead of aborting before the swap listeners exist, and
  * after a swap the theme the `before-swap` stamp carried over stands, so a
  * toggle the reader made still holds for the rest of their visit.
+ *
+ * Paper is white, so a dark page prints light: `beforeprint` switches the root
+ * to the light theme (every token, Shiki color, and `dark:` utility follows
+ * it) and `afterprint` puts the dark theme back. The listeners sit on
+ * `window`, so the one registration outlives client-router swaps.
  */
-export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const r=document.documentElement;let s=null;let blocked=false;try{s=localStorage.getItem("blume-theme");}catch{blocked=true;}const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";r.dataset.theme=s??(blocked&&r.dataset.theme?r.dataset.theme:m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const r=document.documentElement;let s=null;let blocked=false;try{s=localStorage.getItem("blume-theme");}catch{blocked=true;}const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";r.dataset.theme=s??(blocked&&r.dataset.theme?r.dataset.theme:m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);let printed=null;addEventListener("beforeprint",()=>{const r=document.documentElement;if(r.dataset.theme==="dark"){printed="dark";r.dataset.theme="light";}});addEventListener("afterprint",()=>{if(printed){document.documentElement.dataset.theme=printed;printed=null;}});})();`;
 
 /**
  * Keep an embedded Scalar reference on Blume's theme. Scalar picks its own

package/src/components/layout/search/algolia.ts

@@ -48,7 +48,16 @@ export const createSearch = (opts: AlgoliaOptions): SearchFn => {
     // shape, so hits returned by that index carry those fields.
     const records =
       first && "hits" in first ? (first.hits as AlgoliaRecord[]) : [];
-    const hits = records.map((record) => ({
+    // The sync splits a long page across records that share its `url`. The
+    // index's `distinct` returns one of them, unless the site set its own
+    // `attributeForDistinct`; either way a page is listed once.
+    const pages = new Set<string>();
+    const unique = records.filter((record) => {
+      const seen = pages.has(record.url);
+      pages.add(record.url);
+      return !seen;
+    });
+    const hits = unique.map((record) => ({
       content: record.content ?? "",
       excerpt: highlight(
         excerptFor(record.description ?? "", record.content ?? "", query),

package/src/components/layout/search/analytics.ts

@@ -9,6 +9,10 @@
  * result is a `search_select` event with its position, for click-through. The
  * same query settling twice in a row (a filter toggled back and forth) counts
  * once.
+ *
+ * With `search.analytics.queries: false`, providers get each query's length
+ * (`queryChars`) instead of its text, and the text rides only the
+ * `blume:track` DOM event, the way the assistant reports questions.
  */
 import type { TrackProps } from "../analytics-client.ts";
 
@@ -18,8 +22,15 @@ export const MAX_QUERY_CHARS = 100;
 /** How long a query sits untouched before it counts as settled. */
 export const SETTLE_MS = 1000;
 
-/** Sends one analytics event. */
-export type SendEvent = (event: string, props: TrackProps) => void;
+/**
+ * Sends one analytics event; `local` rides only the `blume:track` DOM event
+ * (see `track`).
+ */
+export type SendEvent = (
+  event: string,
+  props: TrackProps,
+  local?: TrackProps
+) => void;
 
 /** The timer a tracker waits on; injectable for tests. */
 export interface SettleTimer {
@@ -27,6 +38,14 @@ export interface SettleTimer {
   start: (callback: () => void, ms: number) => number;
 }
 
+/** How a tracker reports. */
+export interface SearchTrackerOptions {
+  /** Whether providers receive each query's text (`search.analytics.queries`). */
+  queries?: boolean;
+  /** The timer a query waits on to settle; injectable for tests. */
+  timer?: SettleTimer;
+}
+
 /** What the dialog tells the tracker. */
 export interface SearchTracker {
   /** The dialog closed; record the query it was showing. */
@@ -51,23 +70,33 @@ const browserTimer: SettleTimer = {
 /** A tracker for one search dialog. */
 export const createSearchTracker = (
   send: SendEvent,
-  timer: SettleTimer = browserTimer
+  { queries = true, timer = browserTimer }: SearchTrackerOptions = {}
 ): SearchTracker => {
   let pending: PendingSearch | undefined;
   let handle: number | undefined;
   let last: string | undefined;
 
+  // Providers get the query's text, or only its length, in which case the
+  // text goes to the `blume:track` DOM event alone.
+  const report = (event: string, props: TrackProps, query: string): void => {
+    if (queries) {
+      send(event, { ...props, query });
+    } else {
+      send(event, { ...props, queryChars: query.length }, { query });
+    }
+  };
+
   const flush = (): void => {
     if (handle !== undefined) {
       timer.cancel(handle);
       handle = undefined;
     }
     if (pending && pending.query !== last) {
-      send("search", {
-        path: location.pathname,
-        query: pending.query,
-        results: pending.results,
-      });
+      report(
+        "search",
+        { path: location.pathname, results: pending.results },
+        pending.query
+      );
       last = pending.query;
     }
     pending = undefined;
@@ -80,12 +109,11 @@ export const createSearchTracker = (
     },
     selected: (query, position, url) => {
       flush();
-      send("search_select", {
-        path: location.pathname,
-        position,
-        query: query.slice(0, MAX_QUERY_CHARS),
-        url,
-      });
+      report(
+        "search_select",
+        { path: location.pathname, position, url },
+        query.slice(0, MAX_QUERY_CHARS)
+      );
     },
     settled: (query, results) => {
       if (handle !== undefined) {

package/src/components/layout/search/endpoint.ts

@@ -1,22 +1,64 @@
 import { highlight, SEARCH_LIMIT } from "./types.ts";
-import type { SearchFn, SearchHit } from "./types.ts";
+import type { SearchClientOptions, SearchFn, SearchHit } from "./types.ts";
+
+/**
+ * How long a typed query waits for the reader to stop typing before it's
+ * sent, in milliseconds. The dialog searches on every keystroke, and each
+ * request counts toward the endpoint's `rateLimit`.
+ */
+export const SEARCH_DEBOUNCE_MS = 250;
+
+/** Resolve after `ms`, or reject with the abort reason once `signal` aborts. */
+const pause = (ms: number, signal: AbortSignal): Promise<void> =>
+  // oxlint-disable-next-line promise/avoid-new -- adapt setTimeout and the abort event
+  new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true }
+    );
+  });
 
 /**
  * Server-proxied search (Mixedbread): POST the query to a generated endpoint
  * that holds the secret key and talks to the service. The returned hits carry
  * service-derived text and the dialog injects title/excerpt as HTML, so both
  * are escaped (and query matches marked) here, like every other provider.
+ * A failed request rejects, as a hosted provider's does, so the dialog shows
+ * its error rather than an empty "no results".
+ *
+ * With `typing` (the search dialog), a query waits {@link SEARCH_DEBOUNCE_MS}
+ * before it's sent, and a newer one supersedes it: the earlier call's wait or
+ * request is aborted and it rejects with an `AbortError`. Typing a word then
+ * costs one request rather than one per letter, and a slow earlier response
+ * can't land after a later one. Without it, every call is sent at once.
  */
-export const createSearch =
-  (opts: { api: string }): SearchFn =>
-  async (query) => {
+export const createSearch = (
+  opts: { api: string } & SearchClientOptions
+): SearchFn => {
+  let pending: AbortController | undefined;
+  return async (query) => {
+    let signal: AbortSignal | undefined;
+    if (opts.typing) {
+      pending?.abort();
+      pending = new AbortController();
+      ({ signal } = pending);
+      await pause(SEARCH_DEBOUNCE_MS, signal);
+    }
     const response = await fetch(opts.api, {
       body: JSON.stringify({ query }),
       headers: { "Content-Type": "application/json" },
       method: "POST",
+      signal,
     });
     if (!response.ok) {
-      return { hits: [], sections: [] };
+      throw new Error(
+        `Search failed: ${opts.api} answered ${response.status}.`
+      );
     }
     // SAFETY: the endpoint is Blume-generated (`search-endpoint` template) and
     // responds with the SearchHit list it built; title/excerpt are still
@@ -29,3 +71,4 @@ export const createSearch =
     }));
     return { hits, sections: [] };
   };
+};

package/src/components/layout/search/pagefind.ts

@@ -9,14 +9,63 @@ interface PagefindResult {
   }>;
 }
 
-interface PagefindModule {
+/** One Pagefind instance: a page language's index, plus any merged into it. */
+interface PagefindInstance {
+  mergeIndex: (
+    url: string,
+    options: { baseUrl: string; language: string }
+  ) => Promise<void>;
   search: (query: string) => Promise<{ results: PagefindResult[] }>;
 }
 
+interface PagefindModule {
+  createInstance: (options: {
+    basePath: string;
+    baseUrl: string;
+  }) => PagefindInstance;
+}
+
+/** `pagefind-entry.json`: the bundle's index for each language. */
+interface PagefindEntry {
+  languages: Record<string, { page_count: number }>;
+}
+
+// Pagefind names each page after its built file (`quickstart/index.html`), so
+// its URLs end in a slash. Blume serves pages without one (`trailingSlash:
+// "never"`): hosts redirect the slashed URL, and `blume preview` 404s it.
+const TRAILING_SLASH = /(?<=.)\/(?=[#?]|$)/u;
+
+/**
+ * The language whose index Pagefind loads for a page, picked the way its
+ * `findIndex` does: the page's own, else its base language (`pt` for
+ * `pt-br`), else the language with the most pages (a locale with no
+ * translated pages has no index of its own).
+ */
+const loadedLanguage = (
+  languages: PagefindEntry["languages"],
+  language: string
+): string | undefined => {
+  const [base = language] = language.split("-");
+  if (languages[language]) {
+    return language;
+  }
+  if (languages[base]) {
+    return base;
+  }
+  return Object.entries(languages).toSorted(
+    ([, a], [, b]) => b.page_count - a.page_count
+  )[0]?.[0];
+};
+
 /**
  * Pagefind: load the index emitted into the built site and query it. The bundle
  * lives in the output (not `node_modules`), so it is imported at runtime by URL
  * — which is why this only works in the production build, not `dev`.
+ *
+ * Pagefind keeps an index per language and searches the one for the page's
+ * `<html lang>`, which Blume sets to the locale the dialog scopes to. A
+ * search scoped to a locale is that index alone; a search across every
+ * language (no `locale`) merges every other language's index into it.
  */
 export const createSearch = async (opts: {
   url: string;
@@ -24,25 +73,85 @@ export const createSearch = async (opts: {
   // The pagefind bundle lives in the built site (not node_modules) and is
   // resolved at runtime by URL — it can't be a static, code-splittable path.
   // SAFETY: the URL points at the `pagefind.js` module our own build emitted,
-  // whose export contract (`search()`) is fixed by pagefind.
+  // whose export contract (`createInstance()`) is fixed by pagefind.
   // oxlint-disable-next-line react-doctor/no-dynamic-import-path
   const pagefind = (await import(
     /* @vite-ignore */
     opts.url
   )) as PagefindModule;
+  // The bundle's folder, which holds the entry file and every language's index.
+  const bundle = new URL("./", new URL(opts.url, document.baseURI));
+  // `baseUrl` "/" keeps result URLs base-less routes, like every other
+  // provider's: by default Pagefind prefixes the folder the bundle is served
+  // under, and the dialog adds the deployment base itself.
+  const create = (): PagefindInstance =>
+    pagefind.createInstance({ basePath: bundle.pathname, baseUrl: "/" });
+
+  // Every language's index: the page's own, and every other one merged in.
+  const everyLanguage = async (language: string): Promise<PagefindInstance> => {
+    const instance = create();
+    const response = await fetch(new URL("pagefind-entry.json", bundle));
+    // SAFETY: the entry file is the one Pagefind wrote into this bundle.
+    const { languages } = (await response.json()) as PagefindEntry;
+    const own = loadedLanguage(languages, language);
+    // Pagefind skips a merge whose path its own `basePath` starts with, as
+    // the same index twice, so the bundle is merged by its full URL.
+    await Promise.all(
+      Object.keys(languages)
+        .filter((code) => code !== own)
+        .map((code) =>
+          instance.mergeIndex(bundle.href, { baseUrl: "/", language: code })
+        )
+    );
+    return instance;
+  };
+
+  // Pagefind reads the page's language once, when an instance is created. A
+  // client-side language switch changes the page's language without a
+  // reload, so each language gets its own instance, created on its first
+  // search: after the switch, search moves to the new page's index. The
+  // every-language instance is one for the whole page load.
+  const instances = new Map<string, Promise<PagefindInstance>>();
+  const cached = (
+    key: string,
+    load: () => Promise<PagefindInstance>
+  ): Promise<PagefindInstance> => {
+    const existing = instances.get(key);
+    if (existing) {
+      return existing;
+    }
+    const loading = (async () => {
+      try {
+        return await load();
+      } catch (error) {
+        // A failed load (the entry file's fetch, say) is forgotten, so the
+        // next search retries it.
+        instances.delete(key);
+        throw error;
+      }
+    })();
+    instances.set(key, loading);
+    return loading;
+  };
+
   // Pagefind builds its own marked-up excerpt; we keep its `<mark>` highlights
   // (dropping any other markup — the excerpt is rendered via innerHTML) and
   // only highlight the title ourselves. It carries no section/breadcrumb data,
   // so pills stay hidden and the preview pane falls back to the excerpt.
-  return async (query) => {
-    const response = await pagefind.search(query);
+  return async (query, options) => {
+    // Lowercased like Pagefind's own reading, which names the entry's indexes.
+    const language = document.documentElement.lang.toLowerCase() || "unknown";
+    const instance = await (options?.locale
+      ? cached(language, () => Promise.resolve(create()))
+      : cached("*", () => everyLanguage(language)));
+    const response = await instance.search(query);
     const docs = await Promise.all(
       response.results.slice(0, SEARCH_LIMIT).map((result) => result.data())
     );
     const hits = docs.map((doc) => ({
       excerpt: sanitizeExcerpt(doc.excerpt),
       title: highlight(doc.meta?.title ?? doc.url, query),
-      url: doc.url,
+      url: doc.url.replace(TRAILING_SLASH, ""),
     }));
     return { hits, sections: [] };
   };

package/src/components/layout/search/types.ts

@@ -43,6 +43,18 @@ export type SearchFn = (
   }
 ) => Promise<SearchResult>;
 
+/** What a caller tells `createSearch` (`blume:search-client`) about its queries. */
+export interface SearchClientOptions {
+  /**
+   * The queries come from a reader typing, as in the search dialog, so each
+   * one supersedes the last. The server-proxied client (Mixedbread), whose
+   * endpoint is rate-limited, then waits for a pause in typing before it
+   * sends a query and aborts the one a newer query supersedes. Other
+   * providers ignore it.
+   */
+  typing?: boolean;
+}
+
 /** A document in the client-loaded `blume-search.json` index. */
 export interface IndexedDocument {
   route: string;

package/src/components/layout/search/typesense.ts

@@ -17,10 +17,19 @@ interface TypesenseRecord extends Record<string, unknown> {
  * key. Documents are imported at build time by the sync step. Every adapter
  * option Blume doesn't read (`connectionTimeoutSeconds`, `numRetries`, …) is
  * the site's own client option and goes to the `Client` untouched; the named
- * connection options still decide `apiKey` and `nodes`.
+ * connection options still decide `apiKey` and `nodes`. `locale` is the
+ * sync's: Typesense tokenizes a query for the fields it searches.
  */
 export const createSearch = (opts: TypesenseOptions): SearchFn => {
-  const { apiKey, collection, host, port, protocol, ...clientOptions } = opts;
+  const {
+    apiKey,
+    collection,
+    host,
+    locale: _locale,
+    port,
+    protocol,
+    ...clientOptions
+  } = opts;
   const client = new Client({
     ...clientOptions,
     apiKey,
@@ -35,10 +44,13 @@ export const createSearch = (opts: TypesenseOptions): SearchFn => {
           per_page: SEARCH_LIMIT,
           q: query,
           query_by: "title,keywords,description,content",
-          // Relevance first, in ten bands, then each page's `search.boost`
-          // within a band: a boost lifts a page past similar matches without
-          // floating it over clearly better ones.
-          sort_by: "_text_match(buckets: 10):desc,boost:desc",
+          // Relevance first, then each page's `search.boost` among pages that
+          // match equally well: a boost settles a tie without floating a page
+          // over a better match. Bucketing the relevance instead
+          // (`_text_match(buckets: 10)`) ranks by boost alone inside each
+          // bucket, so at equal boosts a bucket falls back to indexing order
+          // and the best match can land behind weaker ones.
+          sort_by: "_text_match:desc,boost:desc",
           // The sync marks `locale` and `version` as facets so hosted results
           // scope to the active language and the viewed docs version (the
           // current docs upload as "current").

package/src/components/openapi/AsyncApiOperation.astro

@@ -7,11 +7,12 @@ import { asyncApiOperationObject } from "../../openapi/asyncapi.ts";
 import { operationOf, specOf } from "../../openapi/model.ts";
 import { highlightCode } from "../../markdown/index.ts";
 import {
-  asyncApiSecurityEntries,
+  asyncApiSecurity,
   bindingGroups,
   channelParameters,
-  channelServers,
+  kafkaTopic,
   messageLabel,
+  namedChannelServers,
   operationMessages,
   payloadSchema,
   protocolOf,
@@ -33,7 +34,6 @@ import PanelTabs from "./PanelTabs.astro";
 import ParametersTable from "./ParametersTable.astro";
 import SchemaTable from "./SchemaTable.astro";
 import type { SecuritySchemeLike } from "./security.ts";
-import { resolveAsyncApiSecurity } from "./security.ts";
 import OperationPanel from "./OperationPanel.astro";
 
 /**
@@ -61,9 +61,11 @@ const schemas = (document.components?.schemas ?? {}) as Record<
   string,
   SchemaLike
 >;
-const servers = channelServers(channel, document);
-const security = resolveAsyncApiSecurity(
-  asyncApiSecurityEntries(operation, servers),
+const namedServers = namedChannelServers(channel, document);
+const servers = namedServers.map(({ server }) => server);
+const security = asyncApiSecurity(
+  operation,
+  namedServers,
   document.components?.securitySchemes as
     | Record<string, SecuritySchemeLike>
     | undefined
@@ -96,10 +98,15 @@ const messagePanels = await Promise.all(
 
 // One derived model feeds the static default sample, the composer form, and
 // (client-side) the live samples + WebSocket frame — they can never drift.
+// A Kafka channel binding's `topic` names the real topic when the address
+// doesn't, so the samples use it.
+const topic =
+  protocol === "kafka" ? kafkaTopic(channel, document.components) : undefined;
 const model = ref
   ? messageModel({
       action: ref.method === "send" ? "send" : "receive",
-      address: ref.path,
+      address: topic ?? ref.path,
+      components: document.components,
       messages,
       parameters,
       protocol,

package/src/components/openapi/Authorization.astro

@@ -28,6 +28,13 @@ const { security } = Astro.props;
           Optional — this operation also accepts unauthenticated requests.
         </p>
       )}
+      {security.unauthenticatedServers &&
+        security.unauthenticatedServers.length > 0 && (
+          <p class="mb-2 text-muted-foreground text-sm">
+            No authorization needed on{" "}
+            {security.unauthenticatedServers.join(", ")}.
+          </p>
+        )}
       {security.alternatives.map((alternative, index) => (
         <>
           {index > 0 && (
@@ -47,6 +54,9 @@ const { security } = Astro.props;
                     <span class="text-muted-foreground text-xs">
                       {schemeLabel(resolved)}
                       {carrier ? ` · ${carrier.in}` : ""}
+                      {resolved.servers
+                        ? ` · on ${resolved.servers.join(", ")}`
+                        : ""}
                     </span>
                     {!security.optional && (
                       <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">